@aperant/framework 0.8.0 → 0.8.4

package/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/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>
@@ -298,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/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/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/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)

package/skills/apt-update/SKILL.md

@@ -49,13 +49,14 @@ The cache file is at `~/.cache/aperant/apt-update-check.json`. It contains `runt
 node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs check-version . --json
 ```
 
-Parse the JSON. From 0.6.7 the envelope merges the SessionStart worker's cache (when fresh — written within the last hour to `~/.cache/aperant/apt-update-check.json`). Capture:
+Parse the JSON. From 0.6.7 the envelope merges the SessionStart worker's cache (when fresh — written within the last hour to `~/.cache/aperant/apt-update-check.json`). From 0.8.3 it also carries the workspace-aware `framework.workspace_version` field (Bundle A). Capture:
 
 - `framework.installed_version` — what's currently on disk
 - `framework.latest_version` — what npm reports as the latest published version (MAY BE `null` when the worker cache is stale / missing / wrong schema)
+- `framework.workspace_version` — set when a workspace `packages/framework/package.json` (with `name === "@aperant/framework"`) is found above the project root; null otherwise. When non-null AND ahead of `installed_version`, the workspace is the source of truth for self-host contributors (auto-detect, no `--from-source` required).
 - `runtimes[]` — list of installed runtime ids + per-runtime `stale_files` count
 - `stale_files_total` — drift tally across runtimes
-- `update_available` — true when worker cache is fresh AND `installed_version < latest_version`
+- `update_available` — true when worker cache is fresh AND `installed_version < latest_version`, OR when `workspace_version > installed_version` (Bundle A — fires regardless of npm cache state)
 - `dev_install_ahead` — true when local kernel is ahead of published (typical local dev)
 - `not_published` — true when npm returned 404 (package not yet on registry)
 - `lookup_error` — non-null when npm view failed for any non-404 reason (timeout, ENETDOWN, etc.)
@@ -64,11 +65,20 @@ The envelope is **single-shape** — every field above is always present. When t
 
 If `runtimes[]` is empty, tell the user they haven't installed Aperant into any runtime yet and suggest `apt-tools init . --claude` (or their preferred runtime). Stop.
 
-## 1.5. Bump the local kernel from npm when newer is available
+## 1.5. Workspace-aware bump — auto-detect dev-host self-host (Bundle A)
 
-The Aperant kernel lives at `.aperant/deps/node_modules/@aperant/framework/`. `apt-tools init` re-installs runtime files at THE LOCAL KERNEL'S VERSION — so a stale kernel means `/apt:update` re-stamps manifests at the OLD version even when npm has a newer release. Bump the kernel BEFORE invoking init.
+The Aperant kernel lives at `.aperant/deps/node_modules/@aperant/framework/`. `apt-tools init` re-installs runtime files at THE LOCAL KERNEL'S VERSION — so a stale kernel means `/apt:update` re-stamps manifests at the OLD version. Bump the kernel BEFORE invoking init.
 
-First, resolve `latest_version` when the envelope had `null` (stale cache).
+**FIRST**, branch on `framework.workspace_version` from step 1's envelope (Bundle A — automatic on every `/apt:update` run, no flag required):
+
+- When `workspace_version` is non-null AND ahead of `installed_version` — the user is an Aperant contributor self-hosting the framework, and a same-PR change bumped `packages/framework/package.json:version`. The workspace is the source of truth (NOT npm). Proceed to §1.7's workspace-pack mechanism. Skip §1.6 (npm view).
+- When `workspace_version` is null OR equal to `installed_version` — no workspace package, OR workspace + kernel already match. Fall through to §1.6 (npm bump path).
+
+This auto-detection replaces the previous "user must remember `--from-source`" footgun. The `--from-source` flag is still honored as an explicit override (§1.7) for: (a) testing pre-publish bumps even when auto-detect didn't fire, (b) forcing the workspace path when a stale `latest_version > workspace_version`.
+
+## 1.6. Bump the local kernel from npm when newer is available
+
+When §1.5 fell through (no workspace-ahead signal), resolve `latest_version` from npm. First, resolve `latest_version` when the envelope had `null` (stale cache).
 
 **Timeout enforcement (ID-04):** The `npm view` call must complete within 10 s — never block the user longer than the SessionStart worker would. Use npm's `--fetch-timeout` flag as the primary mechanism (universally portable across all npm versions); it sets the HTTP fetch timeout in milliseconds:
 
@@ -90,17 +100,47 @@ npm install --prefix .aperant/deps @aperant/framework@<latest_version> --no-save
 
 On `npm 404` (`E404` in stderr) treat it as `not_published` and skip the kernel bump (proceed to step 3). On any other npm failure, surface the npm stderr verbatim and STOP — do NOT proceed to init with a half-installed kernel.
 
-## 1.6. Self-host case — bump from local workspace (FRAMEWORK-BUG-017)
+## 1.7. Self-host case — bump from local workspace (FRAMEWORK-BUG-017)
+
+Fires when EITHER §1.5's workspace-ahead auto-detect signaled it, OR the user invoked `/apt:update --from-source` as an explicit override, OR the route envelope's `update_check.reason` mentions `workspace source ahead of installed kernel`. The source of truth is the local `packages/framework/` workspace — NOT npm. This is the Aperant-contributor self-host case: a same-PR framework fix bumps the workspace `packages/framework/package.json:version` but the kernel under `.aperant/deps/node_modules/@aperant/framework/` still reflects the previous version. §1.6's `npm view` would fetch the published version (still the OLD one), so we skip it.
+
+The reliable bump mechanism is the `apt-tools install-from-source` subcommand (Bundle D), which packs the framework AND every `workspace:*` dep (transitively) into a single `npm install --prefix` invocation. Handles the same-PR unpublished-pair case (e.g. `framework@0.8.3` + `driver-sdk@0.2.0` both at `workspace:*`, both unpublished) without `EUNSUPPORTEDPROTOCOL`.
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs install-from-source . --json
+```
+
+Parse the returned envelope:
+
+```json
+{
+  "status": "ok",
+  "command": "install-from-source",
+  "tarballs": ["/tmp/aperant-driver-sdk-0.2.0.tgz", "/tmp/aperant-framework-0.8.3.tgz"],
+  "kernel_path": "/path/to/project/.aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs"
+}
+```
+
+Capture `tarballs[]` count and `kernel_path` for the Scenario A summary line (the kernel-version slot reads from `kernel_path`'s parent `package.json` rather than a static `{latest_version}` format string when this branch fired).
+
+On `status: 'error'`, the envelope carries an `error` field with the underlying failure (e.g. `pnpm pack ... exited with N`, `no @aperant/framework workspace found`, etc.). Surface it verbatim and STOP — do NOT proceed to init with a half-installed kernel.
+
+If `--from-source` was passed but `install-from-source` returns `no @aperant/framework workspace found`, surface a one-line error (`⚠ --from-source: no workspace package.json found — falling back to npm`) and proceed with the standard §1.6 npm path.
+
+Then proceed to step 3 to re-install the runtime files at the new kernel version. Skip step 4 (cache clear) — the cache is keyed on `latest_version` from npm, and a `--from-source` bump never wrote to it, so there's nothing to invalidate.
 
-When the user invokes `/apt:update --from-source` OR the route envelope's `update_check.reason` mentions `workspace source ahead of installed kernel`, the source of truth is the local `packages/framework/` workspace — NOT npm. This is the Aperant-contributor self-host case: a same-PR framework fix bumps the workspace `packages/framework/package.json:version` but the kernel under `.aperant/deps/node_modules/@aperant/framework/` still reflects the previous version. Step 1.5's `npm view` would fetch the published version (still the OLD one), so we must skip it.
+### What `install-from-source` does under the hood
 
-The reliable bump mechanism mirrors what `runKernelInstall` does today — `pnpm pack` produces a versioned tarball, then `npm install --prefix` consumes it. Symlinking is fragile across re-installs and `pnpm install --filter` doesn't relocate the published artifact into `.aperant/deps`.
+The `apt-tools install-from-source` helper materializes the workspace chain end-to-end. This is the equivalent manual recipe — useful for debugging or for users who want to understand the mechanism. **Prefer the one-line invocation above** unless you have a reason to do it by hand:
 
-Walk up from the project root looking for a sibling `packages/framework/package.json`. When found AND its `name === "@aperant/framework"`:
+⚠ Do NOT substitute `npm pack` — it leaves `workspace:*` literal in the tarball's package.json and breaks `npm install --prefix` with `EUNSUPPORTEDPROTOCOL`. Only `pnpm pack` resolves workspace protocols.
 
 ```bash
-# 1. Pack the workspace source into a versioned tarball.
+# 0. Ensure the dep closure is materialized — the `...` suffix installs transitive workspace deps.
 cd <workspace-root>
+pnpm install --filter @aperant/framework... --frozen-lockfile=false
+
+# 1. Pack the workspace source into a versioned tarball.
 pnpm --filter @aperant/framework pack --pack-destination /tmp
 
 # 2. Install the tarball into the project's kernel root.
@@ -108,19 +148,16 @@ cd <project-root>
 npm install --prefix .aperant/deps /tmp/aperant-framework-<version>.tgz --no-save --no-package-lock --no-audit --no-fund
 ```
 
-Replace `<version>` with the workspace `package.json:version` you just read. The tarball name follows npm's `pack` convention (`@aperant/framework@X.Y.Z` → `aperant-framework-X.Y.Z.tgz`).
-
-If `--from-source` was passed but no `packages/framework/package.json` is found anywhere above the project root, surface a one-line error (`⚠ --from-source: no workspace package.json found — falling back to npm`) and proceed with the standard step 1.5 npm path.
-
-Then proceed to step 3 to re-install the runtime files at the new kernel version. Skip step 4 (cache clear) — the cache is keyed on `latest_version` from npm, and a `--from-source` bump never wrote to it, so there's nothing to invalidate.
+The manual recipe DOES NOT handle workspace:* deps transitively — for a same-PR pair (framework + driver-sdk both at `workspace:*`), you would need to pnpm-pack each dep separately and pass every tarball to the single `npm install --prefix` call. The `apt-tools install-from-source` subcommand walks `dependencies` + `peerDependencies` automatically.
 
 ## 2. Classify the update scenario
 
 Pick ONE of three scenarios based on what you parsed in step 1:
 
-- **A. Version bump available** — `installed_version !== latest_version` (regardless of drift). Users see this most often. Step 1.5 bumped the kernel; step 3 re-stamps manifests at the new version.
-- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten. Step 1.5 was a no-op; step 3 still needs `--force-runtimes` to re-stamp.
+- **A. Version bump available** — `latest_version != null && installed_version !== latest_version` (regardless of drift). Users see this most often. Step 1.5 (workspace) or 1.6 (npm) bumped the kernel; step 3 re-stamps manifests at the new version. **Important:** the `latest_version != null` guard prevents this scenario from firing when npm-latest is unknown (cache stale, package not published, network down — see Scenario E for that case).
+- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten. Steps 1.5 / 1.6 were no-ops; step 3 still needs `--force-runtimes` to re-stamp.
 - **C. Nothing to do** — `installed_version === latest_version` AND `stale_files_total === 0`. Still re-run init with `--force-runtimes` to refresh manifests + cache, but tell the user plainly that no version change happened.
+- **E. No version info available** — `latest_version === null` (cache stale OR package not published OR network down) AND `stale_files_total === 0`. Step 1.5 was a no-op (no workspace-ahead signal), step 1.6 found no usable npm version. Step 3 still re-stamps runtime files for safety, but the skill does NOT claim a version bump happened.
 
 ## 3. Re-install the currently-installed runtimes
 
@@ -169,6 +206,7 @@ Use the format in `<output_format>` below, tailored to the scenario from step 2.
   {install_root_basename}     {file_count} files refreshed
   {install_root_basename}     {file_count} files refreshed
   .aperant/deps/   kernel v{latest_version}
+  Migrated:        legacy .codex/agents/* swept ({removed_count} files removed)
 
   Next: restart Claude Code / Codex to activate the refreshed skills.
 ```
@@ -194,6 +232,7 @@ Example:
 
   {install_root_basename}     {file_count} files ({stale_count} refreshed)
   {install_root_basename}     {file_count} files
+  Migrated:        legacy .codex/agents/* swept ({removed_count} files removed)
 
   Statusline chip cleared.
 ```
@@ -205,10 +244,28 @@ Example:
 
   {install_root_basename}   {file_count} files
   {install_root_basename}   {file_count} files
+  Migrated:                 legacy .codex/agents/* swept ({removed_count} files removed)
 
   No changes applied. Statusline cache cleared.
 ```
 
+## Scenario E — no version info available
+
+```
+⚠ Aperant version info unavailable — refreshed runtime files only
+
+  Reason: {lookup_error || 'cache stale / not published'}
+  {install_root_basename}   {file_count} files
+  {install_root_basename}   {file_count} files
+  Migrated:                 legacy .codex/agents/* swept ({removed_count} files removed)
+
+  Run /apt:update again later to bump the kernel when npm view becomes reachable.
+```
+
+Scenario E fires when `latest_version === null` AND `stale_files_total === 0`. Step 1.5 (workspace-aware) was a no-op (no workspace-ahead signal); step 1.6 (npm view) returned null (cache stale, not published, or network down). The runtime refresh in step 3 still happens — the skill just does NOT claim a bump occurred.
+
+**`Migrated:` slot — conditional render.** The `Migrated:` line in Scenarios A / B / C / E fires ONLY when `init.legacy_cleanup?.ran === true && init.legacy_cleanup.rmdirs.some(p => p.includes('.codex'))`. When no migration happened, OMIT the line entirely (do NOT render an empty placeholder). The label reports the legacy Codex topology sweep (v0.7/v0.8 `.codex/agents/` + `.codex/commands/` misdirect → v0.8.2+ canonical `.agents/skills/<folder>/SKILL.md`) so users understand what changed under `.codex/` on disk.
+
 ## Scenario D — kernel install failed
 
 If init's `kernel.status !== "installed"`, append a warning ABOVE the summary:

package/skills/apt-verify-proof/SKILL.md

@@ -40,9 +40,56 @@ an action, evidence, and a verdict. No hallucinated passes.
 - For code review — use `/apt:review`
 - If no UI/visual changes were made — `/apt:verify` is faster
 
+## Driver Architecture
+
+`/apt:verify-proof` is **runtime-agnostic** — the workflow refers to IDL
+verbs (`driver.click`, `driver.screenshot`, `driver.navigate`, ...) and
+NEVER to concrete MCP tool names (per ID-01). The driver layer at
+`packages/framework/drivers/<id>/` maps verbs to transports.
+
+### Auto-detect
+
+The resolver auto-selects the highest-scoring driver per ID-02
+(capability_coverage > compatibility > stability > priority > locality).
+Preview the selection before running verify-proof:
+
+```bash
+apt-tools detect-runtime .
+# → { runtime: {is_electron, is_nextjs, ...}, selected_driver_id: "..." }
+```
+
+### Override
+
+Force a specific driver chain in `.aperant/config.json`:
+
+```json
+{ "verification": { "runtimes": ["electron", "cli"] } }
+```
+
+### Bundled drivers (4)
+
+- **browser** (priority=100, ga) — Next.js / vanilla web frontends.
+- **electron** (priority=90, ga) — Electron desktop apps.
+- **cli** (priority=60, ga) — headless CI, output-shape assertions.
+- **api** (priority=50, ga) — HTTP / JSON-API regression tests.
+
+### Driver authors
+
+Third-party driver authors should run `apt-tools driver doctor .` before
+publishing to validate manifest schema + IDL conformance:
+
+```bash
+apt-tools driver doctor .
+# → { drivers: [{driverId, manifest_valid, idl_conformant, ...}], summary: {...} }
+```
+
+See `@aperant/driver-sdk` for the IDL types, error taxonomy, and
+conformance kit.
+
 ## Execution
 
-Execute the verify-proof workflow end-to-end:
+Execute the verify-proof workflow end-to-end using IDL verbs (the driver
+maps verbs to its transport — MCP server, local command, HTTP):
 
 <execution_context>
 @packages/framework/workflows/verify-proof.md