@aperant/framework 0.8.1 → 0.8.6

package/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/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/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/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
@@ -476,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/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/skills/apt-fan-out/SKILL.md

@@ -106,9 +106,44 @@ 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, 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.
+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>
 

package/skills/apt-handoff/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: apt:handoff
+description: "Agent-to-agent handoff — compact current conversation into a HANDOFF artifact in the repo for a fresh agent to pick up"
+apt-skill-version: {{APT_VERSION}}
+stage: pause
+intent: capture
+when_to_use: "An agent (not a human) needs to transfer in-flight work to a different agent — different model, different CLI, a fan-out peer, or a fresh context window. Writes a HANDOFF artifact under .aperant/ so the receiver picks up exactly where the sender left off. NOT for human end-of-day stops (use /apt:pause) and NOT for harness auto-compact (the query loop handles that itself)."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write"
+argument-hint: "apt:handoff [what the next session will focus on]"
+gates: []
+---
+<objective>
+Compact the current conversation into a HANDOFF document so a different agent — different model, different CLI, fan-out peer, or fresh context window — can pick up the work without re-discovering everything you already know.
+
+Writes the handoff to `.aperant/handoffs/{id}/HANDOFF.md` (or `{task_dir}/handoffs/{id}/HANDOFF.md` when inside a routed task) so the artifact lives with the repo, survives across machines, and is discoverable by `/apt:resume` and team-status tooling.
+
+**Use when:** an agent decides to transfer the work mid-flight. Examples — sender hit context-budget cap, the next phase needs a different model (e.g. Codex for a heavy refactor), a fan-out conductor is sharding scope to peers, or a planning agent is handing a locked plan to an executor.
+
+**Do NOT use when:**
+- The human operator wants to stop — use `/apt:pause` (it stashes uncommitted work and updates `CONTINUE_INDEX.md`).
+- The harness is about to auto-compact — the query loop handles that itself; agents executing plans must checkpoint to `build-progress.json` instead.
+- A new task is starting fresh — use `/apt` (router) or `/apt:plan`.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (or current task worktree if `state.active_tasks[taskId].worktree_path` is set)
+- **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
+- **Handoff index:** `.aperant/HANDOFFS_INDEX.md`
+- **Sibling skills:** `/apt:pause` (human stop), `/apt:resume` (restore from CONTINUE *or* HANDOFF), `/apt:fan-out` (parallel peers)
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `AGENTS.md` — Project constitution
+- Active Aperant artifacts for the current task, if any:
+  - `{task_dir}/spec.md`, `{task_dir}/implementation_plan.json`, `{task_dir}/build-progress.json`
+  - `{task_dir}/qa_signoff.json`, `{task_dir}/review.json`
+  - `.aperant/debug/*/DEBUG.md`, `.aperant/quick/*/TASK.md`
+- Git state (branch, uncommitted changes, recent commits)
+- `.aperant/state.json` — active tasks, worktree paths
+
+**Writes:**
+- `{task_dir}/handoffs/{handoff-id}/HANDOFF.md` — if inside a routed task
+- `.aperant/handoffs/{handoff-id}/HANDOFF.md` — if ad-hoc work outside any task
+- `.aperant/HANDOFFS_INDEX.md` — index of all open handoffs
+
+**Does NOT touch:**
+- The git working tree. Handoffs are read-only against code. If there are uncommitted changes the sender intends the receiver to keep working on, reference them in the HANDOFF (path + status from `git status --short`) — do NOT stash. Stashing is `/apt:pause` semantics, not `/apt:handoff`.
+</state_files>
+
+<process>
+
+## 1. Determine Handoff Location
+
+Generate a handoff id: `handoff-{YYYYMMDD-HHMM}-{short-slug-of-next-focus}` (e.g. `handoff-20260522-1430-finish-mcp-token-rotation`).
+
+**If inside a routed task** (task_dir is known from the conversation, or `state.json` has an active task for the current branch):
+- Write to `{task_dir}/handoffs/{handoff-id}/HANDOFF.md`
+
+**If ad-hoc work** (manual coding, not routed through /apt):
+- Write to `.aperant/handoffs/{handoff-id}/HANDOFF.md`
+
+```bash
+mkdir -p {handoff_dir}
+```
+
+## 2. Gather Current State
+
+### 2a. Git State
+```bash
+git branch --show-current
+git status --short
+git log --oneline -5
+git stash list
+```
+
+### 2b. Active Aperant Artifacts
+Check and read status of any of: `implementation_plan.json`, `build-progress.json`, `qa_signoff.json`, `review.json`, `.aperant/debug/*/DEBUG.md`.
+
+### 2c. Conversation Context
+From the current conversation, extract:
+- What task was being worked on and the user's framing of why
+- Key decisions made + rationale (especially decisions NOT obvious from the diff)
+- What was tried, what worked, what failed and why
+- Live blockers and open questions
+- Any external state the receiver must check (running processes, deployed previews, CI runs, MCP server sessions)
+
+## 3. Write HANDOFF.md
+
+Create `{handoff_dir}/HANDOFF.md`:
+
+```markdown
+# Handoff: {one-line summary of what the next agent should focus on}
+
+## Session Info
+- **Date:** {ISO datetime}
+- **Sender:** {model + CLI, e.g. "Claude Opus 4.7 / Claude Code"}
+- **Suggested receiver:** {model + CLI hint, or "any agent"}
+- **Branch:** {current branch}
+- **Worktree:** {worktree_path if task-isolated, else repo root}
+- **Last commit:** {hash} — {message}
+- **Task ID:** {task-id, if routed task; else "ad-hoc"}
+
+## Focus For The Receiver
+{The single most important paragraph — what is the receiver supposed to DO next, in concrete terms. If the user passed args to /apt:handoff, that text drives this section.}
+
+## What Was Being Done
+{Plain-language description of the current activity and how it fits the broader task.}
+
+## Decisions Made (do NOT relitigate)
+- {decision 1} — {rationale}
+- {decision 2} — {rationale}
+
+## Existing Artifacts (read these, do not duplicate)
+- `{path or URL}` — {what it contains, why it matters}
+- `{path or URL}` — {what it contains, why it matters}
+
+> Reference paths and URLs instead of pasting content. PRDs, plans, ADRs, issues, commits, diffs, /apt:debug DEBUG.md, /apt:design DESIGN.md — link, don't copy.
+
+## Current State
+- **Pipeline stage:** {plan | execute | verify | review | debug | design | quick | none}
+- **Subtask progress:** {n}/{total} (if applicable, with the in-flight subtask id)
+- **Uncommitted changes:** {yes/no — list files, do not stash}
+- **External state the receiver must check:** {running dev servers, open PRs, MCP sessions, etc.}
+
+## Blockers
+- {blocker 1 — what's needed to unblock, and which file/person/check resolves it}
+- (none)
+
+## What Was Tried
+- {approach 1} — {outcome}
+- {approach 2} — {outcome}
+
+## Next Steps (ordered)
+1. {immediate next action}
+2. {following action}
+3. {…}
+
+## Suggested Skills
+Tell the receiver which Aperant skills are likely to fire next. Map verbs to the live `/apt:*` registry — do NOT invent skill names.
+
+- `/apt:resume` — first thing the receiver should run to load this handoff into context.
+- `/apt:execute` — if a plan exists and subtasks remain.
+- `/apt:debug` — if the open blocker is a reproducible bug without a known cause.
+- `/apt:spar` — if the next decision wants a second-LLM challenge before committing.
+- `/apt:plan` — if scope changed and the existing plan is stale.
+- (omit any that don't apply)
+
+## Redaction Checklist
+Before saving, scrub the HANDOFF for:
+- [ ] API keys, bearer tokens, OAuth secrets (Anthropic, Stripe, Convex, GitHub, etc.)
+- [ ] Database connection strings with passwords
+- [ ] Personally identifiable information not already in the repo
+- [ ] Internal URLs that should not leave the team
+```
+
+## 4. Update Handoff Index
+
+Update `.aperant/HANDOFFS_INDEX.md`. Create with this header if it does not exist:
+```markdown
+# Open Handoffs
+
+| Focus | Branch | Date | Suggested receiver | Location |
+|-------|--------|------|--------------------|----------|
+```
+
+Append one row:
+```
+| {focus (truncated to 60 chars)} | {branch} | {YYYY-MM-DD HH:MM} | {model hint or "any"} | {relative path to HANDOFF.md} |
+```
+
+If a row already exists for this handoff path, update it instead of appending.
+
+## 5. Report
+
+```
+Handoff written: {handoff_dir}/HANDOFF.md
+
+Summary:
+  Focus: {one-line}
+  Branch: {branch}
+  Pipeline stage: {stage}
+  Suggested next skill: {/apt:resume → /apt:{stage}}
+  Open handoffs: {total count from index}
+
+Receiver picks up with:
+  /apt:resume                # discovers this handoff via HANDOFFS_INDEX.md
+  OR read {handoff_dir}/HANDOFF.md directly
+```
+
+</process>
+
+<notes>
+## Why this skill exists separately from /apt:pause
+
+`/apt:pause` and `/apt:handoff` write the same shape of artifact but have different triggers and side effects:
+
+| | `/apt:pause` | `/apt:handoff` |
+|---|---|---|
+| Trigger | Human types it | Agent decides mid-work |
+| Audience | Future-you (same human) | A different agent |
+| Uncommitted work | Stashes via `git stash` | Does NOT stash — references in-place |
+| Index file | `.aperant/CONTINUE_INDEX.md` | `.aperant/HANDOFFS_INDEX.md` |
+| Artifact name | `CONTINUE.md` | `HANDOFF.md` |
+| Typical follow-up | Human runs `/apt:resume` hours/days later | Receiver agent runs `/apt:resume` immediately |
+
+Keeping the index files separate lets `/apt:resume` distinguish "the human stopped here" from "another agent dropped this in your lap" when presenting recovery options.
+
+## Receiver contract
+
+The receiver is expected to:
+1. Run `/apt:resume` (or read HANDOFF.md directly).
+2. Load the referenced artifacts (paths under "Existing Artifacts").
+3. Verify the listed external state still holds (e.g. dev server still running, PR still open).
+4. Delete the HANDOFF.md and its index row after picking up. `/apt:resume` handles the cleanup automatically; manual readers should do it themselves to keep `HANDOFFS_INDEX.md` from drifting.
+</notes>

package/skills/apt-improve/DEEPENING.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/DEEPENING.md
-Licensed under MIT. Modifications: scoped to Aperant's apt:improve
-Phase-1 explore step and aligned with the deletion-test priority
-rubric in Phase 2.
--->
-
 # DEEPENING — Domain-modeling depth lens
 
 This lens asks: **does this area model the domain at the right depth?**

package/skills/apt-improve/INTERFACE-DESIGN.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md
-Licensed under MIT. Modifications: scoped to Aperant's apt:improve
-Phase-1 explore step and aligned with apt:review Pass 4's boundary
-audit semantics (this lens is proactive; Pass 4 is reactive).
--->
-
 # INTERFACE-DESIGN — Boundary-shape lens
 
 This lens asks: **are the boundaries between modules well-shaped?** Are

package/skills/apt-improve/LANGUAGE.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/LANGUAGE.md
-Licensed under MIT. Modifications: scoped to Aperant's apt:improve
-Phase-1 explore step and aligned with CONTEXT.md's aliases-to-avoid
-field — this lens reads that field to catch term conflations.
--->
-
 # LANGUAGE — Naming-consistency lens
 
 This lens asks: **does the codebase use the same word for the same

package/skills/apt-improve/SKILL.md

@@ -22,15 +22,15 @@ gates: []
 
 # Improve — Proactive Refactor Discovery
 
-Open question #2 in the Pocock adoption spec was answered concretely:
+Open question #2 in adoption spec was answered concretely:
 `apt:review` Pass 4 (architecture) is strictly **reactive** — it audits
 the current diff for boundary violations. The work-intent "look at this
 codebase and tell me what to refactor proactively" has no home today
 (users retrofit it onto `apt:discuss --brainstorm` or `/apt:roundtable`,
 both scope-mismatched). This skill is that home.
 
-**Pocock adoption attribution.** 3-phase workflow + DEEPENING /
-INTERFACE-DESIGN / LANGUAGE lenses ported from Matt Pocock's MIT-licensed
+**Aperant adoption attribution.** 3-phase workflow + DEEPENING /
+INTERFACE-DESIGN / LANGUAGE lenses ported from 
 `improve-codebase-architecture` skill. Aperant-specific: spawns the
 `apt-improver` agent and references `apt-discuss/appendices/grill-discipline.md`
 as the canonical source for the autonomy-aware deepening loop rather than
@@ -118,7 +118,7 @@ The deepening loop produces a concrete refactor plan (which becomes
 - `INTERFACE-DESIGN.md` — boundary-shape lens
 - `LANGUAGE.md` — naming-consistency lens
 
-All three are ported from Matt Pocock's improve-codebase-architecture
+All three are ported from 's improve-codebase-architecture
 skill with MIT attribution per AC15.
 
 ## Agent spawned

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)
 
@@ -161,6 +161,14 @@ and is committable as a second-consumer document. Section ordering is
 **load-bearing** — downstream tooling (`apt-tools coverage-check`,
 `apt-tools consistency check`) reads sections by header.
 
+**Three orthogonal user-facing sections — keep them distinct.** User
+Stories carry product motivation, User Outcomes carry the
+verify-proof input contract, and Acceptance Criteria carry code-level
+invariants. The three do NOT subsume each other; a STANDARD/DEEP spec
+carries all three. See the `## User Outcomes` block below for the
+verify-proof unit shape (Epic line + atomic outcomes + surface tags
++ empty-with-note escape).
+
 ```markdown
 # Spec: {task title}
 
@@ -184,6 +192,29 @@ ships: new files, modified files, new flags, new config, new skills.}
 {persona}, when I {trigger}, I want {behavior} so I can {outcome}."
 Stories map 1:1 onto subtasks in implementation_plan.json.}
 
+## User Outcomes
+
+{The verify-proof input contract. One bolded `**Epic:**` headline + N
+atomic outcomes tagged by surface. Authors write the LITERAL string
+`**ON**` — IDs are POSITIONAL and synthesized by the parser (the first
+outcome row becomes `O1`, the second `O2`, etc.). Closed surface set:
+`electron | web | cli | api | electron+web`. Optional cross-references
+via `*(requires ON N)*` where `N` is the digit of a prior outcome's
+position. For pure-refactor specs with no user-observable changes, the
+body MAY be exactly `_No user-observable changes — pure refactor._`
+(italic underscores required, exact em dash, period mandatory).
+Coverage-check parses this section into a `user_outcomes` payload —
+see the gate table below.}
+
+**Epic:** {one-sentence user-facing capability headline}
+
+- **ON** [surface]: {user does X; system shows/does Y}
+- **ON** [surface]: {user does X; system shows/does Y} *(requires ON 1)*
+- **ON** [electron+web]: {cross-surface outcome — runs twice, once per surface}
+
+(Refactor-only escape:)
+_No user-observable changes — pure refactor._
+
 ## Implementation Decisions
 
 {Load-bearing principles carried forward into every subtask. Format:
@@ -215,6 +246,25 @@ ID. Subtasks reference these IDs via their per-subtask
 plan-coverage-check input.}
 ```
 
+**`## User Outcomes` is the verify-proof input contract (STANDARD/DEEP
+only — QUICK is hard-exempt per ID-05 / Fast Path Guarantee).** The
+section sits between `## User Stories` (product motivation prose) and
+`## Implementation Decisions` (load-bearing engineering principles).
+Coverage-check (`apt-tools coverage-check validate .`) parses the
+section into a `user_outcomes` payload with this gate behavior:
+
+| Header present? | Body shape | Gate result (v0.8.x) | v0.9.0 hard cutover |
+|---|---|---|---|
+| no | — | `warn` (migration deadline emitted) | `block` |
+| yes | `outcomes` (≥1 `**ON**` row) | `pass` | `pass` |
+| yes | exactly `_No user-observable changes — pure refactor._` | `pass` | `pass` |
+| yes | empty (header but nothing under it) | `block` | `block` |
+
+Closed surface set: `electron | web | cli | api | electron+web`. The
+`electron+web` tag means the outcome runs on both surfaces during
+verify-proof (split screenshot trees, two test entries in
+`verification.json`).
+
 **Constraint — do NOT interview the user.** The PRD is synthesized from
 the task description + codebase investigation + AGENTS.md, not from a
 clarifying interview. If a section truly cannot be filled, write
@@ -309,7 +359,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 +504,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.