@yemi33/minions 0.1.2379 → 0.1.2381

package/docs/architecture-review-2026-07-09.md

@@ -61,10 +61,8 @@ cancellation.
 
 These require separate focused changes rather than expanding this PR:
 
-1. **Dispatch SQL/JSON empty-state resurrection (high).** A process that has not
-   written SQL can still adopt stale `dispatch.json` when the SQL table is empty.
-   The durable fix is a mirror-generation/hash marker or removal of the legacy
-   fallback, not moving filesystem writes inside a SQLite transaction.
+1. **Dispatch empty-state resurrection (resolved).** The SQL-only cutover removed
+   the legacy fallback; an empty dispatch table now stays empty.
 2. **Pipeline task terminal-state model (high).** Task stages use a boolean
    completion check and promote failed work items to a completed pipeline stage;
    cancelled/review-blocked work can wedge indefinitely. Replace the boolean

package/docs/auto-discovery.md

@@ -46,11 +46,11 @@ tick()
 
 `discoverWork()` iterates every project in `config.projects[]` and runs four core discovery sources: pull requests, per-project work items, central work items, and pipeline/scheduled tasks. Results are prioritized: fixes > reviews > implements > work-items.
 
-Before scanning, the engine materializes plans and specs into project work items (side-effect writes to `work-items.json`), so they're picked up by the work items source below.
+Before scanning, the engine materializes plans and specs into project-scoped SQL work items, so they're picked up by the work-items source below.
 
 ### Source 1: Pull Requests (`discoverFromPrs`)
 
-**Reads:** `~/.minions/projects/<project>/pull-requests.json`
+**Reads:** project-scoped `pull_requests` rows in `engine/state.db`
 
 | PR State | Action | Dispatch Type |
 |----------|--------|---------------|
@@ -92,8 +92,8 @@ Flip via Dashboard → Settings → Polling → "Granular per-poller controls" c
 | Flag | Default | Phase inside `discoverWork()` |
 |------|---------|--------------------------------|
 | `prDiscoveryEnabled` | `true` | Per-project `discoverFromPrs(config, project)` — PR-derived fix / review / build-test work |
-| `workItemsDiscoveryEnabled` | `true` | Per-project `discoverFromWorkItems(config, project)` — project-local `work-items.json` scan |
-| `centralWorkDiscoveryEnabled` | `true` | `discoverCentralWorkItems(config)` — top-level project-agnostic `work-items.json` scan |
+| `workItemsDiscoveryEnabled` | `true` | Per-project `discoverFromWorkItems(config, project)` — project SQL scope |
+| `centralWorkDiscoveryEnabled` | `true` | `discoverCentralWorkItems(config)` — central SQL scope |
 | `scheduledWorkDiscoveryEnabled` | `true` | `discoverScheduledWork(config)` — cron-style scheduled tasks + scheduled meetings |
 | `planMaterializationEnabled` | `true` | `reconcilePrdStatuses(config)` + `materializePlansAsWorkItems(config)` (paired side-effect passes) |
 
@@ -116,7 +116,7 @@ PRD items flow through `materializePlansAsWorkItems()`, which queries SQL PRDs f
 
 ### Source 3: Per-Project Work Items (`discoverFromWorkItems`)
 
-**Reads:** `~/.minions/projects/<project>/work-items.json`
+**Reads:** the project's `work_items` SQL scope
 
 | Item State | Action | Dispatch Type |
 |------------|--------|---------------|
@@ -126,7 +126,7 @@ After dispatching, the engine writes `status: "dispatched"` back to the item. Th
 
 ### Source 4: Central Work Items (`discoverCentralWorkItems`)
 
-**Reads:** `~/.minions/work-items.json` (central, project-agnostic)
+**Reads:** the central `work_items` SQL scope
 
 These are tasks where the agent decides which project to work in. The engine builds a prompt that includes a list of all linked projects with their paths and repo config. The agent then navigates to the appropriate project directory based on the task.
 
@@ -163,7 +163,7 @@ This means a single work item like "Add telemetry to the document creation pipel
 **Adding central work items:**
 - Dashboard Command Center → type your intent (no `#project` = central queue)
 - CLI: `node engine.js work "task title"` (defaults to central queue)
-- Direct edit: `~/.minions/work-items.json`
+- API: `POST /api/work-items` with no project
 
 ### Materialization: Specs and Plans → Work Items
 
@@ -184,11 +184,11 @@ priority: high
 
 **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.
+Both write to the SQL work-item store and are picked up by Source 3 on the same or next tick.
 
 ## PR Status Polling (`pollPrStatus`)
 
-**Runs:** On a wall-clock cadence derived from `prPollStatusEvery × engine.tickInterval` (default 72 × 10s, ≈ 12 minutes), independently of work discovery or file-change wakeups. ADO polling lives in `engine/ado.js`; GitHub polling lives in `engine/github.js` — both run in parallel each cycle (`Promise.allSettled`) and write to the same per-project `pull-requests.json` schema. Replaces the retired agent-based `pr-sync`.
+**Runs:** On a wall-clock cadence derived from `prPollStatusEvery × engine.tickInterval` (default 72 × 10s, ≈ 12 minutes), independently of work discovery. ADO polling lives in `engine/ado.js`; GitHub polling lives in `engine/github.js` — both run in parallel each cycle (`Promise.allSettled`) and write the shared SQL PR schema. Replaces the retired agent-based `pr-sync`.
 
 The engine directly polls the host REST API for **all** PR metadata: build/CI status, human review votes, and completion state. Two API calls per PR — no agent dispatch needed.
 
@@ -196,7 +196,7 @@ The engine directly polls the host REST API for **all** PR metadata: build/CI st
 1. `GET pullrequests/{id}` → `status` (active/completed/abandoned), `mergeStatus`, `reviewers[].vote`
 2. `GET pullrequests/{id}/statuses` → CI pipeline results
 
-**Fields updated in `pull-requests.json`:**
+**Fields updated in the PR store:**
 
 | Field | Source | Values |
 |-------|--------|--------|
@@ -259,7 +259,7 @@ Resolution order:
 
 ## Dispatch Queue
 
-Discovered items land in `engine/dispatch.json`:
+Discovered items land in the SQL dispatch store, exposed as:
 
 ```json
 {
@@ -330,8 +330,8 @@ claude -p --system-prompt-file <sysprompt-file> \
 - CLAUDECODE env vars stripped to allow nested sessions
 
 ### 6. Track State
-- Agent status derived from dispatch queue (`engine/dispatch.json`)
-- Dispatch item → moved from `pending` to `active` in `dispatch.json`
+- Agent status derived from SQL dispatch state
+- Dispatch item → moved from `pending` to `active` transactionally
 - Process tracked in `activeProcesses` Map for timeout monitoring
 
 ## Post-Completion
@@ -347,10 +347,10 @@ proc.on('close')
   │
   ├─ Move dispatch item: active → completed
   │
-  ├─ Sync PRs from output (scan for PR URLs → pull-requests.json)
+  ├─ Sync PRs from output (scan for PR URLs → SQL PR store)
   │
   ├─ Post-completion hooks:
-  │    review     → update PR minionsReview in pull-requests.json, vote on ADO
+  │    review     → update PR minionsReview in SQL, vote on ADO
   │    fix        → set PR minionsReview back to "waiting"
   │    build-test → record verification result and findings
   │
@@ -386,39 +386,26 @@ Work type is auto-detected from keywords (fix, explore, test, review → impleme
                               │
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
-             work-items   notes/       plans/
-             .json        inbox/*.md   *.md
-
-Per-project sources:              Central engine:              Agents:
-
-work-items.json ──┐
-pull-requests.json┤  discoverWork()   dispatch.json
-docs/**/*.md (specs)┤  (each tick)      ┌──────────┐
-                  │       │           │ pending   │
-~/.minions/         │       │           │ active    │
-  work-items.json ┤       │           │ completed │
-  prd/*.json ─────┤       │           └─────┬────┘
-  plans/*.md ─────┘       ▼                 │
-                     addToDispatch()────────┘
-                                            │
-ADO + GitHub REST ── pollPrStatus() ──► pull-requests.json
-(every ~12min)       (buildStatus field)      │
-                                       spawnAgent()
-                                            │
-                               ┌────────────┼────────────┐
-                               ▼            ▼            ▼
-                          worktree     claude CLI    dispatch.json
-                          (in project   (max 100      (active/completed)
-                           repo dir)     turns)
-                                            │
-                                        on exit:
-                                            │
-                        ┌───────────┬───────┼───────┬──────────┐
-                        ▼           ▼       ▼       ▼          ▼
-                    output.log  notes/  PRs    work-items  localhost
-                    (per agent) inbox/*.md  .json  .json       (if webapp,
-                                    │                         from build
-                          consolidateInbox()                  & test)
+             SQL work     notes/       plans/
+             items        inbox/*.md   *.md
+
+Project-scoped SQL ──┐
+Central SQL scope ───┤  discoverWork() ──► SQL dispatch rows
+docs/**/*.md (specs) ┤       │                    │
+SQL PRDs ────────────┘       ▼                    ▼
+                       addToDispatch()        spawnAgent()
+                                                   │
+ADO + GitHub REST ── pollPrStatus() ──► SQL PR rows│
+                                                   ▼
+                                      worktree + runtime CLI
+                                                   │
+                                               on exit:
+                                                   │
+                        ┌───────────┬───────────────┼──────────┐
+                        ▼           ▼               ▼          ▼
+                    output.log  notes/inbox     SQL state   localhost
+                                    │                       (if webapp)
+                          consolidateInbox()
                           (at 5+ files)
                                     │
                                     ▼
@@ -451,7 +438,7 @@ Lack of stdout/stderr is not treated as a hang while the engine still has a live
 | Pull requests | 30 minutes | After dispatching a review, won't re-queue for 30min |
 | Work items | 0 (immediate) | No cooldown, but item status changes to "dispatched" |
 
-Cooldowns are persisted to `engine/cooldowns.json` and reloaded on engine startup. Entries older than 24 hours are pruned. `isAlreadyDispatched()` still provides an additional guard by checking pending/active and recently completed dispatches in `dispatch.json`.
+Cooldowns are persisted in SQLite and reloaded on engine startup. Entries older than 24 hours are pruned. `isAlreadyDispatched()` also checks pending, active, and recently completed SQL dispatch rows.
 
 ## Configuration Reference
 

package/docs/blog-first-successful-dispatch.md

@@ -79,7 +79,7 @@ New approach: rely on the tracked process while the engine has a live process ha
 
 ### Engine Restart Orphan Problem
 
-When the engine restarts, the in-memory `activeProcesses` Map is lost. Active dispatch items stay in `dispatch.json` but the engine has no process handle. Old stale detection (6h threshold) was too slow to catch this. Stale-orphan detection uses recent `live-output.log` activity and catches abandoned dispatches after the restart grace window.
+When the engine restarts, the in-memory `activeProcesses` Map is lost. Active dispatch rows stay in SQLite but the engine has no process handle. Old stale detection (6h threshold) was too slow to catch this. Stale-orphan detection uses recent `live-output.log` activity and catches abandoned dispatches after the restart grace window.
 
 ## The Successful Run
 

package/docs/branch-derivation.md

@@ -64,7 +64,7 @@ number namespace, and ADO work items share theirs. Before this guard, a
 `type: "fix"` WI titled `Fix github:owner/repo#244: …` where **#244 is an
 issue** got `targetPr` / `pr_id` / `prNumber` stamped by
 `dashboard.js#copyWorkItemPrFields`, which then (a) minted a phantom
-`pull-requests.json` record (`agent: 'human'`, went abandoned, polluted the PR
+PR-store record (`agent: 'human'`, went abandoned, polluted the PR
 count) via `shared.autoEnrollPrFromFixWorkItem`, and (b) routed the dispatch
 through the PR-fix path (`targetPr`/`pr_id`/`prNumber`) instead of
 implement-and-open-a-fresh-PR.
@@ -76,7 +76,7 @@ stamping:
    / `meta.pr_followup.parent_pr_url` are explicit operator intent and stamp
    with **no** network call.
 2. **Loose (description/title-scanned) refs on a fix WI** are confirmed via:
-   - an already-tracked `pull-requests.json` record for the ref (cheap, no
+   - an already-tracked SQL PR record for the ref (cheap, no
      network), else
    - a host existence check — `engine/github.js#prExists` (`gh api
      repos/:owner/:repo/pulls/NNN`; 404 ⇒ issue) or `engine/ado.js#prExists`

package/docs/command-center.md

@@ -2,7 +2,7 @@
 
 The Command Center (CC) is the dashboard's conversational chat panel. It opens from the **CC** button in the top-right header and lets you drive the engine — dispatching work items, saving notes, approving plans, and asking questions about Minions state — through a persistent session on the configured CC runtime.
 
-CC is intentionally a thin wrapper around the runtime CLI: state changes happen via tool-driven calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → runtime session persisted in `engine/state.db` (`cc_sessions`; `engine/cc-sessions.json` is a passive mirror). Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
+CC is intentionally a thin wrapper around the runtime CLI: state changes happen via tool-driven calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → runtime session persisted in `engine/state.db` (`cc_sessions`). Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
 
 For canonical detail (system prompt, session lifecycle, turn-ID surfacing pipeline, doc-chat integration, and CC API contract), read [`CLAUDE.md`](../CLAUDE.md) — see the **CC API Contract** and **Sessions** sections — and the source in [`dashboard/js/command-center.js`](../dashboard/js/command-center.js), [`dashboard.js`](../dashboard.js) (`handleCommandCenter`), and [`prompts/cc-system.md`](../prompts/cc-system.md).
 

package/docs/completion-reports.md

@@ -6,9 +6,11 @@ This document is the canonical schema. Playbooks should cross-link here instead
 
 ## Where the report is written
 
-The engine injects the absolute path two ways before spawning each agent:
+The engine delivers the absolute path two ways before spawning each agent:
 
-- `MINIONS_COMPLETION_REPORT` environment variable
+- `MINIONS_COMPLETION_REPORT` in the child environment for cold spawns, or the
+  same-named authoritative value in the trusted ACP session context for pooled
+  spawns
 - The same path appears in the rendered playbook prompt
 
 Path shape (resolved by `shared.dispatchCompletionReportPath()` in `engine/shared.js`):
@@ -21,7 +23,15 @@ The agent must write the JSON to that exact path before exiting. Any character o
 
 ## Trust boundary
 
-Each spawn also receives a per-dispatch cryptographic value via the `MINIONS_COMPLETION_NONCE` environment variable. The engine generates this with `crypto.randomBytes(16).toString('hex')` in `engine.js:spawnAgent()` and stores it on the in-memory active-process record. The agent is required to copy the value verbatim into the report's `nonce` field. On parse, `engine/lifecycle.js:runPostCompletionHooks()` compares `report.nonce` against the in-memory value:
+Each spawn also receives a per-dispatch cryptographic value named
+`MINIONS_COMPLETION_NONCE`. Cold spawns receive it in the child environment;
+pooled ACP spawns receive it in trusted, lease-scoped system context so the
+nonce never enters reusable process state or untrusted task content. The engine
+generates it with `crypto.randomBytes(16).toString('hex')` in
+`engine.js:spawnAgent()` and stores it on the in-memory active-process record.
+The agent is required to copy the value verbatim into the report's `nonce`
+field. On parse, `engine/lifecycle.js:runPostCompletionHooks()` compares
+`report.nonce` against the in-memory value:
 
 - **Match** — the report is trusted and processed normally.
 - **Mismatch** — the report is treated as forged (a prompt-injected agent or a stale process writing into a sibling dispatch's completion path). Every signal it carries — `status`, `pr`, `noop`, `failure_class`, `retryable`, `needs_rerun`, artifacts, follow-ups — is discarded. The dispatch is failed with `failure_class: 'completion-nonce-mismatch'` and the work item is marked failed (no auto-retry honors the agent's `retryable` claim).
@@ -263,7 +273,7 @@ optional `followups` array on its completion report:
 Engine behavior (`engine/lifecycle.js` `processCompletionFollowups`):
 
 - Each entry is logged at `info`: `Followup audit (<agent> wi=<parent>): dispatched <wi_id> — <title> (comment=<id>) — <reason>`.
-- If the claimed `wi_id` does not exist in any project's `work-items.json` at parse time, a `warn` is emitted. This catches dispatches that were deduped to a 409 / 200-duplicate response, reverted, or never actually landed.
+- If the claimed `wi_id` does not exist in any project SQL scope at parse time, a `warn` is emitted. This catches dispatches that were deduped to a 409 / 200-duplicate response, reverted, or never actually landed.
 - The `followups` array is **descriptive only** — the engine does not auto-create or auto-link these WIs from the report. Creation happens at the moment the agent calls `POST /api/work-items`; the report is just the auditable record.
 - Malformed entries (non-object, missing `wi_id`) are logged and skipped.
 

package/docs/constellation-bridge.md

@@ -1,14 +1,14 @@
 # Constellation bridge
 
-Minions ships a small read-only surface that the [Constellation](https://office.visualstudio.com/DefaultCollection/ISS/_git/constellation) dashboard polls to project Minions engine state (agents, dispatch queue, PR pipeline) into its HUD. This page documents the Minions-side of that contract.
+Minions ships a versioned read-only surface that the [Constellation](https://office.visualstudio.com/DefaultCollection/ISS/_git/constellation) agent polls to mirror a locally-running Minions instance into its cloud HUD. Minions remains the execution and state authority on the DevBox; Constellation stores only the bounded metadata projection documented here.
 
-> **The bridge polling logic itself lives in the Constellation repo** (`packages/agent/src/bridges/`). Minions only owns the on/off flag, the marker-file contract, and the `minions bridge` subcommand for local debugging.
+> **The bridge polling logic itself lives in the Constellation repo** (`packages/agent/src/orchestrator-bridge/`). Minions owns the snapshot contract, the on/off flag, the marker-file contract, and the `minions bridge` subcommand for local debugging.
 
 ## Quick start
 
 ```bash
 minions bridge status     # Show enabled flag + last-seen Constellation agent
-minions bridge health     # Probe http://127.0.0.1:7331/api/status and print the projection
+minions bridge health     # Probe /api/constellation/v1/snapshot and print its metadata summary
 minions bridge enable     # Set engine.constellationBridge.enabled = true
 minions bridge disable    # Set engine.constellationBridge.enabled = false
 ```
@@ -38,6 +38,52 @@ minions bridge disable
 
 Both subcommands write `~/.minions/config.json` atomically via `mutateJsonFileLocked`, so concurrent edits from the engine/dashboard cannot tear the file.
 
+## Versioned snapshot contract
+
+The Constellation agent polls:
+
+```text
+GET http://127.0.0.1:7331/api/constellation/v1/snapshot
+```
+
+The endpoint is loopback-only because the Minions dashboard binds `127.0.0.1`. It supports `ETag` and `If-None-Match`; unchanged state returns `304` with no body. A `200` response is a **complete replacement snapshot**, so consumers must remove previously mirrored entities that are absent from the latest response.
+
+```json
+{
+  "protocol": "minions.constellation.snapshot",
+  "protocolVersion": 1,
+  "complete": true,
+  "generatedAt": "2026-07-13T08:00:00.000Z",
+  "minionsVersion": "0.1.2203",
+  "engine": { "state": "running", "pid": 1234 },
+  "entities": {
+    "work_item": [],
+    "pr": [],
+    "plan": [],
+    "schedule": [],
+    "dispatch": [],
+    "agent_status": [],
+    "device_summary": []
+  }
+}
+```
+
+`protocolVersion` changes only for a breaking schema change. Additive optional fields do not require a version bump.
+
+### Privacy boundary
+
+Every entity is rebuilt from an explicit allowlist in `engine/bridge.js`; raw dashboard records are never forwarded. The snapshot excludes task descriptions, prompts, acceptance criteria, completion reports, diffs, comments, human feedback, notes, logs, filesystem paths, environment variables, tokens, and secrets. Strings are length-capped to the matching Constellation schema limits.
+
+The entity shapes match `packages/shared/src/orchestrator-messages.ts` in the Constellation repository:
+
+- `work_item`: identifiers, title, type/priority/status, project/agent, lifecycle timestamps.
+- `pr`: identifiers, title/status/review status, branch/URL, merge metadata and timestamps.
+- `plan`: identifier, title/status, project/agent and timestamps.
+- `schedule`: identifier, title/type/status, project/agent and run timestamps.
+- `dispatch`: identifier, agent/status/type/project, linked WI/PR and lifecycle timestamps.
+- `agent_status`: agent/status/project, current task identifiers/title and update time.
+- `device_summary`: aggregate counts plus protocol, Minions version and engine health.
+
 ## Marker-file contract
 
 The Constellation agent's bridge writes a marker file on every successful poll. Minions reads it with `minions bridge status` so a local operator can verify the bridge is alive and Constellation is talking to it.
@@ -67,21 +113,24 @@ Writers MUST use an atomic-replace pattern (`write to tmp + rename`) so a partia
 
 ## `minions bridge health`
 
-`bridge health` performs a synchronous probe of the Minions dashboard's `GET /api/status` endpoint and prints a **curated subset** — the same fields the Constellation bridge would project into its own data model. This is intentionally small: full `/api/status` is large, unstable, and may expose unrelated local state.
+`bridge health` performs a synchronous probe of the versioned snapshot endpoint and prints its aggregate metadata. This verifies both dashboard reachability and protocol compatibility.
 
 Sample output:
 
 ```text
 bridge: dashboard reachable on http://127.0.0.1:7331
-  projection (same fields the Constellation bridge would read):
+  snapshot (same metadata the Constellation bridge mirrors):
+    protocolVersion: 1
+    minionsVersion: 0.1.2203
     engineState: running
     enginePid: 1234
-    minionsVersion: 0.1.1984
     agentCount: 5
     activeAgentCount: 2
-    dispatchPending: 1
-    dispatchActive: 2
-    dispatchCompleted: 14
+    workItemCount: 18
+    pullRequestCount: 4
+    planCount: 2
+    scheduleCount: 3
+    dispatchCount: 14
     projectCount: 3
 ```
 
@@ -89,6 +138,6 @@ If the dashboard is not listening, `bridge health` prints `dashboard not running
 
 ## Cross-repo coordination
 
-The Constellation-side PR ([P-wi1-bridge-readonly](https://office.visualstudio.com/DefaultCollection/ISS/_git/constellation)) lands independently of this Minions PR. The Minions side merges first with the default `enabled: false`, then the Constellation side lights up bridge polling. Operators flip the flag to `true` only after both sides are deployed.
+The Minions producer lands before the Constellation consumer. During rollout, Constellation may fall back to the legacy per-endpoint projection only when the versioned endpoint returns `404`; a malformed versioned response must fail closed rather than silently downgrading.
 
 The Constellation agent's bridge reads `~/.minions/config.json` directly (no Minions HTTP API call) so config edits propagate without waiting for the engine to restart.

package/docs/constellation-style-telemetry.md

@@ -62,12 +62,12 @@ Key design properties:
 
 | Constellation concept | Minions equivalent today |
 |---|---|
-| `metrics_daily` rollups | `metrics.json._daily.<YYYY-MM-DD>` → `{costUsd, inputTokens, outputTokens, cacheRead, tasks}` |
+| `metrics_daily` rollups | SQL metrics `_daily.<YYYY-MM-DD>` → `{costUsd, inputTokens, outputTokens, cacheRead, tasks}` |
 | Per-entity aggregates | Per-agent counters: `tasksCompleted/Errored`, `prsCreated/Approved/Rejected/Merged`, `reviewsDone`, `totalCostUsd`, `totalInputTokens/OutputTokens/CacheRead`, `totalRuntimeMs`, `model`, `timedTasks` |
-| App/engine analytics | `metrics.json._engine`: `command-center`, `agent-dispatch`, `consolidation`, `agent_memory_reconcile` |
+| App/engine analytics | SQL metrics `_engine`: `command-center`, `agent-dispatch`, `consolidation`, `agent_memory_reconcile` |
 | Emit helpers | `llm.trackEngineUsage()`, `trackReviewMetric()`, `updateMetrics()` (`engine/lifecycle.js`, `engine/llm.js`, `engine/shared.js`) |
 | Structured error taxonomy | `FAILURE_CLASS` constants (recorded per work-item; not yet aggregated as a metric) |
-| Diagnostic stream | `log.json` ring buffer (2500, secret-redacted via `redactSecrets()`) + `engine/dashboard-diagnostics.log` |
+| Diagnostic stream | SQL log tail (secret-redacted via `redactSecrets()`) + `engine/dashboard-diagnostics.log` |
 | Admin overview query | `getMetrics()` (`engine/queries.js`) surfaced via `/api/status` |
 
 ## The gap (the 40% worth building)
@@ -109,9 +109,9 @@ review verdicts, CC turns. Gitignored runtime file (add to the State Files list
 
 ### Phase 2 — Rollup + retention (small, ~½ day)
 Extend the existing daily-rollup path so it also folds event counts + failure-category tallies into
-`metrics.json._daily`. Prune `events.jsonl` lines older than `telemetryRetentionDays` **after** the
+SQL metrics `_daily`. Prune `events.jsonl` lines older than `telemetryRetentionDays` **after** the
 rollup write succeeds (Constellation's invariant). Slots into an existing periodic tick phase.
-All `metrics.json` writes stay inside `mutateJsonFileLocked()`.
+All metric writes go through the SQL metrics store.
 
 ### Phase 3 — Usage dashboard page (medium, ~1–1.5 days)
 New sidebar page reading `getMetrics()` + `_daily`: cost/token trend, dispatches-by-type,
@@ -156,6 +156,6 @@ the other HTML entry points; counters from an in-memory registry, no client libr
   `packages/server/src/api/prism.ts`, `packages/dashboard/src/prism/prism-telemetry.ts`
 - Constellation taxonomy/privacy: `packages/shared/src/constants.ts`,
   `packages/shared/src/privacy.ts`
-- Minions today: `engine/metrics.json`, `getMetrics()` (`engine/queries.js`),
+- Minions today: `engine/state.db` metrics, `getMetrics()` (`engine/queries.js`),
   `trackEngineUsage()` (`engine/llm.js`), `FAILURE_CLASS` (`engine/shared.js`),
   related design doc `design-state-storage.md`.

package/docs/cooldown-merge-semantics.md

@@ -1,5 +1,9 @@
 # `saveCooldowns` merge semantics
 
+> **Historical design record:** this predates the SQL-only cutover. Cooldowns now
+> persist through `engine/small-state-store.js`; file and lock references below
+> describe the superseded implementation evaluated by the original PRD.
+
 Scoping deliverable for PRD item **P-bfa3a-scope-cooldown-merge** (Wave 3, PR10
 pre-work) of the 2026-05-27 weekly bug-audit plan. Decides the merge strategy
 the implementation PR (**P-bfa3b-cooldown-lost-update**) will apply at

package/docs/copilot-cli-schema.md

@@ -31,7 +31,7 @@
 | Default | Value |
 |---|---|
 | `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. |
+| `copilotDisableBuiltinMcps` | `true` — github-mcp-server bypasses Minions' SQL PR tracking; default OFF. |
 | `copilotReasoningSummaries` | `false` — opt-in; only some models honor it. |
 
 ---
@@ -513,13 +513,13 @@ that default.
 server is still *registered* (Copilot inventories it for diagnostics), but the
 agent cannot use its tools. This is the desired behavior — Minions wants the
 server invisible to the agent so all GitHub mutations route through the
-project's `pull-requests.json` tracker rather than spawning ghost PRs.
+project's PR store rather than spawning ghost PRs.
 
 > **Tooltip text for the dashboard `copilotDisableBuiltinMcps` toggle**
 > (per P-7a5c1f8e):
 >
 > > When OFF, agents can autonomously create PRs / labels / comments via the
-> > github-mcp-server, bypassing Minions' `pull-requests.json` tracking. Leave
+> > github-mcp-server, bypassing Minions' PR tracking. Leave
 > > this ON unless you have a specific reason to expose the server.
 
 ---

package/docs/cross-repo-plans.md

@@ -1,6 +1,6 @@
 # Cross-repo plans
 
-> A cross-repo plan is a single Minions plan whose work items ship into **two or more configured projects**. The plan has no owning project; each `missing_features` item declares its own `project`, the materializer fans the items into per-project `work-items.json` files, and verify completion fans out into one verify work item per touched repo.
+> A cross-repo plan is a single Minions plan whose work items ship into **two or more configured projects**. The plan has no owning project; each `missing_features` item declares its own `project`, the materializer fans items into per-project SQL scopes, and verify completion fans out into one verify work item per touched repo.
 >
 > Shipped by `PL-cross-repo-coordination` (`prd/minions-opg-2026-06-10-3.json`, items `P-7a3f1c08` … `P-8b5d3e07`). Default plan shape is unchanged for single-project plans — everything in this doc only activates when the plan markdown declares more than one project.
 
@@ -77,22 +77,22 @@ The top-level `project` is empty. Each item names its own repo. `depends_on` may
 
 ## Per-item project routing
 
-`engine.js#materializePlansAsWorkItems` (~line 5151) groups PRD `missing_features` by `item.project` into a per-project map, then writes each group to `shared.projectWorkItemsPath(project)` — i.e. `<MINIONS_DIR>/projects/<name>/work-items.json`. The routing rules:
+`engine.js#materializePlansAsWorkItems` groups PRD `missing_features` by `item.project`, then writes each group transactionally to that project's SQL work-item scope. The routing rules:
 
 | `item.project` value | Where it lands |
 | --- | --- |
-| Names a configured project | That project's `projects/<name>/work-items.json` |
+| Names a configured project | That project's SQL scope |
 | Names an unknown project | Skipped; PRD item stamped with `_invalidProject: <error>` (see `formatUnknownProjectError`) |
 | Unset, and central WIs disabled | Falls back to the plan-level `defaultProject` (or skipped if neither is resolvable) |
-| Unset, and central WIs enabled | Lands in central `work-items.json` (legacy single-project plans) |
+| Unset, and central WIs enabled | Lands in the central SQL scope |
 
-The materializer enforces a single per-project lock per write (`mutateWorkItems(wiPath, …)`), so per-project writes never contend. Cross-project re-opens (e.g. a `missing` PRD item whose previous WI lives in a sibling project) are queued as `deferredReopens` and executed outside the current project's lock (see `engine.js:5297` for the pattern).
+The materializer uses one transaction per project scope (`mutateWorkItems(project, …)`). Cross-project re-opens are queued as `deferredReopens` and executed outside the current project's transaction.
 
-**Reconciliation, PRD-removal sync, and `i.projects[]` rollup** all happen per-project under the same loop. Per-item state is owned by exactly one project's file at a time, so reading `projectWorkItemsPath(project)` always gives a consistent slice for that repo.
+**Reconciliation, PRD-removal sync, and `i.projects[]` rollup** all happen per-project under the same loop. Per-item state is owned by exactly one SQL scope at a time.
 
 ## Cycle detection (runs ONCE over the whole plan)
 
-`detectDependencyCycles(plan.missing_features)` (`engine.js:4638`) runs once over the full PRD `missing_features` set **before** the per-project grouping loop, so a cyclic chain that crosses repos (e.g. `P-aaa1` in `minions` → `P-bbb2` in `minions-opg` → `P-aaa1`) is detected and every cyclic item is skipped at materialization time — neither project's `work-items.json` receives the cyclic items.
+`detectDependencyCycles(plan.missing_features)` (`engine.js:4638`) runs once over the full PRD `missing_features` set **before** the per-project grouping loop, so a cyclic chain that crosses repos (e.g. `P-aaa1` in `minions` → `P-bbb2` in `minions-opg` → `P-aaa1`) is detected and every cyclic item is skipped at materialization time — neither project's scope receives the cyclic items.
 
 Caveat: `detectDependencyCycles` is a partial DFS — 2-cycles (`A → B → A`) are fully detected, but N-cycles ≥ 3 with distinct nodes only flag the back-edge target and recursing parent. Both legs of a 2-cycle and the canonical back-edge of a longer cycle reliably get skipped. Fixing the partial detector is tracked separately; cross-repo plans inherit the same behaviour as single-project plans.
 
@@ -126,7 +126,7 @@ for each project P in itemsByProject (excluding the `_central` bucket):
     git push -u origin <branch>      # no-op if origin already has the tip
 ```
 
-The block is fully idempotent — `rev-parse --verify` guards the local `git branch` create, and `git push -u origin <branch>` is a no-op when origin already has the tip. Per-project failure isolation is explicit: a broken `localPath` or git config in one project logs a warn and continues to the next. The `_central` pseudo-project bucket (legacy central work-items.json) is skipped because it has no project root.
+The block is fully idempotent — `rev-parse --verify` guards the local `git branch` create, and `git push -u origin <branch>` is a no-op when origin already has the tip. Per-project failure isolation is explicit: a broken `localPath` or git config in one project logs a warn and continues to the next. The `_central` pseudo-project bucket is skipped because it has no project root.
 
 This is what makes the per-project dispatcher's later `git worktree add ... origin/<branch>` work — each project's origin already has the branch pointing at its own main, and parallel dispatches across repos can each commit + push to the same branch name in their own repo independently.
 
@@ -134,7 +134,7 @@ This is what makes the per-project dispatcher's later `git worktree add ... orig
 
 ## Per-project dispatch (read-side)
 
-`engine.js#discoverFromWorkItems(config, project)` (~line 6671) reads exactly one project's `projectWorkItemsPath(project)` per call, routes pending items via `routing.md`, and returns `newWork[]` entries for the dispatcher. Cross-repo plans don't change this loop — the per-project file is the source of truth for what each project's dispatcher sees, and the engine iterates all configured projects per tick.
+`engine.js#discoverFromWorkItems(config, project)` reads exactly one project SQL scope per call, routes pending items via `routing.md`, and returns `newWork[]` entries for the dispatcher. Cross-repo plans don't change this loop; the engine iterates all configured projects per tick.
 
 Module-level `_claimedAgents` in `engine/routing.js` persists across in-process calls but is cleared per tick (`routing.resetClaims()`), so two items in different projects routed to the same agent in the same tick contend correctly for the single agent slot.
 
@@ -145,7 +145,7 @@ Module-level `_claimedAgents` in `engine/routing.js` persists across in-process
 1. Every PRD `missing_features` item has been materialized into a WI.
 2. Every materialized WI is in a terminal state (`DONE_STATUSES` or `cancelled`).
 
-When both gates pass, the function groups **active PRs** by project — reading each project's `pull-requests.json` via `shared.projectPrPath(p)`, joining to the plan's done items via `engine/pr-links.json` (`getPrLinks()`). The result is a `touchedProjects` array: every project that has at least one active PR linked to one of the plan's done items.
+When both gates pass, the function groups **active PRs** by project from the SQL PR store and joins them to done items through the `pr_links` table. The result is a `touchedProjects` array: every project that has at least one active PR linked to one of the plan's done items.
 
 For each touched project the fan-out (lines 245–415):
 
@@ -155,7 +155,7 @@ For each touched project the fan-out (lines 245–415):
   - **Shared-branch plans** reuse `feature_branch` directly — the verify agent checks out the branch in-place in the project's localPath.
   - **Parallel-branch plans** merge each linked PR branch into a per-project worktree at `<localPath>/../worktrees/verify-<projName>-<planSlug>`.
 - Validates every branch ref through `shared.validateGitRef` before splicing into the bash setup commands (P-f3-verify-prompt — defense in depth against shell injection from a crafted `feature_branch` or PR `branch` field).
-- Writes a new verify WI into the touched project's `projectWorkItemsPath(p)` with `itemType: 'verify'`, `type: 'verify'`, `priority: 'high'`, `status: 'pending'`, and `project: <projName>`. The title is project-prefixed (`Verify plan (minions-opg): …`) when `touchedProjects.length > 1` to disambiguate the dashboard listing.
+- Writes a new verify WI into the touched project's SQL scope with `itemType: 'verify'`, `type: 'verify'`, `priority: 'high'`, `status: 'pending'`, and `project: <projName>`. The title is project-prefixed (`Verify plan (minions-opg): …`) when `touchedProjects.length > 1` to disambiguate the dashboard listing.
 
 **Fallback:** when no PRs were ever linked (e.g. items completed without PR records, or legacy state), the fan-out collapses to a single verify WI on the **primary project** (the project with the most completed items) so the plan still gets verified.
 
@@ -240,13 +240,13 @@ Operator approves the plan. Plan-to-prd dispatches against the `minions` project
 
 Engine ticks once:
 
-1. `materializePlansAsWorkItems` groups by project: `{ minions: [P-001], minions-opg: [P-002] }`. Cycle scan runs once over both items, finds nothing. Writes `projects/minions/work-items.json` with P-001 and `projects/minions-opg/work-items.json` with P-002. Branch-strategy is `parallel`, so no shared-branch pre-create runs.
+1. `materializePlansAsWorkItems` groups by project: `{ minions: [P-001], minions-opg: [P-002] }`. Cycle scan runs once over both items, finds nothing. Writes P-001 and P-002 to their respective SQL scopes. Branch-strategy is `parallel`, so no shared-branch pre-create runs.
 2. `discoverFromWorkItems(config, minions)` picks up P-001, routes it via `routing.md`, dispatches `implement` agent. Worktree created on `work/P-001` off `minions`' main.
 3. `discoverFromWorkItems(config, minions-opg)` picks up P-002. Its `depends_on: ["P-001"]` resolves to a same-project dep? **No** — P-001 lives in the `minions` project, so it's a **cross-repo dep**. The dispatcher fetches P-001's branch into the `minions` rootDir, transfer-fetches it into the `minions-opg` worktree under `refs/cross-repo-deps/work/P-001`, computes a short SHA + changed-file list, and appends a `## Cross-repo dependencies` section to the prompt. The agent inspects via `git show` / `git log` and ships matching code in `minions-opg`.
-4. Both items complete with PRs. `engine/pr-links.json` links each PR to its WI.
+4. Both items complete with PRs. SQL `pr_links` rows link each PR to its WI.
 5. Next tick `lifecycle.checkPlanCompletion` runs. Gates pass (every item materialized + done). Groups active PRs by project: `{ minions: [PR for P-001], minions-opg: [PR for P-002] }`. Creates two verify WIs:
-   - `(minions)` verify WI in `projects/minions/work-items.json` with `project: 'minions'`.
-   - `(minions-opg)` verify WI in `projects/minions-opg/work-items.json` with `project: 'minions-opg'`.
+   - `(minions)` verify WI in the `minions` scope with `project: 'minions'`.
+   - `(minions-opg)` verify WI in the `minions-opg` scope with `project: 'minions-opg'`.
 6. Both verify agents dispatch in parallel. Each builds + tests its own repo. Each writes `prd/guides/verify-cross-repo-launch.md` in its own repo's worktree.
 7. Dashboard plan card shows `minions 2/2 · minions-opg 2/2` rollup pills and two labelled verify badges. Operator archives the plan via `POST /api/plans/archive` when both verifies complete.
 
@@ -267,7 +267,7 @@ When you need to change the cross-repo path, the load-bearing seams are:
 | Shared-branch pre-create per project | `engine.js:5318–5356` | Idempotent `rev-parse` → `branch` → `push -u`; per-project failure isolation. |
 | Cross-repo dep partitioning + advisory fetch | `engine.js:2495–2682` (`spawnAgent` dep loop) | `isCrossRepo` split; transfer-fetch via filesystem-path remote into `refs/cross-repo-deps/<branch>`. |
 | Cross-repo dep prompt section | `engine.js:662–710` (`buildCrossRepoDepsSection`) | Renders one section per dep with repo, branch, SHA, files, local ref. |
-| Per-project verify fan-out | `engine/lifecycle.js:217–274` (`checkPlanCompletion`) | Group active PRs by project via `engine/pr-links.json`; one verify WI per touched project. |
+| Per-project verify fan-out | `engine/lifecycle.js` (`checkPlanCompletion`) | Group active PRs by project via SQL links; one verify WI per touched project. |
 | Verify WI creation | `engine/lifecycle.js:387–411` | `itemType:'verify'`, `project: projName`, project-prefixed title when `touchedProjects.length > 1`. |
 | Per-project rollup pills | `dashboard.js#handlePlansList` (P-66b1faec) | Gate `_perProjectProgress.length >= 2`. |
 | Per-project verify badges | `dashboard/js/render-plans.js` (P-d7e592b1) | Gate `verifyWis.length >= 2`. |
@@ -277,7 +277,7 @@ When you need to change the cross-repo path, the load-bearing seams are:
 
 `test/integration/cross-repo-plan-e2e.test.js` (P-8b5d3e07) drives the four load-bearing seams against the real engine code in an isolated `MINIONS_TEST_DIR` (no live state touched, no agents spawned):
 
-1. PRD with per-item `project` fans into per-project `work-items.json` files (alpha vs beta).
+1. PRD with per-item `project` fans into per-project SQL scopes (alpha vs beta).
 2. `discoverFromWorkItems(config, project)` returns only the queried project's items.
 3. `checkPlanCompletion` creates one verify WI per touched project when each project has at least one active PR linked to a done WI.
 4. A 3-feature cyclic chain that crosses project boundaries (alpha → beta → alpha) is detected and none of the cyclic items are written.

package/docs/deprecated.json

@@ -43,10 +43,10 @@
       "LEGACY_DONE_ALIASES",
       "LEGACY_NEEDS_REVIEW_STATUS"
     ],
-    "reason": "Read-side tolerance: cleanup sweep auto-migrates four obsolete work-item / PRD status strings ('in-pr', 'implemented', 'complete', 'needs-human-review') to the canonical 'done' / 'failed' values. The aliases are no longer written anywhere in the engine; the constants exist only to repair stale on-disk values from old engine versions.",
+    "reason": "Read-side tolerance: cleanup sweep auto-migrates four obsolete work-item / PRD status strings ('in-pr', 'implemented', 'complete', 'needs-human-review') to the canonical 'done' / 'failed' values. The aliases are no longer written anywhere in the engine; the constants exist only to repair stale SQL records imported from old engine versions.",
     "status": "active",
     "targetRemovalDate": null,
-    "notes": "Keep indefinitely until telemetry / a sweep log shows zero migrations performed for 30 consecutive days across all known projects (work-items.json + prd/*.json). At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js (definitions at :1165-1166; usage at :1168-1183 for work items and :1269-1272 for PRD missing_features) can be deleted. Total cost on disk today: 4 strings."
+    "notes": "Keep indefinitely until telemetry shows zero migrations for 30 consecutive days across all project scopes and PRDs. At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js can be deleted."
   },
   {
     "id": "config-claude-binary-override",

package/docs/design-state-storage.md

@@ -2,7 +2,7 @@
 
 > Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Implemented**
 
-> **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.
+> **Implementation status:** Migrations 001–024 implement the full SQLite cutover and final compatibility cleanup. `engine/state.db` is the sole runtime-state authority; migration 018 records the cutover, migrations 020–024 absorb the remaining scoped/archive/session state and one-time PRD collision repair. Historical migrations retain one-time JSON import support. Normal runtime never references 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