@aperant/framework 0.7.0 → 0.7.4

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:
 
@@ -1110,6 +1110,8 @@ For `AUTHORSHIP_MODE == "owned"`, continue normally.
 
 AI agents have near-zero marginal cost per fix. The framework fixes **all** confirmed findings — critical, high, medium, and low — regardless of autonomy level. There is no severity gate and no "report for manual resolution" path. If a finding was confirmed by the validator, it gets fixed.
 
+**Hard rule — context budget is NOT a valid skip reason.** The orchestrator MAY NOT defer, drop, downgrade, or "punt for follow-up" any confirmed finding because its own context window feels heavy, because the run has already produced many fixes, or because it judges marginal value low. The query loop auto-compacts on its own — trust it. Per-finding fix work happens inside fix agents (separate context windows), so orchestrator pressure does not justify cutting their inputs. The only valid skip reasons are the ones enumerated in Key Principle #2 (`fixable: false`, critical finding without user approval, file assigned to another fixer). Any other skip is an unauthorized policy deviation — emit all confirmed findings to fixers, then let the audit gate adjudicate outcomes.
+
 | Autonomy | Action |
 |----------|--------|
 | `< 2` | Show findings summary before fixing. Then proceed with auto-fix. |
@@ -1195,6 +1197,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 +1215,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 +1269,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 |
 |---------|---------------------|
@@ -1638,7 +1649,7 @@ node packages/framework/bin/apt-tools.mjs workflow destroy . --id ${REVIEW_ID}
 Agents do NOT assign confidence percentages. Either they have evidence (actual code snippet from Read tool) or they do not have a finding. The validator independently verifies every finding against real code.
 
 ### 2. Fix Everything Found
-If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
+If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. **Neither is "my context window is heavy" or "I've already done a lot this run"** — orchestrator context pressure never authorizes dropping a confirmed finding (see Phase 6 → Principle: Fix Everything). The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
 
 ### 3. Findings Flow Through Files
 Agents write to `.aperant/pr-reviews/{review-id}/findings/`. The orchestrator reads with the Read tool. Fix agents read finding files directly. This keeps the orchestrator context under 30%.
@@ -1702,6 +1713,11 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
 **Wrong:** Skipping Phase 6 entirely when autonomy < 2.
 **Right:** Always fix all confirmed findings. At autonomy < 2, show findings summary first, then proceed with auto-fix. The only difference is whether findings are displayed before fixing — not whether they get fixed.
 
+### Mistake 7a: Dropping Findings Because Orchestrator Context Feels Heavy
+
+**Wrong:** Mid-Phase-6, the orchestrator decides "my window is getting heavy after 6 specialist rounds + Round 1 fixes — I'll skip the minor findings and report a partial fix." This is an unauthorized policy deviation, even when phrased as "judgment call" or "context-budget reasons."
+**Right:** Spawn fix agents for **every** confirmed finding regardless of orchestrator context state. Fix work happens in the fixer's window, not yours. The query loop auto-compacts when it needs to — trust it. If you genuinely cannot fit the spawn calls, that is a framework bug to file (not a license to ship a partial fix); emit all findings to fixers in the smallest batches possible and let the audit gate adjudicate. Severity, "diminishing returns," and your own token pressure are NOT skip authorities — only the three reasons in Key Principle #2 are.
+
 ### Mistake 8: Forgetting to Update metadata.json
 
 **Wrong:** Writing review.json but leaving metadata.json stuck at `"status": "in-progress"`.

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)
 

package/skills/apt-verify-proof/SKILL.md

@@ -89,8 +89,10 @@ For multi-model verification details:
 
 ## Config
 
-Settings in `.aperant/config.json` control behavior (run `/apt:setup` to configure):
-- `verification.evidence_capture` — capture screenshots + terminal output (default: true)
-- `verification.open_report` — open HTML in browser when done (default: true)
-- `multi_model.enabled` — run multi-model verification (default: false)
-- `multi_model.gemini.model` — Gemini preset: default/thorough/fast
+Settings live in the MERGED Aperant config (shared `.aperant/config.json` + per-device `.aperant/config.local.json`; local wins). Run `/apt:setup` to configure. Read via `apt-tools config read .` or the framework's `loadMergedProjectConfig()` — NEVER raw `JSON.parse(readFileSync('.aperant/config.json'))`, which misses per-device overrides.
+
+- `verification.evidence_capture` — shared. capture screenshots + terminal output (default: true)
+- `verification.open_report` — **per-device (config.local.json)** per AUDIT-001. open HTML in browser when done (default: true)
+- `multi_model.enabled` — shared. run multi-model verification (default: false)
+- `multi_model.cross_verification.tools` — **per-device (config.local.json)** per AUDIT-001. which CLIs to cross-verify with.
+- `multi_model.gemini.model` — shared. Gemini preset: default/thorough/fast

package/src/cli/ci-watch/stop-matrix.mjs

@@ -106,6 +106,23 @@ export function classify({ checks, state, prMetadata }) {
 		}
 	}
 
+	// 6b. BUG-031 defensive wait branch — if no checks are actually
+	// failing (everything is success / skipped / in_progress / neutral),
+	// never fall through to the default-red 'fix' at the bottom. Placed
+	// AFTER reviewer-pause so CHANGES_REQUESTED + no-failures still
+	// produces 'reviewer-pause' (locks existing semantics), BEFORE the
+	// remaining checks (identical-log, flake-skip, infra-backoff, fix)
+	// which all assume at least one failing row. Pre-fix, a PR with a
+	// success + a SKIPPED conditional CI job fell through to 'fix' and
+	// burned a fix attempt every tick on a non-existent failure.
+	if (failed.length === 0) {
+		return {
+			action: 'wait',
+			counts_toward_budget: false,
+			reason: 'no failing checks; awaiting in-flight or skipped',
+		}
+	}
+
 	// 7. Identical-log → non-converging fixer.
 	// Compare aggregate fingerprints (same format as the write side in ci-watch.mjs).
 	if (attempts > 0 && st.last_status && failed.length > 0) {

package/src/cli/commands/ci-watch.mjs

@@ -24,6 +24,7 @@
  * itself never shells out to gh.
  */
 
+import { spawnSync } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
@@ -94,7 +95,7 @@ function validatePr(pr) {
  */
 export function cmdCiWatch(subcommand, projectDir, extraArgs) {
 	if (!subcommand) {
-		return err('Usage: apt-tools ci-watch <start|stop|status|tick> <project-dir> [flags]')
+		return err('Usage: apt-tools ci-watch <start|stop|status|tick|sweep> <project-dir> [flags]')
 	}
 	if (!projectDir) {
 		return err(`Usage: apt-tools ci-watch ${subcommand} <project-dir> [flags]`)
@@ -112,9 +113,34 @@ export function cmdCiWatch(subcommand, projectDir, extraArgs) {
 			return doStatus(root, flags)
 		case 'tick':
 			return doTick(root, flags)
+		case 'sweep':
+			return err(
+				'sweep is async; call cmdCiWatchSweep directly (the apt-tools dispatcher routes it separately)',
+			)
 		default:
-			return err(`Unknown ci-watch subcommand: ${subcommand}. Expected: start, stop, status, tick`)
+			return err(
+				`Unknown ci-watch subcommand: ${subcommand}. Expected: start, stop, status, tick, sweep`,
+			)
+	}
+}
+
+/**
+ * Async sibling for the `sweep` subcommand (the rate-limited orphaned-state
+ * walker). Split out from the sync `cmdCiWatch` dispatcher so the latter's
+ * return type stays `CommandResult` (not a `CommandResult | Promise` union)
+ * and the synchronous tests + callers don't need to be wrapped in `await`.
+ *
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ * @returns {Promise<CommandResult>}
+ */
+export async function cmdCiWatchSweep(projectDir, extraArgs) {
+	if (!projectDir) {
+		return err('Usage: apt-tools ci-watch sweep <project-dir> [flags]')
 	}
+	const root = resolve(projectDir)
+	const flags = parseFlags(extraArgs)
+	return await doSweep(root, flags)
 }
 
 // ---------------------------------------------------------------------------
@@ -245,6 +271,91 @@ function doStop(root, flags) {
 	})
 }
 
+// ---------------------------------------------------------------------------
+// sweep — BUG-027 (c): manual GC for orphaned ci-watch state files.
+//
+// Enumerates all watcher state files via `listWatches(root)`, shells out
+// to `gh pr view --json state` for each one (rate-limited to ≤5/sec),
+// and removes the state files whose PR state is MERGED or CLOSED. Never
+// auto-runs on startup — opt-in manual subcommand only, per brief.
+// Honors APT_GH_FIXTURE_JSON for hermetic tests (returns the same body
+// for every PR — fine since the test fixtures we ship cover each
+// branch in isolation).
+// ---------------------------------------------------------------------------
+
+async function doSweep(root, flags) {
+	if (flags.get('orphaned') !== true) {
+		return err(
+			'ci-watch sweep currently supports only `--orphaned`. Usage: apt-tools ci-watch sweep <project-dir> --orphaned',
+		)
+	}
+	const dryRun = flags.get('dry-run') === true
+	const watches = listWatches(root)
+	const removed = []
+	const skipped = []
+	const ghFixture = process.env.APT_GH_FIXTURE_JSON
+	for (let i = 0; i < watches.length; i++) {
+		const watch = watches[i]
+		const pr = watch.pr
+		const prUrl = watch.pr_url ?? null
+		// Validate pr_url shape before passing to gh: must be an https:// URL
+		// or absent. An invalid value (e.g. a flag-injection string from a
+		// tampered state file) falls back to the integer pr number.
+		const safeUrl =
+			typeof prUrl === 'string' && /^https:\/\/.+/.test(prUrl) && !prUrl.startsWith('-')
+				? prUrl
+				: null
+		// Need a PR URL to call `gh pr view`; if absent, fall back to the
+		// integer pr arg which gh accepts for the active repo.
+		const target = safeUrl ?? String(pr)
+		let body = null
+		if (ghFixture) {
+			body = ghFixture
+		} else {
+			try {
+				const res = spawnSync('gh', ['pr', 'view', target, '--json', 'state'], {
+					cwd: root,
+					encoding: 'utf-8',
+				})
+				if (res.status === 0 && res.stdout) body = res.stdout
+			} catch {
+				/* gh transport error — skip this entry */
+			}
+		}
+		if (!body) {
+			skipped.push({ pr, reason: 'gh-unavailable' })
+			continue
+		}
+		let parsed
+		try {
+			parsed = JSON.parse(body)
+		} catch {
+			skipped.push({ pr, reason: 'malformed-gh-json' })
+			continue
+		}
+		const state = parsed?.state ?? null
+		if (state !== 'MERGED' && state !== 'CLOSED') {
+			skipped.push({ pr, reason: `pr-state-${state ?? 'unknown'}` })
+			continue
+		}
+		if (!dryRun) deleteState(root, pr)
+		removed.push({ pr, pr_state: state })
+		// Rate-limit ≤5/sec per brief — sleep 200ms between live gh calls.
+		// Use async setTimeout (non-blocking) rather than Atomics.wait.
+		if (!ghFixture && i < watches.length - 1) {
+			await new Promise((resolve) => setTimeout(resolve, 200))
+		}
+	}
+	return ok({
+		status: 'ok',
+		command: 'ci-watch-sweep',
+		dry_run: dryRun,
+		removed,
+		skipped,
+		total_watches: watches.length,
+	})
+}
+
 // ---------------------------------------------------------------------------
 // status
 // ---------------------------------------------------------------------------