@yemi33/minions 0.1.2287 → 0.1.2289

package/engine/lifecycle.js

@@ -754,6 +754,11 @@ const _STALE_PRD_STATUSES = new Set([WI_STATUS.DISPATCHED, WI_STATUS.FAILED, WI_
 // awaiting-approval PRDs. Previously only COMPLETED was skipped.
 const _PRD_FROZEN_STATUSES = new Set([
   PLAN_STATUS.COMPLETED, PLAN_STATUS.PAUSED, PLAN_STATUS.REJECTED, PLAN_STATUS.AWAITING_APPROVAL,
+  // 'archived' — Phase 10 step 4: archive becomes an in-place flag/status (the
+  // PRD stays in prd/ with status='archived' rather than moving to prd/archive/).
+  // A frozen PRD's item statuses must never be mutated; an archived-in-place PRD
+  // previously froze only by being moved out of the dir these scanners read.
+  'archived',
 ]);
 function syncPrdItemStatus(itemId, status, sourcePlan) {
   if (!itemId) return;
@@ -1316,7 +1321,7 @@ async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
       if (adoParts.length === 3) {
         const ado = require('./ado');
         if (typeof ado.fetchAdoPrMetadata === 'function') {
-          const meta = await ado.fetchAdoPrMetadata(prNumber, adoParts[0], adoParts[1], adoParts[2]);
+          const meta = await ado.fetchAdoPrMetadata(prNumber, adoParts[0], adoParts[1], adoParts[2], project);
           if (meta) {
             title = String(meta.title || '').slice(0, 200);
             branch = meta.branch || '';
@@ -3296,6 +3301,7 @@ async function handlePostMerge(pr, project, config, newStatus) {
         const planPath = path.join(prdDir, pf);
         mutateJsonFileLocked(planPath, (plan) => {
           if (!plan?.missing_features) return plan;
+          if (shared.isPrdArchived(plan)) return plan; // step 4: never mutate an archived (in-place) PRD's items
           for (const feature of plan.missing_features) {
             if (mergedItemSet.has(feature.id) && feature.status !== WI_STATUS.DONE) {
               feature.status = WI_STATUS.DONE;
@@ -5216,7 +5222,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         if (meta.item.planFile) {
           try {
             const prd = safeJson(path.join(PRD_DIR, expectedFile));
-            if (prd && prd.source_plan === meta.item.planFile) {
+            if (prd && shared.prdMatchesSourcePlan(prd.source_plan, meta.item.planFile)) {
               prdFound = true;
               resolvedPrdFilename = expectedFile;
             } else {
@@ -5243,7 +5249,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           if (!f.endsWith('.json')) continue;
           try {
             const prd = safeJson(path.join(PRD_DIR, f));
-            if (prd && prd.source_plan === meta.item.planFile) {
+            if (prd && !shared.isPrdArchived(prd) && shared.prdMatchesSourcePlan(prd.source_plan, meta.item.planFile)) {
               prdFound = true;
               resolvedPrdFilename = f;
               break;

package/engine/live-checkout.js

@@ -62,10 +62,15 @@
  * Worktree (isolated) mode is unaffected — that path still branches from
  * origin/<mainRef> for a clean baseline elsewhere in spawnAgent.
  *
- * PURE — does NOT call completeDispatch, does NOT write inbox alerts. That
- * translation belongs in spawnAgent (engine.js). Keeping this helper free of
- * side effects lets unit tests exercise every branch with a mocked git
- * runner and zero filesystem touching.
+ * MOSTLY PURE — does NOT call completeDispatch. It does NOT mutate the tree or
+ * write inbox alerts on any default path. The ONE opt-in exception is auto-reset
+ * (W-mqvejug6000eeb20): when `liveCheckoutAutoReset` is enabled AND the tree is
+ * dirty, it runs `git fetch origin` + `git reset --hard origin/<branch>` and
+ * writes a single `live-checkout-autoreset-<wiId>` inbox note. Both the reset
+ * git ops and the note writer are injectable (`_git`, `_writeInboxNote`) and the
+ * decision is injectable (`autoReset` / `_resolveAutoReset`), so unit tests stay
+ * filesystem-free. Default (auto-reset off) keeps the helper free of side
+ * effects — the dirty/blocked translation belongs in spawnAgent (engine.js).
  *
  * All git invocations route through `shared.shellSafeGit` (argv-form,
  * shell:false, execFile). Branch and main-ref are validated via
@@ -86,6 +91,17 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 
+// W-mqvejug6000eeb20 — generous stdout ceiling for the read-only git probes in
+// this module (`git status --porcelain`, `rev-parse`, …). Node's execFile
+// default maxBuffer is 1 MB; a live-checkout tree with a very large number of
+// dirty/untracked paths can blow past that on `git status --porcelain`, and the
+// resulting ERR_CHILD_PROCESS_STDOUT_MAXBUFFER rejection was being mis-surfaced
+// as a transient/retryable LIVE_CHECKOUT_FAILED that retry-storms to the cap.
+// 50 MB is far above any realistic porcelain output (≈ thousands of files) yet
+// still bounded. Threaded through `baseOpts` so every git call inherits it; the
+// injected `_git` mock in unit tests ignores opts so the seam is unaffected.
+const LIVE_CHECKOUT_GIT_MAX_BUFFER = 50 * 1024 * 1024;
+
 // PL-live-checkout-reliability-hardening — partial-clone / GVFS blob-fetch
 // signature match. On a Scalar/GVFS-managed ADO repo (blobless partial clone),
 // switching the working tree onto a branch whose tree differs from HEAD must
@@ -117,6 +133,37 @@ function _isPartialCloneBlobError(message = '') {
   );
 }
 
+// W-mqvejug6000eeb20 — production default for resolving the live-checkout
+// auto-reset decision when the caller (engine.js spawnAgent) does not pass an
+// explicit `autoReset` boolean. engine.js is intentionally not threading the
+// project/engine config into prepareLiveCheckout, so we self-resolve: load
+// config.json, match the project by `localPath`, and defer to
+// `shared.resolveLiveCheckoutAutoReset` (per-project boolean wins, else
+// engine-level fallback, else false). Runs only on the dirty path (cold, not
+// hot), and fails CLOSED — any error reading config returns false so a config
+// glitch can never silently trigger a destructive reset.
+function _defaultResolveAutoReset(localPath) {
+  try {
+    const config = shared.safeJson(path.join(shared.MINIONS_DIR, 'config.json')) || {};
+    const projects = shared.getProjects(config);
+    const norm = (p) => path.resolve(String(p || '')).replace(/\\/g, '/').toLowerCase();
+    const target = norm(localPath);
+    const project = projects.find((p) => p && p.localPath && norm(p.localPath) === target) || null;
+    return shared.resolveLiveCheckoutAutoReset(project, config.engine);
+  } catch {
+    return false;
+  }
+}
+
+// W-mqvejug6000eeb20 — production default inbox-note writer for the auto-reset
+// audit trail. Lazily required to avoid a load-order cycle (dispatch.js does not
+// require live-checkout.js, but the lazy require keeps this module importable in
+// isolation / in tests that never trigger the write). Best-effort.
+function _defaultWriteInboxNote(slug, content) {
+  // eslint-disable-next-line global-require
+  return require('./dispatch').writeInboxAlert(slug, content);
+}
+
 async function prepareLiveCheckout(opts = {}) {
   const {
     localPath,
@@ -124,10 +171,15 @@ async function prepareLiveCheckout(opts = {}) {
     mainRef,
     gitOpts,
     dispatchId, // accepted for caller bookkeeping; not used by the helper
-    wiId,       // accepted for caller bookkeeping; not used by the helper
+    wiId,       // accepted for caller bookkeeping; used in the auto-reset note slug
     log,
+    autoReset,  // W-mqvejug6000eeb20: tri-state. `true`/`false` short-circuits the
+                // config-based resolution; `undefined` (the engine.js call shape)
+                // defers to `_resolveAutoReset`.
     _git,       // private injection for testing — defaults to shared.shellSafeGit
     _exists,    // private injection for testing — defaults to fs.existsSync
+    _resolveAutoReset, // private injection for testing — defaults to config-based resolver
+    _writeInboxNote,   // private injection for testing — defaults to dispatch.writeInboxAlert
   } = opts;
 
   // ── Required-arg guards. Throw rather than return {ok:false} so a
@@ -154,7 +206,10 @@ async function prepareLiveCheckout(opts = {}) {
 
   const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
   const exists = (typeof _exists === 'function') ? _exists : fs.existsSync;
-  const baseOpts = { cwd: localPath, ...(gitOpts || {}) };
+  // W-mqvejug6000eeb20 — default maxBuffer (50 MB) so a large `git status
+  // --porcelain` never overflows execFile's 1 MB ceiling. A caller-supplied
+  // gitOpts.maxBuffer still wins (spread after the default).
+  const baseOpts = { cwd: localPath, maxBuffer: LIVE_CHECKOUT_GIT_MAX_BUFFER, ...(gitOpts || {}) };
 
   // ── Step 1: git status --porcelain=v1 -b. Bail early on dirty tree. ─────
   // Porcelain v1 -b adds a `## <branch>` header line as the first output line
@@ -174,7 +229,83 @@ async function prepareLiveCheckout(opts = {}) {
   const branchInfo = statusLines.find((line) => line.startsWith('## ')) || '';
   const dirtyFiles = statusLines.filter((line) => !line.startsWith('## '));
   if (dirtyFiles.length > 0) {
-    return { ok: false, reason: 'dirty', dirtyFiles, branchInfo };
+    // W-mqvejug6000eeb20 — opt-in auto-reset. Default behavior is to bail with
+    // reason:'dirty' (spawnAgent translates to non-retryable LIVE_CHECKOUT_DIRTY
+    // and alerts the operator). When auto-reset is enabled — either the caller
+    // passed an explicit `autoReset` boolean, or the config-based resolver says
+    // so — we DISCARD the dirty state via `git fetch origin` + `git reset --hard
+    // origin/<branch>` and continue. This is destructive (the operator's
+    // uncommitted work is gone), which is why it is strictly opt-in.
+    let wantAutoReset = false;
+    if (typeof autoReset === 'boolean') {
+      wantAutoReset = autoReset;
+    } else {
+      const resolver = (typeof _resolveAutoReset === 'function') ? _resolveAutoReset : _defaultResolveAutoReset;
+      try { wantAutoReset = !!resolver(localPath); } catch { wantAutoReset = false; }
+    }
+
+    if (!wantAutoReset) {
+      return { ok: false, reason: 'dirty', dirtyFiles, branchInfo };
+    }
+
+    if (typeof log === 'function') {
+      log(`live-checkout auto-reset: discarding ${dirtyFiles.length} dirty path(s) on '${branchName}' via fetch + reset --hard origin/${branchName}`);
+    }
+    let resetOk = true;
+    try {
+      await git(['fetch', 'origin'], baseOpts);
+      await git(['reset', '--hard', `origin/${branchName}`], baseOpts);
+    } catch (e) {
+      resetOk = false;
+      if (typeof log === 'function') {
+        log(`live-checkout auto-reset FAILED (fetch/reset): ${e && e.message ? e.message : e}`);
+      }
+    }
+
+    // Re-run the porcelain preflight once. If the tree is now clean we proceed;
+    // otherwise (reset failed, or something is still dirty) we fall back to the
+    // safe dirty refusal so we never dispatch onto an unexpected tree.
+    let stillDirty = dirtyFiles;
+    if (resetOk) {
+      try {
+        const recheckRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
+        const recheckStr = typeof recheckRaw === 'string' ? recheckRaw : '';
+        stillDirty = recheckStr
+          .split(/\r?\n/)
+          .map((line) => line.replace(/\s+$/, ''))
+          .filter((line) => line.length > 0 && !line.startsWith('## '));
+      } catch (e) {
+        resetOk = false;
+        if (typeof log === 'function') {
+          log(`live-checkout auto-reset re-check FAILED: ${e && e.message ? e.message : e}`);
+        }
+      }
+    }
+
+    if (!resetOk || stillDirty.length > 0) {
+      return { ok: false, reason: 'dirty', dirtyFiles: stillDirty, branchInfo };
+    }
+
+    // Audit trail: record the discarded paths so the operator can recover from
+    // reflog / understand why their tree changed. Best-effort, never throws.
+    try {
+      const writeNote = (typeof _writeInboxNote === 'function') ? _writeInboxNote : _defaultWriteInboxNote;
+      const slug = `live-checkout-autoreset-${wiId || dispatchId || 'unknown'}`;
+      const body = [
+        `# Live-checkout auto-reset on '${branchName}'`,
+        '',
+        `⚠️ The live-checkout tree at \`${localPath}\` was dirty at dispatch time and`,
+        '`liveCheckoutAutoReset` is enabled, so it was force-reset to',
+        `\`origin/${branchName}\`. **The following uncommitted changes were DISCARDED**`,
+        '(recover from `git reflog` / `git fsck --lost-found` if needed):',
+        '',
+        '```',
+        ...dirtyFiles,
+        '```',
+      ].join('\n');
+      writeNote(slug, body);
+    } catch { /* best-effort audit note */ }
+    // Fall through — tree is now clean, continue with normal preparation.
   }
 
   // ── Step 2: mid-operation / detached-HEAD preflight (P-b2e8d4a6). ──────
@@ -423,7 +554,7 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
   const alert = (typeof writeInboxAlert === 'function') ? writeInboxAlert : () => {};
   const proj = projectName || 'project';
   const did = dispatchId || '(unknown)';
-  const baseOpts = { cwd: localPath, ...(gitOpts || {}) };
+  const baseOpts = { cwd: localPath, maxBuffer: LIVE_CHECKOUT_GIT_MAX_BUFFER, ...(gitOpts || {}) };
 
   const result = { restored: false, reason: null, failureAlerted: false, fallbackAlerted: false };
 

package/engine/playbook.js

@@ -432,6 +432,9 @@ const PLAYBOOK_REQUIRED_VARS = {
   'meeting-investigate':  ['meeting_title', 'agenda'],
   'meeting-debate':       ['meeting_title', 'agenda'],
   'meeting-conclude':     ['meeting_title', 'agenda'],
+  // M005 — SHERLOC two-phase build-fix. Same required vars as fix (PR-context
+  // dispatch), but routed to build-fix-complex.md for multi-file failures.
+  'build-fix-complex':    ['pr_id', 'pr_branch'],
 };
 
 /**
@@ -878,6 +881,7 @@ function renderPlaybook(type, vars) {
       if (block) inertAppendices.push(block);
     } catch (e) { log('warn', `handoff-context inject failed: ${e.message}`); }
   }
+
   // Inject KB guardrail
   content += `\n\n---\n\n## Knowledge Base Rules\n\n`;
   content += `**Never delete, move, or overwrite files in \`knowledge/\`.** The sweep (consolidation engine) is the only process that writes to \`knowledge/\`. If you think a KB file is wrong, note it in your learnings file — do not touch \`knowledge/\` directly.\n`;
@@ -1306,6 +1310,7 @@ function selectPlaybook(workType, item) {
   if (workType === WORK_TYPE.FIX && hasPrContext) {
     return 'fix';
   }
+  // M005 — SHERLOC: complex build-fix variant, always PR-context (mirrors FIX routing).
   if (workType === WORK_TYPE.BUILD_FIX_COMPLEX && hasPrContext) {
     return 'build-fix-complex';
   }

package/engine/prd-store.js

@@ -205,7 +205,7 @@ function reconcilePrdsFromDisk() {
       let mtime;
       try { mtime = Math.round(fs.statSync(full).mtimeMs); } catch { continue; }
       if (_reconcileMtimes.get(key) === mtime) continue; // unchanged since last seen
-      const prd = _readJsonObj(full);
+      const prd = require('./shared').safeJsonNoRestore(full);
       if (!prd) continue;
       try {
         const { withTransaction } = require('./db');

package/engine/queries.js

@@ -2158,11 +2158,18 @@ function getPrdInfo(config) {
   // two paths is proven by test/unit/db-phase10-read-flip.test.js.
   const processPrd = (pf, archived, plan, mtimeMs) => {
     if (!plan || !plan.missing_features) return;
+    // Phase 10 step 4.2: archived-ness is the FLAG, not the directory. `archived`
+    // is the physical-location signal (prd/ vs prd/archive/); a PRD archived
+    // IN PLACE (stays in prd/ with archived:true / status:'archived') must still
+    // render as archived. Derive the logical value here — the single funnel both
+    // the disk-scan and SQL-mirror sources pass through. Equivalent for current
+    // data (nothing is archived-in-place yet → isPrdArchived is false → ===archived).
+    const isArch = archived || shared.isPrdArchived(plan);
     // Staleness: gate on actual source-plan content change rather than mtime
     // alone (W-mqfevwr60018bd09). Pure path / pure mtime drifts return
     // stale=false so a repointed source_plan doesn't masquerade as a revision.
     let planStale = false;
-    if (!archived && plan.source_plan) {
+    if (!isArch && plan.source_plan) {
       try { planStale = shared.isSourcePlanContentStale(PLANS_DIR, plan).stale; } catch { /* optional */ }
     }
     existingPrds.push({
@@ -2170,7 +2177,7 @@ function getPrdInfo(config) {
       status: plan.status || 'active',
       planStale: planStale || plan.planStale || false,
       completedAt: plan.completedAt || '',
-      _archived: archived,
+      _archived: isArch,
     });
     if (Array.isArray(plan.verifyPrs) && plan.verifyPrs.length > 0) {
       verifyPrsByPlan[pf] = plan.verifyPrs.map(r => ({
@@ -2183,7 +2190,7 @@ function getPrdInfo(config) {
       allPrdItems.push({
         ...f, _source: pf, _planStatus: plan.status || 'active',
         _planSummary: plan.plan_summary || pf, _planProject: plan.project || '',
-        _archived: archived, _sourcePlan: plan.source_plan || '',
+        _archived: isArch, _sourcePlan: plan.source_plan || '',
         _branchStrategy: plan.branch_strategy || 'parallel',
         _planStale: planStale || plan.planStale || false, _lastSyncedFromPlan: plan.lastSyncedFromPlan || null,
         _prdUpdatedAt: new Date(mtimeMs).toISOString(),

package/engine/shared.js

@@ -744,17 +744,46 @@ function safeReadDir(dir) {
 // also fall back to plans/archive/<basename> so a silently-relocated
 // source plan no longer spams ENOENT warnings on every tick.
 
+/**
+ * Canonical association key for a plan/PRD source reference: the bare basename,
+ * stripped of any directory AND the legacy `plans/` (or `plans/archive/`) prefix
+ * some PRDs carry in their `source_plan` field. This is THE single key for
+ * matching a plan markdown file to the PRD(s) that point at it.
+ *
+ * It exists because `source_plan` is written inconsistently — sometimes a bare
+ * `x.md`, sometimes a prefixed `plans/x.md` (pre-#415). Comparing the raw
+ * strings (`prd.source_plan === planFile`) silently fails across the two forms,
+ * which let an archived plan keep a LIVE PRD — the plan↔PRD status desync behind
+ * the "old PRDs came back" resurrection. Always compare/derive via this helper.
+ */
+function sourcePlanKey(ref) {
+  return path.basename(String(ref || ''));
+}
+
+/**
+ * True when a PRD's `source_plan` references the given plan file, tolerant of
+ * the `plans/` prefix + directory differences. Use instead of raw `===`.
+ */
+function prdMatchesSourcePlan(sourcePlanRef, planFile) {
+  const a = sourcePlanKey(sourcePlanRef);
+  const b = sourcePlanKey(planFile);
+  return !!a && a === b;
+}
+
 /**
  * Resolve a PRD's `source_plan` field to an absolute file path under
  * `plansDir`. Tries the direct join first; falls back to
- * plansDir/archive/<basename(source_plan)> when the direct path is
- * missing. Returns null when neither location resolves to a regular file.
+ * plansDir/archive/<basename> when the direct path is missing. The direct join
+ * uses the canonical key so a `plans/`-prefixed source_plan resolves correctly
+ * (a raw join would yield plansDir/plans/x.md). Returns null when neither
+ * location resolves to a regular file.
  */
 function resolveSourcePlanPath(plansDir, sourcePlan) {
   if (!plansDir || !sourcePlan || typeof sourcePlan !== 'string') return null;
-  const direct = path.join(plansDir, sourcePlan);
+  const key = sourcePlanKey(sourcePlan);
+  const direct = path.join(plansDir, key);
   try { if (fs.statSync(direct).isFile()) return direct; } catch { /* miss */ }
-  const archived = path.join(plansDir, 'archive', path.basename(sourcePlan));
+  const archived = path.join(plansDir, 'archive', key);
   try { if (fs.statSync(archived).isFile()) return archived; } catch { /* miss */ }
   return null;
 }
@@ -2677,6 +2706,26 @@ function isLiveCheckoutProject(project) {
   return resolveCheckoutMode(project) === CHECKOUT_MODES.LIVE;
 }
 
+// W-mqvejug6000eeb20 — resolve the effective live-checkout auto-reset decision.
+// Precedence: an explicit per-project boolean (`project.liveCheckoutAutoReset`)
+// wins; otherwise the fleet-wide `engine.liveCheckoutAutoReset` applies;
+// otherwise `false`. Only an explicit boolean counts as "set" at either level —
+// anything else (undefined / null / string) is treated as unset so the next
+// tier (or the `false` default) decides. When ON and a live-checkout tree is
+// dirty, `engine/live-checkout.js#prepareLiveCheckout` runs
+// `git fetch origin` + `git reset --hard origin/<branch>` instead of refusing
+// with LIVE_CHECKOUT_DIRTY (the reset DISCARDS the operator's uncommitted work,
+// so it is opt-in). Sibling of `resolveCheckoutMode` — pure, no I/O.
+function resolveLiveCheckoutAutoReset(project, engine) {
+  if (project && typeof project === 'object' && typeof project.liveCheckoutAutoReset === 'boolean') {
+    return project.liveCheckoutAutoReset;
+  }
+  if (engine && typeof engine === 'object' && typeof engine.liveCheckoutAutoReset === 'boolean') {
+    return engine.liveCheckoutAutoReset;
+  }
+  return false;
+}
+
 function validateCheckoutMode(value) {
   if (value === undefined || value === null || value === '') return undefined;
   if (typeof value !== 'string') {
@@ -3143,6 +3192,15 @@ const ENGINE_DEFAULTS = {
   // itself ALWAYS runs on every orphan-sweep escalation (the flag only gates
   // the kill); holder details are appended to the inbox note either way.
   autoReapOrphanWorktreeHolders: false,
+  // W-mqvejug6000eeb20 — fleet-wide fallback for live-checkout auto-reset.
+  // When ON, a dirty/broken live-checkout tree is `git fetch origin` +
+  // `git reset --hard origin/<branch>`'d before dispatch instead of failing
+  // LIVE_CHECKOUT_DIRTY. Per-project `project.liveCheckoutAutoReset` overrides
+  // this. Default OFF — auto-reset is destructive (it discards the operator's
+  // uncommitted changes), so it is strictly opt-in. Resolution precedence lives
+  // in `resolveLiveCheckoutAutoReset`. Fires ONLY on confirmed dirty-tree
+  // detection, never on mid-operation / blob-fetch / tooling failures.
+  liveCheckoutAutoReset: false,
   orphanHolderScanTimeoutMs: 5000,          // 5s ceiling for the cross-platform holder scan (PowerShell / /proc walk / lsof)
   ccMaxTurns: 50, // max tool-use turns per CC/doc-chat call before CLI stops (per response, not per session)
   ccTurnTimeoutMs: 300000, // W-mpmwxni2000c25c7-b/-d: 5min per-turn no-progress watchdog. The window resets on every liveness signal — token chunk, tool-call notification, tool-update — so an actively-streaming CC/doc-chat turn (long shell command, deep search, sub-agent loop) survives indefinitely up to the outer CC_CALL_TIMEOUT_MS (~1h) ceiling. Only true silence past this window with no progress fires the cancel: the in-flight LLM call is aborted and the handler surfaces `{code:'cc-turn-timeout', retryable:true}` via the typed error envelope so the UI can stop the spinner and offer Retry. Clamped to [10000, 3600000] in the settings POST handler. Independent of CC_CALL_TIMEOUT_MS. Non-streaming doc-chat is the lone wall-clock exception (no progress hooks); see _raceCcDocChatTimeout in dashboard.js for the dual factory/promise shape.
@@ -3804,6 +3862,44 @@ const DONE_STATUSES = new Set([WI_STATUS.DONE, 'in-pr', 'implemented', 'complete
 // Terminal statuses for plan completion — item won't progress further (done, failed, cancelled).
 // Used by checkPlanCompletion to unblock the gate when items are in an unrecoverable state.
 const PLAN_TERMINAL_STATUSES = new Set([...DONE_STATUSES, WI_STATUS.FAILED, WI_STATUS.CANCELLED]);
+
+// True when a PRD is archived — by an explicit flag or the 'archived' top-level
+// status. (Distinct from the directory: a PRD JSON can carry this regardless of
+// whether it physically sits in prd/ or prd/archive/.)
+function isPrdArchived(plan) {
+  return !!plan && typeof plan === 'object' && (plan.archived === true || plan.status === 'archived');
+}
+
+// True when a PRD must NOT be (re)materialized or re-verified because it is
+// DEFUNCT — a dead leftover whose plan is no longer live. This is the
+// resurrection-re-execution guard (the "old PRDs came back" class): the
+// autonomous fleet keeps committing prd/*.json onto feature/cc-pr/backport
+// branches (vector 2) and checking those branches out IN the operator's live
+// checkout, which restores dead PRD files into prd/. The materializer then
+// re-creates and re-runs already-finished work — regardless of the resurrected
+// PRD's own status (awaiting-approval / undefined / completed), so a status-only
+// check is not enough.
+//
+// Definition (plan↔PRD status is meant to stay synced — see prdMatchesSourcePlan):
+//   • archived flag/status → defunct; else
+//   • plan markdown is LIVE in plansDir → NEVER defunct (active PRD / legit
+//     re-open keeps its plan live — this is the catastrophe guard: we never flag
+//     a PRD whose plan is present); else
+//   • plan is gone from plansDir AND (it's positively in plansDir/archive/, OR
+//     the PRD is completed) → defunct.
+// On any fs uncertainty we DON'T flag (favor not blocking real work).
+function isDefunctPrd(plan, plansDir) {
+  if (isPrdArchived(plan)) return true;
+  if (!plan || typeof plan !== 'object' || !plansDir) return false;
+  const sp = sourcePlanKey(plan.source_plan || plan.sourcePlan);
+  if (!sp) return false;
+  let liveExists;
+  try { liveExists = fs.existsSync(path.join(plansDir, sp)); } catch { return false; }
+  if (liveExists) return false; // plan is live → active PRD, never defunct
+  let archivedExists = false;
+  try { archivedExists = fs.existsSync(path.join(plansDir, 'archive', sp)); } catch { /* treat as absent */ }
+  return archivedExists || plan.status === 'completed';
+}
 const WORK_TYPE = {
   IMPLEMENT: 'implement', IMPLEMENT_LARGE: 'implement:large', FIX: 'fix', REVIEW: 'review',
   VERIFY: 'verify', PLAN: 'plan', PLAN_TO_PRD: 'plan-to-prd', DECOMPOSE: 'decompose',
@@ -8850,7 +8946,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, WORKTREE_REQUIRING_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, isPrdArchived, isDefunctPrd, WORK_TYPE, WORKTREE_REQUIRING_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
@@ -8927,6 +9023,8 @@ module.exports = {
   getAdoOrgBase,
   sanitizePath,
   resolveSourcePlanPath, // W-mqfevwr60018bd09 — PRD staleness: resolve source_plan to absolute path (archive-aware)
+  sourcePlanKey, prdMatchesSourcePlan, // canonical plan↔PRD association key (prefix/dir-tolerant) — keeps plan+PRD status synced
+
   computeSourcePlanContentHash, // W-mqfevwr60018bd09 — sha256 of source plan markdown body
   isSourcePlanContentStale, // W-mqfevwr60018bd09 — gate destructive PRD resync on actual content change
   sanitizeBranch,
@@ -8970,6 +9068,7 @@ module.exports = {
   validateCheckoutMode,
   resolveCheckoutMode,
   isLiveCheckoutProject,
+  resolveLiveCheckoutAutoReset,
   validatePid,
   PR_FIX_CAUSE,
   getPrFixAutomationCause,