@yemi33/minions 0.1.2370 → 0.1.2372

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.
 
 ---
 

package/docs/harness-propagation.md

@@ -1,273 +1,43 @@
-# Harness Propagation
+# Native Repository Harness
 
-> Status: contract doc for the **seamless user/repo harness invocation** plan
-> (`plans/seamless-user-repo-harness-invocation.md`, PRD
-> `prd/minions-opg-2026-06-10-4.json`). This is the foundation item — it nails
-> down the *current* propagation surfaces and the worktree footgun so the
-> rest of the plan can extend them without reinventing the contract. Read this
-> before adding a new adapter method, a new asset kind, or a new opt-out flag.
+Minions delegates repository instructions, skills, commands, and MCP discovery
+to the selected CLI runtime. It does not classify repository assets, inject
+selected skill content into prompts, add external harness directories, suppress
+repository instruction files, or attest which harnesses an agent used.
 
-## What is a "harness"
+## Runtime contract
 
-In this doc, "harness" means any user-installed or repo-local asset that the
-runtime CLI auto-discovers when it starts:
+For each dispatch Minions:
 
-- **Skills** — `SKILL.md` files the CLI loads as reusable workflows.
-- **Slash commands** — `*.md` files the CLI exposes as `/command-name`.
-- **MCP servers** — JSON config entries that point at a stdio/HTTP server.
+1. Creates or selects the checkout.
+2. Sets the CLI working directory to the repository root or the configured
+   `meta.workdir`.
+3. Invokes the selected runtime adapter with the task prompt and explicit
+   orchestration/security flags.
 
-A harness is "propagated" when it reaches a dispatched agent without the user
-having to register it again in Minions. The single-line goal: *if it works
-when you type the same task into `claude` / `copilot` / `codex` in this repo
-on this machine, it works when Minions dispatches the same task here.*
+From that point, Claude, Copilot, or Codex performs its normal native discovery
+from the working directory and user configuration. Running the same CLI in the
+same checkout should expose the same repository harness.
 
-## The four propagation mechanisms
+Repository harness files must exist in the dispatched checkout. In worktree
+mode, uncommitted files from the operator's main checkout are intentionally not
+copied into the dispatch worktree. Commit shared repository harness files, use
+the runtime's user-level configuration for personal assets, or opt into live
+checkout mode when the operator tree itself must be used.
 
-Every asset reaches the agent through exactly one of these mechanisms today.
-No engine code branches on `runtime.name` for any of them — the runtime
-adapter answers the contract questions and the engine fans out.
+## Explicit exceptions
 
-### 1. Runtime native discovery (no engine code involved)
+- `engine.copilotDisableBuiltinMcps` prevents Copilot's bundled GitHub MCP from
+  bypassing Minions PR tracking. This is an orchestration safety policy, not a
+  repository-harness override.
+- `engine.claudePreApproveWorkspaceMcps` pre-approves the checkout's native
+  `.mcp.json` entries so a headless Claude process does not block on an invisible
+  trust prompt. It does not alter discovery or server definitions.
+- Workspace manifests may restrict tools and repositories as an explicit
+  security boundary.
 
-The CLI reads its own config and indexes its own asset dirs on every spawn.
-Minions does not copy, symlink, or aggregate user-level assets — it just
-makes sure the relevant dirs are *readable* from the agent's cwd (see
-mechanism #3 below). The actual loading is the CLI's job.
+## Diagnostics
 
-| Runtime | User skills | User commands | User MCP servers |
-|---------|-------------|---------------|------------------|
-| Claude (`engine/runtimes/claude.js`) | `~/.claude/skills`, `~/.agents/skills`, plus `~/.claude/plugins/<…>/skills` | `~/.claude/commands`, plugin `commands/` | `~/.claude.json → mcpServers` |
-| Copilot (`engine/runtimes/copilot.js`) | `~/.copilot/skills`, `~/.agents/skills`, `~/.copilot/installed-plugins/<…>/skills` | `~/.copilot/commands` *(probe)* | `~/.copilot/mcp-config.json → mcpServers` |
-| Codex (`engine/runtimes/codex.js`) | `~/.agents/skills`, `/etc/codex/skills` | not yet supported by CLI | not yet a stable contract |
-
-The first column is the source of truth for "where does the CLI look on
-this machine?". The dashboard's tooling page mirrors this via
-`engine/queries.js → collectSkillFiles / collectCommandFiles`.
-
-### 2. Cwd routing (`shared.resolveSpawnPaths`)
-
-`engine/shared.js → resolveSpawnPaths(project, type, MINIONS_DIR)` decides
-what the agent's `cwd` is:
-
-- **Read-only types** (`meeting`, `ask`, `explore`, `plan-to-prd`, `plan`)
-  → `cwd = project.localPath` (the operator's main checkout — sees
-  uncommitted files).
-- **Code-mutating types** (`implement`, `fix`, `review`, `test`, `verify`,
-  `decompose`, `docs`) → `cwd = <worktree>` (a fresh `git worktree add`
-  checked out at branch tip — only sees committed files).
-
-Cwd routing matters because every CLI's native discovery is **rooted at
-cwd**. Project-scope skills like `<repo>/.claude/skills/foo/SKILL.md` are
-loaded by the CLI only if `<cwd>/.claude/skills/foo/SKILL.md` exists at
-spawn time. See *The worktree-uncommitted footgun* below.
-
-Live-checkout mode (`project.checkoutMode: 'live'`) collapses both branches
-to `cwd = project.localPath` for every dispatch type, so the agent sees
-the operator's working tree as-is (including uncommitted assets). The
-tradeoff is single-mutating-dispatch concurrency per project — see
-`docs/live-checkout-mode.md`.
-
-### 3. `--add-dir` (`engine/spawn-agent.js → computeAddDirs`)
-
-`computeAddDirs({ runtime, minionsDir, homeDir })` builds the list of
-absolute dirs the CLI is allowed to read **outside** its cwd. The current
-list:
-
-1. `minionsDir` — always first, so playbooks, system prompt, and skill
-   index are reachable from any worktree.
-2. Every existing dir returned by `runtime.getUserAssetDirs({ homeDir })`
-   for the resolved runtime — e.g. `~/.claude` + `~/.agents` for Claude,
-   `~/.copilot` + `~/.agents` for Copilot, `~/.codex` + `~/.agents` for
-   Codex.
-
-Non-existent dirs are dropped (Claude CLI rejects unknown `--add-dir`
-entries) and the list is deduped by resolved path.
-
-`--add-dir` is the **only** mechanism today that crosses the worktree
-boundary. It does not (yet) cover project-local-but-uncommitted assets —
-that's plan item #5 (`harnessPropagateProjectLocal`).
-
-### 4. MCP suppression flags
-
-Two flags strip otherwise-inherited MCP / instruction surfaces; everything
-else flows through implicitly because the CLI reads its native config on
-every spawn:
-
-- `engine.copilotDisableBuiltinMcps` (default `true`) → `--disable-builtin-mcps`
-  on Copilot. Strips Copilot's built-in `github-mcp-server` so dispatched
-  agents do not try to open a parallel PR through the bundled MCP while
-  Minions is already managing the PR via the host integration.
-- `engine.copilotSuppressAgentsMd` (default `true`) → `--no-custom-instructions`
-  on Copilot. Strips project `AGENTS.md` auto-load so Minions playbook
-  prompts are not silently overridden by repo-local instructions.
-
-There is no equivalent flag for stripping user-level skills, user-level
-slash commands, or user-level MCPs. The current posture is "always inherit"
-— `engine.hermeticHarness` (P-49e1c8b7, default `false`) is the per-fleet /
-per-agent opt-out. When TRUE:
-
-- `--add-dir` collapses to exactly `[minionsDir]` — every dir from
-  `runtime.getUserAssetDirs({ homeDir })` is dropped.
-- `harnessPropagateProjectLocal` is skipped — no `--project-harness-dir`
-  flags emitted.
-- `claudePreApproveWorkspaceMcps` is skipped — workspace `.mcp.json`
-  servers are not pre-approved in `~/.claude.json`.
-
-The flag is **independent** of `copilotDisableBuiltinMcps` and
-`copilotSuppressAgentsMd` — those keep their existing semantics so an
-operator can run hermetic Claude *and* keep Copilot's built-in MCPs off
-or AGENTS.md auto-load suppressed without re-thinking each lever. Per-agent
-override at `agent.hermeticHarness` (resolved via
-`shared.resolveAgentHermeticHarness(agent, engine)`, mirrors
-`shared.resolveAgentBareMode`).
-
-## The worktree-uncommitted footgun
-
-The single biggest behavioral wrinkle for new contributors:
-
-1. The operator drops an experimental skill at
-   `<repo>/.claude/skills/bar/SKILL.md` on their main checkout.
-2. The skill works fine when invoked by hand:
-   `cd <repo>; claude "use the bar skill"` — Claude's auto-discovery
-   sees it because cwd is the main checkout.
-3. The operator dispatches an `implement` work item against the same repo.
-4. The engine runs `git worktree add <wt> origin/<branch>` (uncommitted
-   files do not appear in a fresh worktree), then spawns the agent with
-   `cwd = <wt>`.
-5. Claude's discovery now happens at `<wt>` — `.claude/skills/bar/` is
-   absent. The agent silently underperforms with no error message.
-
-Read-only dispatch types (`meeting`, `ask`, `explore`, `plan-to-prd`,
-`plan`) do **not** hit this footgun, because their cwd is
-`project.localPath`. Mutating types do.
-
-`--add-dir` is not currently extended to cover this case (plan item #5),
-so the only workarounds today are:
-
-- **Commit it.** The skill becomes visible to every dispatch and every
-  teammate, with the usual reviewability tradeoff.
-- **Move it user-scope.** Drop it under `~/.claude/skills/bar/` instead —
-  the CLI's user-skill discovery still works inside a worktree because
-  `--add-dir` attaches `~/.claude`.
-- **Flip to live-checkout mode.** Set `project.checkoutMode = 'live'` on
-  the project so every dispatch runs in `project.localPath`. Caveats in
-  `docs/live-checkout-mode.md`.
-
-The dashboard tooling page does not yet surface this gap; that's plan
-item #8 ("Harness diagnostics" panel). Until then, run
-`minions doctor --harness` to get the per-runtime view of which dirs the
-engine actually surfaces, and check that flagged "missing" entries
-actually match the assets you expected to inherit.
-
-## `minions doctor --harness`
-
-One-shot CLI diagnostic that prints, per registered runtime, every dir
-or file the engine would surface to a spawned agent under its scope label.
-Implemented in `engine/preflight.js → runHarnessDoctor(minionsHome)` and
-wired into `bin/minions.js` and `engine/cli.js` as the `--harness` mode
-of the existing `minions doctor` command.
-
-### What it prints
-
-```
-Minions Harness Propagation
-  Runtime: claude
-    User asset dirs (--add-dir to agents):
-      ✓ /home/you/.claude                                [user]
-      ✓ /home/you/.agents                                [user]
-    Skill roots (CLI native discovery):
-      ✓ /home/you/.claude/skills                         [user]
-      ✓ /home/you/.agents/skills                         [user]
-      ⚠ /repo/.claude/skills                             [project:myrepo]   (missing on disk)
-      ✓ /repo/.agents/skills                             [project:myrepo]
-    Skill write targets (auto-extract destinations):
-      ✓ /home/you/.claude/skills                         [personal]
-      ✓ /repo/.claude/skills                             [project:myrepo]
-  Runtime: copilot
-    User asset dirs (--add-dir to agents):
-      ✓ /home/you/.copilot                               [user]
-      ✓ /home/you/.agents                                [user]
-    …
-  Worktree --add-dir snapshot (engine fleet default: copilot):
-    ✓ /home/you/.minions                                 [minions]
-    ✓ /home/you/.copilot                                 [user]
-    ✓ /home/you/.agents                                  [user]
-  All harness paths surveyed. Missing on-disk paths are warnings, not failures —
-  they're listed so you can decide whether to create the dir, populate it, or
-  ignore it for this host.
-```
-
-### Exit behavior
-
-The command exits **0 on a healthy host** even if some scoped paths do
-not exist on disk. The whole point is to surface "what would the engine
-attach today?" — a user that does not run Codex may legitimately have
-no `~/.codex` dir, and that is not a failure. Exits non-zero only on a
-true runtime/config error (e.g. registry refuses to resolve a known
-runtime, or `config.json` is unparseable).
-
-### When to run it
-
-- After installing a new skill / command / MCP and "it didn't take" on
-  the next dispatched agent — confirm Minions actually surfaces that dir
-  for the runtime you're dispatching with.
-- After changing `engine.defaultCli` — different runtimes have different
-  asset dirs; the `Worktree --add-dir snapshot` block reflects the fleet
-  default.
-- After re-cloning a repo with `<repo>/.claude/skills/` — the diagnostic
-  shows whether the project-scope path is on disk.
-- Before reporting "agent ignored my skill" — half the time the answer is
-  visible in the diagnostic output.
-
-It does **not** check whether the assets *load successfully* inside the
-CLI (no parse of `SKILL.md`, no MCP handshake). For loadability,
-inspect the dashboard tooling page or run an `ask` dispatch and watch
-the live output.
-
-## Adapter contract summary
-
-The runtime adapters answer these questions. The engine never special-cases
-a runtime by name — it only calls these methods on the resolved adapter.
-
-| Method | Signature | Used by |
-|--------|-----------|---------|
-| `getUserAssetDirs({ homeDir })` | → `string[]` | `engine/spawn-agent.js → computeAddDirs`; `runHarnessDoctor` |
-| `getSkillRoots({ homeDir, project? })` | → `[{ scope, dir, projectName? }]` | `engine/queries.js → collectSkillFiles`; `runHarnessDoctor` |
-| `getSkillWriteTargets({ homeDir, project? })` | → `{ personal, project? }` | `engine/lifecycle.js → extractSkillsFromOutput`; `runHarnessDoctor` |
-| `getCommandRoots({ homeDir, project? })` | → `[{ scope, dir, projectName? }]` | `engine/queries.js → collectCommandFiles` (via `getProjectHarnesses` for project scope); `runHarnessDoctor` |
-| `getMcpConfigPaths({ homeDir, project? })` | → `[{ scope, file, projectName? }]` | `runHarnessDoctor`; planned: `engine/queries.js → getStatusSlowStateMtimePaths` |
-
-`runHarnessDoctor` renders all five surfaces as "Slash commands" and "MCP
-config files" sections alongside the existing User asset dirs / Skill
-roots / Skill write targets blocks. Adapters that don't yet have a stable
-CLI contract for a surface (today: Codex for both commands and MCP,
-Copilot for project-scope commands) return `[]` so consumers can iterate
-runtimes generically without per-runtime branching.
-
-`engine/queries.js` exposes two shared helpers — `getUserHarnesses(homeDir)`
-and `getProjectHarnesses(project)` — that iterate every registered runtime
-via `engine/runtimes.listRuntimes()` + `resolveRuntime()` and union the
-`getSkillRoots` / `getCommandRoots` / `getMcpConfigPaths` contributions,
-deduped by absolute path. The same physical dir contributed by multiple
-adapters (e.g. `~/.agents/skills` exposed by Claude, Copilot, and Codex)
-surfaces once with a `runtimes: [name, ...]` provenance array. Use them
-from dashboard / diagnostics consumers instead of re-walking adapters by
-hand; `collectSkillFiles` / `collectCommandFiles` already do.
-
-> **Follow-up.** `getStatusSlowStateMtimePaths` still hardcodes the
-> per-runtime MCP file paths; refactoring it to consume
-> `getUserHarnesses(...).mcps` + `getProjectHarnesses(...).mcps` is
-> tracked separately so the slow-state mtime tracker automatically picks
-> up new adapters.
-
-## Related docs
-
-- `docs/runtime-adapters.md` — full adapter interface table.
-- `docs/live-checkout-mode.md` — `project.checkoutMode: 'live'`
-  contract (alternative to the worktree-add-dir story for repos where
-  worktrees are unworkable).
-- `docs/skills.md` — skill block format and auto-extraction targets.
-- `plans/seamless-user-repo-harness-invocation.md` — full multi-item plan
-  this doc is the foundation of.
-- `CLAUDE.md` → "Agent Spawn" + "Adapter Contract" — load-bearing
-  invariants the propagation contract piggy-backs on.
+`minions doctor --harness` and the dashboard Tools view show adapter-declared
+native locations as read-only inventory. They do not influence spawning and do
+not claim that a runtime loaded or used an asset.

package/docs/human-vs-automated.md

@@ -15,7 +15,7 @@
 | Metrics | Engine (auto-collect) | Engine | You (view) | — |
 | Error recovery | Engine (detect) | — | You (retry/delete) | You |
 | Project linking | You (`minions add/scan`) | — | — | — |
-| MCP servers / Skills / Commands | You (native CLI config) | Inherited by agents | — | — (opt-out via `hermeticHarness`) |
+| MCP servers / Skills / Commands | You (native CLI config) | Discovered natively by the selected runtime | — | — |
 
 ## The Two Human Gates