@yemi33/minions 0.1.2287 → 0.1.2289

package/dashboard.js

@@ -1842,11 +1842,16 @@ function _archivePrdPostProcess({ planFile, archivePath, planPath, plansDir, _mu
   let plan = {};
   let archivedSource = null;
 
-  // (a) Flip status + archivedAt.
+  // (a) Flip the archived FLAG + status + archivedAt. Phase 10 step 4.2b:
+  // archived-ness is the flag now (not the directory), so set `archived:true`
+  // explicitly. The mutate dual-writes the change into SQL via the chokepoint.
+  // When archivePath === planPath (in-place archive) this flags the PRD where it
+  // sits; when they differ (.md-cascade / legacy move) it flags the moved copy.
   try {
     plan = mutate(archivePath, (data) => {
       if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
       data.status = 'archived';
+      data.archived = true;
       data.archivedAt = new Date().toISOString();
       return data;
     }, { defaultValue: {} }) || {};
@@ -1866,30 +1871,38 @@ function _archivePrdPostProcess({ planFile, archivePath, planPath, plansDir, _mu
     } catch { /* readObj fallback is best-effort */ }
   }
 
-  // (b) Neutralize the .backup sidecar so safeJson auto-restore does not
-  // resurrect the pre-completion snapshot on engine restart (regression of #f28162b0).
-  try {
-    const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
-    if (!backupCleanup.ok) {
-      const warning = `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`;
+  // (b) Neutralize the .backup sidecar at the OLD live path ONLY when the file
+  // actually moved (archivePath !== planPath) — a stale prd/<f>.json.backup left
+  // behind by a move is resurrection fuel. For an in-place archive the file (and
+  // its current .backup) stay put and are valid, so there is nothing to neutralize.
+  if (planPath !== archivePath) {
+    try {
+      const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
+      if (!backupCleanup.ok) {
+        const warning = `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`;
+        archiveWarnings.push(warning);
+        console.warn(warning);
+      }
+    } catch (e) {
+      const warning = `Archive backup cleanup failed for ${planFile}: ${e.message}`;
       archiveWarnings.push(warning);
       console.warn(warning);
     }
-  } catch (e) {
-    const warning = `Archive backup cleanup failed for ${planFile}: ${e.message}`;
-    archiveWarnings.push(warning);
-    console.warn(warning);
   }
 
   // (c) Move the source plan markdown into plans/archive/.
   if (plan.source_plan) {
     try {
-      const mdPath = path.join(plansDir, plan.source_plan);
+      // Canonical key: a `plans/`-prefixed source_plan would otherwise join to
+      // plansDir/plans/x.md and silently miss, leaving the plan un-archived
+      // while the PRD archived — the plan↔PRD desync. (W-? archive sync.)
+      const planKey = shared.sourcePlanKey(plan.source_plan);
+      const mdPath = path.join(plansDir, planKey);
       if (fs.existsSync(mdPath)) {
         // DATA-LOSS GUARD: moveFileNoClobber dedupes + retries so archiving a
         // source plan can't overwrite a previously-archived plan of the same
         // basename (and survives transient Windows file locks).
-        const mdDest = shared.moveFileNoClobber(mdPath, path.join(plansDir, 'archive'), plan.source_plan);
+        const mdDest = shared.moveFileNoClobber(mdPath, path.join(plansDir, 'archive'), planKey);
         archivedSource = path.basename(mdDest);
       }
     } catch (e) {
@@ -8393,13 +8406,20 @@ const server = http.createServer(async (req, res) => {
       const planPath = resolvePlanPath(body.file);
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
 
-      const archiveDir = isPrd ? path.join(PRD_DIR, 'archive') : path.join(PLANS_DIR, 'archive');
-      // DATA-LOSS GUARD: moveFileNoClobber dedupes the destination so a same-
-      // basename collision (e.g. re-archiving a project's canonical
-      // <project>-<date> name, or the W-mq8qdai6 live↔archive collision class)
-      // can't silently destroy a previously-archived plan/PRD + its completed
-      // work-item history. Bumps to -2/-3 instead of overwriting.
-      const archivePath = shared.moveFileNoClobber(planPath, archiveDir, body.file);
+      // Phase 10 step 4.2b: a PRD is archived IN PLACE (flag flip via
+      // _archivePrdPostProcess — the json stays in prd/, no move, so the
+      // live↔archive basename-collision class / footgun #7 is gone). Only the
+      // .md plan still physically moves to plans/archive/.
+      let archivePath;
+      if (isPrd) {
+        archivePath = planPath; // in-place — do not move the PRD json
+      } else {
+        const archiveDir = path.join(PLANS_DIR, 'archive');
+        // DATA-LOSS GUARD: moveFileNoClobber dedupes the destination so a same-
+        // basename collision can't silently destroy a previously-archived plan +
+        // its completed work-item history. Bumps to -2/-3 instead of overwriting.
+        archivePath = shared.moveFileNoClobber(planPath, archiveDir, body.file);
+      }
 
       let archivedSource = null;
       let plan = {};
@@ -8451,33 +8471,19 @@ const server = http.createServer(async (req, res) => {
             console.warn(warning);
             continue;
           }
-          if (!prd || prd.source_plan !== body.file) continue;
-
-          const prdArchiveDir = path.join(PRD_DIR, 'archive');
-          try {
-            if (!fs.existsSync(prdArchiveDir)) fs.mkdirSync(prdArchiveDir, { recursive: true });
-          } catch (e) {
-            const warning = `Archive could not create PRD archive dir for ${prdFile}: ${e.message}`;
-            archiveWarnings.push(warning);
-            console.warn(warning);
-            continue;
-          }
-          let prdArchivePath;
-          try {
-            // DATA-LOSS GUARD: dedupe + retry so the cascade can't clobber a
-            // previously-archived PRD of the same basename.
-            prdArchivePath = shared.moveFileNoClobber(prdLivePath, prdArchiveDir, prdFile);
-          } catch (e) {
-            const warning = `Archive could not move PRD ${prdFile}: ${e.message}`;
-            archiveWarnings.push(warning);
-            console.warn(warning);
-            continue;
-          }
-          // Delegate status-flip + sidecar cleanup + (no-op) source-plan move
-          // to the shared helper so both branches stay in lockstep.
+          // Canonical match (prefix/dir-tolerant): a raw `prd.source_plan !==
+          // body.file` skipped PRDs whose source_plan carried the legacy
+          // `plans/` prefix, archiving the plan but NOT its PRD — the plan↔PRD
+          // status desync behind the "old PRDs came back" resurrection.
+          if (!prd || !shared.prdMatchesSourcePlan(prd.source_plan, body.file)) continue;
+
+          // Phase 10 step 4.2b: flag the PRD archived IN PLACE (no move). The
+          // outer handler already moved the .md to plans/archive/, so the
+          // helper's (c) source-plan move is a no-op; (a) flips the flag (dual-
+          // writing SQL) and (b) skips backup-neutralize since the file stayed.
           const cascadeResult = _archivePrdPostProcess({
             planFile: prdFile,
-            archivePath: prdArchivePath,
+            archivePath: prdLivePath,
             planPath: prdLivePath,
             plansDir: PLANS_DIR,
           });
@@ -8530,11 +8536,36 @@ const server = http.createServer(async (req, res) => {
       const isJson = body.file.endsWith('.json');
       const targetDir = isJson ? PRD_DIR : PLANS_DIR;
       const archivePath = path.join(targetDir, 'archive', body.file);
-      if (!fs.existsSync(archivePath)) return jsonReply(res, 404, { error: 'File not found in archive' });
-      // DATA-LOSS GUARD: restoring from archive must not clobber a LIVE plan/PRD
-      // of the same basename (renameSync overwrites). moveFileNoClobber bumps
-      // the restored name instead so the existing live file survives.
-      const liveDest = shared.moveFileNoClobber(archivePath, targetDir, body.file);
+      const livePath = path.join(targetDir, body.file);
+      // Phase 10 step 4.2b: a PRD can be archived two ways now — legacy
+      // (physically in <dir>/archive/) or in-place (in <dir>/ with the archived
+      // flag set). Restore from whichever it is.
+      let liveDest;
+      if (fs.existsSync(archivePath)) {
+        // DATA-LOSS GUARD: restoring must not clobber a LIVE plan/PRD of the same
+        // basename (renameSync overwrites). moveFileNoClobber bumps the restored
+        // name instead so the existing live file survives.
+        liveDest = shared.moveFileNoClobber(archivePath, targetDir, body.file);
+      } else if (isJson && fs.existsSync(livePath) && shared.isPrdArchived(safeJsonNoRestore(livePath))) {
+        liveDest = livePath; // in-place flag-archived — already in prd/, just clear the flag below
+      } else {
+        return jsonReply(res, 404, { error: 'File not found in archive' });
+      }
+      // Clear the archived flag/status so the unarchived PRD renders LIVE again.
+      // Archived-ness is the FLAG now (4.2a), so moving the file back is no longer
+      // enough — a legacy PRD carries status='archived' and would still render
+      // archived without this. Dual-writes the cleared state into SQL.
+      if (isJson) {
+        try {
+          mutateJsonFileLocked(liveDest, (d) => {
+            if (!d || typeof d !== 'object' || Array.isArray(d)) return d;
+            if (d.status === 'archived') d.status = 'active';
+            delete d.archived;
+            delete d.archivedAt;
+            return d;
+          }, { skipWriteIfUnchanged: true });
+        } catch (e) { console.warn(`Unarchive flag-clear failed for ${body.file}: ${e.message}`); }
+      }
 
       // Also unarchive linked source plan
       let unarchivedSource = null;

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,
@@ -106,7 +226,10 @@
     "status": "removed",
     "removedDate": "2026-06-25",
     "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,16 +237,18 @@
   },
   {
     "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.",
+    "status": "removed",
+    "removedDate": "2026-06-25",
+    "description": "Legacy `autoObserve` body parameter on `POST /api/pull-requests/link`. Replaced by canonical `contextOnly` body param (inverse boolean: `autoObserve: false` ⇔ `contextOnly: true`). This was a READ-BRIDGE on the input side only — the handler read `body.contextOnly` first and fell back to `!body.autoObserve` for callers not yet migrated. Removed by M001 (work/M001).",
     "code": [
       {
         "file": "dashboard.js",
-        "note": "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)."
+        "note": "Removed: linkPullRequestForTracking no longer accepts autoObserve in the destructure; resolvedContextOnly is now simply typeof contextOnly === 'boolean' ? contextOnly : false. Route registry params string no longer lists autoObserve?."
       }
     ],
     "deprecated": "2026-06-08",
     "targetRemovalDate": "2026-06-25",
-    "notes": "Unlike the three record-field aliases, nothing is written here — this is purely an input read-fallback. Removal scope (DEFERRED — gated on confirming no client still POSTs `autoObserve`, not on the expired calendar date): drop the `!body.autoObserve` fallback in the link handler in dashboard.js, drop `autoObserve?` from the route registry `params` string, and update any client (dashboard JS, ops scripts) that still POSTs `autoObserve`. After removal, callers that still send `autoObserve` will see their value silently ignored. On-disk sweep confirmed CLEAN on 2026-06-18: grep of every live projects/*/pull-requests.json (budget-test-project, constellation, minions-opg, office-bohemia) for the `_contextOnly`/`_autoObserve`/`_manual` record keys returned zero matches, so the deferral gate is now cleared and a deliberate, human-reviewed removal can be scheduled (this calendar bump 2026-06-16 → 2026-06-25 is the docs-only consistency half; the actual code removal stays a separate human-reviewed PR)."
+    "notes": "Removed on 2026-06-25. On-disk sweep confirmed CLEAN on 2026-06-18. autoObserve parameter silently ignored by server after this removal — callers that still send it will see the value dropped with contextOnly defaulting to false."
   },
   {
     "id": "worktreemode-field-rename",
@@ -150,10 +275,23 @@
     "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/docs/live-checkout-mode.md

@@ -43,6 +43,23 @@ The engine never calls `git reset --hard`, `git clean -fd`, `git stash`, or any
 
 A thrown error from `prepareLiveCheckout` — a required-arg/ref-validation guard, or a transient `git status`/`rev-parse`/`checkout`/`symbolic-ref` failure — is **not** proof that the operator tree is dirty. `spawnAgent`'s `catch` block therefore completes the dispatch with the **separate** `FAILURE_CLASS.LIVE_CHECKOUT_FAILED` (`'live-checkout-failed'`), which is deliberately **excluded** from `engine/dispatch.js`'s `neverRetry` set. The dispatcher auto-retries with bounded backoff up to `ENGINE_DEFAULTS.maxRetries`, so racy branch-lock handoff, a just-finished sibling dispatch, or transient git state recovers on the next attempt **without a manual `/api/work-items/retry`**. Genuinely terminal underlying reasons (auth, validation) still short-circuit via the reason-string check in `isRetryableFailureReason`. No dirty-files inbox alert is written and no `_pendingReason: 'live_checkout_dirty'` stamp is applied for this path — those belong to the confirmed-dirty result above.
 
+> **`git status --porcelain` maxBuffer (W-mqvejug6000eeb20).** All read-only git probes in `prepareLiveCheckout` / `restoreLiveCheckoutAtDispatchEnd` run with a 50 MB `maxBuffer` (`LIVE_CHECKOUT_GIT_MAX_BUFFER`, threaded through `baseOpts`). A live tree with thousands of dirty/untracked paths could otherwise overflow `execFile`'s 1 MB default and reject with `ERR_CHILD_PROCESS_STDOUT_MAXBUFFER` — a *thrown* error that mis-classified as a transient retryable `LIVE_CHECKOUT_FAILED` (per 2a) and retry-stormed to the cap instead of being surfaced as the dirty tree it actually was. A caller-supplied `gitOpts.maxBuffer` still wins (spread after the default).
+
+#### 2b. Opt-in auto-reset on dirty (`liveCheckoutAutoReset`, W-mqvejug6000eeb20)
+
+By default the dirty tree refusal (Guarantee 2) is terminal — the engine never touches the operator's uncommitted work. **Opt in** to automatic recovery with `liveCheckoutAutoReset`. When enabled, a dirty live tree is **force-reset to the remote** instead of refusing the dispatch:
+
+1. `prepareLiveCheckout` detects the dirty tree (same porcelain preflight as Guarantee 2).
+2. It resolves the effective flag via `shared.resolveLiveCheckoutAutoReset(project, engine)` — **per-project `project.liveCheckoutAutoReset` (boolean) wins**, else the fleet-wide `engine.liveCheckoutAutoReset`, else `false`. (engine.js does not thread project/engine config into the helper, so the production path self-resolves by loading `config.json` and matching the project by `localPath`; it **fails closed** to `false` on any config read error so a glitch can never silently trigger a destructive reset.)
+3. If ON: `git fetch origin` + `git reset --hard origin/<branch>`, then **re-run the porcelain preflight once**. If the tree is now clean, dispatch proceeds normally. If the reset failed or the tree is *still* dirty, it falls back to the safe `{ ok:false, reason:'dirty' }` refusal — the engine never dispatches onto an unexpected tree.
+4. On a successful reset it writes a single `live-checkout-autoreset-<wiId>` inbox note listing **exactly which paths were discarded**, so the operator can recover them from `git reflog` / `git fsck --lost-found`.
+
+This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted changes in the live checkout — which is why it is **OFF by default** and strictly opt-in. Use it only for unattended/CI-style live checkouts where the tree is expected to track the remote and any local drift is disposable.
+
+- **Fleet-wide:** Dashboard → Settings → `Live-checkout auto-reset (fleet-wide)` (`engine.liveCheckoutAutoReset`).
+- **Per-project override:** set `liveCheckoutAutoReset: true|false` on the project object in `config.json` (see the config snippet under *Enabling live mode*). A per-project boolean overrides the fleet-wide default for that project. *(Per-project Settings-UI persistence is deferred — the per-project override is config.json-only for now.)*
+
+
 ### 3. No auto-pull, no `--force`, no fast-forward
 
 After the clean-tree check, `prepareLiveCheckout`:
@@ -109,6 +126,10 @@ The core invariant holds end-to-end through restore: **the engine only ever swit
     "name": "android-aosp",
     "localPath": "/home/yemi/aosp",
     "checkoutMode": "live",
+    // "liveCheckoutAutoReset": true,  // OPT-IN, DESTRUCTIVE — on a dirty tree,
+    //   git fetch origin + git reset --hard origin/<branch> instead of refusing
+    //   (discards uncommitted operator changes; logs a live-checkout-autoreset
+    //   inbox note). Overrides the fleet-wide engine.liveCheckoutAutoReset.
     // …
   }]
 }
@@ -118,7 +139,7 @@ Absent / `null` / `''` reads as `'worktree'` (the default) — explicit is prefe
 
 ### Recovering from `live_checkout_dirty` refusal
 
-When dispatch is blocked by a dirty tree, the dashboard shows the work item as pending with `_pendingReason: 'live_checkout_dirty'` and an inbox alert lists the dirty files. From the project checkout:
+When dispatch is blocked by a dirty tree, the dashboard shows the work item as pending with `_pendingReason: 'live_checkout_dirty'` and an inbox alert lists the dirty files. (To make the engine *auto-recover* from this instead of refusing — at the cost of discarding the dirty changes — enable [opt-in auto-reset](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).) From the project checkout:
 
 ```bash
 # Option A — preserve work for later
@@ -211,7 +232,7 @@ To opt back out, clear `liveValidation` from the project config (or set to `null
 Live-checkout mode is deliberately small. These are NOT supported and will not be added:
 
 - **No `auto` mode.** The choice between `worktree` and `live` is per-project and operator-set. The engine will not auto-detect submodules / `repo` workspaces and silently switch modes.
-- **No auto-stash on dirty refusal.** The engine refuses and exits; it never `git stash`es to "make room" for a dispatch. Stashes silently mutate the operator's tree and conflate engine state with operator state.
+- **No auto-stash on dirty refusal.** The engine refuses and exits; it never `git stash`es to "make room" for a dispatch. Stashes silently mutate the operator's tree and conflate engine state with operator state. (The opt-in `liveCheckoutAutoReset` is the one sanctioned escape hatch — but it **discards** rather than stashes, is OFF by default, and is gated on explicit per-project / fleet-wide opt-in. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
 - **No concurrent dispatches per project.** The cap is 1; raising it would require per-WI subdirectories, which live mode explicitly does not provide.
 - **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `checkoutMode: 'worktree'` (the default).
 - **No per-WI override.** `checkoutMode` is per-project only. There is no `meta.checkoutMode` on a work item that overrides the project setting.
@@ -223,8 +244,9 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | File | Purpose |
 |---|---|
 | `engine/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
+| `engine/shared.js` — `resolveLiveCheckoutAutoReset` + `ENGINE_DEFAULTS.liveCheckoutAutoReset` | Pure precedence resolver (per-project boolean > fleet-wide engine default > false) + the fleet-wide default (OFF). Gates the opt-in dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20). |
 | `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live projects (P-a3f9b202). |
-| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight (incl. `BISECT_LOG`; throw-on-git-dir-failure; exit-1-only detached), original-ref capture, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch` classification** for partial-clone hydration failures (P-a3f9b203; preflight + capture P-b2e8d4a6; hardening PL-live-checkout-reliability-hardening). |
+| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight (incl. `BISECT_LOG`; throw-on-git-dir-failure; exit-1-only detached), original-ref capture, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch` classification** for partial-clone hydration failures, **opt-in dirty auto-reset** (`git fetch origin` + `reset --hard origin/<branch>` + re-check + `live-checkout-autoreset-<wiId>` note when `liveCheckoutAutoReset` is on), **50 MB git maxBuffer** (P-a3f9b203; preflight + capture P-b2e8d4a6; hardening PL-live-checkout-reliability-hardening; auto-reset + maxBuffer W-mqvejug6000eeb20). |
 | `engine/live-checkout.js` — `restoreLiveCheckoutAtDispatchEnd` | Dispatch-end auto-restore (plain `git checkout <originalRef>`, never `--force`/reset/clean/stash, best-effort) + **self-healing dirty recovery** (auto-commit agent WIP onto the agent branch) + `live-checkout-failed-<dispatchId>` terminal-failure alert + `live-checkout-branch-<dispatchId>` fallback notify (now also on unexpected restore errors) (P-d9e6b2c4; self-heal PL-live-checkout-reliability-hardening). |
 | `engine/live-checkout.js` — `maybeRestoreLiveCheckoutFromRecord` | Shared wrapper that fires the dispatch-end restore from a persisted dispatch record; used by `cli.js` + both `timeout.js` reaping paths so a restart-spanning live dispatch is never stranded (PL-live-checkout-reliability-hardening). |
 | `engine.js` — `spawnAgent` live-mode block | Calls `prepareLiveCheckout`, handles dirty / throw branches, gates `git worktree add` on `!liveMode` (P-a3f9b204). |
@@ -237,7 +259,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `engine.js` — worktree-pool / orphan-GC short-circuits | `worktreePath===null` no-ops in live mode (P-a3f9b206). |
 | `engine/cleanup.js` — `runPeriodicWorktreeSweep` live filter | Excludes live-checkout projects from the registry-derived periodic worktree GC so the operator's primary checkout never enters the GC decision surface (PL-live-checkout-reliability-hardening). |
 | `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` step-4 restore | `reset --hard HEAD` (not the index-leaking `checkout -- .`) + retried untracked removal + `liveTreeDirty` surfaced + `shared.removeWorktree` teardown (PL-live-checkout-reliability-hardening). |
-| `dashboard/js/settings.js` — checkoutMode dropdown + chip | Operator-facing UI (P-a3f9b207). |
+| `dashboard/js/settings.js` — checkoutMode dropdown + chip + `set-liveCheckoutAutoReset` fleet toggle | Operator-facing UI; the fleet-wide auto-reset toggle persists to `engine.liveCheckoutAutoReset` (per-project UI deferred — config.json only) (P-a3f9b207; auto-reset toggle W-mqvejug6000eeb20). |
 | `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring}.test.js` | Wiring and contract tests (P-a3f9b208). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` | Non-retryable refusal class. |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION` | Non-retryable refusal class for a mid-operation / detached-HEAD operator tree (in-progress merge/rebase/cherry-pick/revert/bisect or detached HEAD), distinct from the dirty-tree class. Emitted by `spawnAgent`'s mid-op / detached-HEAD refusal block (P-a7f3c1d9; wired P-c5a1f3b8). |

package/engine/ado.js

@@ -2224,6 +2224,13 @@ async function reconcilePrs(config) {
       // are human-authored and should not be auto-tracked or auto-reviewed.
       if (!confirmedItemId) continue;
 
+      // Only auto-link when the work item was dispatched to a configured Minions
+      // agent. PRs from human coworkers or external Copilot agents who happen to
+      // use Minions-style branch naming (work/W-xxx) must not enter the review loop.
+      const configuredAgentIds = new Set(Object.keys(config.agents || {}));
+      const dispatchedTo = String(linkedItem?.dispatched_to || '').toLowerCase();
+      if (!dispatchedTo || !configuredAgentIds.has(dispatchedTo)) continue;
+
       const entry = {
         id: prId,
         prNumber: adoPr.pullRequestId,
@@ -2512,10 +2519,12 @@ async function checkLiveBuildAndConflict(pr, project) {
   }
 }
 
-async function fetchAdoPrMetadata(prNum, adoOrg, adoProj, adoRepo) {
+async function fetchAdoPrMetadata(prNum, adoOrg, adoProj, adoRepo, project) {
   const token = await getAdoToken();
   if (!token) return null;
-  const orgBase = getAdoOrgBase({ adoOrg });
+  // Use full project config when provided so visualstudio.com prUrlBase
+  // resolves correctly via getAdoOrgBase; fall back to bare { adoOrg } stub.
+  const orgBase = getAdoOrgBase(project && project.prUrlBase ? project : { adoOrg });
   const url = `${orgBase}/${encodeURIComponent(adoProj)}/_apis/git/repositories/${encodeURIComponent(adoRepo)}/pullrequests/${encodeURIComponent(String(prNum))}?api-version=7.1`;
   const pr = await adoFetch(url, token);
   if (!pr) return null;

package/engine/github.js

@@ -1498,6 +1498,13 @@ async function reconcilePrs(config) {
       const authorLogin = String(ghPr.user?.login || '').trim().toLowerCase();
       if (!confirmedItemId || !configuredAuthorLogins.has(authorLogin)) continue;
 
+      // Only auto-link when the work item was dispatched to a configured Minions
+      // agent. PRs from human coworkers or external Copilot agents who happen to
+      // use Minions-style branch naming (work/W-xxx) must not enter the review loop.
+      const configuredAgentIds = new Set(Object.keys(config.agents || {}));
+      const dispatchedTo = String(linkedItem?.dispatched_to || '').toLowerCase();
+      if (!dispatchedTo || !configuredAgentIds.has(dispatchedTo)) continue;
+
       const entry = {
         id: prId,
         prNumber: ghPr.number,