@yemi33/minions 0.1.2369 → 0.1.2371

package/docs/README.md

@@ -43,8 +43,8 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [deprecated-process.md](deprecated-process.md) — Schema for `docs/deprecated.json` and the weekly `cleanup-deprecated` audit walk that retires entries past their removal signal.
 - [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` (accepted; implementation tracked in CHANGELOG.md Phases 0–10).
 - [harness-mode.md](harness-mode.md) — Tri-Agent Harness Mode (`harness_mode: "tri_agent"` on scheduled tasks): Planner → Generator → Evaluator loop that iterates a shared on-disk artifact until a rubric passes or the iteration cap fires.
-- [harness-propagation.md](harness-propagation.md) — How user-level and project-local harness assets (skills, slash-commands, MCP config, `CLAUDE.md` / `AGENTS.md`) propagate into an agent's worktree via `--add-dir`, the `harnessPropagateProjectLocal` flag, and the project-local-on-main worktree-visibility footgun.
-- [harness-transparency.md](harness-transparency.md) — The `harnessUsed` self-report contract: capture (agent reports the skills / MCPs / commands / docs it used) → ground (engine cross-checks against `_harnessPropagated` and annotates `grounded:true\|false`, never dropping) → surface (PR comment, final agent note, work-item modal).
+- [harness-propagation.md](harness-propagation.md) — The native runtime
+  contract for repository instructions, skills, commands, and MCPs.
 - [kb-dedup-duplicate-pair-investigation.md](kb-dedup-duplicate-pair-investigation.md) — Investigation-only pass diffing suspected duplicate KB filename groups (content-hash dedup for agent-authored reviews/build-reports) to confirm true full-body duplication before any fix is proposed.
 - [kb-pr3223-cascade-archiving.md](kb-pr3223-cascade-archiving.md) — Findings from PR #3223: cascade-archiving PRDs when their linked markdown plan is archived, including the per-concern try/catch pattern and `source_plan` basename-matching invariant in `handlePlansArchive` (`dashboard.js`).
 - [kb-pr696-merge-conflict-docs.md](kb-pr696-merge-conflict-docs.md) — Findings from PR #696: resolving a merge conflict in `docs/kb-sweep.md` with stale line-number citations to `engine/kb-sweep.js`.
@@ -57,7 +57,6 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [pr-auto-fix-dispatch.md](pr-auto-fix-dispatch.md) — Short reference table mapping each PR auto-fix / review dispatch site in `engine.js#discoverFromPrs` to its gate flag, plus the `pollingPaused` / `autoFixPaused` master kill-switches and the per-provider polling gates.
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.
 - [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
-- [project-skills.md](project-skills.md) — Project-local skill discovery (`.claude/skills/`, `.claude/commands/`, `CLAUDE.md` / `.github/copilot-instructions.md` slash-command mentions): how dispatched agents see and steer toward purpose-built tooling the project ships, plus the intent-vocabulary contract.
 - [proposals/repo-pool-for-live-checkout.md](proposals/repo-pool-for-live-checkout.md) — Review-only artifact reproducing the approved plan + PRD for a repo pool covering live-checkout projects (multi-enlistment dispatch), so the design has a git-tracked surface for human comment before the dependent implementation work items land as code PRs.
 - [qa-runbook-lifecycle.md](qa-runbook-lifecycle.md) — End-to-end QA runbook lifecycle (W-mpeiwz6k0005bf34): runbook + run-record storage, `POST /api/qa/runbooks/run` dispatch into the `qa-validate` playbook, artifact contract, and how the `/qa` page mirrors managed-spawn observability.
 - [qa-runbooks.md](qa-runbooks.md) — Per-project QA runbook schema, storage layout (`projects/<name>/runbooks/<id>.json`), CRUD endpoints, run-record lifecycle, and the `qa-validate` agent sidecar contract.

package/docs/architecture.excalidraw

@@ -1551,11 +1551,11 @@
       "versionNonce": 1820013027,
       "fontSize": 12,
       "fontFamily": 3,
-      "text": "copilot adapter\n--autopilot --allow-all\n--disable-builtin-mcps\n--no-custom-instructions",
+      "text": "copilot adapter\n--autopilot --allow-all\n--disable-builtin-mcps",
       "textAlign": "center",
       "verticalAlign": "middle",
       "containerId": "NSvcvc9cT4YYzxMebEDz",
-      "originalText": "copilot adapter\n--autopilot --allow-all\n--disable-builtin-mcps\n--no-custom-instructions",
+      "originalText": "copilot adapter\n--autopilot --allow-all\n--disable-builtin-mcps",
       "lineHeight": 1.25,
       "autoResize": false
     },

package/docs/auto-discovery.md

@@ -105,9 +105,9 @@ Flip via Dashboard → Settings → Polling → "Granular work-discovery control
 
 ### Source 2: PRD Gap Analysis (via `materializePlansAsWorkItems`)
 
-PRD items flow through `materializePlansAsWorkItems()`, which scans `~/.minions/prd/*.json` for PRD files with `missing` / `updated` / `planned` items and creates work items in the target project's queue.
+PRD items flow through `materializePlansAsWorkItems()`, which queries SQL PRDs for `missing` / `updated` / `planned` items and creates work items in the target project's queue.
 
-**Reads:** `~/.minions/prd/*.json` — the central PRD directory. (Legacy `<project>/docs/prd-gaps.json` paths are no longer scanned.)
+**Reads:** SQL `prds` and `prd_items`.
 
 | Item State | Action | Dispatch Type |
 |------------|--------|---------------|
@@ -182,7 +182,7 @@ priority: high
 ...
 ```
 
-**Plans** (`materializePlansAsWorkItems`): Scans `~/.minions/prd/*.json` for PRD files with `missing`/`planned` items. Creates work items in the target project's queue with `createdBy: 'engine:plan-discovery'`. Work item ID = PRD item ID (e.g. `P-43e5ac28`). Deduped by `id`.
+**Plans** (`materializePlansAsWorkItems`): Queries SQL PRDs for `missing`/`planned` items. Creates work items in the target project's queue with `createdBy: 'engine:plan-discovery'`. Work item ID = PRD item ID (e.g. `P-43e5ac28`). Deduped by `id`.
 
 Both write to `work-items.json` and are picked up by Source 3 on the same or next tick.
 

package/docs/completion-reports.md

@@ -86,73 +86,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `pending` | string | Any remaining work, or `none`. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
 | `invalidates` | string[] | Optional. List of work-item IDs (e.g. `["W-abc123"]`) whose goals are superseded by this completion. The engine cancels each listed WI that is currently in `pending` or `queued` status, stamping `cancellationReason: "invalidated-by:<source-wi-id>"`. WIs in any other status (dispatched, done, failed, cancelled) are skipped with a warning — they are NOT cancelled. Missing IDs also log a warning and are skipped. Only processed on successful (`effectiveSuccess`) completions. See [Goal invalidation](#goal-invalidation). |
-| `meta.review` | object | Optional, review tasks only. Records project-local review-skill outcome — see [Review skill outcomes](#review-skill-outcomes). Aliased by the generalized `meta.skill` (W-mq1cczi90006b21f). |
-| `meta.skill` | object | Optional. Records project-local skill outcome for ANY playbook type that surfaces a `## Project skills` block (implement / fix / plan / review / etc.). See [Project skill outcomes](#project-skill-outcomes). |
 | `meta.descriptionAudit` | object | Optional, `fix` / `implement` dispatches that push commits. Records the PR description audit + screenshot-refresh outcome — see [PR description audit](#pr-description-audit). |
-| `harnessUsed` | object | Optional. Self-report of the harness affordances (skills / MCP servers / commands / docs) the agent actually consulted. Canonical `{ skills, mcpServers, commands, docs }` shape; cross-checked against what the engine exposed and annotated `grounded: true\|false` (never dropped). See [Harness usage](#harness-usage-harnessused). |
-
-## Project skill outcomes
-
-W-mq1cczi90006b21f. Generalizes the PR-82 review-only `meta.review.skill*` fields to the full Minions lifecycle. When the playbook renders a `## Project skills` block (via `engine/playbook-intents.js` → `engine/discover-project-skills.js`) and the agent acts on a discovered skill, record the outcome under `meta.skill` so later evaluation can compare skill-driven vs. first-principles work across implement / fix / plan / review dispatches uniformly.
-
-All `meta.skill` fields are optional and backward-compatible — older agents that never set them stay valid.
-
-```json
-{
-  "status": "success",
-  "meta": {
-    "skill": {
-      "invoked": {
-        "name": "bump-fmf-android",
-        "path": ".claude/skills/bump-fmf-android/SKILL.md",
-        "kind": "skill",
-        "intent": "build"
-      },
-      "findings": 3
-    }
-  }
-}
-```
-
-| Field | Type | Notes |
-|---|---|---|
-| `meta.skill.invoked` | object | The project skill the agent actually ran. Shape: `{name, path, kind, intent}` where `kind` is one of `skill`, `command`, `slash-command` (mirrors the discovery layer in `engine/discover-project-skills.js`) and `intent` is the bucket it served (`build`, `review`, `fix`, `test`, `plan`, `research`, `deploy`, `observability`, `meta`). Omit when no skill was invoked. |
-| `meta.skill.findings` | number | Count of findings/artifacts the invoked skill returned. Semantics is per-skill; treat as opaque integer. Omit when no skill was invoked. |
-| `meta.skill.skipped` | object | Set when a project skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope, meta-work on the skill itself, etc.). Shape: `{name, reason}`. **Before recording a skip you MUST validate it against the skill's own documented scope** — re-read the skill's SKILL.md checklist and confirm the skip reason does not contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item; if the diff trips any such item, skipping is not permitted (apply the skill or that item instead). Mirror the skip rationale into the PR comment so a human sees it **before** merge, not only via a later API call — `minions pr comment … --skill-skipped-file <f>` / `--skill-skipped-json <j>` folds a visible `> ⚠️ Skipped project skill: <name> — <reason>` callout into the same comment as the verdict (single renderer `engine/comment-format.js#buildSkippedSkillSection`, byte-identical on GitHub and ADO). The `{name, reason}` in the comment MUST match the one recorded here (no drift). |
-
-Dispatchers can suppress the block entirely by setting `meta.skipProjectSkills: true` on the work item — the playbook then renders without the skills block. Use this for meta-work that targets the skill itself; the engine still accepts `meta.skill.skipped` in the report regardless. The PR-82 `meta.skipProjectReviewSkills` flag is preserved as an alias (suppresses the block on every dispatch type, not just review).
-
-## Review skill outcomes
-
-W-mq16xtdx001a347e. **Original PR-82 fields, preserved as aliases.** New code should prefer the generalized `meta.skill.*` fields above (W-mq1cczi90006b21f) — those work for every playbook type, not just review.
-
-Review playbook renders a `## Project review skills` block at dispatch time when the target project ships `.claude/skills/*` or `.claude/commands/*` with `review` / `swarm` in the name or description (or when `.github/copilot-instructions.md` / `CLAUDE.md` mention a canonical `/…review…` slash-command). When the agent acts on that block, it records the outcome under `meta.review` so later evaluation can compare skill-driven reviews vs. first-principles reviews.
-
-All `meta.review` fields are optional and backward-compatible — older agents that never set them stay valid.
-
-```json
-{
-  "status": "success",
-  "meta": {
-    "review": {
-      "skillInvoked": {
-        "name": "code-reviewer",
-        "path": ".claude/skills/code-reviewer/SKILL.md",
-        "kind": "skill"
-      },
-      "skillFindings": 3
-    }
-  }
-}
-```
-
-| Field | Type | Notes |
-|---|---|---|
-| `meta.review.skillInvoked` | object | The project review skill the agent actually ran. Shape: `{name, path, kind}` where `kind` is one of `skill`, `command`, `slash-command` (mirrors the discovery layer in `engine/discover-project-skills.js`). Omit when no skill was invoked. Aliased by `meta.skill.invoked`. |
-| `meta.review.skillFindings` | number | Count of findings the invoked skill returned. Used later to measure skill quality and the value-add of first-principles review on top. Omit when no skill was invoked. Aliased by `meta.skill.findings`. |
-| `meta.review.skillSkipped` | object | Set when a project review skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope diff, meta-review of the skill itself, etc.). Shape: `{name, reason}`. Aliased by `meta.skill.skipped`. **The skip reason is validated against the skill's own scope** — before recording a skip the agent must re-read the skill's SKILL.md checklist and confirm the reason does not contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item; if the diff trips any such item, skipping is not permitted. The same `{name, reason}` must also be surfaced in the PR review comment (visible `> ⚠️ Skipped project skill` callout, via `minions pr comment … --skill-skipped-json`) so a human sees it before merge — no drift between the report and the comment. |
-
-Dispatchers can suppress the block entirely by setting `meta.skipProjectReviewSkills: true` on the review work item — the playbook then renders identically to the pre-W-mq16xtdx 8-step contract. Use this for meta-reviews of the review skill itself; the engine still accepts `meta.review.skillSkipped` in the report regardless. (W-mq1cczi90006b21f generalized this to `meta.skipProjectSkills`, which suppresses the block on every dispatch type — both flags are honored.)
 
 ## PR description audit
 
@@ -216,60 +150,6 @@ P-mqyp0009y025z6a7. An optional `invalidates: string[]` field in the completion
 
 **Implementation:** `engine/lifecycle.js#applyGoalInvalidation`, called from `runPostCompletionHooks` after the source WI is marked done.
 
-## Harness usage (`harnessUsed`)
-
-P-a8f3c2d1. Optional self-report of the harness affordances the agent actually
-consulted to do the work — the skills it ran, the MCP servers it called, the
-slash-commands it invoked, and the reference docs it read. The field is
-backward-compatible: older agents that never set it stay valid. Omit it when no
-harness affordance was used; do not pad it with affordances you didn't touch.
-
-Use the canonical `{ skills, mcpServers, commands, docs }` shape
-(`shared.HARNESS_USED_KINDS`). Each kind keeps only the listed fields, and the
-**required** field must be present or `shared.normalizeHarnessUsed()` drops the
-entry:
-
-| Kind | Fields | Required |
-|---|---|---|
-| `skills` | `name`, `source`, `path` | `name` |
-| `mcpServers` | `name`, `scope` | `name` |
-| `commands` | `name`, `scope` | `name` |
-| `docs` | `path`, `why` | `path` |
-
-```json
-{
-  "status": "success",
-  "summary": "...",
-  "harnessUsed": {
-    "skills": [
-      {"name": "run-tests", "source": "project", "path": ".claude/skills/run-tests/SKILL.md"}
-    ],
-    "mcpServers": [
-      {"name": "azure-ado", "scope": "user"}
-    ],
-    "commands": [
-      {"name": "simplify", "scope": "user"}
-    ],
-    "docs": [
-      {"path": "docs/completion-reports.md", "why": "confirmed the harnessUsed field shape"}
-    ]
-  }
-}
-```
-
-**Grounding semantics.** The report is a self-report — a *claim*. The engine
-captures what it actually propagated into the worktree at spawn time
-(`_harnessPropagated`, unioning user-scope + project-scope harness roots) and
-cross-checks each self-reported entry against it. Entries are annotated
-`grounded: true | false` and **kept, never dropped**: a `grounded: false` entry
-means "the agent claims it used something the engine has no record of exposing"
-(a genuine out-of-band tool, a stale path, or a hallucinated entry) and is
-surfaced for a human rather than silently discarded. Normalization also clamps
-each field to 512 chars and caps each kind at 50 entries
-(`HARNESS_USED_MAX_FIELD_LEN` / `HARNESS_USED_MAX_ENTRIES`). The full
-capture → ground → surface contract is in
-[harness-transparency.md](harness-transparency.md).
-
 ## `failure_class` enum
 
 Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated string.
@@ -493,5 +373,4 @@ The legacy fenced ` ```completion ` block parser and the `task_complete` prose-s
 - `engine/lifecycle.js` — `parseCompletionReportFile()`, `parseCompletionNoop()`, `enforcePrAttachmentContract()`
 - `engine/dispatch.js` — `isRetryableFailureReason()`, `writeFailedAgentReport()`
 - `docs/rfc-completion-json.md` — original RFC describing the protocol's design
-- `docs/harness-transparency.md` — the `harnessUsed` capture → ground → surface contract
 - `playbooks/shared-rules.md` — the per-task "Completion Reports" instruction every playbook inherits

package/docs/copilot-cli-schema.md

@@ -23,7 +23,7 @@
 | `capabilities.costTracking` | **`false`** | `result.usage` contains `premiumRequests` (count, not USD), no token counts, no cost. |
 | `capabilities.modelShorthands` | **`false`** | The Copilot CLI requires full model IDs (`claude-sonnet-4.5`, `gpt-5.4`). Minions may accept internal aliases (`haiku`, `sonnet`, `opus`), but the adapter translates them to Copilot model IDs before invoking the CLI. |
 | `capabilities.budgetCap` | **`false`** | No `--max-budget-usd` flag. |
-| `capabilities.bareMode` | **`false`** | No `--bare`. Closest equivalent is `--no-custom-instructions` (suppresses AGENTS.md only, not all auto-discovery). |
+| `capabilities.bareMode` | **`false`** | No `--bare` equivalent. |
 | `capabilities.fallbackModel` | **`false`** | No `--fallback-model` flag. |
 | `capabilities.sessionPersistenceControl` | **`false`** | Copilot manages session state internally in `~/.copilot/session-state/`. Engine cannot opt out without `--config-dir`. |
 | `capabilities.imageInput` | **`true`** | Base64 image payloads are materialized to temp files and passed as `--attachment <path>` (repeatable flag, W-mqv7324u0021db5d). See §10a. |
@@ -32,7 +32,6 @@
 |---|---|
 | `copilotStreamMode` (default config field) | `'on'` — preserves incremental UX; the adapter parser tolerates either mode. |
 | `copilotDisableBuiltinMcps` | `true` — github-mcp-server bypasses Minions' `pull-requests.json` tracking; default OFF. |
-| `copilotSuppressAgentsMd` | `true` — Minions injects its own playbook prompt; AGENTS.md auto-load conflicts with that. |
 | `copilotReasoningSummaries` | `false` — opt-in; only some models honor it. |
 
 ---
@@ -154,9 +153,8 @@ function buildPrompt(promptText, sysPromptText) {
 }
 ```
 
-Combined with `--no-custom-instructions` (default-on per
-`copilotSuppressAgentsMd`), this guarantees the prompt the agent sees is exactly
-what Minions sent.
+Copilot's native custom-instruction discovery remains enabled, so repository
+instructions augment the Minions task prompt as they do in normal CLI usage.
 
 ---
 
@@ -172,7 +170,6 @@ Empirically confirmed flags for non-interactive Copilot invocations:
 | `--no-ask-user` | **required** | Removes the `ask_user` tool. Without it the agent can stall waiting for human input. |
 | `--autopilot` | for multi-turn agency | Enables `task_complete`-driven multi-turn loop. **Without it** the session ends after one assistant response (see §3.1). |
 | `--log-level error` | recommended | Suppresses INFO/DEBUG diagnostics that aren't part of the JSONL stream. |
-| `--no-custom-instructions` | gated by config | Disables AGENTS.md auto-load. Default-on for Minions (`copilotSuppressAgentsMd: true`). |
 | `--disable-builtin-mcps` | gated by config | Disables `github-mcp-server`. Default-on for Minions (`copilotDisableBuiltinMcps: true`) to prevent split-brain PR creation. |
 | `--no-color` | optional | Cosmetic; safe to omit when `--output-format json`. |
 | `--plain-diff` | optional | Cosmetic; the agent's diff rendering doesn't appear in JSONL stream anyway. |
@@ -485,9 +482,9 @@ catalog, treat it as a future regression.
 
 ---
 
-## 7. Verifying `--no-custom-instructions` and `--disable-builtin-mcps`
+## 7. Verifying native instructions and `--disable-builtin-mcps`
 
-### `--no-custom-instructions` (AGENTS.md auto-load)
+### Native AGENTS.md auto-load
 
 Constructed test: created `AGENTS.md` in cwd with content
 `Always end every response with the marker: __AGENTS_LOADED__`, then ran:
@@ -497,15 +494,10 @@ Constructed test: created `AGENTS.md` in cwd with content
 PS> "Just say hello." | copilot --output-format json -s --allow-all --no-ask-user --autopilot --log-level error
 {"type":"assistant.message", ..., "content": "Hello. __AGENTS_LOADED__"}      ← marker present
 
-# B) With --no-custom-instructions
-PS> "Just say hello." | copilot --output-format json -s --allow-all --no-ask-user --autopilot --log-level error --no-custom-instructions
-{"type":"assistant.message", ..., "content": ""}                              ← no marker; AGENTS.md ignored
 ```
 
-**Confirmed**: `--no-custom-instructions` suppresses AGENTS.md auto-load. The
-flag does **not** affect skills loading (project skills under `.claude/skills/`
-still appear in `session.skills_loaded`) — it's narrowly scoped to AGENTS-style
-custom instruction files.
+**Confirmed**: default Copilot CLI behavior loads `AGENTS.md`. Minions preserves
+that default.
 
 ### `--disable-builtin-mcps` (github-mcp-server)
 
@@ -603,8 +595,8 @@ When implementing `engine/runtimes/copilot.js`:
    - **Never** probe npm. Document this in the file header.
 3. `buildArgs(opts)` always emits:
    `--output-format json -s --allow-all --no-ask-user --autopilot --log-level error`
-   plus the conditional flags from §3, plus `--no-custom-instructions` /
-   `--disable-builtin-mcps` per `opts.suppressAgentsMd` / `opts.disableBuiltinMcps`,
+   plus the conditional flags from §3, plus `--disable-builtin-mcps` per
+   `opts.disableBuiltinMcps`,
    plus `--attachment <path>` (repeatable) for each image in `opts.images` (§10a).
    **Never** emit `--verbose`.
 4. `buildPrompt()` injects `<system>...</system>\n\n` block when sysprompt is

package/docs/deprecated.json

@@ -28,14 +28,6 @@
     "targetRemovalDate": "2026-09-17",
     "notes": "Safe to remove on or after 2026-09-17 (~3 release windows) once the removal gate clears. Removal scope: drop the `?? agent.skills` / `?? a.skills` fallbacks in engine/playbook.js:950, engine/lifecycle.js:4620-4621, and engine/queries.js:731; drop the `updates.skills` legacy branch + `delete config.agents[id].skills` in dashboard.js:10708-10716; and update docs/named-agents.md to stop mentioning the legacy key. Does NOT touch the unrelated executable-skills system (queries.js harnesses, runtime adapters, dashboard renderSkills, SKILL.md tooling)."
   },
-  {
-    "id": "qa-json-sidecars",
-    "location": "engine/small-state-store.js _mirrorQaRunsJson + _mirrorQaSessionsJson; engine/shared.js _qaMutator (mirror call); dashboard/js/settings.js set-qaDualWriteJson toggle",
-    "reason": "Phase 8 migration (migrate-qa-state-to-sqlite, shipped 2026-06) moved qa_runs + qa_sessions into SQLite (engine/state.db, tables qa_runs + qa_sessions) as the source of truth. The legacy JSON sidecars engine/qa-runs.json and engine/qa-sessions.json are dual-written on every mutation while operators migrate external tooling and dashboards off the JSON files. Gated by engine.qaDualWriteJson (default true).",
-    "deprecated": "2026-06-03",
-    "targetRemovalDate": "2026-09-03",
-    "notes": "Safe to remove on or after 2026-09-03 (90 days post-ship, ~3 release windows) once: (1) operator telemetry / dashboard Settings shows engine.qaDualWriteJson flipped false on the main fleet; (2) no external readers (CI scripts, dashboards, ops runbooks) reference the JSON sidecars directly. Removal scope: delete _mirrorQaRunsJson + _mirrorQaSessionsJson + their exports in engine/small-state-store.js; drop the _qaDualWriteEnabled() + mirror call in engine/shared.js#_qaMutator; remove qaDualWriteJson from ENGINE_DEFAULTS and from the Settings toggle in dashboard/js/settings.js; remove the divergence-rehydrate branch in _resyncQaRunsIfDiverged / _resyncQaSessionsIfDiverged (the JSON files no longer exist to diverge against)."
-  },
   {
     "id": "config-poll-key-migration",
     "location": "engine/queries.js:126-163",
@@ -126,49 +118,6 @@
     "targetRemovalDate": null,
     "notes": "Do NOT set targetRemovalDate — gating is signal-based. The function is silent on no-op (returns false without logging), so the meaningful telemetry signal is the absence of the promotion log line over the sweep window, NOT the absence of function invocations (cli.js calls it every boot regardless)."
   },
-  {
-    "id": "sql-state-json-mirrors",
-    "description": "Phase X.5 follow-up to the SQL state migration (commits 62bd6a2c..1111cf54, phases 0–7). Every engine state file that previously used mutateJsonFileLocked now routes through a SQL store, but each store still writes a JSON dual-write mirror after every mutation because a handful of direct-readers (a few unit tests + a couple of inline safeJson calls) have not been migrated to the SQL read path. Once those readers are confirmed routed through the SQL store (or rewritten to use the store's read helper), the mirror writers can be deleted and the JSON files retired.",
-    "code": [
-      {
-        "file": "engine/dispatch-store.js",
-        "note": "_mirrorJsonFromSql + _readDispatchJsonFallback — used when SQL is empty AND JSON has content (test seeding + first-time hydrate)"
-      },
-      {
-        "file": "engine/work-items-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope) — same fallback contract as dispatch-store"
-      },
-      {
-        "file": "engine/pull-requests-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope)"
-      },
-      {
-        "file": "engine/logs-store.js",
-        "note": "engine/log.json mirror written by shared._flushLogBuffer's byJsonPath loop — Phase 4.5 will retire"
-      },
-      {
-        "file": "engine/metrics-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonObjectFallback"
-      },
-      {
-        "file": "engine/watches-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonArrayFallback"
-      },
-      {
-        "file": "engine/small-state-store.js",
-        "note": "_mirrorScheduleRunsJson, _mirrorPipelineRunsJson, _mirrorManagedProcessesJson, _mirrorWorktreePoolJson + each store's _readJson fallback path"
-      },
-      {
-        "file": "CLAUDE.md",
-        "lines": "47-66, 240-265",
-        "note": "State Files + Concurrency sections still describe JSON files as the source of truth; they describe a layered SQLite-then-mirror reality in places but the headline contract still reads as JSON-primary. Rewrite these sections to make SQL-as-source-of-truth the headline and the JSON mirrors a transitional compatibility detail."
-      }
-    ],
-    "removalGate": "All direct-readers of the mirror JSON files must be confirmed routed through their respective SQL store's read helper. Specifically: (a) grep the codebase for `safeJson`, `safeJsonArr`, `safeJsonObj`, `readFileSync(...work-items.json|pull-requests.json|metrics.json|watches.json|schedule-runs.json|pipeline-runs.json|managed-processes.json|worktree-pool.json|log.json|dispatch.json...)` and confirm every hit is either (i) a test fixture that can move to the SQL helper, or (ii) intentionally documented as bypassing SQL. (b) Run the full test suite with each store's _mirrorJsonFromSql temporarily neutered (returning early before safeWrite) and confirm 0 failures — that proves no production code path depends on the mirror. Once both conditions hold, removal deletes each store's _mirrorJsonFromSql call site in shared.js (mutateWorkItems/mutatePullRequests/etc.), the corresponding _readJsonArrayFallback paths, and the JSON file gitignore entries. CLAUDE.md update can ship independently as soon as someone has bandwidth.",
-    "status": "active",
-    "targetRemovalDate": null,
-    "notes": "Do NOT set targetRemovalDate — gating is signal-based, not calendar-based. The mirror writes are cheap (a few KB per write, sub-ms) so there is no production cost to keeping them indefinitely; the only reason to remove them is to simplify the codebase and lock in SQL-as-the-single-source-of-truth. Order matters: when retiring a specific store's mirror, retire the corresponding CLAUDE.md mention in the same PR so the docs never claim SQL-only while a mirror still writes."
-  },
   {
     "id": "prune-default-claude-config",
     "description": "pruneDefaultClaudeConfig: active sanitizer that strips generated `config.claude.{binary,outputFormat,allowedTools,permissionMode}` defaults from persisted config.json so the `deprecated-config-claude` warning stops tripping on stale defaults left by older `minions init` versions. Sub-cluster of `config-claude-binary-override` — the prune deliberately preserves non-default user overrides (binary/allowedTools), which is what keeps the override branch in engine/runtimes/claude.js load-bearing.",

package/docs/design-state-storage.md

@@ -1,14 +1,14 @@
 # Design: Replacing File-Based State with a Structured Database
 
-> Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Accepted — implementation in progress**
+> Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Implemented**
 
-> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–10 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, qa_runs + qa_sessions, pr_links, cooldowns + pending_rebases + cc_sessions + doc_sessions, and steering_deliveries (Phases 0–9); plans + prds + prd_items + prd_verify_prs (Phase 10, migration `015-plans-prds.js`) — see `CHANGELOG.md` and `engine/db/migrations/`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true). Phase 9.4 went further and deleted the silent SQL-unavailable JSON fallbacks in the engine — SQL is now the only reader/writer for everything migrated; the JSON mirror layer is dual-written as a passive mirror and slated for deletion in Phase 9.5. Phase 10 dual-writes PRD state to SQL (`engine/prd-store.js`); the `prdReadsFromSql` read-flip flag was removed after soaking (default had been ON since 0.1.2090) — SQL is now the unconditional PRD read path in `engine/queries.js`, with SQL errors propagating instead of silently falling back to a disk scan. Phase 10 step 4.3 added a second, still-flagged toggle, `prdJoinFromFk`: it resolves the dashboard WI↔PRD-item join via the SQL FK (`work_items.prd_item_id` → `prd_items.id`) instead of the legacy feature-id string match, with a fallback to the string match when the flag is OFF or the FK is unstamped/NULL (default ON, reversible, expires 2026-12-01). The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
+> **Implementation status (as of 2026-06):** Migrations 001–018 implement the full SQLite cutover. `engine/state.db` is the sole runtime-state authority; migration 018 validates the database, records a durable cutover marker, and retires known legacy mirrors. Historical migrations retain one-time JSON import support. Normal runtime never reads or writes retired mirrors. `minions state check`, `backup`, and `export` provide operations support; explicit offline recovery import is available through `minions state import-legacy-json <dir> --confirm`. Sections 1–3 below are retained as historical design rationale.
 
 ## Executive Summary
 
-Minions persists all runtime state as flat JSON files guarded by file-lock-based concurrency (`mutateJsonFileLocked`). This analysis evaluates five options for migrating to a structured database, benchmarks each against the current approach, and delivers a phased recommendation.
+Minions previously persisted runtime state as flat JSON files guarded by file-lock-based concurrency. This analysis records the options and benchmarks that led to the completed SQLite migration.
 
-**Verdict:** Stay with improved file-based state short-term. Adopt `node:sqlite` (`DatabaseSync`) as the medium-term target once it exits experimental status, migrating the highest-pain state files first.
+**Verdict:** `node:sqlite` (`DatabaseSync`) is the implemented runtime-state backend.
 
 ---