multi-forge 0.2.0__py3-none-any.whl

forge/_extensions/skills/qa/resources/checklist/14-workflow.md

@@ -0,0 +1,305 @@
+<!-- prereq: 0.3, 2.1, 4.2 -->
+
+## 14. Multi-Model Review (`forge workflow`)
+
+Validates workflow runners + skill architecture.
+
+- `forge workflow panel` is the fan-out runner CLI (supports `--code`, `--context`, and `--check`).
+- `/forge:analyze` is a skill that calls `forge workflow analyze` (N=1 model).
+- `/forge:debate` is a skill that calls `forge workflow debate` (supports `--code` for code evaluation).
+- This section uses `$FORGE_QA_WORKFLOW_MODELS` (set by `start-container.sh` per provider profile). Workflow proxy
+  aliases are created in 4.2.
+- Omitting `--models` uses all configured defaults (from `forge workflow list-models`).
+- Workflow workers require `claude` on PATH in the environment running `forge workflow`; proxies choose model routing,
+  but workers still execute through local `claude -p`.
+
+### 14.1 List Available Workflow Models
+
+<!-- auto -->
+
+```bash
+forge workflow list-models
+forge workflow list-models --json
+forge workflow list-models --available
+
+# Verify structured model metadata used by routing/preflight.
+forge workflow list-models --json \
+  | jq -e 'map(has("name") and has("model_id") and has("family") and has("provider_refs") and has("preferred_proxy") and has("status") and has("reason")) | all'
+
+# `--available` JSON should include only ready models.
+forge workflow list-models --available --json \
+  | jq -e 'all(.status == "ready")'
+```
+
+- [ ] Groups models by primary credential and shows `[configured]` / `[not configured]`
+- [ ] Shows model name, description, and status (`ready`/`unavailable`/`error`)
+- [ ] `--json` outputs a structured JSON array with `name`, `model_id`, `family`, `provider_refs`, `preferred_proxy`,
+  `status`, and `reason`
+- [ ] `--available` filters to ready models only
+
+### 14.2 `forge workflow panel`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+forge workflow panel docs/ --models $FORGE_QA_WORKFLOW_MODELS --json
+```
+
+- [ ] Returns structured JSON output
+- [ ] JSON includes `resolved_models` with actual model refs and proxy/template routing for each worker
+- [ ] `--context blind` is the default (no --resume passed to workers)
+
+### 14.3 `forge workflow panel --check`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+# Policy gate mode (structured verdict + exit code)
+forge workflow panel -p "Check for security issues" --models $FORGE_QA_WORKFLOW_MODELS --check
+echo "Exit code: $?"
+```
+
+- [ ] Returns structured JSON verdict
+- [ ] Exit code 0 = pass, 1 = findings
+
+### 14.4 `forge workflow panel --code`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+# Multi-model code review (uses bundled codereview resource)
+forge workflow panel src/ --code --models $FORGE_QA_WORKFLOW_MODELS --json
+
+# With --check mode
+forge workflow panel src/ --code --models $FORGE_QA_WORKFLOW_MODELS --check
+echo "Exit code: $?"
+```
+
+- [ ] Spawns multiple workers with codereview resource prompt
+- [ ] Returns structured JSON output per worker
+- [ ] `--check` mode: fail-closed -- every worker must succeed AND emit parseable verdict
+
+### 14.5 `forge workflow analyze`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+# Single-model deep analysis (N=1 fan-out with bundled thinkdeep resource)
+forge workflow analyze -p "Analyze the architecture of this project" --models $FORGE_QA_WORKFLOW_MODEL_A --json
+
+# With --check mode (exit 0=pass, 1=findings)
+forge workflow analyze -p "Check for security issues" --models $FORGE_QA_WORKFLOW_MODEL_A --check
+echo "Exit code: $?"
+```
+
+- [ ] Spawns single worker with analysis resource prompt
+- [ ] Returns structured JSON output
+- [ ] JSON includes `resolved_models` with actual model ref and proxy/template routing for the worker
+- [ ] `--check` mode returns exit code 0/1 with verdict
+
+### 14.6 `forge workflow debate`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+# Adversarial debate with positional proposal
+forge workflow debate "Should we rewrite the core in Rust?" --models $FORGE_QA_WORKFLOW_MODELS --json
+
+# Gate mode (exit 0=pass, 1=fail). Debate is fail-closed: success without a parseable verdict = failure.
+forge workflow debate "Should we adopt microservices?" --models $FORGE_QA_WORKFLOW_MODELS --check
+```
+
+- [ ] Spawns workers with stance injection (for/against/neutral)
+- [ ] Mandatory blinding (workers don't see each other's output)
+- [ ] JSON includes `resolved_models` with actual model refs and proxy/template routing for each worker
+- [ ] Returns structured output with agreement/disagreement areas
+
+### 14.7 `forge workflow debate --code`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+# Adversarial code evaluation (uses bundled code evaluation resource)
+forge workflow debate src/ --code --models $FORGE_QA_WORKFLOW_MODELS --json
+
+# With --check mode
+forge workflow debate src/ --code --models $FORGE_QA_WORKFLOW_MODELS --check
+echo "Exit code: $?"
+```
+
+- [ ] Spawns workers with code evaluation resource + stance injection
+- [ ] Returns structured JSON output with code-specific findings per worker
+- [ ] `--check` mode: fail-closed -- every worker must succeed AND emit parseable verdict
+
+### 14.8 `forge workflow consensus`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+# Two-round consensus with role-assigned workers (proposal mode)
+forge workflow consensus "Should we adopt a microservices architecture?" --models $FORGE_QA_WORKFLOW_MODELS --json
+
+# Gate mode (requires 'position' field, not 'verdict')
+forge workflow consensus "Should we adopt event sourcing?" --models $FORGE_QA_WORKFLOW_MODELS --check
+echo "Exit code: $?"
+```
+
+- [ ] Spawns workers with role injection (architecture/security/correctness)
+- [ ] Two rounds: independent positions then reconciliation
+- [ ] Mandatory blinding both rounds (no --resume passed to workers)
+- [ ] JSON includes `round1`, `round2`, `roles`, `role_map`, `reconciliation_brief`
+- [ ] JSON includes `resolved_models` with actual model refs and proxy/template routing for each worker
+- [ ] `--check` mode: requires `position` field (rejects legacy `passed`/`verdict`)
+
+### 14.9 `forge workflow consensus --code`
+
+<!-- prereq: 14.1 -->
+
+<!-- auto -->
+
+```bash
+# Two-round code consensus (code mode uses architecture/security/maintainability)
+forge workflow consensus src/ --code --models $FORGE_QA_WORKFLOW_MODELS --json
+
+# With --check mode
+forge workflow consensus src/ --code --models $FORGE_QA_WORKFLOW_MODELS --check
+echo "Exit code: $?"
+```
+
+- [ ] Spawns workers with code-mode role cycle (architecture/security/maintainability)
+- [ ] Returns structured JSON output with code-specific findings per worker per round
+- [ ] `--check` mode: schema-strict -- only SUPPORT/SUPPORT_WITH_CONDITIONS pass
+
+### 14.10 `/forge:debate` (Live Session)
+
+<!-- prereq: 14.1 -->
+
+<!-- human:guided -->
+
+<!-- requires: api_key -->
+
+Validate the real Claude-facing `/forge:debate` path, not a terminal fallback. This step passes only if Claude Code
+accepts the slash command and actually executes the adversarial runner end to end.
+
+If Session B is not already open, start Claude Code in the container shell first:
+
+```
+cd $FORGE_TEST_REPO
+claude
+```
+
+Read `$FORGE_QA_WORKFLOW_MODELS` from the container environment and construct the fully expanded command for the user to
+type in Session B:
+
+```
+/forge:debate --models <expanded FORGE_QA_WORKFLOW_MODELS> A startup with 5 developers has a working Python monolith serving 10k req/sec. They're hitting scaling issues. Should they rewrite the core in Rust?
+```
+
+Wait for Claude to finish. Do not replace this with `forge workflow debate` in the shell; that CLI surface is already
+covered by `14.6`. If Claude only says `Command completed`, echoes the skill instructions back, or asks you to run the
+commands manually, treat this step as a failure. If the command reports `claude CLI not found in PATH`, the slash
+command was accepted but the nested workflow worker runtime is missing from Claude Code's Bash environment.
+
+- [ ] Slash command accepted in Claude Code (no unknown-skill or parsing error)
+- [ ] Claude executes the skill itself (not just instruction injection / "Command completed")
+- [ ] No workflow preflight error about `claude` missing from PATH
+- [ ] Workers spawned with different stances (for/against/neutral)
+- [ ] Synthesis produced with points of agreement AND disagreement
+- [ ] Different perspectives visible in the final response
+
+### 14.11 Workflow `--models` Filter
+
+<!-- prereq: 14.1 -->
+
+<!-- requires: api_key -->
+
+<!-- auto -->
+
+```bash
+# Single model filter -- should limit to that model only
+forge workflow panel docs/ --models $FORGE_QA_WORKFLOW_MODEL_B --json 2>&1 | jq '.results | keys | length'
+
+echo "---"
+
+# Multiple model filter (comma-separated)
+forge workflow panel docs/ --models $FORGE_QA_WORKFLOW_MODELS --json 2>&1 | jq '{results: (.results | keys), successful: .successful, failed: .failed}'
+
+echo "---"
+
+# Verify result keys match the requested models
+forge workflow panel docs/ --models $FORGE_QA_WORKFLOW_MODEL_B --json 2>&1 | jq '.results | keys'
+```
+
+- [ ] Single `--models` value produces 1 result key in `.results`
+- [ ] Comma-separated `--models` produces one result per specified model (`.successful` count matches)
+- [ ] Result keys in `.results` correspond to the requested model names
+
+### 14.12 Workflow Routing, `--proxy`, and Preflight
+
+<!-- prereq: 4.2, 14.1 -->
+
+<!-- requires: api_key -->
+
+<!-- auto -->
+
+```bash
+# Explicit proxy routing: one selected proxy handles this worker.
+FORGE_DEBUG=1 forge workflow panel docs/ \
+  --models "$FORGE_QA_WORKFLOW_MODEL_A" \
+  --proxy "$FORGE_QA_OPENAI_PROXY" \
+  --json > /tmp/forge-workflow-via.json
+
+jq '{results: (.results | keys), successful, failed}' /tmp/forge-workflow-via.json
+
+echo "---"
+
+# Human output should surface non-blocking routing advisories when they apply.
+forge workflow analyze -p "Reply with READY only." \
+  --models "$FORGE_QA_WORKFLOW_MODEL_A" \
+  --proxy "$FORGE_QA_OPENAI_PROXY" 2>&1 | tee /tmp/forge-workflow-via-warning.txt
+
+grep -E "Routing warning|tier overrides|Proxy tier mappings" /tmp/forge-workflow-via-warning.txt || true
+
+echo "---"
+
+# Routing decisions are logged for observability when logging is enabled.
+latest_log="$(ls -t "$FORGE_HOME"/logs/cli/workflow.*.log 2>/dev/null | head -n 1)"
+test -n "$latest_log" && grep "Routing decision: model=$FORGE_QA_WORKFLOW_MODEL_A" "$latest_log"
+
+echo "---"
+
+# Direct Anthropic workers fail fast when no Anthropic credential is available.
+tmp_home="$(mktemp -d)"
+env -u ANTHROPIC_API_KEY FORGE_HOME="$tmp_home" \
+  forge workflow analyze -p "This should not call the model." \
+    --models claude-opus-4.6 \
+    --json 2>&1 | tee /tmp/forge-workflow-direct-preflight.json
+rm -rf "$tmp_home"
+
+jq -e 'any(.preflight_errors[]; test("ANTHROPIC_API_KEY|anthropic"; "i"))' \
+  /tmp/forge-workflow-direct-preflight.json
+```
+
+- [ ] `--proxy` resolves a compatible selected proxy and the JSON output remains parseable
+- [ ] Non-JSON workflow output prints a `Routing warning:` when `--proxy` selects a cross-family or live-advisory route
+  (same-family routes may have no warning)
+- [ ] The latest CLI workflow log contains a consolidated `Routing decision:` line with model, source, proxy/template,
+  and model ref
+- [ ] Direct Anthropic workflow workers fail during preflight with an actionable credential error when
+  `ANTHROPIC_API_KEY` is absent
+
+---

forge/_extensions/skills/qa/resources/checklist/15-skills.md

@@ -0,0 +1,155 @@
+<!-- prereq: 0.3, 2.1, 4.2, 5.1 -->
+
+## 15. Skills (`/forge:review`, `/forge:understand`, `/forge:panel`, `/forge:consensus`)
+
+Validates the user-facing skill invocation UX. Section 14 tested the underlying `forge workflow` CLI engine; this
+section tests the skills that wrap it with auto-detection and model-aware resource selection.
+
+The workflow-backed skills in this section depend on the workflow proxy aliases created in 4.2. In partial runs such as
+`--from 15`, prereq auto-resolution should create those aliases before `/forge:panel` or `/forge:consensus` is checked.
+
+### 15.1 `forge session context` CLI
+
+<!-- auto -->
+
+```bash
+# Verify the session context command works (requires an active session)
+forge session context test-session-1 --json
+
+# Extract model family field
+forge session context test-session-1 --field model_family
+```
+
+- [ ] Returns valid JSON with session_name, proxy, model_family, models, policy
+- [ ] `--field model_family` returns a raw string (openai, gemini, or anthropic)
+- [ ] Direct (no-proxy) session returns `model_family: "anthropic"`
+
+### 15.2 `forge session context` with UUID
+
+<!-- auto -->
+
+<!-- prereq: 5.1 -->
+
+```bash
+# Get the Claude session UUID from the session manifest
+UUID=$(cat .forge/sessions/test-session-1/forge.session.json | jq -r '.confirmed.claude_session_id // empty')
+
+# If UUID exists, verify UUID-based resolution
+if [ -n "$UUID" ]; then
+  forge session context "$UUID" --field session_name
+  echo "UUID_RESOLVED=true"
+else
+  echo "UUID_RESOLVED=skip (no confirmed UUID yet)"
+fi
+```
+
+- [ ] UUID resolves to the correct session name (or skips if no UUID confirmed yet)
+
+### 15.3 `/forge:review` (Live Session)
+
+<!-- human:guided -->
+
+<!-- requires: api_key -->
+
+In Session B (or a live Claude session in the container), invoke the review skill to verify resource selection.
+
+1. In the container shell, launch Claude and invoke the review skill:
+
+```
+/forge:review src/
+```
+
+2. Verify that Claude:
+   - Loads a code review resource from `~/.claude/skills/review/resources/`
+   - Produces a structured code review with findings
+
+Expected:
+
+- [ ] Skill invocation accepted by Claude Code (no "skill not found" error)
+- [ ] Review output includes file:line references and severity ratings
+
+### 15.4 `/forge:understand` (Live Session)
+
+<!-- human:guided -->
+
+<!-- requires: api_key -->
+
+In the same live Claude session, invoke the understand skill.
+
+1. Invoke the understand skill:
+
+```
+/forge:understand src/main.py --depth quick
+```
+
+2. Verify that Claude:
+   - Reads the target file
+   - Produces a structured explanation
+
+Expected:
+
+- [ ] Skill invocation accepted
+- [ ] Output includes Summary and Key Components sections
+- [ ] Quick depth produces concise output (\<500 words)
+
+### 15.5 `/forge:panel` (Live Session)
+
+<!-- human:guided -->
+
+<!-- requires: api_key -->
+
+In the same live Claude session, invoke the panel skill for a multi-model review.
+
+1. Invoke the panel skill:
+
+```
+/forge:panel src/ --code
+```
+
+2. This fans out to multiple models. Verify that Claude:
+   - Calls `forge workflow panel` under the hood
+   - Collects results from multiple models
+   - Synthesizes findings
+
+Expected:
+
+- [ ] Skill invocation accepted (runs as forked subagent)
+- [ ] Multi-model fan-out executes through configured workflow proxies
+- [ ] Output names the actual resolved model ref and proxy/template used for each worker
+- [ ] Synthesis includes consensus findings and unique insights
+
+Failure cue: if output says the default model set is unusable because OpenRouter proxies are missing, or falls back to a
+Claude-only panel, mark this step failed. That means 4.2 did not create the workflow proxy aliases for this run.
+
+### 15.6 `/forge:consensus` (Live Session)
+
+<!-- human:guided -->
+
+<!-- requires: api_key -->
+
+In the same live Claude session, invoke the consensus skill for a multi-model recommendation.
+
+1. Invoke the consensus skill:
+
+```
+/forge:consensus Should we split the session manager into separate read and write modules?
+```
+
+2. This runs two rounds across multiple models. Verify that Claude:
+   - Calls `forge workflow consensus` under the hood
+   - Round 1 collects independent positions from role-assigned workers
+   - Round 2 produces reconciled recommendations
+   - Synthesizes into agreed/disputed/no-consensus sections
+
+Expected:
+
+- [ ] Skill invocation accepted (runs as forked subagent)
+- [ ] Two-round execution visible in output (Round 1 positions + Round 2 reconciliation)
+- [ ] Output names the actual resolved model ref and proxy/template used for each worker
+- [ ] Synthesis distinguishes agreed recommendations from unresolved disagreements
+- [ ] Roles visible in output (architecture, security, correctness)
+
+Failure cue: if output says the default model set is unusable because OpenRouter proxies are missing, or falls back to
+Claude-only workers, mark this step failed. That means 4.2 did not create the workflow proxy aliases for this run.
+
+---

forge/_extensions/skills/qa/resources/checklist/16-handoff.md

@@ -0,0 +1,224 @@
+<!-- prereq: 0.3, 5.1, 10.1 -->
+
+## 16. Handoff Agent
+
+### 16.1 Configure Direct Handoff Targets
+
+<!-- requires: api_key -->
+
+<!-- auto -->
+
+```bash
+cd $FORGE_TEST_REPO
+
+# Seed one real target doc. The CLI validates existence, so the intentionally
+# missing doc used for runtime-skip coverage is injected below via raw override.
+mkdir -p .forge/memory
+cat > .forge/memory/debugging.md <<'EOF'
+# Debugging Notes
+EOF
+
+# Enable handoff agent for the session and configure explicit designated docs.
+forge session set memory.auto_update.enabled true --session test-session-1
+forge session set memory.auto_update.min_turns 1 --session test-session-1
+forge session set memory.auto_update.mode augment --session test-session-1
+forge session set memory.designated_docs '[]' --session test-session-1
+forge session memory add-doc .forge/memory/debugging.md --strategy debugging --session test-session-1
+forge session memory list-docs --json --session test-session-1 | jq -e '
+  length == 1
+  and any(.[]; .path == ".forge/memory/debugging.md" and .strategy == "debugging")
+'
+
+# Inject one missing doc directly to validate the agent's runtime skip path.
+# This represents stale/manual config; `forge session memory add-doc` should reject it.
+forge session set memory.designated_docs '[{"path":".forge/memory/debugging.md","strategy":"debugging","shadows":null},{"path":".forge/memory/patterns.md","strategy":"patterns","shadows":null}]' --session test-session-1
+forge session memory list-docs --session test-session-1
+forge session memory list-docs --json --session test-session-1 | jq -e '
+  length == 2
+  and any(.[]; .path == ".forge/memory/debugging.md" and .strategy == "debugging")
+  and any(.[]; .path == ".forge/memory/patterns.md" and .strategy == "patterns")
+'
+
+# Verify config
+cat .forge/sessions/test-session-1/forge.session.json | jq '.overrides.memory'
+```
+
+- [ ] Handoff config written to session overrides
+- [ ] `enabled`, `min_turns`, and `mode` values set
+- [ ] `forge session memory add-doc/list-docs` configures an existing designated doc
+- [ ] Raw override includes one missing designated doc for runtime skip coverage
+- [ ] Config stores worktree-relative paths under `memory.designated_docs`
+
+### 16.2 Run Handoff Manually (Direct Update)
+
+<!-- prereq: 16.1 -->
+
+<!-- requires: api_key -->
+
+<!-- auto -->
+
+```bash
+cd $FORGE_TEST_REPO
+
+# Create a deterministic transcript artifact with clear debugging takeaways.
+mkdir -p .forge/artifacts/test-session-1/transcripts
+cat > .forge/artifacts/test-session-1/transcripts/manual-handoff-direct.jsonl <<'EOF'
+{"requestId":"handoff-1","message":{"role":"user","content":[{"type":"text","text":"Pytest failed with ModuleNotFoundError for tomlkit."}]}}
+{"requestId":"handoff-1","message":{"role":"assistant","content":[{"type":"text","text":"The root cause was a missing dependency in the dev environment. Running uv sync fixed it."}]}}
+{"requestId":"handoff-2","message":{"role":"user","content":[{"type":"text","text":"Please capture that debugging note for next time."}]}}
+{"requestId":"handoff-2","message":{"role":"assistant","content":[{"type":"text","text":"Noted: if tests fail with ModuleNotFoundError for tomlkit, run uv sync before retrying."}]}}
+EOF
+
+BEFORE_LINES=$(wc -l < .forge/memory/debugging.md)
+
+forge handoff run \
+  --session-name test-session-1 \
+  --worktree-path $FORGE_TEST_REPO \
+  --transcript-rel .forge/artifacts/test-session-1/transcripts/manual-handoff-direct.jsonl
+
+AFTER_LINES=$(wc -l < .forge/memory/debugging.md)
+
+echo "before=$BEFORE_LINES after=$AFTER_LINES"
+cat .forge/memory/debugging.md
+
+ls .forge/artifacts/test-session-1/handoff/review-*.md
+forge session handoff show test-session-1 --latest
+
+test "$AFTER_LINES" -gt "$BEFORE_LINES"
+test ! -e .forge/memory/patterns.md
+```
+
+- [ ] Missing designated docs are skipped (not created)
+- [ ] Worktree-relative doc paths resolve correctly in the test repo
+- [ ] `forge handoff run` succeeds with the transcript artifact path provided
+- [ ] Existing designated docs are updated with session takeaways
+- [ ] Handoff agent stdout is persisted and visible via `forge session handoff show --latest`
+
+### 16.3 Shadow Handoff (`suggested` + `shadows`)
+
+<!-- prereq: 16.1 -->
+
+<!-- requires: api_key -->
+
+<!-- auto -->
+
+```bash
+cd $FORGE_TEST_REPO
+
+# Create a shadow doc pair and switch designated_docs to the suggested/shadows surface.
+mkdir -p .forge/memory docs
+cat > docs/team-standards.md <<'EOF'
+# Team Standards
+
+- Prefer small, reviewable patches.
+EOF
+
+cat > .forge/memory/suggested_standards.md <<'EOF'
+# Suggested Standards
+EOF
+
+forge session set memory.auto_update.mode augment --session test-session-1
+forge session set memory.designated_docs '[]' --session test-session-1
+forge session memory add-doc .forge/memory/suggested_standards.md \
+  --strategy suggested \
+  --shadows docs/team-standards.md \
+  --session test-session-1
+forge session memory list-docs --session test-session-1
+
+mkdir -p .forge/artifacts/test-session-1/transcripts
+cat > .forge/artifacts/test-session-1/transcripts/manual-handoff-shadow.jsonl <<'EOF'
+{"requestId":"shadow-1","message":{"role":"user","content":[{"type":"text","text":"We kept fixing bugs caused by giant mixed-purpose commits."}]}}
+{"requestId":"shadow-1","message":{"role":"assistant","content":[{"type":"text","text":"A new standard could require small focused commits with clear intent."}]}}
+{"requestId":"shadow-2","message":{"role":"user","content":[{"type":"text","text":"Please propose that as guidance rather than editing the official standards directly."}]}}
+{"requestId":"shadow-2","message":{"role":"assistant","content":[{"type":"text","text":"I will suggest it in the shadow file for human review."}]}}
+EOF
+
+cp docs/team-standards.md /tmp/team-standards.before
+SHADOW_BEFORE=$(wc -l < .forge/memory/suggested_standards.md)
+
+forge handoff run \
+  --session-name test-session-1 \
+  --worktree-path $FORGE_TEST_REPO \
+  --transcript-rel .forge/artifacts/test-session-1/transcripts/manual-handoff-shadow.jsonl
+
+SHADOW_AFTER=$(wc -l < .forge/memory/suggested_standards.md)
+
+cat .forge/memory/suggested_standards.md
+
+cmp -s docs/team-standards.md /tmp/team-standards.before
+test "$SHADOW_AFTER" -gt "$SHADOW_BEFORE"
+```
+
+- [ ] `designated_docs` accepts `strategy: suggested` with `shadows`
+- [ ] Handoff runs successfully against the shadow doc pair
+- [ ] Shadow file gains proposed additions for later human review
+- [ ] Official document is not edited in-place
+
+### 16.4 Queued Handoff on Next CLI Startup
+
+<!-- prereq: 16.1 -->
+
+<!-- requires: api_key -->
+
+<!-- auto -->
+
+```bash
+cd $FORGE_TEST_REPO
+
+# Restore direct-update config for the queued-path test.
+forge session set memory.auto_update.mode augment --session test-session-1
+forge session set memory.designated_docs '[{"path":".forge/memory/debugging.md","strategy":"debugging","shadows":null},{"path":".forge/memory/patterns.md","strategy":"patterns","shadows":null}]' --session test-session-1
+
+cat > .forge/memory/debugging.md <<'EOF'
+# Debugging Notes
+EOF
+
+mkdir -p .forge/walkthrough
+cat > .forge/walkthrough/handoff-queued-source.jsonl <<'EOF'
+{"requestId":"queued-1","message":{"role":"user","content":[{"type":"text","text":"Ruff failed because generated fixtures were not formatted."}]}}
+{"requestId":"queued-1","message":{"role":"assistant","content":[{"type":"text","text":"Running make format fixed the generated fixtures and the follow-up lint pass succeeded."}]}}
+{"requestId":"queued-2","message":{"role":"user","content":[{"type":"text","text":"Please preserve that debugging note for the next session."}]}}
+{"requestId":"queued-2","message":{"role":"assistant","content":[{"type":"text","text":"I will capture that this failure mode is resolved by re-running make format before lint."}]}}
+EOF
+
+SESSION_ID=$(cat .forge/sessions/test-session-1/forge.session.json | jq -r '.confirmed.claude_session_id')
+BEFORE_LINES=$(wc -l < .forge/memory/debugging.md)
+MARKER="${FORGE_HOME:-$HOME/.forge}/pending-work/handoff-${SESSION_ID}.json"
+
+STOP_INPUT=$(jq -nc \
+  --arg sid "$SESSION_ID" \
+  --arg transcript ".forge/walkthrough/handoff-queued-source.jsonl" \
+  '{hook_event_name:"Stop",session_id:$sid,transcript_path:$transcript}')
+
+STOP_OUTPUT=$(echo "$STOP_INPUT" | FORGE_SESSION=test-session-1 forge hook stop)
+echo "$STOP_OUTPUT" | jq '.'
+echo "$STOP_OUTPUT" | jq -e '.queued_handoff == true'
+
+test -f "$MARKER"
+
+# Any later Forge CLI startup should process the queued marker and spawn handoff in the background.
+forge session list >/tmp/handoff-queue-trigger.log
+
+for _ in $(seq 1 30); do
+  AFTER_LINES=$(wc -l < .forge/memory/debugging.md)
+  if [ ! -f "$MARKER" ] && [ "$AFTER_LINES" -gt "$BEFORE_LINES" ]; then
+    break
+  fi
+  sleep 1
+done
+
+AFTER_LINES=$(wc -l < .forge/memory/debugging.md)
+echo "before=$BEFORE_LINES after=$AFTER_LINES marker=$MARKER"
+cat .forge/memory/debugging.md
+
+test ! -f "$MARKER"
+test "$AFTER_LINES" -gt "$BEFORE_LINES"
+```
+
+- [ ] Stop hook reports `queued_handoff: true`
+- [ ] Handoff marker is created under `~/.forge/pending-work/`
+- [ ] A later Forge CLI startup processes the queued handoff automatically
+- [ ] Background handoff updates the designated doc without a direct `forge handoff run`
+- [ ] Pending handoff marker is gone after processing completes
+
+---