@aperant/framework 0.7.0 → 0.7.3

package/package.json

@@ -1,134 +1,134 @@
 {
-  "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"
-  }
-}
+	"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>

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:

package/skills/apt-setup/SKILL.md

@@ -1111,6 +1111,34 @@ The selective-edit pass through Batch 9 MUST respect the §1b dispatch — it do
 
 ## 4. Map Answers to Config
 
+**AUDIT-001 — file-routing contract for per-device fields (UPDATED 0.7.2):** the
+following five fields are PER-DEVICE and MUST land in `.aperant/config.local.json`
+(gitignored), NOT the shared `.aperant/config.json`:
+- `verification.open_report` — covered in the "Auto-Open" mapping below.
+- `multi_model.cross_verification.tools` — covered in the "Cross-Verification" mapping below.
+- `preferences.date_format` — covered in the "Date Format" mapping below.
+- `preferences.time_format` — covered in the "Time Format" mapping below.
+- `preferences.quick_task_post_verify` — covered in apt-quick SKILL config block.
+
+All other fields (including `verification.evidence_capture`,
+`multi_model.cross_verification.enabled`, `multi_model.video_review.*`,
+`preferences.task_index`, every `orchestration.*` value) stay in shared
+`.aperant/config.json`.
+
+Implementation: use the framework's `writeLocalConfigField(targetDir, dotPath, value)`
+helper from `packages/framework/src/cli/config/load.mjs` (or its shell-out
+equivalent via `apt-tools config write . --local --key <dotpath> --value <json>`)
+for the five fields above. NEVER hand-roll `JSON.parse(readFileSync('.aperant/config.json'))`
+followed by `writeFileSync('.aperant/config.json', ...)` for these fields — it
+will land per-device data in the shared file and re-introduce the
+shared-config trap AUDIT-001 was designed to close.
+
+Reads of these fields anywhere in the framework MUST go through
+`loadMergedProjectConfig(targetDir)` or `readLocalOrSharedField(targetDir, dotPath)`
+so per-device overrides are honored.
+
+---
+
 Map the user's selections to config values:
 
 **Verify Mode:**
@@ -1180,13 +1208,16 @@ Note: task ids are slug-first since v0.6.6 — the date-format setting controls
 
 ## 5. Write Config
 
-Write merged config to `.aperant/config.json`:
+Write merged config to two files per AUDIT-001 routing (see Step 4 block):
+
+- Shared `.aperant/config.json` — all project policy values (the bulk of the answers).
+- Per-device `.aperant/config.local.json` — the five AUDIT-001 fields enumerated in Step 4.
 
 ```bash
 mkdir -p .aperant
 ```
 
-Write the JSON file with 2-space indentation. Bump `version` to 4 if upgrading from an older config (versions 2/3 load forward-compatibly — the new `tdd` block is optional).
+Write each JSON file with 2-space indentation. Bump shared `config.json`'s `version` to 4 if upgrading from an older config (versions 2/3 load forward-compatibly — the new `tdd` block is optional). `config.local.json` is gitignored by `.aperant/.gitignore` — do not check it in.
 
 ## 6. Save as Global Defaults (Optional)