@yemi33/minions 0.1.2288 → 0.1.2290

package/engine.js

@@ -2380,6 +2380,7 @@ async function spawnAgent(dispatchItem, config) {
         gitOpts: _gitOpts,
         dispatchId: id,
         wiId: _wiIdForAlert,
+        skipDirtyCheck: !!project.skipLiveCheckoutDirtyCheck,
         log: (msg, lvl) => log(lvl || 'info', msg),
       });
     } catch (liveErr) {
@@ -5283,6 +5284,7 @@ async function spawnAgent(dispatchItem, config) {
           isTerminalFailure: effectiveResult !== DISPATCH_RESULT.SUCCESS,
           resultLabel: errorReason || effectiveResult,
           gitOpts: _gitOpts,
+          skipDirtyCheck: !!project?.skipLiveCheckoutDirtyCheck,
           log,
           writeInboxAlert,
         });
@@ -5792,6 +5794,63 @@ function reservePrdFilename(prdDir, baseFileName, content = '') {
   throw new Error('Could not reserve unique PRD filename after 100 attempts');
 }
 
+// Fleet branches the engine/CC create. A worktree-mode operator checkout should
+// NEVER sit on one of these (or any branch); when it does, a flow ran raw
+// `git checkout`/`merge` in the live checkout instead of a worktree.
+const _FLEET_BRANCH_RE = /^(cc-pr|backport|e2e|verify|sched-|work)\//;
+
+// Self-heal: a worktree-mode project's operator checkout (project.localPath) must
+// always sit on its mainBranch — agents use isolated worktrees, CC Create-PR uses
+// prepare-create-pr-worktree. But fleet flows (CC raw git, backport, sync)
+// sometimes run `git checkout <branch>` + `git merge` THERE despite the rules,
+// leaving it stuck on a feature branch (often mid-conflict) — which restores
+// git-tracked dead PRDs and pollutes the operator's main, then the materializer
+// re-runs finished work. Detect + restore. Conservative: only acts on a stuck
+// merge/rebase OR a recognizably fleet-created branch, so a human's deliberate
+// `git checkout my-feature` in their checkout is left alone. Branch commits are
+// preserved on their ref (reset --hard only drops the uncommitted hijack state).
+function restoreHijackedOperatorCheckouts(config) {
+  if (config?.engine?.autoRestoreOperatorCheckout === false) return;
+  let projects;
+  try { projects = getProjects(config); } catch { return; }
+  for (const project of projects) {
+    try {
+      const localPath = project?.localPath;
+      if (!localPath || !fs.existsSync(localPath)) continue;
+      if (shared.resolveCheckoutMode(project) === shared.CHECKOUT_MODES.LIVE) continue; // live-mode: feature branch is intentional
+      const main = project.mainBranch || 'main';
+      if (String(execSilent('git rev-parse --is-inside-work-tree', { cwd: localPath }) || '').trim() !== 'true') continue;
+      const cur = String(execSilent('git rev-parse --abbrev-ref HEAD', { cwd: localPath }) || '').trim();
+      if (!cur || cur === 'HEAD' || cur === main) continue; // on main or detached — fine
+      const gitDir = String(execSilent('git rev-parse --git-dir', { cwd: localPath }) || '').trim();
+      const absGitDir = gitDir ? (path.isAbsolute(gitDir) ? gitDir : path.join(localPath, gitDir)) : path.join(localPath, '.git');
+      const mergeStuck = fs.existsSync(path.join(absGitDir, 'MERGE_HEAD'));
+      const rebaseStuck = fs.existsSync(path.join(absGitDir, 'rebase-merge')) || fs.existsSync(path.join(absGitDir, 'rebase-apply'));
+      if (!mergeStuck && !rebaseStuck && !_FLEET_BRANCH_RE.test(cur)) continue; // likely a human's deliberate checkout — leave it
+      const why = mergeStuck ? ' (stuck merge)' : rebaseStuck ? ' (stuck rebase)' : ' (fleet branch in live checkout)';
+      log('warn', `Operator checkout for ${project.name} is on '${cur}'${why}; worktree-mode requires ${main} — restoring`);
+      const opts = { cwd: localPath };
+      if (mergeStuck) execSilent('git merge --abort', opts);
+      if (rebaseStuck) execSilent('git rebase --abort', opts);
+      execSilent('git reset --hard HEAD', opts); // drop uncommitted hijack state; branch commits stay on the ref
+      try { shared.validateGitRef(main); } catch (ve) { throw new Error(`restoreHijackedOperatorCheckouts: invalid mainBranch ${JSON.stringify(main)}: ${ve.message}`); }
+      shared.shellSafeGitSync(['checkout', main], opts);
+      const now = String(execSilent('git rev-parse --abbrev-ref HEAD', { cwd: localPath }) || '').trim();
+      if (now === main) {
+        try {
+          writeInboxAlert(`operator-checkout-restored-${project.name}`,
+            `Operator checkout ${localPath} was hijacked onto '${cur}'${why} and restored to ${main}. ` +
+            'A fleet flow ran git checkout/merge in the LIVE operator checkout instead of an isolated worktree ' +
+            '(playbooks/shared-rules.md: "Do NOT checkout branches in the main working tree — use worktrees"). ' +
+            `The '${cur}' branch commits are preserved on its ref.`);
+        } catch { /* alert is best-effort */ }
+      } else {
+        log('warn', `Operator checkout restore for ${project.name} did not reach ${main} (now '${now}') — manual intervention needed`);
+      }
+    } catch (e) { log('warn', `restoreHijackedOperatorCheckouts ${project?.name || '?'}: ${e?.message || e}`); }
+  }
+}
+
 function materializePlansAsWorkItems(config) {
   if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch (e) { log('warn', 'create PRD directory: ' + e.message); } }
   const writePrdLocked = (fileName, data) => {
@@ -6027,6 +6086,19 @@ function materializePlansAsWorkItems(config) {
     // (W-mouptdh1000h9f39).
     let plan = safeJsonNoRestore(path.join(PRD_DIR, file));
     if (!plan?.missing_features) continue;
+    // Resurrection-re-execution guard ("old PRDs came back"): never (re)materialize
+    // a defunct PRD — archived, or completed with its source plan gone from plans/.
+    // Such a PRD can linger in prd/ with stale `missing`-status items; without
+    // this, the materializer re-creates and re-runs already-finished work (it only
+    // filters per-item by PRD_MATERIALIZABLE, which a stale 'missing' item passes).
+    if (shared.isDefunctPrd(plan, PLANS_DIR)) {
+      if (!_defunctPrdSkipLogged.has(file)) {
+        log('info', `Skipping defunct PRD ${file} (archived or completed with archived/removed source plan) — not re-materializing`);
+        _defunctPrdSkipLogged.add(file);
+      }
+      continue;
+    }
+    _defunctPrdSkipLogged.delete(file);
     ({ fileName: file, plan } = enforceDeclaredPlanProject(file, plan));
 
     // ID collision prevention: remap sequential IDs (P-001, P-002) to globally unique P-<uid> IDs.
@@ -8833,7 +8905,7 @@ function discoverCentralWorkItems(config) {
         const prdFiles = safeReadDir(PRD_DIR).filter(f => f.endsWith('.json'));
         for (const pf of prdFiles) {
           const prd = safeJson(path.join(PRD_DIR, pf));
-          if (planKey && prd && path.basename(String(prd.source_plan || '')) === planKey) {
+          if (planKey && prd && !shared.isPrdArchived(prd) && shared.prdMatchesSourcePlan(prd.source_plan, planKey)) {
             prdFilename = pf;
             try { vars.existing_prd_json = fs.readFileSync(path.join(PRD_DIR, pf), 'utf8'); } catch (_) { /* ignore */ }
             log('info', `plan-to-prd: reusing existing PRD "${pf}" for plan "${item.planFile}" (#884)`);
@@ -9129,21 +9201,25 @@ async function discoverWork(config) {
         // (W-mouptdh1000h9f39). Idempotent and fast — readdir + existsSync.
         sweepStaleArchivedPrdBackups(prdDir, prdArchiveDir);
 
-        // Pass 2 — Existing orphan ghost-PRD purge + completion sweep.
+        // Pass 2 — completion sweep. (The ghost-PRD purge that used to live here
+        // was a REDUNDANT + UNSAFE duplicate of the plan-completion scan's
+        // version: it unlinked prd/<f> whenever prd/archive/<f> existed, with NO
+        // `_isGhostPrdRestore` identity check — the exact footgun #7 (#496)
+        // hazard of deleting a legitimately re-opened PRD that shares an archived
+        // basename. The plan-completion scan does the same purge safely (identity-
+        // checked + neutralize); here the isDefunctPrd guard below already skips
+        // archived/defunct PRDs, so this loop never re-runs completion on a ghost.)
         for (const f of fs.readdirSync(prdDir).filter(f => f.endsWith('.json'))) {
           if (completedPlanCache.has(f)) continue;
-          if (fs.existsSync(path.join(prdArchiveDir, f))) {
-            // Orphaned backup restore — plan is already archived. Purge the ghost copy.
-            try { fs.unlinkSync(path.join(prdDir, f)); } catch { }
-            try { fs.unlinkSync(path.join(prdDir, f + '.backup')); } catch { }
-            completedPlanCache.add(f);
-            continue;
-          }
           // safeJsonNoRestore — defense in depth: if the file vanished between
           // readdir and read (e.g. concurrent archive), do not resurrect it
           // from a stale .backup sidecar (W-mouptdh1000h9f39).
           const plan = safeJsonNoRestore(path.join(prdDir, f));
           if (!plan?.missing_features) continue;
+          // Resurrection guard (mirror of completion-scan-B / #523): never re-run
+          // completion (which re-creates the verify gate) for a defunct PRD —
+          // archived, or completed with its plan gone from plans/.
+          if (shared.isDefunctPrd(plan, PLANS_DIR)) { completedPlanCache.add(f); continue; }
           // A completed PRD may still be missing its aggregate verify WI — e.g. it
           // landed on disk pre-completed via the plan-to-prd / pipeline path, so no
           // agent-completion event ever drove checkPlanCompletion (W-mqk5ld3p). The
@@ -9335,6 +9411,9 @@ let tickCount = 0;
 // In-memory cache of plan filenames confirmed completed — avoids redundant
 // checkPlanCompletion calls.  Cleared automatically on engine restart.
 const completedPlanCache = new Set();
+// Dedupe the "Skipping defunct PRD" materializer log so a lingering defunct PRD
+// doesn't spam one line per discovery tick; cleared when the file stops being defunct.
+const _defunctPrdSkipLogged = new Set();
 // Filenames where a live PRD shares a basename with an archived PRD but diverges
 // (different source_plan / introduces new work). We refuse to auto-purge those
 // and warn once instead of every tick. (RC4 — footgun #7 collision protection.)
@@ -9795,6 +9874,12 @@ async function tickInner() {
           }
         }
         const plan = safeJson(path.join(PRD_DIR, file));
+        // Resurrection-re-execution guard: a defunct PRD (archived, or completed
+        // with its source plan gone from plans/) must NOT have its verify gate
+        // re-created. This scan deliberately re-runs completion for completed
+        // PRDs (to build the aggregate verify task), which is exactly how a
+        // resurrected/lingering completed PRD spawned spurious verify WIs.
+        if (shared.isDefunctPrd(plan, PLANS_DIR)) { completedPlanCache.add(file); continue; }
         if (plan && plan.missing_features) {
           // Run for completed PRDs too — a pre-completed plan (flag already set,
           // items pre-marked done) still needs its aggregate verify gate created.
@@ -10413,6 +10498,9 @@ async function tickInner() {
     const maxC = resolveMaxConcurrent(config);
     setTempBudget(Math.max(0, maxC - activeCountPre));
   }
+  // Self-heal a hijacked operator checkout BEFORE discovery/materialization, so a
+  // dead PRD restored by a stray `git checkout` can't be re-materialized this tick.
+  try { restoreHijackedOperatorCheckouts(config); } catch (e) { log('warn', 'restoreHijackedOperatorCheckouts: ' + e.message); }
   let discoveryOk = true;
   try { await withTickTimeout(() => discoverWork(config), 'discoverWork', tickOpTimeoutMs); } catch (e) { log('warn', 'discoverWork: ' + e.message); discoveryOk = false; }
   if (_isTickStale(myGeneration)) return;
@@ -10514,6 +10602,7 @@ module.exports = {
   materializePlansAsWorkItems,
   materializeSpecsAsWorkItems, // exported for testing (P-f7-git-log)
   reservePrdFilename, // exported for testing (P-9b7e5d3c)
+  restoreHijackedOperatorCheckouts, // exported for testing — operator-checkout self-heal
   sweepStaleArchivedPrdBackups, // exported for testing
   _isGhostPrdRestore, // exported for testing (RC4 — ghost-purge identity check)
 
@@ -10577,7 +10666,54 @@ module.exports = {
 
 // ─── Entrypoint ─────────────────────────────────────────────────────────────
 
+// Source-level defense against agents committing prd/*.json + plans/*.md
+// (gitignored engine work-plan state) as if they were deliverables — a tracked
+// PRD resurrects + re-executes on the next checkout ("old PRDs came back"). The
+// hook is GENERATED at runtime into the repo's git hooks dir (NOT committed —
+// opg push-protection blocks committed hooks, and committing one would itself be
+// the kind of supply-chain footgun we're guarding against). The git common hooks
+// dir is shared across all worktrees, so the operator checkout AND every agent
+// worktree are covered. Idempotent; never clobbers a foreign pre-commit hook.
+const PRD_PRECOMMIT_HOOK = [
+  '#!/bin/sh',
+  '# Minions guard (engine-generated; not committed). prd/*.json + plans/*.md are',
+  '# gitignored runtime state and must NEVER be committed — a tracked PRD/plan is',
+  '# resurrected by git checkout/reset/merge and re-runs finished work. See',
+  '# engine.js ensureGitHooksInstalled. Bypass (rarely): git commit --no-verify.',
+  "blocked=$(git diff --cached --name-only --diff-filter=AM | grep -E '^prd/.*\\.json$|^plans/.*\\.md$' || true)",
+  'if [ -n "$blocked" ]; then',
+  '  echo "" 1>&2',
+  '  echo "  Refusing to commit gitignored Minions runtime state (prd/ + plans/ guard):" 1>&2',
+  '  echo "$blocked" | sed \'s/^/      /\' 1>&2',
+  '  echo "  Internal work-plan artifacts, not deliverables. Unstage: git reset HEAD -- prd/ plans/" 1>&2',
+  '  echo "  (genuinely intentional? bypass with: git commit --no-verify)" 1>&2',
+  '  exit 1',
+  'fi',
+  'exit 0',
+  '',
+].join('\n');
+
+function ensureGitHooksInstalled() {
+  try {
+    const inWorkTree = String(shared.execSilent('git rev-parse --is-inside-work-tree', { cwd: MINIONS_DIR }) || '').trim();
+    if (inWorkTree !== 'true') return;
+    const hooksRel = String(shared.execSilent('git rev-parse --git-path hooks', { cwd: MINIONS_DIR }) || '').trim();
+    if (!hooksRel) return;
+    const hooksDir = path.isAbsolute(hooksRel) ? hooksRel : path.join(MINIONS_DIR, hooksRel);
+    const hookFile = path.join(hooksDir, 'pre-commit');
+    let existing = null;
+    try { existing = fs.readFileSync(hookFile, 'utf8'); } catch { /* absent */ }
+    if (existing === PRD_PRECOMMIT_HOOK) return; // already current
+    if (existing && !existing.includes('Minions guard')) return; // respect a foreign hook
+    fs.mkdirSync(hooksDir, { recursive: true });
+    fs.writeFileSync(hookFile, PRD_PRECOMMIT_HOOK);
+    try { fs.chmodSync(hookFile, 0o755); } catch { /* non-posix */ }
+    log('info', `Installed git pre-commit guard (${hookFile}) — blocks committing prd/*.json + plans/*.md`);
+  } catch { /* best-effort */ }
+}
+
 if (require.main === module) {
+  try { ensureGitHooksInstalled(); } catch { /* best-effort */ }
   // Every copilot this process spawns — agent dispatches AND internal
   // `llm.callLLM` calls (consolidation, classification, meetings, …) — inherits
   // this process's COPILOT_HOME, so point it at the seeded, MCP-filtered home.

package/package.json

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

package/playbooks/plan-to-prd.md

@@ -191,10 +191,11 @@ If the task description contains `mode: diff-aware-update`, you are updating an
 - Write ONLY the single `.json` PRD file to `{{team_root}}/prd/` — do NOT write any `.md` files there
 - Do NOT create a git branch, worktree, or PR — this playbook writes minions-internal state only
 - Do NOT modify any files in the project repo
+- **NEVER run `git add prd/` or `git add -f prd/` — PRD files are gitignored runtime artifacts (`prd/*.json` is in `.gitignore`). Force-adding them exposes internal work plans in the public repo diff. A CI guard (`test/unit/prd-not-git-tracked.test.js`) will fail the PR if you do this, and you will be required to run `git rm --cached prd/<file>.json` to undo it.**
 - The engine will dispatch implementation agents automatically once the JSON file exists
 - For `shared-branch`: agents commit to a single branch — one PR is created automatically when all items are done
 - For `parallel`: each agent creates its own branch and PR
 
 ## When to Stop
 
-Your task is complete once you have written the PRD JSON file to `{{team_root}}/prd/{{prd_filename}}`. The engine will detect the file and begin dispatching work. Do NOT create branches, PRs, or modify project code. Stop after writing the JSON file.
+Your task is complete once you have written the PRD JSON file to `{{team_root}}/prd/{{prd_filename}}`. The engine will detect the file and begin dispatching work. Do NOT run any git commands. Do NOT create branches, PRs, or modify project code. Stop after writing the JSON file.

package/playbooks/shared-rules.md

@@ -86,6 +86,7 @@ This task is part of a **shared-branch plan** — every plan item shares the bra
 - Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
 - Do NOT remove worktrees — the engine handles cleanup automatically.
 - Do NOT checkout branches in the main working tree — use worktrees or `git diff`/`git show`.
+- **NEVER run `git checkout <branch>` / `git switch` / `git merge` / `git rebase` / `git cherry-pick` in a project's operator checkout (`project.localPath`, e.g. the configured repo root).** That tree must stay on its main branch. For ANY branch operation — backport, sync, cross-branch merge, "create a PR off branch X" — create an isolated worktree first: `git -C <localPath> worktree add <scratch-path> <base>`, do all checkout/merge/commit/push **inside that worktree**, then `git -C <localPath> worktree remove <scratch-path>`. Running these in the live checkout pollutes the operator's main, leaves stuck-merge conflicts, and resurrects gitignored runtime state (the "old PRDs came back" incident). The engine auto-restores a hijacked operator checkout and files an inbox alert, but do not rely on that — use a worktree.
 - Treat `notes/inbox/` writes as success artifacts only. If the task fails, is blocked, is cancelled, or ends partial, do **not** create an inbox note; report the failure in your final response, completion block, PR/work-item comment, or other task-specific failure channel instead.
 - Read `notes.md` for team rules and decisions before starting.
 - **Check team memory first, then look outside.** Before researching from scratch, check what the team already knows — in this order: