@yemi33/minions 0.1.2447 → 0.1.2449

package/docs/constellation-bridge.md

@@ -46,7 +46,7 @@ The Constellation agent polls:
 GET http://127.0.0.1:7331/api/constellation/v1/snapshot
 ```
 
-The endpoint is loopback-only because the Minions dashboard binds `127.0.0.1`. It supports `ETag` and `If-None-Match`; unchanged state returns `304` with no body. A `200` response is a **complete replacement snapshot**, so consumers must remove previously mirrored entities that are absent from the latest response.
+The endpoint is loopback-only because the Minions dashboard binds `127.0.0.1`. It is gated by `bridge.isBridgeEnabled` — it returns `404` with `{"error": "Constellation bridge is disabled", "code": "bridge-disabled"}` unless `engine.constellationBridge.enabled` is literally `true`, so `minions bridge disable` severs the metadata projection at the HTTP layer rather than merely asking the agent to stop polling. When enabled it supports `ETag` and `If-None-Match`; unchanged state returns `304` with no body. A `200` response is a **complete replacement snapshot**, so consumers must remove previously mirrored entities that are absent from the latest response.
 
 ```json
 {
@@ -72,7 +72,7 @@ The endpoint is loopback-only because the Minions dashboard binds `127.0.0.1`. I
 
 ### Privacy boundary
 
-Every entity is rebuilt from an explicit allowlist in `engine/bridge.js`; raw dashboard records are never forwarded. The snapshot excludes task descriptions, prompts, acceptance criteria, completion reports, diffs, comments, human feedback, notes, logs, filesystem paths, environment variables, tokens, and secrets. Strings are length-capped to the matching Constellation schema limits.
+Every entity is rebuilt from an explicit allowlist in `engine/api/bridge.js`; raw dashboard records are never forwarded. The snapshot excludes task descriptions, prompts, acceptance criteria, completion reports, diffs, comments, human feedback, notes, logs, filesystem paths, environment variables, tokens, and secrets. Strings are length-capped to the matching Constellation schema limits.
 
 The entity shapes match `packages/shared/src/orchestrator-messages.ts` in the Constellation repository:
 
@@ -84,11 +84,53 @@ The entity shapes match `packages/shared/src/orchestrator-messages.ts` in the Co
 - `agent_status`: agent/status/project, current task identifiers/title and update time.
 - `device_summary`: aggregate counts plus protocol, Minions version and engine health.
 
+## Capability protocol contract
+
+The bridge snapshot above is one-way telemetry. The **capability protocol** is the other half: the vocabulary Minions uses to describe the operations Constellation may invoke. Minions is the producer, Constellation is the consumer, and the vocabulary has exactly one definition:
+
+- **Source of truth:** [`engine/api-contracts/capability-protocol.js`](../engine/api-contracts/capability-protocol.js) — plain CommonJS on Node built-ins only (the repo has zero runtime dependencies, so a schema library is not an option). It is the sole definition of the scope vocabulary, the confirmation enum (`none` / `per-call`), the parameter-type set, the capability-entry and manifest-envelope field lists, and the version rule.
+- **Machine-readable artifact:** [`docs/contracts/capability-protocol.v1.json`](contracts/capability-protocol.v1.json), generated with `node engine/api-contracts/capability-protocol.js --emit` and checked in. A unit test fails if the checked-in bytes and the module disagree, and a second test fails if a scope string appears anywhere in this repo outside those two files.
+- **Live negotiation:** `GET http://127.0.0.1:7331/api/capabilities/protocol` serves the same artifact with an `ETag` derived from its checksum. Like every Constellation surface it is gated by `bridge.isBridgeEnabled` — it returns `404` unless `engine.constellationBridge.enabled` is literally `true`.
+
+The artifact carries `protocolVersion` and a `sha256:` content `checksum` computed over every other field with object keys sorted, so a consumer can pin the exact contract revision it generated against and detect an edited or swapped copy. Regenerating from unchanged sources reproduces the same bytes — the artifact is content-addressed, not time-stamped.
+
+The version rule is the snapshot rule stated above — reused verbatim as `CAPABILITY_VERSION_RULE` rather than restated, so the two cannot drift apart.
+
+**Consumers generate, they never transcribe.** Constellation code-generates its enums and types from the artifact and gates on drift; a hand-maintained parallel enum without a drift gate is outside this contract. On the producer side, `validateCapabilityManifest()` **throws** — a manifest declaring a scope, confirmation mode or parameter type outside the contract fails at build time rather than shipping something the consumer cannot generate against.
+
+## Capability manifest (`GET /api/capabilities`)
+
+The protocol contract above is the vocabulary; the **capability manifest** is what Minions actually publishes with it. It is built by [`engine/api-contracts/capability-manifest.js`](../engine/api-contracts/capability-manifest.js) from the route-contract catalog and served at `GET http://127.0.0.1:7331/api/capabilities`, behind the same strict `bridge.isBridgeEnabled` gate (`404` unless `engine.constellationBridge.enabled` is literally `true`) and with an `ETag`/`If-None-Match` `304` revalidation path.
+
+The envelope is `{ protocol, protocolVersion, generatedAt, minionsVersion, capabilities[] }` and each entry is `{ id, title, description, method, path, scopes[], destructive, confirm, params[] }` — both key sets are generated by walking the protocol contract's field lists, never maintained as a copy alongside them.
+
+Two properties define the producer contract:
+
+- **Opt-in and fail-closed.** A route reaches the manifest only when its owning module in `engine/api-contracts/` declares an explicit `capability` block on its override. A route that declares nothing is absent — there is no heuristic and no derived-by-default entry. An incomplete block (missing `id`, `title`, `description`, a non-empty `scopes[]`, `destructive` or `confirm`, or an out-of-vocabulary value for any of them) fails the catalog build with a throw.
+- **Authorization is declared, never inferred.** `destructive` and `confirm` come from that block alone. They are deliberately **not** derived from `dashboard.js#_routeDestructive`, which is a fail-open regex over the route path *and its free-text description* — reusing it would let rewording a description silently reclassify a capability's safety posture for a remote caller. The method-derived read-only/state-changing split is used only to **contradict** a claim: a `destructive: false` capability on a state-changing route must supply a `nonDestructiveRationale`, and a `destructive: true` capability must require per-call confirmation.
+
+`params[]` is projected from the audited route contract's `request.{path,query,body,headers}.fields` — the same source `GET /api/routes` uses — so a published parameter type cannot drift from the contract the route actually validates against. Contract types that refine a JSON type (`identifier`, `basename`, `path`, `array<object>`) normalize to their protocol type; an ambiguous union (`string|array<string>`) has no honest protocol type and throws, which is the signal to tighten the route contract before publishing it as a capability.
+
+### Phase-0 allowlist
+
+The set of annotated routes is deliberately tiny. Phase 0 exists to prove the producer → consumer round trip end to end, so it exposes **four read-only projections and no mutation at all**:
+
+| Capability id    | Route                     |
+| ---------------- | ------------------------- |
+| `plan.list`      | `GET /api/plans`          |
+| `pr.list`        | `GET /api/pull-requests`  |
+| `status.summary` | `GET /api/status`         |
+| `work.list`      | `GET /api/work-items`     |
+
+Every one declares `destructive: false`, `confirm: "none"`, and a single read scope. `status.summary` grants one scope rather than the union of the read scopes: since issue #2949 the status snapshot is only the live engine/throttle/project envelope, and the work, plan, and PR slices it used to carry are separately-declared capabilities of their own.
+
+The allowlist is pinned as a snapshot in `test/unit/capability-allowlist.test.js`, which also asserts that every manifest entry uses a read-only HTTP method. Widening it therefore cannot happen quietly — it is a reviewed diff in that table. **Mutating capabilities are not part of this phase**; they arrive with `engine.constellationBridge.commandsEnabled` (default off), which must keep them out of the manifest *and* refuse them at execution while it is false.
+
 ## Marker-file contract
 
 The Constellation agent's bridge writes a marker file on every successful poll. Minions reads it with `minions bridge status` so a local operator can verify the bridge is alive and Constellation is talking to it.
 
-- **Path:** `~/.minions/engine/constellation-bridge.json` (exposed as `CONSTELLATION_BRIDGE_MARKER_PATH` in `engine/shared.js`).
+- **Path:** `~/.minions/engine/constellation-bridge.json` (exposed as `CONSTELLATION_BRIDGE_MARKER_PATH` in `engine/core/shared.js`).
 - **Owner:** the Constellation agent. The Minions engine **never** writes this file — it is a one-way breadcrumb from Constellation → Minions.
 
 ### Schema (`schemaVersion: 1`)
@@ -104,13 +146,85 @@ The Constellation agent's bridge writes a marker file on every successful poll.
 
 | Field           | Required | Notes                                                                    |
 | --------------- | -------- | ------------------------------------------------------------------------ |
-| `schemaVersion` | yes      | Must equal `1`. Any other value causes Minions to ignore the marker entirely (treated as no-marker, same as a missing file). New fields are added behind a deliberate version bump. |
+| `schemaVersion` | yes      | Must equal `1`. Any other value causes Minions to ignore the marker entirely (treated as no-marker, same as a missing file). New required fields are added behind a deliberate version bump. |
 | `lastSeenAt`    | yes      | ISO-8601 UTC timestamp of the last successful poll.                      |
-| `agentVersion`  | no       | Constellation agent semver string, surfaced in `bridge status`.         |
+| `agentVersion`  | no       | Constellation agent semver string, surfaced in `bridge status` and used by the companion probe below. |
 | `source`        | no       | Free-form identifier, expected `"constellation-agent"` today.            |
+| `healthUrl`     | no       | Loopback URL of the companion's own health endpoint. Optional and additive: readers must tolerate its absence, and Minions refuses any non-loopback value without requesting it. |
 
 Writers MUST use an atomic-replace pattern (`write to tmp + rename`) so a partial write never leaves Minions reading a half-baked JSON blob.
 
+## Companion probe
+
+Minions reports whether a **compatible Constellation companion** is present. It only reports — Minions **never downloads, executes, or installs Constellation**, there is no recursion marker and no reciprocal-bootstrap handshake, and companion absence is a visible degraded state that is never fatal. Minions installs and operates independently.
+
+The probe lives in `engine/api/companion.js` and is surfaced by:
+
+- `minions doctor` — one `Constellation companion` row (always `warn`, never a critical failure, so the doctor exit code is unchanged on hosts without Constellation).
+- `minions bridge health` — printed before the snapshot probe, so it still says something useful when the dashboard is down.
+- `minions init` and `minions update` — non-fatal informational output.
+
+### Statuses
+
+| Status                    | Meaning                                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| `companion-ok`            | A companion registered and its version is inside the declared compatible range.               |
+| `companion-incompatible`  | A companion is present but its version is outside the range, or its marker uses a `schemaVersion` this Minions build does not read. |
+| `companion-missing`       | No marker — no companion has ever registered with this Minions instance.                      |
+| `companion-unknown`       | A companion is present but its state could not be determined: unreadable marker, no declared version, or a refused/failed/timed-out health probe. |
+
+Every report prints the **detected version** and the **declared compatible range**, so an incompatibility is always actionable rather than a bare "not supported".
+
+### How detection works
+
+1. **Marker** — `~/.minions/engine/constellation-bridge.json` (the same file documented above) is the presence signal. There is no PATH lookup and no directory-name heuristic anywhere in the probe.
+2. **Bounded health request (optional)** — when the marker declares a `healthUrl` (or an operator configures one), Minions issues **one** `GET` under an explicit timeout to resolve a version the marker omitted. An operator-configured `healthUrl` is probed even when no marker exists, so a companion that is installed but not yet bridged is not misreported as absent. The URL must be loopback (`127.0.0.1`, `localhost`, `::1`) over `http`/`https`; anything else is refused **without being requested**, so the probe can never make an outbound network request. A refusal, failure, or timeout reports `companion-unknown` — never `companion-missing`.
+
+With no `healthUrl` anywhere — the default — the marker alone decides, and no request of any kind is made.
+
+Both stages are bounded, so a hung companion can never stall `minions doctor`, `minions bridge health`, `minions init`, `minions update`, or engine start. The probe uses Node built-ins only; Minions stays zero-dependency at runtime.
+
+### Setup guidance
+
+On anything other than `companion-ok`, Minions prints the documented Constellation install command for the current platform as **text for the operator to run**:
+
+```text
+Constellation companion: companion-missing
+  version: (unknown)   compatible range: >=0.2.0 <1.0.0
+  no Constellation companion has registered with this Minions instance
+  Minions runs fine without it — Constellation only mirrors state into its HUD.
+  To install or update the companion, run it yourself (PowerShell):
+    irm https://icy-water-0224cc51e.2.azurestaticapps.net/install.ps1 | iex
+  Docs: https://icy-water-0224cc51e.2.azurestaticapps.net/
+  Minions never runs it for you — this is guidance, not an action.
+```
+
+On macOS/Linux the printed command is `curl -fsSL https://icy-water-0224cc51e.2.azurestaticapps.net/install.sh | sh`. Minions never executes either command.
+
+### Config + opt-out
+
+```json
+{
+  "engine": {
+    "constellationCompanion": {
+      "probeEnabled": true,
+      "probeTimeoutMs": 2000,
+      "healthUrl": null
+    }
+  }
+}
+```
+
+| Key              | Default | Notes                                                                                  |
+| ---------------- | ------- | -------------------------------------------------------------------------------------- |
+| `probeEnabled`   | `true`  | Set to `false` to suppress the companion probe **entirely** — no marker read, no health request, no output anywhere. Intended for managed deployments that already know the companion topology. |
+| `probeTimeoutMs` | `2000`  | Hard bound on the optional health request. Clamped to `[250, 15000]` ms at read time.     |
+| `healthUrl`      | `null`  | Operator override for the companion health endpoint. Wins over the marker's own `healthUrl`. Loopback-only. |
+
+The environment variable **`MINIONS_DISABLE_COMPANION_PROBE=1`** does the same as `probeEnabled: false` and wins over config, so a fleet image can suppress the probe without editing `config.json`.
+
+This block is CLI/config-managed like `engine.constellationBridge` — neither Constellation surface has a dashboard Settings control.
+
 ## `minions bridge health`
 
 `bridge health` performs a synchronous probe of the versioned snapshot endpoint and prints its aggregate metadata. This verifies both dashboard reachability and protocol compatibility.
@@ -136,8 +250,22 @@ bridge: dashboard reachable on http://127.0.0.1:7331
 
 If the dashboard is not listening, `bridge health` prints `dashboard not running on :7331 — start it with \`minions dash\`` and exits 1. Use this exit code to gate scripted health checks.
 
+Because the snapshot endpoint is gated, probing it with the bridge disabled is not a dashboard fault. `bridge health` recognizes the `bridge-disabled` response and reports the flag instead of a bare status code, still exiting 1:
+
+```text
+error: Constellation bridge is disabled — enable it with `minions bridge enable`
+  config: engine.constellationBridge.enabled = false
+```
+
 ## Cross-repo coordination
 
-The Minions producer lands before the Constellation consumer. During rollout, Constellation may fall back to the legacy per-endpoint projection only when the versioned endpoint returns `404`; a malformed versioned response must fail closed rather than silently downgrading.
+The Minions producer lands before the Constellation consumer. During rollout, Constellation may fall back to the legacy per-endpoint projection only when the versioned endpoint is genuinely absent; a malformed versioned response must fail closed rather than silently downgrading.
+
+**A `404` is not by itself proof of absence.** The same status now also means "this operator turned the bridge off", and those two cases require opposite behavior — fall back in one, stop entirely in the other. Discriminate on the response body, not the status code:
+
+- `404` with `"code": "bridge-disabled"` → the bridge is deliberately off. **Stop projecting.** Do not fall back to the legacy per-endpoint projection; doing so would keep mirroring the machine the operator just withdrew, which is precisely what `enabled` exists to prevent.
+- Any other `404` (or a non-JSON body) → the route is not served by this Minions build; the legacy fallback applies.
+
+In practice an unmatched path on the Minions dashboard falls through to the SPA catch-all and answers `200 text/html`, never `404`, so on any build that has this route a `404` here is always the gate.
 
 The Constellation agent's bridge reads `~/.minions/config.json` directly (no Minions HTTP API call) so config edits propagate without waiting for the engine to restart.

package/docs/constellation-style-telemetry.md

@@ -65,10 +65,10 @@ Key design properties:
 | `metrics_daily` rollups | SQL metrics `_daily.<YYYY-MM-DD>` → `{costUsd, inputTokens, outputTokens, cacheRead, tasks}` |
 | Per-entity aggregates | Per-agent counters: `tasksCompleted/Errored`, `prsCreated/Approved/Rejected/Merged`, `reviewsDone`, `totalCostUsd`, `totalInputTokens/OutputTokens/CacheRead`, `totalRuntimeMs`, `model`, `timedTasks` |
 | App/engine analytics | SQL metrics `_engine`: `command-center`, `agent-dispatch`, `consolidation`, `agent_memory_reconcile` |
-| Emit helpers | `llm.trackEngineUsage()`, `trackReviewMetric()`, `updateMetrics()` (`engine/lifecycle.js`, `engine/llm.js`, `engine/shared.js`) |
+| Emit helpers | `llm.trackEngineUsage()`, `trackReviewMetric()`, `updateMetrics()` (`engine/orchestration/lifecycle.js`, `engine/agents/llm.js`, `engine/core/shared.js`) |
 | Structured error taxonomy | `FAILURE_CLASS` constants (recorded per work-item; not yet aggregated as a metric) |
 | Diagnostic stream | SQL log tail (secret-redacted via `redactSecrets()`) + `engine/dashboard-diagnostics.log` |
-| Admin overview query | `getMetrics()` (`engine/queries.js`) surfaced via `/api/status` |
+| Admin overview query | `getMetrics()` (`engine/core/queries.js`) surfaced via `/api/status` |
 
 ## The gap (the 40% worth building)
 
@@ -156,6 +156,6 @@ the other HTML entry points; counters from an in-memory registry, no client libr
   `packages/server/src/api/prism.ts`, `packages/dashboard/src/prism/prism-telemetry.ts`
 - Constellation taxonomy/privacy: `packages/shared/src/constants.ts`,
   `packages/shared/src/privacy.ts`
-- Minions today: `engine/state.db` metrics, `getMetrics()` (`engine/queries.js`),
-  `trackEngineUsage()` (`engine/llm.js`), `FAILURE_CLASS` (`engine/shared.js`),
+- Minions today: `engine/state.db` metrics, `getMetrics()` (`engine/core/queries.js`),
+  `trackEngineUsage()` (`engine/agents/llm.js`), `FAILURE_CLASS` (`engine/core/shared.js`),
   related design doc `design-state-storage.md`.

package/docs/contracts/capability-protocol.v1.json

@@ -0,0 +1,165 @@
+{
+  "protocol": "minions.capability.manifest",
+  "protocolVersion": 1,
+  "generator": "engine/api-contracts/capability-protocol.js",
+  "versionRule": "`protocolVersion` changes only for a breaking schema change. Additive optional fields do not require a version bump.",
+  "scopes": [
+    "work:read",
+    "work:write",
+    "plan:read",
+    "plan:write",
+    "pr:read",
+    "notes:write",
+    "watch:write",
+    "engine:control",
+    "cc:converse",
+    "docchat:write",
+    "qa:read"
+  ],
+  "confirmModes": [
+    "none",
+    "per-call"
+  ],
+  "paramTypes": [
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "array",
+    "object"
+  ],
+  "manifestEnvelopeFields": [
+    {
+      "name": "protocol",
+      "type": "string",
+      "required": true,
+      "constant": "minions.capability.manifest",
+      "description": "Protocol identifier."
+    },
+    {
+      "name": "protocolVersion",
+      "type": "integer",
+      "required": true,
+      "constant": 1,
+      "description": "Protocol version; see versionRule."
+    },
+    {
+      "name": "generatedAt",
+      "type": "string",
+      "required": true,
+      "description": "ISO-8601 UTC timestamp of manifest generation."
+    },
+    {
+      "name": "minionsVersion",
+      "type": "string",
+      "required": false,
+      "description": "Optional Minions package version of the producer."
+    },
+    {
+      "name": "capabilities",
+      "type": "array",
+      "required": true,
+      "itemsOf": "capabilityEntryFields",
+      "description": "Capability entries."
+    }
+  ],
+  "capabilityEntryFields": [
+    {
+      "name": "id",
+      "type": "string",
+      "required": true,
+      "description": "Stable capability identifier, unique within a manifest."
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "description": "Short human-readable label."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": true,
+      "description": "One-line description of the effect."
+    },
+    {
+      "name": "method",
+      "type": "string",
+      "required": true,
+      "description": "HTTP method of the backing Minions route."
+    },
+    {
+      "name": "path",
+      "type": "string",
+      "required": true,
+      "description": "Canonical route path template of the backing Minions route."
+    },
+    {
+      "name": "scopes",
+      "type": "array",
+      "required": true,
+      "itemsOf": "scopes",
+      "description": "Scopes consumed, drawn from the scope vocabulary."
+    },
+    {
+      "name": "destructive",
+      "type": "boolean",
+      "required": true,
+      "description": "Whether invoking the capability destroys or irreversibly mutates state. A consumer authorization input, so it is always declared explicitly and never inferred from the route name, method, or description."
+    },
+    {
+      "name": "confirm",
+      "type": "string",
+      "required": true,
+      "allowedValuesOf": "confirmModes",
+      "description": "Confirmation policy for invocation."
+    },
+    {
+      "name": "params",
+      "type": "array",
+      "required": true,
+      "itemsOf": "capabilityParamFields",
+      "description": "Parameter descriptors; may be empty."
+    }
+  ],
+  "capabilityParamFields": [
+    {
+      "name": "name",
+      "type": "string",
+      "required": true,
+      "description": "Parameter name as sent to the route."
+    },
+    {
+      "name": "type",
+      "type": "string",
+      "required": true,
+      "allowedValuesOf": "paramTypes",
+      "description": "Parameter type from the parameter-type set."
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "required": true,
+      "description": "Whether the caller must supply the parameter."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "description": "Optional one-line parameter description."
+    },
+    {
+      "name": "allowedValues",
+      "type": "array",
+      "required": false,
+      "description": "Optional closed value set."
+    },
+    {
+      "name": "maxLength",
+      "type": "integer",
+      "required": false,
+      "description": "Optional maximum length for string parameters."
+    }
+  ],
+  "checksum": "sha256:28a2266d5b4f4a4618073461a06b07380121419603ca31f2539eb8263cfe9318"
+}

package/docs/cooldown-merge-semantics.md

@@ -1,17 +1,17 @@
 # `saveCooldowns` merge semantics
 
 > **Historical design record:** this predates the SQL-only cutover. Cooldowns now
-> persist through `engine/small-state-store.js`; file and lock references below
+> persist through `engine/persistence/small-state-store.js`; file and lock references below
 > describe the superseded implementation evaluated by the original PRD.
 
 Scoping deliverable for PRD item **P-bfa3a-scope-cooldown-merge** (Wave 3, PR10
 pre-work) of the 2026-05-27 weekly bug-audit plan. Decides the merge strategy
 the implementation PR (**P-bfa3b-cooldown-lost-update**) will apply at
-`engine/cooldown.js:63-101`. No code is modified by this scoping artefact.
+`engine/orchestration/cooldown.js:63-101`. No code is modified by this scoping artefact.
 
 ## Context
 
-`engine/cooldown.js:63-101` (`saveCooldowns`) handles only **deletions** across
+`engine/orchestration/cooldown.js:63-101` (`saveCooldowns`) handles only **deletions** across
 the debounced in-memory ↔ on-disk boundary. Any key added to `cooldowns.json`
 by a concurrent writer between two of our writes is **silently overwritten**
 when the in-memory `dispatchCooldowns` Map is flushed via
@@ -20,7 +20,7 @@ the window.
 
 `mutateCooldowns` already runs through `mutateJsonFileLocked`, which acquires
 an exclusive `withFileLock` for the read-modify-write
-(source: `engine/shared.js` `mutateCooldowns` ~L1625 and `mutateJsonFileLocked` ~L1542), so the callback
+(source: `engine/core/shared.js` `mutateCooldowns` ~L1625 and `mutateJsonFileLocked` ~L1542), so the callback
 receives the freshly-read `diskCooldowns` snapshot — but the current code
 throws that snapshot away.
 
@@ -53,7 +53,7 @@ acceptance from P-bfa3b verbatim.
    after the next `loadCooldowns()` on writer B.
 
 2. **Deletion-merge preserved (regression).** The existing
-   `_lastDiskCooldownKeys` logic at `engine/cooldown.js:70-74` runs first,
+   `_lastDiskCooldownKeys` logic at `engine/orchestration/cooldown.js:70-74` runs first,
    before the union — any key present in `_lastDiskCooldownKeys` (i.e. we
    wrote it on our previous flush) but absent from the freshly-read
    `diskCooldowns` is treated as a deliberate delete by another writer and is
@@ -73,7 +73,7 @@ acceptance from P-bfa3b verbatim.
 ## Trade-offs for the three options NOT chosen
 
 - **(b) per-key timestamp-tagged merge** — The entry schema already carries
-  `timestamp` (source: `engine/cooldown.js:154, 171, 195`), so this would add
+  `timestamp` (source: `engine/orchestration/cooldown.js:154, 171, 195`), so this would add
   no new field; but it adds per-key branching in the flush hot path while
   converging on the same winner as (a) in every realistic case, because the
   in-memory entry whose mutation triggered the debounce is by construction at
@@ -88,12 +88,12 @@ acceptance from P-bfa3b verbatim.
   `setCooldown` / `setCooldownFailure` / `isOnCooldown` call adds one fs read
   to the per-dispatch evaluation hot path, contradicts the module-level
   `dispatchCooldowns` Map cache that exists specifically to avoid that cost
-  (source: `engine/cooldown.js:39`), and the lock-protected merge in (a)
+  (source: `engine/orchestration/cooldown.js:39`), and the lock-protected merge in (a)
   achieves the same correctness without the per-read penalty.
 
 ## Implementation notes for the P-bfa3b dispatch (dallas)
 
-- Touch only `engine/cooldown.js:63-101` (`saveCooldowns`) — no API or signature
+- Touch only `engine/orchestration/cooldown.js:63-101` (`saveCooldowns`) — no API or signature
   changes, no caller-side migration. Expected diff: ~10–15 LoC inside the
   existing `mutateCooldowns` callback.
 - The expiry-prune loop and the `pendingContexts` cap/truncate loop must run on
@@ -115,10 +115,10 @@ acceptance from P-bfa3b verbatim.
 
 ## Source references
 
-- `engine/cooldown.js:63-101` — current lost-update site
-- `engine/cooldown.js:38-60` — `loadCooldowns` + `_lastDiskCooldownKeys` baseline
-- `engine/shared.js` `mutateCooldowns` (~L1625) — already lock-protected
-- `engine/shared.js` `mutateJsonFileLocked` (~L1542) — reads disk inside the
+- `engine/orchestration/cooldown.js:63-101` — current lost-update site
+- `engine/orchestration/cooldown.js:38-60` — `loadCooldowns` + `_lastDiskCooldownKeys` baseline
+- `engine/core/shared.js` `mutateCooldowns` (~L1625) — already lock-protected
+- `engine/core/shared.js` `mutateJsonFileLocked` (~L1542) — reads disk inside the
   lock; `skipWriteIfUnchanged` enabled for cooldowns
 - `prd/bug-fix-plan-from-weekly-audit-2026-05-27.json` — P-bfa3a (this scoping)
   and P-bfa3b (implementation acceptance criteria)

package/docs/copilot-cli-schema.md

@@ -28,7 +28,7 @@
 | `capabilities.claudeMdNativeDiscovery` | **`false`** | Copilot loads its native `AGENTS.md`, not repo-authored `CLAUDE.md`; the engine may inject the latter through its separate propagation layer. |
 | `capabilities.fallbackModel` | **`false`** | No `--fallback-model` flag. |
 | `capabilities.sessionPersistenceControl` | **`false`** | Copilot manages session state internally in `~/.copilot/session-state/`. Engine cannot opt out without `--config-dir`. |
-| `capabilities.streamConsumer` | **`true`** | The adapter supplies the stream accumulator used by `engine/llm.js`. |
+| `capabilities.streamConsumer` | **`true`** | The adapter supplies the stream accumulator used by `engine/agents/llm.js`. |
 | `capabilities.imageInput` | **`true`** | Base64 image payloads are materialized to temp files and passed as `--attachment <path>` (repeatable flag, W-mqv7324u0021db5d). See §10a. |
 | `capabilities.acpWorkerPool` | **`true`** | `copilot --acp` supports the capability-gated CC and fleet worker pools. |
 
@@ -88,7 +88,7 @@ When falling back to the gh-hosted form, the adapter must return:
 { bin: '<path-to-gh.exe>', native: true, leadingArgs: ['copilot'] }
 ```
 
-so that `engine/spawn-agent.js` invokes `gh copilot <flags>` rather than
+so that `engine/agents/spawn-agent.js` invokes `gh copilot <flags>` rather than
 `copilot <flags>`. The availability probe does not guarantee that every
 built-in/extension version accepts the standalone agent flags. The path remains
 best-effort; preflight invokes the resolved command with `leadingArgs` and
@@ -130,7 +130,7 @@ copilot -p $big --output-format json -s --allow-all --no-ask-user --autopilot
 ### Decision
 
 Set `capabilities.promptViaArg = false`. The adapter **does not** emit
-`--prompt <text>` in args; instead, `engine/spawn-agent.js` pipes the final
+`--prompt <text>` in args; instead, `engine/agents/spawn-agent.js` pipes the final
 prompt (system block prepended) via stdin. This:
 
 - Sidesteps the Windows 32 KB ARG_MAX cliff for any prompt that bundles
@@ -176,7 +176,7 @@ Empirically confirmed flags for non-interactive Copilot invocations:
 | `--allow-all` | **required** | Equivalent to `--allow-all-tools --allow-all-paths --allow-all-urls`. Without this the CLI prompts for every tool/path use, which deadlocks in stdin/stdout mode. |
 | `--no-ask-user` | **required** | Removes the `ask_user` tool. Without it the agent can stall waiting for human input. |
 | `--autopilot` | for multi-turn agency | Enables `task_complete`-driven multi-turn loop. **Without it** the session ends after one assistant response (see §3.1). |
-| `--log-level <level>` | **do not emit** | Copilot CLI 1.0.76-1 exits silently with code 1 for explicit non-default levels. Omit the flag and use the CLI default; `--output-format json` still keeps stdout machine-readable. |
+| `--log-level <level>` | **do not emit** | Copilot CLI 1.0.76-1 and 1.0.76-2 exit silently with code 1 for explicit non-default levels. Omit the flag and use the CLI default; `--output-format json` still keeps stdout machine-readable. |
 | `--disable-builtin-mcps` | gated by config | Disables `github-mcp-server`. Default-on for Minions (`copilotDisableBuiltinMcps: true`) to prevent split-brain PR creation. |
 | `--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. |
@@ -187,7 +187,7 @@ Empirically confirmed flags for non-interactive Copilot invocations:
 | `--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 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`. |
+| `--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/agents/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
@@ -198,7 +198,7 @@ Empirically confirmed flags for non-interactive Copilot invocations:
 | no `--autopilot` | `assistant.turn_end` → `result` | One-shot Q&A. Fewer events; no `session.task_complete`, no `session.info`. Closer match for CC / doc-chat use cases that don't need multi-turn. |
 
 The Minions agent path (engine.js dispatch) uses autopilot. CC and doc-chat in
-`engine/llm.js` should also use autopilot — they need tool use even when only
+`engine/agents/llm.js` should also use autopilot — they need tool use even when only
 one assistant turn is expected — but the parser must tolerate the absence of
 `session.task_complete` because some early-exit paths skip it.
 
@@ -652,7 +652,7 @@ 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` and appends `--attachment <path>` per file. `engine/llm.js`
+`opts.tmpDir` and appends `--attachment <path>` per file. `engine/agents/llm.js`
 removes that call-scoped directory after the process settles.
 
 ```js

package/docs/cross-repo-plans.md

@@ -34,7 +34,7 @@ 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:4516-4559` (`extractPlanDeclaredProject` / `extractPlanTargetProjects`) for the exact regexes.
+Both forms accept `,`, `|`, or `;` as separators with surrounding whitespace, and strip surrounding quotes. See `engine/core/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).
 
@@ -136,18 +136,18 @@ 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 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.
+Module-level `_claimedAgents` in `engine/orchestration/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` (`engine/lifecycle.js:26-155`, fan-out at `:279-494`) gates on two conditions:
+`engine/orchestration/lifecycle.js#checkPlanCompletion` (`engine/orchestration/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 `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 (`engine/lifecycle.js:312-494`):
+For each touched project the fan-out (`engine/orchestration/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`).
@@ -165,7 +165,7 @@ The verify agents then run in parallel — one per touched project, each in its
 
 Plan card and detail views surface the cross-repo shape:
 
-- **`i.projects[]` per PRD item + plan `_projects` rollup** (P-e8d49105, `engine/queries.js`) — populated when at least one PRD item carries a `project` field. Plan card uses `_projects.length >= 2` as the gate for cross-repo UI variations.
+- **`i.projects[]` per PRD item + plan `_projects` rollup** (P-e8d49105, `engine/core/queries.js`) — populated when at least one PRD item carries a `project` field. Plan card uses `_projects.length >= 2` as the gate for cross-repo UI variations.
 - **Per-project status rollup pills** (P-66b1faec, `dashboard.js#handlePlansList`) — when `Object.keys(_perProjectProgress).length >= 2`, the plan card meta line renders one pill per project with a per-project completion count (e.g. `minions 3/4 · minions-opg 1/2`). Single-project plans render the legacy aggregate progress bar unchanged.
 - **Per-project verify badges in plan detail** (P-d7e592b1, `dashboard/js/render-plans.js`) — when `verifyWis.length >= 2`, the detail view renders one labelled verify badge per project; single-project plans render the legacy single badge unchanged.
 
@@ -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 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:
+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` declaring the engine-pinned `filename` and the dispatched `work_item`; the engine validates the envelope, imports its `prd` object into SQLite under filename `cross-repo-launch.json`, and consumes the sidecar. The cross-repo filename (`cross-<uid>-<date>.json`) is generated once and then pinned on the work item, so a retry keeps the same expected identity instead of orphaning the previous attempt's result — see [plan-lifecycle.md](plan-lifecycle.md#plan-to-prd-result-sidecar). The imported PRD shape is:
 
 ```json
 {
@@ -258,7 +258,7 @@ 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:4516` (`extractPlanDeclaredProject`), `engine/shared.js:4539` (`extractPlanTargetProjects`) | Both scan first 80 lines; HTML comment marker preferred over `**Projects:**` fallback. |
+| Parse plan markdown projects | `engine/core/shared.js:4516` (`extractPlanDeclaredProject`), `engine/core/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`. |
@@ -267,11 +267,11 @@ When you need to change the cross-repo path, the load-bearing seams are:
 | 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 verify fan-out | `engine/orchestration/lifecycle.js:279-494` (`checkPlanCompletion`) | Group active PRs by project via SQL links; one verify WI per touched project. |
+| Verify WI creation | `engine/orchestration/lifecycle.js:350-410`, `engine/orchestration/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. |
+| `i.projects[]` + plan `_projects` rollup | `engine/core/queries.js:2442-2444`, `dashboard.js:7813-7826` | Populated when at least one PRD item has a `project` field. |
 
 ## Executable spec
 

package/docs/dead-code-audit-retractions.md

@@ -9,12 +9,12 @@ This file records false-positive findings from past dead-code audits so subseque
   "id": "reviewFeedbackSourceMatches-not-dead-exported",
   "retractedOn": "2026-06-03",
   "retractedBy": "Dead Code Review meeting (Lambert, Dallas, Ripley unanimous)",
-  "claim": "engine/lifecycle.js reviewFeedbackSourceMatches is still dead-exported",
-  "correction": "The function is NOT exported (verify: grep `reviewFeedbackSourceMatches` in engine/lifecycle.js module.exports block at :5161-5220 returns zero hits) and IS live-called intra-file at engine/lifecycle.js:2939 inside createReviewFeedbackForAuthor.",
+  "claim": "engine/orchestration/lifecycle.js reviewFeedbackSourceMatches is still dead-exported",
+  "correction": "The function is NOT exported (verify: grep `reviewFeedbackSourceMatches` in engine/orchestration/lifecycle.js module.exports block at :5161-5220 returns zero hits) and IS live-called intra-file at engine/orchestration/lifecycle.js:2939 inside createReviewFeedbackForAuthor.",
   "sources": [
-    "engine/lifecycle.js:2883 (definition)",
-    "engine/lifecycle.js:2939 (live caller inside createReviewFeedbackForAuthor)",
-    "engine/lifecycle.js:5161-5220 (module.exports block — function absent)",
+    "engine/orchestration/lifecycle.js:2883 (definition)",
+    "engine/orchestration/lifecycle.js:2939 (live caller inside createReviewFeedbackForAuthor)",
+    "engine/orchestration/lifecycle.js:5161-5220 (module.exports block — function absent)",
     "knowledge/project-notes/2026-06-03-ripley-meeting-conclusion-dead-code-review-2026-06-03.md",
     "notes/inbox/ripley-2026-06-03-1012.md (R2 retraction)"
   ],