@dev-loops/core 1.0.0-rc.3 → 1.0.0-rc.5

package/src/loop/pr-title-markers.mjs

@@ -12,30 +12,91 @@
  * It is intentionally pure and side-effect free.
  */
 
+/**
+ * Builds a status-marker tester for a bare word like "WIP" or "DRAFT".
+ *
+ * A status marker asserts, on its own, that the PR is unfinished: bracketed
+ * (`[WIP]`), parenthesized (`(draft)`), colon-suffixed (`WIP:`), or the
+ * entire title with nothing else attached (a bare standalone `DRAFT`). A
+ * plain `\bWORD\b` match also hits the same word inside a compound noun
+ * phrase that names a component instead — `draft-gate`, `draft gate`,
+ * `wip-branch` — because a hyphen or a space is itself a word boundary. An
+ * underscore is a word character, so `draft_gate` never matched `\bDRAFT\b`
+ * to begin with; it is listed among the exempt forms for consistency, not
+ * because it was ever flagged. None of those forms satisfy any construction
+ * below, so a component name is left unflagged while a real status claim
+ * still is. "swipe"/"wiped"/"drafting" already fail every construction
+ * because there is no boundary between the marker word and the letters that
+ * follow it; a hyphen-prefixed compound like "re-draft" DOES create such a
+ * boundary (`\b` sees the hyphen).
+ *
+ * A trailing tag set off by a dash (`Fix login flow — WIP`) is deliberately
+ * NOT its own construction, even though it reads as a real status claim.
+ * Any dash-based construction narrow enough to close a title's tag also
+ * reopens the compound-noun false positive whenever the joiner is a
+ * different dash character (`Handle en dash–draft–gate naming`), and any fix
+ * for that narrows the construction until it drops real status claims that
+ * were previously caught (`Fix login flow — WIP.`, `— WIP (rebasing)`). The
+ * bracket/paren/colon/standalone set stays free of both failure modes, so a
+ * dash-set-off marker is left unflagged; `WIP:`/`DRAFT:` remains one
+ * keystroke away and stays flagged, the same trade already accepted for
+ * `WIP foo bar`.
+ *
+ * The bracket/paren/colon constructions all require the opening delimiter
+ * (`[`, `(`, or the marker word itself for colon) to sit at the start of the
+ * title or after whitespace — never directly after a letter, `/`, or `-` —
+ * so a conventional-commit scope (`fix(draft): support x`), a path segment
+ * (`app/[draft]/page.tsx`), a scoped label (`feat/draft: x`, `docs/wip:
+ * notes`), and a hyphen-prefixed compound (`re-draft: cleanup`) are all read
+ * as a component name, not a status claim — the same anchoring rule as the
+ * hyphen/underscore/space compound-noun exemption above. This does introduce
+ * one accepted false-negative class: a marker preceded by punctuation other
+ * than whitespace with no space of its own, e.g. `Fix bug,(draft)` or `Fix
+ * login(wip)`. Widening the anchor to "start, whitespace, or punctuation"
+ * would also re-admit the very forms (`/`, `-`) the anchor exists to
+ * exclude, so the narrower, whitespace-only anchor is kept and this
+ * false-negative class is accepted as its cost.
+ *
+ * The colon construction additionally requires the colon itself to CLOSE the
+ * tag — followed by whitespace or the end of the title, never directly by
+ * another character — so a scheme/tag/ref that merely starts with the
+ * marker word (`draft://`, `draft:latest`, `wip:branch`) is read as an
+ * unrelated identifier, not a status claim.
+ */
+function statusMarkerTester(word) {
+  const bracket = new RegExp(`(?:^|\\s)\\[\\s*${word}\\s*\\]`, "i");
+  const paren = new RegExp(`(?:^|\\s)\\(\\s*${word}\\s*\\)`, "i");
+  const colon = new RegExp(`(?:^|\\s)${word}\\s*:(?:\\s|$)`, "i");
+  const standalone = new RegExp(`^\\s*${word}\\s*$`, "i");
+  return (title) => bracket.test(title) || paren.test(title) || colon.test(title)
+    || standalone.test(title);
+}
+
 /**
  * Canonical merge-blocking markers and how to detect them.
  *
- * Word-boundary matching is used for the alphabetic markers so that real words
- * are not false-positives (e.g. "swipe"/"wiped" must not match WIP;
- * "drafting"/"redraft" must not match DRAFT). Bracket/paren/colon punctuation
- * (`[WIP]`, `(wip)`, `WIP:`) are non-word characters, so `\b` boundaries still
- * match those variants. The construction emoji has no word boundary, so it is
- * matched literally anywhere in the title.
+ * "DO NOT MERGE" is a three-word phrase with no plausible compound-noun
+ * reading, so it keeps simple word-boundary matching. The construction emoji
+ * has no word boundary at all, so it is matched literally anywhere in the
+ * title.
  */
 const MARKER_MATCHERS = [
-  { label: "WIP", pattern: /\bWIP\b/i },
-  { label: "DRAFT", pattern: /\bDRAFT\b/i },
+  { label: "WIP", test: statusMarkerTester("WIP") },
+  { label: "DRAFT", test: statusMarkerTester("DRAFT") },
   // Flexible (any) whitespace between the phrase words, case-insensitive.
-  { label: "DO NOT MERGE", pattern: /\bDO\s+NOT\s+MERGE\b/i },
-  { label: "🚧", pattern: /🚧/u },
+  { label: "DO NOT MERGE", test: (title) => /\bDO\s+NOT\s+MERGE\b/i.test(title) },
+  { label: "🚧", test: (title) => /🚧/u.test(title) },
 ];
 
 /**
  * Finds merge-blocking markers in a PR title.
  *
- * Returns the canonical labels of every matched marker, de-duped and in a
- * stable order (the declaration order of {@link MARKER_MATCHERS}). Returns an
- * empty array when the title is clean, empty, or not a string.
+ * Returns the canonical labels of every matched marker, in a stable order
+ * (the declaration order of {@link MARKER_MATCHERS}). Each label can appear
+ * at most once: MARKER_MATCHERS visits each entry exactly once and every
+ * entry's label is distinct, so the result is de-duped by construction —
+ * there is no separate dedupe step to fail. Returns an empty array when the
+ * title is clean, empty, or not a string.
  *
  * @param {unknown} title - The PR title to inspect.
  * @returns {string[]} Canonical labels of matched markers, e.g. ["WIP"] or
@@ -47,8 +108,8 @@ export function findBlockingTitleMarkers(title) {
   }
 
   const matched = [];
-  for (const { label, pattern } of MARKER_MATCHERS) {
-    if (pattern.test(title) && !matched.includes(label)) {
+  for (const { label, test } of MARKER_MATCHERS) {
+    if (test(title)) {
       matched.push(label);
     }
   }

package/src/loop/public-dev-loop-routing.mjs

@@ -1,6 +1,8 @@
 import {
   evaluateRetrospectiveGate,
   normalizeRetrospectiveCheckpointState,
+  normalizeCheckpointCycleIdentity,
+  resolveCheckpointStateFromArtifact,
 } from "./retrospective-checkpoint.mjs";
 import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
@@ -32,6 +34,16 @@ import {
 
 export * from "./public-dev-loop-routing-contract.mjs";
 
+// Re-exported so script-layer callers (e.g. resolve-dev-loop-startup.mjs and
+// checkpoint-contract.mjs) can normalize a checkpoint cycle identity and
+// resolve a durable checkpoint artifact's state through the public routing
+// surface, without retrospective-checkpoint.mjs itself becoming a public
+// package export (see skills/docs/retrospective-checkpoint-contract.md).
+export {
+  normalizeCheckpointCycleIdentity,
+  resolveCheckpointStateFromArtifact,
+};
+
 const COPILOT_ISSUE_ASSIGNEE = "copilot-swe-agent";
 
 const TARGET_KIND_SET = new Set(Object.values(DEV_LOOP_TARGET_KIND));

package/src/loop/retrospective-checkpoint.mjs

@@ -73,22 +73,86 @@ export function normalizeRetrospectiveCheckpointState(value) {
 }
 
 /**
- * Returns true if a routing result represents a qualifying GitHub-first async
- * dev-loop completion that requires a post-run behavioral retrospective before
- * the next start/resume.
+ * Normalizes a dev-loop cycle identity — the minimum facts that pin a
+ * checkpoint record to one specific qualifying completion: repo, PR number,
+ * and merge commit. Returns null when any field is missing or malformed, so a
+ * partial/garbled identity can never be mistaken for a valid one.
  *
- * A qualifying completion is one that:
- * - has a `selectedGate` in RETROSPECTIVE_QUALIFYING_GATES
- * - with `routeKind === "route"` (inspect/status-only results do not qualify)
+ * @param {unknown} identity
+ * @returns {{repo: string, prNumber: number, mergeCommit: string}|null}
  */
-export function isQualifyingAsyncCompletion(routingResult) {
-  if (!routingResult || typeof routingResult !== "object") return false;
-  const { routeKind, selectedGate } = routingResult;
-  if (routeKind !== "route") {
-    return false;
+export function normalizeCheckpointCycleIdentity(identity) {
+  if (!identity || typeof identity !== "object") {
+    return null;
+  }
+  const repo = typeof identity.repo === "string" ? identity.repo.trim() : "";
+  const prNumber = Number.isInteger(identity.prNumber) && identity.prNumber > 0 ? identity.prNumber : null;
+  const mergeCommit = typeof identity.mergeCommit === "string" ? identity.mergeCommit.trim() : "";
+  if (repo.length === 0 || prNumber === null || mergeCommit.length === 0) {
+    return null;
+  }
+  return { repo, prNumber, mergeCommit };
+}
+
+/**
+ * Resolves the RETROSPECTIVE_CHECKPOINT_STATE for a durable checkpoint
+ * artifact, scoped to the recorded cycle's recency (issue: a one-time
+ * `complete`/`skipped` checkpoint must not satisfy every later qualifying
+ * cycle forever).
+ *
+ * A `complete` or `skipped` artifact is scoped by `hasNewerMergeSinceCheckpoint`:
+ * when true, something has merged since the checkpoint's recorded discharge
+ * point (or that point could not be verified at all), so the checkpoint
+ * cannot cover the newer cycle — it fails closed to MISSING. The caller
+ * derives `hasNewerMergeSinceCheckpoint` itself (this module stays
+ * pure/I/O-free) by checking local git ancestry between the checkpoint's
+ * recorded merge commit and the base branch, so this runs fresh on every
+ * evaluation rather than depending on anything having written a fresh
+ * `required` record for the new cycle.
+ *
+ * `required`/`none` are not scoped by this comparison: `required` already
+ * maps to MISSING regardless of recency (an outstanding requirement blocks
+ * the gate no matter which cycle triggered it), and `none` means no
+ * completion has ever been observed.
+ *
+ * @param {object|null|undefined} artifact - Parsed checkpoint JSON, or
+ *   `undefined` when the durable artifact is genuinely ABSENT (no file). Any
+ *   other non-plain-object value — including the JSON literal `null` (a file
+ *   that IS present but contains malformed content) and a corrupt-but-valid
+ *   scalar/array — is treated as present-but-malformed and fails closed to
+ *   MISSING; only a genuinely absent artifact resolves to NONE.
+ * @param {object} [options]
+ * @param {boolean} [options.hasNewerMergeSinceCheckpoint] - True when the
+ *   caller has determined (or could not rule out) that something has merged
+ *   to the base branch since the checkpoint's recorded discharge point.
+ *   Ignored for states other than `complete`/`skipped`. Defaults to `false`
+ *   (trust the recorded state) so callers that never verify recency (e.g.
+ *   `workflow.requireRetrospective` disabled) see unchanged behavior.
+ * @returns {"none"|"complete"|"skipped"|"missing"}
+ */
+export function resolveCheckpointStateFromArtifact(artifact, { hasNewerMergeSinceCheckpoint = false } = {}) {
+  if (artifact === undefined) {
+    return RETROSPECTIVE_CHECKPOINT_STATE.NONE;
+  }
+  if (artifact === null || typeof artifact !== "object" || Array.isArray(artifact)) {
+    // Present but malformed — fail closed, do not treat as "nothing observed".
+    return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;
+  }
+  const rawState = typeof artifact.state === "string" ? artifact.state.trim().toLowerCase() : null;
+  if (rawState === "required" || rawState === "missing") {
+    return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;
+  }
+  if (rawState === "none") {
+    return RETROSPECTIVE_CHECKPOINT_STATE.NONE;
+  }
+  if (rawState === "skipped") {
+    return hasNewerMergeSinceCheckpoint ? RETROSPECTIVE_CHECKPOINT_STATE.MISSING : RETROSPECTIVE_CHECKPOINT_STATE.SKIPPED;
+  }
+  if (rawState === "complete") {
+    return hasNewerMergeSinceCheckpoint ? RETROSPECTIVE_CHECKPOINT_STATE.MISSING : RETROSPECTIVE_CHECKPOINT_STATE.COMPLETE;
   }
-  if (typeof selectedGate !== "string") return false;
-  return RETROSPECTIVE_QUALIFYING_GATES.includes(selectedGate);
+  // Malformed/unrecognized durable state — fail closed.
+  return RETROSPECTIVE_CHECKPOINT_STATE.MISSING;
 }
 
 /**

package/src/loop/reviewer-loop-state.mjs

@@ -1,6 +1,7 @@
 /**
  * Deterministic state machine and bounded planning/merge contracts for reviewer-side PR loops.
  */
+import { SUBMITTED_REVIEW_STATES } from "../github/copilot-helpers.mjs";
 
 export const REVIEWER_STATE = Object.freeze({
   WAITING_FOR_REVIEW_REQUEST: "waiting_for_review_request",
@@ -105,7 +106,6 @@ const VALID_LOCAL_RUN_STATUSES = new Set(["none", "running", "completed", "faile
 const VALID_LOCAL_MERGE_STATUSES = new Set(["none", "ready", "failed"]);
 const VALID_DRAFT_NOTIFICATION_STATUSES = new Set(["none", "notified"]);
 const VALID_SUBMISSION_STATUSES = new Set(["none", "submitted", "failed"]);
-const VALID_SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 
 const SUPPORTED_REVIEW_ANGLES = Object.freeze([
   "correctness",
@@ -143,7 +143,7 @@ function normalizeSubmittedReviewState(value) {
   }
 
   const normalized = value.trim().toUpperCase();
-  return VALID_SUBMITTED_REVIEW_STATES.has(normalized) ? normalized : null;
+  return SUBMITTED_REVIEW_STATES.has(normalized) ? normalized : null;
 }
 
 /**

package/src/loop/ui-e2e-scoping.mjs

@@ -38,8 +38,10 @@ export const VIEWER_SOURCE_PATHS = Object.freeze([
 export const REGISTERED_ARTIFACT_PATHS = Object.freeze([
   "docs/presentations/introducing-dev-loops.html",
   "docs/presentations/dev-loops-deep-dive.html",
+  "docs/presentations/how-dev-loops-decided-itself.html",
   "docs/articles/introducing-dev-loops.html",
   "docs/articles/dev-loops-deep-dive.html",
+  "docs/articles/how-dev-loops-decided-itself.html",
 ]);
 
 export const VIEWER_ARTIFACT_ID = "inspect-run-viewer";

package/src/loop/ui-review-drive.mjs

@@ -44,6 +44,19 @@ export function isErrorResponseStatus(status) {
   return typeof status === "number" && (status < 200 || status >= 400);
 }
 
+/** The one owner of the request-abort carve-out: a request the browser itself
+ * aborted carries no defect signal. Navigating away cancels in-flight asset
+ * requests, so these appear on every multi-step flow. Matched per engine:
+ * WebKit reports "cancelled", Chromium "net::ERR_ABORTED", Firefox
+ * "NS_BINDING_ABORTED". Matching is case-insensitive and substring-based because
+ * engines wrap the token in longer text. A genuine DNS/connection/TLS failure
+ * carries a different token and is still classified must-fix. */
+export function isAbortedRequestFailure(failure) {
+  if (typeof failure !== "string") return false;
+  const f = failure.toLowerCase();
+  return f.includes("cancelled") || f.includes("canceled") || f.includes("err_aborted") || f.includes("ns_binding_aborted");
+}
+
 /** Bound the stack text carried onto a page-error failure so a runaway stack
  * (or a synthetic error with a huge stack) can't bloat the feed envelope. Keeps
  * the head — the top frames, where the throwing file:line sits. Exported so the
@@ -157,6 +170,16 @@ export function classifyFailures({
   }
 
   for (const f of requestFailures) {
+    // A request the BROWSER aborted is not evidence of a defect: navigating away
+    // cancels every asset request still in flight, so a flow with more than one
+    // `goto` manufactures one of these per unfinished image/font on the page it
+    // left. Measured on sofatutor 2026-08-05: a clean two-goto admin2 walk
+    // produced 13, all "cancelled", all classified must-fix — and since
+    // `ok: failures.length === 0`, they failed an otherwise passing drive and
+    // would have been posted as findings against the PR. This is the request-abort
+    // counterpart of the 3xx carve-out in isErrorResponseStatus: a real
+    // server/network fault still arrives with its own failure text and is kept.
+    if (isAbortedRequestFailure(f.failure)) continue;
     failures.push({
       kind: "request-failed",
       severity: MUST_FIX,

package/src/loop/ui-review-provision.mjs

@@ -37,6 +37,10 @@ const MUST_FIX = "must-fix";
  * @param {object} seams - Injected IO (all required except clock/log defaults).
  * @param {(a:{repoRoot:string,pr:number,branch?:string})=>Promise<{path:string,created:boolean,reused:boolean}>} seams.ensureWorktree
  * @param {(a:{worktreePath:string,repoRoot:string})=>{ok:boolean,message?:string,mainWorktreePath?:string|null}} seams.assertNotPrimary
+ * @param {(a:{worktreePath:string,repoRoot:string,pr:number})=>Promise<{ok:boolean,sha?:string|null,detail?:string}>} [seams.pinPrHead] -
+ *   Pin the worktree to the PR head and report the resolved SHA. Optional only
+ *   for back-compat: omitting it leaves the ref UNVERIFIED and is logged as such.
+ *   Runs after the primary-checkout guard, never before.
  * @param {(a:{repoRoot:string,worktreePath:string})=>Promise<{changed:boolean,detail:string}>} seams.detectDepDelta
  * @param {(a:{worktreePath:string})=>Promise<{ok:boolean,detail:string}>} seams.installDeps
  * @param {(worktreePath:string)=>Promise<object|null>} seams.resolveRunRecipe
@@ -58,6 +62,7 @@ export async function provisionAndBoot(
   {
     ensureWorktree,
     assertNotPrimary,
+    pinPrHead,
     detectDepDelta,
     installDeps,
     resolveRunRecipe,
@@ -111,6 +116,36 @@ export async function provisionAndBoot(
     );
   }
 
+  // 2b. Pin the worktree to the PR head, AFTER the primary-checkout guard above
+  //     (this checks out a ref, so it must never run in the primary checkout).
+  //     ensureWorktree resolves `branch` against what already exists, so the
+  //     default `pr-<n>` lands wherever that name happens to point — the base
+  //     branch when no remote carries it, and a same-named remote branch that
+  //     is not this PR's head when one does. A fork PR's head branch is on no
+  //     candidate remote at all. Reviewing the wrong commit still reports
+  //     ok:true, so pin the head explicitly and record the resolved SHA.
+  let headSha = null;
+  if (pinPrHead) {
+    const pin = await pinPrHead({ worktreePath, repoRoot, pr });
+    if (!pin?.ok) {
+      return stop(
+        `cannot pin PR head: ${pin?.detail ?? "unknown failure"}`,
+        {
+          kind: "pr-head-unpinned",
+          severity: MUST_FIX,
+          message: `the worktree could not be pinned to PR #${pr}'s head, so it cannot be reviewed as that PR: ${pin?.detail ?? "unknown failure"}`,
+        },
+        { worktreePath },
+      );
+    }
+    headSha = pin.sha ?? null;
+    record(`worktree pinned to PR head ${headSha ?? "(sha unknown)"}${pin.detail ? ` (${pin.detail})` : ""}`);
+  } else {
+    // Never silent: a caller without the seam gets an unverified ref, which is
+    // exactly the failure mode this step exists to close.
+    record("WARNING: PR head not pinned (no pinPrHead seam) — worktree ref is UNVERIFIED");
+  }
+
   // 3. Install only the dependency-lock delta vs. the primary checkout. No delta
   //    => deps are shared; installing anything would be a blind re-install.
   const delta = await detectDepDelta({ repoRoot, worktreePath });
@@ -256,6 +291,7 @@ export async function provisionAndBoot(
     worktreePath,
     created: wt.created,
     reused: wt.reused,
+    headSha,
     depInstall,
     migrations,
     boot: bootResult,

package/src/projects/resolve-project.mjs

@@ -139,7 +139,7 @@ function resolveProjectSelector(args) {
     : null;
   if (!projectRef && !projectTitle) {
     throw Object.assign(
-      new Error("--project is required (or set queue.board.number / queue.board.title in .devloops)"),
+      new Error("--project is required (or set tracker.board — or the deprecated queue.board — number / title in .devloops)"),
       { code: "INVALID_PROJECT" },
     );
   }