@aperant/framework 0.8.0 → 0.8.4

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

@@ -41,8 +41,9 @@ you must follow when classifying.
 - **Config:** `.aperant/config.json` — project preferences
 - **State:** `.aperant/state.json` — execution state
 - **Task directories:** `.aperant/tasks/{task-id}/` — each task gets isolated artifacts
-- **Codex repo skills:** `.agents/skills/apt*/` — native Codex discovery surface installed by `apt-tools init`
-- **Claude agents:** `.claude/agents/apt-*.md` — specialized agent definitions for heavy workflows
+- **Claude surface:** `.claude/skills/`, `.claude/agents/`
+- **Codex surface:** `.codex/commands/`, `.codex/agents/`
+- **Pi surface:** `.pi/prompts/`, `.pi/skills/`
 </your_environment>
 
 <mandatory_first_step>
@@ -385,18 +386,27 @@ Parse `task_id`, `task_dir`, and (if present) `worktree.worktree_path` / `worktr
 Important nuances:
 - `task_dir` is an **absolute path** under the main repo's `.aperant/tasks/{task-id}/`. All spec/plan/progress artifacts live there and are shared across worktrees.
 - `apt-tools` commands still receive the **project root** as `<project-dir>` — they coordinate state through the main repo's `.aperant/`. The worktree only affects *code editing* cwd.
-- When spawning an agent, set its `cwd` (or prefix its Bash calls with `cd {worktree_path} &&`) to the worktree. Pass `worktree_path` in the agent's context so it knows where it is.
+- When spawning an agent, set its `cwd` (or prefix its Bash calls with `cd {worktree_path} &&`) to the worktree for code reads/edits. Pass `worktree_path` in the agent's context so it knows where code work happens.
+- Planner artifact safety: do **not** spawn `apt-planner` with host-level worktree isolation that gives it a separate copied repo. The planner must write `spec.md` and `implementation_plan.json` to the absolute main-repo `task_dir` from `task create`; `.aperant/tasks/**` is gitignored, so artifacts written under a disposable worktree can be invisible to git and lost when that worktree is cleaned.
 - If no `worktree` block is returned, proceed in the project root as before.
 
 ### Step 3: Spawn Planner Agent
 
 **If `spawn_agent` is true (STANDARD/DEEP):**
 
-Print phase marker BEFORE spawning:
+Print the phase rail BEFORE spawning. Render the panel verbatim — branch glyphs `┌─ │ └─`, status glyphs `✓` (done) / `●` (active) / `○` (pending), one phase per row, inline metrics on completed rows when available:
+
 ```
 [APT] Phase 1/N — Planning (spawning apt-planner agent)
+┌─ Phase rail: {short task name} ───────────────────
+│  Phase 1 Plan       ●  spawning apt-planner
+│  Phase 2 Execute    ○
+│  Phase 3 Verify     ○
+│  Phase 4 Review     ○
+└───────────────────────────────────────────────────
 ```
-(N = total pipeline phases: e.g. plan+execute+verify+review = 4, discuss+plan+… = 5)
+
+(N = total pipeline phases: e.g. plan+execute+verify+review = 4, discuss+plan+… = 5. Keep the `[APT] Phase X/N` header line — it's the backward-compat marker that external grep tooling relies on. The rail panel sits directly below it.)
 
 You **MUST** use the `Task` tool to spawn `apt-planner` — do NOT write
 `spec.md` or `implementation_plan.json` inline using the `Write` tool. The
@@ -413,8 +423,9 @@ Spawn `apt-planner` via Task tool with context:
 ```
 Task: {task_description}
 Task ID: {task_id}
-Task Dir: {task_dir}
+Task Dir: {task_dir}  # absolute path under the main repo, not under worktree_path
 Track: {track}
+Worktree Path: {worktree_path or "none"}
 
 <files_to_read>
 - CLAUDE.md (if exists)
@@ -422,7 +433,7 @@ Track: {track}
 - Any brainstorm notes at .aperant/context/notes/{task_id}-brainstorm.md
 </files_to_read>
 
-Write spec.md and implementation_plan.json to {task_dir}/
+Write spec.md and implementation_plan.json to {task_dir}/. Do not write plan artifacts to `{worktree_path}/.aperant/tasks/...` or any relative `.aperant/tasks/...` path.
 ```
 
 After the agent returns, emit a token running-total line:
@@ -444,9 +455,32 @@ The user's chosen option has a `pipeline` array (e.g. `["plan", "execute", "veri
 **execution_mode = "auto":**
 Auto-chain without waiting. STANDARD and DEEP auto pipelines both follow Plan → execute → verify → review (DEEP additionally leads with discuss).
 
-Each phase transition MUST emit a status marker for visibility:
+Each phase transition MUST emit a status marker AND re-render the phase rail showing the updated state for ALL phases. The rail is the user's primary signal — render it verbatim, do not summarize or skip.
+
 ```
 [APT] Phase {current}/{total} — {name} (spawning {agent})
+┌─ Phase rail: {short task name} ───────────────────
+│  Phase 1 Plan       ✓  {N} subtasks
+│  Phase 2 Execute    ●  spawning apt-executor
+│  Phase 3 Verify     ○
+│  Phase 4 Review     ○
+└───────────────────────────────────────────────────
+```
+
+Metric conventions per phase row (omit metrics on `○` pending rows):
+- **Plan ✓**: `N subtasks`
+- **Execute ✓**: `N commits, K tests` (or `N/M subtasks` mid-execute on `●`)
+- **Verify ✓**: `APPROVED a/b/c/d` (completeness/correctness/quality/coverage)
+- **Review ✓**: `APPROVE a/b/c/d/e/f, K findings fixed` (or `request-changes, K open`)
+- **Ship ✓**: `PR #N` (the SHIPPED collapsed variant — see below)
+
+When ship completes (lifecycle `shipped-pending-merge` + PR URL exists), collapse to the SHIPPED variant:
+
+```
+┌─ {short task name} ────────────────────── ✅ SHIPPED
+│  Plan ✓ Execute ✓ Verify ✓ Review ✓ Ship ✓
+│  PR #{N}: {url}
+└───────────────────────────────────────────────────
 ```
 
 Full auto-chain sequence (STANDARD = 4 phases, DEEP = 5 phases):
@@ -459,6 +493,42 @@ Full auto-chain sequence (STANDARD = 4 phases, DEEP = 5 phases):
 After EACH agent returns, emit the token running-total line (same pattern
 as Step 3: `tokens tally` then print `[APT] Tokens: input+output = total`).
 
+#### Consent-driven --spar-gates auto-inject (FRAMEWORK-RFC-001)
+
+The route envelope carries the consent signal deterministically — do NOT
+re-read `.aperant/config.local.json` from prompt-space. Two envelope fields
+drive the decision, both emitted by `route.mjs` per spec §4.10:
+
+1. **`envelope.spar_inject_gates`** — present only on the flag-override path
+   (explicit `--quick` / `--deep` / `--debug`) when consent is on AND the
+   user did NOT pass an explicit `--spar-gates`. Value is `"plan"` (STANDARD)
+   or `"plan,execute"` (DEEP). When set, append `--spar-gates <value>` to
+   the chained `/apt:run` invocation. **Do NOT recompute** — the deterministic
+   contract lives in code, not prompt-space.
+
+2. **`envelope.spar_consent`** — present on the host-LLM classify path.
+   Shape: `{ enabled: boolean, partner: string|null, user_passed_explicit_gates: boolean }`.
+   After you (the host model) pick a track via Step 0c:
+   - **Track === QUICK or DEBUG: do NOT inject.** QUICK is Fast-Path-exempt
+     (CLAUDE.md Fast Path Guarantee); DEBUG produces no spec/plan to spar
+     against.
+   - **Track === STANDARD** AND `spar_consent.enabled === true` AND
+     `spar_consent.user_passed_explicit_gates === false`: append
+     `--spar-gates plan` to the `/apt:run` invocation.
+   - **Track === DEEP** AND `spar_consent.enabled === true` AND
+     `spar_consent.user_passed_explicit_gates === false`: append
+     `--spar-gates plan,execute` to the `/apt:run` invocation.
+   - `user_passed_explicit_gates === true`: the user already supplied
+     `--spar-gates` — do NOT double-inject. Their flag is already in the
+     dispatched invocation.
+
+If `envelope.spar_consent` is absent (consent never configured) AND
+`envelope.spar_inject_gates` is absent, do NOT inject. The signal is
+**deterministic** — Step 4 reads ONLY the envelope fields above. Do NOT
+re-read `.aperant/config.local.json` from prompt-space; the
+consent-resolution helper is wired into `route.mjs` and the envelope is
+the canonical contract. The structural test grep-locks this invariant.
+
 **execution_mode = "step" or "research":**
 After each stage in the pipeline, show result and ask before proceeding:
 ```

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

@@ -0,0 +1,64 @@
+---
+name: apt:caveman
+description: "Ultra-compressed communication mode — toggle terse 'smart caveman' output to cut token usage ~75% while keeping full technical accuracy"
+apt-skill-version: {{APT_VERSION}}
+stage: ops
+intent: configure
+when_to_use: "The user invokes /apt:caveman, or says 'caveman mode', 'talk like caveman', 'be brief', 'less tokens'. Toggles a persistent terse output mode. Off with 'stop caveman' or 'normal mode'."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_execution_mode: auto
+execution_modes:
+  - auto
+allowed-tools: ""
+argument-hint: "apt:caveman"
+gates: []
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+### Examples
+
+**"Why React component re-render?"**
+
+> Inline obj prop -> new ref -> re-render. `useMemo`.
+
+**"Explain database connection pooling."**
+
+> Pool = reuse DB conn. Skip handshake -> fast under load.
+
+## Auto-Clarity Exception
+
+Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
+
+Example — destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Caveman resume. Verify backup exist first.
+
+## Boundaries
+
+Code, commits, PRs: write normal (full sentences in commit bodies / PR descriptions). Only conversational output is compressed. `stop caveman` / `normal mode` reverts.

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

@@ -22,7 +22,7 @@ gates: []
 <objective>
 Debug an issue using the scientific method: observe symptoms, form hypotheses, test them systematically, and reach a conclusion. State persists across context resets via `.aperant/debug/{session-id}/DEBUG.md`.
 
-**Diagnose-discipline posture loader (Pocock adoption AC10).** You MUST
+**Diagnose-discipline posture loader.** You MUST
 load `appendices/diagnose-discipline.md` into reasoning context at
 session start. It carries the 6-phase loop (Reproduce → Minimise →
 Hypothesise → Instrument → Fix → Regression-test) and the **Phase-1
@@ -61,12 +61,44 @@ reproduction, so loading this appendix is non-trivial.
 ## 1. Initialize or Resume Session
 
 Parse `$ARGUMENTS`:
-- **New session:** Generate session ID from timestamp (`debug-YYYYMMDD-HHmm`)
-- **`--resume <session-id>`:** Read existing `.aperant/debug/{session-id}/DEBUG.md` and continue from last state
-- **`--resume` (no id):** Find the most recent session in `.aperant/debug/` and resume it
+- **New session:** resolve a canonical task id (see 1a below), then use it as the `{session-id}` for the debug working directory.
+- **`--resume <session-id>`:** Read existing `.aperant/debug/{session-id}/DEBUG.md` and continue from last state. Skip Section 1a — the session id is already canonical.
+- **`--resume` (no id):** Find the most recent session in `.aperant/debug/` and resume it. Skip Section 1a.
 
 If resuming, read DEBUG.md and skip to the current phase (observe/hypothesize/test/conclude).
 
+### 1a. Resolve canonical task id (idempotent — new sessions only)
+
+DEBUG now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile once the fix is committed. 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:debug`): the router has already called `task create` and injected `task_id` into your skill context.
+- **Direct path** (`/apt:debug 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 === "DEBUG"` → reuse, skip the create call. Adopt `task_id` as `{session-id}`.
+   - Else (record missing OR wrong track) → call:
+     ```bash
+     apt-tools task create . --description "$ARGUMENTS" --track DEBUG --id {task_id}
+     ```
+     Adopt the id as `{session-id}`.
+
+2. **If no `task_id` in skill context** (direct path):
+   ```bash
+   apt-tools task create . --description "$ARGUMENTS" --track DEBUG
+   ```
+   Parse the generated `task_id` from the envelope and adopt it as `{session-id}`. The canonical id replaces the legacy `debug-YYYYMMDD-HHmm` form.
+
+The debug working dir at `.aperant/debug/{session-id}/` stays — that working artifact is preserved (per spec §3 R7). The canonical task record at `.aperant/tasks/{task-id}/` is created in parallel by `task create`, and both share the same id.
+
+### 1b. Create debug working directory
+
 ```bash
 mkdir -p .aperant/debug/{session-id}
 mkdir -p .aperant/debug/{session-id}/checkpoints

package/dist/plugin/skills/apt-debug/appendices/diagnose-discipline.md

@@ -1,12 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose
-Licensed under MIT. Modifications: ported as an apt:debug posture loader
-so the 6-phase loop attaches to the existing 5-phase apt:debug body
-without forking apt:debug's control flow. Aligned with apt:debug's
-DEBUG.md state file and checkpoint conventions.
--->
-
 # Diagnose Discipline — apt:debug posture loader (6-phase loop)
 
 This appendix loads into `apt:debug`'s reasoning context as a posture
@@ -15,7 +6,7 @@ upgrade. The existing apt:debug body has 5 phases (Observe → Hypothesize
 symptom-gathering with reproduction. Open question #1 was verified — the
 gap is real, the appendix is non-trivial.
 
-This appendix carries the 6-phase Pocock discipline. The skill body
+This appendix carries the 6-phase Aperant discipline. The skill body
 loads it and uses Phase 1 (Reproduce) as a **hard prerequisite** before
 advancing from Observe to Hypothesize.
 
@@ -82,7 +73,7 @@ run on demand to trigger the failure.
 
 These are different mental modes. Minimise asks "what's the smallest
 thing that still fails?" — a reductive activity. Hypothesise asks
-"WHY does it fail?" — an explanatory activity. Pocock's discipline
+"WHY does it fail?" — an explanatory activity. the discipline
 separates them because skipping Phase 2 and going straight from "I can
 repro" to "here's why" tends to anchor on the first plausible cause
 and miss alternatives.

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

@@ -47,7 +47,7 @@ These are two postures of the same skill, not two different skills. The
 intent-detection step below decides which one to enter — same file, same
 artifact layout, different section populated.
 
-**Decision-lock posture loader (Pocock adoption ID-02 + ID-04 — AC11).**
+**Decision-lock posture loader (ID-02 + ID-04 — AC11).**
 When entering decision-lock posture, you MUST load
 `appendices/grill-discipline.md` into reasoning context. It carries the
 validated 100-token reframe sentence ("Your job is not to emit a plan;
@@ -60,7 +60,7 @@ source for the autonomy-aware rule; downstream skills (`apt:improve`,
 `apt:triage`) reference it rather than re-stating the policy. Brainstorm
 posture does NOT load this appendix.
 
-**Brainstorm posture zoom-out helper (Pocock adoption AC6 + AC11).**
+**Brainstorm posture zoom-out helper (AC6 + AC11).**
 When in brainstorm posture and the user's turn contains a zoom-out
 trigger phrase ("give me a broader picture", "I'm lost in this area",
 "explain how this fits", "what's the surrounding architecture", "zoom
@@ -565,9 +565,9 @@ Review-Auto is Auto Mode **plus one human checkpoint at the batch end**. It does
 
 Do NOT introduce per-decision staging ("show me D-01, wait, show me D-02, wait...") — that collapses review-auto into spaced interactive mode and defeats the point of joint reasoning up front. Do NOT skip the pause ("autonomy is high, let's just write it") — that collapses review-auto into auto. The one pause at the end is the whole identity of this mode.
 
-## 6.5. Grill Mode (`--grill` flag — Pocock `grill-with-docs` overlay)
+## 6.5. Grill Mode (`--grill` flag — Aperant `grill-with-docs` overlay)
 
-**Activate when:** the user invoked the skill with `--grill`. This is an **overlay**, not a mode — it stacks on top of whichever Section 6 mode is active (Interactive by default; combine with `--auto` etc. as desired). The overlay does two things: (1) it applies Pocock's 4 grill moves during decision resolution; (2) it fires inline writes to CONTEXT.md and ADRs as terms resolve and decisions pass the Nygard 3-gate.
+**Activate when:** the user invoked the skill with `--grill`. This is an **overlay**, not a mode — it stacks on top of whichever Section 6 mode is active (Interactive by default; combine with `--auto` etc. as desired). The overlay does two things: (1) it applies the 4 grill moves during decision resolution; (2) it fires inline writes to CONTEXT.md and ADRs as terms resolve and decisions pass the Nygard 3-gate.
 
 The discipline this overlay loads is already in [`appendices/grill-discipline.md`](./appendices/grill-discipline.md) — re-read the reframe sentence and the autonomy degradation table before each grill turn. **Do NOT duplicate that content here.** What follows is only the moves + writer-call instructions specific to the overlay.
 

package/dist/plugin/skills/apt-discuss/appendices/grill-discipline.md

@@ -1,12 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs
-Licensed under MIT. Modifications: ported as an apt:discuss posture loader,
-extended with the validated 100-token reframe sentence and the
-autonomy-aware degradation table from the Pocock adoption brainstorm
-(Architectural principles to lock §2).
--->
-
 # Grill Discipline — apt:discuss posture loader
 
 This appendix loads into `apt:discuss`'s reasoning context whenever the
@@ -15,7 +6,7 @@ skill is invoked in decision-lock posture (or as a sub-step inside
 artifacts:
 
 1. The 100-token **reframe sentence** validated by the V2 grill-comparison
-   experiment (43/44 vs 38/44 blind-judge score against Pocock's verbatim
+   experiment (43/44 vs 38/44 blind-judge score against the verbatim
    `grill-with-docs`).
 2. The **autonomy-aware degradation table** that prevents full-auto runs
    from grinding to a halt grilling every gray area.
@@ -98,7 +89,7 @@ where the user has a concrete task with implicit gray areas). The
 options) does NOT load this appendix; brainstorm has its own posture
 encoded in apt:discuss's `<objective>` block.
 
-`apt:zoom-out` (a sibling skill, also Pocock-adopted) does NOT load
+`apt:zoom-out` (a sibling skill, also adopted) does NOT load
 this appendix. Zoom-out is descriptive ("show me the broader picture"),
 not normative ("lock this decision"). Loading grill-discipline there
 would mis-fire the reframe sentence on a read-only operation.

package/dist/plugin/skills/apt-discuss/appendices/zoom-out-helper.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/zoom-out
-Licensed under MIT. Modifications: ported as a loaded-helper for apt:discuss
-brainstorm mode so the discipline activates without spawning the full
-apt:zoom-out skill (the latter is a router-invocable verb on its own).
--->
-
 # Zoom-Out Helper — apt:discuss brainstorm mode loaded helper
 
 This appendix loads into `apt:discuss` brainstorm mode when the user's

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

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Read, Write, Edit, Bash, Grep, Glob"
-argument-hint: "apt:execute [--continue] [--subtask <id>] [--parallel] [--wave <N>] [--tdd] [--no-tdd]"
+argument-hint: "apt:execute [--continue] [--subtask <id>] [--parallel] [--wave <N>] [--tdd] [--no-tdd] [--spar]"
 gates: 
   - constitution-read
   - constitution-coverage
@@ -139,7 +139,7 @@ Before loading context, determine execution mode:
 
 4. **If Sequential Mode:** proceed to Section 1 below (existing behavior, unchanged).
 
-### 0a.1. TDD Discipline Detection (Pocock adoption AC3)
+### 0a.1. TDD Discipline Detection
 
 Compute whether the vertical-tracer-bullet TDD discipline is active for
 this run. The `<tdd_iron_law>` block in Section 3c is gated on this
@@ -168,13 +168,13 @@ else:
 
 Carry `tdd_active` forward to Section 3c. When `tdd_active === false`,
 the iron-law block is skipped entirely and execute behaves identically
-to the pre-Pocock single-commit flow. When `tdd_active === true`, the
+to the pre-vertical-slice single-commit flow. When `tdd_active === true`, the
 red-green-refactor sequence is mandatory and audited by gate G9.
 
 **The QUICK exemption is a constraint, not a toggle.** A user who passes
 `--tdd` on a QUICK-routed task gets `tdd_active = false` and a one-line
 note in the run report: "TDD requested but skipped — QUICK Fast Path
-Guarantee (ID-05)". The Pocock appendix
+Guarantee (ID-05)". The Aperant appendix
 `appendices/tdd-mode.md` carries the rationale.
 
 ## 1. Load Context
@@ -453,6 +453,19 @@ After all subtasks are completed:
 node packages/framework/bin/apt-tools.mjs commit "build: all subtasks complete" --files implementation_plan.json build-progress.json
 ```
 
+### Mark lifecycle phase as `verifying`
+
+Flip the task's lifecycle phase at the success-end boundary so the next stage
+(`/apt:verify`) finds the task in the correct from-state. Mirror the same CLI
+shape as the start-boundary call in Section 2 — quick tasks (no phase linkage)
+silently no-op, and the update is idempotent so it is safe to re-run on
+`--continue`. Skip this step if any subtask ended in `"blocked"` — only the
+all-subtasks-completed branch should advance the phase.
+
+```bash
+node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase verifying
+```
+
 Output:
 ```
 Execution complete:
@@ -463,6 +476,29 @@ Execution complete:
 Next: /apt:verify
 ```
 
+### 4a. --spar flag (FRAMEWORK-RFC-001)
+
+If `$ARGUMENTS` contained `--spar`, dispatch `/apt:spar` against the
+just-completed implementation before reporting Next.
+
+Topic frame: 1-2 sentences derived from `build-progress.json` 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 (corner case), use the task description from
+`.aperant/state.json` as a graceful fallback.
+
+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-build-progress.json>
+```
+
+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:verify`.
+
 ## 5. Wave-Parallel Execution
 
 When wave mode is active (determined in Section 0), execution follows the wave structure instead of flat sequential order. This is the throughput multiplier — independent subtasks run in parallel across multiple agent contexts.

package/dist/plugin/skills/apt-execute/appendices/tdd-mode.md

@@ -1,16 +1,8 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/tdd
-Licensed under MIT. Modifications: ported as an apt:execute appendix
-gated by `tdd_active` (config.coding.tdd_default || --tdd flag) and
-made QUICK-exempt per Aperant's Fast Path Guarantee (ID-05).
--->
-
 # TDD Mode — Vertical Tracer-Bullet Discipline (apt:execute appendix)
 
 This appendix loads into `apt:execute`'s context when `tdd_active === true`
 (see SKILL.md §0a.1). It carries the vertical-tracer-bullet discipline
-Pocock's `tdd` skill captured. The audit gate G9 (`tdd-iron-law`) enforces
+the `tdd` skill captured. The audit gate G9 (`tdd-iron-law`) enforces
 the commit order; this prose explains the **why**.
 
 ## Why vertical tracer bullets, not horizontal layers
@@ -90,7 +82,7 @@ that their flag was overridden by the constraint.
 ## Backward-compat alias
 
 The legacy `config.tdd.iron_law` key continues to enable TDD for
-projects that adopted Aperant before the Pocock content-format
+projects that adopted Aperant before content-format
 upgrade. The new computation rolls it into `tdd_active`:
 
 ```

package/dist/plugin/skills/apt-fan-out/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: apt:fan-out
+description: "Cross-task fan-out — spawn N apt-executor workers from one conductor terminal, each in its own worktree"
+apt-skill-version: {{APT_VERSION}}
+stage: execute
+intent: x-fan-out
+when_to_use: "You have N pre-planned, independent tasks (no file overlap, no cross-dependencies) and want to run them concurrently from a single host CLI session."
+user_invocable: true
+internal: false
+spawns_agent: true
+agent_name: "apt-executor"
+task_context: require-existing
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Task"
+argument-hint: "apt:fan-out --tasks <id,id,id> [--phases <m/p,m/p>] [--unblocked]"
+gates: []
+---
+<objective>
+Run N pre-planned Aperant tasks concurrently from one conductor terminal. This skill is a thin orchestrator over the generalized wave engine (`unit_kind: "task"` path, see ADR-0003) and the existing primitives: `apt-tools worktree create --task`, `apt-tools lock claim`, `apt-tools event append`, and the `parallelization.max_tasks` quota. No daemon, no job queue, no in-skill scheduling. The host CLI's main thread is the conductor (ADR-0001); each spawned apt-executor subagent runs in its own worktree (ADR-0002).
+
+This is the "I have 16 unblocked tasks in this phase, run them all" surface. It replaces the old workaround of opening 16 sibling terminals manually.
+</objective>
+
+<your_environment>
+- **Working directory:** Project root (where you were invoked).
+- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` (or `node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs` when running from an install mirror).
+- **Concurrency cap:** `parallelization.max_tasks` from `.aperant/config.json` (default 4, no paternalism cap per D-07). Read via `cli/config/parallelization.mjs:getMaxTasks(config)`.
+- **Worker identity:** Each spawned worker exports `APT_AGENT_ID=fanout-${batch_id}-${task_id}` before any `apt-tools ...` invocation (per FRAMEWORK-BUG-033 defect 3). This pins their `team-status/{agentId}.json` rows across short-lived CLI calls.
+- **Constitution:** Read `AGENTS.md` if it exists.
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `.aperant/state.json` — `active_tasks[*]` filtered when `--phases` or `--unblocked` resolves the task list.
+- `.aperant/roadmap/{scope}/milestones.json` — milestone/phase membership for `--phases`.
+- `.aperant/config.json:parallelization.max_tasks` — concurrency cap.
+
+**Writes (indirectly via spawned workers):**
+- `.aperant/team-status/fanout-${batch_id}-${task_id}.json` — one stable file per worker (per FRAMEWORK-BUG-033 defect 3 fix).
+- `.aperant/state.json:active_tasks[*].assigned_to` — workers stamp their `APT_AGENT_ID` on claim (per FRAMEWORK-BUG-033 defect 2 fix).
+- `.aperant/events/{today}.jsonl` — `task-claimed`, `wave-started`, `wave-completed` events.
+
+**No filesystem state of its own.** The skill body is pure orchestration glue; all heavy lifting reuses existing primitives.
+</state_files>
+
+<process>
+
+## 1. Resolve the batch — canonical task ID list
+
+The three input forms (`--tasks`, `--phases`, `--unblocked`) all resolve to a canonical `task_ids: [...]` list via the apt-tools helper:
+
+```bash
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --tasks T1,T2,T3,T4
+# OR
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --phases m1/p1,m1/p2
+# OR
+node packages/framework/bin/apt-tools.mjs fan-out resolve . --unblocked
+```
+
+Returns:
+```json
+{
+  "status": "ok",
+  "command": "fan-out-resolve",
+  "task_ids": ["T1", "T2", "T3", "T4"],
+  "source": "tasks",
+  "batch_id": "fanout-20260519-abc123"
+}
+```
+
+If `--tasks` IDs fail the `/^[a-z0-9_-]+$/i` validation regex, the helper returns `status: error` and the skill body MUST abort.
+
+## 2. Ensure each task has a worktree
+
+For each `task_id` in the batch:
+
+```bash
+node packages/framework/bin/apt-tools.mjs worktree create --task ${task_id}
+```
+
+(Skip if `state.active_tasks[task_id].worktree_path` is already set — the create command is idempotent.)
+
+## 3. Spawn N apt-executor subagents
+
+Read the `parallelization.max_tasks` cap from `.aperant/config.json` (or default 4). Slice `task_ids` into batches of size `min(cap, task_ids.length)`. For each task in the current batch, dispatch via the host CLI's `Task` tool with `run_in_background: true`:
+
+- `subagent: apt-executor`
+- `prompt` includes:
+  - `batch_id` (from step 1)
+  - `task_id`
+  - The worktree path for this task
+  - A reminder: "Export `APT_AGENT_ID=fanout-${batch_id}-${task_id}` in every Bash invocation that runs `apt-tools` — see `packages/framework/agents/apt-executor.md` §0a."
+
+The executor agent's `<process>` §0a already documents the env-export rule; the spawn prompt just has to seed `batch_id` and `task_id`.
+
+## 4. Poll team-status until all workers reach a terminal state
+
+```bash
+node packages/framework/bin/apt-tools.mjs team list .
+```
+
+Each worker's row uses its `APT_AGENT_ID=fanout-${batch_id}-${task_id}`. A worker is "done" when its corresponding task's `lifecycle_phase` is one of `closed`, `shipped-pending-merge`, or `blocked`.
+
+**On each poll, re-render the multi-task phase rail verbatim** — one boxed panel per worker, branch glyphs `┌─ │ └─` separating panels, status glyphs `✓` (done) / `●` (active) / `○` (pending), inline metrics on completed rows. Pull metrics from each worker's `build-progress.json` / `qa_signoff.json` / `review.json` (see paths in `.aperant/tasks/{task_id}/`):
+
+```
+[APT] Fan-out status: {N} workers
+┌─ {task 1 short name} ─────────────────────────────
+│  Phase 1 Plan       ✓
+│  Phase 2 Execute    ✓  7 commits, 81 tests
+│  Phase 3 Verify     ✓  APPROVED 9/10/9/9
+│  Phase 4 Review     ✓  APPROVE 9/9/9/10/10, 5 findings fixed
+│  Phase 5 Ship       ●  opening PR
+│
+└─ {task 2 short name} ─────────────────────────────
+   Phase 1 Plan       ✓
+   Phase 2 Execute    ✓  14 commits, 129 tests
+   Phase 3 Verify     ●  running
+   Phase 4 Review     ○
+   Phase 5 Ship       ○
+
+Churned for {Xm Ys} · {K} local agents still running
+```
+
+The first panel uses `┌─ ... │` (top-with-stem); the LAST panel uses `└─ ... ` (bottom corner). Footer line: "Churned" = elapsed since the most recent lifecycle event across all in-flight workers; "K local agents still running" = count of workers whose `lifecycle_phase` is non-terminal AND `assigned_to` is non-null.
+
+## 5. Report
+
+When all workers reach a terminal state, render the rail one final time. For each shipped worker (lifecycle `shipped-pending-merge` + `pr_url` set), collapse that panel to the SHIPPED variant:
+
+```
+[APT] Fan-out complete
+┌─ {task 1 short name} ────────────────────── ✅ SHIPPED
+│  Plan ✓ Execute ✓ Verify ✓ Review ✓ Ship ✓
+│  PR #{N}: {url}
+│
+└─ {task 2 short name} ─────────────────────── ⚠ BLOCKED
+   {one-line reason}
+```
+
+Mix SHIPPED / BLOCKED / in-flight variants in the same rail. Below the panel, emit one consolidated summary: which tasks closed (verdict + PR URL), which are awaiting merge, which blocked. Recommend `/apt:close-task --all` for the post-merge sweep. The `[APT] Fan-out` header lines above each rail are the backward-compat markers for external log-grep tooling — keep them.
+
+</process>
+
+## Design references
+
+- **ADR-0001** — Host CLI main thread is the conductor; no daemon, no in-skill queue.
+- **ADR-0002** — One worktree per task; workers run independent feature branches.
+- **ADR-0003** — Wave engine accepts `unit_kind: "task"` so cross-task fan-out reuses the same primitives as intra-task subtask waves.
+
+## Config keys
+
+- `parallelization.max_tasks` (default 4) — concurrency cap for the spawn loop.
+- `parallelization.max_agents` (default 4) — global agent quota; the spawn loop respects whichever cap is lower.