@yemi33/minions 0.1.2268 → 0.1.2270

package/dashboard/js/render-dispatch.js

@@ -103,7 +103,11 @@ function renderEngineStatus(engine) {
   // against a possibly-cached heartbeat — the bug pattern that produced false-
   // positive STALE banners after control.json was dropped from the mtime tracker.
   const staleMs = engine?.heartbeatAgeMs || 0;
-  if (state === 'running' && engine?.heartbeatStale) state = 'stale';
+  // Map running→stale and degraded→stale when both heartbeat signals are stale.
+  // degraded is set by the dashboard watchdog (issue #423) when the engine PID
+  // is alive but the tick loop is frozen; treat it identically to stale so the
+  // Restart Engine banner fires in both cases.
+  if ((state === 'running' || state === 'degraded') && engine?.heartbeatStale) state = 'stale';
 
   // Clear restart grace as soon as the engine reports a fresh heartbeat — the
   // new engine has caught up, so STALE/restart banners should vanish.

package/dashboard.js

@@ -5951,6 +5951,35 @@ function restartEngine() {
   return newPid;
 }
 
+// ── Frozen-engine detection (issue #423) ─────────────────────────────────────
+// Called by the 30s watchdog when the engine PID is still alive. If both
+// control.heartbeat AND control.lastTickAt have aged past their thresholds,
+// the tick loop is frozen (event-loop blocked). Flip state to 'degraded' so:
+//   • The dashboard UI surfaces a hard warning with a Restart Engine button.
+//   • When the engine eventually unhangs, tickInner reads state !== 'running'
+//     and calls process.exit(0); the PID-dead watchdog then auto-restarts it.
+// The restarted engine reclaims state:'running' on its next boot.
+// Returns true if it wrote the degraded state, false otherwise.
+function _markEngineAsDegradedIfFrozen() {
+  const control = getEngineState();
+  if (control.state !== 'running' || !control.pid) return false;
+
+  const hbAge = control.heartbeat ? Date.now() - control.heartbeat : 0;
+  const tickInterval = Number(CONFIG?.engine?.tickInterval) || shared.ENGINE_DEFAULTS.tickInterval;
+  const tickStaleThresholdMs = Math.max(ENGINE_HEARTBEAT_STALE_MS, 2 * tickInterval);
+  const tickAge = control.lastTickAt ? Date.now() - control.lastTickAt : Infinity;
+
+  const bothStale = !!(control.heartbeat
+    && hbAge > ENGINE_HEARTBEAT_STALE_MS
+    && tickAge > tickStaleThresholdMs);
+  if (!bothStale) return false;
+
+  shared.mutateControl(c => ({ ...c, state: 'degraded' }));
+  console.log(`[watchdog] Engine tick frozen (heartbeat ${Math.round(hbAge / 1000)}s old, last tick ${Math.round(tickAge / 1000)}s old) — marking state as degraded`);
+  try { invalidateStatusCache(); } catch { /* best effort */ }
+  return true;
+}
+
 // -- Server --
 
 // Mutating HTTP methods that require Origin and Content-Type gating.
@@ -14415,6 +14444,8 @@ module.exports = {
   // staleness verdict it stamps on engine.heartbeatStale is the contract under
   // test. No production caller imports this; it is a test seam.
   _buildStatusFastState,
+  // #423 — exported for unit testing the frozen-engine watchdog logic.
+  _markEngineAsDegradedIfFrozen,
   // W-mq5xg5e9000nec0e — exported for direct unit testing of the slim shape
   // produced by GET /api/work-items. Production callers go through the
   // route's `builder` closure (getWorkItems().map(slimWorkItemForList)).
@@ -14643,6 +14674,8 @@ if (require.main === module) {
         if (!alive) {
           console.log(`[watchdog] Engine PID ${control.pid} is dead — auto-restarting...`);
           restartEngine();
+        } else {
+          _markEngineAsDegradedIfFrozen();
         }
       } catch (e) {
         console.error(`[watchdog] Error: ${e.message}`);

package/docs/deprecated.json

@@ -3,10 +3,26 @@
     "id": "agent-config-skills-field",
     "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 field is metadata only (capability tags like `architecture`, `bug-fixes`); nothing in the dispatch path reads it for behavior. A read-compat shim honors the old key so operator configs still carrying `skills` (and no `expertise`) keep working.",
     "code": [
-      { "file": "engine/playbook.js", "lines": "950", "note": "buildSystemPrompt reads `agent.expertise ?? agent.skills ?? []` for the `Expertise:` identity line" },
-      { "file": "engine/lifecycle.js", "lines": "4620-4621", "note": "pickReReviewAgentHints reads `agent.expertise` with an `agent.skills` array fallback" },
-      { "file": "engine/queries.js", "lines": "731", "note": "getAgents normalizes `expertise: a.expertise ?? a.skills ?? []` so the dashboard/settings UI always receives `expertise`" },
-      { "file": "dashboard.js", "lines": "10708-10716", "note": "settings POST accepts a legacy `updates.skills` key, persists as `config.agents[id].expertise`, and deletes the old `skills` key" }
+      {
+        "file": "engine/playbook.js",
+        "lines": "950",
+        "note": "buildSystemPrompt reads `agent.expertise ?? agent.skills ?? []` for the `Expertise:` identity line"
+      },
+      {
+        "file": "engine/lifecycle.js",
+        "lines": "4620-4621",
+        "note": "pickReReviewAgentHints reads `agent.expertise` with an `agent.skills` array fallback"
+      },
+      {
+        "file": "engine/queries.js",
+        "lines": "731",
+        "note": "getAgents normalizes `expertise: a.expertise ?? a.skills ?? []` so the dashboard/settings UI always receives `expertise`"
+      },
+      {
+        "file": "dashboard.js",
+        "lines": "10708-10716",
+        "note": "settings POST accepts a legacy `updates.skills` key, persists as `config.agents[id].expertise`, and deletes the old `skills` key"
+      }
     ],
     "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",
@@ -31,7 +47,10 @@
   {
     "id": "legacy-done-aliases",
     "location": "engine/cleanup.js:1165-1166",
-    "constants": ["LEGACY_DONE_ALIASES", "LEGACY_NEEDS_REVIEW_STATUS"],
+    "constants": [
+      "LEGACY_DONE_ALIASES",
+      "LEGACY_NEEDS_REVIEW_STATUS"
+    ],
     "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 on-disk values from old engine versions.",
     "targetRemovalDate": null,
     "notes": "Keep indefinitely until telemetry / a sweep log shows zero migrations performed for 30 consecutive days across all known projects (work-items.json + prd/*.json). At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js (definitions at :1165-1166; usage at :1168-1183 for work items and :1269-1272 for PRD missing_features) can be deleted. Total cost on disk today: 4 strings."
@@ -40,9 +59,21 @@
     "id": "config-claude-binary-override",
     "description": "Legacy `config.claude.binary` runtime-resolution override. Older `minions init` versions persisted a `config.claude.binary` field that pointed the Claude runtime at a specific binary path. The runtime adapter still honors this override on every Claude spawn; the engine emits a `deprecated-config-claude` warning at config-load time but does NOT delete the override, so the override branch in claude.js is load-bearing for any install that still carries a non-default value.",
     "code": [
-      { "file": "engine/runtimes/claude.js", "lines": "82-86", "note": "resolveBinary() respects config.claude.binary on every Claude spawn (probes npm package dir or direct binary path)" },
-      { "file": "engine/shared.js", "lines": "2482-2496", "note": "warnings.push({ id: 'deprecated-config-claude' }) — surface-only; never deletes the override" },
-      { "file": "engine/shared.js", "lines": "3120-3124", "note": "DEFAULT_CLAUDE.binary baseline that the warning + prune logic compares against" }
+      {
+        "file": "engine/runtimes/claude.js",
+        "lines": "82-86",
+        "note": "resolveBinary() respects config.claude.binary on every Claude spawn (probes npm package dir or direct binary path)"
+      },
+      {
+        "file": "engine/shared.js",
+        "lines": "2482-2496",
+        "note": "warnings.push({ id: 'deprecated-config-claude' }) — surface-only; never deletes the override"
+      },
+      {
+        "file": "engine/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.",
     "targetRemovalDate": null,
@@ -52,13 +83,41 @@
     "id": "legacy-cc-model-migration",
     "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", "lines": "2407", "note": "applyLegacyCcModelMigration definition (function signature + once-per-process flag via _resetLegacyCcModelMigrationFlag)" },
-      { "file": "engine/cli.js", "lines": "477", "note": "Boot call site inside start(); wrapped in try/catch so a migration failure cannot block startup" },
-      { "file": "CLAUDE.md", "lines": "316", "note": "Architectural documentation calling out the in-memory promotion contract" },
-      { "file": "docs/slim-ux/concepts.md", "lines": "671", "note": "Surface-level concepts doc cross-reference" },
-      { "file": "test/unit.test.js", "lines": "19801", "note": "Source-inspection test pinning the CLAUDE.md description against the function name" },
-      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "209-254", "note": "Behavioural unit tests (promotion, no-op when defaultModel set, no-op when ccModel unset, empty-string handling, once-only logging, null-safety)" },
-      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "500-505", "note": "Source-inspection test pinning the cli.js boot call site" }
+      {
+        "file": "engine/shared.js",
+        "lines": "2407",
+        "note": "applyLegacyCcModelMigration definition (function signature + once-per-process flag via _resetLegacyCcModelMigrationFlag)"
+      },
+      {
+        "file": "engine/cli.js",
+        "lines": "477",
+        "note": "Boot call site inside start(); wrapped in try/catch so a migration failure cannot block startup"
+      },
+      {
+        "file": "CLAUDE.md",
+        "lines": "316",
+        "note": "Architectural documentation calling out the in-memory promotion contract"
+      },
+      {
+        "file": "docs/slim-ux/concepts.md",
+        "lines": "671",
+        "note": "Surface-level concepts doc cross-reference"
+      },
+      {
+        "file": "test/unit.test.js",
+        "lines": "19801",
+        "note": "Source-inspection test pinning the CLAUDE.md description against the function name"
+      },
+      {
+        "file": "test/unit/runtime-fleet-helpers.test.js",
+        "lines": "209-254",
+        "note": "Behavioural unit tests (promotion, no-op when defaultModel set, no-op when ccModel unset, empty-string handling, once-only logging, null-safety)"
+      },
+      {
+        "file": "test/unit/runtime-fleet-helpers.test.js",
+        "lines": "500-505",
+        "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.",
     "targetRemovalDate": null,
@@ -68,14 +127,39 @@
     "id": "sql-state-json-mirrors",
     "description": "Phase X.5 follow-up to the SQL state migration (commits 62bd6a2c..1111cf54, phases 0–7). Every engine state file that previously used mutateJsonFileLocked now routes through a SQL store, but each store still writes a JSON dual-write mirror after every mutation because a handful of direct-readers (a few unit tests + a couple of inline safeJson calls) have not been migrated to the SQL read path. Once those readers are confirmed routed through the SQL store (or rewritten to use the store's read helper), the mirror writers can be deleted and the JSON files retired.",
     "code": [
-      { "file": "engine/dispatch-store.js", "note": "_mirrorJsonFromSql + _readDispatchJsonFallback — used when SQL is empty AND JSON has content (test seeding + first-time hydrate)" },
-      { "file": "engine/work-items-store.js", "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope) — same fallback contract as dispatch-store" },
-      { "file": "engine/pull-requests-store.js", "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope)" },
-      { "file": "engine/logs-store.js", "note": "engine/log.json mirror written by shared._flushLogBuffer's byJsonPath loop — Phase 4.5 will retire" },
-      { "file": "engine/metrics-store.js", "note": "_mirrorJsonFromSql + _readJsonObjectFallback" },
-      { "file": "engine/watches-store.js", "note": "_mirrorJsonFromSql + _readJsonArrayFallback" },
-      { "file": "engine/small-state-store.js", "note": "_mirrorScheduleRunsJson, _mirrorPipelineRunsJson, _mirrorManagedProcessesJson, _mirrorWorktreePoolJson + each store's _readJson fallback path" },
-      { "file": "CLAUDE.md", "lines": "47-66, 240-265", "note": "State Files + Concurrency sections still describe JSON files as the source of truth; they describe a layered SQLite-then-mirror reality in places but the headline contract still reads as JSON-primary. Rewrite these sections to make SQL-as-source-of-truth the headline and the JSON mirrors a transitional compatibility detail." }
+      {
+        "file": "engine/dispatch-store.js",
+        "note": "_mirrorJsonFromSql + _readDispatchJsonFallback — used when SQL is empty AND JSON has content (test seeding + first-time hydrate)"
+      },
+      {
+        "file": "engine/work-items-store.js",
+        "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope) — same fallback contract as dispatch-store"
+      },
+      {
+        "file": "engine/pull-requests-store.js",
+        "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope)"
+      },
+      {
+        "file": "engine/logs-store.js",
+        "note": "engine/log.json mirror written by shared._flushLogBuffer's byJsonPath loop — Phase 4.5 will retire"
+      },
+      {
+        "file": "engine/metrics-store.js",
+        "note": "_mirrorJsonFromSql + _readJsonObjectFallback"
+      },
+      {
+        "file": "engine/watches-store.js",
+        "note": "_mirrorJsonFromSql + _readJsonArrayFallback"
+      },
+      {
+        "file": "engine/small-state-store.js",
+        "note": "_mirrorScheduleRunsJson, _mirrorPipelineRunsJson, _mirrorManagedProcessesJson, _mirrorWorktreePoolJson + each store's _readJson fallback path"
+      },
+      {
+        "file": "CLAUDE.md",
+        "lines": "47-66, 240-265",
+        "note": "State Files + Concurrency sections still describe JSON files as the source of truth; they describe a layered SQLite-then-mirror reality in places but the headline contract still reads as JSON-primary. Rewrite these sections to make SQL-as-source-of-truth the headline and the JSON mirrors a transitional compatibility detail."
+      }
     ],
     "removalGate": "All direct-readers of the mirror JSON files must be confirmed routed through their respective SQL store's read helper. Specifically: (a) grep the codebase for `safeJson`, `safeJsonArr`, `safeJsonObj`, `readFileSync(...work-items.json|pull-requests.json|metrics.json|watches.json|schedule-runs.json|pipeline-runs.json|managed-processes.json|worktree-pool.json|log.json|dispatch.json...)` and confirm every hit is either (i) a test fixture that can move to the SQL helper, or (ii) intentionally documented as bypassing SQL. (b) Run the full test suite with each store's _mirrorJsonFromSql temporarily neutered (returning early before safeWrite) and confirm 0 failures — that proves no production code path depends on the mirror. Once both conditions hold, removal deletes each store's _mirrorJsonFromSql call site in shared.js (mutateWorkItems/mutatePullRequests/etc.), the corresponding _readJsonArrayFallback paths, and the JSON file gitignore entries. CLAUDE.md update can ship independently as soon as someone has bandwidth.",
     "targetRemovalDate": null,
@@ -85,15 +169,51 @@
     "id": "prune-default-claude-config",
     "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", "lines": "3126", "note": "pruneDefaultClaudeConfig definition: preserves non-default binary/allowedTools, always strips permissionMode + outputFormat" },
-      { "file": "engine/shared.js", "lines": "5673", "note": "Module export entry" },
-      { "file": "dashboard.js", "lines": "202", "note": "Called when loading config for the dashboard UI" },
-      { "file": "dashboard.js", "lines": "9116", "note": "Called during first config save handler" },
-      { "file": "dashboard.js", "lines": "9331", "note": "Called during second config save path" },
-      { "file": "dashboard.js", "lines": "9450", "note": "Called during third config save path" },
-      { "file": "minions.js", "lines": "385", "note": "Called during CLI init/update flow" },
-      { "file": "test/unit.test.js", "lines": "2260-2303", "note": "Behavioural unit tests (default strip, override preservation, outputFormat unconditional strip) + dashboard call-site source pin" },
-      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "546", "note": "Source-inspection test pinning the dashboard handler call site" }
+      {
+        "file": "engine/shared.js",
+        "lines": "3126",
+        "note": "pruneDefaultClaudeConfig definition: preserves non-default binary/allowedTools, always strips permissionMode + outputFormat"
+      },
+      {
+        "file": "engine/shared.js",
+        "lines": "5673",
+        "note": "Module export entry"
+      },
+      {
+        "file": "dashboard.js",
+        "lines": "202",
+        "note": "Called when loading config for the dashboard UI"
+      },
+      {
+        "file": "dashboard.js",
+        "lines": "9116",
+        "note": "Called during first config save handler"
+      },
+      {
+        "file": "dashboard.js",
+        "lines": "9331",
+        "note": "Called during second config save path"
+      },
+      {
+        "file": "dashboard.js",
+        "lines": "9450",
+        "note": "Called during third config save path"
+      },
+      {
+        "file": "minions.js",
+        "lines": "385",
+        "note": "Called during CLI init/update flow"
+      },
+      {
+        "file": "test/unit.test.js",
+        "lines": "2260-2303",
+        "note": "Behavioural unit tests (default strip, override preservation, outputFormat unconditional strip) + dashboard call-site source pin"
+      },
+      {
+        "file": "test/unit/runtime-fleet-helpers.test.js",
+        "lines": "546",
+        "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.",
     "targetRemovalDate": null,
@@ -104,7 +224,10 @@
     "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.",
     "deprecated": "2026-06-04",
     "code": [
-      { "file": "engine/ado.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." }
+      {
+        "file": "engine/ado.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.",
     "targetRemovalDate": "2026-08-03",
@@ -114,7 +237,10 @@
     "id": "pr-link-autoObserve-body-param",
     "description": "Legacy `autoObserve` body parameter on `POST /api/pull-requests/link`. Replaced by canonical `contextOnly` body param (inverse boolean: `autoObserve: false` ⇔ `contextOnly: true`). This is a READ-BRIDGE on the input side only — the handler reads `body.contextOnly` first and falls back to `!body.autoObserve` for callers not yet migrated. No underscore alias is written onto the record (the record-field aliases already shipped out — see the three paired entries); the only thing kept alive is the input fallback.",
     "code": [
-      { "file": "dashboard.js", "note": "linkPullRequestForTracking resolves `contextOnly` from `body.contextOnly` when boolean, else `autoObserve === undefined ? false : !autoObserve` (dashboard.js:1055-1057). Route registry params string still lists `autoObserve?` (dashboard.js:12680)." }
+      {
+        "file": "dashboard.js",
+        "note": "linkPullRequestForTracking resolves `contextOnly` from `body.contextOnly` when boolean, else `autoObserve === undefined ? false : !autoObserve` (dashboard.js:1055-1057). Route registry params string still lists `autoObserve?` (dashboard.js:12680)."
+      }
     ],
     "deprecated": "2026-06-08",
     "targetRemovalDate": "2026-06-25",
@@ -124,9 +250,18 @@
     "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'.",
     "code": [
-      { "file": "engine/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", "note": "addProject threads options.checkoutMode ?? options.worktreeMode into buildProjectEntry (accepts the legacy options key)." },
-      { "file": "dashboard.js", "note": "handleProjectsAdd reads body.checkoutMode ?? body.worktreeMode; handleSettingsUpdate + mergeSettingsConfigUpdate accept the legacy update.worktreeMode key and delete proj.worktreeMode on every save (active migration)." }
+      {
+        "file": "engine/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",
+        "note": "addProject threads options.checkoutMode ?? options.worktreeMode into buildProjectEntry (accepts the legacy options key)."
+      },
+      {
+        "file": "dashboard.js",
+        "note": "handleProjectsAdd reads body.checkoutMode ?? body.worktreeMode; handleSettingsUpdate + mergeSettingsConfigUpdate accept the legacy update.worktreeMode key and delete proj.worktreeMode on every save (active migration)."
+      }
     ],
     "deprecated": "2026-06-17",
     "targetRemovalDate": "2026-09-17",
@@ -136,20 +271,13 @@
     "id": "pr-observe-observe-body-param",
     "description": "Legacy `observe` body parameter on `POST /api/pull-requests/observe`. The W-mq5s5ttx000j7ab8 endpoint sub-WI introduces canonical `contextOnly` as the inverse (`observe: false` ⇔ `contextOnly: true`) and keeps `observe` accepted for backward compat. Registering the deprecation here so the alias has a documented removal path; the WI explicitly notes this entry is the implementer's call (it is kept for backward compat and may live longer than the underscore-prefixed record fields).",
     "code": [
-      { "file": "dashboard.js", "note": "POST /api/pull-requests/observe handler reads `body.contextOnly` first, then falls back to `!body.observe` for backwards compat." }
+      {
+        "file": "dashboard.js",
+        "note": "POST /api/pull-requests/observe handler reads `body.contextOnly` first, then falls back to `!body.observe` for backwards compat."
+      }
     ],
     "deprecated": "2026-06-08",
     "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`."
-  },
-  {
-    "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",
-    "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"
   }
-]
+]

package/engine/discover-project-skills.js

@@ -7,8 +7,8 @@
  * plan / etc.) can reliably steer agents toward the right purpose-built
  * tooling instead of reinventing flows from first principles.
  *
- * This module is the generalized successor to engine/discover-review-skills.js
- * (PR #82, W-mq16xtdx001a347e). PR 82 hard-scoped discovery to review-flavored
+ * This module is the generalized successor to the PR #82 review-only helper
+ * (W-mq16xtdx001a347e). PR 82 hard-scoped discovery to review-flavored
  * skills via a single KEYWORD_RE; this module discovers EVERY project skill /
  * command / documented slash-command, classifies each one into a small closed
  * intent vocabulary, and lets callers filter to the intents they care about.
@@ -440,9 +440,8 @@ function renderProjectSkillsBlock(entries) {
   return lines.join('\n');
 }
 
-// ── Backward-compatibility shims for PR #82 callers (W-mq16xtdx001a347e) ──
-// These keep the discover-review-skills.js import surface working without
-// requiring every consumer to migrate in lockstep.
+// ── Backward-compatibility aliases for PR #82 callers (W-mq16xtdx001a347e) ──
+// These provide the original PR-82 function names as direct exports.
 
 function discoverReviewSkills(args) {
   // Old API: returns review-flavored entries only, without the new `intents`
@@ -479,7 +478,7 @@ module.exports = {
   renderProjectSkillsBlock,
   classifyIntents,
   INTENT_VOCABULARY,
-  // Backward-compat (PR #82) — see discover-review-skills.js shim.
+  // Backward-compat aliases (PR #82, W-mq16xtdx001a347e).
   discoverReviewSkills,
   renderReviewSkillsBlock,
   // exported for tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2268",
+  "version": "0.1.2270",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/engine/discover-review-skills.js

@@ -1,25 +0,0 @@
-/**
- * engine/discover-review-skills.js — backward-compat shim for PR #82
- * (W-mq16xtdx001a347e).
- *
- * PR #82 introduced `discover-review-skills.js` as a review-only helper. The
- * follow-on W-mq1cczi90006b21f generalized it into
- * `engine/discover-project-skills.js`, which discovers every project skill
- * and classifies them into an intent vocabulary.
- *
- * This file re-exports the two public PR-82 names so existing imports keep
- * resolving without forcing every consumer to migrate in lockstep. The shim
- * filters to the `review` intent and renders the original "## Project review
- * skills" header copy. New code should import directly from
- * engine/discover-project-skills.js and call `filterByIntents` itself.
- */
-
-const {
-  discoverReviewSkills,
-  renderReviewSkillsBlock,
-} = require('./discover-project-skills');
-
-module.exports = {
-  discoverReviewSkills,
-  renderReviewSkillsBlock,
-};