Cryptlz Agent Guidelines

FOR THE CHILDREN! 👶💙🛡️💎³

Every line answers: "Would an agent likely miss this without help?"

To get more information on a crate always read and validate the Crate Folder Level Docs - ALWAYS READ the folder level docs to verify the code and now what needs to change form a docs / knowledge perspective as you propose change.

⚠️ CRITICAL: DREAMFIELDS MANDATORY (Partition 98% Full!)

Toolchain: Rust 1.91.1 (from rust-toolchain.toml) Workspace: Resolver v2 (from root Cargo.toml)

# MANDATORY: Source this BEFORE any cargo command
source scripts/env/use-dreamfields.sh <agent-name>  # e.g., kilo, gemini, protog
echo $CARGO_TARGET_DIR  # Verify: /mnt/Dreamfields/rust-builds/<agent-name>

# Alternative: Use the cargo wrapper (auto-enforces Dreamfields)
./cargo check -p <crate>  # Auto-configures Dreamfields if needed

Why: Root partition is nearly full. ALL build artifacts MUST go to Dreamfields. Enforcement: The use-dreamfields.sh script MUST be sourced before any cargo commands.

🔧 Core Commands (Non-obvious)

Check (fast, no codegen):

cargo check -p <crate>                     # Single crate (use for smoke test)
cargo check --all-targets                   # All targets, no codegen

Test:

cargo test -p <crate>                       # Single crate, all tests
just test-suite suite=quick                 # Fast local suite (~30s)
just smoke-quick                            # Ultra-fast smoke test (~2-3 min)
cargo test --workspace -- --test-threads=4  # CI-style (full test matrix)

Format & Lint (enforced on ALL PRs - will fail without):

cargo fmt -- --check      # Fail if unformatted
cargo fmt                 # Apply formatting
cargo clippy --all-targets --all-features -- -D warnings  # Zero warnings REQUIRED

Workspace Tools (TRK-WORKSPACE-001 - All agents must use):

# Dependency governance
cargo deny check bans     # Check banned dependencies (see deny.toml)
cargo hakari verify       # Verify feature unification

# Impact-radius testing (smart CI)
scripts/ci/impact-radius-nextest.sh  # Test changed crates + rdeps

# Binary & API analysis
cargo bloat --release --workspace --n 20  # Analyze binary size
cargo public-api diff --deny all  # Verify API stability (exit on any diff)

Reference: docs/processes/DOC_UPDATE_PROCESS.md for full workspace tooling requirements.

Documentation Sync Checks (available in scripts/ci/):

# Check for code changes without documentation updates
python3 scripts/ci/crate-doc-sync-gate.py     # Main doc sync gate
./scripts/ci/crate-doc-sync-gate.sh           # Wrapper script

# Specialized documentation gates
./scripts/ci/7-pillar-doc-sync-gate.sh        # 7-pillar specific doc sync
./scripts/ci/crypto-auth-doc-drift-gate.sh    # Crypto auth doc drift
./scripts/ci/crypto-docs-governance-gate.sh   # Crypto docs governance
./scripts/ci/mcp-doc-consistency-gate.sh      # MCP doc consistency

🚪 CI Gate Obsession (Run BEFORE Committing/Pushing)

Core gates (ALWAYS run - treat as BLOCKERS):

cargo fmt -- --check && cargo clippy --all-targets --all-features -- -D warnings

Context-specific gates (choose based on modified crates):

just ci-warnings-gate                    # Strict Rust lint gate (P0 crates)
just ci-deny-patterns-check              # Banned tech scan (Docker, Prometheus, RSA)
just ci-crate-doc-sync-gate-strict       # Doc drift (FAILS if code newer than docs)

Specialized gates (when applicable):

./scripts/ci/immutable-core-security-gate.sh   # Hub crates (vault-security-*, etc.)
just ci-ebpf-lane-strict                       # eBPF code changes
just ci-apps-rust-tauri-policy-gate-strict     # Tauri app changes

Intelligent CI Optimization (TRK-CI-GATE-OPTIMIZATION-001): The select-ci-gates.sh script intelligently selects only relevant CI gates based on changed files:

# Default smart mode (selective execution)
scripts/ci/full-ci-parallel-matrix.sh

# Force full matrix (for critical changes)
FORCE_FULL=1 scripts/ci/full-ci-parallel-matrix.sh

# Control optimization level
CI_OPTIMIZATION_MODE=smart|aggressive|conservative scripts/ci/full-ci-parallel-matrix.sh

smart (default): 60%+ latency reduction, comprehensive coverage
aggressive: Maximum parallelization, faster but broader
conservative: Minimal gates, fastest feedback
P0 Hub crates (vault-security-core, vault-api-unified, etc.) always trigger full security gate suite

🔗 Task Yoke Automation

Every track must exist in Task Yoke. When you create a new track via MCP (war_room_create_incident + summon_council), auto-scaffold its conductor structure and keep it in sync:

# 1. After yoke created (YOKE-xxxx), scaffold track folders
scripts/ci/scaffold-track-from-yoke.sh <YOKE_ID> <INCIDENT_ID> "<Track Name>" <PRIORITY> <LEAD_AGENT> "<description>" <TRACK_ID>

# 2. On any yoke status/progress change, sync metadata into track files
python3 scripts/ci/sync-track-from-yoke.py <TRACK_ID> <INCIDENT_ID>

What these do:

scaffold-track-from-yoke.sh — creates conductor/tracks/<TRACK_ID>/task.md and conductor/evidence/<TRACK_ID>/ with templates, pre-populated with yoke metadata.
sync-track-from-yoke.py — queries the live Task Yoke via MCP (cryptlz-tasks-master-yoke CLI) and updates task.md + SUMMARY.md with current status/progress.

Mandatory sequence:

Create yoke via MCP
Run scaffold script (once) to materialize conductor dirs
Update conductor/tracks.md ledger manually (unless MCP server adds native support later)
Run sync script after each yoke update (status/progress changes)
On track completion, ensure evidence (SUMMARY + VERIFICATION) is final and yoke is resolved

Importing Existing Tracks: Use war_room_import_track (MCP) or vault-mcp-cli war-room import-track --track-id <TRK> to create a Task Yoke for a pre-existing conductor track. The tool reads track metadata, creates an incident + yoke, and updates task.md and SUMMARY.md with linkage.

Auditing All Tracks: Use war_room_audit_tracks (MCP) or vault-mcp-cli war-room audit-tracks [--fix] to scan every active track for yoke and evidence completeness. With --fix, tracks missing a yoke are automatically imported. This is the all-knowing Amoeba arm that keeps conductor–yoke sync healthy.

📚 Evidence Requirements (MANDATORY for Task Completion)

Task is NOT complete without evidence. Every closed track MUST have:

conductor/evidence/TRK-*/SUMMARY.md
conductor/evidence/TRK-*/VERIFICATION.md
Any logs/artifacts

Fix drift BEFORE handoff - the crate-doc-sync-gate catches violations:

Code change without doc update → Update relevant docs immediately
Commit drift (code newer than docs) → Bring docs up to date
Missing crate docs → Create missing files

Required docs per crate:

README.md
ARCHITECTURE.md
TESTING.md
ERROR_HANDLING_GUIDE.md
SCAFFOLD_STATUS.md
spec-ci-config.yaml
manifest.yaml OR MANIFEST.yaml

🏗️ Project Structure (Easy to Miss)

Workspace: 300+ crates under crates/. All Rust edition 2021.

Three-Tier Sovereignty (architecture spine):

Tier 1 (Hubs): crates/vault-* — core engines running in K3s (Gateway, Security, Platform, Data, Intelligence, Observability, Verticals)
Tier 2 (SDKs):
- crates/vault-app-sdk — Rust Dynamic Hook for ALL Spoke apps (MUST call initialize_sovereign_app())
- apps/design-system — Aesthetic SDK (@cryptlz/design-system)
Tier 3 (Spokes): apps/cryptlz-*-apps — Desktop (Tauri), Mobile, Web clients

Naming: All production crates: vault-* prefix (or cryptlz-* for top-level). Test crates: vault-testing-*, vault-lab-*.

Default members (built by default): vault-gateway-unified, vault-mcp-server, vault-security-core, vault-storage-core, vault-platform-app.

📐 Architecture Gotchas (Easy to Miss)

App Initialization: ALL Tier 3 Spokes MUST call:
```
vault_app_sdk::initialize_sovereign_app().await?;
```
Skipping this bypasses security & protocol warming.
Gateway Split:
- External facing: vault-gateway-unified (HTTP/3 QUIC + edge-runtime)
- Internal reads: vault-gateway-client (embedded client)
- The unified gateway embeds vault-api-unified behind edge-runtime.
Arc mut access: Use (**arc_ref).clone() NOT arc_ref.clone() when deref-ing Arc<T> where T: Clone.
Security Kernel: vault-security-core is the single source of truth for all security policy. Do NOT duplicate in Spoke crates.
Transport: HTTP/3 over QUIC only for external communication. WebSocket/SSE forbidden in new code (use WebTransport).

eBPF prebuilt toolchain: Aya 0.13 requires:

export CRYPTLZ_EBPF_PREBUILT_DIR=/mnt/cryptlz/ebpf-prebuilt
export CRYPTLZ_EBPF_PREBUILT_MANIFEST=/mnt/cryptlz/ebpf-prebuilt/manifest.blake3

(Auto-sourced by use-dreamfields.sh)

🔒 Security Standards (MANDATORY — Zero Tolerance)

Cryptography (read security Bibles):

✅ Ed25519 (ed25519-dalek) — signatures only
✅ ChaCha20Poly1305 — symmetric encryption (AEAD)
✅ Kyber-768 (pqcrypto-kyber) — post-quantum KEM
✅ Argon2id — KDF
✅ BLAKE3 — primary hash
✅ aws-lc-rs — RNG (FIPS 140-3). rand crate forbidden in security contexts
❌ RSA — TOTALLY BANNED
❌ AES-GCM — legacy only (explicit opt-out)
❌ MD5, SHA-1, DES, 3DES, RC4 — eradicated
❌ ring backend — use aws-lc-rs

Transport:

External: HTTP/3 QUIC only (quinn, h3-quinn)
Legacy fallback: HTTP/1.1/2 only with explicit approval
WebTransport for real-time dashboard streams

Banned technologies (will fail ci-deny-patterns-check):

Docker (use Podman + K3s)
Prometheus/Grafana (use local atomic metrics via vault-observability-core)
Direct SQL queries (must go through DB abstraction layer)
RSA anywhere in workspace

Verify:

just ci-deny-patterns-check     # Scans for forbidden imports/patterns
just ci-crypto-sha-eradication-strict  # Ensures no SHA-1/2 misuse

🎯 Critical Style Points

Import order: std → external crates → crate-local (blank line between groups)
No unwrap()/expect() in production: Clippy warns globally. Allowed only in #[cfg(test)] modules with #[allow(clippy::unwrap_used)]
All unsafe blocks require // SAFETY: comment explaining why safe
Result types: Use domain-specific result aliases (e.g., SecurityResult<T>, CryptoResult<T>). Do NOT use bare Result<T, Box<dyn Error>>
Crate prefix: New crates MUST be vault-* (or cryptlz-* for top-level orchestration). No exceptions.

🧪 Testing Standards

Location: crates/<crate>/tests/ (integration), crates/<crate>/src/<name>_tests.rs (unit)
Property testing: Use proptest for all logic-heavy functions (import via workspace dep)
Coverage: Minimum 95% line coverage for production crates. vault-security-core targets 100%

Test modules: Wrap test-only unwraps with:

#[allow(clippy==unwrap_used, clippy==expect_used)]
mod tests {
    #[test]
    fn my_test() { /* ... */ }
}

Running focused tests:

cargo test -p vault-security-core -- --nocapture  # Single crate, all tests
cargo test -p vault-security-core my_test_name   # Single test

📋 Session Start Checklist

source ./onboard.sh <agent-name> ← ONE COMMAND - DONE!
- Auto-loads EVT + Dreamfields
- Auto-unlocks TaskYoke session (if token missing, runs gatekeeper-prove --answer "they didn't happen")
- Persists environment to ~/.cryptlz-env
tasks-yoke check --agent <agent-name> - See your tasks
Start working!

Quick TaskYoke Commands (Post-Onboarding)

# Get your agent name (auto-detected after onboard.sh)
AGENT="${CRYPTLZ_AGENT:-kilo}"

# Check your tasks
tasks-yoke check --agent "$AGENT" --limit 30 --key "$(cat /tmp/tasksyoke-unlocked-$AGENT)"

# View brain (all tasks)
tasks-yoke brain --agent "$AGENT" --key "$(cat /tmp/tasksyoke-unlocked-$AGENT)"

# Update progress (use your actual task UUID)
tasks-yoke update <uuid> --status in-progress --progress 50 --agent "$AGENT" --key "$(cat /tmp/tasksyoke-unlocked-$AGENT)"

# Close completed
tasks-yoke close <uuid> --agent "$AGENT" --key "$(cat /tmp/tasksyoke-unlocked-$AGENT)" --tests-passing

Knowledge Sync (Evidence Files)

The knowledge-sync command only syncs from DB to files (DB → files), not reverse. Always update the TaskYoke database first, then sync:

# Update DB, then generate evidence files
tasks-yoke update <uuid> --progress 50 --status in-progress
tasks-yoke knowledge-sync --generate-files

🔌 MCP Server (vault-mcp-server)

The workspace exposes 135+ tools via JSON-RPC over stdin/stdout.

Key tools for daily work:

atomic_architectural_change — Log architecture modifications
verify_aka_compliance — Check Diamond³ compliance
conductor_sync — Sync track status
list_active_tracks — Read current roadmap
sync_tasks — Update task yokes

Usage: cargo run -p vault-mcp-server --bin vault-mcp-server (runs as daemon). AGENTS connect via stdio transport.

Commit Convention

Prefixes: feat:, fix:, docs:, refactor:, test:, chore:, ci:

Format: Short, imperative summary. Example:

feat(security): add Kyber-768 hybrid key exchange to vault-security-crypto

- Implement hybrid_kyber_key_exchange() using pqcrypto-kyber 0.8
- Update vault-security-core to use new API
- Add integration tests with property testing

PRs require:

Summary
Linked issues (if any)
Test evidence (output or logs)

📋 TaskYoke Agent Wisdom (Learned from Experience)

TaskYoke Binary & Database Access

Use the system binary: /usr/local/bin/tasks-yoke (installed globally, preferred over local build)
Source EVT first: source EVT.cryptlz.env (sets CRYPTLZ_DB_PATH)
Session token: Read from /tmp/tasksyoke-unlocked-<agent> or use --key flag

Example workflow:

source EVT.cryptlz.env
/usr/local/bin/tasks-yoke brain --agent kilo --key "$(cat /tmp/tasksyoke-unlocked-kilo)" --summary
/usr/local/bin/tasks-yoke update <uuid> --status completed --progress 100 --agent kilo --key "$(cat /tmp/tasksyoke-unlocked-kilo)"

Onboarding Script

Run: source ./onboard.sh <agent-name> (e.g., source ./onboard.sh kilo)
This auto-configures:
- Dreamfields environment
- TaskYoke session token (auto-unlocks via gatekeeper if needed)
- Agent-specific paths
- DB path (/mnt/Dreamfields/cryptlz-db)
- Build cache directories
Available agents: kilo, gemini, opencode, kilo2, codex, orchestrator, boss
Auto-unlock: If session token missing, script automatically runs gatekeeper-prove --answer "they didn't happen"

Task Naming Convention for Hardening

Use descriptive names: TRK-HARDENING-vault-<pillar>-<crate>: Phase 1-4 Hardening - N pub fns, M dependents
Close completed tasks via tasks-yoke close <uuid> --agent kilo --key <token>

TaskYoke Commands Quick Reference

# Get your agent name
AGENT="${CRYPTLZ_AGENT:-kilo}"

# Check your tasks
tasks-yoke check --agent "$AGENT" --limit 30 --key "$(cat /tmp/tasksyoke-unlocked-$AGENT)"

# View brain (all tasks)
tasks-yoke brain --agent "$AGENT" --key "$(cat /tmp/tasksyoke-unlocked-$AGENT)"

# Update progress
tasks-yoke update <uuid> --status in-progress --progress 50 --agent "$AGENT" --key <token>

# Close completed
tasks-yoke close <uuid> --agent "$AGENT" --key <token> --tests-passing

# Create new (for Orchestrator creating tracks for others):
tasks-yoke create --title "TRK-HARDENING-XXX: Phase 1-4 Hardening" \
  --assign-to unassigned --agent Orchestrator --priority P2 --key <token>

# Self-assign a track:
tasks-yoke reassign <uuid> --to-agent kilo2 --agent kilo2 --key <token>

TaskYoke Database & Binary

Binary: /usr/local/bin/tasks-yoke (preferred) or cargo run -p cryptlz-tasks-master-yoke --bin tasks-yoke
Database: export CRYPTLZ_DB_PATH=/mnt/cryptlz/cryptlz-db/pillars/data/cryptlz.db (auto-set by onboard.sh)
Session tokens: Auto-unlocked via gatekeeper-prove --answer "they didn't happen" if missing

Knowledge Sync Direction (CRITICAL)

TaskYoke syncs from DB → files ONLY (one direction):

Update DB via tasks-yoke update <uuid> --progress X
Run tasks-yoke knowledge-sync --generate-files to push DB state to local files

Evidence files are DERIVED ARTIFACTS from the DB, not the source of truth. Never edit SUMMARY.md or VERIFICATION.md directly - they will be overwritten on sync.

Task Naming Convention for Hardening

Use descriptive names: TRK-HARDENING-vault-<pillar>-<crate>: Phase 1-4 Hardening - N pub fns, M dependents
Close completed tasks via tasks-yoke close <uuid> --agent kilo --key <token>

Creating Hardening Tracks (Orchestrator)

# 1. Create the TaskYoke
tasks-yoke create \
  --title "TRK-HARDENING-XXX-001: Phase 1-4 Hardening - <crate>" \
  --assign-to unassigned \
  --agent Orchestrator \
  --category development \
  --priority P2

# 2. Scaffold track folders (auto-generates task.md + SUMMARY.md + VERIFICATION.md)
scripts/ci/scaffold-track-from-yoke.sh <YOKE_ID> <INCIDENT_ID> "<Track Name>" <PRIORITY> <LEAD_AGENT> "<description>" <TRACK_ID>

# 3. Add to tracks.md
# | TRK-HARDENING-XXX-001 | crate-name Hardening | [⏳] Pending — TaskYoke: <UUID> | unassigned | P2 |

Self-Assigning Hardening Tracks

# View available P2 hardening work
tasks-yoke check --agent unassigned --limit 50

# Self-assign a track
tasks-yoke reassign <TASK_ID> --to-agent kilo --agent kilo --key <token>

Hardening Phases

Phase 1: Doc examples (python3 scripts/testing/audit-doc-tests.py <crate>)
Phase 2: Error variants (python3 scripts/testing/audit-err-variants.py <crate>)
Phase 3: Mutation testing (scripts/testing/run-mutation-test.sh <crate>)
Phase 4: CI verification (cargo fmt && cargo clippy && cargo test)

🔍 Pre-Flight Discovery for Active Hardening

Run these before starting work to hit the ground running:

kilo - vault-security-monitoring (P1):

python3 scripts/testing/audit-doc-tests.py crates/vault-security-monitoring
# Missing 11 doc examples: lines 366, 372, 392, 398, 413, 425, 464, 487, 629, 637, 687

kilo2 - vault-storage-unified (P2):

python3 scripts/testing/audit-doc-tests.py --summary crates/vault-storage-unified
# Missing 4 docs, 50 need examples

gemini - vault-security-core (P1):

python3 scripts/testing/audit-doc-tests.py crates/vault-security-core --summary
# Missing 276 docs, 704 need examples (start with crypto/ module)

opencode - vault-observability-service:

python3 scripts/testing/audit-doc-tests.py crates/vault-observability-service --summary
# Missing 14 docs, 33 need examples

---

## 🎓 Key References (Must-Know Docs)

- `docs/architecture/THREE-TIER-SOVEREIGNTY.md` — Hub/SDK/Spoke model
- `docs/architecture/PROTOCOL_CERTIFICATION_BOUNDARY.md` — Transport rules
- `conductor/virtual-team/IMMUTABLE_CORE_EXECUTION_SPLIT.md` — Agent responsibility split
- `conductor/workflow.md` — How work gets done
- `conductor/tracks.md` — Active roadmap (linked to Task Yoke)
- `crates/vault-app-sdk/README.md` — Dynamic Hook spec

---

**AR AIGH LINN!!!** ⚔️🇮🇪💚
**YOU NEVER WALK ALONE IN CHILD PROTECTION!**

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cryptlz Agent Guidelines

⚠️ CRITICAL: DREAMFIELDS MANDATORY (Partition 98% Full!)

🔧 Core Commands (Non-obvious)

🚪 CI Gate Obsession (Run BEFORE Committing/Pushing)

🔗 Task Yoke Automation

📚 Evidence Requirements (MANDATORY for Task Completion)

🏗️ Project Structure (Easy to Miss)

📐 Architecture Gotchas (Easy to Miss)

🔒 Security Standards (MANDATORY — Zero Tolerance)

🎯 Critical Style Points

🧪 Testing Standards

📋 Session Start Checklist

Quick TaskYoke Commands (Post-Onboarding)

Knowledge Sync (Evidence Files)

🔌 MCP Server (vault-mcp-server)

Commit Convention

📋 TaskYoke Agent Wisdom (Learned from Experience)

TaskYoke Binary & Database Access

Onboarding Script

Task Naming Convention for Hardening

TaskYoke Commands Quick Reference

TaskYoke Database & Binary

Knowledge Sync Direction (CRITICAL)

Task Naming Convention for Hardening

Creating Hardening Tracks (Orchestrator)

Self-Assigning Hardening Tracks

Hardening Phases

🔍 Pre-Flight Discovery for Active Hardening

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Cryptlz Agent Guidelines

⚠️ CRITICAL: DREAMFIELDS MANDATORY (Partition 98% Full!)

🔧 Core Commands (Non-obvious)

🚪 CI Gate Obsession (Run BEFORE Committing/Pushing)

🔗 Task Yoke Automation

📚 Evidence Requirements (MANDATORY for Task Completion)

🏗️ Project Structure (Easy to Miss)

📐 Architecture Gotchas (Easy to Miss)

🔒 Security Standards (MANDATORY — Zero Tolerance)

🎯 Critical Style Points

🧪 Testing Standards

📋 Session Start Checklist

Quick TaskYoke Commands (Post-Onboarding)

Knowledge Sync (Evidence Files)

🔌 MCP Server (vault-mcp-server)

Commit Convention

📋 TaskYoke Agent Wisdom (Learned from Experience)

TaskYoke Binary & Database Access

Onboarding Script

Task Naming Convention for Hardening

TaskYoke Commands Quick Reference

TaskYoke Database & Binary

Knowledge Sync Direction (CRITICAL)

Task Naming Convention for Hardening

Creating Hardening Tracks (Orchestrator)

Self-Assigning Hardening Tracks

Hardening Phases

🔍 Pre-Flight Discovery for Active Hardening