@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/qa-runbook-lifecycle.md

@@ -47,6 +47,34 @@ dashboard page renders a per-row Delete button conditionally (terminal
 only), confirms with the user, and surfaces success/error via
 `showToast()` rather than `alert()`.
 
+Success replies carry `deletedAs`: `terminal` for the normal path,
+`orphaned-pending` for the escape hatch below.
+
+#### Orphaned pending runs (`?orphaned=1`)
+
+Terminal-only deletion leaves one record class permanently stuck: a
+`pending` run written by a stray process that was never dispatched and owns
+nothing. `DELETE /api/qa/runs/<id>?orphaned=1` opts into removing it, but
+only when `engine/qa/runs.js#evaluateOrphanedPendingRun` can prove *every*
+one of these:
+
+- status is `pending` (a `running` run is never eligible);
+- `startedAt` and `completedAt` are unset and `artifacts` is empty;
+- `workItemId` is unset and no non-archived work item carries
+  `meta.qaRunId === <id>`;
+- no QA session carries `qaRunId === <id>`;
+- the record is at least `QA_ORPHAN_MIN_AGE_MS` old (24h), which covers the
+  window where a live dispatch is still back-filling its linkage;
+- `getRunbook(run.runbookId)` returns null **and**
+  `getManagedSpecByName(run.targetName)` returns null.
+
+Any unreadable ownership source fails closed (treated as *not* orphaned).
+A pending run that misses any condition returns
+`409 { error: 'not_orphaned', currentStatus, reason }`, where `reason` names
+the first failed condition (`too_recent`, `runbook_exists`, `session_owned`,
+…). `?orphaned=1` is additive only — it never relaxes the refusal for
+`running` runs or for ambiguously-owned pending runs.
+
 ## Artifact contract
 
 Artifacts live at `<MINIONS_DIR>/engine/qa-artifacts/<runId>/<path>`, served via
@@ -105,7 +133,7 @@ runner-native test file, and (with user approval) a second agent executes
 it. Sessions are a thin orchestration layer on top of the same
 `managed-spawn` + `qa-run-result.json` infrastructure that powers
 runbooks above — they reuse the SQL QA-run store, `engine/qa-artifacts/`, and
-the existing `engine/lifecycle.js#runPostCompletionHooks` qa-run sidecar
+the existing `engine/orchestration/lifecycle.js#runPostCompletionHooks` qa-run sidecar
 hook. Surfaced on `/qa` (sessions card list above the runbooks/runs
 tables) and proxied by the Command Center natural-language shortcut.
 
@@ -127,7 +155,7 @@ runbooks for repeat traffic.
 
 ## State machine
 
-Eight states, source of truth `engine/qa-sessions.js#QA_SESSION_STATE`:
+Eight states, source of truth `engine/qa/sessions.js#QA_SESSION_STATE`:
 
 ```
 pending ──▶ spawning ──▶ drafting ──▶ awaiting-approval ──▶ executing ──▶ done
@@ -168,9 +196,9 @@ routing default):
    **Multi-project fan-out (W-mpq6xqzj000606d0):** when `spec.projects`
    contains more than one project name, SETUP is fanned out — one work item
    per project, queued in parallel into each project's own
-   the target project's SQL work-item scope. The first project (`spec.projects[0]`) is the
-   **primary** (`meta.qaSession.primary === true`); the rest are
-   **co-services** (`primary === false`). Each WI's
+   the target project's SQL work-item scope. One project is the **primary**
+   (`meta.qaSession.primary === true`); the rest are **co-services**
+   (`primary === false`). Each WI's
    `meta.qaSession.coServices` lists the co-service project names (only the
    primary carries the full list; co-services see `[]`) and
    `meta.qaSession.primaryProject` carries the canonical primary name.
@@ -185,6 +213,35 @@ routing default):
    Single-project sessions skip `setupStatus` entirely (fast path uses
    `session.state` directly).
 
+   **Explicit primary + per-project targets (W-msb9kgs402813a97-a).** Which
+   project is primary and which target each project is checked out at are
+   **declared**, not positional:
+
+   - `spec.primaryProject: string` — must be a member of the resolved
+     `projects[]` (`validateSpec` rejects anything else with an error naming
+     the value and the known projects). Defaults to `projects[0]`.
+     `session.coServices` is then *every other* project, so a primary in the
+     middle of the list still fans the rest out correctly.
+   - `spec.projectTargets: { [projectName]: target }` — per-project target
+     overrides. Each key must be a member of `projects[]`, and each value is
+     validated by the same `_validateTarget` rules as `spec.target`. Each
+     SETUP WI is built with `spec.projectTargets[project] || spec.target`
+     (`meta.qaSession.target`, the prompt body, and the WI title all reflect
+     the per-project target), so a co-service is no longer forced onto the
+     primary's branch/PR/commit. DRAFT and EXECUTE inherit the primary's
+     target.
+
+   Both fields ride the normal request allowlist
+   (`engine/qa/process-validation.js#validateQaSessionRequest`), are ordered
+   and marked by the shared `orderTargetsByPrimary` seam in both project
+   resolvers (`dashboard.js#_qaSessionsResolveTargets` and
+   `engine/qa/prd-session.js#resolveTargetsFromConfig`), and are rewritten to
+   canonical project names by `canonicalizeResolvedProjects`. `queueSetup`
+   reorders the resolved targets so the declared primary leads, and throws
+   before `markSpawning` when project-bound targets cannot host it — a
+   contract disagreement surfaces as a 4xx instead of a session stranded in
+   `spawning`.
+
 2. **DRAFT** (`playbooks/qa-session-draft.md`) reads the live spawn
    metadata via `/api/managed-processes/by-name/qa-session-<id>`, calls the
    resolved runner's `generateBrief({target, flowsRaw, capture})` hook, and
@@ -192,7 +249,56 @@ routing default):
    the injected absolute `engine/qa-tests/<sessionId>/test.<ext>` path.
    The completion report's `testFile` value is stored on the session. In
    `confirm` mode the session parks at `awaiting-approval`; in `auto` mode
-   it auto-chains to EXECUTE.
+   it auto-chains to EXECUTE — but only after the visual-journey gate below
+   accepts the draft.
+
+### Visual-journey manifest + pre-EXECUTE gate (W-msb9kgs402813a97-b)
+
+`structuredCompletion.testFile` used to be DRAFT's only structured output, so
+an API-only test file passed straight through `handleDraftComplete` into
+EXECUTE: a session that asked for screenshots or video could reach a green
+`qa-run` having never opened a browser, and a multi-project session could
+ignore every co-service origin.
+
+`engine/qa/visual-journey.js` owns the fix. It is a **declaration** validated by
+the session layer, never a source-string scan of the drafted test file (a guess
+cannot be a gate).
+
+- **Sidecar.** DRAFT writes `agents/<agentId>/qa-session-draft-result.json`
+  (injected as the `{{qa_draft_result_sidecar}}` template var). The contract
+  mirrors `engine/qa/runs.js#prepareResultSidecar` / `#consumeResultSidecar`:
+  `engine.js#spawnAgent` clears stale content before a DRAFT dispatch (load-
+  bearing on the `editDraft` re-draft path, which reuses the session id), and
+  `engine/orchestration/lifecycle.js` does one atomic read-then-unlink on every
+  DRAFT completion — success or failure — so a manifest can never be inherited
+  by the next attempt. Missing / unreadable / malformed / session-id-mismatched
+  files return `{ ok: false, reason }`.
+- **Shape.** `{ sessionId, journeys: [{ id, name, kind: 'browser'|'api',
+  projects[], services[], origins[], steps[], assertions[],
+  evidence: { screenshots[], video[] } }] }`. Journey count, per-list length,
+  per-entry byte size, and the encoded manifest itself are all capped
+  (`visual-journey.js` `LIMITS`), so a runaway agent cannot inflate the session
+  record.
+- **Gate.** Enforced by `validateVisualJourneyManifest(session, manifest,
+  { services })` **only** when `session.spec.capture.video ||
+  session.spec.capture.screenshots` — a logs-only (or capture-less) session
+  keeps its historical pass-through behaviour. It rejects when: there is no
+  manifest at all; no journey has `kind: 'browser'` (an API-only draft cannot
+  produce visual evidence); some project in `session.spec.projects` appears in
+  no journey's `projects`; some name from
+  `managedSpawnNamesForSession(session)` appears in no journey's `services`; or
+  a requested capture type has no planned artifact of its extension
+  (`screenshots` ⇒ `.png`, `video` ⇒ `.webm`). Each rejection is a distinct,
+  actionable message naming the missing projects / services / evidence type.
+- **Placement.** The gate runs inside `handleDraftComplete` **before**
+  `markAwaitingApproval` and **before** the auto-mode EXECUTE queue, so a
+  rejected draft is neither parked for human approval nor chained into
+  EXECUTE. A rejection calls `markFailed` with
+  `failure_class: 'qa-session-draft-visual-coverage'` and the joined error; the
+  auto-path `qa-run` created moments earlier is terminalized as `errored`
+  rather than left pending. An accepted manifest is persisted as
+  `session.visualJourneyManifest` for the EXECUTE-side evidence check to
+  validate against.
 
 3. **EXECUTE** (`playbooks/qa-session-execute.md`) runs the drafted test
    against the live spawn via the runner's `executeBrief` hook, captures
@@ -200,34 +306,141 @@ routing default):
    the injected absolute `qa_result_sidecar` path — the same single-use sidecar
    the `qa-validate` runbook flow uses. Artifacts go to the injected absolute
    `qa_artifacts_dir` keyed by the linked QA run id, not the session id. The
-   `engine/lifecycle.js#runPostCompletionHooks` `meta.qaRunId` hook ingests
+   `engine/orchestration/lifecycle.js#runPostCompletionHooks` `meta.qaRunId` hook ingests
    the sidecar and marks the linked `qa-runs` record terminal; the
    session-level `handleExecuteComplete` then reads the `qa-run` terminal
    status and transitions `executing → done` (or `failed`).
 
+### EXECUTE evidence coverage (W-msb9kgs402813a97-c)
+
+A green `qa-run` is necessary but **not sufficient** for a session that asked
+for screenshots or video. Before this gate, `handleExecuteComplete` went to
+`done` on `qaRunStatus === 'passed'` with no evidence check at all, and
+`normalizeArtifact` accepted any `{type, path}` without touching the
+filesystem — so a run whose only green assertions were API calls closed a
+visual session, and a multi-project session could pass on evidence from a
+single project.
+
+- **Sidecar extension.** The `qa-run-result.json` contract gains
+  `journeyCoverage: [{ journeyId, status: 'passed'|'failed'|'skipped',
+  projects[], services[] }]` plus optional per-artifact `journeyId` and
+  `project`. `engine/qa/runs.js#normalizeJourneyCoverage` drops malformed
+  entries (unknown status, missing id, duplicates) rather than repairing them,
+  and `completeRun` stamps `run.journeyCoverage` **only** when the caller
+  supplied it, so legacy `qa-validate` runs keep their historical record shape.
+- **Validator.** `engine/qa/visual-journey.js#validateEvidenceCoverage({
+  session, manifest, run, artifactsDir })` returns
+  `{ ok, required, missing: { files, journeys, projects, services,
+  evidenceTypes }, errors, error }`. For each requested capture type it asserts
+  (a) at least one artifact of that type is registered on the run,
+  (b) every such artifact resolves **inside** `qaArtifactsDirForRun(runId)`
+  (`shared.isPathInside`) and exists on disk as a non-zero-size regular file,
+  and (c) the union of `journeyCoverage[].projects` over **passed** journeys
+  covers every `session.spec.projects`, the union of `.services` covers every
+  `managedSpawnNamesForSession(session)` name, and every journey the DRAFT
+  manifest declared actually reported `passed`.
+- **Manifest delivery.** Check (c) grades the run against journey ids the DRAFT
+  agent invented, so the EXECUTE prompt has to carry them: the DRAFT sidecar is
+  read-then-unlinked and the accepted manifest survives only on the session
+  record. `engine.js#buildQaExecuteJourneyContract(session)` projects
+  `session.visualJourneyManifest` into the sidecar's own coverage-entry shape
+  (`[{journeyId, name, kind, projects, services}]`) and
+  `_qaVisualJourneyManifestJson(item)` renders it as the
+  `{{visual_journey_manifest_json}}` template var consumed by
+  `playbooks/qa-session-execute.md`. It is EXECUTE-only (the manifest does not
+  exist before DRAFT produces it, and re-draft must not be shown the previous
+  attempt's ids), bounded independently of the DRAFT-side manifest caps, and
+  degrades to `''` for logs-only, legacy, and non-QA dispatches. Without it a
+  flawless visual run would always fail `qa-session-evidence-incomplete`.
+- **Gate.** Run inside `handleExecuteComplete` **before** DONE is chosen. A
+  coverage failure **overrides** a green `qaRunStatus`: the session transitions
+  to `failed` with `failure_class: 'qa-session-evidence-incomplete'` and an
+  `error` naming exactly what was missing. An already-failing run keeps its own
+  `qa-session-execute-failed` / `-errored` class — the gate only ever downgrades
+  a would-be `done`. It is skipped entirely when both capture flags are false
+  or no `visualJourneyManifest` is persisted (a legacy session), so non-visual
+  and pre-manifest completions are untouched. An internal error inside the gate
+  fails **closed**.
+
 Each phase WI carries `meta.sessionId`, `meta.sessionPhase`, `meta.qaSession`
 (target + flowsRaw + mode + capture + runner), and `meta.playbook`. The
 EXECUTE WI additionally carries `meta.qaRunId` so the existing qa-run
 lifecycle hook fires.
 
+### Co-service spawn metadata (W-msb9kgs402813a97-a)
+
+A multi-project session owns one managed-spawn per project, but DRAFT/EXECUTE
+historically only saw the PRIMARY one — a co-service origin was unaddressable
+from the drafted test. `engine.js#buildQaSessionServices` now iterates
+`qaSessions.managedSpawnNamesForSession(session)` and builds a bounded array
+(cap 8) of
+
+```json
+[{ "name": "qa-session-<id>-api", "project": "api", "primary": false,
+   "health": "healthy", "baseUrl": "http://localhost:4000", "ports": [4000] }]
+```
+
+`health` is `healthy` | `unhealthy` (alive, failing its healthcheck) | `down`
+(registered, not alive) | `missing` (no spec registered yet — the normal SETUP
+state). It is surfaced two ways:
+
+- as the `{{session_services_json}}` template var (registered in
+  `PLAYBOOK_OPTIONAL_VARS`, rendered by `playbooks/qa-session-draft.md` and
+  `playbooks/qa-session-execute.md` with prose stating each entry is a **real,
+  separately-reachable origin**, not a route on the primary), and
+- as `briefOpts.services` on the runner adapter `generateBrief()` /
+  `executeBrief()` calls, so an adapter can address a co-service directly.
+
+`managed_spawn_name` is unchanged and still names the **primary** spawn.
+Discovery never fails a render: an unreadable managed-process store degrades to
+`missing` rows and an empty string.
+
+### Who dispatches a phase (W-ms9nq2pu00cd60f3)
+
+`engine/qa/sessions.js` **persists** each phase work item and requests an
+engine wakeup (`control.json._wakeupAt`); it never enqueues a dispatch record
+of its own. The engine's normal work-discovery pass
+(`engine.js#discoverFromWorkItems` for project scopes,
+`#discoverCentralWorkItems` for central) builds the dispatch, and it is the
+only place that stamps `meta.project`, sets `meta.source` (which
+`lifecycle.js#resolveWorkItemScope` needs to route the completion back to the
+session), routes an agent, derives the branch, honours the branch mutex, and
+renders the phase playbook prompt.
+
+Phase work items are `WORK_TYPE.TEST`, which is in
+`shared.WORKTREE_REQUIRING_TYPES`, so their project association is
+load-bearing: `spawnAgent` resolves the worktree rootDir from it, and without
+one it falls back to MINIONS_DIR's parent — which collapses to a drive root on
+installs where MINIONS_DIR sits one level below it (`D:\squad-opg` → `D:\`) and
+fails non-retryably with `failure_class: worktree-preflight`. So
+`_persistWorkItem` **binds** `wi.project` to the SQL scope the item is stored
+in (a scope is `project.name` or the `central` sentinel) rather than trusting
+the builders' `opts.project || spec.project || null` fallback chain, and a
+project/scope disagreement throws instead of persisting an item the engine can
+never place. Central scope has no owning project to bind: a declared project
+there is preserved (that is how `discoverCentralWorkItems` still resolves a
+rootDir), and a genuinely project-less session stays project-less — the
+preflight is not masked.
+
 ## Endpoints
 
 Documented in `dashboard.js`; routes are visible at `GET /api/routes`.
 
 | Method | Path                                       | Behavior                                                                                                                  |
 |--------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
-| POST   | `/api/qa/session`                          | Create session; validates spec, calls `createSession` + `queueSetup` (`pending → spawning`). Body accepts `project: string` (single) OR `projects: string[]` (multi, ≤5; first is primary, rest are co-services). Returns `sessionId`, `setupWorkItemId` (primary's WI), `managedSpawnName`, and (multi only) `projects: string[]`. |
-| POST   | `/api/qa/from-prd`                         | "qa this PRD" bridge. Build a QA Session spec from a completed/approved PRD via `engine/qa-from-prd.js` (pure) then reuse `createSession` + `queueSetup`. Body: `{ prd, mode?, runner? }`. Non-ready / unknown / malformed PRD → **400** (`QaFromPrdError.reason`). Returns `sessionId`, `state`, `setupWorkItemId`, `managedSpawnName`, `projects`, `flowSource`, `warnings[]`, `note` (repo-native-harness copy), and optional `runnerHint`. The test is drafted on the repo's native test harness. |
-| GET    | `/api/qa/sessions`                         | List sessions newest-first. Optional `?limit=N` and `?state=pending\|spawning\|drafting\|awaiting-approval\|executing\|done\|failed\|killed`. |
+| POST   | `/api/qa/session`                          | Create session; validates spec, calls `createSession` + `queueSetup` (`pending → spawning`). Body accepts `project: string` (single) OR `projects: string[]` (multi, ≤5), plus the optional `primaryProject: string` (a member of `projects`; defaults to `projects[0]`) and `projectTargets: { [project]: target }` (per-project target overrides; each key a member of `projects`, each value validated like `target`). Returns `sessionId`, `setupWorkItemId` (primary's WI), `managedSpawnName`, and (multi only) `projects: string[]`, primary-first. |
+| POST   | `/api/qa/from-prd`                         | "qa this PRD" bridge. Build a QA Session spec from a completed/approved PRD via `engine/qa/from-prd.js` (pure) then reuse `createSession` + `queueSetup`. Body: `{ prd, mode?, runner? }`. Non-ready / unknown / malformed PRD → **400** (`QaFromPrdError.reason`). Returns `sessionId`, `state`, `setupWorkItemId`, `managedSpawnName`, `projects`, `flowSource`, `warnings[]`, `note` (repo-native-harness copy), and optional `runnerHint`. The test is drafted on the repo's native test harness. |
+| GET    | `/api/qa/sessions`                         | List sessions newest-first. Optional `?limit=N` and `?state=pending\|spawning\|drafting\|awaiting-approval\|executing\|done\|failed\|killed`. Each record carries a bounded `linkedRun` projection — `{ id, status, artifacts: [{type, path, label}] }` for a session with a `qaRunId` (primary image/video artifacts only, capped at `QA_PRIMARY_ARTIFACT_DEFAULT_MAX`), else `null`. Built from ONE `listRuns` read indexed by id, and fully try/catch'd: a deleted run or an unreadable runs store degrades to `linkedRun: null`, never a 500. |
 | GET    | `/api/qa/sessions/<id>`                    | Fetch a single session record by id.                                                                                      |
 | POST   | `/api/qa/sessions/<id>/approve`            | `awaiting-approval → executing`. Accepts no request body. Server-side creates the linked `qa-runs` record (synthetic `runbookId='qa-session-<id>'`), queues EXECUTE WI, stamps `qaRunId` on the session. |
 | POST   | `/api/qa/sessions/<id>/edit`               | `awaiting-approval → drafting`. Body: `{ feedback }`. Re-fires DRAFT with the reviewer feedback threaded into the prompt. |
 | POST   | `/api/qa/sessions/<id>/cancel`             | Non-terminal → `killed`. Optional `{ reason }`. Does NOT touch the managed-spawn — use `/kill` for that.                  |
 | POST   | `/api/qa/sessions/<id>/kill`               | Non-terminal → `killed`, then generation-safely removes the primary and every multi-project co-service managed-spawn. Best-effort when a spawn is absent or concurrently replaced. |
 | POST   | `/api/qa/sessions/<id>/dismiss`            | Non-terminal → `done`. Accept the draft as final; leaves spawn alive. Optional `{ summary }`.                              |
+| DELETE | `/api/qa/sessions/<id>`                    | Hard-delete a terminal session record (`done`/`failed`/`killed` only). Accepts no request body. Returns `{ ok: true, id, state, testDirRemoved, qaRun, managedSpawnsLive, managedSpawnsKnown }`. `409 not_terminal` (with `currentState`) for an in-flight session, `404 not_found` for unknown ids, `400` for an unsafe id. See "Deleting sessions". |
 | GET    | `/api/qa/runners`                          | List registered runner adapters (built-ins + `qa-runners.d/` plugins). Metadata only — hooks (functions) are stripped.    |
 | POST   | `/api/qa/runners/reload`                   | Accepts no request body. Clears the in-process registry, re-registers built-ins, re-scans `qa-runners.d/` for plugin edits, and returns the fresh runner list. |
-| DELETE | `/api/qa/runs/<id>`                        | Hard-delete a single QA run record (terminal-status runs only) and best-effort wipe its artifact directory under `engine/qa-artifacts/<runId>/`. Returns `{ ok: true, id, artifactsRemoved }` on success, `409 not_terminal` for in-flight runs, `404 not_found` for unknown ids. |
+| DELETE | `/api/qa/runs/<id>`                        | Hard-delete a single QA run record (terminal-status runs only) and best-effort wipe its artifact directory under `engine/qa-artifacts/<runId>/`. Returns `{ ok: true, id, artifactsRemoved, deletedAs }` on success, `409 not_terminal` for in-flight runs, `404 not_found` for unknown ids. `?orphaned=1` additionally removes a provably-orphaned abandoned pending run, or returns `409 not_orphaned` with the failed condition in `reason`. |
 
 The audited contracts returned by `GET /api/routes` expose the canonical enum,
 length, list, nested-field, path, and lifecycle constraints for these routes.
@@ -243,6 +456,38 @@ errors are mapped to HTTP via `_qaSessionsErrorToStatus`:
 - `'unsafe sessionId'` / `'invalid spec'` / `'requires …'` / `'exceeds …'` (spec or feedback validation) → 400
 - `'illegal state transition'` / `'requires state …'` / `'requires non-terminal'` → 409
 
+## Deleting sessions
+
+`DELETE /api/qa/sessions/<id>` (`engine/qa/sessions.js#deleteSession`) exists so
+an operator can clear failed/completed/killed rows out of the dashboard's
+"Recent Sessions" list without hand-editing `engine/state.db`. It is the session
+counterpart of `DELETE /api/qa/runs/<id>` and follows the same shape: the record
+is removed inside `shared.mutateQaSessions` (which emits the `qa_sessions` state
+event), and every filesystem / cross-store side effect runs outside the lock.
+
+**Terminal-only.** Only `done`, `failed`, and `killed` are deletable. Any other
+state returns `409 { error: 'not_terminal', currentState }` — cancel or kill the
+session first (`/cancel`, `/kill`), then delete. A refused delete touches no
+linked resource.
+
+**Linked resources** are cleaned up only where ownership is unambiguous:
+
+| Resource | Behavior |
+|----------|----------|
+| `engine/qa-tests/<id>/` | Removed. The directory is session-owned by construction (`createSession` creates it and the directory name *is* the session id), and removal repeats the `path.resolve` + prefix sandbox used for artifact directories, so only the per-session directory can be reclaimed — never the `qa-tests` root. Reported as `testDirRemoved`. |
+| `session.qaRunId` | Cascaded through `qaRuns.deleteQaRun` **only** when the run still exists and carries the synthetic `runbookId === 'qa-session-<id>'` stamped by `/approve` and the auto-mode chain. Otherwise left in place, with the reason reported in `qaRun.reason`: `no_linked_run`, `not_found` (already deleted), `not_session_owned` (a real runbook owns it), `not_terminal` (+ `currentStatus` — a live run is never vacuumed out from under its agent), `lookup_failed`, or `delete_failed`. `deleteQaRun`'s own terminal-only guard is the second line of defence. |
+| Managed-spawn processes | **Never killed.** A QA managed-spawn can outlive its session, so killing a live process as a side effect of deleting a history record would be a surprise. Live spawn names are reported in `managedSpawnsLive` (with `managedSpawnsKnown: false` when the managed-process store could not be read, so an empty list is not mistaken for "nothing live"); kill them deliberately via `POST /api/managed-processes/kill`. |
+| Work items | Untouched. The SETUP/DRAFT/EXECUTE work items are dispatch history and are not owned by the session record. |
+
+**Repeat and missing-link behavior is safe.** Deleting twice returns a plain
+`404 not_found`; a linked run that a previous call (or a manual
+`DELETE /api/qa/runs/<id>`) already removed reports
+`qaRun.reason: 'not_found'` instead of failing the request. Note that removing a
+session also removes the `session_owned` evidence
+`evaluateOrphanedPendingRun` consults, so a still-`pending` run left behind
+becomes eligible for the explicit `DELETE /api/qa/runs/<id>?orphaned=1` escape
+hatch once its other conditions hold.
+
 ## File locations
 
 - **Session state**: `engine/state.db` `qa_sessions` (all projects,
@@ -262,7 +507,7 @@ errors are mapped to HTTP via `_qaSessionsErrorToStatus`:
 
 ## Runner adapters (P-c4a9e7f3 / P-b8e1d4a6)
 
-Pluggable test-runner registry at `engine/qa-runners.js`. Built-in
+Pluggable test-runner registry at `engine/qa-runners/`. Built-in
 adapters: `playwright` (priority 50, always-true safe default),
 `maestro` (priority 80, detects `.maestro/` and therefore wins when
 present). Each adapter exports five hooks:
@@ -282,7 +527,7 @@ present). Each adapter exports five hooks:
 Resolution order in `detectRunner(target, project, explicitRunner)`:
 explicit-name (no `detect` call, unknown names return null), then
 priority-desc iteration. Plugin folder: `<MINIONS_DIR>/qa-runners.d/*.js`
-(same trust level as `playbooks/` and `watches.d/`). Hot-reload via
+(same trust level as `playbooks/` and `watch-plugins/`). Hot-reload via
 `POST /api/qa/runners/reload` (clears registry → re-registers built-ins →
 re-scans plugin dir) so plugin edits take effect without an engine
 restart.
@@ -290,7 +535,7 @@ restart.
 ## Fast-state slice
 
 `/api/status.qaSessions = { total, sig }` — the unsorted summary helper
-`engine/qa-sessions.js#summarizeSessionsForStatus()`. Mirrors `qaRuns` so
+`engine/qa/sessions.js#summarizeSessionsForStatus()`. Mirrors `qaRuns` so
 the sidebar activity-dot lights up on any new session or state
 transition within one `/api/status` poll cycle (~4s). Do NOT call
 `listSessions({limit:50})` from this hot path — it sorts O(N log N) on
@@ -310,6 +555,18 @@ every fast-state rebuild.
   chip classes (`--done` / `--active` / `--pending` / `--failed` /
   `--killed`) per `session.state`. State-driven left-border color
   (red=failed, green=done, yellow=awaiting-approval, blue=active).
+- **Linked run + evidence** (W-msb9kgs402813a97-d) — a card carrying a
+  `qaRunId` renders a `run:` chip in the meta row that scrolls the matching
+  Recent Runs row (`#qa-run-<id>`) into view, and a **terminal** card renders
+  the run's primary (image/video) artifacts through the same
+  `_qaRenderArtifactPreviews` helper the Recent Runs strip uses — so artifact
+  URLs always go through `/api/qa/artifacts/<runId>/<path>` and no filesystem
+  path is ever exposed. A terminal card whose run captured nothing says
+  "No screenshots or video captured for this run." rather than rendering
+  nothing: a session that captured plenty and one that captured nothing used
+  to be indistinguishable. The data comes from the bounded `linkedRun`
+  projection on `GET /api/qa/sessions` (see the endpoint table), not from the
+  Recent Runs poll, so card content does not depend on poll ordering.
 - **Action buttons** —
   `awaiting-approval` cards show `[Approve & run]` `[Edit]` `[Cancel]`;
   every non-terminal card shows `[Dismiss]` `[Kill spawn]` in the footer;
@@ -338,15 +595,36 @@ field gets the right audit trail.
 
 A completed/approved PRD can be QA'd in one shot — no hand-built spec. The
 bridge is `POST /api/qa/from-prd`, which turns the PRD into a QA Session
-spec via the **pure** spec-builder `engine/qa-from-prd.js`
+spec via the **pure** spec-builder `engine/qa/from-prd.js`
 (`buildQaSessionSpecFromPrd`) and then reuses the **exact same**
 orchestration as `POST /api/qa/session` (`createSession` + `queueSetup`,
 `pending → spawning`). No forked dispatch logic — the SETUP → DRAFT →
 EXECUTE chain above runs verbatim.
 
+That orchestration lives in **`engine/qa/prd-session.js`**
+(`createQaSessionFromPrd`), not in the HTTP handler, so the automatic
+post-verify path below creates identical sessions instead of forking the
+route. The handler keeps only what is genuinely HTTP-specific (body
+validation, header identity, status-code mapping, the runner hint). The one
+injected seam is `resolveTargets`: the dashboard runs each project name
+through its HTTP-input validator (bad project → 400 with an `ApiInputError`
+path), while the engine uses `resolveTargetsFromConfig`, which walks the same
+`shared.resolveProjectSource` seam against the live config.
+
+Both resolvers stamp the caller's `requested` name next to the canonical
+`project` and pipe the list through the shared
+`orderTargetsByPrimary(spec, targets)`, so a spec's `primaryProject` leads the
+resolved list and every entry carries a `primary` boolean. That lets
+`canonicalizeResolvedProjects` rewrite `primaryProject` and the
+`projectTargets` keys to canonical project names — without it, a PRD naming
+`"Web"` would produce `projects: ["web"]` alongside `primaryProject: "Web"` and
+`validateSpec` would reject a spec the caller wrote correctly.
+
 **Body:** `{ prd: "<file>.json", mode?, runner? }`. `prd` is a PRD filename
-resolved under `prd/`, then `prd/archive/` (traversal/absolute/drive-letter
-shapes are rejected). `mode` and `runner` are optional overrides.
+resolved against the SQL PRD store (live bucket, then the archive bucket),
+with a legacy `prd/` + `prd/archive/` filesystem fallback for pre-migration
+installs. Traversal / absolute / drive-letter shapes are rejected. `mode` and
+`runner` are optional overrides.
 
 **Completed/approved guard rail.** The builder rejects any PRD whose
 `status` is not in `{completed, approved}` (`QA_READY_STATUSES`) — drafting
@@ -407,6 +685,59 @@ alongside the usual `sessionId` / `state` / `setupWorkItemId` /
 Command Center exposes this as a natural-language shortcut — "qa this PRD"
 maps to `POST /api/qa/from-prd` (see `prompts/cc-system.md`).
 
+## Automatic QA for verified PRDs (`engine.autoQaCompletedPrds`, W-msal3ser01q4ccb3)
+
+`engine.autoQaCompletedPrds` (default **false**, Settings → Plan & PR
+Workflow → Plan) makes the engine start a PRD-driven QA Session by itself.
+Resolved through `shared.resolveAutoQaCompletedPrds(engine)`; only an explicit
+boolean counts, so a malformed `config.json` cannot silently enable an
+automatic dispatch. When OFF, behaviour is byte-identical to today and the
+manual endpoint above is unaffected either way.
+
+**Trigger — verification, not the status flip.** The hook lives in
+`engine/qa/auto-prd-qa.js#maybeAutoQaAfterVerify` and fires from
+`engine/orchestration/lifecycle.js#runPostCompletionHooks` on a **successful,
+non-skipped verify work item**. It deliberately does *not* key off the PRD's
+top-level `status: completed`: `checkPlanCompletion` sets that flag **before**
+creating the verify work item(s), so triggering there would race the verify
+agent and miss the canonical guide. All four gates must hold:
+
+1. `engine.autoQaCompletedPrds` is on.
+2. The completing work item is a `verify` type with a `sourcePlan`.
+3. `prd/guides/verify-<plan>.md` exists — the artifact that proves
+   verification ran to completion. Flow *priority* is untouched: the builder
+   still prefers the verify guide, then `manual-qa-<plan>.md`, then
+   acceptance criteria.
+4. **Every** verify work item for that plan (across all project scopes) is in
+   a `DONE_STATUSES` state. A cross-repo plan therefore waits for its whole
+   per-project fan-out and launches **one** coherent session — not one per
+   verify completion. Any `failed` / `cancelled` / still-pending sibling
+   blocks QA entirely.
+
+Automatic sessions use `mode: 'auto'` (SETUP → DRAFT → EXECUTE with no
+approval step — nobody is standing by to approve the draft) and
+`createdBy: 'engine:auto-qa-verified-prd'`. Their provenance carries an extra
+`autoTrigger: { reason: 'verified-prd', generation, verifyWorkItemIds[],
+triggeredBy, at }` block alongside the usual PRD provenance.
+
+**Idempotency — a durable verify generation, not an in-memory flag.** The
+dedupe key is `sha256(planFile + every verify WI's "id@completedAt")`,
+truncated to 16 chars. It is CLAIMED inside a `prdStore.mutatePrd` transaction
+(compare-and-set) before any session is created and stamped on the PRD row as
+`_autoQa.launches[]` (bounded to the last 5 entries), so it survives ticks,
+engine restarts, lifecycle retries, duplicate completion callbacks, and
+concurrent cross-repo completions landing in the same tick. `completedAt` is
+what makes a **reopened** PRD re-verifiable: `shared.reopenWorkItem` drops it,
+so the next successful completion produces a different generation and may
+legitimately launch a new session — while the *same* generation always
+collapses to exactly one.
+
+**Failure is bounded and never regresses the PRD.** A rejected launch records
+`status: 'error'` on the launch entry and **keeps** the claim; not releasing it
+is what stops a broken QA path from re-firing every tick. The hook never
+throws (every failure degrades to a warn), never writes PRD completion state,
+and QA failure stays visible in QA state only.
+
 ## When something goes wrong
 
 - **SETUP managed-spawn won't validate** → session lands in `failed` with
@@ -419,10 +750,29 @@ maps to `POST /api/qa/from-prd` (see `prompts/cc-system.md`).
   the injected
   `engine/qa-tests/<sessionId>/` directory. The session failure class is
   `qa-session-draft-failed` when the agent reports that contract failure.
+- **DRAFT succeeded but the session failed anyway** → `failure_class:
+  'qa-session-draft-visual-coverage'`. The session asked for screenshots or
+  video and the agent's visual-journey manifest
+  (`agents/<agentId>/qa-session-draft-result.json`, see
+  `engine/qa/visual-journey.js`) was missing, API-only, or did not cover every
+  project / managed-spawn / requested capture type. `session.error` names
+  exactly what is missing; POST `/api/qa/sessions/<id>/edit` is not available
+  (the session is terminal), so fix the flows/capture spec and create a new
+  session, or re-run DRAFT via a new session with the same target.
 - **EXECUTE qa-run terminal status is `failed`/`errored`** →
   `failure_class: 'qa-session-execute-failed'` /
   `'qa-session-execute-errored'`. The linked `qa-runs` record (joined via
   `session.qaRunId`) carries the agent's `summary` and artifact list.
+- **EXECUTE qa-run passed but the session failed anyway** → `failure_class:
+  'qa-session-evidence-incomplete'`. The session asked for screenshots or video
+  and `validateEvidenceCoverage` could not prove the evidence: a requested
+  capture type had no registered artifact, a registered artifact was missing /
+  zero-byte / outside `engine/qa-artifacts/<runId>/`, a project or managed-spawn
+  appeared in no **passed** `journeyCoverage` entry, or a journey the DRAFT
+  manifest declared never reported `passed`. `session.error` names exactly what
+  was missing; the linked run keeps its own `passed` status, so compare
+  `run.artifacts` + `run.journeyCoverage` against
+  `session.visualJourneyManifest` to see the gap.
 - **Want to start over after seeing a bad draft** → POST
   `/api/qa/sessions/<id>/edit` with `{ feedback: "…" }`; do NOT
   `/cancel` + create a new session unless the original spec was wrong

package/docs/qa-runbooks.md

@@ -16,7 +16,7 @@ scoped to a single project lives under its `projects/<name>/` state dir
 rather than a root-level `runbooks/` directory. Two reasons:
 
 1. **Lifecycle parity with the project.** When a project is removed via
-   `engine/projects.js removeProject`, its `projects/<name>/` dir is
+   `engine/planning/projects.js removeProject`, its `projects/<name>/` dir is
    archived as one unit. Co-locating runbooks under that dir means they
    travel with the project rather than dangling in a global `runbooks/`
    that has no relationship to the project being removed.
@@ -76,7 +76,7 @@ Responses:
 
 ## Module
 
-`engine/qa-runbooks.js` exports:
+`engine/qa/runbooks.js` exports:
 
 ```js
 {
@@ -99,7 +99,7 @@ unlink).
 
 The deferred follow-up items (W-mpeiwz6k0005bf34-b/c/d) have since landed. Brief pointers — see [CLAUDE.md](../CLAUDE.md) → "QA validation runs" for the deep dive:
 
-- **Run dispatch + persistence** (`engine/qa-runs.js`): `POST /api/qa/runbooks/run` creates a SQL QA-run record with `status ∈ pending|running|passed|failed|errored` and dispatches a `qa-validate` work item against the runbook's `targetName`. Read via `GET /api/qa/runs?limit=N&status=...` and `GET /api/qa/runs/<id>`.
+- **Run dispatch + persistence** (`engine/qa/runs.js`): `POST /api/qa/runbooks/run` creates a SQL QA-run record with `status ∈ pending|running|passed|failed|errored` and dispatches a `qa-validate` work item against the runbook's `targetName`. Read via `GET /api/qa/runs?limit=N&status=...` and `GET /api/qa/runs/<id>`.
 - **Artifact contract**: the engine pre-creates `engine/qa-artifacts/<runId>/`; the `qa-validate` agent writes files there and records run-root-relative paths in the injected absolute `agents/<id>/qa-run-result.json` path. The engine clears that sidecar before dispatch, verifies its `runId`, and removes it after consumption. Lifecycle persists the metadata, and `GET /api/qa/artifacts/<runId>/<path>` serves root-level or nested files behind traversal guards (403 on escape). There is no `engine.qaArtifactsMaxBytes` setting or copy-on-completion gate.
 - **UI**: `/qa` dashboard page (`dashboard/pages/qa.html`, `dashboard/js/qa.js`) polls `GET /api/qa/runs` every 5s while active; auto-detects screenshots/videos/logs for inline preview.
 - **Playbook**: `playbooks/qa-validate.md` (routed via the synthetic `qa-validate` task-type in `routing.md`).