@aperant/framework 0.8.1 → 0.8.6

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

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

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

@@ -16,9 +16,12 @@ execution_modes:
   - step
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
 argument-hint: "apt:ship [--draft | --title \"...\"]"
-gates: 
+gates:
+  - constitution-read
+  - verify-approved
   - review-clean
-  - all-subtasks-complete
+  - consistency-check
+  - r-persona-alignment
   - gitignore-in-sync
 config_keys:
   - pipeline.auto_branch
@@ -59,7 +62,7 @@ node packages/framework/bin/apt-tools.mjs gate check . --task-id {task-id} --ski
 ```
 
 Parse the JSON envelope:
-- If `status == "ok"`: proceed to Section 1.
+- If `status == "ok"`: proceed to Section 0.5 / 1.
 - If `status == "fail"` AND `forced` is empty (i.e. the user did NOT pass `--force`): STOP. Report the failed gates verbatim from `failed:[{id, severity, reason}]`, then emit:
   ```
   Hard gate failed. Fix the issues above, or re-run with:
@@ -70,6 +73,17 @@ Parse the JSON envelope:
 
 The ship gate covers constitution-read, verify-approved (qa_signoff.json verdict), review-clean (no unresolved critical/warning findings), gitignore-in-sync (.aperant/.gitignore conformance), and consistency-check (G8 — cross-artifact consistency between spec.md, implementation_plan.json, review.json, qa_signoff.json, and build-progress.json). Because these gates run here, Sections 1–3 below no longer need to re-check the verify verdict or block on review findings — the gate already did it.
 
+### 0.1 Parse `profile` from the envelope
+
+The envelope carries `profile: "lite" | "full-pipeline"` derived from `taskRecord.track` (QUICK / DEBUG → lite; STANDARD / DEEP → full-pipeline). Capture it now — Sections 1, 2, and 3 branch on it:
+
+```bash
+profile=$(echo "$gate_envelope" | jq -r '.profile // "full-pipeline"')
+```
+
+- **`profile === "lite"`** (QUICK or DEBUG track): the three full-pipeline gates (`verify-approved`, `review-clean`, `consistency-check`) were skipped by design — those tracks do not produce `qa_signoff.json`, `review.json`, or a multi-subtask `implementation_plan.json`. SKIP Sections 1 (review.json + decision notes reads) and 2 (commit-to-subtask map). JUMP to Section 3's lite body branch.
+- **`profile === "full-pipeline"`** (STANDARD or DEEP track): full pipeline ran — Sections 1, 2, and 3's full-body template all apply unchanged.
+
 ## 0.5 Pre-PR Committable Drift Check (C56 B2)
 
 Before gathering PR context, audit for uncommitted committable `.aperant/` state and stage anything the self-staging helper missed. This closes the artifact-leak class that the framework shipped with pre-C56: phases flipped in-progress, roadmap JSON touched, decision notes written — none of which followed into the PR's commits.
@@ -97,8 +111,79 @@ Parse the JSON envelope:
 
 Classification reference: `packages/framework/docs/artifact-lifecycle.md` (committable vs ephemeral matrix for every `.aperant/` subpath).
 
+## 0.7 Pre-PR Branch-Current Audit + Rebase Gate
+
+Before any team-sync push (§5) or PR creation (§6), audit whether the task branch has drifted behind `origin/<base_branch>`. A PR opened against a stale base can silently no-op GitHub Actions when path-filter matrices evaluate against the merge-base — the recent Source Control panel pipeline lost ~20 min to this defect class before the operator noticed CI never engaged.
+
+This section runs BEFORE Section 5 (Sync Team Bookkeeping). Order is load-bearing: if §0.7 runs after §5, the team-sync push races the post-§0.7 rebase, the captured `remote_tip_sha` is stale by the time §6 leases against it, and the lease fails on a commit `apt:ship` itself just pushed. The TD-02 structural test locks the §0.7 → §5 ordering.
+
+Resolve the base branch (same `task get` envelope §6 uses):
+
+```bash
+task_info=$(node packages/framework/bin/apt-tools.mjs task get . --id {task-id})
+base_branch=$(echo "$task_info" | jq -r '.task.base_branch // "main"')
+worktree_path=$(echo "$task_info" | jq -r '.task.worktree_path // empty')
+ship_cwd=${worktree_path:-.}
+```
+
+Run the audit from the worktree (or the project root when no worktree is recorded):
+
+```bash
+audit_env=$(node packages/framework/bin/apt-tools.mjs audit branch-current "$ship_cwd" --base "$base_branch")
+behind=$(echo "$audit_env" | jq -r '.behind // 0')
+ahead=$(echo "$audit_env" | jq -r '.ahead // 0')
+mergeable=$(echo "$audit_env" | jq -r '.mergeable')
+audit_warning=$(echo "$audit_env" | jq -r '.audit_warning // empty')
+remote_tip_sha_pre_rebase=$(echo "$audit_env" | jq -r '.remote_tip_sha // empty')
+```
+
+Capture `remote_tip_sha_pre_rebase` now — §6's lease uses it.
+
+**Branch on the envelope:**
+
+- **`behind === 0`** → no rebase needed. The branch is current with `origin/<base_branch>` (or strictly ahead). Skip the rebase and proceed to §1. §6's push will use the plain `git push -u origin <branch>` form, not the lease form.
+
+- **`behind > 0` AND `mergeable === true`** → run a clean rebase:
+  ```bash
+  git -C "$ship_cwd" rebase "origin/$base_branch"
+  ```
+  Proceed to §1. §6's push will use `--force-with-lease=refs/heads/<branch>:$remote_tip_sha_pre_rebase` because history was rewritten.
+
+- **`behind > 0` AND `mergeable === false`** → STOP. Emit a structured error with the conflict preview verbatim:
+  ```
+  [APT:ship] Cannot ship — task branch is behind origin/{base_branch} and the rebase would conflict.
+  Conflicts preview:
+    - {path1}
+    - {path2}
+  Resolve manually (rebase or merge in the worktree), then re-run /apt:ship.
+  ```
+  Exit the skill — do NOT auto-resolve, do NOT proceed to §5 or §6.
+
+- **`mergeable === null` AND `audit_warning === "git-version-too-old"`** → STOP with a friendlier message:
+  ```
+  [APT:ship] Cannot ship — local git is too old to probe mergeability (need git ≥ 2.38 for 'merge-tree --write-tree').
+  Upgrade git, rebase manually, or re-run /apt:ship after upgrading.
+  ```
+  Exit the skill.
+
+- **`mergeable === null` AND `audit_warning === "fetch-failed"` or `"no-remote-base-ref"`** → STOP. The audit could not verify the remote tip, so we cannot lease safely. Emit:
+  ```
+  [APT:ship] Cannot ship — could not fetch origin/{base_branch} ({audit_warning}). Check network + remote, then re-run /apt:ship.
+  ```
+  Exit the skill.
+
+**Autonomy gating.** Read the active task's autonomy level from `.aperant/state.json` (`active_tasks[{task-id}].autonomy`, falling back to `autonomy.default`):
+
+- **Autonomy 0–1 (step / guided)** — print the audit envelope to the operator and ask `Rebase now? [Y/n]` before executing the `git rebase` line. On `N`, exit the skill (user can rebase manually and re-invoke).
+- **Autonomy 2 (auto-chain)** — proceed silently on the clean-rebase branch; STOP on conflict regardless.
+- **Autonomy 3 (YOLO)** — same as 2: silent on clean, STOP on conflict. Auto-resolution of conflicts is explicitly out of scope (see spec §Out of Scope).
+
+The captured `remote_tip_sha_pre_rebase` and `behind` integer are referenced verbatim in §6's push command. Treat them as read-only state for the remainder of the skill.
+
 ## 1. Gather Context
 
+**Profile guard:** Sections 1, 2, and 2.6 apply ONLY to `profile === "full-pipeline"`. When the envelope carried `profile === "lite"` (QUICK / DEBUG), SKIP Sections 1, 2, 2.6 and jump straight to Section 3 (`3.lite` branch).
+
 Read all available context for building the PR:
 
 ```bash
@@ -197,6 +282,53 @@ The helper lives at `packages/framework/src/cli/release-notes/ship-autodraft.mjs
 
 **Title:** Derived from task description. Keep it short (<70 characters).
 
+### 3.lite — `profile === "lite"` (QUICK and DEBUG)
+
+When the gate envelope carries `profile === "lite"`, emit the lite PR body. QUICK and DEBUG do not produce `qa_signoff.json` or `review.json`, so the lite body sources verification evidence from `task.json.verification` (QUICK: `.aperant/quick/{task-id}/task.json`) or, when no per-track task.json exists (DEBUG fallback), from the active-task record in `state.active_tasks[task_id]`.
+
+```bash
+# QUICK: per-track task.json carries the verification block
+task_json=$(cat .aperant/quick/{task-id}/task.json 2>/dev/null)
+# DEBUG fallback: no per-track task.json — verification is best-effort, omit the block if absent
+```
+
+Lite body shape:
+
+```markdown
+## Summary
+
+{one-liner from task.description in state.active_tasks[task-id]}
+
+## Verification
+
+- Typecheck: {task.json.verification.typecheck}
+- Lint: {task.json.verification.lint}
+- Tests: {task.json.verification.test}
+- Visual: {task.json.verification.visual}{when task.json.verification.evidence_path present, append: ` ({evidence_path})`}
+
+{IF track === "DEBUG" AND .aperant/debug/{task-id}/DEBUG.md exists, append the RCA section distilled from the file's `## Conclusion` heading. The distillation is best-effort — quote the conclusion paragraph verbatim, keeping it under ~10 lines:}
+
+## RCA
+
+{distilled from .aperant/debug/{task-id}/DEBUG.md `## Conclusion` section}
+
+## Commits
+
+| Commit | Description |
+|--------|-------------|
+| `{sha}` | {message} |
+
+---
+
+Built with [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework)
+```
+
+The lite body omits `## QA Scores`, `## Review Findings`, `## Decision Traceability`, and the per-subtask column in `## Commits` — none of those signals exist on lite-profile tasks. Once the body is assembled, skip the rest of Section 3 and jump to Section 4.
+
+### 3.full — `profile === "full-pipeline"` (STANDARD and DEEP)
+
+The body structure below is the full-pipeline template — unchanged from the pre-fix behavior. Render it when `profile === "full-pipeline"`.
+
 **Body structure:**
 
 ```markdown
@@ -307,27 +439,51 @@ Parse `worktree_path`, `branch`, and `base_branch` from the result.
 
 - **If the task record has `branch` and `worktree_path` (task-level worktree isolation active):**
   ```bash
-  git -C {worktree_path} push -u origin {branch}
+  if [ "$behind" = "0" ]; then
+    git -C {worktree_path} push -u origin {branch}
+  else
+    # §0.7 rebased — lease against the pre-rebase remote tip so a concurrent
+    # advance of origin/{branch} between §0.7 and §6 trips the lease instead
+    # of silently overwriting the racing party's commit.
+    git -C {worktree_path} push --force-with-lease=refs/heads/{branch}:$remote_tip_sha_pre_rebase origin {branch} || {
+      echo '[APT:ship] Cannot ship — remote-advanced: origin/{branch} moved between §0.7 audit and §6 push. Re-run /apt:ship.' >&2
+      exit 1
+    }
+  fi
   gh pr create --title "{title}" --body "{body}" --base {base_branch} --head {branch}
   ```
-  The PR targets the recorded `base_branch` (the branch the task was forked from), NOT `main`. This is the correct target when the user is shipping an intermediate milestone onto a longer-lived feature branch.
+  The PR targets the recorded `base_branch` (the branch the task was forked from), NOT `main`. This is the correct target when the user is shipping an intermediate milestone onto a longer-lived feature branch. The lease form is used only when §0.7 reported `behind > 0` (history was rewritten); on `behind === 0` a plain push is correct.
 
 - **If the task record has `branch` but no `worktree_path`:** Push the branch from the current cwd and create the PR against `base_branch`:
   ```bash
-  git push -u origin {branch}
+  if [ "$behind" = "0" ]; then
+    git push -u origin {branch}
+  else
+    git push --force-with-lease=refs/heads/{branch}:$remote_tip_sha_pre_rebase origin {branch} || {
+      echo '[APT:ship] Cannot ship — remote-advanced: origin/{branch} moved between §0.7 audit and §6 push. Re-run /apt:ship.' >&2
+      exit 1
+    }
+  fi
   gh pr create --title "{title}" --body "{body}" --base {base_branch} --head {branch}
   ```
 
-- **If no task branch is recorded and we're on main/master:** Legacy behaviour — create a feature branch first:
+- **If no task branch is recorded and we're on main/master:** Legacy behaviour — create a feature branch first. §0.7 only ran when a task record exists; this path is reached only on ad-hoc shipping and the rebase gate is necessarily skipped, so a plain push is correct (no rewritten history to lease against):
   ```bash
   git checkout -b {task-slug}
   git push -u origin {task-slug}
   gh pr create --title "{title}" --body "{body}"
   ```
 
-- **If no task branch is recorded and we're already on a feature branch:** Legacy behaviour — push HEAD and open a PR against `main`:
+- **If no task branch is recorded and we're already on a feature branch:** Legacy behaviour — push HEAD and open a PR against `main`. When §0.7 ran (task record present), the lease form applies when `behind > 0`; on the ad-hoc / no-task-record path the gate is skipped and a plain push is correct:
   ```bash
-  git push -u origin HEAD
+  if [ -n "${remote_tip_sha_pre_rebase:-}" ] && [ "$behind" != "0" ]; then
+    git push --force-with-lease=refs/heads/$(git rev-parse --abbrev-ref HEAD):$remote_tip_sha_pre_rebase origin HEAD || {
+      echo '[APT:ship] Cannot ship — remote-advanced: branch tip moved between §0.7 audit and §6 push. Re-run /apt:ship.' >&2
+      exit 1
+    }
+  else
+    git push -u origin HEAD
+  fi
   gh pr create --title "{title}" --body "{body}"
   ```
 

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

@@ -29,7 +29,7 @@ Two boundaries with adjacent skills:
 - **Spar is not a review skill.** `/codex:adversarial-review` and `/apt:review` are one-shot. Spar loops until convergence or the round cap.
 - **Spar is bidirectional 1:1.** Roundtable is 10-agent. If you want a 3-way debate, use `/apt:roundtable`.
 
-Hard rule, v1: **no artifact directory written.** The transcript stays in-conversation. The host prints a final verdict block, nothing persists to disk under `.aperant/sparring/` or anywhere else.
+Termination posture (v1.1, amending SPAR-06): the termination headline is in-conversation; the long-form converged position is written to a single timestamped file under `.aperant/spar/`. No conversation-transcript dump, no `.aperant/sparring/` directory — see `<state_files>` for the exact contract.
 </objective>
 
 <your_environment>
@@ -47,12 +47,12 @@ Hard rule, v1: **no artifact directory written.** The transcript stays in-conver
 
 **Reads:**
 - `AGENTS.md` — project constitution (principles, conventions, tech stack)
-- `.aperant/config.json` — `router.llm.providers` for partner fallback (read-only)
+- `.aperant/config.json` — `router.llm.providers` for partner fallback (read-only). **NOTE:** `router.llm.providers.<id>.model` is NOT consulted for spar partner model selection — partner CLIs inherit their own native config (codex: `~/.codex/config.toml`; gemini: `GEMINI_MODEL` env / `~/.gemini/settings.json`). The `router.llm.providers` keys serve the cheap LLM-router classifier, a separately scoped reserved surface (see `packages/framework/src/types/config.ts:222-238`); do not conflate.
 - `.aperant/state.json` — `active_task` framing, optional
 - The live conversation transcript (when `[topic]` is empty)
 
 **Writes:**
-- **None.** No artifact directory written — transcript stays in-conversation per SPAR-06. The final verdict is printed to stdout; nothing is persisted under `.aperant/sparring/` or any other path. This is a hard contract — do not "helpfully" add a transcript-dump file.
+- A single markdown file at `.aperant/spar/<short-slug>-<YYYYMMDD-HHMMSS>.md` containing the long-form converged position, the verdict-per-round table, and any parallel-bug call-outs. No subdirectories; flat layout mirroring `.aperant/debug/` and `.aperant/roundtables/`. Write-once; not loaded back into context on subsequent runs. This narrows the SPAR-06 commitment (amended 2026-05-21 — see task `apt-spar-readable-termination-summary_21-05-26`): the conversation transcript still stays in-conversation, full-transcript dumps to `.aperant/sparring/` are still rejected, but the long-form converged position is now persisted so it survives terminal close.
 </state_files>
 
 <rationalization>
@@ -64,7 +64,7 @@ The verify-before-cede rule is the whole skill. Every rationalization below name
 | "I don't need to verify — I already know I'm right." | Holding without evidence is equally forbidden. Your prior beliefs are not citations. If you can't open a file and point at a line, you don't actually know — you remember. The rule is symmetric: cede with evidence OR hold with evidence; never neither. |
 | "Only 1 round is needed — the partner's first response settles it." | True only if verification was performed. If round 1 ended with `verdict: cede` or `verdict: hold` and the verdict cited concrete evidence (`file:line`, test output, doc reference), terminating after round 1 is fine and expected. The danger is treating round 1 as a verdict because the partner's response *felt* conclusive. Speed without verification is not victory. |
 | "I'll skip host-detection and just call codex directly." | This breaks the bidirectional contract. `apt:spar` must work whether the user is on Claude Code, Codex CLI, Gemini CLI, or any of the 15+ runtimes `host-detect` covers. Hardcoding a partner makes the skill Claude-Code-centric and silently breaks the Codex→Claude direction. Always run `host-detect` (or honor `--with`) — never assume the host. |
-| "I'll persist the transcript so the user can revisit it." | SPAR-06 is non-negotiable in v1: no artifact directory written. The conversation transcript is the artifact. Adding a write under `.aperant/sparring/` creates an orphan-cleanup concern the user explicitly rejected; if persistence is needed later, that's a follow-up task, not a "helpful" addition here. |
+| "I'll dump the full conversation transcript to disk." | Wrong scope. The SPAR-06 amendment (2026-05-21) writes ONLY the long-form converged position + verdict-per-round table + parallel call-outs to ONE timestamped file under `.aperant/spar/`. The conversation transcript stays in-conversation; full-transcript dumps to `.aperant/sparring/` are still rejected per the original SPAR-06 rationale (orphan-cleanup concern). Stick to the bounded artifact. |
 </rationalization>
 
 <autonomy_interaction>
@@ -74,7 +74,7 @@ The verify-before-cede rule is the whole skill. Every rationalization below name
 - **Autonomy 2 (Balanced, default):** Run the full loop (up to `--rounds N`, default 3) without mid-loop pauses. Pause **once** before the final converge/escalate decision in `<process>` §9 so the user can accept the termination summary or redirect.
 - **Autonomy 3 (YOLO):** Run end-to-end with no pauses. Print the termination summary and return.
 
-**v1 has no auto-trigger hooks (SPAR-07).** `apt:spar` is manually invoked only — neither `/apt:plan` nor `/apt:review` chain into it automatically. Manual usage data will tell us whether auto-triggering helps; until then, deferring keeps the surface small.
+**v2 honors install-time consent (SPAR-07).** When `.aperant/config.local.json` carries `spar.enabled: true` (set via the `/apt:setup` install prompt) AND `/apt:run` was invoked with — or the `/apt` router auto-injected — `--spar-gates plan` (STANDARD) or `--spar-gates plan,execute` (DEEP), `/apt:spar` auto-fires between named pipeline stages. Manual `/apt:spar` invocation remains the canonical path (§1–§9 unchanged); auto-fire is opt-in per-device, never default-on per-project, never enabled on QUICK (Fast Path Guarantee). v1's "manually invoked only" rule was always deferred-pending-data per the original SPAR-07 escape hatch; founder manual-usage data is that trigger.
 </autonomy_interaction>
 
 <process>
@@ -133,7 +133,7 @@ Do NOT proceed; self-sparring is sycophancy by construction (the host cannot obj
 
 1. **Rung 1 — MCP tool** (`mcp__<partner>-mcp__*`, e.g. `mcp__codex-mcp__codex`). Detected if the host exposes its deferred-tool manifest via `CLAUDE_MCP_DEFERRED_TOOLS` and the tool is registered. When `detected: "runtime-host-only"` the framework process cannot probe the host's tool registry from outside — treat as candidate and attempt the tool call; if the tool is genuinely unavailable in the host's visible registry, fall through to rung 2.
 2. **Rung 2 — Plugin shim** (`${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`). Codex only (claude / gemini have no plugin shim).
-3. **Rung 3 — Raw CLI on `$PATH`** (`codex exec`, `claude -p`, `gemini -m`).
+3. **Rung 3 — Raw CLI on `$PATH`** (`codex exec`, `claude -p`, `gemini`).
 
 Walk the ladder in order; pick the first rung with `detected: true` (or `"runtime-host-only"` for MCP). **MCP rung has a hard timeout** — default 900000ms (15 min), configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. The MCP rung is a structured tool call, NOT a Bash invocation, so the Bash tool's 600000ms ceiling does NOT apply — the MCP rung can carry heavy-research partner runs (e.g. Claude Code partner doing multiple minutes of Read/Grep/Bash) where the Bash rungs would hit the host ceiling. On MCP timeout, **automatically fall through to rung 2 or rung 3** — do NOT fail the whole spar. Treat MCP timeout as "rung unavailable for this invocation."
 
@@ -183,20 +183,32 @@ The table below shows the canonical command shape per (partner × rung); the act
 
 | Partner | Rung | Command | Notes |
 |---|---|---|---|
-| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt})` | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. |
-| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
-| codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. Verify with `codex --help`. |
+| codex | mcp | tool call: `mcp__codex-mcp__codex({prompt, model})` where `model` is parsed from `~/.codex/config.toml`'s `model = "<value>"` line (see §5a below). | Preferred. 900000ms (15 min) timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. If `~/.codex/config.toml` is missing OR the `model =` line is absent/unparseable, treat MCP rung as UNAVAILABLE and fall through to plugin/CLI — never invent a default model (the MCP server's built-in fallback is stale `gpt-5.3-codex`, which is exactly the bug we are fixing). |
+| codex | plugin | `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `--model` flag — `codex-companion.mjs` invokes `codex exec` which inherits `~/.codex/config.toml` automatically. **NO `--write`. NO `--effort` override.** Per SPAR-04 — spar is conversation, not patching. |
+| codex | cli | `codex exec "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Precedent: `apt-pr-review/SKILL.md:1084`. No `--model` flag — `codex exec` inherits `~/.codex/config.toml` automatically. Verify with `codex --help`. |
 | claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. |
 | claude | plugin | n/a | No plugin shim exists for Claude. Skip this rung. |
 | claude | cli | `claude -p "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)" --output-format text` | Symmetric. Claude has no `--write` equivalent — asymmetric flags are a smell. |
 | gemini | mcp | tool call: `mcp__gemini-mcp__*({prompt})` | Preferred. Same 900000ms (15 min) timeout + fallthrough rule. Any `mcp__gemini-mcp__*` tool satisfies the rung. |
 | gemini | plugin | n/a | No plugin shim exists for Gemini. Skip this rung. |
-| gemini | cli | `gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | Read the exact model name from `.aperant/config.json` at runtime — do not hardcode. |
+| gemini | cli | `gemini "$(cat <<'APT_SPAR_PROMPT_EOF' ... APT_SPAR_PROMPT_EOF\n)"` | No `-m` flag — gemini-cli resolves model via `--model` > `GEMINI_MODEL` env > `~/.gemini/settings.json` > built-in default per `docs/cli/model-routing.md:47-58`. Drop the flag, let the cascade work; users override per-shell via `GEMINI_MODEL=...` or per-project via `settings.json`. |
 
 Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 300000).
 
 **Timeout calibration.** The 5-min Bash-rung default and 15-min MCP-rung default are sized for heavy-research partner runs — modern partner CLIs commonly spend multiple minutes doing real Read/Grep/Bash investigation before producing a round response. The two defaults are intentionally asymmetric: the Bash rungs (plugin shim, raw CLI) are capped at the Claude Code Bash tool's 600000ms (10 min) host ceiling, while the MCP rung — a structured tool call rather than a Bash invocation — has no host ceiling and can carry the worst-case 15-min Claude Code partner. For tighter budgets (e.g. CI), pass `--timeout-ms` explicitly. The MCP-rung override is downward-only: if you observe consistent partner-CLI wedges (auth handshakes, hosted-API stalls, CI lanes wanting fast failure), set `apt-spar.mcp_timeout_ms` BELOW the 15-min default in `.aperant/config.json` (e.g. `120000` for a 2-min fast-fail budget) — raising it above 15 min is unnecessary because the default already covers the documented worst case. Future versions may introduce per-partner defaults.
 
+## 5a. Codex MCP model resolution
+
+The codex MCP rung (table row above) requires an explicit `model` arg sourced from the user's `~/.codex/config.toml`. The MCP server (`codex-mcp-server`) does NOT read `~/.codex/config.toml` itself — when no `model` is passed it falls back to a hardcoded stale `gpt-5.3-codex`, silently overriding the user's actual configured model. Resolve the model exactly once per spar invocation, before the rung-table walk:
+
+```bash
+# Resolve the codex MCP model exactly once per spar invocation, before the rung table walk
+CODEX_MCP_MODEL="$(grep -E '^model = "[^"]+"' "$HOME/.codex/config.toml" 2>/dev/null | head -1 | sed -E 's/^model = "([^"]+)".*/\1/')"
+# If empty → codex MCP rung is UNAVAILABLE; fall through to plugin/CLI.
+```
+
+If `$CODEX_MCP_MODEL` is empty (file missing, `model =` line absent, or value not double-quoted), treat the MCP rung as UNAVAILABLE and fall through to plugin → CLI. **Never invent a default** — the upstream MCP server's built-in `gpt-5.3-codex` fallback is exactly the bug this resolution path exists to fix.
+
 **Prompt-quoting safety.** The prompt is user-controlled (it comes from `[topic]` and/or conversation context) and may legitimately contain double quotes, dollar signs, backticks, or `$(...)` substitution that bash would otherwise expand or break on. NEVER interpolate `<prompt>` directly inside a double-quoted shell argument. Instead, pipe via a here-document so the shell treats the body as opaque text:
 
 ```bash
@@ -213,7 +225,7 @@ APT_SPAR_PROMPT_EOF
 )" --output-format text
 
 # Gemini direction
-gemini -m <model-from-router.llm.providers.gemini-cli> "$(cat <<'APT_SPAR_PROMPT_EOF'
+gemini "$(cat <<'APT_SPAR_PROMPT_EOF'
 <prompt body — opaque, no shell expansion>
 APT_SPAR_PROMPT_EOF
 )"
@@ -298,21 +310,70 @@ The hard cap of 3 rounds is non-negotiable in v1 (see SPAR-05). Long-tail disagr
 
 ## 9. Termination Report
 
-Print a final block:
+The termination report has two layers. **Layer 1 — Headline** is printed to stdout and is the only thing the user reads to understand the spar at a glance. **Layer 2 — Detail** is the verbatim long-form converged position; it is persisted to a single timestamped file under `.aperant/spar/` so it survives terminal close (per the SPAR-06 amendment of 2026-05-21 — see `<state_files>`).
+
+### Layer 1 — Headline (always printed)
+
+Emit exactly this shape — `<-- copy this exact shape -->`:
 
+```text
+=== apt:spar — <outcome> ===
+Topic: <one-line topic restatement>
+Host: <cli-id> ↔ Partner: <cli-id>  ·  Rounds: <n>/<cap>
+
+Round 1: <one-sentence shift — what changed in the host's position, or what the partner caught>
+Round 2: <one-sentence shift, omit this line entirely if rounds<2>
+Round 3: <one-sentence shift, omit this line entirely if rounds<3>
+
+Outcome: <one-sentence plain-English statement of what was agreed/disagreed and what it means for the next plan>
+
+Next: <ONE suggested action — a single slash command or a single human-readable instruction. NOT a 4-item menu.>
+
+Full detail: <path>
 ```
-=== apt:spar — termination summary ===
-Topic: <one-line>
-Host: <cli-id>   Partner: <cli-id>   Rounds: <n>/<cap>
-Outcome: converged | held-disagreement | round-cap | partner-unreachable
-Converged position OR Held disagreement: <one-paragraph>
-
-Recommended next step:
-- continue: <best follow-up — usually `/apt:plan` or `/apt:execute`>
-- escalate: `/apt:roundtable "<topic>"` for a 10-agent debate
-- pause:    no further action; surface to the user for human input
+
+Constraints baked into the headline (do NOT relax):
+
+- **One sentence per round, max ~25 words.** No bullets, no nested lists.
+- **No code fences, no JSON, no ASCII tables inside the headline.** Schemas, trust models, verdict-per-round tables, and parallel-bug call-outs all go in the Layer 2 file — never in the headline.
+- **No trailing disposition question.** Do not append "Want me to file this?" or any similar re-ask. The autonomy policy in `<autonomy_interaction>` already governs whether the host pauses for user input; the headline does not re-prompt.
+- **Outcome vocabulary** is exactly one of: `converged`, `held-disagreement`, `round-cap`, `partner-unreachable`. Do not invent new outcome words. These are the terminal-outcome words for the spar as a whole; they are distinct from the §7 per-round verdict words (`cede` / `hold` / `next-round` / `partner-unreachable`) — `partner-unreachable` is the only word shared between the two vocabularies.
+- **`Full detail:`** names the path to the Layer 2 file written below.
+
+### Layer 2 — Persist the long-form (Path B)
+
+ALSO write a single markdown file at `.aperant/spar/<slug>-<YYYYMMDD-HHMMSS>.md` containing the verbatim long-form: the converged-position content (architecture, schemas, trust model), the verdict-per-round table, and any parallel-bug call-outs the spar surfaced. The headline's `Full detail:` line MUST reference this exact path.
+
+**Slug derivation.** Lowercase the topic; replace each run of non-`[a-z0-9]` characters with a single `-`; trim leading/trailing `-`; take the first 6 hyphen-separated tokens; truncate the resulting string to 40 chars; trim any trailing `-` left by truncation. Final form MUST match `^[a-z0-9-]{1,40}$` — the slug is interpolated directly into the path string, so any character outside `[a-z0-9-]` is a path-injection vector and must NOT survive this step. Example: topic `"Should we use Shape C++ for the IDL layer or stay with Shape B"` → tokens `should we use shape c for` (the `++` collapses with the trailing whitespace into a single `-`) → slug `should-we-use-shape-c-for` (24 chars; under the 40-char cap).
+
+**Timestamp format.** `YYYYMMDD-HHMMSS` (UTC, per-second granularity). Two spar invocations within the same second produce identical paths — acceptable risk for v1.1.
+
+**Write invocation.** Use the same single-quoted heredoc safety pattern §5 uses for prompt-quoting — the body is opaque text and may legitimately contain backticks, `$(...)`, or other shell-active characters that bash would otherwise expand:
+
+```bash
+mkdir -p .aperant/spar && cat > ".aperant/spar/<slug>-<YYYYMMDD-HHMMSS>.md" <<'APT_SPAR_LONGFORM_EOF'
+# apt:spar long-form — <topic>
+
+**Host:** <cli-id> · **Partner:** <cli-id> · **Rounds:** <n>/<cap> · **Outcome:** <outcome>
+
+## Converged position (or held disagreement)
+
+<verbatim long-form: architecture, schemas, trust model, etc.>
+
+## Verdict per round
+
+| Round | What host held | What partner caught | What host conceded |
+|-------|----------------|---------------------|--------------------|
+| 1     | ...            | ...                 | ...                |
+
+## Parallel call-outs
+
+<bugs / observations surfaced during sparring that are independent of the topic; omit the whole section if none>
+APT_SPAR_LONGFORM_EOF
 ```
 
-Nothing is written to disk — the termination summary is in-conversation output only (per SPAR-06).
+The `'APT_SPAR_LONGFORM_EOF'` (single-quoted heredoc terminator) is load-bearing — identical to the `APT_SPAR_PROMPT_EOF` convention in §5. It disables variable/command substitution inside the body so an attacker-controlled topic cannot execute commands.
+
+This file is write-once and is NOT loaded back into context on subsequent `apt:spar` runs — it is purely a preservation artifact for the user.
 
 </process>

package/dist/plugin/skills/apt-triage/AGENT-BRIEF.md

@@ -1,11 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/triage/AGENT-BRIEF.md
-Licensed under MIT. Modifications: aligned with Aperant's 5-state
-machine (needs-triage / needs-info / ready-for-agent / ready-for-human /
-wontfix) and the backend-pluggable mirror model (local-only / github-issues / app-inbox).
--->
-
 # Triage Agent Brief — what to do with each state
 
 ## needs-triage (inbound)

package/dist/plugin/skills/apt-triage/OUT-OF-SCOPE.md

@@ -1,10 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/triage/OUT-OF-SCOPE.md
-Licensed under MIT. Modifications: aligned with Aperant's pipeline
-(other skills exist for the out-of-scope concerns — explicit pointers).
--->
-
 # Triage Out-of-Scope
 
 What this skill is NOT. Knowing the boundary prevents triage from