@aperant/framework 0.6.7 → 0.7.3

package/dist/cli/util/version-preflight.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Preflight check: is the installed kernel new enough to support the
+ * named feature?
+ *
+ * - Returns `null` when the install is at-or-above `introducedIn` (pass).
+ * - Returns `null` when `installedVersion` is malformed (fail-open — a
+ *   corrupted `package.json` shouldn't lock users out of every cmd; the
+ *   route-level drift check still catches the same install via the
+ *   version mismatch path).
+ * - Returns a `version_drift` error envelope when the install predates
+ *   `introducedIn`. Callers `exitWith(envelope, 1)`.
+ *
+ * @param {Object} args
+ * @param {string} args.feature  Short name of the feature being gated.
+ * @param {string} args.introducedIn  Minimum framework version that ships the feature.
+ * @param {string} args.installedVersion  The installed kernel's version.
+ * @param {string} args.missingFlag  The CLI flag that requires this version (e.g. '--payload-file').
+ * @returns {null | {
+ *   status: 'error',
+ *   command: 'version-preflight',
+ *   error_code: 'version_drift',
+ *   feature: string,
+ *   introduced_in: string,
+ *   installed_version: string,
+ *   missing_flag: string,
+ *   reason: string,
+ * }}
+ */
+export function requireMinVersion({ feature, introducedIn, installedVersion, missingFlag }: {
+    feature: string;
+    introducedIn: string;
+    installedVersion: string;
+    missingFlag: string;
+}): null | {
+    status: "error";
+    command: "version-preflight";
+    error_code: "version_drift";
+    feature: string;
+    introduced_in: string;
+    installed_version: string;
+    missing_flag: string;
+    reason: string;
+};
+//# sourceMappingURL=version-preflight.d.mts.map

package/dist/cli/util/version-preflight.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-preflight.d.mts","sourceRoot":"","sources":["../../../src/cli/util/version-preflight.mjs"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4FAfG;IAAqB,OAAO,EAApB,MAAM;IACO,YAAY,EAAzB,MAAM;IACO,gBAAgB,EAA7B,MAAM;IACO,WAAW,EAAxB,MAAM;CACd,GAAU,IAAI,GAAG;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAmBH"}

package/dist/cli/util/version-preflight.mjs

@@ -0,0 +1,66 @@
+/**
+ * util/version-preflight.mjs — FRAMEWORK-BUG-017 (rung 2 of 3).
+ *
+ * Pure helper for cmds that depend on a flag / behavior introduced in a
+ * specific framework version. When the installed kernel predates that
+ * version, returning a structured `version_drift` envelope is strictly
+ * better than the silent infra-backoff loop that bit us in
+ * FRAMEWORK-BUG-010.
+ *
+ * Scope (Codex review edit 1): this is a **future-guard** for the next
+ * framework fix that introduces a new flag. A stale 0.6.6 install
+ * obviously cannot execute 0.6.8 preflight code (the helper doesn't
+ * exist there). The actual catch-point for already-stale installs is
+ * the route-side `detectSourceWorkspaceDrift`. This helper makes the
+ * NEXT bug bundle cheaper to ship safely.
+ */
+import { compareVersions, SEMVER_RE } from './semver.mjs';
+/**
+ * Preflight check: is the installed kernel new enough to support the
+ * named feature?
+ *
+ * - Returns `null` when the install is at-or-above `introducedIn` (pass).
+ * - Returns `null` when `installedVersion` is malformed (fail-open — a
+ *   corrupted `package.json` shouldn't lock users out of every cmd; the
+ *   route-level drift check still catches the same install via the
+ *   version mismatch path).
+ * - Returns a `version_drift` error envelope when the install predates
+ *   `introducedIn`. Callers `exitWith(envelope, 1)`.
+ *
+ * @param {Object} args
+ * @param {string} args.feature  Short name of the feature being gated.
+ * @param {string} args.introducedIn  Minimum framework version that ships the feature.
+ * @param {string} args.installedVersion  The installed kernel's version.
+ * @param {string} args.missingFlag  The CLI flag that requires this version (e.g. '--payload-file').
+ * @returns {null | {
+ *   status: 'error',
+ *   command: 'version-preflight',
+ *   error_code: 'version_drift',
+ *   feature: string,
+ *   introduced_in: string,
+ *   installed_version: string,
+ *   missing_flag: string,
+ *   reason: string,
+ * }}
+ */
+export function requireMinVersion({ feature, introducedIn, installedVersion, missingFlag }) {
+    if (!installedVersion || typeof installedVersion !== 'string')
+        return null;
+    if (!SEMVER_RE.test(installedVersion))
+        return null;
+    if (!SEMVER_RE.test(introducedIn))
+        return null;
+    if (compareVersions(installedVersion, introducedIn) >= 0)
+        return null;
+    return {
+        status: 'error',
+        command: 'version-preflight',
+        error_code: 'version_drift',
+        feature,
+        introduced_in: introducedIn,
+        installed_version: installedVersion,
+        missing_flag: missingFlag,
+        reason: `cmd needs feature ${feature} introduced in version ${introducedIn}; installed version is ${installedVersion} — run /apt:update`,
+    };
+}
+//# sourceMappingURL=version-preflight.mjs.map

package/dist/cli/util/version-preflight.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-preflight.mjs","sourceRoot":"","sources":["../../../src/cli/util/version-preflight.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE;IACzF,IAAI,CAAC,gBAAgB,IAAI,OAAO,gBAAgB,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAC1E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAA;IAClD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAA;IAE9C,IAAI,eAAe,CAAC,gBAAgB,EAAE,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAErE,OAAO;QACN,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,mBAAmB;QAC5B,UAAU,EAAE,eAAe;QAC3B,OAAO;QACP,aAAa,EAAE,YAAY;QAC3B,iBAAiB,EAAE,gBAAgB;QACnC,YAAY,EAAE,WAAW;QACzB,MAAM,EAAE,qBAAqB,OAAO,0BAA0B,YAAY,0BAA0B,gBAAgB,oBAAoB;KACxI,CAAA;AACF,CAAC"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.6.4",
+  "version": "0.7.3",
   "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": {
     "name": "Mikalsen AI",
@@ -30,15 +30,19 @@
     "skills/apt-create-docs",
     "skills/apt-debug",
     "skills/apt-design",
+    "skills/apt-diagram",
     "skills/apt-discuss",
     "skills/apt-docs",
     "skills/apt-execute",
+    "skills/apt-improve",
     "skills/apt-mockup",
     "skills/apt-pause",
     "skills/apt-personas",
     "skills/apt-plan",
     "skills/apt-pr-review",
+    "skills/apt-prototype",
     "skills/apt-quick",
+    "skills/apt-release-notes",
     "skills/apt-resume",
     "skills/apt-review",
     "skills/apt-roadmap",
@@ -47,15 +51,20 @@
     "skills/apt-scan",
     "skills/apt-setup",
     "skills/apt-ship",
+    "skills/apt-spar",
     "skills/apt-stress-test",
     "skills/apt-terminal",
+    "skills/apt-triage",
     "skills/apt-update",
     "skills/apt-verify",
-    "skills/apt-verify-proof"
+    "skills/apt-verify-proof",
+    "skills/apt-watch-ci",
+    "skills/apt-zoom-out"
   ],
   "agents": [
     "agents/apt-docs-author.md",
     "agents/apt-executor.md",
+    "agents/apt-improver.md",
     "agents/apt-planner.md",
     "agents/apt-pr-review-codebase-fit.md",
     "agents/apt-pr-review-fixer.md",

package/dist/plugin/agents/apt-improver.md

@@ -0,0 +1,99 @@
+---
+name: apt-improver
+description: Proactive refactor discovery agent — runs apt:improve Phase 1 (explore a named area through DEEPENING / INTERFACE-DESIGN / LANGUAGE lenses) and outputs a candidate refactor inventory. Read-only, no code changes.
+apt-skill-version: {{APT_VERSION}}
+tools: Read, Bash, Grep, Glob
+color: orange
+---
+
+<role>
+You are an Aperant Framework proactive-refactor agent. You scan a named
+area of the codebase through three lenses (DEEPENING, INTERFACE-DESIGN,
+LANGUAGE) and produce a candidate refactor inventory.
+
+Spawned by `/apt:improve` for Phase 1 (Explore). Phases 2 (Present
+candidates) and 3 (Deepen via grill loop) run in the parent agent
+context because they require user interaction.
+
+Your job: read the area, apply the three lenses, output a candidate
+inventory. You are READ-ONLY — no code changes, no decisions locked.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read`
+tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+**Project instructions:** Read `./CLAUDE.md` if it exists for project structure and conventions.
+**Constitution:** Read `AGENTS.md` if it exists for architecture overview.
+**Glossary:** Read `CONTEXT.md` if it exists — its term-blocks (especially `Aliases to avoid` fields) are direct inputs to the LANGUAGE lens.
+
+**Rationalizations (R4):** Read `.aperant/rationalizations/claude-opus-4-6.md` once at session start. Pay particular attention to R-2 (skipping pre-read investigation) and R-5 ("I already verified this implicitly"). As an improver, you only have value if your candidate inventory is grounded in actually-read code — drift here ships hallucinated refactor candidates.
+</project_context>
+
+<environment>
+- **Working directory:** The project root
+- **Note:** You have NO write/edit tools. You investigate and report findings only. Phase 2 (filter + present) and Phase 3 (deepen + lock) run in the parent agent's context.
+</environment>
+
+<process>
+
+## 1. Parse the area name
+
+Extract the area from the spawn prompt. Areas are noun phrases ("sparring engine", "feature registry", "auth flow") — not file paths.
+
+If the area is ambiguous, ask the parent ONE clarifying question via your report — do NOT enter a multi-turn interview.
+
+## 2. Load CONTEXT.md (if present)
+
+If `CONTEXT.md` exists at the project root, read it and extract:
+
+- Term-blocks whose canonical term, definition, or aliases-to-avoid match keywords in the area
+- The full alias list (LANGUAGE lens grep source)
+
+If CONTEXT.md does not exist, skip silently — the LANGUAGE lens runs without the alias grep but still catches in-file conflations.
+
+## 3. Apply the three lenses
+
+Read the lens descriptions (the parent has them in context; if you don't, read them from disk).
+Paths below are relative to the project root (monorepo: `<repo>/packages/framework/` is the
+framework root; standalone install: the project root IS the framework root, so use
+`skills/apt-improve/` directly):
+
+- `packages/framework/skills/apt-improve/DEEPENING.md` (monorepo) or `skills/apt-improve/DEEPENING.md` (standalone)
+- `packages/framework/skills/apt-improve/INTERFACE-DESIGN.md` (monorepo) or `skills/apt-improve/INTERFACE-DESIGN.md` (standalone)
+- `packages/framework/skills/apt-improve/LANGUAGE.md` (monorepo) or `skills/apt-improve/LANGUAGE.md` (standalone)
+
+For each lens, walk the area's files and flag candidates per the lens's red-flag list.
+
+## 4. Output the candidate inventory
+
+Produce a structured report:
+
+```markdown
+# apt:improve Phase-1 inventory — {area}
+
+## DEEPENING candidates
+- `{File}:{Symbol}` — shallow ({reason}); deletion-test target.
+- ...
+
+## INTERFACE-DESIGN candidates
+- `{Module A}` ↔ `{Module B}` — {red-flag name} ({one-line evidence}).
+- ...
+
+## LANGUAGE candidates
+- `{File}:{Line}` — uses `{wrong-term}` for `{canonical}` ({CONTEXT.md reference if applicable}).
+- ...
+
+## Files read
+- {file1}
+- ...
+```
+
+Keep the inventory grounded — every candidate must cite a file + symbol the user can grep for. No speculation; no candidates inferred from filenames alone.
+
+## 5. Hand back to parent for Phase 2/3
+
+Your output is the input to Phase 2 (the parent agent's filter step). Do NOT enter Phase 2 yourself — your role ends here.
+
+</process>

package/dist/plugin/agents/apt-planner.md

@@ -59,6 +59,18 @@ For STANDARD and COMPLEX tasks:
 3. Read key files to understand current architecture
 4. Identify: files to modify, interfaces to respect, tests to update, config to change
 
+### 3.35. React state guidance — sync-store vs render-committed ref (BUG-025-planner)
+
+When a planned event handler fires a flush/persist immediately after mutating a Zustand/Jotai/refs-stored store, the spec MUST recommend reading from `store.getState()` (or the equivalent direct-read primitive) on the synchronous path, NOT from a `useRef`-populated-by-`useEffect`.
+
+Why: refs populated via `useEffect` lag the store by one render cycle. A handler that mutates the store and immediately reads the ref sees the pre-mutation value, silently corrupting persists and order-of-operations contracts. Reference pattern: `apps/desktop/src/renderer/src/App.tsx::runUpsertForIds` (post-fix commit `4c263856`).
+
+Checklist when the task touches a Zustand/Jotai store or any handler doing flush-after-mutate:
+
+- Grep for `useRef(` references that cache store state (e.g. `const fooRef = useRef(foo); useEffect(() => { fooRef.current = foo }, [foo])`).
+- If the spec or planned subtasks read from such a ref on a synchronous path that ALSO mutates the store, recommend `store.getState()` as the read primitive.
+- Note the caveat explicitly in the spec's Implementation Decisions section so the executor doesn't silently revert it.
+
 ### 3.4. Consume design.md (C24)
 
 If `{task_dir}/design.md` exists (emitted by a prior `/apt:design` run), load it before decomposing subtasks:
@@ -199,7 +211,13 @@ If unable to enumerate (network unavailable, action docs unclear), flag it expli
 
 ## 4. Write Specification
 
-Create `{task_dir}/spec.md`:
+The spec.md content format **branches on track** (Pocock adoption ID-05,
+Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
+shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
+survives the task as a second-consumer document.
+
+### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
+
 ```markdown
 # Task: {task description}
 
@@ -219,6 +237,57 @@ Create `{task_dir}/spec.md`:
 {What this task explicitly does NOT cover}
 ```
 
+### 4.B. STANDARD / DEEP / COMPLEX — PRD-shaped spec.md
+
+```markdown
+# Spec: {task title}
+
+**Task ID:** {task-id}
+**Track:** {STANDARD | DEEP}
+**Scope:** {framework | desktop | web | core | ui | backend | docs}
+
+## Problem Statement
+{What pain are we solving? Cite empirical evidence where possible.}
+
+## Solution
+{Chosen approach + bulleted net delta of files / flags / config / skills.}
+
+## User Stories
+{One **US-NN (persona).** story per user-value slice. Stories map 1:1
+onto subtasks in implementation_plan.json.}
+
+## Implementation Decisions
+{Load-bearing principles carried into every subtask. Format:
+"### ID-NN: {title}" + rationale + practical consequence.}
+
+## Testing Decisions
+{One block per test family: "### TD-NN: {family}" + what's covered +
+which subtask owns the test file. Fast Path regression tests MUST be
+enumerated here.}
+
+## Out of Scope
+{Non-goals. Each bullet names what is deferred + where it belongs.}
+
+## Further Notes
+{Sequencing rationale, risk surface, dependencies, files-affected
+preview, and any other executor-load-bearing context.}
+
+### Acceptance Criteria
+{Cross-cutting **AC1..ACN** list — each AC gets a stable ID. Subtasks
+reference these IDs via the per-subtask `acceptance_criteria` field.}
+```
+
+**PRD section ordering is load-bearing.** `apt-tools coverage-check
+validate` greps `## Acceptance Criteria`; `apt-tools consistency check`
+greps `## Solution` and `## User Stories`. Renaming or reordering these
+sections breaks downstream tooling and the C15 consistency rules.
+
+**Do NOT interview the user.** The PRD is synthesized from the task
+description + codebase investigation + AGENTS.md, not from a clarifying
+back-and-forth. If a section truly cannot be filled, write
+`{TBD — needs user input}`; do NOT pause for clarification (that is
+`apt:discuss`'s surface, not the planner's).
+
 ### 4.05. Design Reference section (C24 — when design.md exists)
 
 When `{task_dir}/design.md` exists, `spec.md` MUST include a `## Design Reference` section directly below `## Requirements`. Shape:
@@ -275,12 +344,41 @@ fix it now, not later.
 
 ## 5. Create Implementation Plan
 
-Create `{task_dir}/implementation_plan.json`:
+Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).
+
+### 5.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
+
 ```json
 {
   "task": "{task description}",
-  "complexity": "simple|standard|complex",
+  "complexity": "simple",
   "spec": "spec.md",
+  "subtasks": [
+    {
+      "id": "1",
+      "title": "{subtask title}",
+      "description": "{what to do — concrete, not vague}",
+      "files": ["path/to/file1.ts", "path/to/file2.ts"],
+      "dependencies": [],
+      "status": "pending",
+      "verification": "{command or check to verify completion}"
+    }
+  ]
+}
+```
+
+QUICK subtasks omit `hitl`, `afk`, `acceptance_criteria`, and `user_value`
+fields. The one-shot path doesn't need user-value framing or per-subtask
+HITL gates.
+
+### 5.B. STANDARD / DEEP / COMPLEX — vertical-slice subtask schema
+
+```json
+{
+  "task": "{task description}",
+  "complexity": "standard|complex",
+  "spec": "spec.md",
+  "vertical_slice_schema_version": "1",
   "declared_persona_tier": "primary",
   "declared_personas": ["mobile-dev"],
   "tier_confidence": "high",
@@ -308,29 +406,48 @@ Create `{task_dir}/implementation_plan.json`:
   "subtasks": [
     {
       "id": "1",
-      "title": "{subtask title}",
+      "title": "{subtask title — user-value framing, not 'add UI'}",
       "description": "{what to do — concrete, not vague}",
       "files": ["path/to/file1.ts", "path/to/file2.ts"],
       "acceptance_criteria": ["AC1", "AC3"],
       "dependencies": [],
       "status": "pending",
+      "hitl": "required | review | none",
+      "afk": "safe | unsafe",
+      "user_value": "{one-line user-value framing — who benefits, how}",
       "verification": "{command or check to verify completion}"
     }
   ]
 }
 ```
 
+Mandatory STANDARD/DEEP fields per subtask:
+
+- `hitl` — `"required" | "review" | "none"`. `required` blocks the
+  executor pending human approval (autonomy 1 always pauses; autonomy 2
+  batches; autonomy 3 escalates only on conflict). `review` means the
+  human reviews the diff post-hoc, not blocking. `none` is agent-only.
+- `afk` — `"safe" | "unsafe"`. `safe` means proceed unattended. `unsafe`
+  means pause at the start of this subtask if no human is present
+  (autonomy < 3).
+- `acceptance_criteria` — `string[]` of id-refs (`"AC1"`, …) into spec.md's
+  `## Acceptance Criteria` section.
+- `user_value` — one-line framing of WHO benefits and HOW. Prevents
+  horizontal slicing — every subtask is a vertical user-shippable slice.
+
+Plan-level: `vertical_slice_schema_version: "1"` declares the schema
+version so future migrations can detect this plan as v1.
+
 Rules:
 - Each subtask completable in one focused session
 - Dependencies form a DAG (no circular deps)
 - Verification must be automated (test command, grep check, type check)
 - Files list must be exhaustive — every file the subtask touches
-- `acceptance_criteria` is mandatory: list the canonical AC id-refs
-  (`"AC1"`, `"AC3"`, ...) from the `## Acceptance Criteria` section of
-  spec.md that this subtask satisfies. Verbatim AC text is accepted but
-  discouraged — the id-ref form is stable across spec edits. Every AC in
-  spec.md must be referenced by at least one subtask; gate G8
-  (`consistency-check`) enforces this on ship.
+- `acceptance_criteria` is mandatory on STANDARD/DEEP: every AC in spec.md
+  must be referenced by at least one subtask; gate G8
+  (`consistency-check`) enforces this on ship. Verbatim AC text is
+  accepted but discouraged — id-refs are stable across spec edits.
+- Subtask title MUST frame user value, not file scope.
 
 ### 5.1 Framework-scope doc-sync rule
 

package/dist/plugin/agents/apt-pr-review-fixer.md

@@ -64,7 +64,7 @@ The only valid reasons to skip a finding:
    ```
    [TOOLCHAIN_COMMANDS]
    ```
-6. **If verification passes**: Stage with `git add [specific files]`
+6. **If verification passes**: Stage AND commit atomically per finding with `git add [specific files] && git commit -m "<finding-id>: <one-line>"` (BUG-016 — the audit gate only observes COMMITTED edits in the iteration window; stage-only leaves the index dirty and trips a false-positive hallucination verdict).
 7. **If verification fails**: Revert with `git checkout -- [file]`, mark as "manual fix required" in your report
 
 ---
@@ -89,7 +89,7 @@ Findings with severity `critical`:
 
 ## Report Format
 
-Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied.md`:
+Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied-[FIXER_NAME].md` (BUG-030 canonical naming — the audit gate resolves `fixes-applied-${FIXER_NAME}.md` ahead of the legacy `fixes-applied.md`, so parallel fixers no longer collide on a shared report path):
 
 ```markdown
 # Fix Report — Iteration [N]
@@ -142,11 +142,13 @@ Write to `[REVIEW_DIR]/iterations/[N]/fixes-applied.md`:
 
 ## Pre-Return Self-Audit (mandatory)
 
-Before emitting `VERIFICATION: PASS` or any `FIXED: N > 0` status, run BOTH of these inside the worktree:
+Before emitting `VERIFICATION: PASS` or any `FIXED: N > 0` status, run BOTH of these inside the worktree.
+
+The orchestrator passes you `[ITERATION_START_SHA]` — the SHA captured BEFORE fixers were spawned. The audit gate uses the same SHA as its `--since-sha` window, so your self-audit must mirror it (BUG-016):
 
 ```bash
+cd [WORKTREE_PATH] && git log [ITERATION_START_SHA]..HEAD --oneline
 cd [WORKTREE_PATH] && git diff --cached --name-only
-cd [WORKTREE_PATH] && git diff --name-only
 ```
 
 Paste the **literal command output** into your report under a new section:
@@ -154,11 +156,13 @@ Paste the **literal command output** into your report under a new section:
 ```markdown
 ## Pre-Return Self-Audit
 
-git diff --cached --name-only:
-<paste literal output, or empty if nothing staged>
+git log [ITERATION_START_SHA]..HEAD --oneline:
+<paste literal output — MUST list ≥ 1 commit per claimed fix>
 
-git diff --name-only:
-<paste literal output, or empty if nothing unstaged>
+git diff --cached --name-only:
+<paste literal output — MUST be empty (index clean after every commit)>
 ```
 
-**Rule:** if BOTH outputs are empty AND you claimed to have fixed ≥ 1 finding, your status line MUST be `FIXED: 0 | FAILED: N | SKIPPED: 0 | VERIFICATION: FAIL` and every claimed fix MUST be marked FAILED in the report with `- **Verification**: FAIL — no diff produced`. Do not emit `VERIFICATION: PASS` with an empty diff — the orchestrator runs an **independent** deterministic audit (see `/apt:pr-review` SKILL.md Phase 6 Step 4b, `apt-tools pr-review audit-fixer`) that cross-checks your status line against the worktree git state. Emitting `PASS` when the diff is empty will be caught deterministically and counted as a hallucination; your findings will be treated as unresolved and you may be re-spawned with an explicit hallucination callout.
+**Pass condition (BUG-016 — commit discipline):** the `git log` output MUST contain ≥ 1 commit attributable to this fixer (one commit per fixed finding, message prefixed with the finding id) AND `git diff --cached --name-only` MUST be empty. The previous "I see staged files" rule is OBSOLETE — staging without committing leaves the index dirty and the audit gate's `--since-sha` window (which scopes to committed diff for the current iteration) sees zero matching paths, false-positiving `hallucinated`.
+
+**Fail condition:** if `git log [ITERATION_START_SHA]..HEAD --oneline` is EMPTY AND you claimed to have fixed ≥ 1 finding, your status line MUST be `FIXED: 0 | FAILED: N | SKIPPED: 0 | VERIFICATION: FAIL` and every claimed fix MUST be marked FAILED in the report with `- **Verification**: FAIL — no commit produced`. Likewise if `git diff --cached --name-only` is NON-EMPTY (you forgot to commit some staged edits), status MUST be `VERIFICATION: FAIL` until the index is clean. Do not emit `VERIFICATION: PASS` with an empty commit log or dirty index — the orchestrator runs an **independent** deterministic audit (see `/apt:pr-review` SKILL.md Phase 6 Step 4b, `apt-tools pr-review audit-fixer`) that cross-checks your status line against the worktree git state. Emitting `PASS` when no commits exist will be caught deterministically and counted as a hallucination; your findings will be treated as unresolved and you may be re-spawned with an explicit hallucination callout.

package/dist/plugin/skills/apt/SKILL.md

@@ -130,6 +130,7 @@ Show available commands table:
 | `apt:resume` | Restore context after session break |
 | `apt:pause` | Human-initiated handoff — save state when YOU need to stop |
 | `apt:ship` | Create PR with traceability |
+| `apt:close-task` | Post-merge closer — confirm PR merged, flip phase, drain narration ledger |
 | `apt:setup` | Change framework preferences |
 
 Show current state summary and autonomy flags (`--supervised`, `--guided`, `--autonomous`, `--yolo`).

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

@@ -15,7 +15,7 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Bash, Read, Grep, Glob, Write"
-argument-hint: "apt:close-task [--all | --task <id>]"
+argument-hint: "apt:close-task [--all | --task <id>] [--narrate-only]"
 gates: []
 ---
 <objective>
@@ -40,6 +40,7 @@ Confirm a shipped PR has merged on GitHub, then run the closer side of the task
 - `.aperant/events/{today}.jsonl` — emits `task.closed.merged`.
 - `.aperant/config.json` — strips `authorship_overrides['pr-{N}']` entries for merged PRs.
 - `.aperant/roadmap/{scope}/**` — linked-phase flip (when `task_isolation.auto_close_phase: true`).
+- `.aperant/ci-watches/{pr}.json` — removed for each merged PR (BUG-027 (b) side-effect: prevents watcher state files leaking past PR-terminal-state). Idempotent — already-removed state is a no-op. For retroactive cleanup of orphan state files left behind by pre-fix runs, use `apt-tools ci-watch sweep . --orphaned`.
 </state_files>
 
 <process>
@@ -70,6 +71,7 @@ Internally, close-merged does:
    a. `apt-tools task close . --id {task-id} --verdict approved` (respects `task_isolation.auto_close_phase`).
    b. Strips `config.pr_review.authorship_overrides['pr-{N}']` if present.
    c. Emits `task.closed.merged` event.
+   d. Appends a `pending_narration[]` ledger row to `.aperant/state.json` so `--narrate-only` (see §4) can pick it up. Additive only; never blocks the close.
 3. When `state !== 'MERGED'`, the task stays in `shipped-pending-merge` with a skip reason the user can inspect.
 
 ## 2.5 Narrate completed phases (moved from /apt:ship in C56 B5)
@@ -85,6 +87,33 @@ For each entry in the close-merged envelope's `closed[]` whose record has a non-
 
 Do NOT wait on the narrator. Its status lands in `.aperant/digests/.last-run.json`. Skip narrator spawn entirely when `closed[]` is empty or no closed item has a phase_id.
 
+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:
@@ -95,6 +124,39 @@ 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.
+
+Flags:
+- `--narrate-only --all` (default when `--narrate-only` is bare) — drain every ledger entry.
+- `--narrate-only --task <id>` — drain only the entry for `<id>`.
+
+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
+{
+  "status": "ok",
+  "command": "close-task-narrate-only",
+  "narrated": [{ "task_id": "<id>", "phase_id": "<p|null>", "scope": "<s>" }],
+  "skipped": [{ "task_id": "<id>", "reason": "no-phase-id|features-audit-failed|narrator-spawn-failed" }],
+  "remaining": <ledger.length>
+}
+```
+
+The regular `apt:close-task` flow ALSO falls through to this drain step at the tail of §2.5 — so users who run the skill manually after the sweep get narration without remembering the flag. The `--narrate-only` flag exists for the explicit "drain only, don't poll gh" case.
+
 </process>
 
 <notes>