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

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/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" };