@dev-loops/core 1.0.0-rc.2 → 1.0.0-rc.4

package/src/loop/bash-command-classify.mjs

@@ -143,15 +143,16 @@ function shellSegments(command) {
 }
 
 /**
- * Leading prefix a `gh pr <verb>` segment may carry before the `gh` executable:
- * a run of `NAME=value` env assignments, optional `command`/`env`/`exec` wrapper
- * words, and an absolute/relative path on the gh binary (`/usr/bin/gh`).
+ * Leading prefix a command segment may carry before its real executable: a run of `NAME=value`
+ * env assignments, optional `command`/`env`/`exec` wrapper words, and an absolute/relative path on
+ * the binary (`/usr/bin/gh`, `/usr/bin/git`). Shared by every classifier in this file that must
+ * catch its verb behind these forms (`gh pr <verb>`, `git stash`, ...).
  *
  * Note: this is a pragmatic normalizer, not a full shell tokenizer. Subshell
  * `(gh pr create)`, `{ …; }` group, `-R=value` short-flag, and backslash-escaped
  * `\gh` forms are deliberately out of scope.
  */
-const GH_PR_VERB_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env|exec)\\s+)*(?:\\S*/)?";
+const SHELL_EXEC_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env|exec)\\s+)*(?:\\S*/)?";
 
 /**
  * Build the `gh <subcmd> <verb>` prefix matcher (subcmd = "pr" | "issue").
@@ -163,7 +164,36 @@ const GH_PR_VERB_PREFIX = "(?:[A-Za-z_][A-Za-z0-9_]*=\\S*\\s+)*(?:(?:command|env
  * match — their first token is `node`, not `gh`.
  */
 function ghSubcmdVerbRegex(subcmd, verb) {
-  return new RegExp(`^${GH_PR_VERB_PREFIX}gh\\s+${subcmd}\\s+${verb}(?:\\s|$)`, "i");
+  return new RegExp(`^${SHELL_EXEC_PREFIX}gh\\s+${subcmd}\\s+${verb}(?:\\s|$)`, "i");
+}
+
+/**
+ * A run of git global options that may appear between `git` and the subcommand: `-C <path>`,
+ * `-c <name>=<value>` (each consumes the following token as its value), `--git-dir=<path>`,
+ * `--work-tree=<path>`, or any other bare flag (`-x`, `--long-option`) that takes no value.
+ * Pragmatic normalizer, not a full git CLI parser.
+ */
+const GIT_GLOBAL_OPTION_RUN =
+  "(?:(?:-C|-c)\\s+\\S+\\s+|--(?:git-dir|work-tree)=\\S+\\s+|--?[A-Za-z][\\w-]*\\s+)*";
+
+/**
+ * Whether `command` contains a `git stash` invocation (any subcommand: bare, `push`, `pop`,
+ * `apply`, `save`, `list`, ...) in ANY shell segment — including behind the same env-assignment /
+ * `command`/`env`/`exec` wrapper / binary-path prefix (`GIT_DIR=.git git stash`, `command git
+ * stash`, `/usr/bin/git stash`) and git global options between `git` and `stash` (`git -C /tmp
+ * stash`, `git -c name=value stash pop`) that the sibling `gh` classifiers in this file already
+ * tolerate. Anchored per-segment, so `git stashed`, `git commit -m "git stash"`, or a path literal
+ * containing "git stash" never match. `refs/stash` is a single ref shared by every worktree over
+ * this repo's one `.git` directory, so a stash from one worktree can pop into another's — the
+ * PreToolUse gate blocks it outright on the target repo (see
+ * `skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout`).
+ * @param {string} command @returns {boolean}
+ */
+export function commandContainsGitStash(command) {
+  const re = new RegExp(`^${SHELL_EXEC_PREFIX}git\\s+${GIT_GLOBAL_OPTION_RUN}stash(?:\\s|$)`, "i");
+  return command
+    .split(SHELL_SEGMENT_SEPARATOR)
+    .some((segment) => re.test(segment.trim()));
 }
 
 /** Build the `gh pr <verb>` prefix matcher — delegates to the generic subcmd matcher (DRY). */

package/src/loop/conductor-routing.mjs

@@ -17,7 +17,7 @@
  * - The evaluator is purely functional; no I/O or side effects
  * - Callers use evaluateConductorRouting as the single routing authority
  *
- * Integration boundary (see docs/conductor-routing-contract.md):
+ * Integration boundary (see skills/docs/conductor-routing-contract.md):
  * - This module starts after active-run identity and ownership are already resolved
  * - It consumes already-detected family-local lifecycle states as inputs
  * - It derives the routing outcome directly from states; it does not take a

package/src/loop/copilot-ci-status.mjs

@@ -5,6 +5,58 @@ const STATUS_CONTEXT_FAILURE_STATES = new Set(["FAILURE", "ERROR"]);
 const STATUS_CONTEXT_PENDING_STATES = new Set(["PENDING", "EXPECTED"]);
 const STATUS_CONTEXT_SUCCESS_STATES = new Set(["SUCCESS"]);
 
+/**
+ * Name of the explicit commit STATUS dev-loops posts on its own pull requests
+ * from `.github/workflows/gate-evidence.yml`. Its conclusion is DERIVED from
+ * the loop's own progress (a clean current-head pre_approval_gate verdict),
+ * not an independent build/test signal — so the loop must exclude it when
+ * deriving the CI status that gates its own pre_approval step. Otherwise the
+ * loop could never post the very verdict that would turn this check green
+ * (#1358). This constant names ONLY the status context; the workflow also
+ * surfaces as a check run, so anything partitioning check runs must use
+ * `LOOP_DERIVED_CI_CHECK_NAMES` below. It remains the label reported in
+ * `excludedFailureDetails` for either shape, since both name one workflow.
+ */
+export const LOOP_DERIVED_CI_CHECK_NAME = "gate-evidence";
+
+/**
+ * The same workflow ALSO surfaces as a check run under its job id
+ * (`gate-evidence-runner`) beside the commit status named above, and both are
+ * the loop's own derived signal. Excluding only the status context left the
+ * runner's conclusion gating the loop's own pre_approval step: once the
+ * workflow gained job-level concurrency, a superseded run is cancelled as
+ * normal operation, and a cancelled run is deliberately NOT treated as green
+ * (see normalizeStatusCheckRollupStatus) — so one routine cancellation made
+ * the whole head read "none" and the loop waited on CI forever.
+ */
+export const LOOP_DERIVED_CI_CHECK_NAMES = Object.freeze([LOOP_DERIVED_CI_CHECK_NAME, "gate-evidence-runner"]);
+
+function checkEntryName(entry) {
+  if (typeof entry?.name === "string" && entry.name.length > 0) return entry.name;
+  if (typeof entry?.context === "string" && entry.context.length > 0) return entry.context;
+  return "";
+}
+
+/**
+ * Split rollup/check-run entries into those matching `targetName` and the rest.
+ * Shared by both statusCheckRollup-shaped and check-runs-shaped payloads —
+ * both use `.name` (check-runs also use `.context` for legacy StatusContext).
+ *
+ * @param {Array<object>} entries
+ * @param {string|Array<string>} targetName One name, or several to match.
+ * @returns {{ matched: Array<object>, rest: Array<object> }}
+ */
+export function partitionEntriesByCheckName(entries, targetName) {
+  const list = Array.isArray(entries) ? entries : [];
+  const targets = new Set(Array.isArray(targetName) ? targetName : [targetName]);
+  const matched = [];
+  const rest = [];
+  for (const entry of list) {
+    (targets.has(checkEntryName(entry)) ? matched : rest).push(entry);
+  }
+  return { matched, rest };
+}
+
 function normalizeHeadScopedCiStatus(status) {
   return VALID_HEAD_SCOPED_CI_STATUSES.has(status) ? status : "none";
 }
@@ -253,3 +305,27 @@ export function normalizeHeadScopedCiContract({
 
   return buildCiContract(overallStatus);
 }
+
+/**
+ * Derive a loop-safe CI status from a PR `statusCheckRollup` snapshot: the
+ * `LOOP_DERIVED_CI_CHECK_NAMES` entries (the `gate-evidence` status and the
+ * workflow's own `gate-evidence-runner` check run) are excluded from the
+ * status computation before it can block, and surfaced separately so a
+ * genuinely failing check right beside it can never be masked. Every reason
+ * gate-evidence can be red (missing draft_gate/pre_approval evidence,
+ * unresolved threads, a stale runner) is independently tracked elsewhere in
+ * the loop snapshot, so excluding it here loses no real signal: `status`
+ * stays a plain "success" (not an "unconfirmed" crediblyGreen) when it is the
+ * only excluded failure and everything else is green.
+ *
+ * @param {Array<object>} rollup
+ * @returns {{ status: "success"|"failure"|"pending"|"none", excludedFailureDetails: Array<string> }}
+ */
+export function deriveLoopCiStatusFromRollup(rollup) {
+  const { matched, rest } = partitionEntriesByCheckName(rollup, LOOP_DERIVED_CI_CHECK_NAMES);
+  const status = normalizeStatusCheckRollupStatus(rest);
+  const excludedFailureDetails = matched.length > 0 && normalizeStatusCheckRollupStatus(matched) === "failure"
+    ? [LOOP_DERIVED_CI_CHECK_NAME]
+    : [];
+  return { status, excludedFailureDetails };
+}

package/src/loop/copilot-loop-iterations.mjs

@@ -1,7 +1,6 @@
-import { isCopilotLogin, normalizeTimestamp } from "../github/copilot-helpers.mjs";
+import { SUBMITTED_REVIEW_STATES, isCopilotLogin, normalizeTimestamp } from "../github/copilot-helpers.mjs";
 
 const ACTIVE_COPILOT_REVIEW_REQUEST_STATUSES = new Set(["requested", "already-requested"]);
-const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 
 function normalizeReviewRequestEvents(events) {
   if (!Array.isArray(events)) {

package/src/loop/copilot-loop-state.mjs

@@ -12,7 +12,7 @@
  * becomes an explicit bounded input (agentFixStatus) rather than hidden orchestration behavior.
  */
 
-import { normalizeStatusCheckRollupContract } from "./copilot-ci-status.mjs";
+import { deriveLoopCiStatusFromRollup } from "./copilot-ci-status.mjs";
 
 /** Stable state name constants for the async Copilot review/fix loop. */
 export const STATE = Object.freeze({
@@ -191,7 +191,7 @@ export function isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRo
 }
 
 export function normalizeCiStatus(rollup) {
-  return normalizeStatusCheckRollupContract(rollup).overallStatus;
+  return deriveLoopCiStatusFromRollup(rollup).status;
 }
 
 export function buildSnapshotFromPrFacts({
@@ -206,11 +206,15 @@ export function buildSnapshotFromPrFacts({
   ciStatus,
   lastCopilotRoundMaxSignal = null,
   failureDetails = [],
-  excludedFailureDetails = [],
+  excludedFailureDetails,
 }) {
   const prState = typeof prData?.state === "string" ? prData.state.toUpperCase() : "OPEN";
   const prMerged = prState === "MERGED";
   const prClosed = prState === "CLOSED";
+  // Default derivation excludes the loop's own gate-evidence check (#1358) so a
+  // caller that never threads an explicit ciStatus (e.g. gate-coordination
+  // detection) still never treats it as a blocking CI failure.
+  const rollupDerivation = deriveLoopCiStatusFromRollup(prData?.statusCheckRollup);
 
   return normalizeSnapshot({
     prExists: true,
@@ -225,9 +229,9 @@ export function buildSnapshotFromPrFacts({
     actionableThreadCount,
     copilotReviewRoundCount,
     lastCopilotRoundMaxSignal,
-    ciStatus: ciStatus ?? normalizeCiStatus(prData?.statusCheckRollup),
+    ciStatus: ciStatus ?? rollupDerivation.status,
     failureDetails,
-    excludedFailureDetails,
+    excludedFailureDetails: excludedFailureDetails ?? rollupDerivation.excludedFailureDetails,
   });
 }
 

package/src/loop/default-branch-guard.mjs

@@ -0,0 +1,380 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * A shell working directory can silently reset to the primary checkout — after a
+ * subprocess run, or when a `cd` inside a compound command does not persist. An
+ * agent that then runs a relative-path `git commit && git push` executes it in
+ * the PRIMARY checkout on the DEFAULT branch, so the change lands straight on
+ * the remote's default branch and skips the PR flow entirely. Prose in a
+ * contract cannot stop that; the shell never read it.
+ *
+ * These hooks make the dangerous operation itself fail. Linked worktrees DO run
+ * them — git resolves hooks from the common directory, which every worktree
+ * shares — so what spares the loop's own work is the branch/ref check, not the
+ * hook's absence. A sanctioned release or reconcile sets DEVLOOPS_ALLOW_MAIN=1
+ * to proceed deliberately.
+ */
+export const GUARD_MARKER = "dev-loops:default-branch-guard";
+export const GUARD_OVERRIDE_ENV = "DEVLOOPS_ALLOW_MAIN";
+// pre-merge-commit, not pre-commit, is what git runs for `git merge` (a plain
+// `git commit` never fires during a merge); omitting it let a merge onto a
+// guarded branch land while a plain commit on the same branch was refused.
+export const GUARDED_HOOKS = Object.freeze(["pre-commit", "pre-merge-commit", "pre-push"]);
+
+const REFUSAL_BODY = (what, branchExpr) => `  echo "dev-loops: refusing to ${what} ($${branchExpr}) from this checkout." >&2
+  echo "  The dev-loop works in a linked worktree; a cwd that silently reset to the" >&2
+  echo "  primary checkout is the usual cause. Re-run from the worktree, addressing it" >&2
+  echo "  explicitly (git -C <absolute-worktree-path> ...)." >&2
+  echo "  For a sanctioned release or reconcile: ${GUARD_OVERRIDE_ENV}=1 <command>" >&2`;
+
+/**
+ * Git's ref rules forbid spaces and control characters but permit `$`, backtick,
+ * quotes, `;`, `&`, `|` and parentheses — every one of which sh expands inside
+ * the double-quoted assignment below. A branch named `main$(id)` would execute
+ * on every commit, and `main$HOME` would expand to something that never matches
+ * the real branch, leaving the default silently unguarded. Only names matching
+ * this are baked in. An unsafe DEFAULT branch refuses the install; an unsafe EXPLICIT base is dropped (recorded in droppedExplicitBranches) while the default guard installs.
+ */
+const SHELL_SAFE_BRANCH = /^[A-Za-z0-9._/-]+$/;
+
+/**
+ * Normalize a `defaultBranches` argument (a single branch name, an array of
+ * them, or nothing) to a deduped array of trimmed, non-empty strings. More
+ * than one branch is guarded when a caller's own default (git's advertised
+ * `<remote>/HEAD`) and its resolved working base genuinely differ — e.g. a
+ * `.devloops` `workflow.baseBranch` of `develop` in a repo whose real default
+ * is still `main`: a stray commit on EITHER must be refused.
+ */
+function normalizeBranchList(branches) {
+  const list = branches == null ? [] : Array.isArray(branches) ? branches : [branches];
+  const seen = new Set();
+  const out = [];
+  for (const raw of list) {
+    if (typeof raw !== "string") continue;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0 || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
+/**
+ * @param {(typeof GUARDED_HOOKS)[number]} hookName one of GUARDED_HOOKS —
+ *   "pre-commit", "pre-merge-commit", or "pre-push".
+ * @param {string|string[]|null} defaultBranches the STICKY set, resolved at
+ *   INSTALL time and unioned across installs by installDefaultBranchGuard.
+ *   Baking them in beats re-deriving in shell: `origin/HEAD` is often absent,
+ *   and a main-or-master guess picks a stale local `main` in a `master` repo,
+ *   which would guard the wrong branch and leave the real default open.
+ * @param {string|string[]|null} explicitBranches an operator-scoped set
+ *   (e.g. an explicit `--base`) that REPLACES rather than unions across
+ *   installs — see installDefaultBranchGuard's explicitBaseBranches.
+ * @throws {Error} when hookName is not a guarded hook, or any branch is
+ *   non-empty and not shell-safe. `hookName` and every branch name are
+ *   interpolated straight into the generated script, so THIS function — not
+ *   just its installDefaultBranchGuard caller — is the trust boundary and
+ *   must refuse on its own rather than rely on every caller re-checking first.
+ */
+export function renderGuardHook(hookName, defaultBranches = null, explicitBranches = null) {
+  if (!GUARDED_HOOKS.includes(hookName)) {
+    throw new Error(`renderGuardHook: unknown hook ${JSON.stringify(hookName)}; expected one of ${GUARDED_HOOKS.join(", ")}`);
+  }
+  const branches = normalizeBranchList(defaultBranches);
+  const explicits = normalizeBranchList(explicitBranches);
+  const unsafe = [...branches, ...explicits].find((branch) => !SHELL_SAFE_BRANCH.test(branch));
+  if (unsafe) {
+    throw new Error(
+      `default branch ${JSON.stringify(unsafe)} contains characters the generated hook's shell would expand; refusing to render a hook that could execute it`,
+    );
+  }
+  const defaults = branches.join(" ");
+  const explicitDefaults = explicits.join(" ");
+  const header = `#!/bin/sh
+# ${GUARD_MARKER}
+# Refuses a ${hookName} that would land on a guarded default branch. Installed
+# in the common hook directory, so linked worktrees run it too — their branch
+# is not one of the guarded ones, which is what lets their work through.
+if [ "\${${GUARD_OVERRIDE_ENV}}" = "1" ]; then
+  exit 0
+fi
+defaults="${defaults}"
+explicit_defaults="${explicitDefaults}"
+if [ -z "$defaults" ] && [ -z "$explicit_defaults" ]; then
+  # Not resolvable at install time; fail OPEN rather than guess a branch and
+  # protect the wrong one. The install reports this so it is not silent.
+  exit 0
+fi
+`;
+
+  // pre-commit and pre-merge-commit both fire with HEAD already on the branch
+  // the commit would land on (a plain commit vs. finishing a merge) — same
+  // check, just under the name git actually invokes for each operation.
+  if (hookName !== "pre-push") {
+    return `${header}
+# Full ref, not --short: git DISAMBIGUATES a --short symbolic-ref to
+# "heads/main" when a tag also named "main" exists, so comparing the short
+# form against a bare branch name would never match and let the commit land.
+branch=$(git symbolic-ref --quiet HEAD 2>/dev/null) || exit 0
+for default in $defaults $explicit_defaults; do
+  if [ "$branch" = "refs/heads/$default" ]; then
+${REFUSAL_BODY("commit on the default branch", "default")}
+    exit 1
+  fi
+done
+exit 0
+`;
+  }
+
+  // pre-push receives "<local ref> <local sha> <remote ref> <remote sha>" per
+  // line on stdin. Checking the CURRENT branch instead would miss every
+  // explicit refspec — `git push origin HEAD:main` from a feature branch is the
+  // exact shape that moved a remote default in testing.
+  return `${header}
+blocked=0
+blocked_default=""
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [ -n "$remote_ref" ] || continue
+  for default in $defaults $explicit_defaults; do
+    if [ "$remote_ref" = "refs/heads/$default" ]; then
+      blocked=1
+      blocked_default="$default"
+    fi
+  done
+done
+if [ "$blocked" = "1" ]; then
+${REFUSAL_BODY("push to the default branch", "blocked_default")}
+  exit 1
+fi
+exit 0
+`;
+}
+
+// Ownership is decided by the marker on a line of its OWN, exactly as the
+// renderer emits it. A bare substring test would claim any file that merely
+// mentions the sentinel — a user wrapper commented "# chains to
+// dev-loops:default-branch-guard" reads as ours and gets overwritten, which is
+// the one thing installDefaultBranchGuard promises never to do.
+const GUARD_MARKER_LINE = new RegExp(`^# ${GUARD_MARKER}$`, "mu");
+
+/**
+ * Pull a baked-in branch list back out of a line this guard itself wrote
+ * (`defaults="..."` or `explicit_defaults="..."`), re-validating every entry
+ * against SHELL_SAFE_BRANCH rather than trusting the file. A hand-edited (or
+ * otherwise corrupted) baked value would otherwise make renderGuardHook THROW
+ * on re-install — after earlier hook slots may already have been renamed into
+ * place — which breaks the documented "guard.ok: false means nothing was
+ * written" invariant. Dropping the unsafe entry here keeps the contract:
+ * install refuses on genuinely new bad input, and self-heals a tampered file.
+ */
+function extractBakedBranches(contents, varName) {
+  const match = contents.match(new RegExp(`^${varName}="([^"]*)"$`, "mu"));
+  if (!match) return [];
+  return match[1].split(/\s+/u).filter((branch) => branch.length > 0 && SHELL_SAFE_BRANCH.test(branch));
+}
+
+function readHookState(hookPath) {
+  if (!fs.existsSync(hookPath)) return { ours: true, absent: true, existingBranches: [], existingExplicitBranches: [] };
+  const contents = fs.readFileSync(hookPath, "utf8");
+  const ours = GUARD_MARKER_LINE.test(contents);
+  return {
+    ours,
+    absent: false,
+    existingBranches: ours ? extractBakedBranches(contents, "defaults") : [],
+    existingExplicitBranches: ours ? extractBakedBranches(contents, "explicit_defaults") : [],
+  };
+}
+
+/**
+ * Install the guard hooks into a repository's hook directory.
+ *
+ * Idempotent: re-installing rewrites only hooks this guard authored. A hook the
+ * user (or another tool) wrote is NEVER clobbered — that file is left exactly as
+ * found and reported as `skipped`, because silently replacing someone's hook is
+ * a worse failure than not installing ours.
+ *
+ * `defaultBranches` and `explicitBaseBranches` are tracked as two SEPARATE
+ * slots baked into every hook, because they need opposite persistence rules:
+ * - `defaultBranches` (a repo's own default) is UNIONED across installs — a
+ *   later call resolving fewer/none (a transient fetch hiccup) must never
+ *   un-guard a branch an earlier install already protected.
+ * - `explicitBaseBranches` (an operator's `--base`, or a configured
+ *   `workflow.baseBranch`) is REPLACED wholesale by whatever this call
+ *   passes — a later call with a different (or no) explicit base must be
+ *   able to replace or drop it, never stack it forever. Unioning this slot
+ *   too would permanently guard every branch anyone ever stacked a worktree
+ *   off, refusing that branch's OWN commits with no way to undo it.
+ *
+ * @param {{ gitDir: string, defaultBranches?: string|string[]|null, explicitBaseBranches?: string|string[]|null, hooksPathOverride?: string|null }} target
+ *   `hooksPathOverride` is the repo's `core.hooksPath` when set. Installing into
+ *   `$GIT_DIR/hooks` while git reads elsewhere would report success for a guard
+ *   that can never fire, so that case refuses instead.
+ */
+export function installDefaultBranchGuard({
+  gitDir,
+  defaultBranches = null,
+  explicitBaseBranches = null,
+  hooksPathOverride = null,
+}) {
+  const refuse = (reason, skipReason) => ({
+    ok: false,
+    installed: [],
+    refreshed: [],
+    skipped: GUARDED_HOOKS.map((hook) => ({ hook, reason: skipReason })),
+    reason,
+  });
+
+  // Any STRING means core.hooksPath is set (`git config --get` exits 0), even
+  // to "" — which git treats as "run no hooks at all", not "unset". A caller
+  // that collapsed exit-0-empty and exit-1-unset to the same null would make
+  // this refusal unreachable for exactly the config value it exists to catch.
+  if (typeof hooksPathOverride === "string") {
+    const configured = hooksPathOverride.trim();
+    return configured.length > 0
+      ? refuse(
+          `core.hooksPath is set to ${JSON.stringify(configured)} — install the guard there, or unset it, or use ${GUARD_OVERRIDE_ENV} discipline instead`,
+          `core.hooksPath is set to ${JSON.stringify(configured)}, so hooks in $GIT_DIR/hooks would never run`,
+        )
+      : refuse(
+          `core.hooksPath is set to an empty string — git runs no hooks at all; unset it, or use ${GUARD_OVERRIDE_ENV} discipline instead`,
+          "core.hooksPath is set to an empty string, so git runs no hooks at all",
+        );
+  }
+
+  // A relative or empty gitDir resolves against the caller's cwd, which writes a
+  // stray hooks/ directory into the working tree and reports success for a guard
+  // git will never read.
+  if (typeof gitDir !== "string" || !path.isAbsolute(gitDir)) {
+    return refuse(
+      `gitDir must be an absolute path; got ${JSON.stringify(gitDir)}`,
+      "no absolute git directory to install into",
+    );
+  }
+
+  // Absoluteness alone does not make it a GIT dir: a caller slip (the worktree
+  // root instead of its .git) would otherwise pass, then mkdirSync a stray
+  // hooks/ tree there and report success for a guard git will never read.
+  // Every real git dir — bare, a main checkout, or a linked worktree's own
+  // gitdir — has a HEAD file; that is the cheapest reliable probe.
+  if (!fs.existsSync(path.join(gitDir, "HEAD"))) {
+    return refuse(
+      `gitDir ${JSON.stringify(gitDir)} does not look like a git directory (no HEAD file)`,
+      "gitDir does not look like a git directory",
+    );
+  }
+
+  // A linked worktree's OWN per-worktree gitdir (`.git/worktrees/<name>`) also
+  // has a HEAD file, so the probe above alone lets it through — hooks written
+  // there are never resolved by git (hooks always come from the COMMON dir),
+  // so this would report ok:true for a guard that can never fire. `commondir`
+  // exists only in a linked worktree's own gitdir, never in the common one:
+  // a one-line, same-cost discriminator against exactly that gitdir.
+  if (fs.existsSync(path.join(gitDir, "commondir"))) {
+    return refuse(
+      `gitDir ${JSON.stringify(gitDir)} is a linked worktree's own git directory, not the common one — hooks installed there never run`,
+      "gitDir is a linked worktree's own git directory (has a commondir file), not the common one hooks are resolved from",
+    );
+  }
+
+  const branches = normalizeBranchList(defaultBranches);
+  const allExplicitBranches = normalizeBranchList(explicitBaseBranches);
+  const unsafeBranch = branches.find((branch) => !SHELL_SAFE_BRANCH.test(branch));
+
+  if (unsafeBranch) {
+    return refuse(
+      `default branch ${JSON.stringify(unsafeBranch)} contains characters the generated hook's shell would expand; refusing rather than installing a hook that could execute it or silently guard the wrong branch`,
+      "the resolved default branch name is not shell-safe",
+    );
+  }
+
+  // A shell-unsafe EXPLICIT base (git-legal names like "feat(auth)" or
+  // "fix#123") must not kill the whole install — that would leave the real
+  // default branch unguarded while reporting the worktree ok. Drop only the
+  // unsafe explicit entries, install the default guard regardless, and record
+  // what was dropped so the caller can surface it.
+  const droppedExplicitBranches = allExplicitBranches.filter((branch) => !SHELL_SAFE_BRANCH.test(branch));
+  const explicitBranches = allExplicitBranches.filter((branch) => SHELL_SAFE_BRANCH.test(branch));
+
+  const hooksDir = path.join(gitDir, "hooks");
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  // Read every guarded slot's on-disk state ONCE, up front — not inside the
+  // write loop — so the union below is computed repo-wide. Computing it
+  // per-hook instead let a slot that just became free (a foreign hook
+  // removed) miss what its siblings already had baked in, e.g. a hook
+  // re-installed after its foreign occupant is gone could get written INERT
+  // while its siblings still enforced the real default.
+  const hookStates = GUARDED_HOOKS.map((hook) => ({ hook, hookPath: path.join(hooksDir, hook), ...readHookState(path.join(hooksDir, hook)) }));
+
+  // Sticky slot: union across whatever this call resolved (`branches`) with
+  // what ANY hook of ours already had baked in — never a straight overwrite.
+  // A caller's resolution can legitimately come back empty or narrower on a
+  // later call (a transient fetch/network hiccup, a remote HEAD that briefly
+  // stopped advertising); rewriting to that smaller set would silently
+  // un-guard a branch an earlier install already protected.
+  const stickyBranches = new Set(branches);
+  for (const state of hookStates) {
+    if (!state.ours) continue;
+    for (const branch of state.existingBranches) stickyBranches.add(branch);
+  }
+  const finalStickyBranches = [...stickyBranches];
+
+  // Explicit-base slot: REPLACED wholesale by whatever this call passed, never
+  // unioned with what a PRIOR call baked in — that is what makes the slot
+  // droppable (a later call with a different, or no, explicit base) instead
+  // of accumulating every branch anyone ever stacked a worktree off.
+  const finalExplicitBranches = explicitBranches;
+
+  const installed = [];
+  const refreshed = [];
+  const skipped = [];
+  let anyWritten = false;
+
+  for (const state of hookStates) {
+    const { hook, hookPath, ours, absent } = state;
+    if (!ours) {
+      skipped.push({ hook, reason: "a pre-existing hook is present and was left untouched" });
+      continue;
+    }
+    // Write + chmod a temp file in the SAME directory, then rename into place.
+    // A direct writeFileSync is visible to git mid-write: the common hooks dir
+    // is shared, so a concurrent ensureWorktree call (or a real commit racing
+    // an install) can exec the file while it is still header-only, falling
+    // through to `exit 0` and letting a default-branch commit land. A same-dir
+    // rename is atomic, so any reader sees either the old hook or the new one,
+    // never a partial one.
+    const tmpPath = path.join(hooksDir, `.${hook}.tmp-${process.pid}-${Date.now()}`);
+    fs.writeFileSync(tmpPath, renderGuardHook(hook, finalStickyBranches, finalExplicitBranches), { mode: 0o755 });
+    fs.chmodSync(tmpPath, 0o755); // mode above is umask-limited; force it
+    fs.renameSync(tmpPath, hookPath);
+    anyWritten = true;
+    (absent ? installed : refreshed).push(hook);
+  }
+
+  // Report only what a hook actually enforces: a branch reads as guarded when
+  // at least one slot was WRITTEN with it, never merely requested. Seeding
+  // this from `branches` before the loop (the prior bug) claimed enforcement
+  // — ok: true, defaultBranches: ["main"] — even when every slot was foreign
+  // and nothing was written.
+  const reportedBranches = anyWritten ? [...new Set([...finalStickyBranches, ...finalExplicitBranches])] : [];
+  let reason;
+  if (reportedBranches.length === 0) {
+    reason = anyWritten
+      ? "default branch could not be resolved at install time; the hooks are inert rather than guessing which branch to protect"
+      : "every guarded hook slot is already occupied by a foreign hook; nothing was written, so nothing is enforced";
+  }
+  if (droppedExplicitBranches.length > 0) {
+    const dropNote = `explicit base ${droppedExplicitBranches.map((branch) => JSON.stringify(branch)).join(", ")} contains characters the generated hook's shell would expand; the default guard was installed without it`;
+    reason = reason ? `${reason}; ${dropNote}` : dropNote;
+  }
+  return {
+    ok: true,
+    installed,
+    refreshed,
+    skipped,
+    defaultBranches: reportedBranches,
+    ...(droppedExplicitBranches.length > 0 ? { droppedExplicitBranches } : {}),
+    ...(reason ? { reason } : {}),
+  };
+}

package/src/loop/gate-carry-forward.mjs

@@ -17,7 +17,7 @@
  * caller records the carried verdict with provenance pointing at the PRIOR head's
  * reviewer (that reviewer genuinely reviewed this angle's surface, which the delta
  * did not touch), clearly marked as carried — see
- * docs/gate-review-sub-loop-contract.md and write-gate-findings-log.mjs's
+ * skills/docs/gate-review-sub-loop-contract.md and write-gate-findings-log.mjs's
  * `carriedFromHead` provenance field.
  *
  * The angle -> review-surface mapping is DERIVED from the single source of truth
@@ -125,7 +125,13 @@ export function angleReviewSurface(angle, { alwaysRerun } = {}) {
   const name = typeof angle === "string" ? angle.trim() : "";
   if (name.length === 0) return { kind: "unknown" };
   if (ALWAYS_INCLUDE.has(name)) return { kind: "always" };
-  if (alwaysRerun && new Set(alwaysRerun).has(name)) return { kind: "always" };
+  // Case-insensitive: callers key angles as base+lowercase while configs may
+  // carry case drift ("Correctness"); normalizing HERE keeps producer and
+  // consumer on one predicate instead of each caller pre-lowercasing.
+  if (alwaysRerun) {
+    const normalized = new Set([...alwaysRerun].map((entry) => String(entry).trim().toLowerCase()));
+    if (normalized.has(name.toLowerCase())) return { kind: "always" };
+  }
   const kinds = ANGLE_SURFACE_KINDS.get(name);
   if (!kinds || kinds.size === 0) return { kind: "unknown" };
   return { kind: "kinds", kinds: new Set(kinds) };
@@ -149,6 +155,24 @@ export function angleReviewSurface(angle, { alwaysRerun } = {}) {
  *   is carry-forward-eligible.
  * @returns {{ carryForward: boolean, reason: string }}
  */
+
+// A path whose change rewrites the dev-loop review system itself — the angle
+// pool, mandatory floor, and reviewer personas/prompts — rather than a
+// reviewed surface. A clean verdict produced under the OLD config cannot
+// carry across such a delta, and a converged Copilot round cannot be treated
+// as still-converged either. classifyFile correctly reports these as
+// "config"; this predicate is the carry-forward-specific override. The
+// shipped defaults file is in this class too: it is the layer that ships the
+// angle pool and reviewer prompts, so a delta touching it must never be
+// carried across or reviewed under a reduced diff-class tier.
+const DEV_LOOP_CONFIG_SOURCE_RE = /(^|\/)(\.devloops(\.(ya?ml|json))?|\.pi\/dev-loop\/(settings|defaults)\.[^/]+|packages\/core\/src\/config\/extension-defaults\.yaml)$/;
+export function isDevLoopConfigSourcePath(filePath) {
+  if (typeof filePath !== "string") return false;
+  // Normalize Windows separators like classifyFile does, so a
+  // ".pi\\dev-loop\\settings.yaml" delta is still detected on Windows.
+  return DEV_LOOP_CONFIG_SOURCE_RE.test(filePath.trim().replace(/\\/g, "/"));
+}
+
 export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, prevVerdict }) {
   if (prevVerdict !== "clean") {
     return { carryForward: false, reason: `prior verdict is ${JSON.stringify(prevVerdict ?? null)}, not "clean"` };
@@ -164,6 +188,9 @@ export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, pr
     return { carryForward: false, reason: "delta is empty or unavailable (fail-closed)" };
   }
   for (const file of changedFiles) {
+    if (isDevLoopConfigSourcePath(file)) {
+      return { carryForward: false, reason: `delta rewrites the dev-loop config source (reviewer pool/prompts): ${file}` };
+    }
     const kind = classifyFile(file);
     if (kind === "unknown") {
       return { carryForward: false, reason: `delta contains an unclassifiable file (fail-closed): ${file}` };