@aperant/framework 0.6.5 → 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:
@@ -1017,6 +1148,8 @@ Map the user's selections to config values:
 - "Ask me" → `pr_review.suggest_after_ship: "ask"`
 - "Never" → `pr_review.suggest_after_ship: "never"`
 
+Note: task ids are slug-first since v0.6.6 — the date-format setting controls the trailing date component only.
+
 **Date Format:**
 - "DD-MM-YY" → `preferences.date_format: "DD-MM-YY"`
 - "MM-DD-YY" → `preferences.date_format: "MM-DD-YY"`
@@ -1032,7 +1165,7 @@ Map the user's selections to config values:
 - "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"`
@@ -1147,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
@@ -1158,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).
@@ -289,11 +336,13 @@ Capture the PR URL from the output into `pr_url` (for example, the last line of
 **Record `pr_url` on the task record (C56 A2).** `/apt:close-task` and the auto-close-phase path in `task close` both resolve the PR number from this URL to poll `gh pr view` for merge state — without it, the closer side cannot run:
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --pr-url {PR_URL}
+ship_update=$(node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --pr-url {PR_URL})
 ```
 
 This same call **atomically flips `lifecycle_phase` from `reviewing` to `shipped-pending-merge`** when the task is in `reviewing` and no explicit `--lifecycle-phase` flag is passed. Section 6 is now the single load-bearing step that both records the PR and transitions the lifecycle; Section 8 below documents the semantics but no longer issues a separate command.
 
+It also evaluates `ci_watch.after_ship` and may arm the post-ship CI watcher. Preserve the JSON envelope in `ship_update`; Section 7.2 reads `ci_watch_armed` and `ci_watch_skip_reason` from it instead of issuing a second auto-start command.
+
 Display the resolution so users see which branch/base was used:
 
 ```
@@ -352,29 +401,31 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
 
 ### 7.2 Post-ship /apt:watch-ci hook
 
-After Section 7.1's hint resolves (whether it ran the deep review or skipped), conditionally arm a post-ship CI watcher. The hook is controlled by `ci_watch.after_ship` in `.aperant/config.json` (tri-state: `auto` | `ask` | `never`). The default depends on host capability — `auto` on cron-capable hosts (Claude Code, Pi), `never` elsewhere.
+After Section 7.1's hint resolves (whether it ran the deep review or skipped), report or interactively arm the post-ship CI watcher. The hook is controlled by `ci_watch.after_ship` in `.aperant/config.json` (tri-state: `auto` | `ask` | `never`). The default depends on host capability — `auto` on cron-capable hosts (Claude Code, Pi), `never` elsewhere.
 
 **Skip entirely** when no PR URL was captured in Section 6 (library `npm publish`-only path — same skip rule as 7.1).
 
-**Read host cron capability + the after-ship mode:**
+**Read the Section 6 task-update envelope first:**
 
 ```bash
+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')
 host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host.capabilities.cron')
-after_ship_default=$([ "$host_cron" = "true" ] && echo "auto" || echo "never")
-after_ship_mode=$(jq -r --arg d "$after_ship_default" '.ci_watch.after_ship // $d' .aperant/config.json)
 ```
 
 **Autonomy interaction** (apply BEFORE branching, same rule as 7.1): when `autonomy === 3` (YOLO), degrade `ask` → `auto`.
 
-**Branch on `after_ship_mode`:**
+**Branch on the task-update envelope:**
 
-- **`auto` AND `host_cron=true`** — call `apt-tools ci-watch start --pr {pr_number} --task-id {task-id} --host {cli}`. On success, emit:
+- **`ci_watch_armed=true` AND `host_cron=true`** — emit:
 
   ```
-  [APT:ship] CI watcher armed (host cron: {cli}). Deadline: {iso}. Stop: /apt:watch-ci --stop --pr {N}.
+  [APT:ship] CI watcher armed (host cron: {ci_watch_host}). Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
   ```
 
-- **`auto` AND `host_cron=false`** — call `apt-tools ci-watch start --pr {pr_number} --task-id {task-id} --host {cli}` (creates state file, sets `scheduler_handle: null`), then emit:
+- **`ci_watch_armed=true` AND `host_cron=false`** — emit:
 
   ```
   [APT:ship] CI watcher state created (host has no cron; advance manually: /apt:watch-ci --tick --pr {N}).
@@ -382,15 +433,26 @@ after_ship_mode=$(jq -r --arg d "$after_ship_default" '.ci_watch.after_ship // $
 
   This is the honest-gap surface per D-03 — we never lie about cron-capability.
 
-- **`ask`** — emit:
+- **`ci_watch_skip_reason=ask-deferred`** — emit:
 
   ```
   [APT:ship] Arm CI watcher for PR {N} now? [Y/n]
   ```
 
-  On `Y` (or empty enter), invoke the `auto` branch logic above (with the same host-cron derivation). On `N` or any other response, proceed silently to Section 8.
+  On `Y` (or empty enter), call:
 
-- **`never`** — silent. Proceed directly to Section 8.
+  ```bash
+  node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli}
+  ```
+
+  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.
+
+- **`ci_watch_skip_reason=disabled`** — silent. Proceed directly to Section 8.
+
+- **Any other skip reason** — emit:
+  ```
+  [APT:ship] CI watcher not armed: {ci_watch_skip_reason}
+  ```
 
 Section 7.2 is purely additive — it does not affect Section 7.1's `pr_review.suggest_after_ship` policy or any other config block.