@dev-loops/core 1.0.0-rc.6 → 1.0.0

package/src/github/copilot-helpers.mjs

@@ -6,14 +6,32 @@
  * scripts and other packages/core modules.
  */
 
+import { GATE_REVIEW_VERDICT_SET } from "../loop/policy-constants.mjs";
+import { trimmedOrNull } from "../loop/normalize.mjs";
+
 // Exported so anything deciding "is there a real prior review" uses the same
 // whitelist as the loop-state reader — two copies could drift, and a guard
 // acting on the gate's behalf must agree with the gate about what a submitted
 // review is.
 export const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 const GATE_REVIEW_NAMES = new Set(["draft_gate", "pre_approval_gate"]);
-const GATE_REVIEW_VERDICTS = new Set(["clean", "findings_present", "blocked"]);
+// `review` (the standalone review entrypoint, upsert-checkpoint-verdict.mjs's
+// `--gate review`) is a RECOGNIZED gate header — it is identified, not
+// absent — but carries no draft/pre-approval evidence by design (#1808 AC3).
+// Recognizing it (rather than leaving it unrecognized) is what lets
+// parseGateReviewCommentFields below short-circuit to null the instant a
+// `review` header is seen, instead of falling through to the lenient
+// draft_gate/pre_approval_gate token scan — the fallthrough that previously
+// let a `review` verdict whose findings text merely MENTIONED "draft_gate"
+// get recorded as real draft-gate evidence (a draft-gate bypass).
+const NON_EVIDENCE_GATE_NAMES = new Set(["review"]);
+const RECOGNIZED_GATE_NAMES = new Set([...GATE_REVIEW_NAMES, ...NON_EVIDENCE_GATE_NAMES]);
 const GATE_EXECUTION_MODES = new Set(["fanout_fanin", "inline_single_agent"]);
+// Size-budget outcome vocabulary — mirrors
+// check-size-budget.mjs's computeSizeBudget outcome enum exactly; this file
+// never recomputes the outcome, only round-trips it through the verdict
+// comment.
+const GATE_SIZE_OUTCOMES = new Set(["pass", "escalate", "block"]);
 
 // The literal header line the gate review body always emits first
 // (upsert-checkpoint-verdict.mjs's renderGateReviewCommentBody, re-exported
@@ -288,14 +306,19 @@ function stripGateCommentMarkdown(rawLine) {
   return line.trim();
 }
 
+// Recognizes BOTH evidence gates (draft_gate/pre_approval_gate) and the
+// non-evidence `review` gate — parseGateReviewCommentFields below relies on
+// `review` coming back as an identified value (not null) so it can
+// short-circuit to non-evidence explicitly, rather than leaving the field
+// null and falling through to the lenient token-scan fallback.
 function normalizeGateReviewName(value) {
   const normalized = stripOptionalCodeTicks(value).toLowerCase();
-  return GATE_REVIEW_NAMES.has(normalized) ? normalized : null;
+  return RECOGNIZED_GATE_NAMES.has(normalized) ? normalized : null;
 }
 
 function normalizeGateReviewVerdict(value) {
   const normalized = stripOptionalCodeTicks(value).toLowerCase();
-  return GATE_REVIEW_VERDICTS.has(normalized) ? normalized : null;
+  return GATE_REVIEW_VERDICT_SET.has(normalized) ? normalized : null;
 }
 
 function normalizeGateReviewHeadSha(value) {
@@ -308,6 +331,32 @@ function normalizeGateExecutionMode(value) {
   return GATE_EXECUTION_MODES.has(normalized) ? normalized : null;
 }
 
+function normalizeGateSizeOutcome(value) {
+  const normalized = stripOptionalCodeTicks(value).toLowerCase();
+  return GATE_SIZE_OUTCOMES.has(normalized) ? normalized : null;
+}
+
+function normalizeGateSizeTouchesT1(value) {
+  const normalized = stripOptionalCodeTicks(value).toLowerCase();
+  if (normalized === "touched") return true;
+  if (normalized === "not touched") return false;
+  return null;
+}
+
+// "none" | "granted" | "granted by <name>" — the approver name is free text
+// (already sanitized by the poster via sanitizeInline before rendering), so
+// no further normalization beyond trimming is applied here.
+function normalizeGateSizeWaiver(value) {
+  const normalized = stripOptionalCodeTicks(value).trim();
+  if (/^none$/iu.test(normalized)) return { granted: false, approvedBy: null };
+  const grantedMatch = normalized.match(/^granted(?:\s+by\s+(.+))?$/iu);
+  if (grantedMatch) {
+    const approvedBy = grantedMatch[1]?.trim();
+    return { granted: true, approvedBy: approvedBy && approvedBy.length > 0 ? approvedBy : null };
+  }
+  return null;
+}
+
 function parseGateReviewCommentFields(body) {
   if (typeof body !== "string" || body.trim().length === 0) {
     return null;
@@ -321,6 +370,10 @@ function parseGateReviewCommentFields(body) {
     nextAction: null,
     executionMode: null,
     inlineReason: null,
+    sizeOutcome: null,
+    sizeTouchesT1: null,
+    sizeWaiverGranted: null,
+    sizeWaiverApprovedBy: null,
   };
 
   for (const rawLine of body.split(/\r?\n/u)) {
@@ -413,6 +466,50 @@ function parseGateReviewCommentFields(body) {
       }
       continue;
     }
+
+    match = line.match(/^(?:[-*]\s*)?size[\s-]budget\s+outcome\s*:\s*(.+)$/iu);
+    if (match) {
+      if (fields.sizeOutcome === null) {
+        fields.sizeOutcome = normalizeGateSizeOutcome(match[1]);
+      }
+      continue;
+    }
+
+    match = line.match(/^(?:[-*]\s*)?size[\s-]budget\s+t1\s+slice\s*:\s*(.+)$/iu);
+    if (match) {
+      if (fields.sizeTouchesT1 === null) {
+        fields.sizeTouchesT1 = normalizeGateSizeTouchesT1(match[1]);
+      }
+      continue;
+    }
+
+    match = line.match(/^(?:[-*]\s*)?size[\s-]budget\s+waiver\s*:\s*(.+)$/iu);
+    if (match) {
+      if (fields.sizeWaiverGranted === null) {
+        const parsedWaiver = normalizeGateSizeWaiver(match[1]);
+        if (parsedWaiver) {
+          fields.sizeWaiverGranted = parsedWaiver.granted;
+          fields.sizeWaiverApprovedBy = parsedWaiver.approvedBy;
+        }
+      }
+      continue;
+    }
+  }
+
+  // An explicit, RECOGNIZED `review` gate field is authoritative and returns
+  // null here — before the lenient token-scan fallback below ever runs. A
+  // `review` verdict comment carries no draft/pre-approval evidence by
+  // design (#1808 AC3); without this short circuit, `fields.gate` would stay
+  // "review" (not one of the two evidence gates) but the lenient fallback
+  // below only fires when `!fields.gate` — so a *recognized* `review` gate
+  // would otherwise skip the fallback yet still return non-null fields keyed
+  // to "review", which is harmless for the two summarizers here (they only
+  // read `.draft_gate`/`.pre_approval_gate`) but leaves the non-evidence
+  // contract implicit rather than explicit. Stated plainly: an identified
+  // non-evidence gate must never be treated as an unidentified body, and an
+  // unidentified body is the ONLY case the token-scan fallback exists for.
+  if (NON_EVIDENCE_GATE_NAMES.has(fields.gate)) {
+    return null;
   }
 
   // Lenient fallback: detect gate name and head SHA anywhere in body
@@ -481,6 +578,10 @@ export function parseGateReviewCommentMarkerBody(body) {
     nextAction: fields.nextAction,
     executionMode: fields.executionMode,
     inlineReason: fields.inlineReason,
+    sizeOutcome: fields.sizeOutcome,
+    sizeTouchesT1: fields.sizeTouchesT1,
+    sizeWaiverGranted: fields.sizeWaiverGranted,
+    sizeWaiverApprovedBy: fields.sizeWaiverApprovedBy,
     contractComplete: Boolean(fields.verdict && fields.findingsSummary && fields.nextAction),
   };
 }
@@ -525,9 +626,13 @@ export function summarizeGateReviewComments(comments) {
       nextAction: parsed.nextAction,
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
+      sizeOutcome: parsed.sizeOutcome ?? null,
+      sizeTouchesT1: parsed.sizeTouchesT1 ?? null,
+      sizeWaiverGranted: parsed.sizeWaiverGranted ?? null,
+      sizeWaiverApprovedBy: parsed.sizeWaiverApprovedBy ?? null,
       surface: normalizeVerdictSurface(comment?.surface),
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
-      commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
+      commentUrl: trimmedOrNull(comment?.html_url),
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
         ? (comment.updated_at ?? comment.updatedAt).trim()
         : typeof (comment?.created_at ?? comment?.createdAt) === "string"
@@ -579,10 +684,14 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
       nextAction: parsed.nextAction,
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
+      sizeOutcome: parsed.sizeOutcome ?? null,
+      sizeTouchesT1: parsed.sizeTouchesT1 ?? null,
+      sizeWaiverGranted: parsed.sizeWaiverGranted ?? null,
+      sizeWaiverApprovedBy: parsed.sizeWaiverApprovedBy ?? null,
       contractComplete: parsed.contractComplete,
       surface: normalizeVerdictSurface(comment?.surface),
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
-      commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
+      commentUrl: trimmedOrNull(comment?.html_url),
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
         ? (comment.updated_at ?? comment.updatedAt).trim()
         : typeof (comment?.created_at ?? comment?.createdAt) === "string"

package/src/github/gh.mjs

@@ -0,0 +1,94 @@
+/**
+ * Shared `gh` CLI invoke-and-parse helpers (child 6 of the simplification
+ * epic #1689). This module introduces the shared implementation only; the
+ * ~19 call-site migrations are the follow-up children (projects: #1696;
+ * github/loop/refine: #1697).
+ *
+ * `ghJson` is the composed SUPERSET the callers share (per #1695's AC): a
+ * label-conditional non-zero-exit message — `gh command failed: <detail>` with
+ * no label (probe-ci-status shape) or `<label> failed: <detail>` with one
+ * (fetch-ci-logs shape) — always carrying `code: "GH_API_ERROR"`, plus the
+ * inline `Invalid JSON from gh: <stdout|<empty>>` malformed-stdout shape
+ * (probe-ci-status). `ghGraphql` reproduces scripts/projects/add-queue-item.mjs's
+ * superset (`gh api graphql failed` / `GraphQL errors:` with GH_API_ERROR /
+ * GRAPHQL_ERROR; `parseJsonText` → `Invalid JSON input`).
+ *
+ * Because `ghJson` is a composed superset, NO current caller matches it exactly
+ * — migrating each is a deliberate behavior harmonization, not a blind swap:
+ *   - probe-ci-status.mjs: `gh command failed:` / `Invalid JSON from gh:` already
+ *     match; it gains the `GH_API_ERROR` code on non-zero exit.
+ *   - fetch-ci-logs.mjs: `<label> failed:` matches (pass its label); it gains the
+ *     `GH_API_ERROR` code and its malformed-JSON message becomes
+ *     `Invalid JSON from gh:` (was `parseJsonText` → `Invalid JSON input`).
+ *   - upsert-checkpoint-verdict.mjs / post-gate-findings.mjs: gain the code and
+ *     their malformed-JSON message becomes `Invalid JSON from gh:` (was
+ *     `Invalid JSON input`).
+ * The follow-up children (projects: #1696; github/loop/refine: #1697) migrate
+ * each caller and update its pinned test messages accordingly.
+ */
+
+import { runChild as defaultRunChild } from "../cli/primitives.mjs";
+import { parseJsonText } from "./review-threads.mjs";
+
+/**
+ * Run a `gh` subcommand and parse its stdout as JSON. Fails loudly on a
+ * non-zero exit (naming the command's stderr) and on malformed JSON stdout.
+ *
+ * @param {string[]} args - argv passed to `ghCommand`.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {string} [opts.ghCommand] - defaults to `"gh"`.
+ * @param {typeof defaultRunChild} [opts.runChild] - injectable child-exec seam.
+ * @param {string} [opts.label] - controls the non-zero-exit message: when set,
+ *   the thrown error reads `<label> failed: <detail>` (the fetch-ci-logs shape);
+ *   when omitted it reads `gh command failed: <detail>` (the probe-ci-status
+ *   shape). Either way the non-zero-exit error carries `code: "GH_API_ERROR"`.
+ */
+export async function ghJson(args, { env, ghCommand = "gh", runChild = defaultRunChild, label } = {}) {
+  const result = await runChild(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    const prefix = label ? `${label} failed` : "gh command failed";
+    throw Object.assign(new Error(`${prefix}: ${detail}`), { code: "GH_API_ERROR" });
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Invalid JSON from gh: ${result.stdout.trim() || "<empty>"}`);
+  }
+}
+
+/**
+ * Run a `gh api graphql` query and parse its response.
+ *
+ * @param {string} query - the GraphQL document.
+ * @param {Record<string, string>} vars - `--field key=value` variables.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {typeof defaultRunChild} [runChild] - injectable child-exec seam.
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowErrors] - when true, a GraphQL `errors` array
+ *   in the response is returned instead of thrown.
+ */
+export async function ghGraphql(query, vars, env, runChild = defaultRunChild, { allowErrors = false } = {}) {
+  const fieldArgs = [];
+  for (const [key, value] of Object.entries(vars)) {
+    fieldArgs.push("--field", `${key}=${value}`);
+  }
+  const result = await runChild(
+    "gh",
+    ["api", "graphql", "--field", `query=${query}`, ...fieldArgs],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
+  }
+  const payload = parseJsonText(result.stdout);
+  if (!allowErrors && payload.errors && payload.errors.length > 0) {
+    throw Object.assign(
+      new Error(`GraphQL errors: ${payload.errors.map((e) => e.message).join("; ")}`),
+      { code: "GRAPHQL_ERROR" },
+    );
+  }
+  return payload;
+}

package/src/github/issue-ops.mjs

@@ -288,6 +288,13 @@ export async function listIssues(options, { env = process.env, ghCommand = "gh",
   for (const label of options.labels ?? []) {
     args.push("--label", label);
   }
+  // `--search` narrows the result set to gh's own full-text search (title,
+  // body, comments) rather than the bare paged listing — needed by a caller
+  // that must find one specific issue by title without trusting that it falls
+  // within the default 30-issue page.
+  if (typeof options.search === "string" && options.search.length > 0) {
+    args.push("--search", options.search);
+  }
   const result = await run(ghCommand, args, env);
   if (result.code !== 0) {
     const detail = result.stderr.trim() || `exit code ${result.code}`;

package/src/loop/agent-stall.mjs

@@ -19,6 +19,8 @@
  * sources those signals from pi run artifacts + runner-coordination state.
  */
 
+import { trimmedOrNull } from "./normalize.mjs";
+
 export const AGENT_STALL_STATUS = Object.freeze({
   STALLED: "stalled",
   NOT_STALLED: "not_stalled",
@@ -178,8 +180,8 @@ export function buildAgentStallRecoveryBrief({
   lastAction = null,
   reason = "",
 } = {}) {
-  const r = typeof runId === "string" && runId.trim().length > 0 ? runId.trim() : null;
-  const work = typeof cwd === "string" && cwd.trim().length > 0 ? cwd.trim() : null;
+  const r = trimmedOrNull(runId);
+  const work = trimmedOrNull(cwd);
   const action = typeof lastAction === "string" && lastAction.trim().length > 0
     ? lastAction.trim()
     : "unknown last action";

package/src/loop/commit-msg-guard.mjs

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Enforces the commit-message contract AT COMMIT TIME (issue #1869): the
+ * attribution trailers, the no-bare-#N rule, and the conventional-commit
+ * subject form were previously prose-only — nothing checked them, so a
+ * non-compliant commit landed silently. Installed alongside the
+ * default-branch guard (see default-branch-guard.mjs), through the same
+ * ensure-worktree provisioning path, so it rides into every worktree too.
+ *
+ * The rendered hook is a single self-contained Node script (ESM: this repo's
+ * root package.json is `"type": "module"`, and Node resolves an
+ * extensionless direct-run script's module type by walking up for the
+ * nearest package.json — verified empirically, not merely assumed). Keeping
+ * the ENTIRE check inline in the rendered script (rather than requiring a
+ * sibling file back into the checkout) means the installed hook keeps
+ * working even if the checkout that installed it is later removed or moved
+ * — the same self-containment default-branch-guard's hooks rely on.
+ */
+export const COMMIT_MSG_GUARD_MARKER = "dev-loops:commit-msg-guard";
+export const COMMIT_MSG_WAIVER_MARKER = `${COMMIT_MSG_GUARD_MARKER}:allow`;
+
+// Ownership check mirrors default-branch-guard's: the marker must be its own
+// line (a `//` comment, since the rendered hook is JS), not merely mentioned,
+// so a foreign hook that references us in prose is still left untouched.
+const GUARD_MARKER_LINE = new RegExp(`^// ${COMMIT_MSG_GUARD_MARKER}$`, "mu");
+
+/**
+ * Renders the commit-msg hook as a standalone, runnable Node script. The
+ * validation logic below is the ONLY copy of it — there is no separate JS
+ * implementation this must stay in sync with, exactly like renderGuardHook's
+ * shell body has none either. Tests exercise it by actually running it (see
+ * commit-msg-guard.test.mjs), the same way default-branch-guard.test.mjs
+ * drives real git rather than asserting on rendered text.
+ *
+ * String.raw, not a plain template literal: the generated script is full of
+ * regex backslash escapes (\s, \d, \b, \.) that a normal template literal
+ * would silently strip (an unrecognized string escape drops its backslash),
+ * corrupting every regex in the installed hook. String.raw keeps every
+ * backslash literal while still substituting the ${...} marker constants.
+ * The generated script deliberately uses NO template literals of its own
+ * (string concatenation instead) — a literal backtick would otherwise close
+ * THIS OUTER template early.
+ */
+export function renderCommitMsgGuardHook() {
+  return String.raw`#!/usr/bin/env node
+// ${COMMIT_MSG_GUARD_MARKER}
+// Enforces the commit-message contract (issue #1869): attribution trailers,
+// no bare non-issue #<digits>, and a conventional-commit subject. A
+// per-commit waiver line (${COMMIT_MSG_WAIVER_MARKER}) skips every check
+// below for a deliberate exception.
+import { readFileSync } from "node:fs";
+
+// git invokes commit-msg with ONLY the message-file path (unlike
+// prepare-commit-msg, which also gets a source/sha) — no signal distinguishes
+// an ordinary commit from a merge/squash at this hook. A default, unedited
+// merge message ("Merge branch '...'", "Merge pull request #...", "Merge tag
+// '...'"), a default git-revert message (Revert "..."), or a
+// git commit --fixup/--squash autosquash subject (fixup! ... / squash! ...)
+// is git/tooling-generated, not operator-authored prose, so each is exempt by
+// its own recognizable shape rather than forced through a conventional-commit
+// subject and trailers it was never meant to carry.
+const [, , msgPath] = process.argv;
+const message = readFileSync(msgPath, "utf8");
+const subjectLine = message.split("\n", 1)[0] || "";
+if (
+  /^Merge (branch|tag|remote-tracking branch|pull request) /u.test(subjectLine) ||
+  /^Revert "/u.test(subjectLine) ||
+  /^(fixup|squash)! /u.test(subjectLine)
+) process.exit(0);
+
+if (/^${COMMIT_MSG_GUARD_MARKER}:allow\b/mu.test(message)) process.exit(0);
+
+const errors = [];
+
+// Trailers are required only for an AGENT-authored commit: Claude Code sets
+// CLAUDECODE=1 in every shell it spawns (the same harness-detection signal
+// packages/core/src/loop/run-context.mjs's isClaudeHarness checks) — a plain
+// human commit (CLAUDECODE unset) is never "Claude", so requiring a Claude
+// co-author trailer on it would misattribute the commit, not enforce honesty.
+if (process.env.CLAUDECODE === "1") {
+  if (!/^Co-Authored-By:\s*Claude\s+.+\s+<noreply@anthropic\.com>\s*$/imu.test(message)) {
+    errors.push("missing required trailer: Co-Authored-By: Claude <model> <noreply@anthropic.com>");
+  }
+  if (!/^Claude-Session:\s*\S+/imu.test(message)) {
+    errors.push("missing required trailer: Claude-Session: <url>");
+  }
+}
+
+// A genuine "Closes #N" / "Fixes #N" / "Refs #N" reference (optionally a
+// comma/and-joined list, and optionally the trailer colon form "Closes: #N")
+// is allowed and stripped first; any #<digits> left over is a bare non-issue
+// enumeration, which GitHub auto-links to an unrelated issue/PR when
+// rendered.
+const withoutAllowedRefs = message.replace(
+  /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|refs?|references?):?\s+#\d+(?:\s*(?:,|and)\s*#\d+)*/giu,
+  "",
+);
+if (/#\d+/u.test(withoutAllowedRefs)) {
+  errors.push('bare #<digits> reference found; use "Closes #N" / "Fixes #N" / "Refs #N" for a genuine issue reference, or reword a non-issue enumeration (e.g. "defect N")');
+}
+
+if (!/^(feat|fix|chore|docs|test|refactor|revert|perf|style|ci|build)\([^()\n]+\): .+\S/u.test(subjectLine)) {
+  errors.push("subject must be conventional-commit form \"type(scope): summary\" (type one of feat/fix/chore/docs/test/refactor/revert/perf/style/ci/build)");
+}
+
+if (errors.length > 0) {
+  console.error("dev-loops: WORKTREE-COMMIT-MSG-GUARD refuses this commit — contract violation(s):");
+  for (const error of errors) console.error("  - " + error);
+  console.error("  Waiver: add a \"${COMMIT_MSG_WAIVER_MARKER}\" line to the commit message for a deliberate exception.");
+  process.exit(1);
+}
+process.exit(0);
+`;
+}
+
+/**
+ * Install the commit-msg guard into a repository's hook directory. Mirrors
+ * default-branch-guard's install-refusal checks (a caller with an unsafe
+ * `core.hooksPath`, a non-absolute/non-git `gitDir`, or a linked worktree's
+ * OWN gitdir must never report success for a hook that can never fire) and
+ * its atomic write + foreign-hook preservation — duplicated rather than
+ * shared, since it is one hook, not a family; see default-branch-guard.mjs
+ * for the family version if a third hook installer ever needs the same
+ * shape factored out.
+ *
+ * @param {{ gitDir: string, hooksPathOverride?: string|null }} target
+ */
+export function installCommitMsgGuard({ gitDir, hooksPathOverride = null }) {
+  const refuse = (reason) => ({ ok: false, installed: false, refreshed: false, skipped: true, reason });
+
+  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`)
+      : refuse("core.hooksPath is set to an empty string — git runs no hooks at all");
+  }
+  if (typeof gitDir !== "string" || !path.isAbsolute(gitDir)) {
+    return refuse(`gitDir must be an absolute path; got ${JSON.stringify(gitDir)}`);
+  }
+  if (!fs.existsSync(path.join(gitDir, "HEAD"))) {
+    return refuse(`gitDir ${JSON.stringify(gitDir)} does not look like a git directory (no HEAD file)`);
+  }
+  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`);
+  }
+
+  const hooksDir = path.join(gitDir, "hooks");
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, "commit-msg");
+
+  const existing = fs.existsSync(hookPath) ? fs.readFileSync(hookPath, "utf8") : null;
+  const ours = existing === null || GUARD_MARKER_LINE.test(existing);
+  if (!ours) {
+    return { ok: true, installed: false, refreshed: false, skipped: true, reason: "a pre-existing hook is present and was left untouched" };
+  }
+
+  // Same atomic tmp-write + rename as default-branch-guard: the hooks dir is
+  // shared across worktrees, so a direct writeFileSync would be visible
+  // mid-write to a concurrent install or a real commit racing this one.
+  const tmpPath = path.join(hooksDir, `.commit-msg.tmp-${process.pid}-${Date.now()}`);
+  fs.writeFileSync(tmpPath, renderCommitMsgGuardHook(), { mode: 0o755 });
+  fs.chmodSync(tmpPath, 0o755);
+  fs.renameSync(tmpPath, hookPath);
+
+  return { ok: true, installed: existing === null, refreshed: existing !== null, skipped: false };
+}

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

@@ -1,4 +1,5 @@
 import { SUBMITTED_REVIEW_STATES, isCopilotLogin, normalizeTimestamp } from "../github/copilot-helpers.mjs";
+import { trimmedOrNull } from "./normalize.mjs";
 
 const ACTIVE_COPILOT_REVIEW_REQUEST_STATUSES = new Set(["requested", "already-requested"]);
 
@@ -70,7 +71,7 @@ function normalizeCommits(commits) {
       sortKey: index,
       committedAtMs: normalizeTimestamp(commit?.committedAt),
       authorLogin: typeof commit?.authorLogin === "string" ? commit.authorLogin.trim() : "",
-      sha: typeof commit?.sha === "string" && commit.sha.trim().length > 0 ? commit.sha.trim() : null,
+      sha: trimmedOrNull(commit?.sha),
     }))
     .filter((commit) => commit.committedAtMs !== null)
     .sort((left, right) => left.committedAtMs - right.committedAtMs || left.sortKey - right.sortKey);

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

@@ -91,12 +91,45 @@ export function renderGuardHook(hookName, defaultBranches = null, explicitBranch
   }
   const defaults = branches.join(" ");
   const explicitDefaults = explicits.join(" ");
+  // pre-commit ONLY: runs the fail-closed secret scan BEFORE anything else in
+  // this hook — before the override-env check below (that override is a
+  // default-BRANCH escape hatch for a sanctioned release; it must never
+  // double as a secret-scan bypass, there is none) and before the
+  // unresolved-defaults early exit (a secret-scan must never go quiet just
+  // because branch resolution failed at install time). Git always invokes a
+  // hook with the working tree ROOT as its cwd (githooks(5)), so a plain
+  // cwd-relative path here already resolves against each worktree's OWN
+  // checked-out copy of the scanner — no --show-toplevel round trip needed.
+  // A missing scanner file is a checkout that predates this feature (nothing
+  // to run), not a bypass attempt, so it is skipped rather than blocked; a
+  // scanner that IS present and errors, or finds a hit, always blocks — see
+  // scripts/security/scan-staged-diff.mjs. Its stdout carries only the clean
+  // "{ok:true,hits:[]}" success payload (a hit's diagnostics go to STDERR,
+  // per the CLI's own `payload.ok ? stdout : stderr` split above) — silenced
+  // here so a normal commit prints no JSON noise, while a blocked commit's
+  // stderr (file/line/detector-class) still reaches the developer untouched.
+  // Shell var deliberately named "scan_cli" rather than e.g. "secret_scanner":
+  // this repo's own pre-commit hook (below) runs a heuristic sink-pattern
+  // detector that fires on a credential-shaped variable name feeding any
+  // stdout redirect, even one that discards output; naming it around a
+  // scanner CLI path rather than a credential keeps this file's own diff
+  // clean through its own hook.
+  const secretScanBlock = hookName === "pre-commit"
+    ? `scan_cli="scripts/security/scan-staged-diff.mjs"
+if [ -f "$scan_cli" ]; then
+  node "$scan_cli" >/dev/null
+  if [ "$?" != "0" ]; then
+    exit 1
+  fi
+fi
+`
+    : "";
   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
+${secretScanBlock}if [ "\${${GUARD_OVERRIDE_ENV}}" = "1" ]; then
   exit 0
 fi
 defaults="${defaults}"

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

@@ -57,7 +57,10 @@ import { ALWAYS_INCLUDE, CATEGORY_ANGLE_MAP } from "../analysis/change-classifie
  * @type {Record<string, string[]>}
  */
 const KIND_TO_CATEGORIES = {
-  docs: ["DOCS_ONLY"],
+  // #1442: a docs file is PROSE_PRESENT when it lands on the prose surface, so
+  // deslop's carry-forward surface is the `docs` kind (a non-docs delta never
+  // re-runs a clean deslop verdict).
+  docs: ["DOCS_ONLY", "PROSE_PRESENT"],
   config: ["CONFIG_ONLY"],
   test: ["TEST_ONLY"],
   ci: ["CI_ONLY"],
@@ -108,6 +111,14 @@ const ANGLE_SURFACE_KINDS = (() => {
 
 /**
  * Resolve an angle's declared review surface (the pure angle -> surface mapping).
+ * `angle` is matched trim+lowercase against ALL THREE lookups below (the
+ * hardcoded ALWAYS_INCLUDE set, the caller-supplied `alwaysRerun` set, and the
+ * `kinds` map) — deliberately: this makes a case/whitespace-drifted name (e.g.
+ * "Correctness", "PR-Description") resolve the SAME surface as its canonical
+ * form, rather than falling through to `{ kind: "unknown" }`. That is a
+ * decision-affecting default: a case-drifted MAPPED angle now becomes
+ * carry-forward-eligible (via `resolveAngleCarryForward`) where an unnormalized
+ * lookup would have fail-closed it as unknown.
  *
  * - ALWAYS_INCLUDE angles (gate-evidence, renderer-security, pr-description) plus
  *   any explicit alwaysRerun angle -> `{ kind: "always" }`. These review a surface
@@ -122,15 +133,17 @@ const ANGLE_SURFACE_KINDS = (() => {
  * @returns {AngleReviewSurface}
  */
 export function angleReviewSurface(angle, { alwaysRerun } = {}) {
-  const name = typeof angle === "string" ? angle.trim() : "";
+  // Normalized ONCE here (trim+lowercase) so every caller — the hardcoded
+  // ALWAYS_INCLUDE check below, the configured alwaysRerun match, and the
+  // kinds lookup — agrees on one predicate regardless of whether the caller
+  // pre-lowercases (consolidate-fanin.mjs does; write-gate-context.mjs's
+  // mandatory-angle refusal does not, and must not have to).
+  const name = typeof angle === "string" ? angle.trim().toLowerCase() : "";
   if (name.length === 0) return { kind: "unknown" };
   if (ALWAYS_INCLUDE.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" };
+    if (normalized.has(name)) return { kind: "always" };
   }
   const kinds = ANGLE_SURFACE_KINDS.get(name);
   if (!kinds || kinds.size === 0) return { kind: "unknown" };