@aperant/framework 0.6.6 → 0.7.0

package/package.json

@@ -1,134 +1,134 @@
 {
-	"name": "@aperant/framework",
-	"version": "0.6.6",
-	"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
-	"author": "Mikalsen AI <hello@mikalsen.ai>",
-	"type": "module",
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"bin": {
-		"framework": "./bin/apt-tools.mjs",
-		"apt-tools": "./bin/apt-tools.mjs",
-		"apt-proof-video": "./bin/apt-proof-video.mjs"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./types": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./dist/types/index.js"
-		},
-		"./cost": {
-			"types": "./dist/cost/index.d.ts",
-			"import": "./dist/cost/index.js"
-		},
-		"./mappers": {
-			"types": "./dist/mappers/index.d.ts",
-			"import": "./dist/mappers/index.js"
-		},
-		"./schemas": {
-			"types": "./dist/schemas/index.d.ts",
-			"import": "./dist/schemas/index.js"
-		},
-		"./standalone": {
-			"types": "./dist/standalone/index.d.ts",
-			"import": "./dist/standalone/index.js"
-		},
-		"./coordination/event-schema": {
-			"types": "./src/cli/coordination/event-schema.d.ts",
-			"import": "./src/cli/coordination/event-schema.mjs"
-		},
-		"./roadmap/conductor-view": {
-			"types": "./src/cli/roadmap/conductor-view.d.ts",
-			"import": "./src/cli/roadmap/conductor-view.mjs"
-		},
-		"./design/scan": {
-			"import": "./src/cli/design/scan.mjs"
-		},
-		"./design/extract-repo": {
-			"import": "./src/cli/design/extract-repo.mjs"
-		},
-		"./design/synthesize": {
-			"import": "./src/cli/design/synthesize.mjs"
-		}
-	},
-	"scripts": {
-		"build": "tsc && node scripts/extract-personas-schema.mjs",
-		"dev": "tsc --watch --preserveWatchOutput",
-		"typecheck": "tsc --noEmit",
-		"lint": "biome check . --diagnostic-level=error",
-		"lint:fix": "biome check --write . --diagnostic-level=error",
-		"clean": "rm -rf dist",
-		"test": "vitest run",
-		"c28:cutover": "node scripts/c28-cutover.mjs",
-		"build-plugin": "node scripts/build-plugin.mjs",
-		"publish-plugin": "node scripts/publish-plugin.mjs",
-		"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
-		"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
-		"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
-	},
-	"files": [
-		"dist/",
-		"bin/",
-		"src/cli/",
-		"src/cost/",
-		"commands/",
-		"skills/",
-		"agents/",
-		"prompts/",
-		"templates/",
-		"context/",
-		"workflows/",
-		"examples/",
-		"LICENSE",
-		"README.md",
-		"CHANGELOG.md",
-		"!**/__tests__/**",
-		"!**/*.test.*",
-		"!**/*.spec.*",
-		"!**/*.test.d.ts.map",
-		"!**/*.test.js.map"
-	],
-	"keywords": [
-		"ai",
-		"framework",
-		"coding-assistant",
-		"claude-code",
-		"codex",
-		"aperant"
-	],
-	"license": "AGPL-3.0-only",
-	"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
-	"bugs": {
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
-	},
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
-		"directory": "packages/framework"
-	},
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"dependencies": {
-		"@clack/prompts": "^1.2.0",
-		"proper-lockfile": "^4.1.2",
-		"yaml": "^2.8.3",
-		"zod": "^4.3.6"
-	},
-	"optionalDependencies": {
-		"@babel/parser": "^7.29.2",
-		"@babel/traverse": "^7.29.0",
-		"@google/genai": "^1.50.1",
-		"css-tree": "^3.2.1",
-		"playwright": "^1.59.1"
-	},
-	"devDependencies": {
-		"@vitest/coverage-v8": "^4.1.5"
-	}
-}
+  "name": "@aperant/framework",
+  "version": "0.7.0",
+  "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
+  "author": "Mikalsen AI <hello@mikalsen.ai>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "framework": "./bin/apt-tools.mjs",
+    "apt-tools": "./bin/apt-tools.mjs",
+    "apt-proof-video": "./bin/apt-proof-video.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./cost": {
+      "types": "./dist/cost/index.d.ts",
+      "import": "./dist/cost/index.js"
+    },
+    "./mappers": {
+      "types": "./dist/mappers/index.d.ts",
+      "import": "./dist/mappers/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./standalone": {
+      "types": "./dist/standalone/index.d.ts",
+      "import": "./dist/standalone/index.js"
+    },
+    "./coordination/event-schema": {
+      "types": "./src/cli/coordination/event-schema.d.ts",
+      "import": "./src/cli/coordination/event-schema.mjs"
+    },
+    "./roadmap/conductor-view": {
+      "types": "./src/cli/roadmap/conductor-view.d.ts",
+      "import": "./src/cli/roadmap/conductor-view.mjs"
+    },
+    "./design/scan": {
+      "import": "./src/cli/design/scan.mjs"
+    },
+    "./design/extract-repo": {
+      "import": "./src/cli/design/extract-repo.mjs"
+    },
+    "./design/synthesize": {
+      "import": "./src/cli/design/synthesize.mjs"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/cli/",
+    "src/cost/",
+    "commands/",
+    "skills/",
+    "agents/",
+    "prompts/",
+    "templates/",
+    "context/",
+    "workflows/",
+    "examples/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/__tests__/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.test.d.ts.map",
+    "!**/*.test.js.map"
+  ],
+  "keywords": [
+    "ai",
+    "framework",
+    "coding-assistant",
+    "claude-code",
+    "codex",
+    "aperant"
+  ],
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
+  "bugs": {
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
+    "directory": "packages/framework"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "@babel/parser": "^7.29.2",
+    "@babel/traverse": "^7.29.0",
+    "@google/genai": "^1.50.1",
+    "css-tree": "^3.2.1",
+    "playwright": "^1.59.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/extract-personas-schema.mjs",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --diagnostic-level=error",
+    "lint:fix": "biome check --write . --diagnostic-level=error",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "c28:cutover": "node scripts/c28-cutover.mjs",
+    "build-plugin": "node scripts/build-plugin.mjs",
+    "publish-plugin": "node scripts/publish-plugin.mjs",
+    "publish:verdaccio": "node scripts/publish-verdaccio.mjs",
+    "release:verdaccio": "pnpm build && pnpm publish:verdaccio",
+    "ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
+  }
+}

package/skills/apt-close-task/SKILL.md

@@ -88,6 +88,31 @@ Do NOT wait on the narrator. Its status lands in `.aperant/digests/.last-run.jso
 
 After step 2.5 spawns narrators for the just-closed candidates, the skill ALSO drains `state.pending_narration[]` (entries the passive sweep parked there) — see §4.
 
+## 2.6 Drop user-facing release-note fragment (persona-aware release-notes opt-in)
+
+This step is additive bookkeeping — it must NEVER block the close path or surface a destructive failure. Runs ONLY when `.aperant/config.json` has `changelog.release_notes.enabled === true`. When the toggle is `false` (the default for projects that don't publish user-facing notes), skip the section entirely.
+
+For each entry in the close-merged envelope's `closed[]`:
+
+1. Read the merged PR body via `gh pr view <pr_number> --json body`. Look for a single `Release note:` line (case-insensitive). The line is what `/apt:ship` Section 2.6 auto-drafted (or a manual edit by the author).
+2. Look for a persona tag in the PR body or in commits. Reasonable sources: the `Release note:` line itself if the author included one (e.g. `Release note: [Maya] …`), a `release-note-persona:` trailer in the most recent commit, or the persona name embedded in the auto-drafted line by §2.6.2 of /apt:ship.
+3. Invoke the deterministic drafter:
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes draft . \
+  --pr <pr_number> \
+  --note "<release-note-line-text>" \
+  [--persona <persona-name>]
+```
+
+This call is synchronous, sub-100ms, and idempotent per subtask 2 — re-running close-task does not duplicate the fragment.
+
+4. On non-zero exit from `release-notes draft`, append a `pending_release_note[]` row to `.aperant/state.json` so a manual re-run can recover. Do NOT block close-merged on this — it is additive bookkeeping, not core lifecycle. Use `apt-tools state-update . --append-pending-release-note '{"task_id": "<id>", "pr_number": <n>, "reason": "<error>"}'` if such a helper exists, otherwise call `apt-tools state-artifacts . --note '<msg>'` or write a one-line warning to stderr.
+
+Skip the section quietly when:
+- The PR body has no `Release note:` line AND no auto-draft signal (intentional infra-only PR, or the `no-notes` label was applied at ship time).
+- The CLI returns `{status: 'ok', written: false, reason: 'no-change'}` — already idempotent-handled by subtask 2's contract; treat as success.
+
 ## 3. Summary
 
 close-merged emits an envelope with:
@@ -98,6 +123,8 @@ close-merged emits an envelope with:
 
 Report the summary verbatim. If anything landed in `skipped[]` with a recoverable reason (`offline`, `rate_limited`), suggest the user re-run once the network clears.
 
+**Local cleanup recap (best-effort).** On confirmed merge, `task close-merged` runs `computeWorktreeCleanup` against the primary repo (`packages/framework/src/cli/task/worktree-cleanup.mjs:140-230`): `git fetch origin <base>` (failure → recorded as `fetch_failed` warning, cleanup proceeds), `git checkout <base>` (failure → returns `action: 'checkout_failed'` and preserves BOTH the worktree and the task branch — nothing is removed), `git merge --ff-only origin/<base>` (failure → `ff_only_failed` warning, GC still runs), `git worktree remove <wtPath>`, and `git branch -d <taskBranch>` (failure on squash/rebase merges → `branch_delete_failed` warning, `branch_deleted: false` in the envelope; user can `git branch -D` manually). This is why `/apt:watch-ci` auto-merge MUST NOT pass `gh pr merge --delete-branch` — that flag would try to do the same work from inside the worktree where `git switch <base>` cannot succeed (see FRAMEWORK-BUG-019).
+
 ## 4. Narrate-only mode
 
 When invoked with `--narrate-only`, skip §1 (no `gh pr view` polling) and §2 (no destructive close path). The deterministic close already ran via the passive post-merge sweep — your job is to drain the `state.pending_narration[]` ledger the sweep parked.
@@ -108,10 +135,13 @@ Flags:
 
 Per ledger entry `{ task_id, scope, phase_id, closed_at, pr_number }`:
 
+0. **Enumerate the ledger first.** Run `apt-tools task close-merged . --narrate-only [--task <id>]`. The envelope's `closed[]` is the read-only list of pending narration rows (each carries `narration_pending: true`); state.json is not mutated. When `closed[]` is empty, exit early with `{status: 'ok', narrated: [], skipped: [], remaining: 0}` — there is nothing to drain.
 1. Run `apt-tools features-audit . --apply-stubs --task <task_id>` so the feature registry catches whatever the closed task introduced. If the subprocess exits non-zero, skip the entry with `reason: 'features-audit-failed'` — never block narration on registry update.
 2. When `phase_id` is non-null, spawn `apt-team-docs-narrator` (background, fire-and-forget) using the same shape as §2.5: `subagent_type: apt-team-docs-narrator`, `run_in_background: true`, `description: Narrate shipped phase {phase_id}`, `prompt: Run in phase-ship mode with --phase {phase_id} --scope {scope}.`. When `phase_id` is null, skip the spawn with `reason: 'no-phase-id'` (quick tasks have no phase to narrate).
 3. On successful spawn (or successful no-phase skip), drain the row via `apt-tools task narration-drain . --task <task_id>` which acquires `withFileLock(state.json)` and removes the matching `pending_narration[]` entry. On spawn failure, leave the row in place with `reason: 'narrator-spawn-failed'` so the user can re-invoke.
 
+**At-least-once retry semantics (FRAMEWORK-BUG-020).** Step 0 is read-only — it does NOT remove rows. Steps 1–3 are the existing per-row drain contract: a row stays in `pending_narration[]` until step 3 calls `narration-drain` successfully. If the orchestrator crashes between step 2 (narrator spawn) and step 3 (drain), the row remains parked and a retry will spawn narration again. Re-spawning is safe because the narrator is **anchor-replace idempotent** by design (see `agents/apt-team-docs-narrator.md` §6 / §2 and the "Idempotent operations only" rule in §notes) — it uses HTML-comment anchors to bound the replaced region in ROADMAP.md, so a second run replaces the same span rather than appending.
+
 Emit a summary envelope:
 
 ```json

package/skills/apt-diagram/SKILL.md

@@ -174,8 +174,38 @@ order: (a) consent gate, (b) renderer dispatch, (c) failure handling.
 
 ### 5a. Consent gate
 
-Read `.aperant/config.json` and look at `diagram.mcpConsent`. The
-shape is:
+Per FRAMEWORK-AUDIT-001, `mcpConsent` is per-user state and lives in
+`.aperant/config.local.json` (gitignored), NOT the shared
+`.aperant/config.json`. The `diagram.mode` field stays in `config.json` as
+team policy. Read the MERGED config (config.json deep-merged with
+config.local.json — local wins on collision) and look at
+`diagram.mcpConsent` via the same in-skill `node -e` pattern Step 2 uses:
+
+```bash
+node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const aperantDir = path.join(process.cwd(), ".aperant");
+  function readJson(p) {
+    try { return JSON.parse(fs.readFileSync(p, "utf-8")); } catch { return null; }
+  }
+  const shared = readJson(path.join(aperantDir, "config.json")) || {};
+  const local = readJson(path.join(aperantDir, "config.local.json")) || {};
+  // Deep-merge — local wins on collision; matches loadMergedProjectConfig semantics.
+  function merge(a, b) {
+    if (a === null || typeof a !== "object" || Array.isArray(a)) return b;
+    if (b === null || typeof b !== "object" || Array.isArray(b)) return b;
+    const out = { ...a };
+    for (const k of Object.keys(b)) out[k] = (k in a) ? merge(a[k], b[k]) : b[k];
+    return out;
+  }
+  const cfg = merge(shared, local);
+  const consent = cfg && cfg.diagram ? cfg.diagram.mcpConsent : null;
+  process.stdout.write(JSON.stringify(consent || null));
+'
+```
+
+The shape is:
 
 ```json
 { "host": "<host string>", "decision": "granted" | "denied", "grantedAt": "<ISO 8601 timestamp>" }
@@ -196,7 +226,7 @@ Decide whether to prompt:
 - If `diagram.mcpConsent.host !== <configured MCP host>` → prompt.
 - If `diagram.mcpConsent.host === <configured MCP host>` AND `diagram.mcpConsent.decision === "denied"` → hard-error immediately with the exact denied text (no re-prompt):
   ```
-  diagram MCP consent denied; re-run with `--mode=file` or change diagram.mcpConsent in .aperant/config.json
+  diagram MCP consent denied; re-run with `--mode=file` or change diagram.mcpConsent in .aperant/config.local.json
   ```
 - Otherwise (host matches AND decision is `"granted"`) → the existing consent applies; proceed to 5b.
 
@@ -206,23 +236,25 @@ When prompting, print a single line naming the host and ask `granted / denied`:
 apt:diagram is about to send diagram data to the Excalidraw MCP server at <host>. Type `granted` to allow, `denied` to refuse.
 ```
 
-Read one line of input. Persist the decision back to
-`.aperant/config.json` with a read-mutate-write JSON pattern:
+Read one line of input. Persist the decision to
+`.aperant/config.local.json` (NOT `config.json` — `mcpConsent` is per-user
+state per FRAMEWORK-AUDIT-001; the local file is gitignored). The
+read-mutate-write JSON pattern targets the local file only:
 
 ```bash
 node -e '
   const fs = require("fs");
   const path = require("path");
-  const cfgPath = path.join(process.cwd(), ".aperant/config.json");
+  const cfgPath = path.join(process.cwd(), ".aperant/config.local.json");
   const decision = process.env.APT_DIAGRAM_DECISION; // "granted" | "denied"
   if (decision !== "granted" && decision !== "denied") {
     process.stderr.write("invalid decision\n");
     process.exit(1);
   }
   const host = process.env.APT_DIAGRAM_HOST;
-  let cfg = { diagram: { mode: "mcp", mcpConsent: null } };
+  let cfg = { diagram: { mcpConsent: null } };
   try { cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8")); } catch {}
-  cfg.diagram = cfg.diagram || { mode: "mcp", mcpConsent: null };
+  cfg.diagram = cfg.diagram || { mcpConsent: null };
   cfg.diagram.mcpConsent = {
     host,
     decision,
@@ -232,11 +264,15 @@ node -e '
 '
 ```
 
+Note: the write target above is `config.local.json` (gitignored, per-user).
+The shared `config.json` is not touched — `diagram.mode` lives there and
+stays team-shared policy.
+
 If the decision is `"denied"`, exit with EXACTLY this text (verbatim,
 no rewording, no extra punctuation):
 
 ```
-diagram MCP consent denied; re-run with `--mode=file` or change diagram.mcpConsent in .aperant/config.json
+diagram MCP consent denied; re-run with `--mode=file` or change diagram.mcpConsent in .aperant/config.local.json
 ```
 
 If the decision is `"granted"`, proceed to 5b.

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>