@aperant/framework 0.8.1 → 0.8.4

package/skills/apt-plan/SKILL.md

@@ -19,7 +19,7 @@ execution_modes:
   - plan-only
   - research
 allowed-tools: "Read, Grep, Glob, Write, Bash, WebSearch"
-argument-hint: "apt:plan [task description]"
+argument-hint: "apt:plan [task description] [--spar]"
 gates: 
   - constitution-read
   - constitution-coverage
@@ -33,7 +33,7 @@ Analyze a task, assess complexity, investigate the codebase, and produce a struc
 - **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
 - **Prompts directory:** Installed alongside this command in the @aperant/framework package
 - **Constitution:** Read `AGENTS.md` in the project root if it exists — it defines project principles, tech stack, and conventions that override defaults
-- **Task directory:** `{task_dir}` — passed from the router. All plan artifacts (spec.md, implementation_plan.json) are written here, NOT to project root.
+- **Task directory:** `{task_dir}` — passed from the router as an absolute main-repo path. All plan artifacts (spec.md, implementation_plan.json) are written here, NOT to project root and NOT to a worktree-local `.aperant/tasks/` directory.
 </your_environment>
 
 <state_files>
@@ -122,9 +122,9 @@ If `{task_dir}/design.md` exists (emitted by a prior `/apt:design` run), load it
 
 ## 5. Write Specification
 
-Create `spec.md` in the task directory (`{task_dir}` passed from the router, e.g. `.aperant/tasks/{task-id}/spec.md`).
+Create `spec.md` in the task directory (`{task_dir}` passed from the router, e.g. `/abs/main/repo/.aperant/tasks/{task-id}/spec.md`). Do not use a relative `.aperant/tasks/{task-id}/spec.md` path when the agent is running in a worktree.
 
-**Content format branches on track (Fast Path Guarantee — Pocock adoption ID-05):**
+**Content format branches on track (Fast Path Guarantee — ID-05):**
 
 ### 5.A. QUICK track — legacy 4-section format (hard-exempt from PRD upgrade)
 
@@ -309,7 +309,7 @@ When `status: warn` (non-blocking enforcement) and the user is in **auto mode**
 
 Create `implementation_plan.json` in the task directory (`{task_dir}/implementation_plan.json`).
 
-**Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).**
+**Subtask schema branches on track.**
 
 ### 6.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
 
@@ -454,6 +454,24 @@ Plan created:
 Next: /apt:execute
 ```
 
+### 9b. --spar flag (FRAMEWORK-RFC-001)
+
+If `$ARGUMENTS` contained `--spar`, dispatch `/apt:spar` against the
+just-written `spec.md` + `implementation_plan.json` before reporting Next.
+
+Topic frame: the §1 Scope paragraph from `spec.md` (1-2 sentences). Same
+`--timeout-ms 120000` pipeline-mode budget and NO `--rounds` flag (per
+FRAMEWORK-BUG-038 — pipeline gates always defer to the skill default).
+When merged-config `spar.partner` is set, append `--with <partner>`.
+
+```
+/apt:spar --timeout-ms 120000 [--with <partner>] <topic-frame-from-spec.md-§Scope>
+```
+
+After spar returns, append the termination headline + Layer 2 path
+(`.aperant/spar/<slug>-<ts>.md`) into the report output so the user can
+review findings before invoking `/apt:execute`.
+
 ### 9a. Mode-Aware Compact Suggestion (Human-in-the-Loop Only)
 
 Decide whether to show a compact suggestion by reading the **per-task autonomy** from state — not the global default, because the router asks per-task and stores the answer on the task record.

package/skills/apt-plan/adapters/conductor.md

@@ -42,7 +42,7 @@ auto-stamped `terminal_id`.
 
 This replaces the earlier markdown-discipline emit step. The earlier
 step was correctly skipped on QUICK / SIMPLE classified tasks (Fast
-Path Guarantee, Pocock adoption ID-05) — moving the emit to a
+Path Guarantee, ID-05) — moving the emit to a
 framework postcondition makes it work uniformly across QUICK, STANDARD,
 DEEP, and COMPLEX without violating the Fast Path Guarantee.
 

package/skills/apt-planner.md

@@ -59,7 +59,7 @@ For STANDARD and COMPLEX tasks:
 
 ## 4. Write Specification
 
-Content format branches on track (Pocock adoption ID-05, Fast Path Guarantee).
+Content format branches on track.
 
 ### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
 

package/skills/apt-prototype/LOGIC.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/LOGIC.md
-Licensed under MIT. Modifications: scoped to terminal-app prototypes
-that validate state machines, protocols, and control flow. Aligned with
-the 5 universal rules in apt-prototype/SKILL.md.
--->
-
 # LOGIC branch — Terminal app for state-machine validation
 
 When the user's question is about **behavior**, the prototype is a

package/skills/apt-prototype/SKILL.md

@@ -29,7 +29,7 @@ planning artifact, NOT a feature, and NOT something to merge. The output
 is a single-command-runnable prototype that lets the user feel whether
 the question's answer is "yes" or "no", then gets thrown away.
 
-**Pocock adoption attribution.** Discipline ported from Matt Pocock's
+**Aperant adoption attribution.** Discipline ported from 's
 MIT-licensed `prototype` skill. Routes between two branches by
 question-type; the UI branch delegates to Aperant's existing
 `/apt:mockup` skill for HTML+Tailwind variants. The LOGIC branch and
@@ -70,7 +70,7 @@ If the question is genuinely ambiguous, ask ONE clarifying question
 ("are you asking about behavior or appearance?") — do NOT enter a long
 interview.
 
-## The 5 Universal Rules (Pocock discipline, applies to both branches)
+## The 5 Universal Rules (Aperant discipline, applies to both branches)
 
 These five rules apply to EVERY prototype this skill produces. They are
 load-bearing — violating them collapses the prototype into ceremony
@@ -109,7 +109,7 @@ disguised as a question.
 When the question is about behavior / control flow / state machines /
 protocols:
 
-1. Read `LOGIC.md` for the discipline (ported from Pocock's
+1. Read `LOGIC.md` for the discipline (ported from 's
    `prototype/LOGIC.md` with MIT attribution).
 2. Write ONE file (e.g., `prototype.mjs`, `prototype.ts`, or
    `prototype.py`) that:
@@ -126,7 +126,7 @@ protocols:
 
 When the question is about layout / aesthetics / flow / discoverability:
 
-1. Read `UI.md` for the discipline (ported from Pocock's
+1. Read `UI.md` for the discipline (ported from 's
    `prototype/UI.md` with MIT attribution).
 2. Invoke `/apt:mockup --variants 3` as a sub-step. apt:mockup already
    enforces the UI-specific universal rules (zero-dep Tailwind CDN, no

package/skills/apt-prototype/UI.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/UI.md
-Licensed under MIT. Modifications: routed through Aperant's existing
-apt:mockup skill rather than a freestanding HTML+Tailwind generator;
-aligned with the 5 universal rules in apt-prototype/SKILL.md.
--->
-
 # UI branch — Delegates to apt:mockup
 
 When the user's question is about **appearance / layout / flow /

package/skills/apt-quick/SKILL.md

@@ -52,7 +52,37 @@ Execute a small task quickly without full pipeline overhead. For small fixes, do
 
 Extract the task description from `$ARGUMENTS`.
 
-Generate a task ID: `quick-{YYYYMMDD}-{short-slug}` (e.g., `quick-20260410-fix-typo`).
+### 1a. Resolve canonical task id (idempotent)
+
+QUICK now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile. The body owns idempotency because `apt-tools task create` does NOT guard against existing ids (see spec §3 R8).
+
+Two invocation paths converge here:
+
+- **Router path** (`/apt` → `/apt:quick`): the router has already called `task create` and injected `task_id` into your skill context.
+- **Direct path** (`/apt:quick foo`): no `task_id` in context — you create one now.
+
+Sequence:
+
+1. **If `task_id` is present in skill context** (router path):
+   ```bash
+   apt-tools task get . --id {task_id}
+   ```
+   - If exit 0 AND the returned record has `track === "QUICK"` → reuse, skip the create call.
+   - Else (record missing OR wrong track) → call:
+     ```bash
+     apt-tools task create . --description "$ARGUMENTS" --track QUICK --id {task_id}
+     ```
+     Parse `task_id` from the returned envelope (it will match the id you passed).
+
+2. **If no `task_id` in skill context** (direct path):
+   ```bash
+   apt-tools task create . --description "$ARGUMENTS" --track QUICK
+   ```
+   Parse the generated `task_id` from the envelope — it will be the canonical `{slug}_YY-MM-DD` shape.
+
+The task id is now canonical (no more `quick-YYYYMMDD-*` invention). `QuickTaskSchema` accepts both the canonical `{slug}_YY-MM-DD` form and the legacy `quick-YYYYMMDD-{slug}` form for back-compat with already-shipped task records on disk.
+
+### 1b. Create QUICK working directory
 
 ```bash
 mkdir -p .aperant/quick/{task-id}

package/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/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:**
 
 ```