@aperant/framework 0.6.6 → 0.7.0

package/skills/apt-release-notes/appendices/persona-voice.md

@@ -0,0 +1,59 @@
+# Persona-voice posture loader
+
+Aperant-authored posture loader consumed by `apt-release-notes/SKILL.md`.
+Per the CLAUDE.md `appendices/` convention, this file augments the parent
+skill's context — it is NOT independently router-invocable.
+
+## Why this exists
+
+The dev `CHANGELOG.md` (owned by `/apt:docs changelog`) describes WHAT
+changed in engineering terms: file paths, function names, task IDs,
+schema bumps. Release notes describe WHY the change matters to a
+specific human. Same merge, different voice. The release-notes pipeline
+hands you a structured fragment payload — your job is to tune the prose
+so the line reads like product-marketing copy for the persona, not like
+a commit message with the prefix stripped.
+
+## Posture rules (apply when composing a `Release note: …` line)
+
+1. **Verb first.** Start with the user's outcome — "See your shipped
+   builds in one tab" — not the implementation ("Added a `/builds` tab
+   to the dashboard"). The reader doesn't care that you added a tab;
+   they care that they can now see builds.
+2. **Persona-specific framing.**
+   - **End-user persona (audience: `end-user`)** — plain language, no
+     jargon. Avoid framework names, file paths, API endpoint paths.
+     One sentence. Concrete value.
+   - **Developer / API persona (audience: `developer-api`)** — API + SDK
+     semantics are the value proposition. Naming a new method is good.
+     Linking the migration page is good. Don't hide the implementation
+     details; they ARE the user-visible surface for this persona.
+   - **Internal-team persona (audience: `internal-team`)** — lighter
+     polish, faster cadence. One sentence is still ideal but the
+     internal team is fine with a touch of process-jargon ("we now
+     auto-rotate session tokens") when it conveys real value.
+3. **Triage bucket is your friend.** If you don't have strong signal
+   for the persona's framing — leave the line in the form the auto-draft
+   produced. The compile step will surface it under `## Needs Triage`
+   and the human curator can decide whether to ship it. Forced
+   confidence in the note voice is a regression class.
+4. **Tone matches the persona's archetype.** "The Vibe Coder" persona
+   wants energy ("Now you can branch off any session in one click").
+   "The Reviewer" persona wants precision ("Branch-from-session now
+   preserves your review queue with exact ordering"). Read the
+   archetype field in personas.json before composing.
+5. **No emoji unless the project's design taste explicitly calls for
+   it.** Aperant's house style is restrained; consumer-facing apps with
+   "playful" design tokens may differ — defer to the project's design
+   brief if one exists.
+
+## What this loader does NOT cover
+
+- Compile-time narrative beyond the per-PR sentence — that's the host
+  LLM's wider job at `/apt:release-notes --compile`, informed by
+  `PROJECT.md` Core Value, the personas roster, and the structured
+  per-tier sections the compiler writes.
+- Translating between audience values — picking the right audience is
+  set at `/apt:setup` Batch 9 time. The audience field doesn't change
+  mid-release; voice changes only at the per-fragment level inside the
+  audience already chosen.

package/skills/apt-setup/SKILL.md

@@ -120,7 +120,20 @@ Also check for global defaults at `~/.aperant/defaults.json` — if they exist a
 
 ## 1b. Review Mode (existing config detected)
 
-If `.aperant/config.json` already exists AND `--reset` was NOT passed, enter **review mode** instead of running all batches from scratch.
+**Canonical signal.** The `onboarding.completed` marker inside `.aperant/config.json` is the canonical signal that a user has walked through the full /apt:setup batch sequence. Structural completeness of the JSON config does NOT imply onboarding completeness — `packages/framework/templates/config.json` ships with all keys populated to sensible defaults by design, so the JSON alone cannot disambiguate "fresh seed" from "fully tuned." Future template additions must not assume otherwise.
+
+**Dispatch.** Read `.aperant/config.json` and inspect the `onboarding` block. Branch on the four marker states:
+
+| Marker state                                                | `/apt:setup` behaviour                                                |
+|-------------------------------------------------------------|-----------------------------------------------------------------------|
+| No `onboarding` block (legacy pre-fix config)               | enter **review mode** (preserve current behaviour; do NOT re-onboard) |
+| `onboarding.seeded_from_template: true` AND `onboarding.completed: false` | enter **full Batch 1-8 flow** (treat as fresh setup)      |
+| `onboarding.completed: true`                                | enter **review mode**                                                 |
+| `--reset` flag passed                                       | enter **full Batch 1-8 flow** always (overrides marker)               |
+
+`init` writes the `seeded_from_template: true` / `completed: false` marker on fresh seed only (see `packages/framework/src/cli/commands/init.mjs::applyInterviewAnswers`). The upgrade path never writes the marker — that is why a legacy unmarked config routes to review mode.
+
+If the dispatch lands you in review mode, continue below. If it lands you in the full flow, jump to **Step 2**.
 
 First, run host detection to show resolved orchestration:
 
@@ -175,6 +188,8 @@ AskUserQuestion([
       { label: "Orchestration", description: "Phase delegation, review mode, debate mode, agent teams" },
       { label: "Team Collaboration", description: "Enable/disable team mode — shared task board, roadmap, members" },
       { label: "Visibility", description: "Artifact-sharing policy — what leaves your machine (roadmap, team.json, decisions, digests, tasks)" },
+      { label: "Task Tracking", description: "Tracker backend (local-only / github-issues / app-inbox), publish to tracker, TDD default, prototype discipline" },
+      { label: "Changelog & Release Notes", description: "Internal dev changelog + opt-in user-facing release notes (audience, persona filter)" },
       { label: "Everything", description: "Re-run full setup from scratch" },
       { label: "Done", description: "Keep current settings" }
     ]
@@ -189,7 +204,8 @@ AskUserQuestion([
 - "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**
 - "Task Tracking" → jump to **Step 3g** (Batch 8 only), then skip to **Step 4** and **Step 5**
-- "Everything" → proceed to **Step 2** and run all batches (same as fresh setup)
+- "Changelog & Release Notes" → jump to **Step 3h** (Batch 9 only), then skip to **Step 4** and **Step 5**
+- "Everything" → proceed to **Step 2** and run all batches (same as fresh setup). **Legacy-completes-Everything marker write:** if the starting config has no `onboarding` block (legacy unmarked config) and the user completes the full flow, write a full `onboarding` block at Step 5 as `{ completed: true, seeded_from_template: false, seeded_at: <ISO-8601 now> }` to record the explicit onboarding pass.
 - "Done" → display "Settings unchanged." and exit
 
 For selective edits, **pre-fill the existing values** as the default selection in each question. The user can confirm or change. Unchanged values are preserved — do not overwrite the entire config, only merge the changed section.
@@ -978,6 +994,121 @@ Add a row to the Step 8 table:
 
 ---
 
+## 3h. Present Settings (Batch 9: Changelog & Release Notes)
+
+This batch captures the **persona-aware changelog + release-notes** preferences introduced by `apt-release-notes/SKILL.md`. Two top-level questions: (1) keep an internal dev `CHANGELOG.md` and (2) publish user-facing release notes. Q2 defaults to **No** on internal/library projects (per spec ID-7: the presence of `personas.json` does NOT auto-enable release-notes — opt-in must be explicit).
+
+If a host supports structured prompts (Claude Code), prefer `AskUserQuestion`. For non-structured hosts (Codex, Gemini-CLI plain mode), present each question as a numbered list and read the reply as a single number per question.
+
+### 3h.1 Present the dev-changelog picker
+
+```
+AskUserQuestion([
+  {
+    question: "Keep an internal dev changelog?",
+    header: "Dev Changelog",
+    options: [
+      { label: "Yes (Recommended)",
+        description: "Auto-update CHANGELOG.md from commits on every /apt:ship. Dev-flavored, internal." },
+      { label: "No",
+        description: "Skip the dev changelog entirely." }
+    ]
+  }
+])
+```
+
+### 3h.2 Present the release-notes picker
+
+```
+AskUserQuestion([
+  {
+    question: "Publish user-facing release notes?",
+    header: "Release Notes",
+    options: [
+      { label: "No (Recommended for internal / library projects)",
+        description: "Skip the user-facing surface entirely. Most projects pick this." },
+      { label: "Yes",
+        description: "Enable /apt:release-notes — auto-draft fragments on /apt:ship, compile at tag time." }
+    ]
+  }
+])
+```
+
+### 3h.3 If Yes — present the audience + persona-filter sub-pickers
+
+When Q2 = Yes, ask:
+
+```
+AskUserQuestion([
+  {
+    question: "Who is the primary audience for these release notes?",
+    header: "Audience",
+    options: [
+      { label: "End user",        description: "Plain-language, value-focused. Suits consumer apps." },
+      { label: "Developer / API", description: "Technical, references API + SDK semantics. Suits libraries." },
+      { label: "Internal team",   description: "Lighter polish, faster cadence. Suits company-internal apps." }
+    ]
+  },
+  {
+    question: "Which personas should drive the published notes?",
+    header: "Persona Filter",
+    options: [
+      { label: "Primary only",
+        description: "Only primary-tier personas surface in published notes." },
+      { label: "Primary + Secondary (Recommended)",
+        description: "Primary + secondary tiers. Default — balances signal with completeness." },
+      { label: "All personas",
+        description: "Every tier surfaces. Useful for marketplaces / multi-sided products." }
+    ]
+  }
+])
+```
+
+If `.aperant/personas.json` is absent and Q2 = Yes, emit a non-blocking hint:
+
+```
+[apt:setup] Note: .aperant/personas.json is missing. Release notes will work but every
+            fragment will land in `## Needs Triage` until you run /apt:personas.
+```
+
+This is a hint only — the user can still complete setup; the triage bucket is the intentional safety net (spec ID-6 never-silent-drop).
+
+### 3h.4 Map answers to `.aperant/config.json`
+
+Mapping rules (extend Section 4 below):
+
+| User picked | Config write |
+|---|---|
+| Q1: Yes | `changelog.dev.enabled = true` |
+| Q1: No | `changelog.dev.enabled = false` |
+| Q2: No  | `changelog.release_notes.enabled = false` (DEFAULT — leave audience + persona_filter at template defaults) |
+| Q2: Yes | `changelog.release_notes.enabled = true` and apply the audience + persona-filter sub-pickers |
+| Audience: End user        | `changelog.release_notes.audience = "end-user"` |
+| Audience: Developer / API | `changelog.release_notes.audience = "developer-api"` |
+| Audience: Internal team   | `changelog.release_notes.audience = "internal-team"` |
+| Persona filter: Primary only            | `changelog.release_notes.persona_filter = "primary"` |
+| Persona filter: Primary + Secondary    | `changelog.release_notes.persona_filter = "primary+secondary"` (DEFAULT) |
+| Persona filter: All personas           | `changelog.release_notes.persona_filter = "all"` |
+
+The remaining `release_notes` keys (`output_dir`, `require_pr_field`, `draft.*`, `compile.*`, `publish.*`) keep their template defaults from `packages/framework/templates/config.json` v5. Users wanting to override those edit `.aperant/config.json` directly — they are not surfaced through the Q-block to keep the picker short.
+
+Migration rule: any existing config WITHOUT a `changelog` block gets defaults silently from the template migrator (`migrateConfigSchema` in `src/cli/config/schema-migrate.mjs`) — this is the same auto_added path Batch 8 relies on for the `task_tracking` / `coding` blocks.
+
+### 3h.5 Review-Mode routing entry
+
+Extend the "1b. Review Mode" routing table (§1b) to include "Changelog & Release Notes" as a selectable edit target — jumping back into this Batch 9 picker.
+
+### 3h.6 Confirmation row
+
+Add a row to the Step 8 table:
+```
+| Changelog & Release Notes | dev: {Yes/No}; release-notes: {Yes/No} (audience: {value}, persona-filter: {value}) |
+```
+
+The selective-edit pass through Batch 9 MUST respect the §1b dispatch — it does NOT flip `onboarding.completed`. Marker writes are reserved for the full-flow / "Everything" branches.
+
+---
+
 ## 4. Map Answers to Config
 
 Map the user's selections to config values:
@@ -1034,7 +1165,7 @@ Note: task ids are slug-first since v0.6.6 — the date-format setting controls
 - "File (default)" → `diagram.mode: "file"`
 - "MCP (live canvas)" → `diagram.mode: "mcp"`
 
-If `.aperant/config.json` has no `diagram` block yet, also seed `diagram.mcpConsent: null` so the structure matches the template default. Existing `mcpConsent` records are preserved across mode flips (changing the mode does not invalidate prior consent for the same host).
+**Diagram MCP consent (per-user, FRAMEWORK-AUDIT-001).** The `diagram.mcpConsent` field is per-user and lives in `.aperant/config.local.json` (gitignored), NOT in the shared `config.json`. If `config.local.json` doesn't exist or has no `diagram.mcpConsent` field, seed `{diagram: {mcpConsent: null}}` in `config.local.json`. The `diagram.mode` field (file vs mcp) stays in `config.json` as team-shared policy and continues to seed there. Existing `mcpConsent` records in `config.local.json` are preserved across mode flips (changing the mode does not invalidate prior consent for the same host).
 
 **Orchestration (Auto mode):** "Auto (Recommended)" → all three fields set to `"auto"`:
 - `orchestration.phase_delegation: "auto"`
@@ -1149,6 +1280,7 @@ Display:
 | Review Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |
 | Debate Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |
 | Visibility           | {solo / team / oss} (overrides if any)        |
+| Changelog & Release Notes | dev: {Yes/No}; release-notes: {Yes/No} (audience, persona-filter) |
 | Saved as Defaults    | {Yes/No}                     |
 
 Config saved to: .aperant/config.json
@@ -1160,6 +1292,17 @@ Commands now use these settings automatically:
   /apt:setup        — change settings anytime
 ```
 
+### 8. (continued) Flip `onboarding.completed` on full-flow success
+
+After a successful **full Batch 1-8 pass** (i.e. the user came in via `--reset`, via the fresh-seed marker-state `seeded_from_template:true / completed:false`, or via the review-mode "Everything" option), patch `.aperant/config.json` to set `onboarding.completed: true`. **Preserve** the existing `seeded_from_template` and `seeded_at` fields untouched — they carry forensic value (debug "did init upgrade overwrite my config?"). Concretely:
+
+- Read the current `.aperant/config.json` you just wrote in **Step 5**.
+- Set `onboarding.completed = true`. If the `onboarding` block was already present, preserve the other fields verbatim.
+- If the starting config was a **legacy unmarked config** (no `onboarding` block — see §1b "Everything" routing), instead write the full block as `{ completed: true, seeded_from_template: false, seeded_at: <ISO-8601 now> }`.
+- Re-write `.aperant/config.json` with 2-space indentation.
+
+Selective edits in review mode (Verification, Pipeline, Orchestration, Team Collaboration, Visibility, Task Tracking) DO NOT flip the marker — only a full Batch 1-8 pass does.
+
 ### 8a. PreCompact Hook Status
 
 After confirming settings, check whether the framework's PreCompact hook is

package/skills/apt-ship/SKILL.md

@@ -146,6 +146,53 @@ Format as a markdown table:
 
 If no plan exists (ad-hoc task), list commits without subtask mapping.
 
+## 2.6 Release-note auto-draft (persona-aware release-notes opt-in)
+
+This section runs ONLY when `.aperant/config.json` has `changelog.release_notes.enabled === true`. When the toggle is `false` (the default for the 9-of-10 internal projects that never publish user-facing notes), skip the section entirely — do NOT compute the feature diff and do NOT touch the PR body draft.
+
+Read the toggle:
+
+```bash
+rn_enabled=$(jq -r '.changelog.release_notes.enabled // false' .aperant/config.json)
+```
+
+If `rn_enabled !== "true"`, jump to Section 3.
+
+### 2.6.1 Compute the feature-registry diff
+
+The auto-draft needs to know which features the PR's commits touched. Use the same `features-audit` surface that `apt:execute` uses post-step:
+
+```bash
+base=$(node packages/framework/bin/apt-tools.mjs task get . --id {task-id} | jq -r '.base_branch // "main"')
+feature_diff=$(node packages/framework/bin/apt-tools.mjs features-audit . --diff-since "$base" --json)
+```
+
+The envelope shape (see `packages/framework/src/cli/commands/features-audit.mjs`) returns the list of touched features with their declared `personas: []` field (when the registry's feature row carries one).
+
+### 2.6.2 Decide draft vs block via the helper
+
+Hand the diff + the project's personas envelope + the filter mode to `ship-autodraft.mjs`. The CLI returns one of three envelopes:
+
+- `{status: 'draft', line, persona, matchedFeatures}` — append `line` to the PR body draft built in Section 3.
+- `{status: 'block', reason, message}` — fire the block path below.
+- `{status: 'warn', reason, message}` — log the warning and proceed without the line.
+
+The block path triggers when `release_notes.require_pr_field === true` (default) AND auto-draft failed (no feature match OR no persona signal). The exact error string is locked by AC7:
+
+```
+[APT] No release-note signal found — author manual note in PR body or label PR no-notes
+```
+
+When the block fires, STOP — do NOT proceed to `gh pr create`. The user must either (a) author a manual `Release note: …` line in the PR body via `git commit --amend` (or by editing the PR body after open), or (b) label the PR `no-notes` via `gh pr edit --add-label no-notes` and re-run `/apt:ship`. The label-based escape hatch keeps the gate from blocking infra-only PRs that genuinely have no user-facing impact.
+
+### 2.6.3 Inject the line into the PR body draft
+
+When the helper returns `status: 'draft'`, append the `line` value verbatim to the PR body draft assembled in Section 3, immediately under the `## Summary` heading. The line is one sentence, persona-voice-tuned, suitable for a user-facing surface.
+
+### 2.6.4 Helper contract (for testability)
+
+The helper lives at `packages/framework/src/cli/release-notes/ship-autodraft.mjs`. It is a pure function — given the feature-diff envelope + personas envelope + filter mode + the `require_pr_field` toggle, it returns the decision. The `decideAutodraft` export is unit-tested via TD-4; the SKILL.md body wires it without re-deriving the decision logic.
+
 ## 3. Build PR Body
 
 **Title:** Derived from task description. Keep it short (<70 characters).
@@ -365,19 +412,30 @@ ci_watch_armed=$(echo "$ship_update" | jq -r '.ci_watch_armed // false')
 ci_watch_skip_reason=$(echo "$ship_update" | jq -r '.ci_watch_skip_reason // empty')
 ci_watch_host=$(echo "$ship_update" | jq -r '.ci_watch.host // "unknown"')
 ci_watch_deadline=$(echo "$ship_update" | jq -r '.ci_watch.deadline // empty')
+ci_watch_scheduler_handle=$(echo "$ship_update" | jq -r '.scheduler_handle // empty')
 host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host.capabilities.cron')
 ```
 
 **Autonomy interaction** (apply BEFORE branching, same rule as 7.1): when `autonomy === 3` (YOLO), degrade `ask` → `auto`.
 
-**Branch on the task-update envelope:**
+**Branch on the task-update envelope** (FRAMEWORK-BUG-018 — Track 1: distinguish state-recording from wake-registration):
 
-- **`ci_watch_armed=true` AND `host_cron=true`** — emit:
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` non-empty** — emit:
 
   ```
   [APT:ship] CI watcher armed (host cron: {ci_watch_host}). Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
   ```
 
+  This is the only honest "armed" case — a scheduler handle proves the wake is registered.
+
+- **`ci_watch_armed=true` AND `host_cron=true` AND `ci_watch_scheduler_handle` empty** — emit:
+
+  ```
+  [APT:ship] CI watcher state created (host: {ci_watch_host}). Register a wake-up to drive ticks: CronCreate every ~3min running '/apt:watch-ci --tick --pr {N}'. Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
+  ```
+
+  State is recorded but no scheduler is registered — the orchestrator MUST register a wake or ticks will never fire. Track 2 (auto-wake on arm) will populate `scheduler_handle` and route into the first branch instead.
+
 - **`ci_watch_armed=true` AND `host_cron=false`** — emit:
 
   ```
@@ -395,10 +453,11 @@ host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host
   On `Y` (or empty enter), call:
 
   ```bash
-  node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli}
+  arm_envelope=$(node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli})
+  ci_watch_scheduler_handle=$(echo "$arm_envelope" | jq -r '.scheduler_handle // empty')
   ```
 
-  Then emit the same host-cron-aware success banner used for `ci_watch_armed=true`. On `N` or any other response, proceed silently to Section 8.
+  Then route into the same four-way logic above — branch 1 (armed with handle), branch 2 (state-created, needs wake), or branch 3 (host has no cron). On `N` or any other response, proceed silently to Section 8.
 
 - **`ci_watch_skip_reason=disabled`** — silent. Proceed directly to Section 8.
 

package/skills/apt-spar/SKILL.md

@@ -129,14 +129,26 @@ If `--with` resolves to the same CLI as the host (e.g. `--with claude` when `hos
 
 Do NOT proceed; self-sparring is sycophancy by construction (the host cannot objectively challenge itself). This check runs after `host-detect` and before any partner availability check.
 
-**Partner unavailable.** If the resolved partner CLI binary or script is not on `$PATH` — or, for the codex-companion path, if `CLAUDE_PLUGIN_ROOT` is unset OR `${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs` does not exist — print a clean fallback and stop:
+**Partner transport ladder (FRAMEWORK-BUG-024).** Read `host.partner_transports.<partner>` from the host-detect envelope (`jq '.host.partner_transports.codex'`, etc.). Each partner has a 3-rung ladder evaluated in preference order — **MCP-first** for cleaner tool-call integration, with automatic fallthrough to plugin shim then raw CLI:
+
+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`).
+
+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."
+
+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:
 
 ```
-[apt:spar] partner `<id>` unavailable. Either:
-  - install the partner CLI (Codex: install the `codex` Claude Code plugin so `CLAUDE_PLUGIN_ROOT/scripts/codex-companion.mjs` resolves; Claude: install the `claude` CLI on $PATH; Gemini: install the `gemini` CLI on $PATH)
-  - re-run with `--with <other-id>` to pick a different partner
+[apt:spar] partner `<id>` unavailable. Tried:
+  - MCP tool `mcp__<partner>-mcp__*`: <not loaded in this host | runtime-host-only + timed out at <ms>ms>
+  - Plugin shim `${CLAUDE_PLUGIN_ROOT}/scripts/<partner>-companion.mjs`: <missing reason>
+  - Raw CLI `<bin>` on $PATH: not found
+Install any one of the three or re-run with `--with <other-id>`.
 ```
 
+The failure message MUST name all three transports tried (`mcp`, `plugin shim`, `raw CLI`) so the user can pick the cheapest fix.
+
 Do NOT silently degrade to the host (sparring with yourself is sycophancy by construction).
 
 ## 4. Frame the Round
@@ -159,13 +171,26 @@ The frame is one shot per round — no multi-turn conversation with the partner
 
 **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.
 
-The table below shows the canonical command shape; the actual invocation MUST use the heredoc pattern in the next subsection — never raw double-quoted interpolation.
-
-| Host | Command | Notes |
-|---|---|---|
-| `host=claude-code` (or `--with codex`) | `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. |
-| `host=codex` (or `--with claude`) | `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. |
-| `--with gemini` (any host) | `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. |
+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.
+
+<!--
+  Future contributor: the `codex exec` flag below is taken from the precedent
+  at `packages/framework/skills/apt-pr-review/SKILL.md:1084`. Codex CLI flag
+  surface evolves; verify with `codex --help` at execution time and update
+  this table if the non-interactive invocation shape changes.
+-->
+
+| 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 | 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 | 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 | 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).
 

package/skills/apt-update/SKILL.md

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Bash, Read, Write"
-argument-hint: "apt:update"
+argument-hint: "apt:update [--from-source]"
 gates: []
 ---
 
@@ -42,35 +42,101 @@ The cache file is at `~/.cache/aperant/apt-update-check.json`. It contains `runt
 
 ## 1. Read current state
 
+<!-- TODO(followup): support PATH-only / npx-only kernel installs. The
+     hardcoded `.aperant/deps/...` path below fails users who don't have a
+     project-local kernel directory. Tracked as a separate task. -->
 ```bash
 node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs check-version . --json
 ```
 
-Parse the 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`). Capture:
+
 - `framework.installed_version` — what's currently on disk
-- `framework.latest_version` — what's in the source / published
+- `framework.latest_version` — what npm reports as the latest published version (MAY BE `null` when the worker cache is stale / missing / wrong schema)
 - `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`
+- `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.)
+
+The envelope is **single-shape** — every field above is always present. When the worker cache is stale or missing, `latest_version` is `null`, the four booleans are `false`, `stale_files_total` falls back to a local-only count, and `lookup_error` is `null`. Your parser doesn't need to branch on cache freshness.
 
 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
+
+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.
+
+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:
+
+```bash
+npm view @aperant/framework version --fetch-timeout=10000 --fetch-retries=0 --json --silent 2>/dev/null || true
+```
+
+On Linux/macOS with GNU coreutils installed, you MAY additionally wrap with a hard shell-level timer: `timeout 10 npm view ...` (Linux) or `gtimeout 10 npm view ...` (macOS via `brew install coreutils`). Shell-level wrapping is optional — `--fetch-timeout=10000` alone is sufficient because it is universal. Do NOT rely solely on the shell `timeout` command without the npm flag, as it is not available on all systems.
+
+If npm exits non-zero or times out, surface a one-line warning (`⚠ npm view failed — using local kernel`) and proceed; the local kernel still works for the runtime refresh, just at the older version.
+
+**Security (SEC-001):** Before interpolating `latest_version` into any shell command, verify it matches the semver pattern `^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$`. If it does not match, treat it as missing and fall back to the explicit version pinning path (proceed with the local kernel version, surface `⚠ latest_version invalid — using local kernel`). This protects against a poisoned cache entry reaching a shell command.
+
+When `installed_version < latest_version`, bump:
+
+```bash
+npm install --prefix .aperant/deps @aperant/framework@<latest_version> --no-save --no-package-lock --no-audit --no-fund
+```
+
+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)
+
+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.
+
+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`.
+
+Walk up from the project root looking for a sibling `packages/framework/package.json`. When found AND its `name === "@aperant/framework"`:
+
+```bash
+# 1. Pack the workspace source into a versioned tarball.
+cd <workspace-root>
+pnpm --filter @aperant/framework pack --pack-destination /tmp
+
+# 2. Install the tarball into the project's kernel root.
+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.
+
 ## 2. Classify the update scenario
 
-Pick ONE of three scenarios based on what you just parsed:
+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.
-- **B. Drift only** — `installed_version === latest_version` but `stale_files_total > 0`. User hand-edited an installed file or something was partially overwritten.
-- **C. Nothing to do** — `installed_version === latest_version` AND `stale_files_total === 0`. Still re-run init to refresh the update-check cache, but tell the user plainly that no changes were applied.
+- **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.
+- **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.
 
 ## 3. Re-install the currently-installed runtimes
 
-Build the flags list from the runtime ids (e.g. `--claude --codex`) and run:
+Build the flags list from the runtime ids (e.g. `--claude --codex`) and pass `--force-runtimes` so init bypasses the `upgrade_noop` short-circuit (Bug 2 fix, 0.6.7) and re-stamps every manifest:
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . --claude --force-runtimes
+```
+
+Example with multiple runtimes installed:
 
 ```bash
-node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . <flags>
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . --claude --codex --force-runtimes
 ```
 
-**Do NOT add `--yes`, `--solo`, `--team`, or any other Class A flag.** This command is meant to refresh runtime files only — adding `--yes` triggers a config schema migration that can silently flip `share.visibility` to `solo` and re-write `.gitignore`, which is exactly the 0.6.0/0.6.1 dogfood bug. If `init` returns a `requires_input` envelope (schema drift), surface it to the user verbatim and stop; let them decide team vs solo with the explicit flag. From 0.6.4 onward `--yes` infers visibility from existing git tracking, but the skill must still not add it — keep this command scoped to runtime refresh.
+**Do NOT add `--yes`, `--solo`, `--team`, or any other Class A flag.** This command is meant to refresh runtime files only — adding `--yes` triggers a config schema migration that can silently flip `share.visibility` to `solo` and re-write `.gitignore`, which is exactly the 0.6.0/0.6.1 dogfood bug. `--force-runtimes` is the ONLY new flag this skill adds. If `init` returns a `requires_input` envelope (schema drift), surface it to the user verbatim and stop; let them decide team vs solo with the explicit flag. From 0.6.4 onward `--yes` infers visibility from existing git tracking, but the skill must still not add it — keep this command scoped to runtime refresh.
 
 Parse the init JSON. Capture for each runtime:
 - `install_root` (shortened to the basename, e.g. `.claude`)
@@ -164,5 +230,6 @@ Runtime files were still refreshed; `/apt` will still work from PATH if `apt-too
 - **Worker hasn't run yet**: the cache file is missing. That's fine — run check-version directly (step 1 is robust to a missing cache). Proceed normally.
 - **Re-install fails (non-zero exit from init)**: surface the JSON `error` field verbatim in a single line, then stop. Do NOT delete the cache file — the chip should remain visible so the user sees the failure persists.
 - **Kernel install fails but runtime install succeeds**: see Scenario D above. Do not treat this as a total failure; the user's skills still work via PATH fallback.
+- **CLAUDE.md / AGENTS.md foreign rows (exit 2, `instruction-file.foreign-rows`)** — 0.7.0+ — init now refuses to silently clobber custom rows in the `<!-- APT:framework-* -->` block. If `init` exits 2 with `code: instruction-file.foreign-rows`, the `foreignRowIds[]` field lists the rows the generator did NOT produce. Two paths: (a) remove the foreign rows from CLAUDE.md / AGENTS.md by hand and re-run init, or (b) re-run with `--force-overwrite-catalog` to regenerate anyway. Unattended upgrade flows should detect this code and surface it to the operator — silent bypass is a regression.
 
 </edge_cases>

package/skills/apt-watch-ci/SKILL.md

@@ -69,8 +69,8 @@ Watcher already running for PR {N} (held by sessionId={x}, pid={y}); exiting.
 
 For the `--tick` mode, execute exactly the following sequence — once — inside this single skill invocation:
 
-1. **Poll.** Call `gh pr checks <N> --json name,bucket,state,conclusion,detailsUrl` and `gh pr view <N> --json state,reviewDecision`. On any `gh` failure, write the captured stderr to a temp file and let the cmd's `tick` route to `infra-backoff` (it surfaces the same action when the gh payload is unavailable).
-2. **Classify + state update.** Call `apt-tools ci-watch tick {worktree} --pr {N}`. The cmd internally:
+1. **Poll.** Call `gh pr checks <N> --json name,bucket,state,conclusion,detailsUrl` and `gh pr view <N> --json state,reviewDecision`. Combine both JSON outputs into a single file shaped `{checks: <pr-checks-json>, prMetadata: <pr-view-json>}` (for example with `jq -s '{checks: .[0], prMetadata: .[1]}'`) and save it as `{captured.json}` (any path under the worktree is fine). On any `gh` failure, omit the file and let the cmd's `tick` route to `infra-backoff` (it surfaces the same action when no payload is available).
+2. **Classify + state update.** Call `apt-tools ci-watch tick {worktree} --pr {N} --payload-file {captured.json}`. The cmd reads `{captured.json}` from disk and runs the classifier — it does NOT shell out to `gh` itself (that boundary stays with the orchestrator skill; see commands/ci-watch.mjs:15). The cmd internally:
    - acquires the per-PR lock (BUSY → exit 2 → step §2);
    - reads the per-PR state file;
    - runs the stop-matrix classifier (`packages/framework/src/cli/ci-watch/stop-matrix.mjs`);
@@ -87,7 +87,10 @@ For the `--tick` mode, execute exactly the following sequence — once — insid
 
 When `action ∈ {green, merged, closed, attempts-cap, wall-cap, identical-log}`:
 
-- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`. Else print the exact D-08 text:
+- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`.
+  - **DO NOT pass `--delete-branch`** to `gh pr merge` from this auto-merge path — ever, unconditionally. The watcher's cwd is the task worktree, where `gh`'s `--delete-branch` post-merge cleanup tries to `git switch <base>` and fails because `<base>` is checked out in the primary worktree. The remote merge has already succeeded by then; local branch + worktree cleanup is `/apt:close-task`'s job via `apt-tools task close-merged` → `computeWorktreeCleanup` (see FRAMEWORK-BUG-019).
+
+  Else print the exact D-08 text:
 
   ```
   ✅ CI green — merge in browser or run /apt:close-task post-merge