@aperant/framework 0.8.1 → 0.8.6

package/skills/apt-research/appendices/domain-tools.md

@@ -0,0 +1,236 @@
+# Domain Tools, Gates, and Output Templates
+
+> Per-domain tool surface, reasoning gates, and synthesis output template.
+> Load when domain has been detected (Step 1d) or when synthesizing
+> (Step 10).
+
+The four domains are detected from the user's question in Step 1d and
+recorded as immutable in `research-spec.md ## Domain`. The detected
+domain determines which tools each `apt-researcher` role gets, which
+reasoning steps are enabled, and what shape the final `RESEARCH.md`
+output takes.
+
+## Domain detection signals
+
+| Domain | Signals | Examples |
+|---|---|---|
+| **mechanistic** | physics, math, distributed systems, algorithms, deterministic engineering systems with provable behavior | "how does Raft handle leader election", "what does axle stiffness do to chassis dynamics", "is this algorithm O(log n)" |
+| **empirical** | medicine, biology, nutrition, psychology, public-health, social science, anything where human variation dominates and replication matters | "does intermittent fasting cause muscle loss", "what's the effect of X on Y in older adults", "is supplement X effective" |
+| **strategic** | tool/vendor comparison, market analysis, license/contract evaluation, anything where the answer depends on vendor disclosure + ecosystem health | "best embedded DB for offline-first 2026", "should we pick Vitest or Bun test", "is Turso safe to depend on" |
+| **general** | catch-all when none of the above fit; usually broad knowledge questions or framing-questions | "what is consensus in distributed systems", "explain bitemporal databases" |
+
+Ambiguous question → `general`. The user can override with explicit
+flag (future: `--domain <name>`); for v1, signal-based detection is
+authoritative.
+
+## Per-domain tool surface
+
+Each `apt-researcher` role gets the base tools (Read, Grep, Glob,
+WebSearch, WebFetch, Context7) PLUS the domain extras below.
+
+### mechanistic
+
+| Tool | How invoked | Used by |
+|---|---|---|
+| arxiv search | `curl "http://export.arxiv.org/api/query?search_query=..."` | Retriever |
+| PDF reader | `curl -o /tmp/x.pdf {url} && pdftotext /tmp/x.pdf -` | Builder, Skeptic, Retriever |
+| Wolfram Alpha (if API key set) | `curl "https://api.wolframalpha.com/v2/query?..."` | Builder, Skeptic |
+
+First-principles derivation: **ENABLED**. Builder and Skeptic may
+produce derivations grounded in domain theory. Judge accepts them
+into `claims.json` at `source_tier: derived-theory` (weight 0.6
+in `uncertainty` formula).
+
+### empirical
+
+| Tool | How invoked | Used by |
+|---|---|---|
+| Crossref DOI resolve | `curl "https://api.crossref.org/works/{doi}"` | Retriever, citation audit |
+| PubMed E-utilities | `curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=..."` | Retriever |
+| PMC full-text fetch | `curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pmc&id={pmcid}"` | Builder, Skeptic |
+| Europe PMC fallback | `curl "https://www.ebi.ac.uk/europepmc/webservices/rest/search?query=..."` | Retriever |
+
+First-principles derivation: **DEMOTED**. Builder/Skeptic may invoke
+theory (mechanism, leucine threshold, etc.) but Judge demotes the
+output to `source_tier: hypothesis` (weight 0.1). Hypotheses cannot
+reach `confidence: high` regardless of how compelling the reasoning
+sounds — only empirical evidence at `tier ≥ independent-test` can
+elevate a claim to `high`.
+
+Citation audit is **MANDATORY** every iteration (not every N) in
+empirical domains. Every new citation MUST be DOI/PMID-verified
+via Crossref or NCBI before promotion to `sources.json`. Failures
+go straight to `suspect-citations.md` and the claim depending on
+them is downgraded.
+
+### strategic
+
+| Tool | How invoked | Used by |
+|---|---|---|
+| GitHub releases | `gh release list -R {owner}/{repo} --limit 20` | Retriever |
+| GitHub code search | `gh search code "..." --limit 20` | Retriever, Skeptic |
+| License fetch | `gh api repos/{owner}/{repo}/license` or WebFetch raw LICENSE | Retriever |
+| Changelog fetch | WebFetch `CHANGELOG.md` or `gh api repos/{owner}/{repo}/contents/CHANGELOG.md` | Retriever |
+| Package metadata | `npm view {pkg} --json` / `pip show {pkg} --verbose` / `cargo search {pkg}` | Retriever |
+
+First-principles derivation: **DISABLED**. "Derive whether libSQL is
+stable from theory" is nonsense. Builder is instructed to synthesize
+from sources only. If Builder produces a derivation-shaped output,
+Judge rejects it with `## reason: derivation invalid in strategic domain`.
+
+Vendor-only evidence is a spar trigger (see `overnight-loop.md`
+§spar-triggers). Strategic domain treats vendor-doc as
+`source_tier: vendor-doc` (weight 0.5) — NOT a high tier.
+
+### general
+
+Default tool surface. First-principles is **SOFT-ENABLED with
+hypothesis demotion** — Builder/Skeptic may derive but Judge
+demotes to `hypothesis` until empirical or primary-doc evidence
+elevates the claim.
+
+## Output gates (Step 10 — synthesis)
+
+The synthesis template in `RESEARCH.md` has a common core (defined in
+the main SKILL.md `## 10. Synthesize`) PLUS domain-specific sections.
+
+### mechanistic
+
+Add:
+
+```markdown
+## First-principles derivations
+
+For each derivation accepted into the claim graph at
+`source_tier: derived-theory`:
+
+- **{derivation name}** — claim {C-id}
+  - Premises: {what we assumed}
+  - Steps: {compact derivation}
+  - Cross-check vs sources: {which sources confirm/contradict the derivation}
+  - Failure mode: {when does this derivation break?}
+```
+
+If a derivation contradicts an empirical source, the derivation is
+flagged as bounded — Judge MUST note the boundary condition.
+
+### empirical
+
+Add (mandatory, non-negotiable):
+
+```markdown
+## Not medical / financial / safety advice
+
+This research synthesis is informational. It is not a substitute for
+professional advice from a licensed clinician, financial advisor, or
+safety expert. Individual circumstances vary; outcomes that apply to
+populations may not apply to any specific person.
+
+## What this CAN'T tell you
+
+- {Specific question the evidence does not address}
+- {Specific population the evidence does not cover}
+- {Specific interaction or confounder the evidence cannot resolve}
+
+## Quality of evidence
+
+For each cited study supporting a critical claim:
+
+| Source | Design | n | Peer-reviewed | Replicated | Notes |
+|---|---|---|---|---|---|
+| {S-id} | {RCT/cohort/meta} | {n} | {yes/no} | {yes/no/unknown} | {note} |
+```
+
+Imperatives in the synthesis prose ("you should…", "do X", "avoid Y")
+are STRIPPED by Judge. Empirical synthesis uses descriptive language
+("evidence suggests…", "in the populations studied…").
+
+If the synthesis would recommend a course of action affecting health,
+finance, or safety, Judge inserts: "**Discuss with a qualified
+professional before acting on this synthesis.**"
+
+### strategic
+
+Add (mandatory):
+
+```markdown
+## Conditional-tree recommendation
+
+```
+if {decision-relevant condition A}:
+  → recommend {Option X}
+  → reason: {1-line}
+elif {decision-relevant condition B}:
+  → recommend {Option Y}
+  → reason: {1-line}
+else:
+  → no clear winner — {what's the unresolved question}
+```
+
+## Vendor-claim conflicts
+
+For each option where evidence is vendor-only or vendors disagree:
+
+- **{Option}** — {dimension}
+  - Vendor claim: {what the vendor says}
+  - Independent confirmation: {available | NOT AVAILABLE}
+  - Risk if vendor claim is wrong: {what breaks}
+
+## Decision blockers
+
+Questions only the user can answer that change the recommendation:
+
+- {Question} — affects: {which option(s)}
+```
+
+Single-winner output is **REJECTED** by Judge when evidence is
+vendor-only across the deciding dimension. The skill produces a
+conditional tree or explicit "no clear winner" — never a confident
+universal recommendation in those cases.
+
+### general
+
+Add:
+
+```markdown
+## Outstanding gaps
+
+- {Open question that the synthesis does not close}
+
+## Recommended next reads
+
+- {Source} — covers {what aspect}
+```
+
+## Mode-specific additions (orthogonal to domain)
+
+Applied AFTER the domain gates. From the main SKILL.md `## 10.
+Synthesize`, repeated here for the per-domain reader:
+
+- **UNDERSTAND** → mental model section with mechanism + analogy
+- **VERIFY** → verdict line (`confirmed | partially confirmed | false |
+  contested | unknown`)
+- **SOLVE** → candidate approaches table + `## Falsification status`.
+  For code-domain SOLVE: blocks `CONVERGED` if no falsification was
+  run (test / simulator / model-checker / formal-method sketch).
+  Force STALLED with `## Cannot certify without falsification` and
+  enumerate what falsification harness would be needed.
+- **COMPARE** → dimensions × options matrix + per-cell evidence
+  pointers (conditional-tree comes from the strategic domain gate)
+
+## Tool-surface fallbacks
+
+If a domain tool is unavailable in the current environment (e.g.
+`gh` not installed, no network access for Crossref), the affected
+role MUST report this in its output:
+
+```
+## Tool unavailable
+- {tool name}: {why unavailable}
+- Impact on this iteration: {what could not be done}
+```
+
+Judge records the missing capability in `iteration-log.md` and adjusts
+stop-state evaluation: a STALLED verdict resulting from missing tools
+gets `## Cannot resolve without` annotated with "tool {X} unavailable
+in this environment". The user can resolve and `--resume`.

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