@aperant/framework 0.8.0 → 0.8.4

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>
@@ -52,7 +52,7 @@ Hard rule, v1: **no artifact directory written.** The transcript stays in-conver
 - 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>
@@ -90,7 +90,7 @@ Parse `$ARGUMENTS`. Extract:
   `[apt:spar] --rounds clamped to 3 (hard cap, see SPAR-05)`
   and proceed with N=3. If N<1, clamp to 1 and print:
   `[apt:spar] --rounds clamped to 1 (minimum)`
-- `--timeout-ms N` — per-partner Bash timeout in milliseconds, default 90000 (90s). Capped at 600000 (10m, the Bash tool's own ceiling).
+- `--timeout-ms N` — per-partner Bash timeout in milliseconds, default 300000 (5 min). Capped at 600000 (10 min, the Bash tool's own ceiling).
 - `[topic]` — the remaining text after flags. If empty, frame the round from the **last N conversation turns** as the context.
 
 Also read (best-effort, skip silently if missing):
@@ -135,7 +135,7 @@ Do NOT proceed; self-sparring is sycophancy by construction (the host cannot obj
 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`).
 
-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 60000ms, configurable via `apt-spar.mcp_timeout_ms` in `.aperant/config.json`. Empirical: the Codex MCP `claude_code` tool has been observed to hang past 120s. 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."
+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."
 
 If all three rungs are unavailable (every rung `detected: false`, or MCP `runtime-host-only` timed out AND rungs 2+3 are `detected: false`), print:
 
@@ -163,13 +163,14 @@ You are the sparring partner in an apt:spar round. Your job:
 - Identify the strongest objection.
 - Cite specific evidence where possible (file:line, test output, doc reference).
 - Be specific, not generic — "this might fail" is not a finding; "this fails when X because Y" is.
+- After your main objection, provide NEXT_WEAKEST_POINT: one additional independent objection that would still matter if your first point is resolved. This populates the next round's frame.
 ```
 
 The frame is one shot per round — no multi-turn conversation with the partner inside a single round.
 
 ## 5. Invoke Partner (with timeout)
 
-**Wrap every partner Bash call with an explicit timeout** (default 90000ms, override via `--timeout-ms`). The empirical reason: the Codex MCP `claude_code` tool has been observed to hang past 120s while the `claude -p` CLI returns in seconds. A hung partner CLI must NOT stall the spar loop.
+**Wrap every partner Bash call with an explicit timeout** (default 300000ms (5 min), override via `--timeout-ms`). The empirical reason: heavy-research partner CLIs (especially Claude Code in `--with claude` mode) routinely spend multiple minutes doing genuine Read/Grep/Bash investigation per round, and a hung partner CLI must NOT stall the spar loop indefinitely.
 
 The table below shows the canonical command shape per (partner × rung); the actual invocation for shell-based rungs (plugin shim, raw CLI) MUST use the heredoc pattern in the next subsection — never raw double-quoted interpolation. The MCP rung is a structured tool call — no shell quoting concern applies.
 
@@ -182,19 +183,19 @@ 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. 60s timeout (configurable `apt-spar.mcp_timeout_ms`); on timeout fall through to plugin then CLI. |
+| 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`. |
-| claude | mcp | tool call: `mcp__claude-code-mcp__claude_code({prompt})` | Preferred. Same 60s timeout + fallthrough rule. |
+| 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 60s timeout + fallthrough rule. Any `mcp__gemini-mcp__*` tool satisfies the rung. |
+| 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. |
 
-Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 90000).
+Set the Bash tool's `timeout` parameter to `--timeout-ms` (default 300000).
 
-**Timeout calibration.** The 90s default is a conservative ceiling sized for worst-case Codex hangs (empirical: the `claude_code` MCP tool has been observed timing out at 120s while `claude -p` returns in seconds). A single unified ceiling simplifies the loop-control logic and avoids per-partner special-casing in v1. For tighter budgets, pass `--timeout-ms` explicitly; future versions may introduce per-partner defaults.
+**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.
 
 **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:
 
@@ -284,7 +285,9 @@ After each round, print a verdict block (one of these four, exact format):
 
 ## 8. Loop Control (max 3 rounds)
 
-- If `verdict=cede` → **converge, terminate** unilaterally. The host has accepted the partner's prior claim with cited evidence; no second partner turn is needed.
+- If `verdict=cede` AND `--rounds 1` was explicit → terminate this round.
+- If `verdict=cede` AND `--rounds >= 2` (default) → emit `next-round` regardless: convergence requires TWO consecutive rounds with the same disposition AND no materially new evidence. Round 1 alone cannot terminate as converged.
+- The host's `next-round` payload for Round 2 MUST include: (a) the cited evidence that confirmed the partner's Round 1 point, (b) a request to challenge the host's cited evidence with the partner's NEXT_WEAKEST_POINT.
 - If `verdict=hold` → only triggers `next-round` (partner gets the new evidence). There is no terminal `hold` convergence in a single round. If the round cap is reached with hold still active, the held position stands and the loop exits via the round-cap path below.
 - If `verdict=next-round` → invoke the partner again with the new evidence the host just cited, go to Step 4.
 - If the round counter hits **3 rounds** (or whatever `--rounds N` clamped to) → **terminate** with:
@@ -295,21 +298,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

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

@@ -31,8 +31,8 @@ This skill moves a task through a 5-state machine. The state machine
 runs identically regardless of backend (local-only / github-issues /
 app-inbox); only the mirror destination changes.
 
-**Pocock adoption attribution.** State machine + AGENT-BRIEF.md +
-OUT-OF-SCOPE.md sub-files ported from Matt Pocock's MIT-licensed
+**Aperant adoption attribution.** State machine + AGENT-BRIEF.md +
+OUT-OF-SCOPE.md sub-files ported from 
 `triage` skill. Aperant-specific extensions:
 
 - Backend abstraction (configured at `apt:setup` Batch 8 — task_tracking.backend)