@dev-loops/core 1.0.1 → 1.0.2-slim.0

package/src/claude/hook-decisions.mjs

@@ -1,5 +1,5 @@
 /**
- * Pure decision logic for the Claude Code dev-loop hooks (#773).
+ * Pure decision logic for the Claude Code dev-loop hooks.
  *
  * The hook *scripts* are thin: they read the PreToolUse/PostToolUse stdin payload, gather facts
  * (git tracked/ignored status, gate-evidence result), and call these pure deciders. Keeping the
@@ -46,7 +46,7 @@ const ALLOW = Object.freeze({ decision: "allow" });
 
 /**
  * Whether the command string also invokes an evidence-writing script (findings-log ledger or
- * checkpoint-verdict upsert). Used only to enrich the merge-block message (#1172) — a compound
+ * checkpoint-verdict upsert). Used only to enrich the merge-block message — a compound
  * command combining an evidence write with `gh pr merge` is blocked pre-execution, so the write
  * never runs; this substring check has no false-negative cost (worst case: the plain message).
  */
@@ -64,22 +64,15 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
 /**
  * Decide whether a PreToolUse Bash command must be blocked by a dev-loop gate boundary.
  *
- * Three gated commands on the target repo:
+ * Gated commands on the target repo (each rationale sits inline at its check):
  *   - `gh pr create` — blocked outright; PR creation must flow through the canonical wrapper
- *     (`scripts/github/create-pr.mjs` / `dev-loops pr create`), which always drafts and
- *     self-assigns. Closes the hole where raw `gh pr create` opens a ready PR, bypassing draft-first.
- *   - `gh pr ready` — blocked without clean draft_gate evidence (`pre-pr-ready-gate`).
- *   - `gh pr merge` — blocked without the full pre-merge gate evidence (`detect-checkpoint-evidence`:
- *     clean current-head draft_gate + pre_approval_gate). The loop runs this check before merging;
- *     gating it here closes the hole where a hand-run `gh pr merge` skips the pre-approval gate
- *     entirely. Everything else passes through.
- *   - raw `gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment` — blocked ONLY when the call
- *     originates from a SUBAGENT context (`agentType` is a non-null string) and targets the repo.
- *     Sanctioned external writes flow through node wrappers (gate-verdict comments via
- *     `upsert-checkpoint-verdict.mjs`, review replies via `reply-resolve*.mjs`, board sync,
- *     `comment-issue.mjs`), whose Bash command string is `node scripts/…` and never matches these
- *     raw-`gh` matchers. The MAIN AGENT / operator (agentType null) retains direct `gh issue
- *     create` — that path is authorized (#1051).
+ *     (`scripts/github/create-pr.mjs` / `dev-loops pr create`), which always drafts and self-assigns.
+ *   - `gh pr ready` — blocked without clean draft_gate evidence.
+ *   - `gh pr merge` — blocked without full pre-merge gate evidence (clean current-head draft_gate +
+ *     pre_approval_gate).
+ *   - raw `gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment` — blocked ONLY
+ *     from a SUBAGENT context (`agentType` non-null) on the target repo. Sanctioned external writes
+ *     flow through node wrappers; the MAIN AGENT / operator (agentType null) retains direct access.
  *
  * The hook computes `gatePassed`/`gateError` from the gate script appropriate to the command kind.
  *
@@ -101,10 +94,10 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     return ALLOW;
   }
   // Normalize (trim + case-fold) so a divergent slug (surrounding whitespace, casing) does not
-  // silently fail OPEN and disable every guard that depends on inTargetRepo (#1622).
+  // silently fail OPEN and disable every guard that depends on inTargetRepo.
   const inTargetRepo = (repoSlug ?? "").trim().toLowerCase() === TARGET_REPO_SLUG.trim().toLowerCase();
 
-  // OPS-NO-INLINE-INTERPRETER (#1622): inline interpreters (`node -e`/`--eval`/`-p`, `python3 -c`,
+  // OPS-NO-INLINE-INTERPRETER: inline interpreters (`node -e`/`--eval`/`-p`, `python3 -c`,
   // heredocs fed to node/python) are barred actor-independently on the target repo — the rule bars
   // "Coordinator and agent flows"; sanctioned output parsing uses `--jq`/`--silent`, never an
   // inline interpreter.
@@ -118,10 +111,10 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     };
   }
 
-  // SUBISSUE-NO-ADHOC-BYPASS (#1622): ad-hoc `gh api` writes to the target repo's sub-issue endpoints.
+  // SUBISSUE-NO-ADHOC-BYPASS: ad-hoc `gh api` writes to the target repo's sub-issue endpoints.
   // Actor-independent (no reserved direct path). Gated on the target repo: the absolute slug-embedded
   // form identifies the target repo; the bare relative form (`gh api issues/5/sub_issues`) resolves
-  // against the cwd repo, so it is in scope only when running in the target repo (mirrors the #1047
+  // against the cwd repo, so it is in scope only when running in the target repo (mirrors the
   // explicit-`--repo`/cwd-target posture).
   if (inTargetRepo && commandContainsSubIssueAdHocBypass(command)) {
     return {
@@ -132,7 +125,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     };
   }
 
-  // COPILOT-FOLLOWUP-REPLY-RESOLVE-HELPER (#1622): ad-hoc thread-resolution writes — raw `gh api` POST
+  // COPILOT-FOLLOWUP-REPLY-RESOLVE-HELPER: ad-hoc thread-resolution writes — raw `gh api` POST
   // to pulls/<n>/comments/<m>/replies, or a `gh api graphql` resolveReviewThread mutation (the Rest
   // path names the target repo; the graphql form has no path-host repo, so it is scoped to the cwd
   // repo). Actor-independent: reply through reply-resolve-review-thread(s).mjs.
@@ -146,7 +139,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     };
   }
 
-  // COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY (#1622): ad-hoc Copilot review requests — raw `gh api` writes
+  // COPILOT-FOLLOWUP-REQUEST-HELPER-ONLY: ad-hoc Copilot review requests — raw `gh api` writes
   // to pulls/<n>/requested_reviewers, or a bare `/copilot` / `/copilot re-review` comment summon on the
   // target repo. Actor-independent: request Copilot via scripts/github/request-copilot-review.mjs.
   if (inTargetRepo && (commandContainsCopilotRequestBypass(command) || commandContainsCopilotSummonComment(command))) {
@@ -174,7 +167,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   }
   // Subagent-scoped external-write guard: block ad-hoc `gh issue create`/`gh issue comment`/
   // `gh issue edit`/`gh pr comment` on the target repo from a subagent, so external writes flow through the
-  // sanctioned node wrappers. The main-agent/operator path (agentType null) is unaffected (#1051).
+  // sanctioned node wrappers. The main-agent/operator path (agentType null) is unaffected.
   if (typeof agentType === "string" && commandContainsRawExternalWrite(command)) {
     const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
     // Scope PER segment, mirroring the `gh pr create` block: in scope when no explicit --repo and
@@ -205,7 +198,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   const isMerge = commandContainsGhPrMerge(command);
   const isCreate = commandContainsGhPrCreate(command);
 
-  // STOP-HUMAN-MERGE-001 (#1622): when the repo resolves `autonomy.humanMergeOnly`, `gh pr merge` is
+  // STOP-HUMAN-MERGE-001: when the repo resolves `autonomy.humanMergeOnly`, `gh pr merge` is
   // refused actor-independently — the main agent is the actor that performs GitHub writes, so only an
   // actor-independent deny enforces the human-merge invariant (an agent-scoped deny would enforce
   // nothing on the main-agent write path).
@@ -220,7 +213,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
   }
 
   if (!isReady && !isMerge && !isCreate) {
-    // COPILOT-FOLLOWUP-WAIT-TOOLS (#1622): banned detached/polling wait wrappers. Subagent-only — the
+    // COPILOT-FOLLOWUP-WAIT-TOOLS: banned detached/polling wait wrappers. Subagent-only — the
     // rule is classified `agent` (behavioral guidance for the dev-loop driving agent); the main
     // agent/operator retains manual wait tooling. The main agent's own sanctioned wait path is still
     // the deterministic tools.
@@ -244,7 +237,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
     // Evaluate scope PER create segment, not just the first: a create is in scope when it
     // explicitly targets the repo, or (with no explicit --repo) the cwd is the repo. An explicit
-    // `--repo <target>` is denied regardless of cwd (#1047). DENY if ANY create segment is in
+    // `--repo <target>` is denied regardless of cwd. DENY if ANY create segment is in
     // scope — otherwise a leading out-of-scope create (`gh pr create --repo other/repo`) would
     // short-circuit and shield a later in-scope raw create (`&& gh pr create --fill`).
     const anyCreateInScope = extractRepoFlagsFromGhPrCreateSegments(command).some((seg) =>
@@ -307,7 +300,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
       // This hook evaluates PreToolUse — BEFORE the Bash tool call runs. A compound command that
       // writes gate evidence (findings-log ledger, checkpoint verdict) and merges in the same call
       // is blocked here with the write never having executed, which looks like the evidence
-      // "vanished" (#1172). Hint the split when the command carries an evidence-writing invocation
+      // "vanished". Hint the split when the command carries an evidence-writing invocation
       // alongside the merge, so the failure is self-explaining instead of looking like data loss.
       const alsoWritesEvidence = commandContainsEvidenceWrite(command);
       return {
@@ -369,9 +362,102 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
   };
 }
 
+/**
+ * Env var that authorizes a deliberate main-checkout mutation while a worktree
+ * cycle is active. Reuses the existing default-branch-guard override
+ * (`DEVLOOPS_ALLOW_MAIN`, GUARD_OVERRIDE_ENV) — both mean "I intend to operate on
+ * the primary checkout on purpose" — so the operator surface stays one flag.
+ */
+export const WORKTREE_CHECKOUT_GUARD_OVERRIDE_ENV = "DEVLOOPS_ALLOW_MAIN";
+
+/**
+ * Decide whether a PreToolUse Write/Edit is a WRONG-CHECKOUT mutation: the call
+ * context is operating inside a linked worktree (the active cycle worktree) but
+ * the target resolves to a TRACKED file in the MAIN checkout instead of that
+ * worktree.
+ *
+ * After `ensure-worktree.mjs` establishes an isolated worktree for a cycle, an
+ * absolute-path `Edit`/`Write` that names the main-checkout copy of a source
+ * file lands the change on the wrong checkout — silently, until a `git status`
+ * in the worktree turns up empty (observed in practice: six edits hit main
+ * before a self-caught restore). This guard catches that before it reaches a commit.
+ *
+ * The "active worktree" is anchored to the CALL CONTEXT's cwd, not to a durable
+ * marker: this repo accumulates many stale `tmp/worktrees/` worktrees, so "a
+ * worktree exists" cannot mean "a cycle is active". The worktree that CONTAINS
+ * cwd is the one this context is driving; a write escaping it into main is the
+ * wrong-checkout mistake.
+ *
+ * The hook resolves the facts (via the shared `worktree-guard.mjs` primitives)
+ * and passes booleans so this decider stays pure and unit-testable:
+ * - `activeWorktreeRoot`: the listed worktree root containing cwd, or null when
+ *   cwd is not inside any worktree (no active cycle context — AC3).
+ * - `isTargetUnderActiveWorktree`: the target resolves inside that worktree (a
+ *   legitimate in-worktree edit — AC2).
+ * - `isMainCheckoutTracked`: the target resolves under the main checkout AND is
+ *   a tracked (non-gitignored) file. The hook sets this true when the status is
+ *   UNRESOLVABLE (e.g. `git check-ignore` errored) so an ambiguous context fails
+ *   safe rather than silently allowing a wrong-checkout write (AC4).
+ * - `allowMainCheckout`: the deliberate-override signal (`DEVLOOPS_ALLOW_MAIN=1`)
+ *   for an intended main-checkout edit (AC3).
+ *
+ * @param {Object} params
+ * @param {string} params.filePath - Target file path (as supplied to the tool).
+ * @param {string|null} [params.activeWorktreeRoot] - Listed worktree root containing cwd, or null.
+ * @param {boolean} [params.isTargetUnderActiveWorktree] - Target is inside the active worktree.
+ * @param {boolean} [params.isMainCheckoutTracked] - Target is a tracked main-checkout file (or unresolvable).
+ * @param {boolean} [params.allowMainCheckout] - Deliberate override (DEVLOOPS_ALLOW_MAIN=1).
+ * @param {string|null} [params.suggestedWorktreePath] - The worktree-local path the write should target.
+ * @returns {HookDecision}
+ */
+export function decideWorktreeCheckoutGuard({
+  filePath,
+  activeWorktreeRoot = null,
+  isTargetUnderActiveWorktree = false,
+  isMainCheckoutTracked = false,
+  allowMainCheckout = false,
+  suggestedWorktreePath = null,
+}) {
+  // No active worktree context — this is the main checkout / orchestrator / a
+  // consumer repo's own interactive dev. A main-checkout edit is intended here
+  // (AC3). Also the only path that runs for repos never using dev-loop worktrees.
+  if (!activeWorktreeRoot) {
+    return ALLOW;
+  }
+  // Deliberate, operator-authorized main-checkout write during an active cycle (AC3).
+  if (allowMainCheckout) {
+    return ALLOW;
+  }
+  // Legitimate in-worktree edit — no false positive (AC2).
+  if (isTargetUnderActiveWorktree) {
+    return ALLOW;
+  }
+  // Outside the active worktree AND not a tracked main-checkout file: a scratch
+  // path (/tmp), a gitignored path, another worktree's file, or outside the repo
+  // entirely — none is the wrong-checkout mistake this guard exists to catch.
+  if (!isMainCheckoutTracked) {
+    return ALLOW;
+  }
+  // A worktree cycle is active and the target is a tracked main-checkout file
+  // (or an unresolvable/ambiguous context that fails safe — AC4). This is a
+  // wrong-checkout mutation (AC1).
+  const fix = suggestedWorktreePath
+    ? ` Edit the worktree copy instead: "${suggestedWorktreePath}".`
+    : "";
+  return {
+    decision: "deny",
+    reason:
+      `WORKTREE-WRONG-CHECKOUT-GUARD: wrong-checkout mutation blocked — a worktree cycle is active ` +
+      `("${activeWorktreeRoot}") but this Write/Edit targets the MAIN checkout's non-gitignored file ` +
+      `"${filePath}".${fix} A file mutation that lands on the main checkout while a worktree is ` +
+      "active is silently lost from the branch. Set DEVLOOPS_ALLOW_MAIN=1 only for a deliberate " +
+      "main-checkout edit. See skills/docs/worktree-guidance.md.",
+  };
+}
+
 /**
  * Env var that exempts an interactive session awaiting commit authorization from the
- * SubagentStop uncommitted-work guard (#1619).
+ * SubagentStop uncommitted-work guard.
  *
  * An opt-in signal set by the operator or the interactive coordination path
  * (`DEVLOOPS_COMMIT_AUTH_PENDING=1`) when intentionally holding uncommitted work pending
@@ -384,34 +470,48 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
 export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
 
 /**
- * Env var that exempts an orchestrator-owned-commit dispatch from the SubagentStop
- * uncommitted-work guard (#1786).
+ * Subagent roles whose contract forbids committing to the repository.
  *
- * A "LOCAL EDITS ONLY: no commit" dispatch (e.g. the `developer`/`quality`/`docs` delegation
- * pattern in `skills/local-implementation/SKILL.md` "Delegation contract") tells the subagent to
- * make local edits and report changed files, leaving commit + push to the dispatching
- * orchestrator once it consolidates results. Without an exemption, that subagent's own
- * SubagentStop event still sees the dirty worktree it was told not to commit and deadlocks. The
- * dispatcher sets `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` for that dispatch to declare it owns the
- * commit — same opt-in `DEVLOOPS_*` signal shape as `DEVLOOPS_COMMIT_AUTH_PENDING`, but distinct:
- * this one exempts a non-interactive delegated dispatch whose commit responsibility sits with its
- * caller, not an interactive session awaiting operator authorization. Left unset, an ordinary
- * dispatch's commit-before-exit obligation stays enforced (fail closed by default).
+ * The `judge` and `review` agents are read-only over the repository: the judge writes only its
+ * own verdict artifact (under `tmp/`, gitignored) and the gate reviewer writes only its findings
+ * artifact (also under `tmp/`) — neither ever authors a tracked-file edit. So any uncommitted
+ * tracked change present in such a subagent's worktree is FOREIGN: it belongs to the orchestrator
+ * that dispatched it (a pending orchestrator edit that was in the shared worktree when the
+ * read-only pass ran), not to the read-only subagent. `LOCAL-COMMIT-BEFORE-EXIT` must not force
+ * one of these roles to author a commit of that foreign work — doing so violates the verdict-only
+ * contract (`agents/judge.agent.md`: "The only thing you write is your own verdict artifact").
+ * The data-loss protection is enforced against the OWNER of the edit (the orchestrator) on its own
+ * stop instead. This is intentionally scoped to read-only roles: editing roles (`developer`,
+ * `fixer`, `docs`, `quality`) and the orchestrator stay enforced.
  */
-export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT";
+export const READONLY_SUBAGENT_ROLES = Object.freeze(["judge", "review"]);
+
+/** Whether `agentType` (Claude `agent_type` from the SubagentStop payload) is a read-only role. */
+export function isReadOnlySubagentRole(agentType) {
+  return typeof agentType === "string" && READONLY_SUBAGENT_ROLES.includes(agentType);
+}
 
 /**
  * Decide whether a SubagentStop must be blocked because the subagent's worktree has
- * uncommitted changes (#1619).
+ * uncommitted changes.
  *
  * `scripts/loop/cleanup-worktree.mjs` runs `git worktree remove --force` after a merge, so
  * uncommitted changes in a worktree are destroyed with no warning. `LOCAL-COMMIT-BEFORE-EXIT`
  * existed only as prose. This decider makes it mechanical: refuse the subagent stop when the
  * cwd is under `tmp/worktrees/` and `git status --porcelain` is non-empty, unless the session
- * is an interactive one awaiting commit authorization, or the dispatch is an explicit
- * orchestrator-owned-commit exemption (#1786) (either exempt). A clean worktree, a cwd
+ * is an interactive one awaiting commit authorization (exempt). A clean worktree, a cwd
  * outside `tmp/worktrees/`, and a git-error/empty-porcelain case all allow the stop.
  *
+ * Editing roles (`developer`/`fixer`/`docs`/`quality`) stay fully enforced: an editing
+ * sub-delegate commits its own work before exit (`LOCAL-COMMIT-BEFORE-EXIT`), so a dirty exit is
+ * always a real defect, never a sanctioned "orchestrator owns the commit" split. The removed
+ * `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT` env-var exemption deadlocked such a role under a
+ * task-scoped no-commit instruction whenever the orchestrator could not set a per-dispatch env
+ * var (the Claude harness): the hook demanded a commit the session then denied, then re-blocked
+ * the exit. Disallowing the edit-here/commit-there split at the contract level makes the
+ * guard the enforcer and the deadlock structurally impossible while preserving data-loss
+ * protection. An orchestrator that wants one consolidated commit performs the edits itself.
+ *
  * Pure and side-effect free. The hook script gathers `cwd` and the `git status --porcelain`
  * output and calls this; the block decision is surfaced via exit code 2 + stderr JSON by the
  * hook (the SubagentStop contract differs from PreToolUse's `permissionDecision` form).
@@ -424,21 +524,38 @@ export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS
  * @param {boolean} [params.pendingCommitAuthorization] - True when the interactive session is
  *   awaiting commit authorization (exempt) — derived by the hook script from the
  *   `DEVLOOPS_COMMIT_AUTH_PENDING=1` opt-in env signal.
- * @param {boolean} [params.orchestratorOwnsCommit] - True when this dispatch is an explicit
- *   orchestrator-owned-commit exemption (exempt) — derived by the hook script from the
- *   `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` opt-in env signal.
+ * @param {string|null} [params.agentType] - Claude `agent_type` from the SubagentStop payload;
+ *   a read-only role (`judge`/`review`, per `READONLY_SUBAGENT_ROLES`) is exempt — its
+ *   contract forbids commits, so any dirty tracked edit in its worktree is foreign
+ *   (orchestrator-owned) and must not be pinned on it.
  * @returns {HookDecision}
  */
-export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, orchestratorOwnsCommit = false }) {
+export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, agentType = null }) {
   if (typeof cwd !== "string" || !isUnderWorktreePath(cwd)) {
     return ALLOW;
   }
-  if (pendingCommitAuthorization || orchestratorOwnsCommit) {
+  if (pendingCommitAuthorization) {
     return ALLOW;
   }
   if (typeof porcelain !== "string" || porcelain.trim() === "") {
     return ALLOW;
   }
+  // Read-only role exemption: the worktree is dirty, but a `judge`/`review` subagent's
+  // contract forbids commits, so this pending tracked edit is foreign — it belongs to the
+  // orchestrator that dispatched this pass. Do not force a verdict-only role to commit it; allow
+  // the stop with an advisory naming the orchestrator as the actor responsible for the edit. The
+  // data-loss guard still fires against the orchestrator on its own (editing) stop.
+  if (isReadOnlySubagentRole(agentType)) {
+    return {
+      decision: "allow",
+      advisory: true,
+      reason:
+        `LOCAL-COMMIT-BEFORE-EXIT exempt for read-only role "${agentType}": the worktree has ` +
+        "uncommitted changes, but a verdict-only role must not author a commit of work it did not " +
+        "create. This pending edit is foreign — the ORCHESTRATOR that dispatched this pass owns it " +
+        "and is responsible for committing it before its own stop.",
+    };
+  }
   const dirty = porcelain
     .split("\n")
     .map((l) => l.trim())