@aperant/framework 0.8.1 → 0.8.4

package/dist/plugin/skills/apt-resume/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: apt:resume
-description: "Restore context from a paused session or recover from a crash"
+description: "Restore context from a paused session, an agent handoff, or recover from a crash"
 apt-skill-version: {{APT_VERSION}}
 stage: resume
 intent: capture
-when_to_use: "The user is returning to paused work or recovering from a crash and needs to restore context from CONTINUE artifacts or the active-task state."
+when_to_use: "The user is returning to paused work, picking up an agent-to-agent handoff, or recovering from a crash and needs to restore context from CONTINUE artifacts, HANDOFF artifacts, or the active-task state."
 user_invocable: true
 internal: false
 spawns_agent: false
@@ -19,14 +19,15 @@ argument-hint: "apt:resume [task-id]"
 gates: []
 ---
 <objective>
-Restore context and continue work after a session break — whether it was a graceful pause (CONTINUE files exist) or a crash/disconnect (no CONTINUE but state.json has an active task). Supports multiple paused sessions — shows all and lets the user pick which to resume.
+Restore context and continue work after a session break — whether it was a graceful pause (CONTINUE files exist), an agent-to-agent handoff (HANDOFF files exist, written by `/apt:handoff`), or a crash/disconnect (no CONTINUE/HANDOFF but state.json has an active task). Supports multiple resumable sessions of mixed type — shows all and lets the user pick which to resume.
 </objective>
 
 <your_environment>
 - **Working directory:** The project root (where you were invoked)
 - **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
 - **Constitution:** Read `AGENTS.md` in the project root if it exists
-- **Pause index:** `.aperant/CONTINUE_INDEX.md` (lists all paused sessions)
+- **Pause index:** `.aperant/CONTINUE_INDEX.md` (human-pause sessions written by `/apt:pause`)
+- **Handoff index:** `.aperant/HANDOFFS_INDEX.md` (agent-to-agent handoffs written by `/apt:handoff`)
 - **Legacy handoff:** `.aperant/CONTINUE.md` (pre-v2 single-file format, migrate if found)
 - **State:** `.aperant/state.json` (always exists if initialized)
 - **Cross-agent team signal:** `.aperant/team-status/{agent-id}.json` records (gitignored, TTL-expired) are the canonical "who's working on what" surface; `state.active_tasks` is this agent's local view.
@@ -35,74 +36,85 @@ Restore context and continue work after a session break — whether it was a gra
 
 <process>
 
-## 1. Discover Paused Sessions
+## 1. Discover Resumable Sessions
+
+Each discovered session is tagged with a **type** — `pause` (human stopped, `CONTINUE.md`) or `handoff` (agent transferred work, `HANDOFF.md`) — and tracked alongside its location. Scan both surfaces; do not assume only one exists.
 
 ### 1a. Check for pause index
-Read `.aperant/CONTINUE_INDEX.md` if it exists — this is the primary source of paused sessions.
+Read `.aperant/CONTINUE_INDEX.md` if it exists — primary source for `type=pause` sessions.
+
+### 1b. Check for handoff index
+Read `.aperant/HANDOFFS_INDEX.md` if it exists — primary source for `type=handoff` sessions (agent-to-agent transfers from `/apt:handoff`).
 
-### 1b. Check for legacy CONTINUE.md
+### 1c. Check for legacy CONTINUE.md
 If `.aperant/CONTINUE.md` exists (pre-v2 format), treat it as one paused session. Migrate it after resume:
 - Move it to the appropriate task dir or `.aperant/paused/` location
-- Add it to the index
+- Add it to `CONTINUE_INDEX.md`
 
-### 1c. Scan for task-level CONTINUE files
-As a fallback, scan for CONTINUE.md files that might not be in the index:
+### 1d. Scan for task-level CONTINUE and HANDOFF files
+As a fallback, scan for files that might not be in either index:
 ```bash
 find .aperant/tasks/*/CONTINUE.md .aperant/paused/*/CONTINUE.md 2>/dev/null
+find .aperant/tasks/*/handoffs/*/HANDOFF.md .aperant/handoffs/*/HANDOFF.md 2>/dev/null
 ```
 
-### 1d. Check state.json for active tasks
+### 1e. Check state.json for active tasks
 ```bash
 node packages/framework/bin/apt-tools.mjs health-check .
 node packages/framework/bin/apt-tools.mjs task list .
 ```
 
-Combine all sources into a unified list of resumable sessions.
+Combine all sources into a unified list of resumable sessions, each carrying `{ type, path, branch, focus_or_task, date, suggested_receiver? }`.
 
 ## 2. Present Sessions
 
-### If multiple paused sessions found:
+### If multiple resumable sessions found:
+
+Render handoffs FIRST (agent dropped work in your lap = higher urgency than human-paused work). Tag each row with `[pause]` or `[handoff]`.
 
 ```
-Paused Sessions
+Resumable Sessions
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  1. Chat UI Polish + Sidebar Redesign
+  1. [handoff] Finish MCP token rotation wiring
+     Branch: feat/mcp-rotation | Handed off: 2026-05-22 14:30
+     Sender: Claude Opus 4.7 / Claude Code → Receiver: any agent
+     → .aperant/handoffs/handoff-20260522-1430-finish-mcp-token-rotation/HANDOFF.md
+
+  2. [pause] Chat UI Polish + Sidebar Redesign
      Branch: closing-phase-4 | Paused: 2026-04-13
      Progress: 6/9 items done
      → .aperant/paused/paused-20260413-chat-ui-polish/CONTINUE.md
 
-  2. Onboarding State Unification
+  3. [pause] Onboarding State Unification
      Branch: feat/onboarding-sync | Paused: 2026-04-13
      Progress: executing subtask 3/5
      → .aperant/tasks/task-20260413-onboarding-sync/CONTINUE.md
 
-  3. Fix DB Path in services.ts
-     Branch: closing-phase-4 | Paused: 2026-04-12
-     Progress: planned, not started
-     → .aperant/tasks/task-20260412-fix-db-path/CONTINUE.md
-
 Which session to resume? (number, or "all" to see full context for each)
 ```
 
 Wait for user selection before proceeding.
 
-### If one paused session found:
+### If one resumable session found:
 Proceed directly to Step 3 with that session.
 
-### If no paused sessions but active tasks in state.json:
+### If no resumable sessions but active tasks in state.json:
 Follow crash recovery flow (Step 4).
 
 ### If nothing found:
 ```
-No paused sessions or active tasks found.
+No paused sessions, handoffs, or active tasks found.
 
 → Start something new: /apt "describe your task"
 ```
 
 ## 3. Resume Selected Session
 
-Read the selected CONTINUE.md and extract:
+Branch on `type`:
+
+### 3a. type=pause — read CONTINUE.md
+Extract:
 - **Task description** — What was being worked on
 - **Branch** — Which branch to be on
 - **Decisions made** — Context that must not be lost
@@ -110,26 +122,37 @@ Read the selected CONTINUE.md and extract:
 - **Current state** — Pipeline stage, progress
 - **Next steps** — Ordered list of what to do next
 
+### 3b. type=handoff — read HANDOFF.md
+Extract the handoff-specific fields:
+- **Focus For The Receiver** — the load-bearing paragraph; this drives the immediate next action
+- **Sender / Suggested receiver** — model + CLI hints (warn if the current agent is a poor fit, e.g. handoff suggested Codex for a heavy refactor and the receiver is a small model)
+- **Existing Artifacts** — open each referenced path/URL into context BEFORE acting
+- **Decisions Made (do NOT relitigate)** — treat as locked context
+- **Uncommitted changes** — handoffs do NOT stash; verify the listed files still exist in the working tree with `git status --short` and reconcile if drift occurred since the handoff was written
+- **External state the receiver must check** — verify each item (dev server running, PR open, MCP session live) before resuming
+- **Suggested Skills** — use as the next-action recommendation
+
 ### Check Branch
 ```bash
 git branch --show-current
 ```
 If not on expected branch: suggest `git checkout {expected-branch}`
 
-### Restore Stashed Work
-If CONTINUE.md indicates stashed changes, find and pop the matching stash:
+### Restore Stashed Work (pause only)
+For `type=pause` ONLY — if CONTINUE.md indicates stashed changes, find and pop the matching stash:
 ```bash
 git stash list | grep "apt-pause: {task description}"
 ```
+`type=handoff` never stashes; skip this step for handoffs.
 
 ### Present Context Summary
-Display all key context from CONTINUE.md, then suggest the next action based on pipeline stage.
+Display all key context from the artifact, then suggest the next action based on pipeline stage (pause) or Focus + Suggested Skills (handoff).
 
 ### Clean Up After Resume
 After user confirms they have context:
-- Remove the CONTINUE.md file that was resumed
-- Remove its row from CONTINUE_INDEX.md
-- If the index is now empty, delete CONTINUE_INDEX.md
+- Remove the resumed artifact file (`CONTINUE.md` or `HANDOFF.md`)
+- Remove its row from the matching index (`CONTINUE_INDEX.md` or `HANDOFFS_INDEX.md`)
+- If the index is now empty, delete it
 
 ## 4. Crash Recovery (no CONTINUE, stale active_tasks)
 

package/dist/plugin/skills/apt-run/SKILL.md

@@ -17,7 +17,7 @@ execution_modes:
   - plan-mode
   - plan-only
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
-argument-hint: "apt:run [task description] [--skip-review] [--phase-mode auto|agent-team|sub-agents|sequential]"
+argument-hint: "apt:run [task description] [--skip-review] [--phase-mode auto|agent-team|sub-agents|sequential] [--spar-gates plan[,execute]]"
 gates: 
   - constitution-read
   - constitution-coverage
@@ -58,7 +58,14 @@ As of C32 the STANDARD and DEEP auto pipelines **terminate on review** (`plan
 
 1. Read `AGENTS.md` if it exists
 2. Parse task description from `$ARGUMENTS` (everything before flags)
-3. Parse flags: `--skip-review`, `--dry-run`
+3. Parse flags: `--skip-review`, `--dry-run`, `--phase-mode <mode>`, `--spar-gates <comma-list>`.
+   - `--spar-gates <plan|execute|plan,execute>` (FRAMEWORK-RFC-001) — comma-separated stage list to auto-fire `/apt:spar` after. Per-invocation override of `.aperant/config.local.json` `spar.enabled`. On QUICK track, print the verbatim hard-reject line and discard the flag (Fast Path Guarantee — CLAUDE.md):
+
+   ```
+   [apt:run] --spar-gates ignored for QUICK track (Fast Path Guarantee)
+   ```
+
+   On STANDARD / DEEP / DEBUG tracks, the flag is honored and consumed by §3b (plan gate) and §4b (execute gate). Default is to fall back to merged-config `spar.enabled` semantics — see §3b / §4b for the full resolution order. The flag accepts only `plan`, `execute`, or `plan,execute` — any other value is rejected with `[apt:run] --spar-gates accepts plan, execute, or plan,execute`.
 
 ```bash
 node packages/framework/bin/apt-tools.mjs state .
@@ -127,6 +134,12 @@ node packages/framework/bin/apt-tools.mjs commit "plan: create implementation pl
 
 **Output:** spec.md, implementation_plan.json
 
+**Spar hint surface (FRAMEWORK-RFC-001).** If merged-config `spar.hint === true` AND `spar.enabled === false`, print:
+```
+[apt] plan complete. /apt:spar available before next stage. (skill, not auto-fire)
+```
+Skip the print on `spar.enabled === true` (the gate handler in §3b already fires).
+
 If `--dry-run` flag is set:
 ```
 Dry run complete. Plan created but not executed.
@@ -137,6 +150,51 @@ Remove --dry-run to execute the full pipeline.
 ```
 Exit.
 
+## 3b. Stage 1.5 — Spar Gate (plan)
+
+**FRAMEWORK-RFC-001 — auto-fire `/apt:spar` after the plan stage when consent is on.**
+
+Resolve effective gates:
+
+1. **Track gate.** If track is `QUICK`, **skip this entire section** and continue to §4. QUICK is hard-exempt per CLAUDE.md Fast Path Guarantee. If the user passed `--spar-gates` on a QUICK invocation, §1 already printed the verbatim hard-reject and discarded the flag.
+2. **Read merged config** via `loadMergedProjectConfig(.)`:
+
+   ```bash
+   node packages/framework/bin/apt-tools.mjs config show . --merged
+   ```
+
+   Parse `spar.enabled` (boolean) and `spar.partner` (`'codex' | 'claude' | 'gemini' | null`). When `spar.enabled === true`, build default gates by track: `["plan"]` for STANDARD, `["plan", "execute"]` for DEEP.
+3. **Per-invocation override.** If the user passed `--spar-gates <list>` on the `/apt:run` invocation (parsed in §1), the explicit value WINS over merged-config defaults (per-invocation precedence — classic config precedence).
+4. **Gate check.** If `"plan"` is not in the resolved gate list, skip the rest of this section.
+
+If `"plan"` is in the resolved gate list, dispatch the spar gate.
+
+**Compose the topic frame (1–2 sentences).** Prefer `spec.md` §Scope (the first paragraph under the `## 1. Scope` heading). If spec.md has no `## 1. Scope` heading (QUICK-skipped or non-PRD-shaped — Open Q4 graceful fallback), use the task description passed to `/apt:run`.
+
+**Dispatch `/apt:spar`** with the topic frame. **Pipeline-mode invocation MUST carry `--timeout-ms 120000`** (2-min Bash-rung fast-fail per spec §4.6 "Pipeline-mode timeout rationale" — pipeline gates run under a tighter budget than manual `apt:spar`). **NO `--rounds` flag** (per FRAMEWORK-BUG-038 fix — pipeline gates always defer to the skill default; passing `--rounds 1` would re-introduce the Round 1 unilateral-terminate bug). When `spar.partner` is set in merged config, append `--with <partner>`; when null, omit `--with` and let `apt:spar` use the host-default-partner mapping in `apt-spar/SKILL.md` §3.
+
+```
+/apt:spar --timeout-ms 120000 [--with <partner>] <topic-frame-from-spec.md-or-task-description>
+```
+
+**Pipeline-mode timeout rationale.** `apt-spar/SKILL.md:198` "Timeout calibration" notes that modern partner CLIs commonly spend multiple minutes doing real Read/Grep/Bash investigation, justifying the manual-mode 5-min Bash-rung / 15-min MCP-rung defaults. Pipeline-mode partner queries are NARROWER than manual: the gate prompt is a focused 1-2-sentence frame on a specific just-completed stage, not open-ended brainstorming. 2 minutes is adequate for that narrower scope, and `partner-unreachable` (the rung ladder exhausts within 2 min) skips the gate cleanly without blocking the pipeline. Worst-case DEEP wall budget: 2 gates × 3 rounds × 2 min = 12 min (vs ~90 min before this clamp under MCP-rung partner degradation). MCP-rung tightening is out of scope per Open Q5 — see spec §4.6.
+
+**Consent-on but partner-null inline prompt.** If `spar.enabled: true && spar.partner === null` (consent given but no partner detected at install — graceful skip path), prompt the user inline before dispatch (the inline prompt's dispatch ALSO carries `--timeout-ms 120000` and NO `--rounds` flag):
+
+```
+[apt:run] Sparring auto-fire is enabled but no partner was set at install. Pick one now ([1] codex / [2] claude / [3] gemini / [s] skip this gate):
+```
+
+Map response → invoke `/apt:spar --timeout-ms 120000 --with <id> <topic-frame>` (no `--rounds`), or skip the gate. Do NOT write the choice back to `config.local.json` automatically — the user re-runs `/apt:setup` → Pipeline → Sparring Auto-Fire to persist.
+
+**After spar returns to natural convergence:**
+
+1. Read the spar termination headline (printed inline by `apt:spar/SKILL.md` §9 Layer 1).
+2. Capture the Layer 2 file path from the `Full detail:` line of the headline (e.g. `.aperant/spar/<slug>-<YYYYMMDD-HHMMSS>.md`).
+3. Append both the one-line headline summary AND the Layer 2 file path into the executor's spawn context for §4 (the executor reads spar findings before subtask 1).
+
+If the gate emits `partner-unreachable` (rung ladder exhausted within timeout), skip the gate cleanly and continue to §4 — do NOT fail the pipeline.
+
 ## 4. Stage 2 — Execute (apt:execute)
 
 Branch on `PHASE_MODE`:
@@ -168,6 +226,34 @@ Execute the apt:execute workflow inline:
 
 **Output:** All subtasks completed, build-progress.json updated
 
+**Spar hint surface (FRAMEWORK-RFC-001).** If merged-config `spar.hint === true` AND `spar.enabled === false`, print:
+```
+[apt] execute complete. /apt:spar available before next stage. (skill, not auto-fire)
+```
+Skip on `spar.enabled === true` (the gate handler in §4b already fires).
+
+## 4b. Stage 2.5 — Spar Gate (execute)
+
+**FRAMEWORK-RFC-001 — auto-fire `/apt:spar` after the execute stage on DEEP (or explicit user opt-in).**
+
+Same resolution logic as §3b, but the gate name is `"execute"` and the topic frame is composed from `build-progress.json` (1–2 sentences summarizing the diff that just landed, e.g. "N subtasks completed against the M-file plan; the largest change touched <path>"). If `build-progress.json` is missing or empty, fall back to the task description (Open Q4 graceful fallback).
+
+**Track gate:** if track is `QUICK`, skip this section entirely (Fast Path Guarantee). Default gates from merged-config `spar.enabled === true` only include `"execute"` on DEEP. STANDARD does NOT enter this block by default; DEEP does. User-passed `--spar-gates plan,execute` opts STANDARD into this block too (per-invocation precedence).
+
+**Gate check:** if `"execute"` is not in the resolved gate list, skip this section.
+
+If `"execute"` is in the resolved gate list, dispatch as in §3b — same pipeline-mode budget:
+
+```
+/apt:spar --timeout-ms 120000 [--with <partner>] <topic-frame-from-build-progress.json>
+```
+
+**NO `--rounds` flag** (per FRAMEWORK-BUG-038 — pipeline always defers to skill default). Same `--timeout-ms 120000` 2-min Bash-rung fast-fail as §3b. Same inline-prompt path for the `enabled: true && partner === null` graceful-skip case (the inline-prompt dispatch ALSO carries `--timeout-ms 120000`).
+
+After spar returns, parse the termination headline + Layer 2 path and append both into the verifier's spawn context for §5 (the verifier reads execute-gate spar findings alongside its de-anchored re-read).
+
+`partner-unreachable` skips the gate cleanly — pipeline continues to §5.
+
 ## 5. Stage 3 — Verify (apt:verify)
 
 **De-anchored re-read (PHASE_MODE=sequential only — roundtable 2026-05-14 R2):**
@@ -183,6 +269,8 @@ This block exists because the roundtable's STANDARD-track de-anchoring relies on
 
 Sub-agents and agent-team modes skip this block — they get fresh-context isolation by spawning, which makes the de-anchored re-read redundant.
 
+**Spar findings context (FRAMEWORK-RFC-001).** If §3b or §4b dispatched `/apt:spar`, the verifier MUST read the Layer 2 file (`.aperant/spar/<slug>-<YYYYMMDD-HHMMSS>.md`) before scoring — both gate files when DEEP fired both gates. Spar findings flagged as `parallel call-outs` in the Layer 2 file may require `qa_signoff.json` `notes` entries even when not blocking. The headline summary already lives in the verifier's spawn context (appended by §3b / §4b); the Layer 2 read is the load-bearing detail loop.
+
 Execute the apt:verify workflow inline:
 
 1. Check all subtasks completed
@@ -200,6 +288,12 @@ Execute the apt:verify workflow inline:
 
 **Output:** qa_signoff.json with status
 
+**Spar hint surface (FRAMEWORK-RFC-001).** If merged-config `spar.hint === true` AND `spar.enabled === false`, print:
+```
+[apt] verify complete. /apt:spar available before next stage. (skill, not auto-fire)
+```
+Skip on `spar.enabled === true` (no verify-stage gate exists in v2 — see spec §8 Out of Scope; this nudge surfaces /apt:spar as a manual option only).
+
 If `qa_signoff.json` status is `"rejected"` after max iterations:
 ```
 Verification failed after {n} iterations. Issues remain:
@@ -236,28 +330,32 @@ Execute the apt:review workflow inline (see `apt-review/SKILL.md`):
 
 **Output:** review.json (written to task directory)
 
+**Spar hint surface (FRAMEWORK-RFC-001).** If merged-config `spar.hint === true` AND `spar.enabled === false`, print:
+```
+[apt] review complete. /apt:spar available before next stage. (skill, not auto-fire)
+```
+Skip on `spar.enabled === true` (no pre-ship gate exists in v2 — see spec §8 Out of Scope).
+
 **This is the task review, not the PR review.** It runs inline without sub-agents. For heavy multi-agent PR review, use `/apt:pr-review` separately.
 
 ## 7. Pipeline Summary
 
-```
-Pipeline Complete: {task description}
+Render the phase rail panel verbatim — branch glyphs `┌─ │ └─`, status glyphs `✓` (done) / `●` (active) / `○` (pending/skipped), inline metrics per row drawn from the artifacts written across §3–§6:
 
+```
+[APT] Pipeline Complete: {task description}
+┌─ Phase rail: {short task name} ───────────────────
+│  Phase 1 Plan       ✓  {n} subtasks
+│  Phase 2 Execute    ✓  {completed}/{total} subtasks, {k} commits
+│  Phase 3 Verify     ✓  {qa_status} {completeness}/{correctness}/{quality}/{coverage}
+│  Phase 4 Review     ✓  {assessment} {scores}, {findings_count} findings ({fixed} fixed)
+└───────────────────────────────────────────────────
 Branch: apt/{sanitized-task-name}
-Stages:
-  1. Plan:    spec.md + implementation_plan.json ({n} subtasks)
-  2. Execute: {completed}/{total} subtasks completed
-  3. Verify:  {qa_status} (scores: {completeness}/{correctness}/{quality}/{coverage})
-  4. Review:  {assessment} ({findings} found, {fixed} fixed, {remaining} remaining)
-
-Artifacts:
-  - spec.md
-  - implementation_plan.json
-  - build-progress.json
-  - qa_signoff.json
-  - review.json
+Artifacts: spec.md · implementation_plan.json · build-progress.json · qa_signoff.json · review.json
 ```
 
+Substitute live values from the on-disk artifacts: `build-progress.json.completed_subtasks.length` for the commits count, `qa_signoff.json.verdict` + `scores` for verify, `review.json.assessment` + `scores` + `findings.length` for review. Use `●` for a stage still in flight (e.g. verify rejected mid-rerun), `○` only for a stage skipped entirely. The `[APT] Pipeline Complete` header above the panel is the backward-compat marker for external log-grep tooling — keep it.
+
 **Always end with a "What's Next" recommendation:**
 
 ```

package/dist/plugin/skills/apt-setup/SKILL.md

@@ -199,7 +199,7 @@ AskUserQuestion([
 
 **Routing:**
 - "Verification" → jump to **Step 2** (Batch 1 + Batch 2 only), then skip to **Step 4** (mapping) and **Step 5** (write)
-- "Pipeline" → jump to **Step 3b** (Batch 3 only, including Diagram Mode), then skip to **Step 4** and **Step 5**
+- "Pipeline" → jump to **Step 3** (Batch 2: auto-branch, code review, TDD, PR Review Auto-Suggest, **Sparring Auto-Fire**) AND **Step 3b** (Batch 3 only, including Diagram Mode), then skip to **Step 4** and **Step 5**
 - "Orchestration" → jump to **Step 3c** (Batch 4 only), then skip to **Step 4** and **Step 5**
 - "Team Collaboration" → jump to **Step 3d** (Batch 5 only), then skip to **Step 4** and **Step 5**
 - "Visibility" → jump to **Step 3e** (Batch 6 only), then skip to **Step 4** and **Step 5**
@@ -359,6 +359,76 @@ AskUserQuestion([
 ])
 ```
 
+### Sparring Auto-Fire (FRAMEWORK-RFC-001)
+
+Per-device opt-in for pipeline-integrated `/apt:spar`. Three phases — top-level Yes/No, then a conditional partner picker (if Yes) or hint sub-picker (if No). All three resolved fields land in `.aperant/config.local.json` per AUDIT-001 (NOT the shared `config.json`).
+
+**Phase 1 — Top-level Yes/No:**
+
+```
+AskUserQuestion([
+  {
+    question: "Enable /apt:spar to auto-fire after planning (and execution on DEEP tasks)? Spawns a second LLM provider to challenge the plan before you commit code.",
+    header: "Sparring Auto-Fire",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended for now)", description: "Keep /apt:spar manual-only. You invoke it yourself when you want a second opinion." },
+      { label: "Yes", description: "After every /apt:run plan stage (STANDARD) or plan+execute stages (DEEP), spawn a partner LLM to spar with the current host. QUICK tasks are hard-exempt." }
+    ]
+  }
+])
+```
+
+**Phase 2 — Partner picker (only if Phase 1 = Yes):**
+
+Before showing the picker, run `apt-tools host-detect` and parse `host.partner_transports.{codex,claude,gemini}` plus `host.cli`. Build the partner availability map:
+
+```bash
+node packages/framework/bin/apt-tools.mjs host-detect
+```
+
+For each of `codex`, `claude`, `gemini`, check whether ANY rung (MCP, plugin, raw CLI) under `host.partner_transports.<id>` is `detected: true` (or `"runtime-host-only"` for the MCP rung). Also exclude the current host (`host.cli`) — `/apt:spar` rejects same-host sparring by construction (Open Q1 — e.g. on `claude-code` host, the `claude` option is hidden because sparring against the same CLI is sycophancy).
+
+If zero partners remain after filtering, print this graceful skip line and write `spar.enabled: true, spar.partner: null` so the user can opt back in later by installing a partner CLI and re-running `/apt:setup` → Pipeline:
+
+```
+[apt:setup] Sparring auto-fire enabled but no partner CLIs detected. Install codex / claude / gemini and re-run /apt:setup → Pipeline → Sparring Auto-Fire to pick a partner.
+```
+
+Otherwise, show the partner picker including only detected, non-same-host partners. Example (on a Claude Code host where codex MCP is loaded and gemini CLI is installed):
+
+```
+AskUserQuestion([
+  {
+    question: "Which partner LLM should /apt:spar use by default? You can override per-invocation with --with <id>.",
+    header: "Sparring Partner",
+    multiSelect: false,
+    options: [
+      // Include only detected, non-same-host partners. Example shape:
+      { label: "Codex (gpt-5)", description: "OpenAI Codex CLI / MCP — sharp on type and edge-case reasoning." },
+      { label: "Gemini", description: "Google Gemini — sharp on broad search and doc citations." }
+      // "Claude (sonnet)" omitted on a claude-code host (same-host rejection).
+    ]
+  }
+])
+```
+
+**Phase 3 — Hint sub-picker (only if Phase 1 = No):**
+
+```
+AskUserQuestion([
+  {
+    question: "Print a one-line reminder at the end of each pipeline stage that /apt:spar is available?",
+    header: "Sparring Hint",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended)", description: "Silent. You remember to run /apt:spar yourself when needed." },
+      { label: "Yes", description: "Print `[apt] {stage} complete. /apt:spar available before next stage. (skill, not auto-fire)` at each stage hand-off." }
+    ]
+  }
+])
+```
+
 ### Task-level worktree isolation (only if host supports worktrees)
 
 First check `host.capabilities.worktrees` from the host-detect output. If `false` (Codex, Gemini, OpenCode), skip this question and leave `task_isolation.worktree_per_task` at its default (`false`).
@@ -888,10 +958,10 @@ Add a row to the Step 8 table:
 
 ---
 
-## 3g. Present Settings (Batch 8: Task Tracking + Coding) (Pocock adoption AC13)
+## 3g. Present Settings (Batch 8: Task Tracking + Coding) (AC13)
 
 This batch captures the **task_tracking** backend and the **coding**
-defaults block introduced by the Pocock adoption (ST-10 apt:triage +
+defaults block introduced by adoption (ST-10 apt:triage +
 ST-3 apt:execute --tdd).
 
 Per ID-01 (Framework full-featured locally; backends are pluggable), the
@@ -977,7 +1047,7 @@ AskUserQuestion([
 
 Migration rule: any existing config WITHOUT a `task_tracking` or
 `coding` block gets defaults silently — NEVER error on a missing block.
-This is the migration path for projects that adopted Aperant pre-Pocock.
+This is the migration path for projects that adopted Aperant pre-vertical-slice.
 
 ### 3g.4 Review-Mode routing entry
 
@@ -1111,14 +1181,17 @@ The selective-edit pass through Batch 9 MUST respect the §1b dispatch — it do
 
 ## 4. Map Answers to Config
 
-**AUDIT-001 — file-routing contract for per-device fields (UPDATED 0.7.2):** the
-following five fields are PER-DEVICE and MUST land in `.aperant/config.local.json`
+**AUDIT-001 — file-routing contract for per-device fields (UPDATED 0.8.1 for FRAMEWORK-RFC-001):** the
+following PER-DEVICE fields MUST land in `.aperant/config.local.json`
 (gitignored), NOT the shared `.aperant/config.json`:
 - `verification.open_report` — covered in the "Auto-Open" mapping below.
 - `multi_model.cross_verification.tools` — covered in the "Cross-Verification" mapping below.
 - `preferences.date_format` — covered in the "Date Format" mapping below.
 - `preferences.time_format` — covered in the "Time Format" mapping below.
 - `preferences.quick_task_post_verify` — covered in apt-quick SKILL config block.
+- `spar.enabled` — covered in the "Sparring Auto-Fire" mapping below (FRAMEWORK-RFC-001).
+- `spar.partner` — covered in the "Sparring Auto-Fire" mapping below (FRAMEWORK-RFC-001).
+- `spar.hint` — covered in the "Sparring Auto-Fire" mapping below (FRAMEWORK-RFC-001).
 
 All other fields (including `verification.evidence_capture`,
 `multi_model.cross_verification.enabled`, `multi_model.video_review.*`,
@@ -1128,7 +1201,10 @@ All other fields (including `verification.evidence_capture`,
 Implementation: use the framework's `writeLocalConfigField(targetDir, dotPath, value)`
 helper from `packages/framework/src/cli/config/load.mjs` (or its shell-out
 equivalent via `apt-tools config write . --local --key <dotpath> --value <json>`)
-for the five fields above. NEVER hand-roll `JSON.parse(readFileSync('.aperant/config.json'))`
+for the per-device fields enumerated above (`verification.open_report`,
+`multi_model.cross_verification.tools`, `preferences.date_format`,
+`preferences.time_format`, `preferences.quick_task_post_verify`, and the
+three `spar.*` fields). NEVER hand-roll `JSON.parse(readFileSync('.aperant/config.json'))`
 followed by `writeFileSync('.aperant/config.json', ...)` for these fields — it
 will land per-device data in the shared file and re-introduce the
 shared-config trap AUDIT-001 was designed to close.
@@ -1176,6 +1252,18 @@ Map the user's selections to config values:
 - "Ask me" → `pr_review.suggest_after_ship: "ask"`
 - "Never" → `pr_review.suggest_after_ship: "never"`
 
+**Sparring Auto-Fire (FRAMEWORK-RFC-001):**
+- Phase 1 "No" → `spar.enabled: false`, ask Phase 3 (hint sub-picker)
+- Phase 1 "Yes" → `spar.enabled: true`, ask Phase 2 (partner picker)
+- Phase 2 "Codex" → `spar.partner: "codex"`
+- Phase 2 "Claude" → `spar.partner: "claude"`
+- Phase 2 "Gemini" → `spar.partner: "gemini"`
+- Phase 2 graceful-skip path (zero partners detected) → `spar.partner: null` (re-prompted inline by `/apt:run` gate handler when consent is on but partner is null)
+- Phase 3 "Yes" → `spar.hint: true`
+- Phase 3 "No" → `spar.hint: false` (or omit the field)
+
+**AUDIT-001 — all three fields are PER-DEVICE** and MUST land in `.aperant/config.local.json` via `writeLocalConfigField(targetDir, dotPath, value)` (or its shell-out equivalent `apt-tools config write . --local --key <dotpath> --value <json>`). Do NOT touch shared `.aperant/config.json` for any `spar.*` field. The AUDIT-001 routing block above already enumerates `spar.enabled`, `spar.partner`, `spar.hint` as per-device — this addendum is the call-site reference for future contributors.
+
 Note: task ids are slug-first since v0.6.6 — the date-format setting controls the trailing date component only.
 
 **Date Format:**
@@ -1211,7 +1299,7 @@ Note: task ids are slug-first since v0.6.6 — the date-format setting controls
 Write merged config to two files per AUDIT-001 routing (see Step 4 block):
 
 - Shared `.aperant/config.json` — all project policy values (the bulk of the answers).
-- Per-device `.aperant/config.local.json` — the five AUDIT-001 fields enumerated in Step 4.
+- Per-device `.aperant/config.local.json` — the AUDIT-001 per-device fields enumerated in Step 4 (5 original + 3 `spar.*` fields per FRAMEWORK-RFC-001).
 
 ```bash
 mkdir -p .aperant
@@ -1302,6 +1390,7 @@ Display:
 | Auto Branch          | {Yes/No}                     |
 | Code Review          | {Yes/No}                     |
 | TDD Iron Law         | {Yes/No}                     |
+| Sparring Auto-Fire   | {Off / On (codex), On (claude), On (gemini)} (hint: {Yes/No}) |
 | Date Format          | {DD-MM-YY / MM-DD-YY / YY-MM-DD} |
 | Time Format          | {24h / 12h}                  |
 | Task Index           | {Yes/No}                     |