dev-loops 0.7.1 → 0.7.2

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

@@ -11,7 +11,7 @@ import {
   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 { 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";
@@ -30,6 +30,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,
@@ -80,6 +86,7 @@ export function parseDetectPrGateCoordinationCliArgs(argv) {
     help: false,
     repo: undefined,
     pr: undefined,
+    lightweight: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -87,6 +94,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 +120,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}`);
   }
@@ -458,9 +470,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
@@ -515,7 +538,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 +584,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/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,

package/scripts/loop/sanctioned-commands.mjs

@@ -26,9 +26,11 @@ export const SANCTIONED_COMMANDS = Object.freeze({
   reads: Object.freeze({
     "pr-facts": "scripts/github/view-pr.mjs",
     "ci-status": "scripts/github/probe-ci-status.mjs",
+    "ci-wait": "scripts/github/wait-pr-checks.mjs",
     "ci-logs": "scripts/github/fetch-ci-logs.mjs",
     "issue-list": "scripts/github/list-issues.mjs",
     "copilot-review-state": "scripts/github/probe-copilot-review.mjs",
+    "review-threads": "scripts/github/list-review-threads.mjs",
     "gate-coordination": "scripts/loop/detect-pr-gate-coordination-state.mjs",
   }),
 

package/scripts/loop/validate-pr-body-spec.mjs

@@ -24,8 +24,8 @@ const USAGE = `Usage:
   validate-pr-body-spec.mjs --input <path> [--expected-issue <n>]
 Validate that a PR body carries the lightweight spec-of-record invariants
 (Objective/why, In scope, Explicit non-goals, testable Acceptance criteria,
-Definition of done, Open questions/risks, and a GitHub closing-keyword issue
-reference such as \`Closes #123\`).
+Definition of done, Open questions/risks, and — unless --no-issue is given —
+a GitHub closing-keyword issue reference such as \`Closes #123\`).
 Required (exactly one):
   --repo <owner/name> --pr <number>   Fetch the PR body via gh and validate it
   --input <path>                      Path to a JSON file with { "body": "..." }
@@ -34,7 +34,14 @@ Required (exactly one):
 Optional:
   --expected-issue <n>                Positive integer; the referenced closing
                                       issue(s) must include this number, else
-                                      "closes_wrong_issue".
+                                      "closes_wrong_issue". Mutually exclusive
+                                      with --no-issue.
+  --no-issue                          Explicit issue-less mode (#1210): the PR
+                                      is the sole artifact, so a closing-issue
+                                      reference is FORBIDDEN rather than
+                                      required — one present fails closed under
+                                      "unexpected_closing_issue_reference".
+                                      Mutually exclusive with --expected-issue.
 Success output (stdout, JSON):
   {
     "ok": true | false,
@@ -61,6 +68,7 @@ export function parseValidatePrBodySpecCliArgs(argv) {
     pr: undefined,
     input: undefined,
     expectedIssue: undefined,
+    noIssue: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -70,6 +78,7 @@ export function parseValidatePrBodySpecCliArgs(argv) {
       pr: { type: "string" },
       input: { type: "string" },
       "expected-issue": { type: "string" },
+      "no-issue": { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -111,12 +120,19 @@ export function parseValidatePrBodySpecCliArgs(argv) {
       options.expectedIssue = Number(value);
       continue;
     }
+    if (token.name === "no-issue") {
+      options.noIssue = true;
+      continue;
+    }
     if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.help) {
     return options;
   }
+  if (options.noIssue && Number.isInteger(options.expectedIssue)) {
+    throw parseError("--no-issue is mutually exclusive with --expected-issue; provide exactly one issue-linkage mode");
+  }
   const hasInput = typeof options.input === "string" && options.input.length > 0;
   const hasAnyRemote = (typeof options.repo === "string" && options.repo.length > 0) || Number.isInteger(options.pr);
   const hasRemotePair = typeof options.repo === "string" && options.repo.length > 0 && Number.isInteger(options.pr);
@@ -163,12 +179,12 @@ export async function validatePrBodySpecFromOptions(options, { env = process.env
     const body = typeof payload.body === "string" ? payload.body : "";
     const repo = typeof payload.repo === "string" ? payload.repo : options.repo ?? null;
     const pr = Number.isInteger(payload.pr) ? payload.pr : options.pr ?? null;
-    return { ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null }), repo, pr };
+    return { ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null, issueLess: options.noIssue }), repo, pr };
   }
   parseRepoSlug(options.repo);
   const body = await fetchPrBody({ repo: options.repo, pr: options.pr }, { env, ghCommand });
   return {
-    ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null }),
+    ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null, issueLess: options.noIssue }),
     repo: options.repo,
     pr: options.pr,
   };

package/scripts/pages/build-state-atlas.mjs

@@ -2,10 +2,10 @@
 // state machine rendered as a mermaid diagram, emitted DETERMINISTICALLY from
 // the code's own exported tables so the page can never drift from the code.
 //
-// Four diagrams come straight from packages/core/src/loop tables (copilot loop,
-// reviewer loop, outer conductor routing, and the public dev-loop gate hub); two
-// more are authored from documented, table-less sources (the PR lifecycle
-// contract and the release pipeline workflow).
+// Five diagrams come straight from packages/core/src/loop tables (copilot loop,
+// reviewer loop, outer conductor routing, the public dev-loop gate hub, and the
+// PR lifecycle contract); one more (the release pipeline workflow) is authored
+// from a documented, table-less source.
 //
 // The page reuses the article design system (docs/articles/introducing-dev-loops.html):
 // the same :root tokens, body gradient, and typography. It intentionally defines
@@ -15,6 +15,7 @@ import { STATE, TRANSITIONS } from '../../packages/core/src/loop/copilot-loop-st
 import { REVIEWER_STATE, REVIEWER_TRANSITIONS } from '../../packages/core/src/loop/reviewer-loop-state.mjs';
 import { OUTER_STATE, OUTER_TRANSITIONS } from '../../packages/core/src/loop/conductor-routing.mjs';
 import { PUBLIC_DEV_LOOP_GATE_CONTRACT } from '../../packages/core/src/loop/public-dev-loop-routing-contract.mjs';
+import { PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS } from '../../packages/core/src/loop/pr-lifecycle.mjs';
 
 // Classify a state/gate id by name into one of four visual classes. Colors are
 // drawn from the site's own dark palette (accent violet, kicker blue,
@@ -80,7 +81,7 @@ function gateClass(row) {
 }
 
 function renderGateFlowchart(contract) {
-  const lines = ['flowchart TD', '    router(["dev-loop router"])'];
+  const lines = ['flowchart LR', '    router(["dev-loop router"])'];
   for (const row of contract) {
     const strategy = row.selectedStrategy ?? 'none';
     lines.push(`    router -->|${row.routeKind}| ${row.gate}["${row.gate} — ${strategy}"]`);
@@ -105,47 +106,16 @@ const outerDiagram = renderStateDiagram(
 );
 const gateDiagram = renderGateFlowchart(PUBLIC_DEV_LOOP_GATE_CONTRACT);
 
-// --- Statically-authored diagrams (documented, table-less sources) ---
+// PR lifecycle: the 13-state vocabulary + required transitions exported by
+// packages/core/src/loop/pr-lifecycle.mjs (issue #1193), re-exported here so
+// this module's public surface is unchanged. The L2/L3 state-machine
+// conformance harness (scripts/docs/validate-state-machine-conformance.mjs)
+// imports the same core module directly rather than through this one, so it
+// never pulls in this page generator's diagram-rendering work at load time.
+export { PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS };
+const prLifecycleDiagram = renderStateDiagram(PR_LIFECYCLE_TRANSITIONS, PR_LIFECYCLE_STATES);
 
-// PR lifecycle: the 13-state vocabulary + required transitions from
-// skills/docs/pr-lifecycle-contract.md.
-const prLifecycleStates = [
-  'draft_local_review_gate',
-  'draft_local_remediation',
-  'ready_state_needs_copilot_request',
-  'waiting_for_copilot_review',
-  'copilot_feedback_remediation',
-  'copilot_reply_resolve_pending',
-  'merge_conflict_resolution',
-  'final_local_preapproval_gate',
-  'final_gate_remediation',
-  'waiting_for_human_pr_approval',
-  'waiting_for_merge',
-  'terminal_slice_complete',
-  'stopped_needs_user_decision',
-];
-const prLifecycleDiagram = renderStateDiagram([
-  ['draft_local_review_gate', 'draft_local_remediation'],
-  ['draft_local_review_gate', 'ready_state_needs_copilot_request'],
-  ['draft_local_review_gate', 'stopped_needs_user_decision'],
-  ['draft_local_remediation', 'draft_local_review_gate'],
-  ['ready_state_needs_copilot_request', 'waiting_for_copilot_review'],
-  ['ready_state_needs_copilot_request', 'stopped_needs_user_decision'],
-  ['waiting_for_copilot_review', 'copilot_feedback_remediation'],
-  ['copilot_feedback_remediation', 'copilot_reply_resolve_pending'],
-  ['copilot_reply_resolve_pending', 'ready_state_needs_copilot_request'],
-  ['waiting_for_copilot_review', 'merge_conflict_resolution'],
-  ['merge_conflict_resolution', 'waiting_for_copilot_review'],
-  ['waiting_for_copilot_review', 'final_local_preapproval_gate'],
-  ['final_local_preapproval_gate', 'final_gate_remediation'],
-  ['final_local_preapproval_gate', 'waiting_for_human_pr_approval'],
-  ['final_gate_remediation', 'final_local_preapproval_gate'],
-  ['waiting_for_human_pr_approval', 'waiting_for_merge'],
-  ['waiting_for_human_pr_approval', 'draft_local_review_gate'],
-  ['waiting_for_merge', 'terminal_slice_complete'],
-  ['terminal_slice_complete', '[*]'],
-  ['stopped_needs_user_decision', '[*]'],
-], prLifecycleStates);
+// --- Statically-authored diagram (documented, table-less source) ---
 
 // Release pipeline: the fail-closed gate chain from .github/workflows/release.yml.
 const releasePipelineNodes = [
@@ -189,7 +159,7 @@ const releaseDiagram = [
 
 const INTRO_PROSE = [
   'dev-loops drives every pull request through closed, deterministic state machines. Workflow control lives in the graph; agent judgment enters only as bounded, explicit inputs, never as hidden orchestration. Exactly one state applies at a time, and each state exposes the legal transitions out of it.',
-  "Every diagram on this page is generated at site-build time from the code's own exported tables — the copilot loop's <code>STATE</code>/<code>TRANSITIONS</code>, the reviewer loop's <code>REVIEWER_STATE</code>/<code>REVIEWER_TRANSITIONS</code>, the outer loop's <code>OUTER_STATE</code>/<code>OUTER_TRANSITIONS</code>, and the public router's <code>PUBLIC_DEV_LOOP_GATE_CONTRACT</code>. They cannot drift from the code: change a transition table and this page changes with it. Two diagrams (the PR lifecycle and the release pipeline) are authored from documented contracts that have no single code table.",
+  "Every diagram on this page is generated at site-build time from the code's own exported tables — the copilot loop's <code>STATE</code>/<code>TRANSITIONS</code>, the reviewer loop's <code>REVIEWER_STATE</code>/<code>REVIEWER_TRANSITIONS</code>, the outer loop's <code>OUTER_STATE</code>/<code>OUTER_TRANSITIONS</code>, the public router's <code>PUBLIC_DEV_LOOP_GATE_CONTRACT</code>, and the PR lifecycle's <code>PR_LIFECYCLE_STATES</code>/<code>PR_LIFECYCLE_TRANSITIONS</code>. They cannot drift from the code: change a transition table and this page changes with it. One diagram (the release pipeline) is authored from a documented contract that has no single code table.",
   'The state names are not labels for a picture — they are the literal contract identifiers that appear in logs, handoff envelopes, and gate artifacts. Nodes are coloured by role: <strong>active / in-progress</strong> steps the loop advances itself, <strong>waiting-on-external</strong> states that block on something outside the loop (CI, Copilot, a human), <strong>blocked / fail-closed</strong> states that stop or reconcile rather than guess, and <strong>terminal</strong> states where the slice is complete.',
 ];
 
@@ -217,7 +187,7 @@ const SECTIONS = [
   {
     id: 'pr-lifecycle',
     title: 'PR lifecycle contract',
-    source: 'skills/docs/pr-lifecycle-contract.md (documented vocabulary)',
+    source: 'packages/core/src/loop/pr-lifecycle.mjs — PR_LIFECYCLE_STATES + PR_LIFECYCLE_TRANSITIONS',
     prose: [
       'One PR moves through a stable thirteen-state vocabulary from draft to merge. These identifiers are part of the contract surface even as the helper implementations around them change. Two local gates guard the path — <code>draft_gate</code> (draft to ready-for-review) and <code>pre_approval_gate</code> (before final approval) — and both are fail-closed fan-out reviews that run independent angle chains and must produce clean current-head evidence to pass.',
       'All gate evidence is per-head: a new push re-opens the gates, and ready-to-draft resets the lifecycle back into draft-stage gating. A conflicted head detours through <code>merge_conflict_resolution</code> before any further gate progression — a conflicted PR is never treated as approval- or merge-ready, even if older gate comments and CI were green. Human approval and merge are explicit external waits, not hidden remediation states.',
@@ -270,7 +240,7 @@ function sectionMarkup(s) {
         <h2>${s.title}</h2>
         <p class="source">Diagram generated from <code>${s.source}</code></p>
 ${proseParagraphs(s.prose)}
-        <div class="diagram"><div class="mermaid">
+        <div class="diagram"><button class="expand" type="button" aria-label="View diagram fullscreen">⤢ Fullscreen</button><div class="mermaid">
 ${escapeMermaid(s.diagram)}
 </div></div>
       </section>`;
@@ -404,6 +374,16 @@ export function buildStateAtlasHtml() {
   }
   .diagram .mermaid { text-align: center; }
   .diagram .mermaid svg { max-width: 100%; height: auto; }
+  .diagram { position: relative; }
+  .diagram .expand { position: sticky; float: right; top: 0.6rem; right: 0.6rem; margin: 0 0 -2rem; z-index: 2; font: 600 0.72rem var(--font); color: var(--copy); background: rgba(15, 23, 42, 0.85); border: 1px solid var(--card-border); border-radius: 8px; padding: 0.35rem 0.6rem; cursor: pointer; }
+  .diagram .expand:hover { color: var(--heading); border-color: var(--accent); }
+  .diagram .mermaid { cursor: zoom-in; }
+  .diagram .mermaid:fullscreen { cursor: zoom-out; background: #0b1220; display: flex; align-items: center; justify-content: center; padding: 2rem; }
+  .diagram .mermaid:-webkit-full-screen { cursor: zoom-out; background: #0b1220; display: flex; align-items: center; justify-content: center; padding: 2rem; }
+  .diagram .mermaid:-webkit-full-screen svg { max-width: calc(100vw - 4rem); max-height: calc(100vh - 4rem); width: auto; height: auto; }
+  .diagram .mermaid:fullscreen svg { max-width: calc(100vw - 4rem); max-height: calc(100vh - 4rem); width: auto; height: auto; }
+  .diagram .mermaid.fs-fallback { position: fixed; inset: 0; z-index: 50; background: #0b1220; display: flex; align-items: center; justify-content: center; padding: 1rem; cursor: zoom-out; overflow: auto; }
+  .diagram .mermaid.fs-fallback svg { max-width: calc(100vw - 2rem); max-height: calc(100vh - 2rem); width: auto; height: auto; }
 </style>
 </head>
 <body>
@@ -416,6 +396,28 @@ ${sections}
     </main>
     <script src="assets/mermaid.min.js"></script>
     <script>
+      let fsInFlight = false;
+      document.addEventListener('click', async (e) => {
+        if (fsInFlight) return;
+        const target = e.target instanceof Element ? e.target : e.target?.parentElement;
+        if (!target) return;
+        const btn = target.closest('.diagram .expand');
+        const box = btn ? btn.parentElement.querySelector('.mermaid') : target.closest('.diagram .mermaid');
+        if (!box) return;
+        fsInFlight = true;
+        try {
+          const fsElement = document.fullscreenElement || document.webkitFullscreenElement;
+          if (fsElement === box) {
+            await (document.exitFullscreen || document.webkitExitFullscreen)?.call(document);
+            return;
+          }
+          if (box.classList.contains('fs-fallback')) { box.classList.remove('fs-fallback'); return; }
+          const request = box.requestFullscreen || box.webkitRequestFullscreen;
+          if (request) await request.call(box);
+          else box.classList.add('fs-fallback'); // iOS Safari: CSS overlay fallback
+        } catch { /* fullscreen denied: fall back to the CSS overlay */ box.classList.add('fs-fallback'); }
+        finally { fsInFlight = false; }
+      });
       mermaid.initialize({
         startOnLoad: true,
         securityLevel: 'strict',