@yemi33/minions 0.1.2423 → 0.1.2425

package/docs/copilot-cli-schema.md

@@ -16,7 +16,7 @@
 | `capabilities.promptViaArg` | **`false`** | Stdin works in non-interactive mode and dodges the Windows ARG_MAX (~32 KB) limit that breaks `-p "<long-prompt>"` outright (`CreateProcess` rejects it before Copilot even starts). |
 | `capabilities.modelDiscovery` | **`true`** | `GET https://api.githubcopilot.com/models` with a `gh auth token` Bearer returns HTTP 200 + a 24-model JSON catalog. |
 | `capabilities.streaming` | **`true`** | `--stream on` (default) emits `assistant.message_delta` events incrementally; `--stream off` suppresses deltas but the final `assistant.message` always arrives. |
-| `capabilities.sessionResume` | **`true`** | `--resume <session-id>` documented, and every `result` event emits `sessionId`. |
+| `capabilities.sessionResume` | **`true`** | `--resume=<session-id>` resumes a session, and every `result` event emits `sessionId`. |
 | `capabilities.midRunSessionId` | **`false`** | Copilot exposes the resumable session id only on the terminal `result`, so mid-run steering waits for a checkpoint. |
 | `capabilities.resumePromptCarryover` | **`true`** | Command Center resume turns should prepend the browser's recent Q&A transcript because Copilot's session store is opaque to Minions and can resume without enough conversational context. |
 | `capabilities.systemPromptFile` | **`false`** | No `--system-prompt-file` flag exists. Inject system prompt via a `<system>` block prepended to stdin. |
@@ -142,20 +142,24 @@ prompt (system block prepended) via stdin. This:
   The `@<path>` prefix syntax is only documented for `--additional-mcp-config`,
   not `--prompt`.
 
-### `buildPrompt(promptText, sysPromptText)` — recommended impl
+### `buildPrompt(promptText, sysPromptText, opts)` — recommended impl
 
 Copilot has no `--system-prompt-file`. Inject the system prompt as a `<system>`
 block prepended to the user prompt, mirroring the convention used by
 [Anthropic's tool-use docs](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use):
 
 ```js
-function buildPrompt(promptText, sysPromptText) {
+function buildPrompt(promptText, sysPromptText, opts = {}) {
   const user = promptText == null ? '' : String(promptText);
-  if (!sysPromptText) return user;
-  return `<system>\n${sysPromptText}\n</system>\n\n${user}`;
+  if (opts.sessionId) return user;
+  if (sysPromptText == null || sysPromptText === '') return user;
+  return `<system>\n${String(sysPromptText)}\n</system>\n\n${user}`;
 }
 ```
 
+Resumed sessions already carry their original system context, so replaying the
+block would duplicate instructions on every turn.
+
 Copilot's native custom-instruction discovery remains enabled, so repository
 instructions augment the Minions task prompt as they do in normal CLI usage.
 
@@ -174,16 +178,16 @@ Empirically confirmed flags for non-interactive Copilot invocations:
 | `--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. |
 | `--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. |
+| `--no-color` | always emitted | Keeps any incidental CLI rendering free of ANSI color. |
+| `--plain-diff` | always emitted | Keeps incidental diff rendering plain even though normal output is JSONL. |
 | `--max-autopilot-continues N` | optional | Maps from `opts.maxTurns`. |
 | `--effort <level>` | optional | Choices: `low|medium|high|xhigh`. **No `max`** — adapter must map `'max' → 'xhigh'`. |
 | `--model <id>` | optional | Full model ID (see §6 for the catalog). |
-| `--resume=<session-id>` | optional | Maps from `opts.sessionId`. Note the `=` syntax — `--resume <id>` is also accepted but `--resume` standalone enters interactive picker. |
+| `--resume=<session-id>` | optional | Maps from `opts.sessionId`. The `=` form is required; a separated value is parsed as a positional argument. |
 | `--stream on` / `--stream off` | optional | Default is `on`. See §4. |
 | `--enable-reasoning-summaries` | optional | Maps from `opts.reasoningSummaries`; only Anthropic models populate `assistant.reasoning_delta`. |
 | `--add-dir <path>` | adapter-supported, normally omitted | Registers extra read-allowed dirs when `opts.addDirs` is supplied. Normal Minions dispatch leaves this empty and relies on Copilot's native cwd/user-config discovery. |
-| `--attachment <path>` | injected for image inputs | Passes an image file to the model. Repeatable. The adapter writes each base64 image payload to a temp file, emits one `--attachment` per file, and deletes temps after spawn (W-mqv7324u0021db5d). Gated by `capabilities.imageInput`. |
+| `--attachment <path>` | injected for image inputs | Passes an image file to the model. Repeatable. The adapter writes each base64 image payload inside the call-scoped temp directory and emits one `--attachment` per file; `engine/llm.js` removes the directory after the process settles. Gated by `capabilities.imageInput`. |
 | `-v` / `--verbose` | **never emit** | Does not exist on Copilot. The Claude adapter emits `--verbose`; the Copilot adapter MUST NOT. |
 
 ### 3.1 `--autopilot` vs single-shot
@@ -268,10 +272,11 @@ Captured against three model invocations:
 | `assistant.message` | ✓ | ✓ | ✓ | no | Authoritative final assistant content for the turn. |
 | `tool.execution_start` | ✓ | ✓ | ✓ | no | Tool call begin. `data.toolName`, `data.arguments`. |
 | `tool.execution_complete` | ✓ | ✓ | ✓ | no | Tool call end. `data.success: bool`, `data.result.{content, detailedContent}`. |
-| `result` | ✓ | ✓ | ✓ | no | Final aggregate. `data.usage`, `sessionId`, `exitCode`. |
+| `result` | ✓ | ✓ | ✓ | no | Final aggregate. Top-level `usage`, `sessionId`, and `exitCode`. |
 | `function` | (in stdin-no-`-p` test) | – | – | no | Observed once in an early stdin test; appears to be a meta event for tool invocation. **Treat as ignorable** unless future spike re-confirms its semantics. |
 
-All events share the envelope `{ type, data, id, timestamp, parentId, ephemeral? }`.
+Most events share the envelope `{ type, data, id, timestamp, parentId, ephemeral? }`;
+the terminal `result` keeps `usage`, `sessionId`, and `exitCode` at the top level.
 `ephemeral: true` marks events that the Copilot UI hides from the persistent
 session log (e.g., deltas, MCP loading noise). The parser should ignore the
 `ephemeral` flag — it's a UI hint, not a parser hint.
@@ -597,13 +602,14 @@ When implementing `engine/runtimes/copilot.js`:
    - Recognize npm shims returned by PATH and resolve the package's JavaScript
      entry; no separate npm-prefix scan is needed.
 3. `buildArgs(opts)` always emits:
-   `--output-format json -s --allow-all --no-ask-user --autopilot --log-level error`
+   `--output-format json -s --no-color --plain-diff --allow-all --no-ask-user --autopilot --log-level error`
    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
-   non-empty; passthrough otherwise (§2).
+4. `buildPrompt()` injects `<system>...</system>\n\n` when sysprompt is
+   non-empty on a fresh call; a resumed call (`opts.sessionId`) passes through
+   only the new user prompt (§2).
 5. `resolveModel()` translates Minions internal aliases before the CLI boundary:
    `'haiku'` → `'claude-haiku-4.5'`, `'sonnet'` → `'claude-sonnet-4.5'`, and
    `'opus'` → `'claude-opus-4.5'`. All other model IDs pass through unchanged.
@@ -646,16 +652,20 @@ When the spike's findings disagree with the plan text, **this document wins**
 `capabilities.imageInput: true`. The Copilot CLI accepts image files via
 `--attachment <path>` (the flag is repeatable). The adapter's `buildArgs(opts)`
 materializes each base64 payload from `opts.images` to a temp file in
-`opts.tmpDir`, appends `--attachment <path>` per file, and arranges cleanup after
-`spawn` returns.
+`opts.tmpDir` and appends `--attachment <path>` per file. `engine/llm.js`
+removes that call-scoped directory after the process settles.
 
 ```js
-// Simplified adapter flow (see engine/runtimes/copilot.js _buildAttachmentArgs)
-for (const img of opts.images ?? []) {
-  const ext = MIME_TO_EXT[img.mimeType] ?? 'bin';
-  const filePath = path.join(opts.tmpDir, `attachment-${i}.${ext}`);
-  fs.writeFileSync(filePath, Buffer.from(img.dataBase64, 'base64'));
-  args.push('--attachment', filePath);
+// Simplified buildArgs flow (see engine/runtimes/copilot.js)
+if (Array.isArray(opts.images) && opts.tmpDir) {
+  for (let i = 0; i < opts.images.length; i++) {
+    const img = opts.images[i];
+    if (!img?.dataBase64) continue;
+    const ext = _mimeToExt(img.mimeType);
+    const filePath = path.join(opts.tmpDir, `img-${i}-${Date.now().toString(36)}.${ext}`);
+    fs.writeFileSync(filePath, Buffer.from(img.dataBase64, 'base64'));
+    args.push('--attachment', filePath);
+  }
 }
 ```
 

package/docs/cross-repo-plans.md

@@ -2,7 +2,7 @@
 
 > A cross-repo plan is a single Minions plan whose work items ship into **two or more configured projects**. The plan has no owning project; each `missing_features` item declares its own `project`, the materializer fans items into per-project SQL scopes, and verify completion fans out into one verify work item per touched repo.
 >
-> Shipped by `PL-cross-repo-coordination` (`prd/minions-opg-2026-06-10-3.json`, items `P-7a3f1c08` … `P-8b5d3e07`). Default plan shape is unchanged for single-project plans — everything in this doc only activates when the plan markdown declares more than one project.
+> Shipped by `PL-cross-repo-coordination` (items `P-7a3f1c08` … `P-8b5d3e07`). Default plan shape is unchanged for single-project plans — everything in this doc only activates when the plan markdown declares more than one project.
 
 ## When to use a cross-repo plan
 
@@ -34,13 +34,13 @@ A cross-repo plan is detected by a single signal at parse time: `shared.extractP
 **Projects:** minions, minions-opg
 ```
 
-Both forms accept `,`, `|`, or `;` as separators with surrounding whitespace, and strip surrounding quotes. See `engine/shared.js#extractPlanTargetProjects` (line ~3713) for the exact regex.
+Both forms accept `,`, `|`, or `;` as separators with surrounding whitespace, and strip surrounding quotes. See `engine/shared.js:4516-4559` (`extractPlanDeclaredProject` / `extractPlanTargetProjects`) for the exact regexes.
 
 The dashboard's Create-Plan modal (P-b51c08af) renders a multi-select project picker. Submitting two or more projects normalizes to a deduped array and `POST /api/plans/create` writes the plan with the plural `**Projects:**` header + HTML comment marker, no singular `**Project:**` line. Selecting zero or one project keeps the legacy singular header (no behavioural change for single-project plans).
 
 ### 2. Plan-to-prd dispatch
 
-When the central planner picks up a plan-to-prd work item, `engine.js#discoverCentralWorkItems` (~line 7470) parses both project signals from the plan content and sets `vars.target_projects` on the dispatch when the plan is cross-repo. The `plan-to-prd.md` playbook (P-3b8c40d9) injects a `{{target_projects}}` section that:
+When the central planner picks up a plan-to-prd work item, `engine.js#discoverCentralWorkItems` (`engine.js:10180-10506`) parses both project signals from the plan content and sets `vars.target_projects` on the dispatch when the plan is cross-repo. The `plan-to-prd.md` playbook (P-3b8c40d9) injects a `{{target_projects}}` section that:
 
 - Tells the agent to **omit the top-level `"project"` field** on the PRD JSON (or set it to `""`).
 - Requires **every `missing_features` item to carry an explicit `project`** chosen from the target list.
@@ -92,13 +92,13 @@ The materializer uses one transaction per project scope (`mutateWorkItems(projec
 
 ## Cycle detection (runs ONCE over the whole plan)
 
-`detectDependencyCycles(plan.missing_features)` (`engine.js:4638`) runs once over the full PRD `missing_features` set **before** the per-project grouping loop, so a cyclic chain that crosses repos (e.g. `P-aaa1` in `minions` → `P-bbb2` in `minions-opg` → `P-aaa1`) is detected and every cyclic item is skipped at materialization time — neither project's scope receives the cyclic items.
+`detectDependencyCycles(plan.missing_features)` (`engine.js:7084-7097`, called at `engine.js:7557-7564`) runs once over the full PRD `missing_features` set **before** the per-project materialization loop, so a cyclic chain that crosses repos (e.g. `P-aaa1` in `minions` → `P-bbb2` in `minions-opg` → `P-aaa1`) is detected and every reported cyclic item is skipped at materialization time — neither project's scope receives those items.
 
 Caveat: `detectDependencyCycles` is a partial DFS — 2-cycles (`A → B → A`) are fully detected, but N-cycles ≥ 3 with distinct nodes only flag the back-edge target and recursing parent. Both legs of a 2-cycle and the canonical back-edge of a longer cycle reliably get skipped. Fixing the partial detector is tracked separately; cross-repo plans inherit the same behaviour as single-project plans.
 
 ## Cross-repo `depends_on` (advisory merge)
 
-`item.depends_on` may freely reference a work-item id that lives in another project. The dispatcher in `engine.js#spawnAgent` (~line 2498) partitions resolved dep branches into two buckets via `dep.isCrossRepo`:
+`item.depends_on` may freely reference a work-item id that lives in another project. The dispatcher in `engine.js#spawnAgent` (`engine.js:4457-4658`) partitions resolved dep branches into two buckets via `dep.isCrossRepo`:
 
 1. **Same-project deps** — fetched into the dispatcher's `rootDir` and merged into the worktree using the historical loop (with ancestor pruning, preflight conflict detection, ADO bearer-token retry, etc.). A merge failure here is a real failure (`FAILURE_CLASS.MERGE_CONFLICT` after preflight, retryable).
 
@@ -106,7 +106,7 @@ Caveat: `detectDependencyCycles` is a partial DFS — 2-cycles (`A → B → A`)
    - Fetches the dep branch into the **dep's** project rootDir (the current project's origin doesn't carry the ref).
    - Transfer-fetches the tip into the current worktree under the namespaced ref `refs/cross-repo-deps/<branch>` via a filesystem-path remote.
    - Computes a best-effort tip SHA + changed-file list (vs the dep project's main).
-   - Appends a `## Cross-repo dependencies` section to the prompt (`engine.js#buildCrossRepoDepsSection`, ~line 671) listing the repo, branch, short SHA, ref, and changed files.
+   - Appends a `## Cross-repo dependencies` section to the prompt (`engine.js:793-823`, `buildCrossRepoDepsSection`) listing the repo, branch, short SHA, ref, and changed files.
    - **Never merges** the dep branch into the worktree (cross-repo merges would commingle unrelated repo content).
    - **Never escalates** on fetch failure — the dispatch proceeds with an advisory entry that records the attempt with `files: []`.
    - Cross-repo deps with no resolvable `projectRoot` (missing `localPath` on the dep project) are dropped with a warn and never reach the agent.
@@ -115,7 +115,7 @@ The agent's contract with cross-repo deps is read-only inspection (`git show ref
 
 ## Shared-branch pre-creation (per project, idempotent)
 
-When a cross-repo plan declares `branch_strategy: "shared-branch"` with an explicit `feature_branch`, the materializer's tail block in `engine.js#materializePlansAsWorkItems` (~line 5318) pre-creates that branch in **every project the plan touched** before the first dispatcher pass:
+When a cross-repo plan declares `branch_strategy: "shared-branch"` with an explicit `feature_branch`, the materializer's tail block in `engine.js#materializePlansAsWorkItems` (`engine.js:7718-7756`) pre-creates that branch in **every project the plan touched** before the first dispatcher pass:
 
 ```text
 for each project P in itemsByProject (excluding the `_central` bucket):
@@ -136,24 +136,24 @@ This is what makes the per-project dispatcher's later `git worktree add ... orig
 
 `engine.js#discoverFromWorkItems(config, project)` reads exactly one project SQL scope per call, routes pending items via `routing.md`, and returns `newWork[]` entries for the dispatcher. Cross-repo plans don't change this loop; the engine iterates all configured projects per tick.
 
-Module-level `_claimedAgents` in `engine/routing.js` persists across in-process calls but is cleared per tick (`routing.resetClaims()`), so two items in different projects routed to the same agent in the same tick contend correctly for the single agent slot.
+Module-level `_claimedAgents` in `engine/routing.js` persists across in-process calls but is cleared at the start of each discovery pass (`routing.resetClaimedAgents()`), so two items in different projects routed to the same agent in the same pass contend correctly for the single agent slot.
 
 ## Per-project verify fan-out
 
-`engine/lifecycle.js#checkPlanCompletion` (line 24, fan-out at lines 217–274) gates on two conditions:
+`engine/lifecycle.js#checkPlanCompletion` (`engine/lifecycle.js:26-155`, fan-out at `:279-494`) gates on two conditions:
 
 1. Every PRD `missing_features` item has been materialized into a WI.
-2. Every materialized WI is in a terminal state (`DONE_STATUSES` or `cancelled`).
+2. Every materialized WI is in `PLAN_TERMINAL_STATUSES` (`DONE_STATUSES`, `failed`, or `cancelled`).
 
 When both gates pass, the function groups **active PRs** by project from the SQL PR store and joins them to done items through the `pr_links` table. The result is a `touchedProjects` array: every project that has at least one active PR linked to one of the plan's done items.
 
-For each touched project the fan-out (lines 245–415):
+For each touched project the fan-out (`engine/lifecycle.js:312-494`):
 
 - Looks up any existing verify WI keyed on `(sourcePlan, itemType:'verify', project)`. Legacy single-WI plans match against the primary project name when `existingVerify.project` is unset.
 - Skips if the existing verify is active; re-opens if it's eligible (`isReopenableVerify`).
 - Otherwise builds a per-project setup block:
-  - **Shared-branch plans** reuse `feature_branch` directly — the verify agent checks out the branch in-place in the project's localPath.
-  - **Parallel-branch plans** merge each linked PR branch into a per-project worktree at `<localPath>/../worktrees/verify-<projName>-<planSlug>`.
+  - **Shared-branch plans** create or reuse a stable sibling verify worktree at `verify-<project>-<plan>` (no collision suffix) from `origin/<feature_branch>`; no PR branches are merged. The fixed name allows coordinated reuse across retries.
+  - **Parallel-branch plans** merge each linked PR branch into a per-project worktree at `<localPath>/../worktrees/verify-<projName>-<planSlug>-<uid>` (a `shared.uid()` collision-avoidance suffix) since each item links its own PR and may require unique setup.
 - Validates every branch ref through `shared.validateGitRef` before splicing into the bash setup commands (P-f3-verify-prompt — defense in depth against shell injection from a crafted `feature_branch` or PR `branch` field).
 - Writes a new verify WI into the touched project's SQL scope with `itemType: 'verify'`, `type: 'verify'`, `priority: 'high'`, `status: 'pending'`, and `project: <projName>`. The title is project-prefixed (`Verify plan (minions-opg): …`) when `touchedProjects.length > 1` to disambiguate the dashboard listing.
 
@@ -214,7 +214,7 @@ Plan markdown `plans/cross-repo-launch.md`:
 Add a new compliance check + matching engine plumbing.
 ```
 
-Operator approves the plan. Plan-to-prd dispatches against the `minions` project (read-only worktree, first in the target list). The plan-to-prd agent writes PRD `prd/cross-repo-launch.json`:
+Operator approves the plan. Plan-to-prd dispatches against the `minions` project (read-only worktree, first in the target list). The agent writes `agents/<agent-id>/prd-result.json`; the engine validates the envelope, imports its `prd` object into SQLite under filename `cross-repo-launch.json`, and deletes the sidecar. The imported PRD shape is:
 
 ```json
 {
@@ -238,11 +238,11 @@ Operator approves the plan. Plan-to-prd dispatches against the `minions` project
 }
 ```
 
-Engine ticks once:
+Engine begins execution:
 
 1. `materializePlansAsWorkItems` groups by project: `{ minions: [P-001], minions-opg: [P-002] }`. Cycle scan runs once over both items, finds nothing. Writes P-001 and P-002 to their respective SQL scopes. Branch-strategy is `parallel`, so no shared-branch pre-create runs.
 2. `discoverFromWorkItems(config, minions)` picks up P-001, routes it via `routing.md`, dispatches `implement` agent. Worktree created on `work/P-001` off `minions`' main.
-3. `discoverFromWorkItems(config, minions-opg)` picks up P-002. Its `depends_on: ["P-001"]` resolves to a same-project dep? **No** — P-001 lives in the `minions` project, so it's a **cross-repo dep**. The dispatcher fetches P-001's branch into the `minions` rootDir, transfer-fetches it into the `minions-opg` worktree under `refs/cross-repo-deps/work/P-001`, computes a short SHA + changed-file list, and appends a `## Cross-repo dependencies` section to the prompt. The agent inspects via `git show` / `git log` and ships matching code in `minions-opg`.
+3. While P-001 is pending or dispatched, P-002 stays pending with `dependency_unmet`. After P-001 reaches a `DONE_STATUSES` value, a later `discoverFromWorkItems(config, minions-opg)` pass picks up P-002. Its dependency lives in the `minions` project, so it is a **cross-repo dep**: the dispatcher fetches P-001's branch into the `minions` rootDir, transfer-fetches it into the `minions-opg` worktree under `refs/cross-repo-deps/work/P-001`, computes a short SHA + changed-file list, and appends a `## Cross-repo dependencies` section to the prompt. The agent inspects via `git show` / `git log` and ships matching code in `minions-opg`.
 4. Both items complete with PRs. SQL `pr_links` rows link each PR to its WI.
 5. Next tick `lifecycle.checkPlanCompletion` runs. Gates pass (every item materialized + done). Groups active PRs by project: `{ minions: [PR for P-001], minions-opg: [PR for P-002] }`. Creates two verify WIs:
    - `(minions)` verify WI in the `minions` scope with `project: 'minions'`.
@@ -258,20 +258,20 @@ When you need to change the cross-repo path, the load-bearing seams are:
 
 | Concern | File:line | Notes |
 | --- | --- | --- |
-| Parse plan markdown projects | `engine/shared.js:3690` (`extractPlanDeclaredProject`), `engine/shared.js:3713` (`extractPlanTargetProjects`) | Both scan first 80 lines; HTML comment marker preferred over `**Projects:**` fallback. |
-| `POST /api/plans/create` array normalization | `dashboard.js` (P-2e9b54d1) | Dedup + per-name validation via `shared.findProjectByName`; 0–1 → singular header, 2+ → plural header + marker. |
-| Plan-to-prd dispatch wiring | `engine.js:7470+` (`discoverCentralWorkItems`) | Sets `vars.target_projects` when plan is cross-repo; picks first listed project for the read-only worktree. |
+| Parse plan markdown projects | `engine/shared.js:4516` (`extractPlanDeclaredProject`), `engine/shared.js:4539` (`extractPlanTargetProjects`) | Both scan first 80 lines; HTML comment marker preferred over `**Projects:**` fallback. |
+| `POST /api/plans/create` array normalization | `dashboard.js:13958-14006` | Dedup + per-name validation via `shared.findProjectByName`; 0–1 → singular header, 2+ → plural header + marker. |
+| Plan-to-prd dispatch wiring | `engine.js:10319-10506` (`discoverCentralWorkItems`) | Sets `vars.target_projects` when plan is cross-repo; picks first listed project for the read-only worktree. |
 | Plan-to-prd playbook contract | `playbooks/plan-to-prd.md` (P-3b8c40d9) | Tells the agent to omit top-level `project`, set per-item `project`, default to `parallel`. |
-| Per-project work-item grouping | `engine.js:5151–5181` (`materializePlansAsWorkItems`) | `itemsByProject` map; unknown-project items stamped `_invalidProject`. |
-| Cross-repo cycle detection | `engine.js:5183–5192` | One global scan over `plan.missing_features` BEFORE per-project loop. |
-| Shared-branch pre-create per project | `engine.js:5318–5356` | Idempotent `rev-parse` → `branch` → `push -u`; per-project failure isolation. |
-| Cross-repo dep partitioning + advisory fetch | `engine.js:2495–2682` (`spawnAgent` dep loop) | `isCrossRepo` split; transfer-fetch via filesystem-path remote into `refs/cross-repo-deps/<branch>`. |
-| Cross-repo dep prompt section | `engine.js:662–710` (`buildCrossRepoDepsSection`) | Renders one section per dep with repo, branch, SHA, files, local ref. |
-| Per-project verify fan-out | `engine/lifecycle.js` (`checkPlanCompletion`) | Group active PRs by project via SQL links; one verify WI per touched project. |
-| Verify WI creation | `engine/lifecycle.js:387–411` | `itemType:'verify'`, `project: projName`, project-prefixed title when `touchedProjects.length > 1`. |
-| Per-project rollup pills | `dashboard.js#handlePlansList` (P-66b1faec) | Gate `_perProjectProgress.length >= 2`. |
-| Per-project verify badges | `dashboard/js/render-plans.js` (P-d7e592b1) | Gate `verifyWis.length >= 2`. |
-| `i.projects[]` + plan `_projects` rollup | `engine/queries.js` (P-e8d49105) | Populated when at least one PRD item has a `project` field. |
+| Per-project work-item grouping | `engine.js:7523-7553` (`materializePlansAsWorkItems`) | `itemsByProject` map; unknown-project items stamped `_invalidProject`. |
+| Cross-repo cycle detection | `engine.js:7084-7097`, `engine.js:7557-7564` | One global scan over `plan.missing_features` before the per-project materialization loop. |
+| Shared-branch pre-create per project | `engine.js:7718-7756` | Idempotent `rev-parse` → `branch` → `push -u`; per-project failure isolation. |
+| Cross-repo dep partitioning + advisory fetch | `engine.js:4457-4658` (`spawnAgent` dep loop) | `isCrossRepo` split; transfer-fetch via filesystem-path remote into `refs/cross-repo-deps/<branch>`. |
+| Cross-repo dep prompt section | `engine.js:793-823` (`buildCrossRepoDepsSection`) | Renders one section per dep with repo, branch, SHA, files, local ref. |
+| Per-project verify fan-out | `engine/lifecycle.js:279-494` (`checkPlanCompletion`) | Group active PRs by project via SQL links; one verify WI per touched project. |
+| Verify WI creation | `engine/lifecycle.js:350-410`, `engine/lifecycle.js:445-494` | `itemType:'verify'`, `project: projName`, project-prefixed title when `touchedProjects.length > 1`. |
+| Per-project rollup pills | `dashboard.js:7826-7845`, `dashboard/js/render-plans.js:389-417` | Gate `Object.keys(_perProjectProgress).length >= 2`. |
+| Per-project verify badges | `dashboard/js/render-plans.js:351-417` | Gate `verifyWis.length >= 2`. |
+| `i.projects[]` + plan `_projects` rollup | `engine/queries.js:2442-2444`, `dashboard.js:7813-7826` | Populated when at least one PRD item has a `project` field. |
 
 ## Executable spec
 
@@ -280,7 +280,7 @@ When you need to change the cross-repo path, the load-bearing seams are:
 1. PRD with per-item `project` fans into per-project SQL scopes (alpha vs beta).
 2. `discoverFromWorkItems(config, project)` returns only the queried project's items.
 3. `checkPlanCompletion` creates one verify WI per touched project when each project has at least one active PR linked to a done WI.
-4. A 3-feature cyclic chain that crosses project boundaries (alpha → beta → alpha) is detected and none of the cyclic items are written.
+4. A 2-feature cycle across project boundaries is detected and both cycle members are skipped while an independent third item still materializes.
 
 Run via `node test/integration/cross-repo-plan-e2e.test.js` (or as part of `npm run test:integration`).
 

package/docs/demo/memory-system.html

@@ -1511,7 +1511,7 @@
         <dl>
           <dt>engine.inboxConsolidateThreshold</dt><dd>5</dd>
           <dt>engine.memoryEpisodicCapture</dt><dd>false</dd>
-          <dt>engine.autoConsolidateMemory</dt><dd>false</dd>
+          <dt>engine.autoConsolidateMemory</dt><dd>true</dd>
         </dl>
       </article>
       <article class="control-card">

package/docs/deprecated.json

@@ -189,21 +189,6 @@
     "targetRemovalDate": "2026-08-03",
     "notes": "Introduced by W-mq03l6zh0006f0a1 (Per-org ADO throttle isolation). 60-day window (2 release cycles + buffer) gives the in-flight per-org migration time to land + observe per-org keys on the diagnostics endpoint. Observable live at GET /api/diagnostics/ado-throttle — the endpoint reports a single `global` key while the arg-less shim is still load-bearing, and per-org `<orgBase>` keys once isolation is complete; that key shape is the human-readable signal for whether this shim can retire."
   },
-  {
-    "id": "pr-link-autoObserve-body-param",
-    "status": "removed",
-    "removedDate": "2026-06-25",
-    "description": "Legacy `autoObserve` body parameter on `POST /api/pull-requests/link`. Replaced by canonical `contextOnly` body param (inverse boolean: `autoObserve: false` ⇔ `contextOnly: true`). This was a READ-BRIDGE on the input side only — the handler read `body.contextOnly` first and fell back to `!body.autoObserve` for callers not yet migrated. Removed by M001 (work/M001).",
-    "code": [
-      {
-        "file": "dashboard.js",
-        "note": "Removed: linkPullRequestForTracking no longer accepts autoObserve in the destructure; resolvedContextOnly is now simply typeof contextOnly === 'boolean' ? contextOnly : false. Route registry params string no longer lists autoObserve?."
-      }
-    ],
-    "deprecated": "2026-06-08",
-    "targetRemovalDate": "2026-06-25",
-    "notes": "Removed on 2026-06-25. On-disk sweep confirmed CLEAN on 2026-06-18. autoObserve parameter silently ignored by server after this removal — callers that still send it will see the value dropped with contextOnly defaulting to false."
-  },
   {
     "id": "worktreemode-field-rename",
     "description": "Legacy `project.worktreeMode` config field (enum 'isolated'|'live'). Consolidated by W-mqiaw974 (issue #241) into a single `project.checkoutMode` field (enum 'worktree'|'live'): the old 'isolated' value became the implicit default 'worktree', and the overlapping/never-shipped 'shared' value was removed. The write side is migrated — buildProjectEntry, dashboard settings POST, and projects.addProject all write `checkoutMode`, and the dashboard settings/merge paths delete any stale `worktreeMode` key on save. What survives is a READ-BRIDGE ONLY: `shared.resolveCheckoutMode(project)` (and the `isLiveCheckoutProject` predicate built on it) reads canonical `checkoutMode` first, then falls back to the legacy `worktreeMode` field ('isolated'→'worktree', 'live'→'live') so an un-migrated config.json keeps dispatching live-checkout projects correctly. `validateCheckoutMode` also silently coerces a submitted legacy 'isolated' value to 'worktree'.",
@@ -231,22 +216,151 @@
     "code": [
       {
         "file": "dashboard.js",
-        "note": "POST /api/pull-requests/observe handler reads `body.contextOnly` first, then falls back to `!body.observe` for backwards compat."
+        "note": "updatePullRequestObserveFlag() reads `contextOnly` first (canonical); when it is not a boolean it falls back to `!observe` for backwards compat with external callers. dashboard/js/render-prs.js's togglePrObserve() (the only in-repo client) now POSTs `contextOnly` exclusively and no longer sends `observe` (P-2b6e4d81)."
       }
     ],
     "deprecated": "2026-06-08",
     "status": "active",
+    "targetRemovalDate": "2026-09-29",
+    "notes": "targetRemovalDate set 2026-07-01 (~90 days out, P-2b6e4d81) after confirming zero remaining `body.observe` / `observe:` sends in dashboard client-side JS (grep of dashboard/js/*.js) — the only client caller, render-prs.js's togglePrObserve(), now POSTs `contextOnly` exclusively. Removal scope on/after 2026-09-29: drop the `body.observe` / `!observe` fallback branch in dashboard.js's updatePullRequestObserveFlag, drop the legacy-`observe`-acceptance note from the route registry `params` string, and remove the back-compat assertions in test/unit/pr-observe-toggle.test.js that POST the legacy `observe` field, once no external tooling is confirmed to still send it."
+  },
+  {
+    "id": "discover-review-skills",
+    "description": "engine/discover-review-skills.js — standalone module that discovered and surfaced review-skill annotations from agent output. Superseded by the inline skill-extraction logic in engine/lifecycle.js during the skill-system consolidation.",
+    "code": [],
+    "deprecated": "2026-06-29",
+    "status": "removed",
+    "removedDate": "2026-06-29",
     "targetRemovalDate": null,
-    "notes": "targetRemovalDate intentionally null — unlike the record-field aliases (`_contextOnly`, `_autoObserve`, `_manual`) which carry a 7-day clock, the `observe` body param is documented as a longer-lived back-compat alias. Set targetRemovalDate to a concrete future date once the dashboard UI + any client scripts are confirmed to POST `contextOnly` exclusively. Removal scope when the date is set: drop the `body.observe` fallback in dashboard.js, drop `observe` from the route registry params, and update any client still POSTing `observe`."
+    "notes": "engine/discover-review-skills.js does not exist on disk. The functionality was folded into engine/lifecycle.js skill extraction. No callers remain."
   },
   {
     "id": "discover-review-skills-shim",
     "description": "engine/discover-review-skills.js is a 25-line re-export shim for engine/discover-project-skills.js. Zero production callers; only test files (discover-review-skills.test.js, discover-project-skills.test.js:706) reference it.",
     "addedDate": "2026-06-24",
+    "deprecated": "2026-06-24",
+    "status": "removed",
+    "removedDate": "2026-06-25",
+    "removedPr": "opg-microsoft/minions#406",
+    "removedCommit": "051fbb1a308143ddc5690f5230b986fc7c199bff",
     "targetRemovalDate": "2026-09-01",
     "removalGate": "No external callers import discover-review-skills.js; test files updated to import from discover-project-skills.js directly.",
     "removalScope": "Delete engine/discover-review-skills.js, delete test/unit/discover-review-skills.test.js, update test/unit/discover-project-skills.test.js:706 to import from discover-project-skills.js.",
     "autoRemoveSafe": false,
-    "notes": "gate: zero test references to discover-review-skills; must update tests to point to discover-project-skills.js before file can be deleted"
+    "notes": "Shim and its dedicated test were deleted in PR #406. This entry is retained as a historical registry record per the deprecated.json contract (records are stamped removed, not deleted)."
+  },
+  {
+    "id": "build-and-test-work-type-alias",
+    "description": "Read compatibility for hybrid validation work items created with type `build-and-test` before the engine enforced the distinction between canonical work-item types and playbook names. Routing normalizes the legacy value to canonical `test`; liveValidation config validation also normalizes it on save.",
+    "code": [
+      {
+        "file": "engine/routing.js",
+        "lines": "normalizeWorkType",
+        "note": "Maps legacy work-item type `build-and-test` to WORK_TYPE.TEST."
+      },
+      {
+        "file": "engine/shared.js",
+        "lines": "normalizeLiveValidationWorkType",
+        "note": "Normalizes persisted liveValidation.type values before routing and validation."
+      }
+    ],
+    "status": "active",
+    "targetRemovalDate": null,
+    "removalGate": "A state/config sweep across all installations must show no work_items.type or projects[].liveValidation.type value equal to `build-and-test` for 30 consecutive days.",
+    "notes": "Do not remove on a calendar alone; old pending SQL work items must remain dispatchable after upgrade."
+  },
+  {
+    "id": "legacy-runtime-named-spawn-flags",
+    "description": "Compatibility bridge for pre-adapter-v1 spawn callers. API-v1 runtime invocations carry their semantic options in the opaque `--runtime-options` payload, but built-in adapters still emit the historical named wrapper flags (`--model`, `--max-turns`, `--effort`, `--resume`, budget/bare/fallback and Copilot tuning flags), and spawn-agent.js still parses those flags individually. Keeping both transports allows older in-process callers and wrapper integrations to continue working during the adapter-contract rollout.",
+    "code": [
+      {
+        "file": "engine/runtimes/contract.js",
+        "lines": "buildSpawnFlags",
+        "note": "Emits the legacy named flag list before appending the canonical opaque `--runtime-options` payload."
+      },
+      {
+        "file": "engine/runtimes/claude.js",
+        "lines": "buildSpawnFlags",
+        "note": "Claude-specific legacy wrapper flag emitter."
+      },
+      {
+        "file": "engine/runtimes/copilot.js",
+        "lines": "buildSpawnFlags",
+        "note": "Copilot-specific legacy wrapper flag emitter, including repeatable disabled-MCP flags."
+      },
+      {
+        "file": "engine/runtimes/codex.js",
+        "lines": "buildSpawnFlags",
+        "note": "Codex-specific legacy wrapper flag emitter."
+      },
+      {
+        "file": "engine/spawn-agent.js",
+        "lines": "parseSpawnArgs",
+        "note": "Parses each historical named adapter option in addition to the canonical `--runtime-options` payload."
+      }
+    ],
+    "deprecated": "2026-07-13",
+    "status": "active",
+    "targetRemovalDate": "2026-10-13",
+    "removalGate": "Do not remove before three release windows have shipped with adapter API v1. Add or inspect spawn-wrapper telemetry that distinguishes invocations containing `--runtime-options` from named-flags-only invocations; named-flags-only usage must remain at zero across all known engines and integrations for >=30 consecutive days. Also confirm no external tooling invokes engine/spawn-agent.js with named adapter flags.",
+    "removalScope": "Delete buildSpawnFlags from the three bundled adapters; simplify contract.buildSpawnFlags to emit only `--runtime <name> --runtime-options <payload>`; remove the individual adapter-option cases from spawn-agent.parseSpawnArgs while retaining `--runtime`, `--runtime-options`, and generic passthrough handling; update the named-flag compatibility assertions in test/unit.test.js, test/unit/auto-recovery.test.js, test/unit/copilot-adapter.test.js, and test/unit/spawn-agent-helpers.test.js.",
+    "autoRemoveSafe": false,
+    "notes": "The opaque payload is additive, not encrypted. This bridge is deliberately time-bounded but external-caller-gated; reaching the calendar date alone is insufficient."
+  },
+  {
+    "id": "versionless-runtime-adapter-compat",
+    "description": "Compatibility path for custom runtime adapters registered before adapter API versioning. registerRuntime() accepts adapters without `apiVersion`, records them as legacy, does not enforce the strict bundled-adapter method surface, passes their custom buildSpawnFlags() the original raw options object, and suppresses the opaque options suffix so their historical argv contract remains unchanged.",
+    "code": [
+      {
+        "file": "engine/runtimes/contract.js",
+        "lines": "legacyAdapters, normalizeRuntimeAdapter, buildSpawnFlags",
+        "note": "Tracks versionless adapters in a WeakSet and preserves their pre-v1 buildSpawnFlags behavior."
+      },
+      {
+        "file": "engine/runtimes/index.js",
+        "lines": "registerRuntime",
+        "note": "Public registration defaults to compatibility normalization; bundled adapters opt into strict validation explicitly."
+      },
+      {
+        "file": "test/unit/spawn-agent-helpers.test.js",
+        "lines": "versionless custom buildSpawnFlags receives raw options without an opaque suffix",
+        "note": "Pins raw-option identity/shape and absence of the API-v1 suffix for legacy custom adapters."
+      }
+    ],
+    "deprecated": "2026-07-13",
+    "status": "active",
+    "targetRemovalDate": null,
+    "removalGate": "Instrument versionless registerRuntime() calls with a deduplicated deprecation signal, then observe zero registrations across all known engines and supported extension/plugin packages for >=90 consecutive days. A source/package sweep must also confirm every maintained custom adapter exports `apiVersion: 1` and satisfies strict contract validation.",
+    "removalScope": "Remove the legacyAdapters WeakSet and versionless branch from engine/runtimes/contract.js; require explicit apiVersion on every registration; make registerRuntime strict by default (or expose an explicitly named test-only partial-registration seam); update partial test adapters to declare API v1 or use that test seam; remove the versionless compatibility tests.",
+    "autoRemoveSafe": false,
+    "notes": "No calendar-only removal: Minions cannot infer how many third-party adapters exist. An explicit unsupported future API version already fails loudly; this shim covers only an omitted version."
+  },
+  {
+    "id": "preapprove-workspace-mcps-wrapper",
+    "description": "Legacy exported helper name from before workspace preparation moved behind the runtime adapter contract. engine/spawn-agent.js still exports preApproveWorkspaceMcps(), which resolves the selected adapter, delegates to prepareWorkspace(), and maps the generic `unsupported-runtime` result back to the historical `not-claude` reason. Production engine dispatch now calls the runtime facade's prepareWorkspace() directly.",
+    "code": [
+      {
+        "file": "engine/spawn-agent.js",
+        "lines": "preApproveWorkspaceMcps and module.exports",
+        "note": "Backward-compatible wrapper and export; no production engine call site remains."
+      },
+      {
+        "file": "engine/runtimes/claude.js",
+        "lines": "prepareWorkspace",
+        "note": "Canonical implementation that must remain after the wrapper is removed."
+      },
+      {
+        "file": "test/unit/spawn-agent-helpers.test.js",
+        "lines": "preApproveWorkspaceMcps test group",
+        "note": "Legacy-wrapper behavioral coverage to migrate to direct Claude-adapter prepareWorkspace tests."
+      }
+    ],
+    "deprecated": "2026-07-13",
+    "status": "active",
+    "targetRemovalDate": "2026-10-13",
+    "removalGate": "After at least three release windows, repository and supported-extension searches must show zero imports or calls to preApproveWorkspaceMcps outside its compatibility tests for >=30 consecutive days. Confirm all maintained callers resolve an adapter and invoke the runtime facade's prepareWorkspace() instead.",
+    "removalScope": "Delete preApproveWorkspaceMcps and its module.exports entry from engine/spawn-agent.js; migrate the wrapper tests in test/unit/spawn-agent-helpers.test.js to call engine/runtimes/claude.js#prepareWorkspace directly; retain the adapter implementation and engine.js facade call.",
+    "autoRemoveSafe": false,
+    "notes": "The wrapper is synchronous and behavior-preserving, so there is no urgency to remove it before external usage is known to be zero."
   }
 ]

package/docs/diagnostics-memory.md

@@ -134,14 +134,15 @@ curl -s "http://localhost:7331/api/diagnostics/memory/history?process=dashboard&
 }
 ```
 
-`samples` is ordered oldest-first. `limit` clamps to the **newest** N.
-Both rings are in-process — restarting the dashboard zeroes them. There
+`samples` is ordered oldest-first. `limit` must be an integer from 1 to
+1440 and selects the **newest** N. Unknown or repeated query fields return
+400. Both rings are in-process — restarting the dashboard zeroes them. There
 is no on-disk replay for history (by design — the soak gate
 `test/perf/soak.test.js` covers the regression case the disk history
 would otherwise serve).
 
-A 400 is returned when `process` is missing or not in
-`{engine, dashboard}`.
+A 400 is returned when `process` is missing or not exactly one of
+`{engine, dashboard}`, or when `limit` is malformed or outside its range.
 
 ## 2. `MEMORY_BASELINE engine ...` log lines
 
@@ -221,6 +222,9 @@ curl -X POST -s \
   | jq
 ```
 
+The confirmation is a query field. The POST body must be absent; putting the
+token in a JSON body is rejected before either process captures a snapshot.
+
 ```json
 {
   "dashboardSnapshot": "D:\\squad-opg\\engine\\diagnostics\\heap-dashboard-2026-06-12T20-15-30-123Z.heapsnapshot",

package/docs/human-vs-automated.md

@@ -64,7 +64,7 @@ These run continuously without you:
 You kick these off, then they run without you:
 
 - **Work items** — type in dashboard, engine dispatches, agent executes, PR created
-- **PRD items** — `/prd` in dashboard, engine discovers and dispatches implement tasks
+- **PRD items** — approve a plan or add an item from **Plans**; the engine materializes and dispatches its work item
 - **Fan-out** — one task dispatched to all idle agents in parallel
 - **Retry** — click retry on failed item, engine re-dispatches fresh
 - **Notes** — `/note` in dashboard, flows through inbox → consolidation → team knowledge
@@ -96,7 +96,7 @@ These are entirely on you:
 If you start the engine and dashboard, then leave:
 
 1. Engine ticks every 10 seconds
-2. Discovers pending work items, PRD gaps, PR reviews needed
+2. Discovers pending work items, materializable PRD items, and PR reviews needed
 3. Dispatches agents (up to max concurrent)
 4. Agents create worktrees, write code, create PRs
 5. Engine monitors for process exit, hard timeouts, stale orphans, and build failures