@yemi33/minions 0.1.2352 → 0.1.2354

package/engine/cli.js

@@ -1653,6 +1653,10 @@ const commands = {
       return;
     }
     const targetProject = target?.project || (projects.length > 0 ? projects[0] : null);
+    if (!targetProject) {
+      console.log('No projects configured. Add a project before running work.');
+      return;
+    }
     const wiPath = projectWorkItemsPath(targetProject);
     const archivePath = wiPath.replace(/\.json$/, '-archive.json');
 

package/engine/lifecycle.js

@@ -8,7 +8,7 @@ const path = require('path');
 const os = require('os');
 const shared = require('./shared');
 const { safeRead, safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, mutateJsonFileLocked, mutateWorkItems, execAsync, projectPrPath, getPrLinks,
-  log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PR_STATUS, REVIEW_STATUS, RETRY_DELAY_MS, DISPATCH_RESULT,
+  log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, REVIEW_STATUS, RETRY_DELAY_MS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { resolveRuntime } = require('./runtimes');
 const adoGitAuth = require('./ado-git-auth');
@@ -38,27 +38,6 @@ function checkPlanCompletion(meta, config) {
   // Collect work items from ALL projects + central (PRD items can be in either)
   const allWorkItems = queries.getWorkItems(config);
   const planItems = allWorkItems.filter(w => w.sourcePlan === planFile && w.itemType !== 'pr' && w.itemType !== 'verify');
-  if (planItems.length === 0) return;
-
-  // W-mqk5ld3p: verify-creation must be a pure function of work-item state,
-  // independent of who/what set `status: completed`. We do NOT short-circuit on
-  // the raw `_completionNotified` boolean — a PRD can land on disk pre-completed
-  // with the flag already set (out-of-band write by the plan-to-prd / pipeline
-  // path), and the legacy top-of-function `if (_completionNotified) return` then
-  // permanently skipped the aggregate build/test verify gate. Instead the flag
-  // gates ONLY the one-shot completion summary (below); control always falls
-  // through to the verify-creation block, which re-checks for an existing verify
-  // WI under the file lock and is therefore safe to reach every scan. The one
-  // exception is the REOPEN sub-path (terminal verify → re-open): that is a
-  // plan-modification concern (the dashboard clears `_completionNotified` when it
-  // re-opens a plan), so it is gated on `!alreadyNotified` to avoid bouncing an
-  // already-done verify on every steady-state scan.
-  const alreadyNotified = plan.status === PLAN_STATUS.COMPLETED && !!plan._completionNotified;
-
-  // Hard completion gate: every PRD feature ID must have a corresponding work item in a terminal state.
-  const planFeatureIds = new Set((plan.missing_features || []).map(f => f.id).filter(Boolean));
-  const workItemById = {};
-  for (const w of planItems) { if (w.id) workItemById[w.id] = w; }
 
   // Self-heal stale completion. checkPlanCompletion only ever ADVANCED a plan to
   // `completed` — it never reverted. So a PRD that was completed and then gained
@@ -71,6 +50,8 @@ function checkPlanCompletion(meta, config) {
   // materializer recreates the missing WI and the normal completion flow resumes.
   // Idempotent: once reverted (status active, flag cleared) the guard no-ops, so
   // it cannot flap on subsequent scans while the item is genuinely incomplete.
+  // Defined BEFORE the `planItems.length === 0` early return (below) so the
+  // zero-materialized-items dead end (W-mrboq1g900096f04) can call it too.
   const reopenStaleCompletedPlan = (reason) => {
     if (plan.status !== PLAN_STATUS.COMPLETED && !plan._completionNotified) return false;
     log('warn', `Plan ${planFile}: re-opening stale completed PRD — ${reason}`);
@@ -83,6 +64,50 @@ function checkPlanCompletion(meta, config) {
     return true;
   };
 
+  if (planItems.length === 0) {
+    // W-mrboq1g900096f04: a PRD that reaches `completed` with ZERO materialized
+    // work items (agent authoring bug, race, or manual/API misuse writing
+    // status:'completed' directly instead of 'awaiting-approval') was a
+    // permanent, silent dead end — this function used to hard-return here
+    // before ever reaching reopenStaleCompletedPlan above, and
+    // materializePlansAsWorkItems unconditionally skips COMPLETED plans, so
+    // nothing ever re-triggered materialization. Self-heal: if the PRD is
+    // COMPLETED and still has feature IDs stuck at a non-terminal PRD-level
+    // status ('missing'/'updated', i.e. PRD_MATERIALIZABLE) with no
+    // corresponding work item, reopen it so the materializer picks it up.
+    // Do NOT reopen a genuinely-complete PRD (no missing_features, or every
+    // feature already at a terminal PRD-level status such as 'done').
+    if (plan.status === PLAN_STATUS.COMPLETED) {
+      const stuckIds = (plan.missing_features || [])
+        .filter(f => f?.id && PRD_MATERIALIZABLE.has(f.status))
+        .map(f => f.id);
+      if (stuckIds.length > 0) {
+        reopenStaleCompletedPlan(`${stuckIds.length} item(s) stuck at PRD-level status with zero materialized work items: ${stuckIds.join(', ')}`);
+      }
+    }
+    return;
+  }
+
+  // W-mqk5ld3p: verify-creation must be a pure function of work-item state,
+  // independent of who/what set `status: completed`. We do NOT short-circuit on
+  // the raw `_completionNotified` boolean — a PRD can land on disk pre-completed
+  // with the flag already set (out-of-band write by the plan-to-prd / pipeline
+  // path), and the legacy top-of-function `if (_completionNotified) return` then
+  // permanently skipped the aggregate build/test verify gate. Instead the flag
+  // gates ONLY the one-shot completion summary (below); control always falls
+  // through to the verify-creation block, which re-checks for an existing verify
+  // WI under the file lock and is therefore safe to reach every scan. The one
+  // exception is the REOPEN sub-path (terminal verify → re-open): that is a
+  // plan-modification concern (the dashboard clears `_completionNotified` when it
+  // re-opens a plan), so it is gated on `!alreadyNotified` to avoid bouncing an
+  // already-done verify on every steady-state scan.
+  const alreadyNotified = plan.status === PLAN_STATUS.COMPLETED && !!plan._completionNotified;
+
+  // Hard completion gate: every PRD feature ID must have a corresponding work item in a terminal state.
+  const planFeatureIds = new Set((plan.missing_features || []).map(f => f.id).filter(Boolean));
+  const workItemById = {};
+  for (const w of planItems) { if (w.id) workItemById[w.id] = w; }
+
   // Check 1: every feature must have a work item (materialized)
   // Fallback: also accept features marked done directly in the PRD JSON (resolved externally)
   const unmaterialized = [...planFeatureIds].filter(id => {
@@ -5647,9 +5672,16 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
             const w = data.find(i => i.id === meta.item.id);
             if (!w) return data;
             const retries = w._retryCount || 0;
+            // #893 gate failure reason — surfaced into the next dispatch's prompt via
+            // buildWorkItemDispatchVars()'s retry_context var (W-mrbq53ra000lf2e5) so the
+            // retried agent knows the PRD file was never found instead of silently
+            // repeating the same mistake.
+            const gateReason = `Validation gate (#893): no PRD JSON file was found on disk for planFile "${meta.item.planFile || w.planFile || '(unknown)'}" (expected "${expectedFile || '(unset)'}") after the previous attempt completed. Write the PRD JSON to the exact path specified in the playbook before finishing.`;
             if (retries < ENGINE_DEFAULTS.maxRetries) {
               w.status = WI_STATUS.PENDING;
               w._retryCount = retries + 1;
+              w._lastRetryReason = gateReason;
+              w._lastRetryAt = ts();
               // W-mpmwxn1j — bump per-agent counter so a planner that never
               // writes the PRD gets reassigned after maxRetriesPerAgent hits.
               const failedAgent = meta?._agentId || w.dispatched_to;
@@ -5661,6 +5693,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
               w.status = WI_STATUS.FAILED;
               w.failReason = 'PRD file not written after ' + ENGINE_DEFAULTS.maxRetries + ' attempts';
               w.failedAt = ts();
+              w._lastRetryReason = gateReason;
               log('warn', `plan-to-prd ${meta.item.id} failed — no PRD file after ${ENGINE_DEFAULTS.maxRetries} retries`);
             }
             return data;

package/engine/live-checkout.js

@@ -1168,6 +1168,40 @@ async function prepareLiveCheckout(opts = {}) {
   // auth-less GVFS blob fetches that fail on partial clones in headless mode.
   const failedCreate = await runCheckout(['checkout', '-b', branchName], { creating: true });
   if (failedCreate) return failedCreate;
+  // ── originalRef contamination invariant (P-mrb8yg9x001gf984). ───────────
+  // Defense-in-depth mirror of the existing-branch (4b) invariant above
+  // (W-mrb6an8300058fd8). Ordinarily the WRONG-BASE GUARD earlier in this
+  // path (Step 4d-i) already normalizes originalRef to mainRef whenever HEAD
+  // started off a non-mainRef branch and !allowNonMainBase — but that
+  // normalization only runs inside the `headBranch !== mainRef` branch of
+  // that guard. If some future change to that guard (or to the
+  // auto-base-repair / STALE-BASE divergence logic sitting between it and
+  // here) leaves originalRef still pointing at a leftover engine-managed
+  // branch instead of a sane restore target, it would otherwise flow straight
+  // through to the return below and propagate into
+  // restoreLiveCheckoutAtDispatchEnd at dispatch end — the exact
+  // contamination class W-mrb6an8300058fd8 fixed on the 4b path. Apply the
+  // SAME `_looksLikeAgentBranch` check here (same `!allowNonMainBase` gate —
+  // an explicit PR-continuation / shared-branch dispatch still intentionally
+  // bypasses this, exactly as it does on the 4b path) so the new-branch-fork
+  // path can never silently regress that invariant.
+  if (!allowNonMainBase && originalRefType === 'branch' && originalRef && originalRef !== mainRef &&
+      _looksLikeAgentBranch(originalRef)) {
+    logFn(
+      `[live-checkout] originalRef anomaly: HEAD's captured originalRef '${originalRef}' still looks like an engine-managed branch after forking '${branchName}' — this looks like leftover contamination from an earlier dispatch that should have been corrected to '${mainRef}' already. Attempting to correct it now.`,
+      'warn'
+    );
+    const corrected = await _resolveMainRefForRestore({ git, baseOpts, mainRef, autoBaseRepair, _resolveAutoBaseRepair, localPath, logFn });
+    if (corrected.ref) {
+      originalRef = corrected.ref;
+      originalRefType = corrected.type;
+    } else {
+      logFn(
+        `[live-checkout] originalRef anomaly: could not resolve '${mainRef}' as a corrected restore target (no local ref, auto-base-repair disabled, or 'origin/${mainRef}' missing) — leaving originalRef as the contaminated '${originalRef}'; a human should verify the operator checkout manually.`,
+        'warn'
+      );
+    }
+  }
   return { ok: true, branch: branchName, created: true, originalRef, originalRefType };
 }
 
@@ -1451,7 +1485,10 @@ async function restoreLiveCheckoutAtDispatchEnd(opts = {}) {
  * and the per-agent cli/model override pattern):
  *   1. If `project.liveCheckoutAutoStash` is an explicit boolean, use it.
  *   2. Else if `engine.liveCheckoutAutoStash` is an explicit boolean, use it.
- *   3. Else default false.
+ *   3. Else fall back to `shared.ENGINE_DEFAULTS.liveCheckoutAutoStash`
+ *      (default true as of W-mrawiym8000c42c9 — non-destructive, recoverable
+ *      via `git stash pop`, and now the first line of defense in the
+ *      dirty-tree recovery flow now that `liveCheckoutAutoReset` defaults off).
  *
  * Pure — no I/O. Tested in test/unit/live-checkout-auto-stash.test.js.
  *
@@ -1466,7 +1503,7 @@ function resolveLiveCheckoutAutoStash(opts = {}) {
   if (engine && typeof engine.liveCheckoutAutoStash === 'boolean') {
     return engine.liveCheckoutAutoStash;
   }
-  return false;
+  return shared.ENGINE_DEFAULTS.liveCheckoutAutoStash;
 }
 
 /**
@@ -1536,11 +1573,29 @@ async function performLiveCheckoutAutoStash(opts = {}) {
  *
  * Returns a discriminated outcome the caller acts on:
  *   - `{ outcome:'unchanged', liveResult }` — not dirty, disabled, or stash failed
- *     (caller falls through to the existing retry-once-then-fail dirty handling).
+ *     (caller falls through to the existing retry-once-then-fail dirty handling,
+ *     or — W-mrawgw4q000a6bff — to an explicit `liveCheckoutAutoReset` fallback
+ *     when that policy also resolves true; see engine.js spawnAgent).
  *   - `{ outcome:'stashed', liveResult }`   — stashed + re-preflighted; proceed.
  *   - `{ outcome:'threw', error }`           — the re-preflight threw; caller must
  *     fail the dispatch as LIVE_CHECKOUT_FAILED (engine-specific completion).
  *
+ * W-mrawgw4q000a6bff — stash-before-reset ordering + no auto-sync-to-origin.
+ * The re-preflight (step 2) is called with `autoReset:false` so a still-dirty
+ * tree after a successful stash NEVER silently falls through to a destructive
+ * reset here — reset is only ever triggered explicitly by the caller as a
+ * documented last-resort fallback. Also, by design, this function does NOT
+ * follow up a successful stash with a `git merge --ff-only origin/<mainRef>`
+ * to re-sync the branch: `liveCheckoutAutoStash`'s contract (see
+ * `resolveLiveCheckoutAutoStash` above) has only ever been "park the dirty
+ * changes so dispatch can proceed", never "keep the branch in sync with
+ * origin" — that stronger guarantee is what `liveCheckoutAutoReset` is for,
+ * and it is still available as an explicit opt-in for dispatches that need it
+ * (with stash getting first crack at the tree, non-destructively, per the new
+ * ordering). Adding an implicit ff-only sync here would blur that line and
+ * risk a "successful" stash silently leaving a merge commit or a still-dirty
+ * tree if the ff fails — so it was deliberately left out.
+ *
  * @param {object} opts
  * @returns {Promise<{outcome:'unchanged'|'stashed'|'threw', liveResult?:object, error?:Error}>}
  */
@@ -1549,6 +1604,7 @@ async function applyLiveCheckoutAutoStash(opts = {}) {
     liveResult, project, engine, localPath, branchName, mainRef,
     gitOpts, dispatchId, wiId, log,
     clearDirtyStamp, writeStashNote,
+    _git, // private injection for testing — forwarded to performLiveCheckoutAutoStash + the re-preflight prepareLiveCheckout call
   } = opts;
   const logFn = (typeof log === 'function') ? log : () => {};
   const reason = (liveResult && liveResult.ok === false) ? liveResult.reason : null;
@@ -1557,7 +1613,7 @@ async function applyLiveCheckoutAutoStash(opts = {}) {
   }
   let stashResult;
   try {
-    stashResult = await performLiveCheckoutAutoStash({ localPath, dispatchId, gitOpts, log });
+    stashResult = await performLiveCheckoutAutoStash({ localPath, dispatchId, gitOpts, log, _git });
   } catch (stashErr) {
     stashResult = { ok: false, error: stashErr && stashErr.message };
   }
@@ -1567,7 +1623,10 @@ async function applyLiveCheckoutAutoStash(opts = {}) {
   }
   let newLive;
   try {
-    newLive = await prepareLiveCheckout({ localPath, branchName, mainRef, gitOpts, dispatchId, wiId, log });
+    // autoReset:false — see the function doc above; a still-dirty tree after a
+    // successful stash must never silently fall through to a destructive reset
+    // inside this re-preflight.
+    newLive = await prepareLiveCheckout({ localPath, branchName, mainRef, gitOpts, dispatchId, wiId, log, autoReset: false, _git });
   } catch (stashLiveErr) {
     return { outcome: 'threw', error: stashLiveErr };
   }

package/engine/playbook.js

@@ -307,6 +307,7 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   'references',           // only set when item.references has entries
   'acceptance_criteria',  // only set when item.acceptanceCriteria has entries
   'checkpoint_context',   // only set when resuming from a prior timeout
+  'retry_context',      // only set when retrying after a validation-gate failure (#893)
   // Host-specific identifiers — always one of {ado_*, github_*} is empty
   // (project is either ADO or GitHub, never both). Keeping them as warns
   // produces ~96 noise lines per day on a single-host project.

package/engine/pr-action.js

@@ -85,16 +85,20 @@ const PR_ACTION_FOLLOWUPS = Object.freeze([
   { kind: 'track-auto-fix', label: 'Track for auto-fix' },
 ]);
 
-/** Canonical `host:slug#number` id for a record/ref, or '' when unknowable. */
+/**
+ * Canonical `host:slug#number` id for a record/ref, or '' when unknowable.
+ *
+ * Thin wrapper over prResolve.prIdFromRef: normalizes the heterogeneous
+ * record shapes buildPrActionFollowups is called with — an explicit
+ * `record.prId`, a `record.ref` ref object, or a bare ref-shaped object
+ * (`{host, slug, number}`/`{id}`) — into the ref shape prIdFromRef expects,
+ * then delegates so the `host:slug#number` template literal has one owner.
+ */
 function _prIdForRecord(record) {
   if (!record) return '';
   if (record.prId) return record.prId;
   const ref = record.ref || record;
-  if (ref && ref.id) return ref.id;
-  if (ref && ref.host && ref.slug && (ref.number || ref.number === 0)) {
-    return `${ref.host}:${ref.slug}#${ref.number}`;
-  }
-  return '';
+  return prResolve.prIdFromRef(ref) || '';
 }
 
 /**
@@ -364,7 +368,8 @@ function buildPrActionPrompt(action, payload) {
     number: payload && payload.number,
     id: payload && payload.prId,
   };
-  const prId = ref.id || (ref.host && ref.slug && ref.number ? `${ref.host}:${ref.slug}#${ref.number}` : (payload && payload.slug ? `${payload.slug}#${payload.number}` : 'the pull request'));
+  const prId = prResolve.prIdFromRef(ref)
+    || (payload && payload.slug ? `${payload.slug}#${payload.number}` : 'the pull request');
   const guidance = PR_ACTION_GUIDANCE[act] || PR_ACTION_GUIDANCE.review;
 
   const sections = [