🛡️ BSP Bulletproof-First Operator Manual

What bulletproof requires (from memory/feedback_bulletproof_default.md + CLAUDE.md Rule 9):

• Read first, build second (read existing docs/code before authoring)
• Test after each layer (Producer ≠ Verifier — CLAUDE.md Rule 1)
• Multi-layer defense over single-pass shortcut
• Retry-with-backoff on every API call
• Multi-model fallback chain on critical agents (Claude Opus → GPT-4o)
• Receipts not narration (CLAUDE.md Rule 2)
• ≤ 200 lines of code per turn (§11 self-limits)
• Pre-flight 6-question test (Apr 21 SOP + bulletproof check)
• Cleanup as you go (no diagnostic snippets / dead helpers / cruft)

Architectural enforcement — can't be bypassed accidentally

• Tier 2+ REFUSES Solo mode — --mode solo --tier 2 exits with code 2 + redirect message
• Bricks UI scope REJECTED at intake — Referee returns sys.exit 3 if dispatch is editor-click work
• Hallucinated IDs caught at audit — Auditor empirical-grep pre-LLM cross-check
• Validation Score gates surfacing — FAIL_HIGH dispatches surface as REJECTED, not as ready

Old way (broken)

New way

Each dispatch is tagged with a tier. Tier governs whether you have to approve it before execution.

Method 1: Just tell Claude Code in chat

Simplest. You say "I need a dispatch for X" → I author it → I save to disk → I show you for ship/hold.

Method 2: Direct command on the VM

Solo mode (cheap, fast)

Council mode (high-stakes)

Method 3: With Project Ledger context (recommended)

Council reads the live ledger → drift baselines + recent decisions + open items → produces a dispatch grounded in current state.

Method 4: Future — Streamlit cockpit on :8506

Phase 2 build. Single-pane-of-glass for review queue + ledger + audit trail. DEFERRED

Every dispatch is saved to /opt/nexus/nexus/scripts/output/dispatches/phase_<ts>_<slug>.md and logged to MH. You see the dispatch + the council reviews. Then:

Three responses you can give Claude Code

Refresh the project ledger (do this first thing each session)

Solo dispatch — tactical

Council dispatch — high-stakes

Read the most-recent dispatch

Pull the most-recent dispatch to Windows for review

How it works

What the agents now MUST do

1. Read the brief in full before authoring or reviewing.
2. Cite specific identifiers in every dispatch — exact file paths, snippet IDs (e.g. #115, #163, #167), element IDs (e.g. f5a4a5 section, aa1001 nav-nested, 3ba269 Call Now button), post IDs (105 header, 106 footer, 258 OP, 157 homepage), schema markup keys, child-theme add_action hooks with priorities.
3. Confirm which codebase sections were read (by section ID — the brief lists all 30 available IDs).
4. Cross-check against failure-modes never-do list — if proposed action is on the list (regex string-replace on production files, force-render Bricks templates without DOM relocation, etc.), REJECT or AMEND.
5. If brief doesn't cover a code path, name the section ID needed and proceed with explicit assumptions flagged.

How to use it (you don't have to do anything — it's automatic)

That single command now refreshes BOTH the ledger AND the codebase brief. Council picks up both automatically on the next dispatch.

Manual brief refresh (when codebase doc updates)

Disabling the brief (debugging / not recommended)

Use this only when debugging the runtime itself. Production dispatches must always have brief loaded.

Before your first dispatch, verify these 5 things. ~3 min total.

What to do every time you sit down to work on BSP. ~5 min from sit-down to first dispatch shipped.

If you want to run dispatches without Claude Code in the loop, here's how to compose the command yourself. ~60 sec.

What to actually look at when you read a dispatch markdown. ~2 min per dispatch.

When you say "ship X", here's what happens. So you know what to expect in the receipt.

Tier 0 — read-only / docs / MH log

No state change → no rollback needed. If MH log was wrong, edit the section directly:

Tier 1 — staging writes (functions.php / Bricks tree / snippets)

Backup is automatic. Every write writes a backup file at /tmp/<file>.bak_<ts> first.

functions.php rollback

Then re-deploy the backup via install-child:

Bricks tree rollback (Template 105 etc.)

Backup at /tmp/template_<id>_pre_<phase>.json. Re-POST to native-save:

Snippet rollback

Code Snippets plugin keeps revision history. Or delete the new snippet + recreate the old one from /tmp/snippets_backup_<ts>.json.

Tier 2 — production writes

Each dispatch must include its own rollback as a literal command. Tier 2 dispatches get extra: backup BEFORE write, sha256 readback AFTER write. Rollback = re-deploy backup + verify sha256 returns to pre-write hash.

Tier 3 — destructive / irreversible

Per definition: not rollback-able. Don't ship without signed receipt + Robert presence at execution.

Before you /clear, close the laptop, or hand off — 90 sec.

• All dispatches accounted for — every dispatch you ran today has a receipt + MH section. Run: ssh dovew@34.55.179.122 "ls -lt /opt/nexus/nexus/scripts/output/dispatches/ | head -10"
• No mid-flight aborts unresolved — if any step aborted, did you decide retry / amend / abandon? If still hanging, document state in MH before close.
• Final ledger snapshot — python3 /opt/nexus/nexus/scripts/project_ledger.py. Captures end-of-day state for tomorrow's session.
• End-of-session MH log — one bullet list per dispatch: shipped / amended / held / aborted. Future you needs this.
• Cache state clean — final LS + CF purge if anything live changed. curl -X POST /wp-json/bsp/v2/cache/purge + Cloudflare API.
• Open dispatches list updated — anything HOLD'd this session is in the queue for tomorrow.

Sometimes the council produces a dispatch that's technically correct but misses the point. Here's how to course-correct.

The bulletproof default rule says: build the recovery story BEFORE you need it. If the council breaks, follow these in order.

Symptom 1: Anthropic API 529 / overloaded

Already handled automatically. _retry_post() retries 3x with 5s/15s/30s backoff. If still failing, call_strategist_with_fallback() falls back to GPT-4o. No action needed.

Symptom 2: Gemini Auditor returns empty

Already handled — call_gemini() Pro→Flash fallback fires automatically. If both fail, Auditor returns error message + Critic+Researcher reviews still surface.

Symptom 3: Zeus RAG endpoint (port 8765) down

Council degrades gracefully — RAG block notes "service unavailable" + dispatch authors with Protocol Gates + Project Ledger only. Validate Zeus is healthy:

Restart if needed:

Symptom 4: Validation Score returns FAIL_HIGH on a dispatch you expected PASS

This is the system catching a hallucination correctly. Read the FAIL_HIGH detail in the dispatch surface. Common causes:

• robert@ or /var/www/ in dispatch — re-run, Strategist will likely correct on retry
• Strategist truncated — bump max_tokens or split question into 2 dispatches
• Empirical audit found fake IDs — Strategist hallucinated, re-run with tighter prompt

Symptom 5: A council component (referee.py / auditor_tools.py / validation_score.py) imports broken

All components are independent try/except imports. If one breaks, others still work. council_runtime.py sets *_AVAILABLE = False on import failure and skips that layer with a warning.

Symptom 6: Need to bypass a defense layer for debugging

Override flags (use only when debugging council itself, NOT for production dispatches):

None of these flags affect Validation Score — that always runs. To bypass Validation Score (NOT recommended), edit council_runtime.py to set VALIDATION_AVAILABLE = False.

Symptom 7: council_runtime.py itself has a syntax error / can't run

Locked baseline + git history fallback:

Or rebuild from the canonical reference in MH section bsp-apr26-bulletproof-council-v2-architecture-shipped — that section lists every file and its size. Zeus RAG retrieves it on demand.

Symptom 8: Production cutover Friday goes sideways

The cutover dispatch authored under bulletproof v2 has its own ABORT gates per step + literal rollback command. See: most recent fri-cutover-final dispatch in /opt/nexus/nexus/scripts/output/dispatches/. The dispatch itself is the recovery doc.

Last resort: full recovery from MH paper trail

Every council dispatch is logged to MH. Every architectural decision is logged to MH. Zeus RAG indexes MH. To recover the entire council from scratch:

1. SSH to VM: ssh dovew@34.55.179.122
2. Read MH section bsp-apr26-bulletproof-council-v2-architecture-shipped — full file list + sizes + receipts
3. Read MH section bsp-apr25-bulletproof-default-rule-9 — Rule 9 codification
4. Reconstruct files from git log + BSP_Bulletproof_Council_Architecture_v2.html

• Streamlit cockpit on :8506 — single-pane-of-glass for review queue + ledger + audit
• systemd integration — council runs as a service, not invocation-based
• Cron loop — daily drift check, ledger refresh, end-of-day MH snapshot
• Self-improvement loop — every incident auto-generates a rule update + council prompt patch
• Cross-project generalization — same harness for HCP, Daniel, ST attribution