@aperant/framework 0.6.7 → 0.7.3

package/package.json

@@ -1,134 +1,134 @@
 {
-  "name": "@aperant/framework",
-  "version": "0.6.7",
-  "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"
-  }
-}
+	"name": "@aperant/framework",
+	"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": "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"
+	}
+}

package/prompts/conductor-framework-context.md

@@ -0,0 +1,63 @@
+<!-- Conductor Framework Context (auto-injected) -->
+# Aperant framework — slash-skills dispatchable in sub-terminals
+
+Dispatch via `sendToTerminal(terminalId, '/<skill> <args>\\r', ...)`.
+
+## Skills
+
+| Skill | When to dispatch |
+|-------|------------------|
+| `/apt:author-skill` | Author a new Aperant skill (test-first stub). |
+| `/apt:bootstrap` | Generate / refresh PROJECT.md. |
+| `/apt:close-task` | Post-merge: confirm PR merged, flip phase, GC state. |
+| `/apt:create-docs` | Persona-first product docs from PROJECT.md + features. |
+| `/apt:debug` | Systematic debugging with persistent state. |
+| `/apt:design` | DESIGN.md + wireframe + critique. Hands off to apt:plan. |
+| `/apt:diagram` | .excalidraw / MCP-canvas diagrams. |
+| `/apt:discuss` | Brainstorm vision or lock ambiguous decisions. |
+| `/apt:docs` | Generate / update documentation verified against code. |
+| `/apt:execute` | Execute an implementation plan — build code from subtasks. |
+| `/apt:improve` | Proactive refactor via DEEPENING / INTERFACE / LANGUAGE lenses. |
+| `/apt:mockup` | HTML+Tailwind mockup loop with parallel variants. |
+| `/apt:pause` | Human-initiated session handoff. |
+| `/apt:personas` | Discover 3-5 personas grounded in code + PROJECT.md. |
+| `/apt:plan` | Create an implementation plan from a task description. |
+| `/apt:pr-review` | Multi-agent PR review (6 specialists, validator, fixer). |
+| `/apt:prototype` | Question-driven throwaway prototyping. |
+| `/apt:quick` | Fast task execution — skip planning. |
+| `/apt:release-notes` | Persona-aware user-facing release notes. |
+| `/apt:resume` | Restore context from paused session / crash. |
+| `/apt:review` | Task-level code review (6-pass fix-all pipeline). |
+| `/apt:roadmap` | Manage per-scope roadmaps (milestones, phases). |
+| `/apt:roundtable` | 10-agent structured debate w/ supermajority vote. |
+| `/apt:run` | Full pipeline — plan/execute/verify/review. |
+| `/apt:scan` | Build/refresh the .aperant/features/ registry. |
+| `/apt:setup` | Configure Aperant preferences. |
+| `/apt:ship` | Open PR with QA scores + decision traceability. |
+| `/apt:spar` | Adversarial sparring loop between two CLIs (max 3 rounds). |
+| `/apt:stress-test` | Scenario simulation to catch plan gaps. |
+| `/apt:terminal` | Spawn a sibling Aperant terminal w/ its own worktree. |
+| `/apt:triage` | Move a task through the 5-state triage machine. |
+| `/apt:update` | Refresh installed skills/agents/hooks across runtimes. |
+| `/apt:verify` | Validate implementation against spec (QA review loop). |
+| `/apt:verify-proof` | Visual proof-of-work verification (screenshots, BETA). |
+| `/apt:watch-ci` | Post-ship CI watcher (poll, auto-fix red, push). |
+| `/apt:zoom-out` | Orient yourself in an unfamiliar area — one-page summary. |
+
+## Dispatch recipe
+
+Spawn a Claude Code CLI in a fresh terminal, then send the slash:
+
+```
+spawnTerminal({ projectPath, cwd, cliCommand: 'claude --dangerously-skip-permissions', ... })
+sendToTerminal(terminalId, '/apt:plan <terse task description>\r', ...)
+```
+
+Codex / Gemini / OpenCode ports exist — swap `cliCommand` accordingly.
+Skill semantics are identical across CLIs.
+
+## Observe-then-act
+
+Read what a sub-terminal produced via `readFromTerminal(terminalId,
+{tailBytes?})`. Use AFTER a write to confirm the skill took. NEVER assume
+the write landed — observe.

package/prompts/conductor-system.md

@@ -97,10 +97,21 @@ Write (use when needed, no human approval gating):
 - `listTerminals()` — fleet snapshot (cwd, busyState, isCLIMode).
 - `sendToTerminal(terminalId, input, requestId, reasoning)` — tap-on-
   shoulder. Always one line. Append `\r` to submit. NEVER multi-line essay.
+- `readFromTerminal(terminalId, {tailBytes?})` — snapshot recent PTY
+  output (~100 KB cap). Use AFTER `sendToTerminal` to confirm the write
+  took. NEVER assume — observe. On self-hosted web / cloud the host may
+  return `{output: null, error: 'host not action-capable in this mode'}`;
+  fall back to `readEventLog` polling there.
 - `destroyTerminal(terminalId, requestId, reasoning)` — irreversible.
   Prefer graceful `sendToTerminal('exit\r')`.
 - `emitIntent({...})` — audit envelope for non-tool decisions.
 
+## Framework knowledge
+
+The auto-injected `conductor-framework-context` block at the very top of
+this system prompt lists every `/apt:*` skill you can dispatch into a
+sub-terminal. Consult it BEFORE deciding which skill to send.
+
 Tool surface depends on host. If `spawnTerminal` is not in your tools,
 you are in observe-only mode — do not promise spawns; describe what you
 WOULD do.

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

@@ -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>
@@ -123,6 +124,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.
@@ -133,10 +136,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-discuss/SKILL.md

@@ -17,7 +17,7 @@ execution_modes:
   - step
   - research
 allowed-tools: "Bash, Read, Grep, Glob, Write"
-argument-hint: "apt:discuss [--brainstorm] [topic]"
+argument-hint: "apt:discuss [--brainstorm] [--grill] [topic]"
 gates: []
 ---
 <objective>
@@ -183,10 +183,11 @@ If any file is missing, proceed with what's available. The framework works with
 Extract the task description from `$ARGUMENTS`:
 
 1. Strip mode flags (`--assumptions`, `--power`, `--auto`, `--review-auto`, `--continue`) from arguments
-2. The remaining text is the task description
-3. If task description is empty but `state.json` has an `active_task`, use that task's description
-4. If still empty, ask: "What are you working on?"
-5. Generate a `task-id` slug from the description: lowercase, hyphens, max 40 characters
+2. Strip the **`--grill`** overlay flag from arguments (orthogonal to the mode flags — see Section 6.5). `--grill` may combine with any mode; standalone `--grill` defaults to Interactive.
+3. The remaining text is the task description
+4. If task description is empty but `state.json` has an `active_task`, use that task's description
+5. If still empty, ask: "What are you working on?"
+6. Generate a `task-id` slug from the description: lowercase, hyphens, max 40 characters
    - Example: "Add OAuth login with Google" -> `add-oauth-login-with-google`
 
 ## 3.5. Brainstorm (skip if you picked decision-lock in Section 1)
@@ -564,6 +565,47 @@ Review-Auto is Auto Mode **plus one human checkpoint at the batch end**. It does
 
 Do NOT introduce per-decision staging ("show me D-01, wait, show me D-02, wait...") — that collapses review-auto into spaced interactive mode and defeats the point of joint reasoning up front. Do NOT skip the pause ("autonomy is high, let's just write it") — that collapses review-auto into auto. The one pause at the end is the whole identity of this mode.
 
+## 6.5. Grill Mode (`--grill` flag — Pocock `grill-with-docs` overlay)
+
+**Activate when:** the user invoked the skill with `--grill`. This is an **overlay**, not a mode — it stacks on top of whichever Section 6 mode is active (Interactive by default; combine with `--auto` etc. as desired). The overlay does two things: (1) it applies Pocock's 4 grill moves during decision resolution; (2) it fires inline writes to CONTEXT.md and ADRs as terms resolve and decisions pass the Nygard 3-gate.
+
+The discipline this overlay loads is already in [`appendices/grill-discipline.md`](./appendices/grill-discipline.md) — re-read the reframe sentence and the autonomy degradation table before each grill turn. **Do NOT duplicate that content here.** What follows is only the moves + writer-call instructions specific to the overlay.
+
+### The 4 grill moves (apply during gray-area resolution)
+
+1. **Challenge against the glossary.** When the user uses a term that conflicts with an existing CONTEXT.md term-block, call it out immediately: *"Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"* Read `CONTEXT.md` (or per-context CONTEXT files via `CONTEXT-MAP.md`) when the overlay activates; skip silently if absent.
+2. **Sharpen fuzzy language.** When the user uses vague or overloaded terms, propose a precise canonical term: *"You're saying 'account' — do you mean Customer or User? Those are different things."*
+3. **Stress-test with concrete scenarios.** When domain relationships are being discussed, invent specific scenarios that probe edge cases and force precision about the boundaries between concepts.
+4. **Cross-reference with code.** When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: *"Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"*
+
+### Inline writer calls (NOT batched)
+
+When a term resolves with confidence during the grill, invoke `apt-tools context write` to upsert the term-block into CONTEXT.md **right there** — do NOT batch:
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs context write . \
+  --term "Plan thread" \
+  --definition "<one-line definition>" \
+  --aliases-to-avoid "Plan session,plan chat" \
+  --cardinality "one-to-many"
+```
+
+**Lazy creation:** if no `CONTEXT.md` exists at the project root (or in the relevant per-context directory when `CONTEXT-MAP.md` is present), the first resolved term creates the file. Do NOT create CONTEXT.md upfront with placeholder content.
+
+**Glossary-only rule:** CONTEXT.md is a glossary of domain terms — NO implementation details, NO spec content, NO scratch-pad notes. Implementation lives in `spec.md` / `implementation_plan.json`; scratch lives in `.aperant/context/notes/{task-id}.md`. Term-blocks are user-facing concepts (e.g. "Plan thread", "Sparring round"), not code identifiers (e.g. "ChatSession", "useTaskStore").
+
+When a decision passes the **Nygard 3-gate**, offer to write an ADR via `apt-tools adr write .`. The 3-gate (ALL three must hold — miss one and skip the ADR):
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful.
+2. **Surprising without context** — a future reader will wonder *"why did they do it this way?"*.
+3. **Result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons.
+
+If only one or two hold, the decision belongs in `.aperant/context/notes/{task-id}.md` (locked-decisions list), not in an ADR.
+
+### Autonomy interaction
+
+`--grill` does not change the autonomy degradation already specified in [`appendices/grill-discipline.md`](./appendices/grill-discipline.md). Autonomy 1 grills every term/decision interactively; Autonomy 2 batches recommendations; Autonomy 3 auto-locks with the three escalation triggers (conflict-with-locked, critical-path file, no-defensible-default). The overlay simply ensures that whichever autonomy path runs, the writer CLIs fire as side-effects of the resolution work.
+
 ## 7. Advanced Elicitation (DEEP Tasks Only)
 
 After all decisions are locked, check the task track. If the track is DEEP (from state.json or router context), behavior depends on the resolved mode from Section 6's precedence chain (D-07):

package/skills/apt-execute/SKILL.md

@@ -383,11 +383,20 @@ executor commits introduce a new feature surface without registering it.
 
 ```bash
 node packages/framework/bin/apt-tools.mjs features-audit . \
+  --task-id "$TASK_ID" \
   --diff-files "$(git diff --name-only HEAD^ HEAD | tr '\n' ',')" \
   --apply-stubs
 ```
 
 Notes:
+- `--task-id $TASK_ID` (BUG-025b) is mandatory when the executor runs
+  from the main-repo cwd instead of inside the worktree (the
+  orchestrator's common path). features-audit resolves the worktree's
+  `.aperant/features/` from the active task record and writes there,
+  preventing generated `*.json` from leaking into main. When invoked
+  from the worktree cwd directly, `--task-id` is a no-op (layer 1
+  detection short-circuits). Pass `--no-worktree-redirect` only when
+  you intentionally want to write to the invoking cwd.
 - `--apply-stubs` only runs when the matched surface's policy is
   `auto-update` (the default for `.aperant/features/*.json`). Users who
   opted out via `/apt:setup` Batch 7 get a no-op — the command still

package/skills/apt-plan/SKILL.md

@@ -99,6 +99,18 @@ For STANDARD and COMPLEX tasks:
    - Test files that will need updates
    - Configuration that may need changes
 
+### 4.4. 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 exactly 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`).
+
+Investigation checklist when the task touches a Zustand/Jotai store or any handler that does flush-after-mutate:
+
+- Grep for `useRef(` references that cache store state (e.g. `const fooRef = useRef(foo)` populated by `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()` (or `useFooStore.getState()`) as the read primitive.
+- Note the caveat explicitly in the spec's Implementation Decisions section so the executor doesn't silently revert it.
+
 ### 4.5. Consume design.md (C24)
 
 If `{task_dir}/design.md` exists (emitted by a prior `/apt:design` run), load it before decomposing subtasks:

package/skills/apt-pr-review/SKILL.md

@@ -257,7 +257,7 @@ When the result is `unknown`, treat it as `external` for safety and prompt the u
 Authorship could not be auto-detected for PR #${PR_NUMBER}. Treat as [owned / external]? (default: external)
 ```
 
-If `autonomy_level >= 3` (yolo), skip the prompt and lock in `external`. Persist the user's answer to BOTH `pr-state.json:authorship` AND `config.json:pr_review.authorship_overrides['pr-${PR_NUMBER}']` so subsequent rounds don't re-ask.
+If `autonomy_level >= 3` (yolo), skip the prompt and lock in `external`. Persist the user's answer to `pr-state.json:authorship` so subsequent rounds don't re-ask. (Per C56 A3 — authorship overrides moved from `config.json:pr_review.authorship_overrides` to per-PR `pr-state.json` so they GC with the pr-review round. Legacy `config.json` entries are still read with a deprecation warning + auto-promoted to pr-state on next `init-pr`; do NOT write to `config.json` from new code.)
 
 Store the result as `AUTHORSHIP_MODE` and use it as a gate at every later phase:
 
@@ -1195,6 +1195,12 @@ Take all confirmed, fixable findings and group them into up to 3 independent gro
 
 #### Step 3: Spawn Fix Agents
 
+**Capture the iteration-start SHA BEFORE spawning fixers** (used by both the Step 4b audit gate AND the per-fixer Pre-Return Self-Audit added in BUG-016 — fixers now commit atomically per finding, and the audit window is scoped by this SHA):
+
+```bash
+ITERATION_START_SHA=$(cd "${WORKTREE_PATH}" && git rev-parse HEAD)
+```
+
 For each fix group, spawn a fix agent. Read the agent definition from `.claude/agents/apt-pr-review-fixer.md` and fill in:
 
 | Placeholder | Value |
@@ -1207,6 +1213,7 @@ For each fix group, spawn a fix agent. Read the agent definition from `.claude/a
 | `[CRITICAL_APPROVAL]` | `true` or `false` for each critical finding in this group |
 | `[PARALLEL_FIXERS]` | `true` if more than 1 fixer is spawned this iteration |
 | `[WORKTREE_PATH]` | The worktree path — fix agents edit files HERE, not in the user's working directory |
+| `[ITERATION_START_SHA]` | The SHA captured BEFORE spawning fixers (see Step 4b's `ITERATION_START_SHA=$(...)` capture). Required for BUG-016 commit-discipline Pre-Return Self-Audit. |
 
 ```
 Agent(
@@ -1260,7 +1267,9 @@ If `--since-sha` is **omitted**, the CLI falls back to `git merge-base HEAD orig
 
 Rule of thumb: pass `--since-sha "${ITERATION_START_SHA}"` on every audit invocation. The merge-base fallback exists only so a missing flag doesn't flip every standard-branch-workflow repo into a false-positive hallucination — it is NOT a replacement for the explicit flag.
 
-The CLI returns a JSON envelope with `verdict` ∈ `verified | hallucinated | skipped`, writes `iterations/${ITERATION}/audit.json` (append-only), and bumps `metadata.json.fixer_hallucinations_total` on every `hallucinated` outcome. The envelope's `observed.since_sha` + `observed.since_sha_source` fields record which SHA was used and where it came from (`flag` | `merge-base` | `null`). The same envelope is used for the fixer and the self-reviewer (Phase 7) — `--fixer self-reviewer` reads from `self-review.md` instead of `fixes-applied-group{N}.md`.
+The CLI returns a JSON envelope with `verdict` ∈ `verified | hallucinated | skipped`, writes `iterations/${ITERATION}/audit.json` (append-only), and bumps `metadata.json.fixer_hallucinations_total` on every `hallucinated` outcome. The envelope's `observed.since_sha` + `observed.since_sha_source` fields record which SHA was used and where it came from (`flag` | `merge-base` | `null`). The same envelope is used for the fixer and the self-reviewer (Phase 7) — `--fixer self-reviewer` reads from `self-review.md`.
+
+**Canonical fix-report filename per fixer (BUG-030):** each fixer agent writes to `fixes-applied-${FIXER_NAME}.md` (e.g. `fixes-applied-fixer-1.md`). The audit CLI resolves candidates in strict order: `fixes-applied-group{N}.md` (legacy group-named, pre-BUG-030 reviews) → `fixes-applied-fixer-{N}.md` (NEW fixer-named) → `fixes-applied-${FIXER_NAME}.md` (exact match, preferred for non-numeric fixer names) → `fixes-applied.md` (legacy unscoped, single-fixer reviews only). Writing the canonical name eliminates the cross-fixer false-positive `hallucinated` verdict that fired when two parallel fixers shared `fixes-applied.md`.
 
 | Verdict | Orchestrator Action |
 |---------|---------------------|

package/skills/apt-quick/SKILL.md

@@ -279,18 +279,29 @@ skill MUST exit silently regardless of the config value, so spawned subagents
 never block on a prompt that no human will answer.
 
 ```bash
-# Pseudocode the model executes inline:
+# Pseudocode the model executes inline.
+# AUDIT-001: `preferences.quick_task_post_verify` is per-device — read from
+# the MERGED config (shared `.aperant/config.json` + local
+# `.aperant/config.local.json`). Local wins on collision. Reading raw
+# `config.json` only would miss per-device overrides.
 node -e '
   const fs = require("fs");
   const path = require("path");
-  const cfgPath = path.join(process.cwd(), ".aperant/config.json");
+  const readJsonOrEmpty = (p) => { try { return JSON.parse(fs.readFileSync(p, "utf-8")) ?? {} } catch { return {} } };
+  const shared = readJsonOrEmpty(path.join(process.cwd(), ".aperant/config.json"));
+  const local = readJsonOrEmpty(path.join(process.cwd(), ".aperant/config.local.json"));
+  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);
   let mode = "ask";
-  try {
-    const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
-    if (cfg && cfg.preferences && cfg.preferences.quick_task_post_verify) {
-      mode = cfg.preferences.quick_task_post_verify;
-    }
-  } catch {}
+  if (cfg.preferences && cfg.preferences.quick_task_post_verify) {
+    mode = cfg.preferences.quick_task_post_verify;
+  }
   if (mode === "never" || !process.stdin.isTTY) process.exit(0);
   if (mode === "always") { /* invoke apt:verify {task-id} */ process.exit(0); }
   // mode === "ask": readline prompt with 30s timeout, default = skip.

package/skills/apt-researcher.md

@@ -41,6 +41,7 @@ Parse the investigation query. Identify:
 3. Read key files to understand the full picture
 4. Follow import chains to map dependencies
 5. Check tests for behavioral documentation
+6. **Report which refs cache store state on a render-cycle delay** (BUG-025-planner): when investigating React state or any Zustand/Jotai store touched by handlers, grep for `useRef(` patterns populated via `useEffect`. Flag them explicitly — they lag the store by one render and any sync-mutate-then-read code path against them silently corrupts. Reference pattern: `apps/desktop/src/renderer/src/App.tsx::runUpsertForIds` (post-fix commit `4c263856`).
 
 ## 3. Report Findings
 Produce a clear, structured answer: