@aperant/framework 0.7.0 → 0.7.4

package/dist/plugin/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 |
 |---------|---------------------|
@@ -1454,33 +1463,63 @@ node packages/framework/bin/apt-tools.mjs workflow advance . --id ${REVIEW_ID} -
 
 If `WORKTREE_PATH != .` AND fixes were applied in Phase 6/7:
 
+Get the PR head ref (for branch reviews, use the branch name directly):
 ```bash
-cd ${WORKTREE_PATH}
+PR_HEAD_REF=$(gh pr view ${PR_NUMBER} --json headRefName -q .headRefName)
+```
 
-# Commit all staged fixes
-git add -A
-git commit -m "fix: auto-fix review findings from /apt:pr-review (review ${REVIEW_ID})"
+#### Confirmation gate (BUG-009 fix)
 
-# Push fixes back to the PR branch
-# For PRs: push to the PR's head ref
-git push origin HEAD:${PR_HEAD_REF}
+Whether the push prompts for confirmation is controlled by `pr_review.confirm_before_push` in `.aperant/config.json` (tri-state: `ask` | `auto` | `never`; default when absent: `auto` at autonomy ≥ 2, `ask` at autonomy < 2). Mirrors the `pr_review.suggest_after_ship` precedent in `/apt:ship` Section 7.1 — `ask` is honest about the irreversible-ish nature of the push (re-triggers CI on origin, visible to teammates); `auto` honors yolo pipelines.
 
-cd -
+```bash
+confirm_mode=$(jq -r '.pr_review.confirm_before_push // empty' .aperant/config.json)
+autonomy=$(jq -r '.autonomy.default // 2' .aperant/config.json)
+if [ -z "$confirm_mode" ]; then
+  if [ "${autonomy}" -ge 2 ]; then confirm_mode="auto"; else confirm_mode="ask"; fi
+fi
 ```
 
-Where `PR_HEAD_REF` is the PR's head branch name (e.g., `feat/auth`). Get it from:
+Branch on `confirm_mode`:
+
+- **`never`** — Skip push entirely. Print "fixes left in worktree; push manually with `git -C ${WORKTREE_PATH} push origin HEAD:${PR_HEAD_REF}`". Proceed to Step 0b cleanup.
+- **`auto`** — Proceed silently to the catch-all + push below. No prompt.
+- **`ask`** — Emit the structured question: `Fixes are ready in the worktree. Push to ${PR_HEAD_REF}? (y/n)`. On `n` or any non-`y`: same skip behavior as `never`. On `y` (or empty enter): proceed.
+
+`confirm_before_push` is purely additive — it does not affect `authorship_override`, `authorship_overrides`, `max_rounds`, or `suggest_after_ship` in the same `pr_review` block.
+
+#### Catch-all + push (BUG-010 fix)
+
+The fixer pipeline normally produces atomic per-finding commits, so the worktree is clean by the time Step 0 runs. The catch-all commit below exists ONLY to capture uncommitted residue (rare — e.g. a fixer's pre-return self-audit failed to detect a stray edit). Guard it before committing:
+
 ```bash
-gh pr view ${PR_NUMBER} --json headRefName -q .headRefName
-```
+cd ${WORKTREE_PATH}
 
-For branch reviews: push to the branch name directly.
+# Guard 1: skip the catch-all entirely if the tree is clean.
+# Per-finding commits with proper messages are strictly better history than a single catch-all.
+if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
+  # Guard 2: explicit allowlist instead of `git add -A`.
+  # `git add -A` would sweep orchestrator-level Read/Write side-effects
+  # (metadata.json, audit.json, validated.md, etc.) into the PR. Bad.
+  # Stage ONLY files in the review's touched set, computed from the iteration diffs.
+  REVIEW_TOUCHED=$(git diff --name-only ${ITERATION_START_SHA:-HEAD~4}..HEAD 2>/dev/null \
+                   | grep -v '^\.aperant/' \
+                   | tr '\n' ' ')
+  if [ -n "$REVIEW_TOUCHED" ]; then
+    # shellcheck disable=SC2086
+    git add -- $REVIEW_TOUCHED
+  fi
+  # Only commit if `git add --` actually staged something.
+  if ! git diff --cached --quiet; then
+    git commit -m "fix: auto-fix review findings from /apt:pr-review (review ${REVIEW_ID})"
+  fi
+fi
 
-**IMPORTANT:** Ask the user for confirmation before pushing:
-```
-Fixes are ready in the worktree. Push to ${PR_HEAD_REF}? (y/n)
+git push origin HEAD:${PR_HEAD_REF}
+cd -
 ```
 
-If the user declines, skip the push but still write the report. The fixes remain in the worktree for manual review.
+Two guards. The outer `if` skips the whole catch-all path when the tree is clean. The inner allowlist (filter to files in the iteration-diff scope, minus anything under `.aperant/`) prevents `git add` from sweeping arbitrary orchestrator side-effects into the PR. Both guards default to the safe no-op shape on the happy path (fixers committed atomically, clean tree).
 
 ### Step 0b: Cleanup Worktree
 

package/dist/plugin/skills/apt-prototype/LOGIC.md

@@ -0,0 +1,109 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/LOGIC.md
+Licensed under MIT. Modifications: scoped to terminal-app prototypes
+that validate state machines, protocols, and control flow. Aligned with
+the 5 universal rules in apt-prototype/SKILL.md.
+-->
+
+# LOGIC branch — Terminal app for state-machine validation
+
+When the user's question is about **behavior**, the prototype is a
+single terminal app that the user runs and watches. The output prints
+every state transition so the user can FEEL whether the logic works,
+not just reason about it.
+
+## When this branch fires
+
+Question types that route here:
+
+- "Does this state machine work?"
+- "Does this control flow handle edge case X?"
+- "Can this protocol handle out-of-order messages?"
+- "What does the worker pool do under back-pressure?"
+- "Does this retry policy actually converge?"
+
+Question types that DO NOT route here (use UI branch instead):
+
+- "Does this UI shape feel right?"
+- "Is this flow discoverable?"
+- "Does this layout work on mobile?"
+
+## File shape
+
+ONE file. Pick the project's primary runtime (TypeScript via `tsx`,
+JavaScript via `node`, Python via `python3`, etc.). The shape:
+
+```
+// THROWAWAY PROTOTYPE — do not merge, do not extend, do not test.
+// Question: "{verbatim question from user}"
+// Decision criterion: "{what does 'yes' look like? what does 'no' look like?}"
+
+// --- State machine model ---
+// {Declare states, transitions, and any guards.}
+
+// --- Transition driver ---
+// {A function that takes (currentState, event) and returns nextState,
+//  PRINTING every transition so the user can see what's happening.}
+
+// --- Scripted run ---
+// {5-10 sequential transitions that exercise the interesting paths.}
+```
+
+## Single-command invocation
+
+The prototype runs with ONE command. Examples:
+
+- `node prototype.mjs` — no transpile, no build, no install
+- `pnpm dlx tsx prototype.ts` — uses dlx so no dependency added to the project
+- `python3 prototype.py` — no virtualenv setup
+
+If your prototype needs any of: webpack, vite, esbuild, a database
+connection, an environment variable — you are prototyping the wrong
+question. Re-scope to the BEHAVIOR question; the infrastructure is a
+separate concern.
+
+## Surface-state-transparently — concrete examples
+
+A terminal app prints state transitions inline:
+
+```
+[T+0]  state=IDLE
+[T+1]  event=user.click.submit → state=SUBMITTING
+[T+2]  event=network.timeout → state=RETRYING (attempt 1)
+[T+3]  event=network.timeout → state=RETRYING (attempt 2)
+[T+4]  event=network.timeout → state=FAILED (exceeded retries)
+```
+
+The user reads this output and either says "yes that's what I wanted"
+or "no, the retry policy needs jitter" — and the question is answered
+in 30 seconds of looking, not 3 hours of staring at a flowchart.
+
+If the state machine has parallel regions or hierarchical states, print
+the full state vector at each transition, not just the leaf state.
+
+## When the scripted run isn't enough
+
+If the user needs to drive the state machine interactively (the
+question is "what happens when I hit submit twice quickly?"), add a
+tiny REPL loop:
+
+```
+> submit
+[T+1] event=user.click.submit → state=SUBMITTING
+> submit
+[T+2] event=user.click.submit (REJECTED — already submitting)
+[T+2] state=SUBMITTING
+> timeout
+[T+3] event=network.timeout → state=RETRYING (attempt 1)
+```
+
+Keep the REPL parser dumb (split on space, no quoting, no escape
+handling). The user isn't testing your parser; they're testing the
+state machine.
+
+## Throwaway discipline reminder
+
+When the question is answered, delete the prototype file. Do not let it
+linger as "documentation of the design decision" — that's what
+`apt-tools adr write` or `.aperant/context/notes/` are for.

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

@@ -0,0 +1,143 @@
+---
+name: apt:prototype
+description: "Question-driven throwaway prototyping with 5-rule discipline — LOGIC branch (terminal-app for state-machine validation) and UI branch (delegates to apt:mockup)"
+apt-skill-version: {{APT_VERSION}}
+stage: design
+intent: design
+when_to_use: "The user has a question that wants a runnable prototype rather than a plan — 'does this state machine work?' (LOGIC branch) or 'does this UI shape feel right?' (UI branch). Throwaway code by design; do NOT confuse this with apt:plan or apt:execute."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: create-new
+default_track: STANDARD
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:prototype [question]"
+gates: []
+config_keys:
+  - coding.prototype_discipline
+---
+
+# Prototype — Question-Driven Throwaway Code
+
+This skill ships throwaway code that answers ONE question. It is NOT a
+planning artifact, NOT a feature, and NOT something to merge. The output
+is a single-command-runnable prototype that lets the user feel whether
+the question's answer is "yes" or "no", then gets thrown away.
+
+**Pocock adoption attribution.** Discipline ported from Matt Pocock's
+MIT-licensed `prototype` skill. Routes between two branches by
+question-type; the UI branch delegates to Aperant's existing
+`/apt:mockup` skill for HTML+Tailwind variants. The LOGIC branch and
+the 5-rule discipline are new for Aperant.
+
+## When to Use
+
+- The user asks a question (not a "build me X" request) — "does this
+  state machine work?", "does this UI shape feel right?", "would users
+  find this discoverable?"
+- A throwaway prototype is the cheapest answer (cheaper than designing,
+  planning, building, then discovering the answer was "no")
+- The answer can be felt by running the prototype, not just reasoning
+  about it
+
+## When NOT to Use
+
+- The user has a feature request — use `/apt:plan` + `/apt:execute`
+- The user wants a polished mockup to share — use `/apt:mockup` directly
+  (the UI branch of this skill delegates there anyway)
+- The user wants production code with tests — that's TDD-mode
+  `/apt:execute --tdd`, not a prototype
+
+## Branch routing
+
+Inspect the user's question:
+
+- **LOGIC branch** — triggers: "does this state machine work?", "does
+  this control flow handle edge case X?", "can this protocol handle
+  out-of-order messages?". Answer: a single-file terminal app the user
+  can run with one command to feel the state transitions.
+- **UI branch** — triggers: "does this UI shape feel right?", "is this
+  flow discoverable?", "does this layout work on mobile?". Answer:
+  delegate to `/apt:mockup --variants 3` for HTML+Tailwind parallel
+  variants.
+
+If the question is genuinely ambiguous, ask ONE clarifying question
+("are you asking about behavior or appearance?") — do NOT enter a long
+interview.
+
+## The 5 Universal Rules (Pocock discipline, applies to both branches)
+
+These five rules apply to EVERY prototype this skill produces. They are
+load-bearing — violating them collapses the prototype into ceremony
+disguised as a question.
+
+1. **Throwaway-marked.** Every prototype file MUST carry a top-of-file
+   comment: `// THROWAWAY PROTOTYPE — do not merge, do not extend, do
+   not test.` This is not optional. Files without this marker drift into
+   production code and the question never gets answered cleanly.
+
+2. **Single-command-run.** The prototype runs with ONE command. No
+   build step. No dependency install. `node prototype.mjs` or `pnpm dlx
+   tsx prototype.ts` or `bash prototype.sh` — pick one and stop. If you
+   reach for webpack, you're prototyping a build, not the question.
+
+3. **No-persistence-default.** The prototype does NOT touch any
+   persistent store (libSQL, Convex, localStorage, .aperant/state.json).
+   Everything is in-memory. If persistence is part of the question,
+   explicitly opt in via a tmpfile — never the project's actual stores.
+
+4. **Skip-polish.** No error handling for impossible scenarios. No
+   accessibility audit. No mobile responsive breakpoints unless the
+   question is about mobile. No animation refinement. Polish is what
+   you do AFTER the prototype answered "yes"; doing it now obscures
+   whether the answer was actually "yes".
+
+5. **Surface-state-transparently.** The prototype prints / renders its
+   internal state at every step the user might want to inspect. A
+   terminal app prints every state transition. A UI prototype shows
+   the data shape next to the rendered output. The user must be able
+   to SEE what's happening — they can't feel an answer to "does this
+   work" if the state is hidden.
+
+## LOGIC branch — terminal app for state-machine validation
+
+When the question is about behavior / control flow / state machines /
+protocols:
+
+1. Read `LOGIC.md` for the discipline (ported from Pocock's
+   `prototype/LOGIC.md` with MIT attribution).
+2. Write ONE file (e.g., `prototype.mjs`, `prototype.ts`, or
+   `prototype.py`) that:
+   - Models the state machine in code
+   - Provides a command-line driver that fires transitions one at a
+     time, printing each state
+   - Includes a 5-10 turn scripted run at the bottom that exercises the
+     interesting paths
+3. Write a one-line invocation: `node prototype.mjs` (or whatever).
+4. Verify: run it. The user reads the output, gets their answer, and
+   the file is deleted.
+
+## UI branch — delegates to apt:mockup
+
+When the question is about layout / aesthetics / flow / discoverability:
+
+1. Read `UI.md` for the discipline (ported from Pocock's
+   `prototype/UI.md` with MIT attribution).
+2. Invoke `/apt:mockup --variants 3` as a sub-step. apt:mockup already
+   enforces the UI-specific universal rules (zero-dep Tailwind CDN, no
+   JS, throwaway HTML iterations preserved).
+3. The 5 universal rules above still apply — verify each HTML file
+   carries the `<!-- THROWAWAY PROTOTYPE -->` marker.
+
+## Output contract
+
+- Single prototype file (LOGIC) OR 3 HTML variants via apt:mockup (UI).
+- No commits. No tests. No docs. The skill emits a final note: "Delete
+  this when the question is answered."
+- If the user wants to convert the prototype into real code, that's a
+  separate `/apt:plan` invocation.

package/dist/plugin/skills/apt-prototype/UI.md

@@ -0,0 +1,90 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/prototype/UI.md
+Licensed under MIT. Modifications: routed through Aperant's existing
+apt:mockup skill rather than a freestanding HTML+Tailwind generator;
+aligned with the 5 universal rules in apt-prototype/SKILL.md.
+-->
+
+# UI branch — Delegates to apt:mockup
+
+When the user's question is about **appearance / layout / flow /
+discoverability**, the prototype is one or more HTML files generated
+by Aperant's existing `/apt:mockup` skill. apt:mockup already enforces
+the UI-specific universal rules (zero-dep Tailwind CDN, no JS, throwaway
+HTML iterations preserved).
+
+## When this branch fires
+
+Question types that route here:
+
+- "Does this UI shape feel right?"
+- "Is this flow discoverable?"
+- "Does this layout work on mobile?"
+- "Should the primary action be a button or a card?"
+- "How does X scale to N items?"
+
+Question types that DO NOT route here (use LOGIC branch):
+
+- "Does this state machine work?"
+- "Does this control flow handle edge case X?"
+- "Can this protocol handle out-of-order messages?"
+
+## How the delegation works
+
+apt:prototype's UI branch is a thin wrapper that:
+
+1. Parses the user's question to extract the UI element / flow being
+   asked about (e.g., "search results card with N items").
+2. Invokes the existing skill: `/apt:mockup --variants 3 [extracted topic]`.
+3. apt:mockup produces 3 parallel HTML+Tailwind variants under
+   `.aperant/mockups/{topic-slug}/` so the user can compare them
+   side-by-side.
+
+apt:prototype does NOT re-implement HTML+Tailwind generation — the
+discipline lives in apt:mockup's body. UI.md exists so the apt:prototype
+skill body can branch on question-type without conflating "logic
+prototype" and "UI mockup" code paths.
+
+## The 5 universal rules still apply
+
+apt:mockup already enforces:
+
+- Throwaway-marked (each HTML file carries a comment marker)
+- Single-command-run (`open mockup.html` — zero dependencies)
+- No-persistence-default (static HTML, no localStorage usage by default)
+- Skip-polish (CSS reset, no animation refinement, no responsive
+  breakpoints unless the question is about responsive)
+
+The fifth rule — **surface-state-transparently** — is the one
+apt:mockup doesn't fully cover by default. For UI prototypes where the
+question is about data shape (e.g., "what does this look like with 0
+items vs 100 items?"), instruct apt:mockup to render each variant with
+a different data-fixture state, and put the fixture JSON in a
+side-panel of each mockup so the user can see what's driving the
+render.
+
+## What apt:prototype's UI branch adds over running apt:mockup directly
+
+Two things:
+
+1. **Question framing.** apt:mockup is invocable as "build me a mockup
+   of X". apt:prototype's UI branch is invocable as "I have a question
+   about UI X — show me three answers." The framing shifts the
+   discipline from "deliver the mockup the user asked for" to "answer
+   the user's question with the cheapest possible visual artifact."
+
+2. **5-rule cross-discipline reminder.** When the UI branch fires, the
+   skill body explicitly re-states all 5 universal rules (not just the
+   UI-specific ones). The user gets the apt:prototype mental model on
+   top of apt:mockup's mechanical output — which prevents the variant
+   from drifting into "polish this until it's production-ready."
+
+## When the apt:mockup delegation is NOT enough
+
+If the question requires interaction the user can drive (click through,
+hover states, conditional rendering on input), the right call is
+`/apt:prototype` LOGIC branch on top of `/apt:mockup` — a tiny
+JS-driven terminal-ish runner that swaps between the 3 mockups based
+on simulated state. This is rare; most UI questions are answered by
+the side-by-side parallel variants apt:mockup already produces.

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

@@ -21,6 +21,8 @@ gates: []
 ---
 <objective>
 Execute a small task quickly without full pipeline overhead. For small fixes, doc updates, config changes, and ad-hoc tasks. Skip planning — go straight to implementation with atomic commits and lightweight state tracking.
+
+**QUICK is sequential single-agent by contract.** Per roundtable 2026-05-14 (R1), QUICK = one agent doing intent → implementation in one context window. There are no phase sub-agents. This is a contract, not an optimization — the QUICK track exists precisely because phase isolation buys nothing on tasks small enough that the planner's mental model and the implementer's mental model would be identical.
 </objective>
 
 <your_environment>
@@ -99,6 +101,34 @@ If the task does NOT cross any obligation axes, proceed normally.
 2. Use Glob/Grep to find the files that need changes
 3. Read those files to understand current state
 
+## 3.5. Risk Check (mandatory)
+
+Before implementing, check the risk class of files this task will modify. QUICK shares the same Critical/Destructive hard stop as `/apt:execute` step 3b — the speed of QUICK does NOT waive the risk gate. Misclassified QUICK tasks touching `**/auth/**`, `**/schema*`, `**/convex/schema.*`, or other Critical paths must NOT commit without explicit human approval.
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs risk-check . --paths {target files}
+```
+
+If the task description contains destructive keywords ("delete", "remove", "drop", "force-push"), pass `--operation delete` so glob matching covers the destructive intent.
+
+Parse the JSON result and apply the gate:
+
+**If `risk_class` is `"Critical"` or `"Destructive"`:**
+Stop execution. Show the user:
+```
+RISK GATE: This QUICK task touches {risk_class} files.
+Files: {matched_paths list}
+Pattern: {matched_pattern}
+
+Approve this change? (yes/no)
+```
+Wait for explicit approval. If denied, abort the task and record `verification.risk_gate = "denied"` in `task.json`. The gate is hardcoded at ALL autonomy levels — QUICK does not get to skip it.
+
+**If `risk_class` is `"Elevated"` AND autonomy < 3:**
+Show the affected files briefly before proceeding (5-second delay; user can interrupt). At YOLO autonomy, proceed without stopping.
+
+**Why this exists:** roundtable 2026-05-14 R1 surfaced that `apt-quick` previously had no risk-check gate, meaning a misclassified QUICK task touching schema/auth could commit Critical-path changes with zero code-level safeguard. See `.aperant/roundtables/phase-mode-per-track-20260514/REPORT.md` (R1, Risk Assessment §1).
+
 ## 4. Implement
 
 Make the changes directly:
@@ -249,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.