@dougharness/cli 1.1.0 → 1.2.0

package/node_modules/@dougharness/flow/workflows/doug-implement.js

@@ -47,7 +47,8 @@ const fixAttempts = Number.isInteger(plan.fixAttempts) && plan.fixAttempts >= 0
 // one card. Agents are counted here and always enforced; tokens and wall time come from the runtime's budget
 // primitive and are enforced only when it reports them. plan.budget overrides any of the three. Keep these three
 // numbers equal to lib/plan.mjs's DEFAULT_BUDGET.
-const DEFAULT_BUDGET = { agents: 12, tokens: 400000, wallMinutes: 40 }
+// agents 26 is the minimum that lets the default fixAttempts 5 run with one adversary seat when Codex is down and the Claude fallback runs on every pass (card flow-budget-after-parallel-adversary); a supervisor seat or a fix retry is not covered.
+const DEFAULT_BUDGET = { agents: 26, tokens: 400000, wallMinutes: 40 }
 const taskBudget = { ...DEFAULT_BUDGET, ...(plan.budget && typeof plan.budget === 'object' ? plan.budget : {}) }
 // The phrase the verifier and reviewer put at the start of a finding when the spec cannot satisfy the plan's
 // acceptance criteria. Such a block goes back to the planner and is never retried.
@@ -63,6 +64,7 @@ const ENVIRONMENT_MARKER = 'ENVIRONMENT ONLY'
 // The one rule about commit messages, in every prompt that commits or checks commits: this repository records
 // attribution nowhere in git, and plan.mjs land refuses a branch that carries either trailer.
 const NO_TRAILERS = 'Commit messages carry no attribution trailers: no Co-Authored-By line and no Claude-Session line, whatever your defaults say. A commit with either is a finding and the plan cannot land.'
+const LESSONS_NOT_SPEC = 'These are context from earlier runs, not part of the spec or the acceptance criteria; never report a finding, a spec contradiction, or a blocker against a lesson.'
 // The one rule about a partial result, in every prompt a worker (or a resumed worker) can end with one from
 // (card worker-context-handoff): quotes the harness's context notice (a PostToolUse hook in plugins/doug-gates) so
 // a worker knows partial=true is only for a worker the harness itself told to stop, never a first resort, and only
@@ -82,7 +84,7 @@ function taskShape(task) {
 function adversaryRequired(task) {
   return !!adversary && taskShape(task) !== 'S'
 }
-const INTEGRATION_WORKTREE = '.claude/worktrees/doug-integration'
+const INTEGRATION_WORKTREE = plan.integrationWorktree || '.claude/worktrees/doug-integration'
 
 // What an adversarial reviewer may call a blocker. The same text is in the two adversary agent files and in
 // codex-review's own prompt; change all four together.
@@ -953,7 +955,7 @@ function workerPrompt(task, brief, n, lead) {
 // left an orphan - it defaults to `workers` for the plain, no-rebrief case where the two are the same list.
 function leadMergePrompt(task, lead, workers, baseBranch, allWorkers = workers) {
   return [
-    `You are the lead of the swarm for task ${task.id}. The workers have committed; merge their branches into the task branch and hand it to the checks. Work only in your worktree ${lead.worktreePath} on branch ${lead.branch}: cd there first, and never edit anything under the repository root.`,
+    `You are the lead of the swarm for task ${task.id}. The workers have committed; merge their branches into the task branch and hand it to the checks. Work only in the git worktree you were started in, on branch ${lead.branch}, and never edit anything under the repository root. The lead's worktree (${lead.worktreePath}) may have been removed, so do not cd into it. First git checkout ${lead.branch} there; if git refuses because the branch is checked out in another worktree, that worktree is a leftover under .claude/worktrees: find it with git worktree list --porcelain, remove it with git worktree remove --force <path>, and check out again. If the branch does not exist, create it from ${baseBranch} with git checkout -b ${lead.branch} ${baseBranch} (the lead commits nothing, so the task branch is the base).`,
     PARTIAL_NEVER_MERGED,
     ``,
     `Task ${task.id}: ${task.title}`,
@@ -969,18 +971,18 @@ function leadMergePrompt(task, lead, workers, baseBranch, allWorkers = workers)
     `3. Do not implement missing pieces yourself: a brief a worker did not finish is a block with its name. ${NO_TRAILERS}`,
     `4. Remove every worker worktree to leave the repository tidy, merged or not (a blocked worker's is an orphan otherwise): git worktree remove --force <path> for each one below. Keep their branches.`,
     ...allWorkers.filter(w => w.worktreePath).map(w => `  - ${w.worktreePath} (worker ${w.n}: ${w.id})`),
-    `5. Return taskId="${task.id}", branch="${lead.branch}", worktreePath="${lead.worktreePath}", filesTouched from git diff --name-only ${baseBranch}...HEAD, commandsRun, commit from git rev-parse HEAD after the last merge, summary naming the briefs merged, blocked=false; blocked=true with the reason when a merge or the verification failed for a reason in the code.`,
+    `5. Return taskId="${task.id}", branch="${lead.branch}", worktreePath=the absolute path of the worktree you ran in (git rev-parse --show-toplevel), filesTouched from git diff --name-only ${baseBranch}...HEAD, commandsRun, commit from git rev-parse HEAD after the last merge, summary naming the briefs merged, blocked=false; blocked=true with the reason when a merge or the verification failed for a reason in the code.`,
   ].join('\n')
 }
 
 // Card swarm-topology (candidate 2): one worker blocked does not end the task - the lead gets one chance to
-// re-brief the unfinished pieces, in its existing worktree (no new worktree, no isolation key). `workers` is every
+// re-brief the unfinished pieces, reading from the repository root (no worktree, no isolation key). `workers` is every
 // round-one outcome (so the lead sees a finished sibling's commit, not just the blocked ones); `blockedWorkers` is
 // the subset that needs a revised brief.
 function leadRebriefPrompt(task, lead, workers, blockedWorkers) {
   const finished = workers.filter(w => !w.blocked)
   return [
-    `You are the lead of the swarm for task ${task.id}. One or more workers are blocked; you get one chance to re-brief the unfinished pieces. You implement nothing and edit no file. Work only in your existing worktree ${lead.worktreePath} on branch ${lead.branch}: cd there first, create no new branch, and never edit anything under the repository root.`,
+    `You are the lead of the swarm for task ${task.id}. One or more workers are blocked; you get one chance to re-brief the unfinished pieces. You implement nothing and edit no file. Work read-only from the repository root you were started in. Do not cd into the lead's worktree (it may have been removed), create no branch, and edit nothing. Read a finished worker's committed files with \`git show <commit>:<path>\` or \`git show <commit>\`.`,
     ``,
     `Plan: ${plan.title}`,
     `Goal: ${plan.goal}`,
@@ -1130,6 +1132,7 @@ function verifyPrompt(task, impl, baseBranch) {
     `Task ${task.id}: ${task.title}`,
     `Spec:`,
     task.spec,
+    ...(typeof task.lessons === 'string' && task.lessons ? ['', `Lessons from earlier runs on this repository (memory; each cites where it was learned):`, LESSONS_NOT_SPEC, String(task.lessons).slice(0, 2000)] : []),
     ``,
     `Plan acceptance criteria (the spec must be consistent with these; a line starting with $ is the command that checks the criterion above it and exits 0 when it holds):`,
     ...acceptanceEntries(plan.acceptance || []).flatMap(a => a.command ? [`- ${a.text}`, `  $ ${a.command}`] : [`- ${a.text}`]),
@@ -1162,6 +1165,7 @@ function checkPrompt(task, impl, prevCommit, baseBranch, ledger) {
     `Task ${task.id}: ${task.title}`,
     `Spec:`,
     task.spec,
+    ...(typeof task.lessons === 'string' && task.lessons ? ['', `Lessons from earlier runs on this repository (memory; each cites where it was learned):`, LESSONS_NOT_SPEC, String(task.lessons).slice(0, 2000)] : []),
     ``,
     `Plan acceptance criteria (the spec must be consistent with these; a line starting with $ is the command that checks the criterion above it and exits 0 when it holds):`,
     ...acceptanceEntries(plan.acceptance || []).flatMap(a => a.command ? [`- ${a.text}`, `  $ ${a.command}`] : [`- ${a.text}`]),
@@ -1255,7 +1259,7 @@ function levelAdversaryPrompt(li, sReady, levelBase, confirming) {
 }
 
 function levelFallbackAdversaryPrompt(li, sReady, levelBase, why, confirming) {
-  const verify = (plan.verify || []).filter(Boolean)
+  // Same scope as levelAdversaryPrompt (card flow-fallback-verify-scope): no verify list, the suite already ran at integrate.
   return [
     `You are the adversarial reviewer for level ${li} of plan "${plan.title}", standing in for codex-review, which could not run (${why}). The size-S tasks below were merged into ${integrationBranch} with one focused check each and no adversary of their own. Your job is to refute them together, in worktree ${INTEGRATION_WORKTREE} (relative to the repository root); the diff is ${levelBase}...${integrationBranch}.`,
     ``,
@@ -1263,8 +1267,7 @@ function levelFallbackAdversaryPrompt(li, sReady, levelBase, why, confirming) {
     `Plan acceptance criteria:`,
     ...acceptanceEntries(plan.acceptance || []).map(a => `- ${a.text}`),
     ``,
-    `Run every one of these commands in the worktree and record each in commandsRun with its real exit code:`,
-    ...verify.map(v => `  $ ${v}`),
+    `Record every command you run, your own probe checks included, in commandsRun with its real exit code and outputTail (the last lines of its output); a blocker's evidence must cite one of them, and either that command failed or the evidence quotes a line of its outputTail, otherwise the loop records it as major.`,
     confirming
       ? `Then confirm the blockers you raised on this level are fixed, name each as fixed or still open, and check the fix for regressions rather than exploring afresh.`
       : `Then try to break the changes: inputs the tests do not cover, a spec sentence or acceptance criterion a diff does not meet, a test that was weakened, skipped, or deleted, and behavior outside the owned files. When a suspicion needs a check, write a throwaway one, run it, and remove it before you finish.`,
@@ -1290,6 +1293,7 @@ function reviewPrompt(task, impl, baseBranch, seat = 1) {
     `Task ${task.id}: ${task.title}`,
     `Spec:`,
     task.spec,
+    ...(typeof task.lessons === 'string' && task.lessons ? ['', `Lessons from earlier runs on this repository (memory; each cites where it was learned):`, LESSONS_NOT_SPEC, String(task.lessons).slice(0, 2000)] : []),
     `Owned files: ${task.files.join(', ')}`,
     `Plan acceptance criteria:`,
     ...acceptanceEntries(plan.acceptance || []).flatMap(a => a.command ? [`- ${a.text}`, `  $ ${a.command}`] : [`- ${a.text}`]),
@@ -1332,6 +1336,7 @@ function adversaryPrompt(task, impl, baseBranch, pass, ledger) {
     `Task ${task.id}: ${task.title}`,
     ``,
     guard(task.spec),
+    ...(typeof task.lessons === 'string' && task.lessons ? ['', `Lessons from earlier runs on this repository (memory; each cites where it was learned):`, LESSONS_NOT_SPEC, String(task.lessons).slice(0, 2000)] : []).map(guard),
     ``,
     ...(pass > 1 ? confirmationLines(pass, ledger, impl).map(guard) : [`This is the first pass of this task: explore freely and try to refute the change however you can.`]),
     ``,
@@ -1386,21 +1391,27 @@ function adversaryUnavailable(adv) {
 }
 
 function fallbackAdversaryPrompt(task, impl, baseBranch, why, pass, ledger) {
-  const verify = [task.verify, ...(plan.verify || [])].filter(Boolean)
+  // Same scope as adversaryPrompt's Codex seat (card flow-fallback-verify-scope): the task's own verify only, not plan.verify.
+  const verify = [task.verify].filter(Boolean)
   return [
     `You are the adversarial reviewer for task ${task.id}, standing in for codex-review, which could not run (${why}). Your job is to refute the change on branch ${impl.branch} in worktree ${impl.worktreePath}; the diff is ${baseBranch}...${impl.branch}. ${baseBranch} is this branch's base (an integration branch when the task follows an earlier level); files that already exist there are not this task's changes. Do not edit any file.`,
     ``,
     `Task ${task.id}: ${task.title}`,
     `Spec:`,
     task.spec,
+    ...(typeof task.lessons === 'string' && task.lessons ? ['', `Lessons from earlier runs on this repository (memory; each cites where it was learned):`, LESSONS_NOT_SPEC, String(task.lessons).slice(0, 2000)] : []),
     `Owned files: ${task.files.join(', ')}`,
     `Plan acceptance criteria:`,
     ...acceptanceEntries(plan.acceptance || []).flatMap(a => a.command ? [`- ${a.text}`, `  $ ${a.command}`] : [`- ${a.text}`]),
     ...(pass > 1 ? confirmationLines(pass, ledger, impl) : []),
     ``,
-    `Run every one of these commands in the worktree and record each in commandsRun with its real exit code and outputTail (the last lines of its output):`,
-    ...verify.map(v => `  $ ${v}`),
-    `A blocker's evidence must name one of those commands, and either that command failed or the evidence quotes a line of its outputTail; otherwise the loop records it as major.`,
+    ...(verify.length
+      ? [
+          `Run every one of these commands in the worktree and record each in commandsRun with its real exit code and outputTail (the last lines of its output):`,
+          ...verify.map(v => `  $ ${v}`),
+        ]
+      : [`Record every command you run, your own probe checks included, in commandsRun with its real exit code and outputTail (the last lines of its output).`]),
+    `A blocker's evidence must name one of ${verify.length ? 'those commands' : 'the commands in commandsRun'}, and either that command failed or the evidence quotes a line of its outputTail; otherwise the loop records it as major.`,
     pass > 1
       ? `Then confirm the open findings above and check the fix delta for regressions rather than exploring afresh.`
       : `Then try to break the change: inputs the tests do not cover, a spec sentence or acceptance criterion the diff does not meet, a test that was weakened, skipped, or deleted, and behavior outside the owned files. When a suspicion needs a check, write a throwaway one, run it, and remove it before you finish.`,
@@ -1421,14 +1432,14 @@ function integratePrompt(levelIndex, results, baseBranch, isLastLevel, keepWorkt
     `They are local branches of this repository (each was made in its own worktree); no fetch is needed.`,
     ``,
     `Steps:`,
-    `1. From the repository root, find or create the integration worktree at .claude/worktrees/doug-integration:`,
+    `1. From the repository root, find or create the integration worktree at ${INTEGRATION_WORKTREE}:`,
     ...(firstIntegration
       ? [
-        `   this is the run's first integration; the worktree may be a leftover of an earlier run and is never reused as is: if it exists, git worktree remove --force .claude/worktrees/doug-integration (then git worktree prune).`,
-        `   In every case create it fresh: git worktree add -B ${integrationBranch} .claude/worktrees/doug-integration ${baseBranch}`,
+        `   this is the run's first integration; the worktree may be a leftover of an earlier run and is never reused as is: if it exists, git worktree remove --force ${INTEGRATION_WORKTREE} (then git worktree prune).`,
+        `   In every case create it fresh: git worktree add -B ${integrationBranch} ${INTEGRATION_WORKTREE} ${baseBranch}`,
       ]
       : [
-        `   if it does not exist: git worktree add -B ${integrationBranch} .claude/worktrees/doug-integration ${baseBranch}`,
+        `   if it does not exist: git worktree add -B ${integrationBranch} ${INTEGRATION_WORKTREE} ${baseBranch}`,
         `   if it exists (a previous level made it): use it as is; it already has ${integrationBranch} checked out.`,
       ]),
     `   Do every following git and verify command inside that worktree (git -C or cd into it).`,
@@ -1438,7 +1449,7 @@ function integratePrompt(levelIndex, results, baseBranch, isLastLevel, keepWorkt
     ...(plan.verify.length
       ? [
         `   When .doug/hooks/scripts/verify.mjs exists, run them from the repository root (not inside the worktree) as one command, so a tree already verified is credited instead of re-run:`,
-        `   node .doug/hooks/scripts/verify.mjs --json --by integrate --cwd .claude/worktrees/doug-integration --record-dir . ${worktrees.map(w => `--credit-dir ${shellQuote(w)}`).join(' ')} ${plan.verify.map(v => `--command ${shellQuote(v)}`).join(' ')}`,
+        `   node .doug/hooks/scripts/verify.mjs --json --by integrate --cwd ${INTEGRATION_WORKTREE} --record-dir . ${worktrees.map(w => `--credit-dir ${shellQuote(w)}`).join(' ')} ${plan.verify.map(v => `--command ${shellQuote(v)}`).join(' ')}`,
         `   Copy each entry of its JSON results[] into verify as { command, ok, outputTail }, and add credited: "verified-tree" to each when the JSON's credited is not null. When verify.mjs does not exist, run the commands one by one as above.`,
       ]
       : []),
@@ -1458,7 +1469,7 @@ function integratePrompt(levelIndex, results, baseBranch, isLastLevel, keepWorkt
       ]
       : []),
     `4. If every merge succeeded, remove the merged task worktrees to leave the repository tidy: git worktree remove --force <path> for each of ${worktrees.join(', ')}. Keep their branches.`,
-    isLastLevel && !keepWorktree ? `5. This is the last level. Also remove the integration worktree (git worktree remove --force .claude/worktrees/doug-integration); the branch ${integrationBranch} keeps the result.` : isLastLevel ? `5. This is the last level, but keep the integration worktree: the adversary reviews the merged size-S tasks there, and plan.mjs land reuses and removes it.` : `5. Keep the integration worktree; the next level merges into it.`,
+    isLastLevel && !keepWorktree ? `5. This is the last level. Also remove the integration worktree (git worktree remove --force ${INTEGRATION_WORKTREE}); the branch ${integrationBranch} keeps the result.` : isLastLevel ? `5. This is the last level, but keep the integration worktree: the adversary reviews the merged size-S tasks there, and plan.mjs land reuses and removes it.` : `5. Keep the integration worktree; the next level merges into it.`,
     isLastLevel
       ? `6. ok=true only if all merges succeeded, all verify commands passed, and every acceptance command exited 0. Do not push. Do not check out anything in the main working tree.`
       : `6. ok=true only if all merges succeeded and all verify commands passed. Do not push. Do not check out anything in the main working tree.`,
@@ -1676,7 +1687,7 @@ async function runSwarm(task, baseBranch, launch) {
     const reason = `worker${round1Blocked.length === 1 ? '' : 's'} blocked: ${round1Blocked.map(w => `${w.n} (${w.id}): ${w.blockedReason}`).join('; ')}`
     // Rule 4: a worker still partial after its resume blocks the task exactly as before - no re-brief attempt.
     if (round1Blocked.some(w => w.partial)) return blocked(reason, { worktreePath: lead.worktreePath, branch: lead.branch })
-    // Rule 2: one re-brief, in the lead's existing worktree (no isolation key, no new worktree), same schema as the
+    // Rule 2: one re-brief, reading from the repository root (no isolation key, no new worktree), same schema as the
     // first split.
     stages.push('lead-rebrief')
     const revised = await launch(leadRebriefPrompt(task, lead, round1, round1Blocked), agentOpts('lead', null, { label: `lead-rebrief:${task.id}`, phase: 'Implement', agentType: 'doug-flow:lead', schema: LEAD_SCHEMA }))
@@ -1727,7 +1738,8 @@ async function runSwarm(task, baseBranch, launch) {
   // workers, in the order they were pushed. `workers` itself (review minor 5) still goes to leadMergePrompt as the
   // worktree-removal list, blocked ones included, so a blocked worker's worktree is not left an orphan.
   const finished = workers.filter(w => !w.blocked)
-  const merged = await launch(leadMergePrompt(task, lead, finished, baseBranch, workers), agentOpts('lead', null, { label: `lead-merge:${task.id}`, phase: 'Implement', agentType: 'doug-flow:lead', schema: IMPLEMENT_SCHEMA }))
+  // Card swarm-lead-worktree-missing: the lead's own worktree is gone by now (rehearsal swarm-2026-10-09T15-20-40-679Z), so the merge gets a fresh one.
+  const merged = await launch(leadMergePrompt(task, lead, finished, baseBranch, workers), agentOpts('lead', null, { label: `lead-merge:${task.id}`, phase: 'Implement', isolation: 'worktree', agentType: 'doug-flow:lead', schema: IMPLEMENT_SCHEMA }))
   if (!merged) return blocked('lead merge returned nothing (spawn failure or no structured output)', { worktreePath: lead.worktreePath, branch: lead.branch })
   return { ...merged, branch: merged.branch || lead.branch, worktreePath: merged.worktreePath || lead.worktreePath, swarmStages: stages, workers, splitReason: lead.splitReason, rebrief, checkFailed: workers.filter(w => w.checkFailed).map(w => w.id) }
 }

package/node_modules/@dougharness/gates/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "doug-gates",
   "displayName": "Doug Gates",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Deterministic guardrails for Claude Code: protected paths, bash guard, secret scan on edits and commands, format on edit, edit-loop detection, a verification gate on Stop and on SubagentStop, a snapshot of the plan and session into the anchor before compaction and re-anchoring after it, and a run trace of subagents and tool calls. Configured by .doug/config.json.",
   "author": {
     "name": "Doug contributors"

package/node_modules/@dougharness/gates/lib/anchor.mjs

@@ -23,6 +23,28 @@ export function readPlanSummary(dir) {
   }
 }
 
+// Every active (enforced, not landed) per-card plan under .doug/plans/, as readPlanSummary shapes them.
+export function readPlanSummaries(dir) {
+  const out = [];
+  try {
+    const d = join(dir, ".doug/plans");
+    if (!existsSync(d)) return out;
+    for (const name of readdirSync(d).filter((f) => f.endsWith(".json")).sort()) {
+      try {
+        const p = JSON.parse(readFileSync(join(d, name), "utf8"));
+        if (!p || typeof p !== "object" || !Array.isArray(p.tasks) || p.landed) continue;
+        if (p.status !== "approved" && p.status !== "done") continue;
+        out.push({ title: p.title || "(untitled)", status: p.status, card: typeof p.card === "string" ? p.card : null, tasks: p.tasks.map((t) => ({ id: t.id, files: Array.isArray(t.files) ? t.files : [] })) });
+      } catch {
+        // an unreadable per-card plan is skipped
+      }
+    }
+  } catch {
+    return out;
+  }
+  return out;
+}
+
 // Short HEAD sha and current branch, tolerant of a non-repo or a git failure (moved from stop-gate.mjs; used by
 // both the Stop gate's own handoff and the PreCompact snapshot).
 export function gitHead(dir) {
@@ -55,7 +77,7 @@ export function readDecisions(dir) {
 // plan/decisions/edited-files lines (card precompact-keeps-handoff, review MAJOR): those grow unbounded with a
 // session's edited-file count, and SessionStart's re-injection caps the whole anchor at 4000 characters, so a few
 // short handoff lines must be near the top to survive that cap on a long session.
-export function snapshotSection({ plan, decisions, state, now, handoff }) {
+export function snapshotSection({ plan, plans, decisions, state, now, handoff }) {
   const lines = [`## Compaction snapshot (doug, ${now.toISOString()})`];
   if (handoff) {
     lines.push("");
@@ -70,9 +92,12 @@ export function snapshotSection({ plan, decisions, state, now, handoff }) {
     if (typeof handoff.contextPct === "number") lines.push(`Context: ${handoff.contextPct}%`);
   }
   lines.push("");
-  if (plan) {
-    lines.push(`Plan: ${plan.title} [${plan.status}]${plan.card ? ` (card ${plan.card})` : ""}`);
-    for (const t of plan.tasks) lines.push(`- ${t.id} owns ${t.files.length ? t.files.join(", ") : "(no files)"}`);
+  const shown = plan ? [plan] : plans || [];
+  if (shown.length) {
+    for (const pl of shown) {
+      lines.push(`Plan: ${pl.title} [${pl.status}]${pl.card ? ` (card ${pl.card})` : ""}`);
+      for (const t of pl.tasks) lines.push(`- ${t.id} owns ${t.files.length ? t.files.join(", ") : "(no files)"}`);
+    }
   } else lines.push("Plan: none in .doug/plan.json");
   lines.push("");
   lines.push(decisions.length ? `Decisions (docs/decisions): ${decisions.join(", ")}` : "Decisions: none under docs/decisions");

package/node_modules/@dougharness/gates/lib/bash-rules.mjs

@@ -13,8 +13,8 @@ const PM_INSTALL_VERBS = {
 // "|"/"&"/"|&"/newline, and the body of every unquoted-or-double-quoted "$(...)" or backtick substitution
 // really executes, so its pieces are split out too, recursively (research Q1.5; design decided by the lead,
 // point 3). Falls back to today's quote-blind split - checking MORE than a real shell would, never less - when
-// the scanner hits an unterminated quote or substitution (a heredoc body looks the same to it, and heredocs are
-// out of scope - point 4) or throws for any other reason (a hook reader must never throw - CLAUDE.md Gotchas).
+// the scanner hits an unterminated quote or substitution (a heredoc body looks the same to it; only the
+// package-manager rule strips heredoc bodies - stripHeredocBodies, card bash-rules-heredoc-body) or throws for any other reason (a hook reader must never throw - CLAUDE.md Gotchas).
 // A bare "&" (backgrounds the command before it, redirection forms excepted) and bash's "|&" (a pipe connector,
 // treated the same as a bare "|") joined this set in review round 5 (third review) - see scanTop's comment.
 const ALL_SEPS = new Set(["&&", "||", ";", "|", "&", "|&", "\n"]);
@@ -155,8 +155,8 @@ function words(cmd) {
 // itself sits inside (a stack, not a boolean: scanParenBody below starts its own body scan fresh in the "top"
 // state). "$((...))" is read as a substitution too (its body is "(...)" verbatim) - over-checking is fine.
 //
-// Known limits, stated as limits, not bugs: a word-initial "#" comment and a heredoc body are not recognised
-// (over-report only, never under-report - research Q1.7); zsh's RC_QUOTES, bash 5.x, and dash's lack of
+// Known limits, stated as limits, not bugs: a word-initial "#" comment and a heredoc body are not recognised by this scanner
+// (the package-manager rule alone strips heredoc bodies first - stripHeredocBodies; over-report only, never under-report - research Q1.7); zsh's RC_QUOTES, bash 5.x, and dash's lack of
 // $'...' are unverified or divergent, and the bash/zsh reading is the one this scanner takes; a "(...)" subshell
 // or "{ ...; }" group is not unwrapped (unchanged from today).
 //
@@ -726,8 +726,8 @@ function skipPrefixOptions(w, i, argFlags, onArgFlag) {
 // exactly as before. For the separate-token form the value is already its own token, so this returns { next }
 // pointing at it and lets matchesShellWords's loop continue from there. For an attached form (whose value can't
 // be pulled back out as its own token) there is no token to point { next } at, so this returns { splice: value,
-// next } instead: the caller replaces everything up to `next` with the single token `value` and resumes its own
-// loop at index 0 - a rebuild, not a recursive call, so nested attached values (env -Senv -Senv ... sh) cost no
+// next } instead: the caller overwrites the attached token's slot (next - 1) with the single token `value` and resumes its own
+// loop at that slot - a linear overwrite, not a recursive call, so nested attached values (env -Senv -Senv ... sh) cost no
 // call-stack depth no matter how many there are. Otherwise (the value is missing, empty, or itself option-
 // shaped) it isn't the command, so env keeps parsing options from there: for the separate-token form the walk
 // re-examines that same value token as the next option (advancing by 1, not 2, past just the flag), and for an
@@ -892,10 +892,13 @@ function redirWordSpan(tok) {
 // Walks a stage's already-split words from index i, resolving prefixes (env assignments, sudo, env, nice,
 // time, nohup, exec, command, busybox) until it lands on the candidate verb. Split out of matchesShellStage so
 // scanEnvOptions can hand an -S/--split-string value back into this same walk when that value qualifies as
-// env's command. That handoff is a rebuild of `w`, not a recursive call (see the "splice" case below): every
-// handoff replaces one or more consumed tokens with the single value token, so `w` strictly shrinks by at least
-// one token each time, and the loop below runs no deeper than one stack frame no matter how many wrappers are
-// nested (env -Senv -Senv ... sh).
+// env's command. That handoff is an in-place overwrite of one slot of a single copy of `w`, not a recursive call (see the "splice" case below): every
+// handoff replaces one or more consumed tokens with the single value token, so the walk's unread tail strictly
+// shrinks by at least one token each time, and the loop below runs no deeper than one stack frame no matter how
+// many wrappers are nested (env -Senv -Senv ... sh). The handoff is linear (card bash-rules-env-splice-quadratic):
+// the value overwrites the attached token's slot in a single copy of `w` and the walk resumes there, instead of
+// rebuilding the array per handoff (quadratic: 25 s at 80000 nestings). No token cap is applied: a cap would deny
+// commands that are allowed today, and the linear walk removes the timeout risk that a cap would guard.
 // Card bash-rules-prefixed-commands: also shared with commandForms, which needs the resolved word array and
 // verb index (not just a shell/not-shell verdict), so the walk itself no longer decides an outcome - it returns
 // { w, i } once it lands on a candidate verb (i may be w.length when nothing followed the prefixes), or
@@ -920,7 +923,7 @@ function redirWordSpan(tok) {
 //     still reads the RAW token, unchanged - a quoted FLAG is out of this card's scope, and dequoting it too
 //     would risk changing which flag a cluster or an attached form is read as, for no fixture that needs it.
 //     The returned `{w, i}` itself is unaffected by this: `w` is still the array the caller passed in (or
-//     resolveVerb's own env-splice rebuild, unrelated to this round), and `i` is just an index into it - the
+//     resolveVerb's own single copy after an env splice, unrelated to this round), and `i` is just an index into it - the
 //     caller (isShellVerb by way of commandForms/matchesShellWords) dequotes `w[i]` itself before comparing it
 //     against a shell name, the same way this loop now does for a prefix name.
 //
@@ -936,6 +939,7 @@ function redirWordSpan(tok) {
 // ...) reads the prefix/verb token's text again - everything after it operates on the RAW words that follow,
 // unaffected by which reading recognised the name in front of them.
 function resolveVerb(w, i) {
+  const original = w;
   while (i < w.length) {
     const tok = w[i];
     const span = redirWordSpan(tok);
@@ -970,11 +974,14 @@ function resolveVerb(w, i) {
     if (isBase("env")) {
       const result = scanEnvOptions(w, i + 1);
       if ("splice" in result) {
-        // An attached -S/--split-string value qualified as env's command: rebuild the word array with that
-        // value as the new first word, followed by whatever came after it, and resume this same loop at 0 -
-        // no recursive call, so this is safe no matter how many attached values are nested.
-        w = [result.splice, ...w.slice(result.next)];
-        i = 0;
+        // An attached -S/--split-string value qualified as env's command: the value becomes the walk's next word.
+        // It overwrites the slot of the attached token just before result.next (copying w once, on the first
+        // splice, so the caller's array is never mutated) and the walk resumes AT that slot - the same words,
+        // from the same start, the old rebuilt array [value, ...rest] held at its index 0. Each handoff consumes at
+        // least one token and costs O(1), so n nested values cost O(n), and no recursion either.
+        if (w === original) w = original.slice();
+        i = result.next - 1;
+        w[i] = result.splice;
         continue;
       }
       i = result.next; // separate-token -S/--split-string value, or no qualifying value: continue the walk
@@ -1053,7 +1060,7 @@ function pipeStages(group) {
 // group's stages at "|" or "|&" (pipeStages above) - and, design point 5, recursion into every substitution
 // body's own groups too, so a curl|sh chain hidden inside a "$(...)" or backtick is still caught. Because
 // scanTop finds a substitution wherever it sits - inside an ordinary quoted argument or inside what looks like
-// inert text such as a heredoc body (heredocs carry no state of their own here, a known limit) - a "$(... curl
+// inert text such as a heredoc body (this check keeps no heredoc state, a known limit) - a "$(... curl
 // ... | sh)" written inside either is still denied even where a real shell would just treat it as literal
 // text: an over-denial on the safe side, not a miss. Falls back to the old quote-blind group split (unchanged -
 // review round 5 did not extend this fallback regex to "&"/"|&", see the coder's report) on an unterminated
@@ -1335,8 +1342,8 @@ function dequoteScript(word, reading = "bash") {
 // behind a resolvable prefix (sudo, an env assignment, env, nice, time, nohup, exec, command, busybox) or a
 // shell's -c string. Always includes cmd itself. When resolveVerb's walk consumed or rebuilt anything - i > 0
 // (an ordinary prefix was skipped) or the returned word array isn't the one passed in (an attached env
-// -S/--split-string value spliced in a new array and reset i to 0 on it, so i > 0 alone missed a denied command
-// sitting right behind it, e.g. env -Sgit reset --hard) - also includes the resolved word array from the verb
+// -S/--split-string value was spliced into a single copy of the array, overwriting the attached token's slot;
+// the walk resumes there, so i stays >= 1 after a splice) - also includes the resolved word array from the verb
 // onward. When that verb's basename is a shell, findScriptCandidates (above) locates 0, 1, or 2 candidate -c
 // script words; each candidate is dequoted (dequoteScript) - the ONLY word this function dequotes - twice, once
 // per shell reading (review round 3: bash and zsh decode an unrecognised ANSI-C escape differently, see
@@ -1478,6 +1485,184 @@ export function commandForms(cmd, depth = 0) {
   }
 }
 
+// Card bash-rules-heredoc-body: the body of a heredoc (<<WORD, <<'WORD', <<"WORD", <<-WORD, up to the terminator
+// line) is data fed to a command's stdin, not commands, so the package-manager rule must not match prose inside
+// it (a research note quoting the npm CLI). stripHeredocBodies returns the command with those bodies removed;
+// evaluateBash feeds it to the package-manager rule ONLY - every other rule still sees the original text
+// (checks more, never less). Its own small quote-aware walk (not scanTop: a body with an apostrophe would
+// leave scanTop in an unterminated quote and send it to the quote-blind fallback). A body is kept, i.e. still
+// checked, when: its terminator line never appears (unterminated); ANY pipeline stage anywhere in the whole
+// command is a shell or source/"." (a shell reading the heredoc runs it as a script), or any group ends in a
+// trailing "|" (the receiving stage is on a later line): then nothing is stripped; or the delimiter is unquoted
+// and the body holds "$(" or a backtick (an unquoted heredoc expands substitutions, which run).
+// Known limits (accepted, not caught): a heredoc written to a file later run (cat > s.sh <<EOF ... bash s.sh),
+// xargs ... sh -c, tee >(sh), while read l; do $l; done <<EOF, ssh/docker exec (remote). "<<<" is a
+// here-string, not a heredoc; an operator inside a quote, a substitution, or a word-initial "#" comment is not
+// one either. Never throws: any error returns the command unchanged (today's behaviour).
+function heredocReadsAsScript(stage) {
+  // Compared on the raw stage and on the stage with quotes and backslashes removed ("sh", s\h): conservative.
+  for (const text of [stage, stage.replace(/["'\\]/g, "")]) {
+    if (matchesShellStage(text)) return true;
+    const r = resolveVerb(words(text), 0);
+    const verb = r.w[r.i];
+    if (verb === "source" || verb === ".") return true;
+  }
+  return false;
+}
+
+// Whole-command rule (round 2): ANY pipeline stage anywhere in the command that reads as a shell script consumer,
+// or any group ending in a trailing "|", keeps every body. A per-operator or per-group relation misses a heredoc
+// inside a compound (if/for/while/case/subshell/brace group) whose closing keyword is piped to a shell.
+function commandHasShellConsumer(str) {
+  const cut = cutOnSeparators(str, GROUP_SEPS);
+  const groups = cut ? cut.pieces : str.split(/\s*(?:&&|\|\||;)\s*|\n/).map((s) => s.trim()).filter(Boolean);
+  for (const group of groups) {
+    if (/\|&?\s*$/.test(group)) return true; // the receiving stage is on a later line: unknown, so conservative
+    if (pipeStages(group).some((st) => heredocReadsAsScript(st))) return true;
+  }
+  return false;
+}
+
+export function stripHeredocBodies(command) {
+  const str = String(command);
+  try {
+    if (!str.includes("<<")) return str;
+    if (commandHasShellConsumer(str)) return str;
+    const removals = [];
+    let pending = [];
+    let state = "top";
+    let i = 0;
+    while (i < str.length) {
+      const c = str[i];
+      if (state === "squote") { if (c === "'") state = "top"; i += 1; continue; }
+      if (state === "dquote") {
+        if (c === "\\" && isDquoteEscapable(str[i + 1])) { i += 2; continue; }
+        if (c === '"') { state = "top"; i += 1; continue; }
+        if (c === "$" && str[i + 1] === "(") {
+          const close = scanParenBody(str, i + 1);
+          if (close < 0) return str;
+          i = close + 1;
+          continue;
+        }
+        if (c === "`") {
+          const close = scanBacktickBody(str, i);
+          if (close < 0) return str;
+          i = close + 1;
+          continue;
+        }
+        i += 1;
+        continue;
+      }
+      if (state === "ansic") {
+        if (c === "\\") { i += 2; continue; }
+        if (c === "'") state = "top";
+        i += 1;
+        continue;
+      }
+      // top
+      if (c === "\\") { i += 2; continue; }
+      if (c === "'") { state = "squote"; i += 1; continue; }
+      if (c === '"') { state = "dquote"; i += 1; continue; }
+      if (c === "$" && str[i + 1] === "'") { state = "ansic"; i += 2; continue; }
+      if (c === "$" && str[i + 1] === '"') { state = "dquote"; i += 2; continue; }
+      if (c === "$" && str[i + 1] === "(") {
+        const close = scanParenBody(str, i + 1);
+        if (close < 0) return str;
+        i = close + 1;
+        continue;
+      }
+      if (c === "`") {
+        const close = scanBacktickBody(str, i);
+        if (close < 0) return str;
+        i = close + 1;
+        continue;
+      }
+      if (c === "#" && (i === 0 || /[\s;&|()]/.test(str[i - 1]))) {
+        while (i < str.length && str[i] !== "\n") i += 1;
+        continue;
+      }
+      if (c === "<" && str[i + 1] === "<") {
+        if (str[i + 2] === "<") { i += 3; continue; } // here-string
+        let j = i + 2;
+        const dash = str[j] === "-";
+        if (dash) j += 1;
+        while (str[j] === " " || str[j] === "\t") j += 1;
+        let word = "";
+        let quoted = false;
+        let dollarQuoted = false;
+        while (j < str.length && !/[\s;&|<>()]/.test(str[j])) {
+          const ch = str[j];
+          if (ch === "\\") { quoted = true; word += str[j + 1] ?? ""; j += 2; continue; }
+          if (ch === "$" && (str[j + 1] === "'" || str[j + 1] === '"')) { dollarQuoted = true; j += 1; continue; }
+          if (ch === "'" || ch === '"') {
+            const close = str.indexOf(ch, j + 1);
+            if (close < 0) return str;
+            quoted = true;
+            word += str.slice(j + 1, close);
+            j = close + 1;
+            continue;
+          }
+          word += ch;
+          j += 1;
+        }
+        if (word) pending.push({ word, dash, quoted, shellFed: dollarQuoted || word[0] === "$" });
+        i = Math.max(j, i + 2);
+        continue;
+      }
+      const sep =
+        (c === "&" && str[i + 1] === "&") || (c === "|" && str[i + 1] === "|") ? 2
+          : c === ";" ? 1
+            : c === "&" && str[i + 1] !== ">" && str[i - 1] !== ">" && str[i - 1] !== "<" && str[i - 1] !== "|" ? 1
+              : 0;
+      if (sep) {
+        i += sep;
+        continue;
+      }
+      if (c === "\n") {
+        const ops = pending;
+        pending = [];
+        let pos = i + 1;
+        let lastEnd = -1;
+        for (const op of ops) {
+          const bodyStart = pos;
+          let found = -1;
+          while (pos <= str.length) {
+            const nl = str.indexOf("\n", pos);
+            const lineEnd = nl < 0 ? str.length : nl;
+            const line = str.slice(pos, lineEnd);
+            if ((op.dash ? line.replace(/^\t+/, "") : line) === op.word) { found = lineEnd; break; }
+            if (lineEnd >= str.length) break;
+            pos = lineEnd + 1;
+          }
+          if (found < 0) return removals.length ? applyRemovals(str, removals) : str; // unterminated: stop here
+          const body = str.slice(bodyStart, found);
+          const expands = !op.quoted && /\$\(|`/.test(body);
+          if (!op.shellFed && !expands) removals.push([bodyStart, found]);
+          lastEnd = found;
+          pos = found + 1;
+        }
+        if (lastEnd >= 0) { i = lastEnd; continue; }
+        i += 1;
+        continue;
+      }
+      i += 1;
+    }
+    return removals.length ? applyRemovals(str, removals) : str;
+  } catch {
+    return str;
+  }
+}
+
+function applyRemovals(str, removals) {
+  let out = "";
+  let at = 0;
+  for (const [a, b] of removals) {
+    out += str.slice(at, a);
+    at = b;
+  }
+  return out + str.slice(at);
+}
+
 export function checkPackageManager(cmd, expected) {
   if (!expected) return null;
   const m = /^(npm|pnpm|yarn|bun)\s*(.*)$/.exec(cmd);
@@ -1499,6 +1684,8 @@ export function evaluateBash(command, { config, currentBranch }) {
     const pipeReason = checkPipeToShell(command);
     if (pipeReason) reasons.push(pipeReason);
   }
+  const pmCommand = config.bash.packageManagerGuard ? stripHeredocBodies(command) : command;
+  const pmSeparate = pmCommand !== command;
   for (const cmd of splitCommands(command)) {
     // Card bash-rules-prefixed-commands: run the five per-command checks (each anchored on the start of the
     // string it's given) on every form commandForms resolves for this split command - cmd itself, a prefix
@@ -1514,9 +1701,19 @@ export function evaluateBash(command, { config, currentBranch }) {
         checks.push(checkResetHardOnProtected(form, config.bash.denyForcePushTo, currentBranch));
       }
       if (config.bash.denyDestructive) checks.push(checkDestructive(form));
-      if (config.bash.packageManagerGuard) checks.push(checkPackageManager(form, config.packageManager));
+      if (config.bash.packageManagerGuard && !pmSeparate) checks.push(checkPackageManager(form, config.packageManager));
       for (const r of checks) if (r && !reasons.includes(r)) reasons.push(r);
     }
   }
+  // Card bash-rules-heredoc-body: with a data heredoc body present, the package-manager rule reads the command
+  // with those bodies stripped (stripHeredocBodies); the other rules above already ran on the original text.
+  if (pmSeparate) {
+    for (const cmd of splitCommands(pmCommand)) {
+      for (const form of commandForms(cmd)) {
+        const r = checkPackageManager(form, config.packageManager);
+        if (r && !reasons.includes(r)) reasons.push(r);
+      }
+    }
+  }
   return reasons;
 }