@aperant/framework 0.6.6 → 0.6.7

package/skills/apt-release-notes/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: apt:release-notes
+description: "Persona-aware user-facing release notes — draft, compile, publish"
+apt-skill-version: {{APT_VERSION}}
+stage: ops
+intent: capture
+when_to_use: "The user wants to draft, compile, or publish persona-aware user-facing release notes for a project that opted in via /apt:setup."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_track: DEEP
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:release-notes [--draft --pr <n> | --compile <tag> | --publish <tag>]"
+gates: []
+---
+
+<objective>
+Produce user-facing release notes for a project that opted in via
+`/apt:setup` → Batch 9 → "Publish user-facing release notes? Yes". This
+skill is separate from `/apt:docs changelog` — the dev-flavored
+`CHANGELOG.md` surface stays its responsibility; this skill owns the
+persona-voice-tuned narrative that ships to end users.
+
+Three modes:
+
+- `--draft --pr <n>` — write a per-PR fragment file (towncrier-style).
+  Usually called automatically by `/apt:close-task` on merge; rarely
+  invoked by hand.
+- `--compile <tag>` — at release time, read every accumulated fragment,
+  filter by the configured persona tier, write a single per-tag
+  narrative file, and clear the unreleased dir.
+- `--publish <tag>` — shell `gh release create/edit` to push the
+  compiled body to the GitHub Release.
+
+Rules of the road (locked):
+
+- **Per-project opt-in (spec ID-7).** Presence of `.aperant/personas.json`
+  does NOT auto-enable this skill. The toggle is
+  `config.changelog.release_notes.enabled` — opt-in is explicit via
+  `/apt:setup` Batch 9.
+- **No LLM calls in the CLI (spec ID-3).** The deterministic verbs
+  (`apt-tools release-notes draft|compile|publish`) handle file I/O only.
+  Persona-voice tuning is authored by you — the host LLM — using the
+  `appendices/persona-voice.md` loader.
+- **Triage bucket is non-negotiable (spec ID-6).** Fragments without a
+  recognized persona tag MUST surface in a `## Needs Triage` section at
+  compile time. Never silent-drop. This is the human curator's safety
+  net against trust collapse over time.
+- **Fast Path Guarantee (CLAUDE.md).** This skill is DEEP-track-only
+  surface area. `/apt:quick` never enters this skill; the
+  `apt-release-notes-quick-exempt.test.ts` regression test pins the
+  exemption.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root
+- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary.
+- **gh CLI dependency:** required only for `--publish`. The `publish` verb returns a graceful `{status: 'skipped', reason: 'gh-not-found'}` envelope when `gh` is unavailable — the skill never crashes the host on a missing binary.
+- **Output:** `docs/releases/_unreleased/PR-<n>.md` (fragments) + `docs/releases/<tag>.md` (compiled) + GitHub Release body (when published).
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `.aperant/config.json` — `changelog.release_notes.{enabled, output_dir, persona_filter, require_pr_field}` and the stage blocks.
+- `.aperant/personas.json` — persona roster + tier; used by `compile` to filter fragments.
+- `docs/releases/_unreleased/PR-*.md` — fragments accumulated since the last tag.
+- `PROJECT.md` (when present) — Core Value section feeds the hero narrative the host LLM authors at compile time.
+
+**Writes:**
+- `docs/releases/_unreleased/PR-<n>.md` — towncrier-style fragments (draft mode).
+- `docs/releases/<tag>.md` — per-tag compiled narrative (compile mode).
+- GitHub Release body via `gh release create/edit` (publish mode).
+</state_files>
+
+<process>
+
+## 0. Hard-Gate + Opt-in Check
+
+No hard gates (`gates: []`). Before running ANY mode, confirm the project opted in:
+
+```bash
+rn_enabled=$(jq -r '.changelog.release_notes.enabled // false' .aperant/config.json)
+if [ "$rn_enabled" != "true" ]; then
+  echo "[apt:release-notes] This project has not opted into user-facing release notes."
+  echo "                    Run /apt:setup → 'Changelog & Release Notes' to enable."
+  exit 0
+fi
+```
+
+When opted out, exit cleanly — never crash, never write any file.
+
+## 1. Parse Flags
+
+The skill's three modes are mutually exclusive. Parse `$ARGUMENTS`:
+
+- `--draft --pr <n> --note "<text>" [--persona <name>] [--commits <sha,sha,...>] [--date <YYYY-MM-DD>]` → Draft mode (§2).
+- `--compile <tag>` → Compile mode (§3).
+- `--publish <tag> [--dry-run]` → Publish mode (§4).
+
+If no mode flag is passed, display a short usage message and exit.
+
+## 2. Draft Mode
+
+Used to write a per-PR fragment. Usually this is called automatically by `/apt:close-task` on merge (see `apt-close-task/SKILL.md` §2.6), but it can be invoked by hand for backfills or for manual fragments.
+
+Hand the inputs to the deterministic CLI:
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes draft . \
+  --pr {pr_number} \
+  --note "{one-sentence user-impact note}" \
+  [--persona {persona-name}] \
+  [--date {ISO-date}]
+```
+
+The CLI is idempotent — re-running with identical inputs returns `{status: 'ok', written: false, reason: 'no-change'}`. Trust the envelope; do NOT manually inspect the file before running.
+
+When you (the host LLM) compose the note, consult `appendices/persona-voice.md` for the persona-voice posture loader. The fragment goes into the user-facing pipeline; voice-tune accordingly.
+
+## 3. Compile Mode
+
+Used at release time to fold every accumulated fragment into a single per-tag narrative. The CLI does the deterministic work — your job is the narrative pass on the compiled body if the user wants polish beyond the structured per-PR list.
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes compile . --tag {tag}
+```
+
+The envelope reports:
+
+```json
+{
+  "status": "ok",
+  "command": "release-notes-compile",
+  "tag": "{tag}",
+  "path": "docs/releases/{tag}.md",
+  "fragments_total": N,
+  "fragments_in_body": M,
+  "fragments_in_triage": K,
+  "fragments_filtered": F,
+  "cleared_unreleased": true
+}
+```
+
+If `fragments_in_triage > 0`, ALERT the user before proceeding to publish — those fragments need persona curation. Offer two options:
+
+1. Edit the compiled file directly to move triage entries into the right tier section (and re-tag the persona in the original PR if appropriate).
+2. Proceed to publish with the triage section intact — sometimes the right call when the unmapped change is genuinely cross-cutting.
+
+If `fragments_total === 0`, gently note that there's nothing to compile yet (likely the user hasn't merged any PRs since the last release).
+
+## 4. Publish Mode
+
+Push the compiled body to the GitHub Release:
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes publish . --tag {tag}
+```
+
+The CLI handles both `gh release create` (new release) and `gh release edit` (existing release). When `gh` is not on PATH, the envelope returns `{status: 'skipped', reason: 'gh-not-found'}` — surface the message to the user and suggest installing the GitHub CLI.
+
+For local-only verification, pass `--dry-run` to skip the network call and just confirm the body file exists.
+
+## 5. Re-invocation
+
+Each mode is safe to re-run:
+
+- `draft` — idempotent per spec AC2.
+- `compile` — overwrites `<tag>.md` and re-clears `_unreleased/`. Running compile twice in a row with no new fragments produces an empty body — careful.
+- `publish` — `gh release edit` is the second call's branch, so the GitHub Release body is replaced cleanly.
+
+</process>
+
+<appendices>
+- `appendices/persona-voice.md` — Aperant-authored posture loader for voice-tuning the note text per persona archetype.
+</appendices>
+
+<integration>
+| Skill | How it interacts |
+|-------|------------------|
+| `/apt:setup` Batch 9 | Writes the opt-in toggle + audience + persona-filter that this skill reads. |
+| `/apt:ship` §2.6 | Auto-drafts the `Release note: …` line in the PR body BEFORE this skill runs; ship blocks if `require_pr_field=true` AND no signal. |
+| `/apt:close-task` §2.6 | Invokes `apt-tools release-notes draft` on merge — drops the per-PR fragment automatically. |
+| `/apt:docs changelog` | The dev-flavored sibling. Stays its own surface; this skill does NOT touch `CHANGELOG.md`. |
+| `/apt:personas` | Produces the `.aperant/personas.json` roster that compile mode filters against. |
+</integration>

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).

package/skills/apt-update/SKILL.md

@@ -42,35 +42,77 @@ 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.
+
 ## 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`)

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`);