dev-loops 0.5.0 → 0.7.1

package/scripts/claude/generate-claude-assets.mjs

@@ -14,7 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { transformAgent, transformSkill, stripPiOnlyBlocks } from "@dev-loops/core/claude/asset-generation";
+import { transformAgent, transformSkill, transformCommand, stripPiOnlyBlocks } from "@dev-loops/core/claude/asset-generation";
 
 /**
  * Collect the generated assets as { target, content } pairs (target is repo-relative).
@@ -45,6 +45,19 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
     }
   }
 
+  // Direct slash commands (#972): thin generated wrappers over the public dev-loop contract,
+  // one `.claude/commands/<name>.md` per `commands/<name>.command.md` source. No routing logic.
+  const commandsDir = path.join(repoRoot, "commands");
+  if (fs.existsSync(commandsDir)) {
+    for (const entry of fs.readdirSync(commandsDir).sort()) {
+      if (!entry.endsWith(".command.md")) continue;
+      const source = `commands/${entry}`;
+      const raw = fs.readFileSync(path.join(repoRoot, source), "utf8");
+      const base = entry.slice(0, -".command.md".length);
+      assets.push({ target: `.claude/commands/${base}.md`, content: transformCommand({ source, raw, version }) });
+    }
+  }
+
   const skillsDir = path.join(repoRoot, "skills");
   if (fs.existsSync(skillsDir)) {
     for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -171,6 +184,7 @@ function listFilesRecursive(repoRoot, rel) {
 function listExistingAssetFiles(repoRoot) {
   const files = [
     ...listFilesRecursive(repoRoot, ".claude/agents"),
+    ...listFilesRecursive(repoRoot, ".claude/commands"),
     ...listFilesRecursive(repoRoot, ".claude/skills"),
   ];
   // `.claude/hooks/` mixes hand-authored scripts (hooks.json, _hook-io.mjs, the three hook

package/scripts/github/capture-review-threads.mjs

@@ -11,7 +11,7 @@ import {
 import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 export const REVIEW_THREADS_QUERY = [
   "query($owner: String!, $name: String!, $pr: Int!) {",
   "  repository(owner: $owner, name: $name) {",
@@ -103,14 +103,7 @@ export function parseCaptureCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token));
       continue;
     }
-    if (token.name === "jq") {
-      options.jq = requireTokenValue(token);
-      continue;
-    }
-    if (token.name === "silent") {
-      options.silent = true;
-      continue;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t))) continue;
     throw new Error(`Unknown argument: ${token.rawName}`);
   }
   const hasLiveArgs = options.repo !== undefined || options.pr !== undefined;

package/scripts/github/comment-issue.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage: comment-issue.mjs --repo <owner/name> --issue <number> (--body <text> | --body-file <path>)
+Post a comment on a GitHub issue. Thin wrapper over \`gh issue comment\` — use this
+instead of an agent-level raw \`gh issue comment\` so the loop's internal-tooling
+record stays clean (#993; the read-side siblings are list-issues.mjs / fetch-ci-logs.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --issue <number>              Issue number to comment on
+  --body <text>                 Comment body as a single argument
+  --body-file <path>            Read the comment body from a file (preserves
+                                newlines; alternative to --body; - reads stdin)
+Output (stdout, JSON):
+  { "ok": true, "repo": "owner/repo", "issue": 17, "commentUrl": "https://github.com/owner/repo/issues/17#issuecomment-123" }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseCommentIssueCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      body: { type: "string" },
+      "body-file": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    issue: undefined,
+    body: undefined,
+    bodyFile: undefined,
+    jq: undefined,
+    silent: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "body") {
+      options.body = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "body-file") {
+      const rawPath = requireTokenValue(token, parseError).trim();
+      if (rawPath.length === 0) {
+        throw parseError("--body-file must be a non-empty path");
+      }
+      options.bodyFile = rawPath;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined || options.issue === undefined) {
+    throw parseError("Commenting on an issue requires both --repo <owner/name> and --issue <number>");
+  }
+  if (options.body === undefined && options.bodyFile === undefined) {
+    throw parseError("Commenting on an issue requires --body <text> or --body-file <path>");
+  }
+  if (options.body !== undefined && options.bodyFile !== undefined) {
+    throw parseError("--body and --body-file are mutually exclusive; pass only one");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+async function resolveBody(options) {
+  if (options.bodyFile === undefined) {
+    if (options.body.trim().length === 0) {
+      throw new Error("--body must not be empty");
+    }
+    return options.body;
+  }
+  const source = options.bodyFile === "-" ? 0 : options.bodyFile;
+  const body = await readFile(source, "utf8");
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+// Post the comment via `gh issue comment`, then read its URL back from
+// `gh issue comment` output. `gh issue comment` prints the new comment URL on
+// success — capture it so callers don't need a follow-up read.
+export async function commentIssue(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const body = await resolveBody(options);
+  const result = await run(
+    ghCommand,
+    ["issue", "comment", String(options.issue), "--repo", options.repo, "--body", body],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue comment failed: ${detail}`);
+  }
+  // `gh issue comment` prints the created comment's URL (the last non-empty line
+  // of stdout). Surface it so the caller has the comment URL without a re-read.
+  const commentUrl = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .pop() ?? null;
+  if (commentUrl === null || !/^https?:\/\//u.test(commentUrl)) {
+    throw new Error(`gh issue comment did not return a comment URL (got: ${result.stdout.trim() || "<empty>"})`);
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, commentUrl };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseCommentIssueCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await commentIssue(options, { env, ghCommand, run });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}

package/scripts/github/create-label.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage: create-label.mjs --repo <owner/name> --name <label> [--color <hex>] [--description <text>] [--force]
+Create (or idempotently reuse) a GitHub label. Thin wrapper over \`gh label create\`
+— use this instead of an agent-level raw \`gh label create\` so the loop's
+internal-tooling record stays clean (siblings: comment-issue.mjs, edit-pr.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --name <label>                Label name to create
+Optional:
+  --color <hex>                 Hex color without '#' (default: d73a4a)
+  --description <text>          Label description
+  --force                       Update the label if it already exists
+Output (stdout, JSON):
+  { "ok": true, "created": true, "name": "gate:full", "color": "d73a4a", "repo": "owner/repo" }
+  { "ok": true, "created": false, "alreadyExists": true, "name": "gate:full" }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success (created or already exists)
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseCreateLabelCliArgs(argv) {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      name: { type: "string" },
+      color: { type: "string" },
+      description: { type: "string" },
+      force: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: false,
+    strict: false,
+  });
+  if (values.help) {
+    return { help: true };
+  }
+  const repo = typeof values.repo === "string" ? values.repo.trim() : undefined;
+  const name = typeof values.name === "string" ? values.name.trim() : undefined;
+  if (!repo || !name) {
+    throw parseError("Creating a label requires both --repo <owner/name> and --name <label>");
+  }
+  try {
+    parseRepoSlug(repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  const color = typeof values.color === "string" && values.color.trim().length > 0 ? values.color.trim() : "d73a4a";
+  const description =
+    typeof values.description === "string" && values.description.length > 0 ? values.description : undefined;
+  return {
+    help: false,
+    repo,
+    name,
+    color,
+    description,
+    force: values.force === true,
+    jq: values.jq,
+    silent: values.silent === true,
+  };
+}
+
+// Pure: assemble the `gh label create` argv. Exported so the arg shape can be
+// tested without spawning gh.
+export function buildLabelArgs({ repo, name, color, description, force }) {
+  const args = ["label", "create", name, "--repo", repo, "--color", color];
+  if (description !== undefined) {
+    args.push("--description", description);
+  }
+  if (force) {
+    args.push("--force");
+  }
+  return args;
+}
+
+export function createLabel(options, { ghCommand = "gh", exec = execFileSync } = {}) {
+  const args = buildLabelArgs(options);
+  try {
+    exec(ghCommand, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    const stderr = typeof error?.stderr === "string" ? error.stderr : String(error?.stderr ?? "");
+    // Without --force, gh errors if the label exists. Treat that as idempotent
+    // success so re-runs are safe; any other failure propagates.
+    if (!options.force && /already exists/i.test(stderr)) {
+      return { ok: true, created: false, alreadyExists: true, name: options.name };
+    }
+    const detail = stderr.trim() || (error instanceof Error ? error.message : String(error));
+    throw new Error(`gh label create failed: ${detail}`);
+  }
+  return { ok: true, created: true, name: options.name, color: options.color, repo: options.repo };
+}
+
+export function run(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, ghCommand = "gh", exec = execFileSync } = {},
+) {
+  let options;
+  try {
+    options = parseCreateLabelCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = createLabel(options, { ghCommand, exec });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+export const main = run;
+
+if (isDirectCliRun(import.meta.url)) {
+  process.exitCode = run();
+}

package/scripts/github/detect-checkpoint-evidence.mjs

@@ -9,15 +9,19 @@ import {
   summarizeGateReviewCommentMarkers,
   summarizeGateReviewComments,
 } from "../_core-helpers.mjs";
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
-import { loadDevLoopConfig, resolveGateConfig, resolveRequireFanoutEvidence } from "@dev-loops/core/config";
+import { FANOUT_PROVENANCE_MIN_REVIEWERS, GATE_FULL_LABEL, loadDevLoopConfig, resolveGateConfig, resolveLightMode, resolveRequireFanoutEvidence, resolveRequireFanoutProvenance } from "@dev-loops/core/config";
+import { FANOUT_UNAVAILABLE_MESSAGE, provenanceConsistencyError } from "@dev-loops/core/loop/gate-fanin";
+import { detectMergeBaseScope, isEligibleForLightMode } from "../loop/detect-change-scope.mjs";
 import { buildLogPath } from "./write-gate-findings-log.mjs";
 import { ensureAsyncRunnerOwnership } from "../loop/_pr-runner-coordination.mjs";
 import { detectStaleRunner } from "../loop/_stale-runner-detection.mjs";
+import { resolveLedgerCheckouts, resolveRepoRoot } from "../loop/_repo-root-resolver.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: detect-checkpoint-evidence.mjs --repo <owner/name> --pr <number>
 Fetch the live PR head SHA and visible PR issue comments, then summarize the
 latest valid draft-gate and pre-approval checkpoint verdict comments. Always fail
@@ -84,9 +88,11 @@ Output (stdout, JSON; always includes preMergeGateCheck):
 Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
   { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success (gate evidence is valid)
-  1  Argument error, gh failure, malformed gh JSON, or missing required pre-merge gate evidence.`.trim();
+  1  Argument error, gh failure, malformed gh JSON, or missing required pre-merge gate evidence.
+  2  Invalid --jq filter.`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectCheckpointEvidenceCliArgs(argv) {
   const { tokens } = parseArgs({
@@ -96,6 +102,7 @@ export function parseDetectCheckpointEvidenceCliArgs(argv) {
       repo: { type: "string" },
       pr: { type: "string" },
       "require-before-merge": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -125,6 +132,7 @@ export function parseDetectCheckpointEvidenceCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     if (token.name === "require-before-merge") {
       throw parseError(`--require-before-merge has been removed: gate evidence enforcement is now always-on by default. Omit the flag.`);
     }
@@ -249,7 +257,24 @@ export function buildPreMergeGateCheck(evidence, unresolvedThreadCount = null, s
   // { required: false, gates: [] } so the `.required` guard skips this block.
   if (fanoutEnforcement && fanoutEnforcement.required) {
     for (const gate of fanoutEnforcement.gates) {
-      if (gate.executionMode !== "fanout_fanin") {
+      // Light-mode acceptance (#1174): a genuinely under-threshold micro-PR
+      // collapses the gate fan-out to a single inline check (#1043). Accept that
+      // inline verdict ONLY when ALL hold, fail CLOSED otherwise:
+      //   - lightMode is enabled in config, AND
+      //   - the reviewed head's merge-base scope was RE-DERIVED under threshold
+      //     (scopeUnderThreshold; false whenever scope could not be derived), AND
+      //   - the PR carries no gate:full label (which always forces fan-out), AND
+      //   - the verdict records a non-empty inline reason.
+      // Any non-light inline verdict (over threshold / label / lightMode off /
+      // scope underivable) falls through to the byte-identical rejection below.
+      const lightAccepted =
+        gate.executionMode === "inline_single_agent"
+        && fanoutEnforcement.lightMode === true
+        && fanoutEnforcement.hasFullLabel !== true
+        && gate.scopeUnderThreshold === true
+        && typeof gate.inlineReason === "string"
+        && gate.inlineReason.trim().length > 0;
+      if (gate.executionMode !== "fanout_fanin" && !lightAccepted) {
         failures.push(
           `${gate.name}: requireFanoutEvidence is enabled but executionMode is "${gate.executionMode ?? "unset"}" (expected "fanout_fanin"); inline gate verdicts are not accepted`,
         );
@@ -259,6 +284,31 @@ export function buildPreMergeGateCheck(evidence, unresolvedThreadCount = null, s
         failures.push(
           `${gate.name}: requireFanoutEvidence is enabled but no findings-log ledger exists for the reviewed head (${gate.ledgerPath})`,
         );
+        continue;
+      }
+      // Opt-in provenance enforcement (gates.requireFanoutProvenance), layered on
+      // top of fan-out evidence. When off (default) requireProvenance is falsy so
+      // NO new failure is added — behavior is byte-identical to today. When on, a
+      // fanout_fanin ledger must record INTERNALLY-CONSISTENT provenance (checked
+      // the same way the write path validates it — a hand-edited or shadow ledger
+      // is re-validated here, not trusted) with distinctReviewers >= the floor.
+      // Provenance is enforced ONLY for fanout_fanin verdicts (#1174): a
+      // light-accepted inline verdict is already scope-bounded and has no
+      // multi-reviewer provenance to record, so requiring it would make the
+      // light path unmergeable — the inverse of this issue's fix.
+      if (fanoutEnforcement.requireProvenance && gate.executionMode === "fanout_fanin") {
+        const prov = gate.provenance;
+        const consistencyErr = provenanceConsistencyError(prov);
+        const reviewers = prov && Number.isInteger(prov.distinctReviewers) ? prov.distinctReviewers : null;
+        if (consistencyErr) {
+          failures.push(
+            `${gate.name}: requireFanoutProvenance is enabled but the findings-log ledger lacks valid fan-out provenance (${consistencyErr}); ${FANOUT_UNAVAILABLE_MESSAGE}`,
+          );
+        } else if (reviewers === null || reviewers < FANOUT_PROVENANCE_MIN_REVIEWERS) {
+          failures.push(
+            `${gate.name}: requireFanoutProvenance is enabled but the findings-log ledger lacks valid fan-out provenance (need provenance.distinctReviewers >= ${FANOUT_PROVENANCE_MIN_REVIEWERS}, got ${reviewers === null ? "none" : reviewers}); ${FANOUT_UNAVAILABLE_MESSAGE}`,
+          );
+        }
       }
     }
   }
@@ -287,24 +337,88 @@ async function ledgerExists(fullPath) {
     return false;
   }
 }
+/**
+ * True if the ledger (relative path) exists under ANY enumerated checkout
+ * (main + every worktree). Fixes #1050: a ledger written in the PR worktree is
+ * found even when the check runs from a different checkout's git-toplevel.
+ */
+async function ledgerExistsInAny(checkouts, ledgerPath) {
+  for (const root of checkouts) {
+    if (await ledgerExists(path.resolve(root, ledgerPath))) {
+      return true;
+    }
+  }
+  return false;
+}
+/**
+ * Read the recorded fan-out `provenance` object from a ledger across the
+ * enumerated checkouts. Mirrors ledgerExistsInAny's "ANY checkout satisfies"
+ * semantics: prefers the FIRST checkout whose ledger provenance actually
+ * SATISFIES enforcement (internally consistent AND distinctReviewers >= floor),
+ * so a below-floor or provenance-less ledger in an earlier-enumerated checkout
+ * cannot SHADOW a valid one in the PR worktree (which would falsely fail closed).
+ * Falls back to the first non-null provenance (for a useful diagnostic message)
+ * only when NO checkout satisfies, and null only when none is present. Only
+ * called when requireFanoutProvenance is enabled so the default path pays no I/O.
+ */
+async function readLedgerProvenanceInAny(checkouts, ledgerPath) {
+  let firstNonNull = null;
+  for (const root of checkouts) {
+    const full = path.resolve(root, ledgerPath);
+    try {
+      const parsed = JSON.parse(await readFile(full, "utf8"));
+      const prov = parsed && typeof parsed === "object" ? parsed.provenance : null;
+      if (prov == null) continue; // ledger present but no provenance — keep scanning.
+      if (provenanceConsistencyError(prov) === null && prov.distinctReviewers >= FANOUT_PROVENANCE_MIN_REVIEWERS) {
+        return prov; // satisfying ledger — prefer it over any earlier below-floor one.
+      }
+      if (firstNonNull === null) firstNonNull = prov; // remember for diagnostics.
+    } catch {
+      // Missing/unreadable/malformed ledger in this checkout — try the next.
+    }
+  }
+  return firstNonNull;
+}
 /**
  * Build the fan-out evidence enforcement descriptor.
  *
  * Enforcement is ON by default (opt-out via gates.requireFanoutEvidence: false).
  * Returns { required: false } when enforcement is disabled OR when config is
  * unavailable (config == null — null or undefined — after a failed load) — config-unavailable must
- * fail open and never enable enforcement. When enabled, records per-required-gate
- * executionMode and whether the deterministic findings-log ledger exists for the
- * reviewed head SHA so the pre-merge check can fail closed on inline verdicts or
- * missing ledgers.
+ * fail open and never enable enforcement. When enabled, returns
+ * { required: true, requireProvenance, lightMode, hasFullLabel, gates } where
+ * each per-required-gate entry records executionMode, inlineReason,
+ * scopeUnderThreshold, and whether the deterministic findings-log ledger exists
+ * for the reviewed head SHA, so the pre-merge check can fail closed on inline
+ * verdicts or missing ledgers.
+ *
+ * Light mode (#1174): when gates.lightMode is configured, `hasFullLabel`
+ * (gate:full PR label) and `baseRef` feed a fail-closed merge-base scope
+ * re-derivation for inline verdicts. A gate's scopeUnderThreshold is true only
+ * when light mode is on, the PR has no gate:full label, a base ref is known,
+ * and the reviewed head's merge-base diff is genuinely under threshold — which
+ * lets the pre-merge check accept an inline single-agent verdict for a
+ * small-scope PR instead of always rejecting inline evidence.
  */
-async function buildFanoutEnforcement({ repo, pr, currentHeadSha, draftGateMarker, preApprovalGateMarker, config, cwd }) {
+export async function buildFanoutEnforcement({ repo, pr, currentHeadSha, draftGateMarker, preApprovalGateMarker, config, cwd, hasFullLabel = false, baseRef = null }) {
   // Fail open when config could not be loaded/validated. `== null` covers both
   // null and undefined; the loader only ever yields null on failure, but the
   // loose check defensively treats an absent config as unavailable.
   if (config == null || !resolveRequireFanoutEvidence(config)) {
+    // Disabled/unavailable return is intentionally byte-identical to before
+    // (no requireProvenance key): buildPreMergeGateCheck only reads it inside
+    // the `required` block, so this preserves the exact existing shape.
     return { required: false, gates: [] };
   }
+  // Provenance enforcement is opt-in and layered ON TOP of fan-out evidence: it
+  // only takes effect while evidence enforcement (above) is active.
+  const requireProvenance = resolveRequireFanoutProvenance(config);
+  // Light-mode facts (#1174): the threshold that a re-derived merge-base scope
+  // must fall under for an inline verdict to be accepted. null when lightMode is
+  // disabled → no inline verdict can ever be accepted (scopeUnderThreshold stays
+  // false), preserving today's rejection.
+  const lightThreshold = resolveLightMode(config);
+  const lightMode = lightThreshold != null;
   const draftRequired = resolveGateConfig(config, "draft").required;
   const preApprovalRequired = resolveGateConfig(config, "preApproval").required;
   const gateSpecs = [
@@ -312,18 +426,35 @@ async function buildFanoutEnforcement({ repo, pr, currentHeadSha, draftGateMarke
     { name: "pre_approval_gate", marker: preApprovalGateMarker, required: preApprovalRequired },
   ].filter((spec) => spec.required && spec.marker.visible);
   const gates = [];
+  const checkouts = resolveLedgerCheckouts(cwd);
+  // checkouts[0] is always resolveRepoRoot(cwd) (resolveLedgerCheckouts adds it
+  // first, unconditionally, and never throws — it falls back to cwd on git
+  // failure) — reuse it instead of a second `git rev-parse --show-toplevel`.
+  const repoRoot = checkouts[0];
   for (const spec of gateSpecs) {
     const headSha = spec.marker.headSha ?? currentHeadSha;
     const ledgerPath = buildLogPath({ repo, pr, gate: spec.name, headSha, tmpRoot: "tmp" });
-    const fullPath = path.resolve(cwd, ledgerPath);
+    // Re-derive scope FAIL-CLOSED for inline verdicts only (the fan-out default
+    // path pays no git I/O). scopeUnderThreshold is true ONLY when lightMode is
+    // on, the PR has no gate:full label, a base ref is known, and the merge-base
+    // diff for the reviewed head is genuinely under threshold. Any git/scope
+    // failure leaves it false, so the inline verdict is rejected exactly as today.
+    let scopeUnderThreshold = false;
+    if (lightMode && !hasFullLabel && baseRef && spec.marker.executionMode === "inline_single_agent") {
+      const scope = detectMergeBaseScope({ base: baseRef, head: headSha, cwd: repoRoot });
+      scopeUnderThreshold = scope.ok === true && isEligibleForLightMode(scope, lightThreshold);
+    }
     gates.push({
       name: spec.name,
       executionMode: spec.marker.executionMode ?? null,
+      inlineReason: spec.marker.inlineReason ?? null,
+      scopeUnderThreshold,
       ledgerPath,
-      ledgerExists: await ledgerExists(fullPath),
+      ledgerExists: await ledgerExistsInAny(checkouts, ledgerPath),
+      provenance: requireProvenance ? await readLedgerProvenanceInAny(checkouts, ledgerPath) : null,
     });
   }
-  return { required: true, gates };
+  return { required: true, requireProvenance, lightMode, hasFullLabel, gates };
 }
 export async function detectCheckpointEvidence(options, { env = process.env, ghCommand = "gh", cwd = process.cwd() } = {}) {
   const runnerOwnership = await ensureAsyncRunnerOwnership({
@@ -378,8 +509,31 @@ export async function detectCheckpointEvidence(options, { env = process.env, ghC
   // treat it as config-unavailable and leave fan-out enforcement disabled
   // (preserves default behavior). Other gate checks remain unaffected.
   let config = null;
-  const { config: loadedConfig, errors: configErrors } = await loadDevLoopConfig({ repoRoot: cwd });
+  const { config: loadedConfig, errors: configErrors } = await loadDevLoopConfig({ repoRoot: resolveRepoRoot(cwd) });
   config = Array.isArray(configErrors) && configErrors.length > 0 ? null : loadedConfig;
+  // Light-mode pre-merge facts (#1174): the base commit for the merge-base scope
+  // re-derivation and whether the PR forces full fan-out via the gate:full label.
+  // Fetched LAZILY — only when fan-out enforcement is active AND lightMode is on
+  // AND a gate actually recorded an inline verdict — so the common fan-out path
+  // (and every existing caller/test) makes NO extra gh call and stays unchanged.
+  let baseRef = null;
+  let hasFullLabel = false;
+  const anyInlineVerdict = [draftGateMarker, preApprovalGateMarker].some(
+    (marker) => marker.visible && marker.executionMode === "inline_single_agent",
+  );
+  if (config != null && resolveRequireFanoutEvidence(config) && resolveLightMode(config) != null && anyInlineVerdict) {
+    try {
+      const lightFacts = await runGhJson(["pr", "view", String(options.pr), "--repo", options.repo, "--json", "baseRefOid,labels"], { env, ghCommand });
+      baseRef = typeof lightFacts?.baseRefOid === "string" && lightFacts.baseRefOid.trim().length > 0
+        ? lightFacts.baseRefOid.trim()
+        : null;
+      hasFullLabel = Array.isArray(lightFacts?.labels)
+        && lightFacts.labels.some((label) => (typeof label === "string" ? label : label?.name) === GATE_FULL_LABEL);
+    } catch {
+      // Fail CLOSED: without the label/base facts we cannot safely accept an
+      // inline verdict, so leave baseRef null (scope underivable → rejected).
+    }
+  }
   const fanoutEnforcement = await buildFanoutEnforcement({
     repo: options.repo,
     pr: options.pr,
@@ -388,6 +542,8 @@ export async function detectCheckpointEvidence(options, { env = process.env, ghC
     preApprovalGateMarker,
     config,
     cwd,
+    hasFullLabel,
+    baseRef,
   });
   return {
     ok: true,
@@ -458,7 +614,7 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    process.stdout.write(`${JSON.stringify(output)}\n`);
+    process.exitCode = emitResult(output, { jq: options.jq, silent: options.silent });
   } catch (error) {
     if (error && typeof error === "object" && "staleRunner" in error && error.staleRunner) {
       const staleRunnerCheck = {