@yemi33/minions 0.1.2447 → 0.1.2449

package/docs/default-branch-ci.md

@@ -0,0 +1,173 @@
+# Default-branch CI (post-merge gate)
+
+Companion to the PR gate. Workflows:
+
+| Workflow | Trigger | Runs |
+|---|---|---|
+| `.github/workflows/pr-tests.yml` | `pull_request` → `main`, `workflow_dispatch`, `workflow_call` | `npm run lint` + `npm test` (blocking) and the perf bucket (non-blocking) |
+| `.github/workflows/default-branch-tests.yml` | `push` → `main`, `workflow_dispatch` | Calls the PR gate, then files/updates a tracking issue on failure |
+
+## Why a post-merge gate is required
+
+A `pull_request` gate proves each branch green **at its own tip**. It cannot
+prove the **merged** tree green, because that tree does not exist until the
+merge lands.
+
+The motivating class of defect is merge-order breakage: two PRs are each green
+in isolation, merge cleanly (no textual conflict), and are broken only in
+combination — one removes an identifier while the other adds a reference to it.
+Nothing in either PR's diff is wrong; the *combination* is. Concretely, the
+incident that produced this workflow left dangling identifier references in a
+module, so every consumer failed at load time. That turned `npm run lint` red
+with `no-undef` errors and cascaded a whole suite off a single load error — on
+PRs whose diffs never touched the code, including a docs-only PR.
+
+Without a post-merge run:
+
+- the first signal is unrelated PRs turning red hours later;
+- the signal is ambiguous, because it appears on diffs that cannot explain it;
+- triage cost lands on whoever opens the next PR, not on the merge that broke it.
+
+The post-merge gate makes the merged tree the thing that is executed, so the
+break is reported against the merge commit that caused it, immediately, and
+independently of anyone opening a PR.
+
+## Reuse direction is load-bearing
+
+`default-branch-tests.yml` **calls** `pr-tests.yml` (`uses:
+./.github/workflows/pr-tests.yml`). The reuse must point that way, not the
+reverse:
+
+- A reusable-workflow *call* renames the resulting check from `Unit Tests` to
+  `<caller job> / Unit Tests`. The branch ruleset on `main` requires the status
+  check context `Unit Tests` **by exact string**, so making the PR gate a caller
+  of a shared workflow would leave every PR waiting on a check that can never
+  report.
+- Copying the job into a second workflow instead of calling it is the other
+  failure mode: the copy drifts, and the post-merge gate quietly stops testing
+  what the PR gate tests — which is the same "nobody executes this combination"
+  hole in a new place.
+
+So the job definition lives once, in `pr-tests.yml`, and the post-merge
+workflow is a thin caller.
+
+## Cost controls
+
+- The non-blocking perf bucket opts out of the post-merge run
+  (`if: ${{ github.event_name != 'push' }}`; inside a called workflow
+  `github.event_name` is the *caller's* event). It is already non-blocking on
+  PRs, so re-running it after the merge buys no gating signal.
+- `concurrency` is keyed on the ref with `cancel-in-progress: true`. The gate
+  answers "is the default branch healthy right now?", and a superseded run's
+  tree is a strict ancestor of the newer one, so a defect that is still present
+  is still caught. The trade-off is deliberate: a defect introduced *and*
+  reverted between two runs is not separately reported.
+- No matrix dimension is added. Runner topology follows the fork
+  (`ubuntu-latest` here; see [distribution.md](distribution.md) for the dual-CI
+  split).
+
+## When it goes red
+
+The failing run is the primary signal. `report-failure` additionally opens — or
+comments on, if one is already open — an issue titled
+`Default branch is red: post-merge gate failing on main`, so the breakage has an
+owner and a place to record the fix-forward-or-revert decision. Lookup is an
+exact-title match over `gh issue list` (a single JSON array, pull requests
+excluded, internally paginated) rather than the search API, which is eventually
+consistent and would file a duplicate on the next failing merge.
+
+Issue filing is scoped to `github.ref == 'refs/heads/main'` so a manual
+`workflow_dispatch` used to exercise the wiring never files an issue.
+
+## Lockfile versions must exist in the self-hosted runner's reachable registry
+
+yemi33's blocking lanes — `pr-tests.yml`'s `Unit Tests (Windows)` and
+`publish.yml`'s `validate` — run on a corporate-managed self-hosted Windows
+host, and that host has two properties that together constrain what the
+committed lockfile is allowed to contain:
+
+1. **`registry.npmjs.org` is unreachable from it.** The connection is rejected
+   during the TLS handshake (`schannel: SEC_E_ILLEGAL_MESSAGE`, npm reports
+   `ERR_SSL_SSL/TLS_ALERT_HANDSHAKE_FAILURE`), not merely proxied.
+2. **npm is pointed at an internal Azure Artifacts mirror** by the machine's
+   user and global `npmrc`. npm's default `replace-registry-host=npmjs` then
+   rewrites every `registry.npmjs.org` tarball URL in the committed lockfile to
+   that mirror at install time, so `resolved` in `package-lock.json` describes
+   intent, not the host actually contacted.
+
+So the self-hosted lane can only install versions the mirror actually carries,
+and a lockfile entry the mirror lacks fails `npm ci` with `E404` — taking down
+the PR gate *and* the npm release, since `validate` gates `publish`.
+
+**Pinning the public registry in CI does not fix this** — not via
+`actions/setup-node`'s `registry-url`, not via `NPM_CONFIG_REGISTRY`, not via
+`npm ci --registry=…`. All three only convert the `E404` into a TLS handshake
+failure, because property 1 is a network-level block. The mirror is the only
+package source that lane has.
+
+A candidate version must therefore satisfy **two** independent constraints:
+it has to exist on the mirror, *and* it has to sit at or above its security
+patch floor. Availability alone is not a sufficient reason to choose a version.
+
+The worked precedent is `brace-expansion`. A transitive dev-dependency bump
+from 1.1.16 to 1.1.18 (opg#1170, backported as yemi33#4299) moved the lockfile
+past the mirror, which serves `1.1.16` but returns 404 for `1.1.17` and
+`1.1.18` while remaining current for everything else. Reverting the lockfile to
+1.1.16 restores `npm ci` — and is **not** an acceptable fix: 1.1.16 is
+vulnerable to GHSA-mh99-v99m-4gvg (CVE-2026-14257, HIGH), whose 1.x patch floor
+is exactly the missing 1.1.17. The org's `GitOps/AdvancedSecurity` dependency
+review correctly fails such a PR with `Dependency review detected vulnerable`,
+and that check is org-managed — it cannot be configured away from this repo.
+
+Comparing the two sides settles it. The mirror's newest per major line was
+`1.1.16 / 2.1.2 / 3.0.2 / 4.0.1 / 5.0.8`; the advisory's patch floors are
+`1.1.17 / 2.1.3 / 3.0.3 / 5.0.8`. Only **5.0.8** satisfies both. But
+`brace-expansion` 5.x exports a named `expand` rather than a callable default,
+so forcing it under `minimatch@3.x` fails at require time with
+`TypeError: expand is not a function` — meaning no `overrides` entry on
+`brace-expansion` alone can work.
+
+The fix is to move the *parent*. `eslint@10` drops `@eslint/eslintrc` and
+depends on `minimatch@^10.2.5`, which in turn depends on
+`brace-expansion@^5.0.5` and resolves to the patched, mirror-available 5.0.8.
+So the tree lands on a non-vulnerable version by ordinary resolution, with **no
+`overrides` entry at all** — nothing forced against a declared range, and
+nothing for Dependabot to re-propose and re-break.
+
+The rule to carry forward: when the mirror lacks a version, do not pin below a
+security patch floor to buy availability. Find a version that satisfies both,
+upgrading the dependency's parent when the compatible-and-patched version lives
+in a newer major. If no such version exists, escalate to the mirror owners to
+have the patched version stocked rather than shipping a known-vulnerable pin.
+Confirm availability from the runner host with
+`npm view <pkg> versions --json`, and check the floor against the advisory
+(`gh api /advisories/<GHSA-id>`).
+
+## Merge queue: evaluated, deliberately not implemented
+
+A GitHub merge queue is the strictly stronger answer to this defect class: it
+builds the *prospective* merged result and tests it **before** it lands, so a
+merge-order break is **prevented** rather than detected after the fact. It was
+evaluated and rejected for now on three repo-specific grounds:
+
+1. **It would be routinely bypassed.** Merges here are performed with
+   `gh pr merge --admin` (the documented policy for this repo, and what the
+   engine's auto-merge path uses). Administrative merges bypass the queue
+   entirely, so the queue would give assurance it is not actually providing —
+   worse than an honest post-merge gate. Adopting a queue therefore requires
+   first changing how merges are performed, which is a policy change, not a CI
+   change.
+2. **Cost and latency.** A queue runs a full CI pass per queued PR against a
+   speculative merge commit. This repository merges frequently (agent PRs,
+   scheduled review PRs, dependabot), so the queue would multiply full runs and
+   serialize merges behind an ~8-minute lint + unit pass.
+3. **It is not free to wire correctly.** The required check must also report on
+   `merge_group` events; if the workflow does not trigger on `merge_group`, the
+   queue stalls indefinitely waiting for a check that never runs. That is a
+   sharper failure mode than the one being fixed and deserves its own change.
+
+The post-merge gate is cheap, correct regardless of merge method (including
+`--admin`), and closes the *detection* hole today. Revisit the merge queue if
+and when administrative-bypass merging stops being the norm; at that point this
+workflow's job-reuse structure is already the piece a `merge_group` trigger
+would hang off.

package/docs/deprecated.json

@@ -4,17 +4,17 @@
     "description": "Legacy per-agent descriptive-metadata array `agents.<id>.skills` in config.json, renamed to `agents.<id>.expertise` to remove the name collision with executable runtime/harness skills (SKILL.md). The tags appear in the agent identity prompt and provide a soft preference to `pickReReviewAgentHints` when selecting a re-reviewer; they are not hard routing constraints. A read-compat shim honors the old key so operator configs still carrying `skills` (and no `expertise`) keep working.",
     "code": [
       {
-        "file": "engine/playbook.js",
+        "file": "engine/agents/playbook.js",
         "lines": "1094",
         "note": "buildSystemPrompt reads `agent.expertise ?? agent.skills ?? []` for the `Expertise:` identity line"
       },
       {
-        "file": "engine/lifecycle.js",
+        "file": "engine/orchestration/lifecycle.js",
         "lines": "5317-5321",
         "note": "pickReReviewAgentHints reads `agent.expertise` with an `agent.skills` array fallback"
       },
       {
-        "file": "engine/queries.js",
+        "file": "engine/core/queries.js",
         "lines": "830-832",
         "note": "getAgents normalizes `expertise: a.expertise ?? a.skills ?? []` so the dashboard/settings UI always receives `expertise`"
       },
@@ -26,19 +26,19 @@
     ],
     "removalGate": "Telemetry / a config sweep across all known engines must show no persisted `config.agents.<id>.skills` key (only `expertise`) for >=30 consecutive days, confirming every operator config has been re-saved through the dashboard (which drops the legacy key) or hand-migrated.",
     "targetRemovalDate": "2026-09-17",
-    "notes": "Safe to remove on or after 2026-09-17 (~3 release windows) once the removal gate clears. Removal scope: drop the `?? agent.skills` / `?? a.skills` fallbacks in engine/playbook.js:1094, engine/lifecycle.js:5317-5319, and engine/queries.js:832; drop the `updates.skills` legacy branch + `delete config.agents[id].skills` in dashboard.js:11245-11252; and update docs/named-agents.md to stop mentioning the legacy key. Does NOT touch the unrelated executable-skills system (queries.js harnesses, runtime adapters, dashboard renderSkills, SKILL.md tooling)."
+    "notes": "Safe to remove on or after 2026-09-17 (~3 release windows) once the removal gate clears. Removal scope: drop the `?? agent.skills` / `?? a.skills` fallbacks in engine/agents/playbook.js:1094, engine/orchestration/lifecycle.js:5317-5319, and engine/core/queries.js:832; drop the `updates.skills` legacy branch + `delete config.agents[id].skills` in dashboard.js:11245-11252; and update docs/named-agents.md to stop mentioning the legacy key. Does NOT touch the unrelated executable-skills system (queries.js harnesses, runtime adapters, dashboard renderSkills, SKILL.md tooling)."
   },
   {
     "id": "config-poll-key-migration",
-    "location": "engine/queries.js:126-163",
+    "location": "engine/core/queries.js:126-163",
     "function": "migrateDeprecatedConfigPollKeysOnce",
     "reason": "One-time boot migration that renames legacy engine config keys (adoPollStatusEvery → prPollStatusEvery, adoPollCommentsEvery → prPollCommentsEvery). Keys were renamed on 2026-04-16; this shim ensures any persisted config.json on a long-lived host gets transparently rewritten on next boot.",
     "targetRemovalDate": "2026-08-09",
-    "notes": "Safe to delete on or after 2026-08-09 (3 months after the rename) once we are confident every engine has rebooted at least once and the closure-flagged migration (_configPollKeyMigrationChecked at line 124) is no longer reachable on any persisted config. Removal is one function + the call site in getConfig() at engine/queries.js:166."
+    "notes": "Safe to delete on or after 2026-08-09 (3 months after the rename) once we are confident every engine has rebooted at least once and the closure-flagged migration (_configPollKeyMigrationChecked at line 124) is no longer reachable on any persisted config. Removal is one function + the call site in getConfig() at engine/core/queries.js:166."
   },
   {
     "id": "legacy-done-aliases",
-    "location": "engine/cleanup.js:1165-1166",
+    "location": "engine/orchestration/cleanup.js:1165-1166",
     "constants": [
       "LEGACY_DONE_ALIASES",
       "LEGACY_NEEDS_REVIEW_STATUS"
@@ -46,7 +46,7 @@
     "reason": "Read-side tolerance: cleanup sweep auto-migrates four obsolete work-item / PRD status strings ('in-pr', 'implemented', 'complete', 'needs-human-review') to the canonical 'done' / 'failed' values. The aliases are no longer written anywhere in the engine; the constants exist only to repair stale SQL records imported from old engine versions.",
     "status": "active",
     "targetRemovalDate": null,
-    "notes": "Keep indefinitely until telemetry shows zero migrations for 30 consecutive days across all project scopes and PRDs. At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js can be deleted."
+    "notes": "Keep indefinitely until telemetry shows zero migrations for 30 consecutive days across all project scopes and PRDs. At that point the constants and both _migrateLegacyItem branches in engine/orchestration/cleanup.js can be deleted."
   },
   {
     "id": "config-claude-binary-override",
@@ -58,17 +58,17 @@
         "note": "resolveBinary() respects config.claude.binary on every Claude spawn (probes npm package dir or direct binary path)"
       },
       {
-        "file": "engine/shared.js",
+        "file": "engine/core/shared.js",
         "lines": "2482-2496",
         "note": "warnings.push({ id: 'deprecated-config-claude' }) — surface-only; never deletes the override"
       },
       {
-        "file": "engine/shared.js",
+        "file": "engine/core/shared.js",
         "lines": "3120-3124",
         "note": "DEFAULT_CLAUDE.binary baseline that the warning + prune logic compares against"
       }
     ],
-    "removalGate": "Telemetry: the `deprecated-config-claude` warning emitted at engine/shared.js:2492-2495 must report zero hits across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must show no `config.claude.binary` value that diverges from DEFAULT_CLAUDE.binary. Only then is the override branch in resolveBinary() (engine/runtimes/claude.js:82-86) removable, along with the `_deprecatedConfigClaudeFields` membership for `binary` and the warning emitter at engine/shared.js:2482-2496.",
+    "removalGate": "Telemetry: the `deprecated-config-claude` warning emitted at engine/core/shared.js:2492-2495 must report zero hits across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must show no `config.claude.binary` value that diverges from DEFAULT_CLAUDE.binary. Only then is the override branch in resolveBinary() (engine/runtimes/claude.js:82-86) removable, along with the `_deprecatedConfigClaudeFields` membership for `binary` and the warning emitter at engine/core/shared.js:2482-2496.",
     "status": "active",
     "targetRemovalDate": null,
     "notes": "Do NOT set targetRemovalDate — removal must be signal-gated, not calendar-gated. This entry is paired with `prune-default-claude-config`: the prune strips DEFAULT-matching values but intentionally preserves user overrides, which is precisely why the override branch in claude.js stays reachable. Removing the override before the prune entry's gate clears would silently break installs that still rely on a custom binary path."
@@ -78,12 +78,12 @@
     "description": "applyLegacyCcModelMigration: in-memory shim that promotes legacy `engine.ccModel` to `engine.defaultModel` when defaultModel is unset, so single-model installs keep working after the runtime fleet refactor (P-3b8e5f1d). No on-disk rewrite — the persisted config.json continues to carry the legacy `ccModel` field. Called unconditionally on every engine boot from cli.start().",
     "code": [
       {
-        "file": "engine/shared.js",
+        "file": "engine/core/shared.js",
         "lines": "2407",
         "note": "applyLegacyCcModelMigration definition (function signature + once-per-process flag via _resetLegacyCcModelMigrationFlag)"
       },
       {
-        "file": "engine/cli.js",
+        "file": "engine/operations/cli.js",
         "lines": "477",
         "note": "Boot call site inside start(); wrapped in try/catch so a migration failure cannot block startup"
       },
@@ -113,7 +113,7 @@
         "note": "Source-inspection test pinning the cli.js boot call site"
       }
     ],
-    "removalGate": "Telemetry: the once-per-boot deprecation log line emitted by applyLegacyCcModelMigration (via the injected logger at engine/shared.js:2407) must show zero promotion events across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must confirm no `engine.ccModel` field remains. Once both conditions hold, removal deletes the function + _resetLegacyCcModelMigrationFlag export at engine/shared.js:4977, the boot call at engine/cli.js:477, the CLAUDE.md:316 paragraph and docs/slim-ux/concepts.md:671 reference, and the tests at runtime-fleet-helpers.test.js:209-254 + :500-505 + unit.test.js:19801.",
+    "removalGate": "Telemetry: the once-per-boot deprecation log line emitted by applyLegacyCcModelMigration (via the injected logger at engine/core/shared.js:2407) must show zero promotion events across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must confirm no `engine.ccModel` field remains. Once both conditions hold, removal deletes the function + _resetLegacyCcModelMigrationFlag export at engine/core/shared.js:4977, the boot call at engine/operations/cli.js:477, the CLAUDE.md:316 paragraph and docs/slim-ux/concepts.md:671 reference, and the tests at runtime-fleet-helpers.test.js:209-254 + :500-505 + unit.test.js:19801.",
     "status": "active",
     "targetRemovalDate": null,
     "notes": "Do NOT set targetRemovalDate — gating is signal-based. The function is silent on no-op (returns false without logging), so the meaningful telemetry signal is the absence of the promotion log line over the sweep window, NOT the absence of function invocations (cli.js calls it every boot regardless)."
@@ -123,12 +123,12 @@
     "description": "pruneDefaultClaudeConfig: active sanitizer that strips generated `config.claude.{binary,outputFormat,allowedTools,permissionMode}` defaults from persisted config.json so the `deprecated-config-claude` warning stops tripping on stale defaults left by older `minions init` versions. Sub-cluster of `config-claude-binary-override` — the prune deliberately preserves non-default user overrides (binary/allowedTools), which is what keeps the override branch in engine/runtimes/claude.js load-bearing.",
     "code": [
       {
-        "file": "engine/shared.js",
+        "file": "engine/core/shared.js",
         "lines": "3126",
         "note": "pruneDefaultClaudeConfig definition: preserves non-default binary/allowedTools, always strips permissionMode + outputFormat"
       },
       {
-        "file": "engine/shared.js",
+        "file": "engine/core/shared.js",
         "lines": "5673",
         "note": "Module export entry"
       },
@@ -168,24 +168,24 @@
         "note": "Source-inspection test pinning the dashboard handler call site"
       }
     ],
-    "removalGate": "Telemetry: pruneDefaultClaudeConfig must return false (no mutation) for every call across all known engines for >=30 consecutive days (add an `_engine.pruneDefaultClaudeConfigStrips` counter if needed to observe this), AND the parent `config-claude-binary-override` entry must have already cleared its own gate. The dependency is strict: removing the prune while users still rely on the override branch would surface the `deprecated-config-claude` warning on every stale generated default. Once both conditions hold, removal is the function definition (engine/shared.js:3126), the export at :5673, all 5 call sites (dashboard.js:202, :9116, :9331, :9450; minions.js:385), and the tests at unit.test.js:2260-2303 + runtime-fleet-helpers.test.js:546.",
+    "removalGate": "Telemetry: pruneDefaultClaudeConfig must return false (no mutation) for every call across all known engines for >=30 consecutive days (add an `_engine.pruneDefaultClaudeConfigStrips` counter if needed to observe this), AND the parent `config-claude-binary-override` entry must have already cleared its own gate. The dependency is strict: removing the prune while users still rely on the override branch would surface the `deprecated-config-claude` warning on every stale generated default. Once both conditions hold, removal is the function definition (engine/core/shared.js:3126), the export at :5673, all 5 call sites (dashboard.js:202, :9116, :9331, :9450; minions.js:385), and the tests at unit.test.js:2260-2303 + runtime-fleet-helpers.test.js:546.",
     "status": "active",
     "targetRemovalDate": null,
     "notes": "Do NOT set targetRemovalDate — gating is signal-based AND ordered. This entry MUST NOT be removed before `config-claude-binary-override` clears its gate, otherwise installs with stale defaults will flood the deprecation channel until their next config save. The 5 call sites form a complete coverage net: load (dashboard.js:202 + minions.js:385) + save (dashboard.js:9116/9331/9450), so any code path that touches config.json runs the sanitizer."
   },
   {
     "id": "ado-throttle-arg-less-shim",
-    "description": "Arg-less form of isAdoThrottled() in engine/ado.js. Introduced by W-mq03l6zh0006f0a1-b as a back-compat shim during the per-org ADO throttle isolation rollout: pre-rollout, isAdoThrottled() collapsed the single process-global tracker to one boolean; post-rollout, the canonical form is isAdoThrottled(orgBase) against the per-org Map. The arg-less call site is preserved transiently so engine code (and any in-process callers) that haven't yet been threaded through with a per-org `orgBase` keep returning the safe global-OR (true if ANY org is currently throttled) — preventing a regression where new poll work bypasses a still-warm throttle backoff on an unrelated noisy org.",
+    "description": "Arg-less form of isAdoThrottled() in engine/ado/index.js. Introduced by W-mq03l6zh0006f0a1-b as a back-compat shim during the per-org ADO throttle isolation rollout: pre-rollout, isAdoThrottled() collapsed the single process-global tracker to one boolean; post-rollout, the canonical form is isAdoThrottled(orgBase) against the per-org Map. The arg-less call site is preserved transiently so engine code (and any in-process callers) that haven't yet been threaded through with a per-org `orgBase` keep returning the safe global-OR (true if ANY org is currently throttled) — preventing a regression where new poll work bypasses a still-warm throttle backoff on an unrelated noisy org.",
     "deprecated": "2026-06-04",
     "status": "removed",
     "removedDate": "2026-06-25",
     "code": [
       {
-        "file": "engine/ado.js",
+        "file": "engine/ado/index.js",
         "note": "isAdoThrottled() arg-less branch and the global-OR fold over the per-org Map. Single call site to migrate: shared.getAdoOrgBase(project) is already in scope at every consumer."
       }
     ],
-    "removalGate": "Two conditions must hold simultaneously: (a) grep `engine/ado.js` for `isAdoThrottled\\s*\\(\\s*\\)` and confirm zero arg-less call sites remain across the engine — every caller passes a concrete `orgBase` resolved via `shared.getAdoOrgBase(project)`; (b) `GET /api/diagnostics/ado-throttle` on a live engine has been observed for >=2 consecutive weeks reporting per-org keys (proves the per-org Map is populated under load and the global-OR isn't masking a regression). Once both hold, removal deletes the arg-less branch in isAdoThrottled and the global-OR fold; callers that still pass no argument become an immediate, surfaced bug rather than a silent over-throttle.",
+    "removalGate": "Two conditions must hold simultaneously: (a) grep `engine/ado/index.js` for `isAdoThrottled\\s*\\(\\s*\\)` and confirm zero arg-less call sites remain across the engine — every caller passes a concrete `orgBase` resolved via `shared.getAdoOrgBase(project)`; (b) `GET /api/diagnostics/ado-throttle` on a live engine has been observed for >=2 consecutive weeks reporting per-org keys (proves the per-org Map is populated under load and the global-OR isn't masking a regression). Once both hold, removal deletes the arg-less branch in isAdoThrottled and the global-OR fold; callers that still pass no argument become an immediate, surfaced bug rather than a silent over-throttle.",
     "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."
   },
@@ -194,11 +194,11 @@
     "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'.",
     "code": [
       {
-        "file": "engine/shared.js",
+        "file": "engine/core/shared.js",
         "note": "resolveCheckoutMode reads project.worktreeMode as the fallback when checkoutMode is absent; validateCheckoutMode coerces 'isolated'→'worktree'. The only surviving reads of the legacy field are these two back-compat bridges."
       },
       {
-        "file": "engine/projects.js",
+        "file": "engine/planning/projects.js",
         "note": "addProject threads options.checkoutMode ?? options.worktreeMode into buildProjectEntry (accepts the legacy options key)."
       },
       {
@@ -226,13 +226,13 @@
   },
   {
     "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.",
+    "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/orchestration/lifecycle.js during the skill-system consolidation.",
     "code": [],
     "deprecated": "2026-06-29",
     "status": "removed",
     "removedDate": "2026-06-29",
     "targetRemovalDate": null,
-    "notes": "engine/discover-review-skills.js does not exist on disk. The functionality was folded into engine/lifecycle.js skill extraction. No callers remain."
+    "notes": "engine/discover-review-skills.js does not exist on disk. The functionality was folded into engine/orchestration/lifecycle.js skill extraction. No callers remain."
   },
   {
     "id": "discover-review-skills-shim",
@@ -254,12 +254,12 @@
     "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",
+        "file": "engine/orchestration/routing.js",
         "lines": "normalizeWorkType",
         "note": "Maps legacy work-item type `build-and-test` to WORK_TYPE.TEST."
       },
       {
-        "file": "engine/shared.js",
+        "file": "engine/core/shared.js",
         "lines": "normalizeLiveValidationWorkType",
         "note": "Normalizes persisted liveValidation.type values before routing and validation."
       }
@@ -294,7 +294,7 @@
         "note": "Codex-specific legacy wrapper flag emitter."
       },
       {
-        "file": "engine/spawn-agent.js",
+        "file": "engine/agents/spawn-agent.js",
         "lines": "parseSpawnArgs",
         "note": "Parses each historical named adapter option in addition to the canonical `--runtime-options` payload."
       }
@@ -302,7 +302,7 @@
     "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.",
+    "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/agents/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."
@@ -337,10 +337,10 @@
   },
   {
     "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.",
+    "description": "Legacy exported helper name from before workspace preparation moved behind the runtime adapter contract. engine/agents/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",
+        "file": "engine/agents/spawn-agent.js",
         "lines": "preApproveWorkspaceMcps and module.exports",
         "note": "Backward-compatible wrapper and export; no production engine call site remains."
       },
@@ -359,7 +359,7 @@
     "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.",
+    "removalScope": "Delete preApproveWorkspaceMcps and its module.exports entry from engine/agents/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/design-inbox-entries-schema.md

@@ -1,7 +1,7 @@
 # inbox_entries Table Schema
 
 ## Overview
-The `inbox_entries` table and `engine/inbox-store.js` implement a persistent, time-ordered, unread-tracking message queue decoupled from the runtime work-item/dispatch lifecycle. The store API exists, but production engine, dashboard, and consolidation paths do not consume it yet; those paths still use their existing inbox mechanisms.
+The `inbox_entries` table and `engine/persistence/inbox-store.js` implement a persistent, time-ordered, unread-tracking message queue decoupled from the runtime work-item/dispatch lifecycle. The store API exists, but production engine, dashboard, and consolidation paths do not consume it yet; those paths still use their existing inbox mechanisms.
 
 ## Schema Specification
 
@@ -61,7 +61,7 @@ The `inbox_entries` table and `engine/inbox-store.js` implement a persistent, ti
 
 ### Integration Status
 
-The table currently has no foreign keys and `engine/inbox-store.js` has no production callers. Dispatch feedback, PR notifications, dashboard inbox views, and consolidation are potential consumers, not implemented relationships. Until those call sites migrate, this table is not the source of truth for `notes/inbox/` or agent steering inbox files.
+The table currently has no foreign keys and `engine/persistence/inbox-store.js` has no production callers. Dispatch feedback, PR notifications, dashboard inbox views, and consolidation are potential consumers, not implemented relationships. Until those call sites migrate, this table is not the source of truth for `notes/inbox/` or agent steering inbox files.
 
 ## Performance Considerations
 
@@ -94,5 +94,5 @@ The table currently has no foreign keys and `engine/inbox-store.js` has no produ
 ## Related Code
 
 - **Schema:** `engine/db/migrations/019-inbox-entries.js`.
-- **Store:** `engine/inbox-store.js` (reads, transactional mutators, and best-effort `emitStateEvent('inbox', ...)` after real changes).
+- **Store:** `engine/persistence/inbox-store.js` (reads, transactional mutators, and best-effort `emitStateEvent('inbox', ...)` after real changes).
 - **Consumers:** none in production yet.