dev-loops 0.7.1 → 0.8.0

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -10,12 +10,13 @@ import {
   resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
 } from "../_core-helpers.mjs";
-import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
-import { loadDevLoopConfig, resolveGateConfig, resolveRefinement, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { parsePrNumber, requireTokenValue, runChild as defaultRunChild } from "../_cli-primitives.mjs";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveGateConfig, resolveRefinement, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState, isCopilotRoundCapReached, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
-import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
+import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION, REFINEMENT_ARTIFACT_SPEC_SOURCE } from "@dev-loops/core/loop/pr-gate-coordination";
 import { shouldGuardCopilotReviewRequest } from "@dev-loops/core/loop/pr-gate-coordination";
+import { PLAN_FILE_PROMOTION_DOC_PATH_PATTERN } from "@dev-loops/core/loop/plan-file-promote-contract";
 import { UI_E2E_CHECK_NAMES } from "@dev-loops/core/loop/ui-e2e-scoping";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { detectPostConvergenceSignificantChange } from "./_post-convergence-change.mjs";
@@ -30,6 +31,12 @@ Required:
   --repo <owner/name>   Repository slug (e.g. owner/repo)
   --pr <number>         Pull request number
 Optional:
+  --lightweight   This PR is light-dispatched (#1210): compose the Copilot
+                  round cap with localImplementation.lightMode.maxCopilotRounds
+                  (default 1) via min(lightMode.maxCopilotRounds,
+                  refinement.maxCopilotRounds) instead of using
+                  refinement.maxCopilotRounds alone. refinement.maxCopilotRounds:
+                  0 still disables Copilot rounds even with --lightweight.
 Output (stdout, JSON):
   {
     "ok": true,
@@ -61,11 +68,19 @@ Output (stdout, JSON):
       "headSha": null,
       "verdict": null
     },
+    "refinementArtifact": {
+      "status": "present",
+      "specSource": "linked_issue",
+      "reason": "...",
+      "finding": null
+    },
     "allowedNextActions": ["resolve_merge_conflicts"],
     "forbiddenActions": ["run_pre_approval_gate", "declare_merge_ready"],
     "nextAction": "resolve_merge_conflicts",
     "reason": "..."
   }
+  (refinementArtifact.planDocPath is present only when specSource is
+  "plan_file"; the key is omitted entirely for "linked_issue" and "pr_body")
 Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
   { "ok": false, "error": "..." }
@@ -80,6 +95,7 @@ export function parseDetectPrGateCoordinationCliArgs(argv) {
     help: false,
     repo: undefined,
     pr: undefined,
+    lightweight: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -87,6 +103,7 @@ export function parseDetectPrGateCoordinationCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       pr: { type: "string" },
+      lightweight: { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -112,6 +129,10 @@ export function parseDetectPrGateCoordinationCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
     if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
@@ -155,7 +176,7 @@ export function parseGitStatusConflictFiles(text) {
   }
   return conflictFiles;
 }
-async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/pulls/${pr}/requested_reviewers`],
@@ -167,7 +188,7 @@ async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghComm
   }
   return parseRequestedReviewersPayload(result.stdout);
 }
-async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeable,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup,files"],
@@ -190,18 +211,19 @@ export async function fetchPrFactsWithSettledMergeable(
   {
     env = process.env,
     ghCommand = "gh",
+    runChild = defaultRunChild,
     maxPolls = 3,
     pollDelayMs = 1500,
     sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
     fetch = fetchPrFacts,
   } = {},
 ) {
-  let prData = await fetch(options, { env, ghCommand });
+  let prData = await fetch(options, { env, ghCommand, runChild });
   let polls = 0;
   while (String(prData?.mergeable || "").toUpperCase() === "UNKNOWN" && polls < maxPolls) {
     polls += 1;
     await sleep(pollDelayMs);
-    prData = await fetch(options, { env, ghCommand });
+    prData = await fetch(options, { env, ghCommand, runChild });
   }
   return prData;
 }
@@ -259,7 +281,7 @@ export function resolveLinkedIssuesFromPr(prData) {
   return dedupe(matches.map((m) => Number((/(\d+)/.exec(m) || [])[1])));
 }
 
-async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["issue", "view", String(issue), "--repo", repo, "--json", "body"],
@@ -275,18 +297,107 @@ async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand =
     return null;
   }
 }
-export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed, prMerged }, { env = process.env, ghCommand = "gh" } = {}) {
-  const linkedIssues = resolveLinkedIssuesFromPr(prData);
-  if (linkedIssues.length === 0) {
-    if (prDraft) {
+// Plan-file promotion PRs (P4, `buildPromotionPrBody`) carry no linked issue by
+// design; the PR body instead names the committed plan doc as the spec-of-record
+// verbatim (marker owned by plan-file-promote-contract.mjs). Matching that
+// literal marker is how the refinement check tells a promoted plan-file PR
+// apart from an ordinary issue-less body.
+
+// Resolve the refinement artifact for a draft PR with zero linked issues,
+// directly from its own body. The sanctioned three-origin model
+// (artifact-authority-contract.md) backs a draft PR with a linked issue, a
+// promoted plan file, or the PR body itself as the spec-of-record; only the
+// first fetches an issue body, so this never needs a network call.
+// `specSource` here (linked_issue|pr_body|plan_file) is a distinct enum from
+// handoff-envelope.mjs's CANONICAL_SPEC_SOURCE (phase_doc|pr_body): same field
+// name, different object, different value space — never conflate the two.
+async function resolveNoIssueRefinementArtifact(body) {
+  const { detectIssueRefinementArtifact, validatePrBodySpec } = await import("@dev-loops/core/loop/issue-refinement-artifact");
+  const planDocMatch = PLAN_FILE_PROMOTION_DOC_PATH_PATTERN.exec(body);
+  if (planDocMatch) {
+    const planDocPath = planDocMatch[1].trim();
+    // The marker sentence alone is spoofable (any body can paste it): require the
+    // body to still carry real AC/DoD checklist content, the same invariant
+    // `buildPromotionPrBody` actually embeds, before trusting the plan-file claim.
+    // Deliberately narrower than `artifact.hasACs`: that flag also turns true on a
+    // bare linked-refinement-doc mention (no checklist items at all), which is the
+    // right OR for a linked ISSUE body but not for a plan-file promotion PR body —
+    // a plan-file claim must be backed by actual AC/DoD checklist items, not just
+    // another doc mention next to the marker.
+    // Plan-file promotion is issue-less by design (`buildPromotionPrBody`
+    // neutralizes closing keywords): any closing reference the body carries —
+    // including the cross-repo `owner/repo#N` form validatePrBodySpec also
+    // accepts — means the body would auto-close an issue it doesn't actually
+    // back. Reuse validatePrBodySpec's closing-reference extraction
+    // (issueLess mode's `closesIssues`) instead of a second regex.
+    const closesIssues = validatePrBodySpec({ body, issueLess: true }).closesIssues;
+    if (closesIssues.length > 0) {
       return {
         status: "missing",
         linkedIssue: null,
         linkedIssues: [],
-        reason: "Draft PR has no deterministically resolvable linked issue (no closingIssuesReferences and no Closes/Fixes/Resolves #n reference in body); draft gate cannot verify a refinement artifact.",
+        specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PLAN_FILE,
+        planDocPath,
+        reason: `PR body names the promoted plan doc \`${planDocPath}\` as the spec-of-record but also carries a GitHub closing reference (${closesIssues.map((n) => `#${n}`).join(", ")}); plan-file promotion is issue-less by design and must not carry a reference that would auto-close an issue it doesn't back.`,
         finding: "missing_refinement_artifact",
       };
     }
+    const artifact = detectIssueRefinementArtifact({ body });
+    if (artifact.acItems.length > 0 || artifact.dodItems.length > 0) {
+      return {
+        status: "present",
+        linkedIssue: null,
+        linkedIssues: [],
+        specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PLAN_FILE,
+        planDocPath,
+        acItems: artifact.acItems,
+        dodItems: artifact.dodItems,
+        sections: artifact.sections,
+        reason: `Refinement artifact present via the promoted plan doc \`${planDocPath}\` the PR body carries as the spec-of-record (plan-file promotion; no linked issue required).`,
+        finding: null,
+      };
+    }
+    return {
+      status: "missing",
+      linkedIssue: null,
+      linkedIssues: [],
+      specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PLAN_FILE,
+      planDocPath,
+      reason: `PR body names the promoted plan doc \`${planDocPath}\` as the spec-of-record but carries no Acceptance criteria / DoD checklist content (${artifact.reason}); a bare marker sentence cannot satisfy the refinement check.`,
+      finding: "missing_refinement_artifact",
+    };
+  }
+  const specResult = validatePrBodySpec({ body, issueLess: true });
+  if (specResult.ok) {
+    return {
+      status: "present",
+      linkedIssue: null,
+      linkedIssues: [],
+      specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PR_BODY,
+      acItems: specResult.acItems,
+      dodItems: specResult.dodItems,
+      sections: specResult.sections,
+      reason: "Refinement artifact present via the PR body itself (issue-less lightweight PR-body-as-spec; validate-pr-body-spec --no-issue clean).",
+      finding: null,
+    };
+  }
+  return {
+    status: "missing",
+    linkedIssue: null,
+    linkedIssues: [],
+    specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.PR_BODY,
+    reason: `PR body fails the issue-less lightweight spec-of-record validation (validate-pr-body-spec --no-issue: ${specResult.errors.map((e) => e.code).join(", ")}).`,
+    finding: "missing_refinement_artifact",
+  };
+}
+
+export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed, prMerged }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
+  const linkedIssues = resolveLinkedIssuesFromPr(prData);
+  if (linkedIssues.length === 0) {
+    if (prDraft) {
+      const body = typeof prData?.body === "string" ? prData.body : "";
+      return resolveNoIssueRefinementArtifact(body);
+    }
     return {
       status: "unknown",
       linkedIssue: null,
@@ -308,7 +419,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
   // is refined if AT LEAST ONE linked issue carries a refinement artifact.
   const evaluated = [];
   for (const issue of linkedIssues) {
-    const body = await fetchIssueBody({ repo, issue }, { env, ghCommand });
+    const body = await fetchIssueBody({ repo, issue }, { env, ghCommand, runChild });
     if (body === null) {
       evaluated.push({ issue, artifact: null });
       continue;
@@ -327,6 +438,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
       status: "present",
       linkedIssue: firstPresent.issue,
       linkedIssues,
+      specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE,
       refinedIssues,
       source: a.source,
       acItems: a.acItems,
@@ -354,6 +466,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
         status: "missing",
         linkedIssue: firstEvaluated.issue,
         linkedIssues,
+        specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE,
         refinedIssues,
         reason: `Failed to fetch body for linked issue(s) ${scopeLabel}; draft gate cannot verify a refinement artifact, treating as missing.`,
         finding: "missing_refinement_artifact",
@@ -377,6 +490,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
     status: "missing",
     linkedIssue: firstFetched.issue,
     linkedIssues,
+    specSource: REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE,
     refinedIssues,
     source: first.source,
     acItems: first.acItems,
@@ -390,7 +504,7 @@ export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed,
     _onlyEnforcedWhenDraft: prDraft === true,
   };
 }
-async function fetchLocalConflictFiles({ env = process.env, gitCommand = "git" } = {}) {
+async function fetchLocalConflictFiles({ env = process.env, gitCommand = "git", runChild = defaultRunChild } = {}) {
   let result;
   try {
     result = await runChild(
@@ -458,9 +572,20 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   // detect-copilot-loop-state path and with request-copilot-review's cap logic.
   const interpreterRepoRoot = runtime.repoRoot ?? resolveRepoRoot(process.cwd());
   const interpreterConfigResult = await loadDevLoopConfig({ repoRoot: interpreterRepoRoot });
-  const interpreterRefinementConfig = (Array.isArray(interpreterConfigResult.errors) && interpreterConfigResult.errors.length > 0)
+  const interpreterConfigHasErrors = Array.isArray(interpreterConfigResult.errors) && interpreterConfigResult.errors.length > 0;
+  const interpreterRefinementConfig = interpreterConfigHasErrors
     ? resolveRefinement({ version: 1 })
     : resolveRefinement(interpreterConfigResult.config ?? { version: 1 });
+  if (options.lightweight) {
+    // Compose (not replace) the round cap for light-dispatched PRs (#1210):
+    // min(lightMode.maxCopilotRounds ?? 1, refinement.maxCopilotRounds), so
+    // maxCopilotRounds: 0 still disables Copilot rounds everywhere. Shared with
+    // the maxCopilotRounds resolution below (#1126 requires the two to agree).
+    interpreterRefinementConfig.maxCopilotRounds = resolveEffectiveCopilotRoundCap(
+      interpreterConfigHasErrors ? { version: 1 } : (interpreterConfigResult.config ?? { version: 1 }),
+      { lightweight: true },
+    );
+  }
   const interpretation = interpretLoopState(snapshot, interpreterRefinementConfig);
   const disposition = summarizeLoopInterpretation(interpretation, interpreterRefinementConfig);
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
@@ -493,7 +618,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   };
 }
 
-async function fetchCopilotEverFormallyRequested({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+async function fetchCopilotEverFormallyRequested({ repo, pr }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
   const result = await runChild(
     ghCommand,
     ["api", `repos/${repo}/issues/${pr}/timeline`, "--paginate", "--jq",
@@ -515,7 +640,12 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
   const hasConfigErrors = Array.isArray(configLoadResult.errors) && configLoadResult.errors.length > 0;
   const config = hasConfigErrors ? {} : (configLoadResult.config ?? {});
   const draftGateConfig = resolveGateConfig(config, "draft");
-  const maxCopilotRounds = resolveRefinementConfig(config, "maxCopilotRounds");
+  // Shared with interpreterRefinementConfig.maxCopilotRounds in
+  // loadPrGateCoordinationContext (#1126: the two must never disagree at the
+  // cap boundary) — the same lightweight composition (#1210) is applied here.
+  const maxCopilotRounds = options.lightweight
+    ? resolveEffectiveCopilotRoundCap(config, { lightweight: true })
+    : resolveRefinementConfig(config, "maxCopilotRounds");
   // Shared with interpretLoopState (consumed by copilot-pr-handoff.mjs) and
   // evaluatePrGateCoordination — the single source of truth for "is the
   // Copilot round cap reached" so this detector cannot disagree with the
@@ -556,6 +686,10 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     copilotReviewRoundCount: context.snapshot?.copilotReviewRoundCount ?? 0,
     maxCopilotRounds,
     sameHeadCleanConverged: context.interpretation.sameHeadCleanConverged,
+    // Independent gate-ENTRY re-check (#1190): fed alongside (not derived from)
+    // sameHeadCleanConverged, so an outstanding request on the current head refuses
+    // RUN_PRE_APPROVAL_GATE even if sameHeadCleanConverged were somehow stale/wrong.
+    copilotReviewRequestStatus: context.snapshot?.copilotReviewRequestStatus ?? "none",
     draftGateRequireCi: draftGateConfig.requireCi,
     draftGate: context.gateEvidence.draftGate,
     draftGateMarker: context.gateEvidence.draftGateMarker,

package/scripts/loop/detect-refinement-grill-state.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { requireTokenValue } from "../_cli-primitives.mjs";
+import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import {
+  interpretRefinementGrillState,
+  normalizeGrillSnapshot,
+} from "@dev-loops/core/loop/refinement-grill-state";
+import { detectIssueRefinementArtifact } from "@dev-loops/core/loop/issue-refinement-artifact";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+
+const HELP = `Usage: detect-refinement-grill-state.mjs [--input <path> | --body-file <path> [--surface issue|pr|plan]]
+Detect refinement/grill sub-loop state.
+Modes (choose exactly one):
+  --input <path>                  Interpret a JSON grill snapshot from file
+  --body-file <path>              Seed the deterministic already-refined / zero-iteration
+                                  snapshot from a markdown body on disk
+Options (body-file mode only):
+  --surface issue|pr|plan         Surface the body belongs to (default: issue)
+
+${JQ_OUTPUT_USAGE}
+
+Exit codes:
+  0   Success
+  1   Error
+  2   Invalid --jq filter
+`;
+
+const VALID_SURFACES = new Set(["issue", "pr", "plan"]);
+
+export function parseDetectGrillCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      input: { type: "string" },
+      "body-file": { type: "string" },
+      surface: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    inputPath: undefined,
+    bodyFilePath: undefined,
+    surface: undefined,
+    help: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "input") {
+      options.inputPath = requireTokenValue(token);
+      continue;
+    }
+    if (token.name === "body-file") {
+      options.bodyFilePath = requireTokenValue(token);
+      continue;
+    }
+    if (token.name === "surface") {
+      const surface = requireTokenValue(token).trim();
+      if (!VALID_SURFACES.has(surface)) {
+        throw new Error("--surface must be one of: issue, pr, plan");
+      }
+      options.surface = surface;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t))) continue;
+    throw new Error(`Unknown argument: ${token.rawName}`);
+  }
+  const hasInput = options.inputPath !== undefined;
+  const hasBodyFile = options.bodyFilePath !== undefined;
+  if (hasInput === hasBodyFile) {
+    throw new Error("Provide exactly one input source: --input <path> or --body-file <path>");
+  }
+  if (hasInput && options.surface !== undefined) {
+    throw new Error("--surface applies only to --body-file mode");
+  }
+  return options;
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr } = {},
+) {
+  const options = parseDetectGrillCliArgs(argv);
+  if (options.help) { stdout.write(HELP); return; }
+
+  let snapshot;
+  if (options.inputPath) {
+    const text = await readFile(options.inputPath, "utf8");
+    snapshot = normalizeGrillSnapshot(parseJsonText(text));
+  } else {
+    const body = await readFile(options.bodyFilePath, "utf8");
+    const surface = options.surface ?? "issue";
+    // Deterministic seed for the already-refined / zero-iteration path only: the full
+    // semantic gap detection (scope/actor/decision) is the agent-layer bounded input consumed
+    // at await_answers. This body-file mode computes ONLY the deterministic AC-presence signal
+    // via the single is-it-refined source of truth, detectIssueRefinementArtifact.
+    const artifact = detectIssueRefinementArtifact({ body });
+    snapshot = normalizeGrillSnapshot({
+      loaded: true,
+      detectRan: true,
+      surface,
+      openGapCount: artifact.finding ? 1 : 0,
+      unresolvedGapCount: 0,
+    });
+  }
+
+  const interpretation = interpretRefinementGrillState(snapshot);
+  process.exitCode = emitResult(
+    {
+      ok: true,
+      snapshot,
+      state: interpretation.state,
+      allowedTransitions: interpretation.allowedTransitions,
+      nextAction: interpretation.nextAction,
+    },
+    { jq: options.jq, silent: options.silent, stdout, stderr },
+  );
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => { process.stderr.write(`${formatCliError(error)}\n`); process.exitCode = 1; });
+}

package/scripts/loop/resolve-dev-loop-startup.mjs

@@ -21,7 +21,8 @@ import {
 } from "@dev-loops/core/loop/async-start-contract";
 import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { isCopilotLogin } from "@dev-loops/core/github/copilot-helpers";
-import { loadDevLoopConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveLightMode, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { detectScope } from "./detect-change-scope.mjs";
 import { createPiAdapter } from "@dev-loops/core/harness";
 import { validatePlanFile } from "../refine/validate-plan-file.mjs";
 import {
@@ -65,6 +66,14 @@ Optional modifier:
                  heuristic (chore/fix commit type + no --plan-file + small change)
                  is a documented manual signal; --lightweight is the explicit,
                  deterministic trigger.
+                 Used ALONE (no --issue/--pr/--input/--plan-file/--spike):
+                 issue-less PR-first (#1210) — no tracker binding at all
+                 (canonicalSpecSource: pr_body, no issue-keyed worktree
+                 requirement). Gated on localImplementation.lightMode being
+                 enabled AND the live change scope (git diff) staying within
+                 its maxFiles/maxLines threshold; fails closed with a distinct
+                 reason (light mode disabled / scope undetectable / over
+                 threshold) requiring --issue above the threshold.
 ${JQ_OUTPUT_USAGE}
 
 Exit codes:
@@ -200,17 +209,23 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
   if (modeCount > 1) {
     throw parseError("--issue, --pr, --input, --plan-file, and --spike are mutually exclusive; provide exactly one");
   }
-  if (modeCount === 0) {
-    throw parseError("--input <path>, --issue <n>, --pr <n>, --plan-file <path>, or --spike <path> is required");
+  // --lightweight is normally a MODIFIER (not a 6th mode): it makes the PR body
+  // the spec-of-record for the --issue local path. Used ALONE (modeCount === 0,
+  // issue #1210) it is instead the issue-less PR-first trigger — no tracker
+  // binding at all — so the "no mode selected" error is skipped in that case.
+  if (modeCount === 0 && !options.lightweight) {
+    throw parseError("--input <path>, --issue <n>, --pr <n>, --plan-file <path>, --spike <path>, or --lightweight (issue-less PR-first) is required");
   }
-  // --lightweight is a MODIFIER (not a 6th mode): it makes the PR body the
-  // spec-of-record for the --issue local path. It is the opposite of --plan-file
-  // (which commits a durable plan doc as the spec) and only composes with --issue.
+  // --lightweight is the opposite of --plan-file (which commits a durable plan
+  // doc as the spec) regardless of mode.
   if (options.lightweight && options.planFile !== undefined) {
     throw parseError("--lightweight and --plan-file are opposites: --plan-file commits a durable plan doc as the spec-of-record, --lightweight makes the PR body the spec. Provide only one.");
   }
-  if (options.lightweight && options.issue === undefined) {
-    throw parseError("--lightweight is a modifier for the --issue path (the PR body becomes the spec-of-record). Combine it with --issue <n>.");
+  // When another mode IS selected, --lightweight only composes with --issue
+  // (not --pr/--input/--spike). Used with no mode selected at all, it is the
+  // issue-less PR-first trigger handled above.
+  if (options.lightweight && modeCount > 0 && options.issue === undefined) {
+    throw parseError("--lightweight is a modifier for the --issue path (the PR body becomes the spec-of-record). Combine it with --issue <n>, or use --lightweight alone (no other mode flag) for the issue-less PR-first path.");
   }
   return options;
 }
@@ -545,6 +560,120 @@ export function buildSpikeInput({ spikeFilePath }) {
     },
   };
 }
+// Candidate default-branch refs for issue-less scope measurement, in preference
+// order. origin/HEAD tracks the remote default branch when set; the rest cover
+// the common names.
+const ISSUELESS_BASE_REF_CANDIDATES = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
+
+function resolveIssuelessMergeBase(cwd) {
+  for (const ref of ISSUELESS_BASE_REF_CANDIDATES) {
+    try {
+      return execFileSync("git", ["merge-base", ref, "HEAD"], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      // try the next candidate
+    }
+  }
+  return null;
+}
+
+/**
+ * Decide whether the live change scope is eligible for issue-less lightweight
+ * PR-first (#1210): reuses the same localImplementation.lightMode threshold
+ * that gates inline vs full-fanout gate dispatch, so "genuinely small" means
+ * the same thing everywhere in the repo.
+ *
+ * Scope is measured from the merge-base with the default branch to the WORKING
+ * TREE (`git diff --stat <merge-base>`), so multi-commit branches and
+ * uncommitted changes are both counted — a HEAD~1-only measure would fail OPEN
+ * on a branch whose earlier commits already exceed the threshold. Fails CLOSED
+ * on every negative path (disabled / no resolvable base / undetectable diff /
+ * over threshold) with a distinct reason so the caller can report why --issue
+ * is required instead of silently defaulting one way or the other.
+ *
+ * Every git invocation is bound to `cwd` (the adapter-resolved repoRoot),
+ * matching the rest of this file's git calls — process.cwd() is never relied
+ * on implicitly so this stays correct when invoked from a subdirectory or
+ * with a harness cwd that differs from the OS process cwd.
+ *
+ * @param {import("@dev-loops/core/config").DevLoopConfig} config
+ * @param {string} [cwd] - Repo root to run git commands in (defaults to process.cwd() when omitted).
+ * @returns {{ eligible: true, scope: object, threshold: {maxFiles:number,maxLines:number} } | { eligible: false, reason: "light_mode_disabled"|"scope_detection_failed"|"over_threshold", scope?: object, threshold?: object, detail?: string }}
+ */
+export function resolveIssuelessLightweightEligibility(config, cwd) {
+  const threshold = resolveLightMode(config);
+  if (!threshold) {
+    return { eligible: false, reason: "light_mode_disabled" };
+  }
+  const mergeBase = resolveIssuelessMergeBase(cwd);
+  if (mergeBase === null) {
+    return {
+      eligible: false,
+      reason: "scope_detection_failed",
+      detail: `no merge-base with any default-branch candidate (${ISSUELESS_BASE_REF_CANDIDATES.join(", ")})`,
+    };
+  }
+  // detectScope with only `base` diffs base..working-tree in one measure
+  // (committed branch delta + uncommitted changes).
+  const scope = detectScope({ base: mergeBase, cwd });
+  if (scope.ok === false) {
+    return { eligible: false, reason: "scope_detection_failed", detail: scope.error };
+  }
+  if (scope.filesChanged > threshold.maxFiles || scope.linesChanged > threshold.maxLines) {
+    return { eligible: false, reason: "over_threshold", scope, threshold };
+  }
+  return { eligible: true, scope, threshold };
+}
+
+/**
+ * Build a `--lightweight` startup input with NO tracker binding at all
+ * (issue-less PR-first, #1210): `--lightweight` used alone, no --issue.
+ *
+ * Read-only: no tracker mutation, no GitHub calls, no issue/PR number. Gated
+ * by {@link resolveIssuelessLightweightEligibility} — an ineligible change
+ * throws so the CLI fails closed (exit 1, no readiness bundle) with a message
+ * naming the distinct reason, mirroring buildPlanFileInput/buildSpikeInput's
+ * fail-closed-on-invalid-input convention. Exempt from the worktree-isolation
+ * guard like the plan-file/spike paths: there is no issue number to key a
+ * worktree on.
+ *
+ * @param {{ config: import("@dev-loops/core/config").DevLoopConfig, cwd?: string }} params
+ * @returns {object} startup input with canonicalSpecSource: "pr_body"
+ */
+export function buildLightweightIssuelessInput({ config, cwd }) {
+  const eligibility = resolveIssuelessLightweightEligibility(config, cwd);
+  if (!eligibility.eligible) {
+    if (eligibility.reason === "light_mode_disabled") {
+      throw new Error("--lightweight without --issue (issue-less PR-first) requires localImplementation.lightMode.enabled in .devloops; enable light mode or provide --issue <n>.");
+    }
+    if (eligibility.reason === "scope_detection_failed") {
+      throw new Error(`--lightweight without --issue (issue-less PR-first) requires a measurable change scope; git diff failed (${eligibility.detail}). Provide --issue <n> instead.`);
+    }
+    throw new Error(`--lightweight without --issue (issue-less PR-first) requires the change to stay within the light-mode threshold (maxFiles=${eligibility.threshold.maxFiles}, maxLines=${eligibility.threshold.maxLines}); this change is ${eligibility.scope.filesChanged} files / ${eligibility.scope.linesChanged} lines. Provide --issue <n> for above-threshold changes.`);
+  }
+  return {
+    intent: "start_issue_locally",
+    mode: "bounded_handoff",
+    targetPreference: "prefer_local",
+    artifactState: "not_applicable",
+    issueLinkageResolution: "not_applicable",
+    issueReadiness: "not_applicable",
+    issueAssignmentState: "not_applicable",
+    loopState: "implementation_pending",
+    canonicalSpecSource: "pr_body",
+    planFileExempt: true,
+    currentState: {
+      target: { kind: "local_phase", issue: null, pr: null, linkedPr: null, branch: null, phase: "lightweight-issueless" },
+      ownership: "local",
+      nextActor: "local",
+      status: "active",
+      authorization: "authorized",
+    },
+  };
+}
 export function summarizeCanonicalState(bundle) {
   return {
     target: bundle.canonicalState?.target ?? null,
@@ -746,6 +875,14 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     if (options.lightweight) {
       input = { ...input, canonicalSpecSource: "pr_body" };
     }
+  } else if (options.lightweight) {
+    // --lightweight used ALONE (no other mode flag): issue-less PR-first (#1210).
+    // A broken config must surface as ITS OWN failure, not decay to the
+    // misleading light_mode_disabled reason a bare {version:1} would produce.
+    if (configErrors.length > 0) {
+      throw new Error(`--lightweight without --issue (issue-less PR-first) requires a loadable dev-loop config, but config loading failed: ${configErrors.map((e) => e?.message ?? String(e)).join("; ")}. Fix the config or provide --issue <n>.`);
+    }
+    input = buildLightweightIssuelessInput({ config: devLoopConfig, cwd: repoRoot });
   } else {
     input = buildAutoResolvedInput({
       pr: options.pr,