@yemi33/minions 0.1.2424 → 0.1.2426

package/docs/README.md

@@ -9,7 +9,8 @@ Hands-on stories and distribution guides for people running or evaluating Minion
 - [blog-first-successful-dispatch.md](blog-first-successful-dispatch.md) — Narrative walkthrough of the first end-to-end agent dispatch and the seven failed spawn attempts that preceded it.
 - [architecture-review-2026-07-09.md](architecture-review-2026-07-09.md) — Architecture review covering engine orchestration, SQL/JSON state boundaries, runtime/process recovery, worktree lifecycle, pipelines/schedules, and prompt assembly, verified against `origin/main` at `b1b83dd2`.
 - [documentation-audit-2026-07-09.md](documentation-audit-2026-07-09.md) — Verified user-facing documentation audit covering runtime, CLI, storage, routing, and broken-link corrections.
-- [distribution.md](distribution.md) — How Minions is published (this repo: `@opg-microsoft/minions` to GitHub Packages; paired peer `@yemi33/minions` to npm) and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
+- [internal-install.md](internal-install.md) — **Start here to install.** One-command internal install/upgrade of `@opg-microsoft/minions` from the ISS `ProjectFeed-ISS` Azure Artifacts feed using the caller's `az` login: the ordered migration plan, consistent state backup, temporary-token handling, active-agent deferral, and idempotency.
+- [distribution.md](distribution.md) — How Minions is published: the internal `@opg-microsoft/minions` customer channel consumed from ISS `ProjectFeed-ISS`, the public/legacy `@yemi33/minions` npm channel, and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
 - [onboarding.md](onboarding.md) — Condensed first-30-minutes walkthrough for a new operator.
 - [tutorials/README.md](tutorials/README.md) — Progressive tutorial track from installation through advanced automation and operations.
 
@@ -18,7 +19,7 @@ Hands-on stories and distribution guides for people running or evaluating Minion
 - [tutorials/01-install-and-connect.md](tutorials/01-install-and-connect.md) — Install Minions, verify a runtime, link a project, and start the dashboard.
 - [tutorials/02-first-task.md](tutorials/02-first-task.md) — Dispatch and inspect a bounded first task.
 - [tutorials/03-plan-driven-feature.md](tutorials/03-plan-driven-feature.md) — Review, approve, execute, and verify a dependency-aware plan.
-- [tutorials/04-runtimes-and-harness.md](tutorials/04-runtimes-and-harness.md) — Select runtimes and verify project skill, command, and MCP propagation.
+- [tutorials/04-runtimes-and-harness.md](tutorials/04-runtimes-and-harness.md) — Select runtimes and verify native project skill, command, and MCP discovery.
 - [tutorials/05-schedules-and-watches.md](tutorials/05-schedules-and-watches.md) — Combine time-based schedules with state-based watches.
 - [tutorials/06-managed-services.md](tutorials/06-managed-services.md) — Leave an engine-owned development service running with health checks.
 - [tutorials/07-cross-repo-plan.md](tutorials/07-cross-repo-plan.md) — Coordinate one plan across multiple linked repositories.
@@ -28,6 +29,7 @@ Hands-on stories and distribution guides for people running or evaluating Minion
 
 Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
 
+- [api-errors.md](api-errors.md) — Dashboard API error contract: the stable `{error, code, field, …}` envelope, the 400/404/409/422/5xx status taxonomy, the safe (bounded + secret-redacted) rejected-value policy, alias/enum compatibility rules, and the self-correct-4xx / don't-blindly-retry-5xx behavior. Contracts are discoverable via `GET /api/routes` and the `engine/api-contracts` route-to-validation matrix.
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
 - [claude-md-propagation.md](claude-md-propagation.md) — Propagating repo-authored `CLAUDE.md` instructions to runtimes that don't auto-load it (Copilot/Codex): the `claudeMdNativeDiscovery` capability flag, the bounded nearest-applicable walk-up discovery, the `propagateClaudeMdForNonClaudeRuntimes` config knob, and why it's orthogonal to each runtime's native `AGENTS.md` discovery.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: configured-runtime sessions, resume semantics, system-prompt invalidation, and per-tab session storage.
@@ -51,7 +53,6 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [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`.
-- [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.
 - [managed-spawn.md](managed-spawn.md) — Engine-owned long-running services (managed-spawn primitive): sidecar schema, healthcheck examples, lifecycle, dashboard API, and the WI 1 (build) → WI 2 (test) chained-validation pattern.
@@ -65,13 +66,14 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [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.
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
 - [runtime-adapters.md](runtime-adapters.md) — Runtime adapter contract (`engine/runtimes/*`): how the engine talks to Claude Code, Copilot CLI, and future CLIs through a single capability-flagged interface.
-- [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop.
+- [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop, including structured review learning (durable, opt-in lessons from verified review findings).
 - [shared-lifecycle-module-map.md](shared-lifecycle-module-map.md) — Documentation-only module-boundary audit of `engine/shared.js` / `engine/lifecycle.js`: function inventory, cross-file call graph, and a proposed split map (no code moved).
 - [skills.md](skills.md) — Skill block format: how agents emit reusable `\`\`\`skill` blocks and how the engine extracts them into native personal-skill directories.
 - [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX design notes: simplified surface concepts driving the project picker, inline project link, and decoupled folder picker.
 - [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.
-- [team-memory.md](team-memory.md) — End-to-end hybrid memory system: file-backed inputs and consolidation, SQL/FTS5 records, retrieval and fallback, prompt bounds, episodic capture, security, APIs, and operations.
+- [team-memory.md](team-memory.md) — End-to-end hybrid memory system: file-backed inputs and consolidation, SQL/FTS5 records, retrieval and fallback, prompt bounds, episodic capture, the review-learning lifecycle (capture/recall/promotion/contradiction/diagnostics) and its staged rollout + rollback, security, APIs, and operations.
 - [timeouts-and-liveness.md](timeouts-and-liveness.md) — What kills (or doesn't kill) a live tracked agent: the wall-clock vs steering kill invariants, spawn-phase watchdog gates, steering safety nets, and stale-orphan detection ladder.
+- [visual-evidence-ci.md](visual-evidence-ci.md) — GitHub Actions before/after dashboard capture: path and label triggers, deterministic base/head fixtures, artifact/comment lifecycle, trust boundary, and local reproduction.
 - [watches.md](watches.md) — Persistent monitoring jobs: target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
 - [workspace-manifests.md](workspace-manifests.md) — Declarative per-agent permission scoping: `allowed_tools` / `allowed_repos` / `allowed_external_urls` / `memory_scope`, dispatch-time repo gate, and runtime `--allowedTools` narrowing.
 - [worktree-lifecycle.md](worktree-lifecycle.md) — Worktree pool recycling, the live-dispatch guard that prevents wiping an agent's unpushed work, the dirty/divergent quarantine path, and the Windows EPERM/EBUSY file-lock retry footgun.

package/docs/api-errors.md

@@ -0,0 +1,144 @@
+# Dashboard API errors, validation contracts, and safe retries
+
+The Minions dashboard (`dashboard.js`, port 7331) validates every request against
+a versioned route contract before it touches state. This document is the stable
+reference for the **error envelope**, the **status taxonomy**, the **safe
+rejected-value policy**, the **compatibility rules**, and the **retry /
+self-correction behavior** that callers — humans, agents, and Command Center —
+should rely on.
+
+The machine-readable source of truth is the route contract catalog in
+`engine/api-contracts/` (surfaced live at `GET /api/routes`). Never hard-code a
+route's accepted inputs from prose; discover them from the contract.
+
+## Discoverable contracts (`GET /api/routes`)
+
+`GET /api/routes` returns one entry per live route. Each entry carries the
+contract metadata built by `engine/api-contracts` — `owner`, `audit`,
+`request.{body,path,query,headers}` (each with a `policy` and typed `fields`),
+`request.aliases`, `request.constraints`, and `negativeTests`.
+
+- **`policy`** is one of `none`, `optional`, `required`. A closed release never
+  ships a `pending-audit` surface — the audited-route closure gate
+  (`assertAuditedRouteClosure`) rejects any route whose input surface has not
+  been described, and the dashboard refuses to boot if one slips through.
+- **`fields[].allowedValuesSource`** names the live source of a field's accepted
+  values (e.g. `config.projects[].name`, `shared.WORK_ITEM_PRIORITY_VALUES`,
+  `runtimes.listRuntimes()`). Prefer reading the source over guessing an enum.
+- **`negativeTests`** enumerate the rejection strategies with their expected
+  status, so you can predict a 400/404/409/422 before you send a bad request.
+
+The route-to-validation matrix (`engine/api-contracts` →
+`buildRouteValidationMatrix()`) derives, at call time, a row per route recording
+method/path, owner, accepted inputs, contract source, negative cases, status
+mapping, and side-effect assertion. Counts come from
+`summarizeRouteContracts()` and are never cached — a regressed route is visible
+immediately in the plan verification guide.
+
+## Stable error envelope
+
+Every rejected request returns a JSON body with a stable shape (built by
+`engine/api-validation.js#toApiErrorResponse` / `exposedEnvelope`):
+
+```json
+{
+  "error": "human-readable message (bounded to 500 chars)",
+  "code": "machine-stable-code",
+  "field": "offendingField",
+  "path": "body.nested.field",
+  "expected": "integer",
+  "rejectedValue": "<safely summarized>",
+  "allowedValues": ["...bounded list..."],
+  "min": 1,
+  "max": 6,
+  "minLength": 1,
+  "maxLength": 4096,
+  "details": [ { "code": "...", "message": "...", "field": "...", "path": "..." } ]
+}
+```
+
+- `error` and `code` are **always** present. `code` defaults to `invalid-input`
+  for 4xx validation failures.
+- The inline `field` / `path` / `expected` / `rejectedValue` / `allowedValues` /
+  bound keys mirror the **first** entry of `details`; `details` may list multiple
+  field-level failures (capped) for a single request.
+- Programmatic callers should branch on `code` (stable) and, when present,
+  `field` / `path`; treat `error` as display text only.
+
+## Status taxonomy
+
+| Status | Meaning | Caller action |
+|--------|---------|---------------|
+| `400 Bad Request` | Malformed/invalid input: wrong type, out-of-range, unknown enum, failed cross-field constraint, encoded path separator. | **Self-correctable.** Read `code`/`field`/`expected`/`allowedValues`, fix the payload, resend. |
+| `404 Not Found` | A well-formed identifier addresses no existing resource (unknown project, missing meeting/watch/lesson id). | **Self-correctable.** Use a valid id (discover via the relevant list endpoint). |
+| `409 Conflict` | The resource exists but is in the wrong state for the action (terminal meeting, duplicate follow-up, ambiguous `?source`). | Reconcile state or dedupe; do not blindly retry the identical request. |
+| `422 Unprocessable Entity` | The request is syntactically valid but semantically rejected as a whole (atomic settings candidate mixing valid + invalid fields, non-string routing content). | **Self-correctable.** Fix the flagged field(s) and resubmit the whole candidate. |
+| `5xx` | A dependency or the engine failed (`code: internal-error`), or a runtime/discovery dependency is unavailable (`503`). The body is deliberately generic and leaks no internal detail. | **Not self-correctable from the payload.** See retry policy below. |
+
+`4xx` bodies always use the exposed envelope. `5xx` bodies collapse to
+`{ "error": "Internal server error", "code": "internal-error" }` (or the
+route's typed `503` envelope) so internal error text and stack context never
+reach the client.
+
+## Safe rejected-value policy
+
+Echoing back the value that was rejected is convenient for debugging but is a
+data-exfiltration and log-poisoning risk. `engine/api-validation.js` enforces a
+uniform **safe rejected-value policy**:
+
+- **Strings** are bounded (default cap) before being echoed.
+- **Objects / arrays / buffers** are never echoed verbatim — they are summarized
+  to `{ type, keyCount }` / `{ type, length }`.
+- **Non-finite numbers, symbols, functions** are replaced with a bracketed tag.
+- **Secret-like fields and paths** (tokens, credentials, secret-shaped keys —
+  `isSecretLikePath`) suppress `rejectedValue` entirely and drop
+  `allowedValues`.
+- `allowedValues` is capped in count and each entry is bounded in length, so a
+  large dynamic source (project names, agent keys) can be advertised safely.
+
+Callers must not assume `rejectedValue` is a faithful round-trip of what they
+sent; it is a bounded, redacted summary for diagnosis only.
+
+## Compatibility rules
+
+- **Codes are stable; messages are not.** Match on `code` (and `field`/`path`).
+  Prose in `error` may be reworded without notice.
+- **Aliases are documented, not silent.** A route that accepts a legacy field
+  name declares it in `request.aliases` (`{ name, canonical }`, e.g.
+  `worktreeMode → checkoutMode`, `observe → contextOnly`). New code should send
+  the canonical field; the alias remains read-compatible.
+- **Additive fields.** New optional request fields and new response fields may be
+  added; unknown request fields are ignored unless a route's contract explicitly
+  rejects them. Do not depend on a field being absent.
+- **Priority and other enums come from one source.** Caller-controlled priority
+  boundaries validate against `shared.WORK_ITEM_PRIORITY_VALUES`
+  (`shared.validateWorkItemPriority`) — there is no duplicated allowed-values
+  list to drift. Enum surfaces advertise their `allowedValuesSource` instead of
+  freezing a copy.
+
+## Retry and self-correction behavior
+
+- **`4xx` (400/404/409/422): self-correct, do not retry blindly.** The failure is
+  in your request. Read `code`, `field`, `expected`, and `allowedValues`, fix the
+  payload, and resend once. Retrying the identical request will fail identically.
+- **`5xx` (including `503` dependency-unavailable): a dependency failed, not your
+  payload.** Do **not** immediately resend the same request in a tight loop —
+  that amplifies load on an already-failing dependency. If a retry is warranted,
+  back off (and prefer the engine's own retry/reconciliation paths for
+  state-changing operations, which are idempotency-aware). A `503` from model
+  discovery or a runtime dependency means the dependency is down, not that your
+  request was wrong.
+- **State-changing routes reject before side effects.** Every audited mutating
+  route validates the full request and returns its `4xx` before persisting
+  anything (see each route's `negativeTests` and the matrix's side-effect
+  assertion), so a rejected mutation leaves state untouched and is safe to
+  correct and resend.
+
+## See also
+
+- [command-center.md](command-center.md) — Command Center request/response
+  contract and the `X-CC-Turn-Id` correlation header.
+- [design-state-storage.md](design-state-storage.md) — where the state a mutating
+  route touches actually lives.
+- `engine/api-contracts/` — the contract catalog, coverage gate, and matrix
+  generator that back this document.

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-07-10 against `engine.js` `tickInner()` and `routing.md`.
+> Last verified: 2026-07-21 against `engine.js` `tickInner()`, `engine/shared.js`, and `routing.md`.
 
 How the minions engine finds work and dispatches agents automatically.
 
@@ -16,7 +16,8 @@ tick()
   1b. checkIdleThreshold()       Notify on excessive agent idleness
   1c. checkMeetingTimeouts()     Advance round-based meetings whose timer fired
   2.  consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
-  2.1 shouldAutoSweep() → spawnSweepRunnerDetached()  Periodic KB sweep (opt-in via engine.autoConsolidateMemory, 4h cadence)
+  2.05 bootstrapDefaultSchedules() Reconcile generated schedules once per engine process; while enabled, retry every tick until reconciliation succeeds
+  2.1 shouldAutoSweep() → spawnSweepRunnerDetached()  Periodic KB sweep (default-on via engine.autoConsolidateMemory, 4h cadence)
   2.5 runCleanup()               Periodic cleanup (every 60 ticks ≈ 10min)
   2.52 sweepKeepProcesses()      keep_processes TTL/dead-PID sweep (every 180 ticks)
   2.53 sweepManagedSpawn()       managed_spawn TTL/dead-PID/log-rotate sweep (every 180 ticks)
@@ -25,7 +26,7 @@ tick()
   2.6 pollPrStatus()             Poll ADO + GitHub for build, review, merge status (wall-clock cadence from prPollStatusEvery × tickInterval, default ≈ 12min)
        processPendingRebases()   Run any rebase work queued from the previous tick
        syncPrdFromPrs()          Backfill PRD item status from active PRs
-       checkPlanCompletion()     Mark plans completed when all features done/in-pr
+       checkPlanCompletion()     Mark plans completed when all features are terminal (done/failed/cancelled)
   2.7 pollPrHumanComments()      Poll PR threads for human comments (wall-clock cadence from prPollCommentsEvery × tickInterval, default ≈ 12min)
        reconcilePrs() (ADO+GH)   Reconciliation sweep (runs regardless of poll flags)
       reconcileSharedBranchPrs() Backfill the PR store for shared-branch plans whose aggregate remote PR is untracked/under-linked (runs unconditionally, like the other recovery sweeps)
@@ -42,11 +43,19 @@ tick()
 >
 > Dispatch of already-pending work runs before `discoverWork()`, not after (`engine.js` comment: "Process pending dispatches before discovery. discoverWork() runs pre-dispatch LLM validation for newly found work; a slow validator must not starve runnable entries that are already durable in dispatch.pending.").
 
+**Tick-overlap protection.** A hard timeout or five-minute lock force-release
+increments `tickGeneration`. Before worktree preparation, each pending item
+acquires a persisted `_spawnLeaseId` tied to that generation; leased pending
+rows count against `maxConcurrent`, and activation occurs only at runtime
+handoff. Worktree setup and quarantine repeatedly revalidate the lease, so an
+older tick aborts instead of spawning the same dispatch twice or quarantining a
+successor attempt's worktree.
+
 ## Work Discovery
 
-`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.
+`discoverWork()` iterates every project in `config.projects[]` and runs four core discovery sources: pull requests, per-project work items, central work items, and scheduled work. Results are prioritized: fixes > reviews > implements > work-items.
 
-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.
+Plans are materialized before the project scan; specs are materialized inside each project pass before its work-item scan. Both become project-scoped SQL work items consumed by Source 2 below.
 
 ### Source 1: Pull Requests (`discoverFromPrs`)
 
@@ -103,18 +112,7 @@ Composition with per-project gates: setting `workItemsDiscoveryEnabled: false` s
 
 Flip via Dashboard → Settings → Polling → "Granular work-discovery controls (P-d6f0a2b5)" collapsible, or set the keys directly in `config.engine`.
 
-### Source 2: PRD Gap Analysis (via `materializePlansAsWorkItems`)
-
-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:** SQL `prds` and `prd_items`.
-
-| Item State | Action | Dispatch Type |
-|------------|--------|---------------|
-| `status: "missing"` or `"updated"` | Queue implementation (re-opens any existing done WI) | `implement` |
-| `estimated_complexity: "large"` | Routes to `implement:large` (prefers Rebecca) | `implement:large` |
-
-### Source 3: Per-Project Work Items (`discoverFromWorkItems`)
+### Source 2: Per-Project Work Items (`discoverFromWorkItems`)
 
 **Reads:** the project's `work_items` SQL scope
 
@@ -124,7 +122,7 @@ PRD items flow through `materializePlansAsWorkItems()`, which queries SQL PRDs f
 
 After dispatching, the engine writes `status: "dispatched"` back to the item. The agent is scoped to the specific project directory.
 
-### Source 4: Central Work Items (`discoverCentralWorkItems`)
+### Source 3: Central Work Items (`discoverCentralWorkItems`)
 
 **Reads:** the central `work_items` SQL scope
 
@@ -162,14 +160,30 @@ 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)
+- CLI: `minions work "task title"` (defaults to central queue)
 - API: `POST /api/work-items` with no project
 
+### Source 4: Scheduled Work (`discoverScheduledWork`)
+
+**Reads:** `config.schedules[]` and persistent schedule-run state.
+
+Enabled schedules whose three-field cron expression matches the current minute produce work through `engine/scheduler.js`. Ordinary tasks and tri-agent harness missions are written to the central SQL work-item scope with `_scheduleId` metadata; meeting schedules create meeting records directly. The persisted `lastRun` value prevents a schedule from firing twice in the same calendar minute.
+
+`engine.bootstrapDefaultSchedules` defaults to `true` and is configurable under
+Dashboard → Settings → Workflow Defaults. `engine/schedule-bootstrap.js`
+idempotently creates a read-only per-project git-fetch schedule (title-derived
+`keep-branch-fresh-git-fetch-origin-…` id, `0 */12 *`, `explore`) and one shared
+`harness-sweep-all-projects` schedule (`0 6 *`, `explore`, low priority).
+Project creation applies the bootstrap in the same config lock; engine startup
+reconciles older installs once. Existing operator customizations stay intact,
+and only generated project schedules tagged during removal are re-enabled on
+relink.
+
 ### Materialization: Specs and Plans → Work Items
 
-Before the 3 core sources run, the engine materializes indirect sources into work items:
+Before the four core sources run, the engine materializes indirect sources into work items:
 
-**Specs** (`materializeSpecsAsWorkItems`): When a PR merges that added/modified `.md` files under `docs/` (configurable via `workSources.specs.filePatterns`), the engine reads each doc and checks for `type: spec` in its frontmatter. Only docs with this marker are treated as actionable specs — regular documentation is ignored. For matching docs, it extracts title/summary/priority and creates implementation work items with `createdBy: 'engine:spec-discovery'`. State tracked in `.minions/spec-tracker.json` to avoid re-processing merged PRs.
+**Specs** (`materializeSpecsAsWorkItems`): When a PR merges that added/modified `.md` files under `docs/` (configurable via `workSources.specs.filePatterns`), the engine reads each doc and checks for `type: spec` in its frontmatter. Only docs with this marker are treated as actionable specs — regular documentation is ignored. For matching docs, it extracts title/summary/priority and creates implementation work items with `createdBy: 'engine:spec-discovery'`. State is tracked in `projects/<name>/spec-tracker.json` to avoid re-processing merged PRs.
 
 Example spec frontmatter:
 ```markdown
@@ -184,7 +198,7 @@ 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 the SQL work-item store 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 2 on the same or next tick.
 
 ## PR Status Polling (`pollPrStatus`)
 
@@ -223,7 +237,7 @@ Item found
   │
   ├─ isOnCooldown(key)?         → skip if dispatched within cooldown window
   │    Default: 30min for PRD/PRs, 0 for work-items
-  │    Cooldowns are in-memory (reset on engine restart)
+  │    Cooldowns are persisted in SQLite and survive engine restart
   │
   └─ resolveAgent(workType)?    → skip if no idle agent available
        Checks routing.md: preferred → fallback → any idle agent
@@ -239,6 +253,7 @@ routing.md table (see the file for the authoritative list):
   implement:large → rebecca (fallback: dallas)
   review          → ripley  (fallback: lambert)
   fix             → _author_ (fallback: _any_)    ← routes to PR author, any idle as fallback
+  build-fix-complex → _author_ (fallback: dallas)
   plan            → ripley  (fallback: rebecca)
   plan-to-prd     → lambert (fallback: rebecca)
   explore         → ripley  (fallback: rebecca)
@@ -250,6 +265,9 @@ routing.md table (see the file for the authoritative list):
   docs            → lambert (fallback: _any_)
   setup           → dallas  (fallback: _any_)
   qa-validate     → dallas  (fallback: ralph)
+  qa-session-setup   → dallas (fallback: ralph)
+  qa-session-draft   → dallas (fallback: ralph)
+  qa-session-execute → dallas (fallback: ralph)
 ```
 
 Resolution order:
@@ -287,17 +305,24 @@ When an item is dispatched:
 meta.project.localPath → rootDir (the repo on disk)
 ```
 
-### 2. Create Git Worktree (if task has a branch)
-```
-git worktree add <rootDir>/../worktrees/<branch> -b <branch> <mainBranch>
-```
-- Branch names are sanitized (alphanumeric, dots, hyphens, slashes only, max 200 chars)
-- If worktree fails for implement/fix → item marked as error, moved to completed
-- If worktree fails for review/explore/ask → falls back to rootDir (read-only tasks)
+### 2. Resolve the Checkout
+
+`shared.resolveSpawnPaths()` owns placement:
+
+- In worktree mode, every project-bound dispatch gets an engine-owned worktree.
+  Branch-bearing work uses its target branch; branchless/read-only work uses a
+  detached worktree. The engine never falls back to `project.localPath`.
+- New worktrees require a freshly fetched `origin/<mainRef>` base. If the fetch
+  or remote ref cannot be verified, allocation fails instead of branching from
+  a stale local base.
+- Live/hybrid validation work runs in `project.localPath` only when
+  `resolveCheckoutMode(project, type)` selects live mode.
+- Project-less read-only work starts in `MINIONS_DIR`.
+- A validated relative `meta.workdir` is applied beneath the selected base.
 
 ### 3. Render Playbook
 ```
-playbooks/<type>.md  →  substitute {{variables}}  →  append notes.md  →  append learnings requirement
+playbooks/<type>.md → substitute {{variables}} → inject shared rules/context appendices
 ```
 
 Variables injected from config and item metadata:
@@ -307,28 +332,23 @@ Variables injected from config and item metadata:
 - `{{team_root}}` — path to central `.minions/` directory
 
 ### 4. Build System Prompt
-Combines:
-- Agent identity (name, role, skills)
-- Agent charter (`agents/<name>/charter.md`)
-- Project context (repo name, repo host config, main branch)
-- Critical rules (worktrees, MCP tools, PowerShell, learnings)
-- Full `notes.md` content
-
-### 5. Spawn Claude CLI
-```bash
-claude -p --system-prompt-file <sysprompt-file> \
-  --output-format stream-json --max-turns 100 --verbose \
-  --dangerously-skip-permissions
-# Prompt text is piped via stdin (not passed as an arg).
-# Agent dispatches route through engine/spawn-agent.js; CC / doc-chat use a direct
-# spawn path in engine/llm.js that bypasses spawn-agent.js entirely.
-# Permission bypass is runtime-owned: Copilot uses
-# --autopilot --allow-all --no-ask-user instead.
-```
+Combines agent identity, project context, safety rules, pinned context, and
+memory. With `memoryRetrieval` enabled, a bounded task-relevant evidence pack
+replaces broad team/personal notes; otherwise bounded `notes.md` and personal
+memory are used. Human/LLM-authored appendices are wrapped as untrusted input.
+
+### 5. Resolve and Spawn the Runtime
+
+The engine resolves `resolveRuntime(resolveAgentCli(...))`; the selected adapter
+owns binary discovery, argv, prompt delivery, workspace preparation, and output
+parsing. Cold agent dispatches use the runtime-neutral
+`engine/spawn-agent.js`; opt-in Copilot fleet dispatch can use the ACP worker
+pool. CC/doc-chat use direct `engine/llm.js` calls.
 
-- Process runs in the worktree directory (or rootDir for reviews)
+- Process runs in the resolved worktree/live checkout (or `MINIONS_DIR` for
+  project-less read-only work)
 - stdout/stderr captured (capped at 1MB each)
-- CLAUDECODE env vars stripped to allow nested sessions
+- runtime-specific environment cleanup stays inside the adapter/spawn wrapper
 
 ### 6. Track State
 - Agent status derived from SQL dispatch state
@@ -337,12 +357,12 @@ claude -p --system-prompt-file <sysprompt-file> \
 
 ## Post-Completion
 
-When the claude process exits:
+When the selected runtime exits:
 
 ```
 proc.on('close')
   │
-  ├─ Save output to agents/<name>/output.log
+  ├─ Save output to agents/<id>/output.log
   │
   ├─ Dispatch completion determines visible agent status ("done"/"error")
   │
@@ -351,9 +371,10 @@ proc.on('close')
   ├─ Sync PRs from output (scan for PR URLs → SQL PR store)
   │
   ├─ Post-completion hooks:
-  │    review     → update PR minionsReview in SQL, vote on ADO
-  │    fix        → set PR minionsReview back to "waiting"
-  │    build-test → record verification result and findings
+  │    review      → update PR minionsReview in SQL; platform vote only when autoApplyReviewVote is enabled
+  │    fix         → set PR minionsReview back to "waiting"
+  │    test/verify → record validation result and findings
+  │    qa-*        → terminalize linked QA run/session state
   │
   ├─ Check for learnings in notes/inbox/
   │    (warns if agent didn't write findings)
@@ -411,9 +432,9 @@ ADO + GitHub REST ── pollPrStatus() ──► SQL PR rows│
                                     │
                                     ▼
                               notes.md
-                              (injected into
-                               all future
-                               playbooks)
+                              (fallback memory
+                               when active retrieval
+                               has no evidence pack)
 ```
 
 ## Timeout & Stale-Orphan Detection
@@ -452,7 +473,7 @@ All discovery behavior is controlled via `config.json`:
     "maxConcurrent": 5,          // max agents running at once
     "agentTimeout": 18000000,     // 5 hours — hard runtime limit
     "heartbeatTimeout": 300000,  // 5min — stale-orphan grace after process tracking is lost
-    "maxTurns": 100,             // max claude CLI turns per agent
+    "maxTurns": 100,             // max runtime turns per agent
     "worktreeCreateTimeout": 300000, // timeout for git worktree add on large repos
     "worktreeCreateRetries": 1   // retry count for transient add failures
   },
@@ -475,4 +496,5 @@ All discovery behavior is controlled via `config.json`:
 }
 ```
 
-To disable a work source for a project, set `"enabled": false`. To change where the engine looks for PRD or PR files, change the `path` field (resolved relative to `localPath`).
+To disable a work source for a project, set `"enabled": false`. PR and PRD runtime
+state is SQL-backed; there is no JSON path override for those stores.