@dev-loops/core 1.0.2-slim.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.2-slim.0",
+  "version": "1.0.2",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -22,6 +22,7 @@
     "./debt/signal": "./src/debt/debt-signal.mjs",
     "./github/copilot-helpers": "./src/github/copilot-helpers.mjs",
     "./github/comment-id-guard": "./src/github/comment-id-guard.mjs",
+    "./github/closing-ref-guard": "./src/github/closing-ref-guard.mjs",
     "./github/gh": "./src/github/gh.mjs",
     "./github/issue-ops": "./src/github/issue-ops.mjs",
     "./github/ownership-helpers": "./src/github/ownership-helpers.mjs",

package/src/config/config.mjs

@@ -447,12 +447,34 @@ function boardRefConfig(ownerKey) {
     });
 }
 
+/**
+ * Logical board columns the queue status-column config recognizes. Mirrors
+ * LOGICAL_COLUMN in loop/queue-board-sync.mjs; kept inline (a frozen 4-value
+ * list) so this low-level config-schema module does not depend on
+ * queue-board-sync, which pulls in the projects/GitHub-access modules through
+ * its own imports. The two lists are pinned in lockstep by the schema test.
+ */
+const QueueLogicalColumn = z.enum(["next_up", "in_progress", "ready_for_review", "done"]);
+
 /** Queue mode config */
 const QueueConfig = z.strictObject({
   maxParallel: z.number().int().min(1).max(10).default(3).describe("Maximum queue items worked in parallel."),
   maxAutoFiledIssues: z.number().int().min(0).max(100).default(10).describe("Cap on auto-filed issues per run."),
   reDispatchMaxRetries: z.number().int().min(0).max(10).default(1).describe("Retries when re-dispatching a failed queue item."),
   archiveOlderThanDays: z.number().int().positive().describe("Archive done board items older than this many days.").optional(),
+  statusColumns: z
+    .strictObject({
+      next_up: z.string().trim().min(1).optional(),
+      in_progress: z.string().trim().min(1).optional(),
+      ready_for_review: z.string().trim().min(1).optional(),
+      done: z.string().trim().min(1).optional(),
+    })
+    .describe("Logical-column -> board display-name overrides. Consumed by loadStateColumnMap (loop/queue-board-sync.mjs).")
+    .optional(),
+  stateColumnMap: z
+    .record(z.string().trim().min(1), QueueLogicalColumn)
+    .describe("Loop-state -> known logical column overrides. Consumed by loadStateColumnMap (loop/queue-board-sync.mjs).")
+    .optional(),
 });
 
 /**

package/src/config/extension-defaults.yaml

@@ -195,6 +195,17 @@ gates:
   fanout:
     maxAnglesPerGroup: 3
     maxConcurrent: 4
+    # The table is global; a group is only emitted for a gate that actually
+    # resolves at least one of its angles, so a group naming preApproval-only
+    # angles is inert for the draft/spike gates (their angle sets never include
+    # these), and vice versa. The first four groups name draft-gate surfaces;
+    # the design-* and finalization groups name preApproval-exclusive angles so
+    # a grouped preApproval round collapses to one reviewer per group instead of
+    # scattering those angles across arbitrary auto-chunked leftover units.
+    # finalization names only correctness-final/ui-validation: contradiction-lens
+    # is deliberately NOT grouped here because it is also a draft-gate angle, and
+    # a global group naming it would peel it into a finalization unit in the draft
+    # gate too. It stays an auto-chunk leftover in both gates.
     groups:
       - name: docs-surface
         angles: [docs, link-check, config-drift, contract-surface]
@@ -204,6 +215,12 @@ gates:
         angles: [correctness, input-validation]
       - name: determinism-state
         angles: [determinism, state-concurrency]
+      - name: design-simplicity
+        angles: [dry, kiss, yagni, deep]
+      - name: design-solid
+        angles: [srp, soc, ocp, lsp, isp, dip]
+      - name: finalization
+        angles: [correctness-final, ui-validation]
   preApproval:
     angles:
       - name: dry

package/src/github/closing-ref-guard.mjs

@@ -0,0 +1,80 @@
+// Canonical closing-reference primitives shared by the create-pr / edit-pr
+// wrappers so both guard a body's closing reference against the branch's own
+// resolved issue with one implementation. A body swap that re-points the
+// reference at a different issue would otherwise pass silently, and a merge
+// would then close the wrong issue — this is the fail-closed backstop against
+// that data-integrity hole.
+
+import { extractClosingIssueNumbers as extractCanonicalClosingRefs } from "../loop/issue-refinement-artifact.mjs";
+
+// Every issue number the body's closing references name. Delegates to the ONE
+// canonical body-spec parser so the closing-keyword vocabulary (close/closes/
+// closed, fix/fixes/fixed, resolve/resolves/resolved, any case), the cross-repo
+// `owner/repo#N` form, fenced/inline-code stripping (a `Closes #N` inside a
+// ```fenced``` example or `inline code` span does not auto-close on GitHub and
+// must not spoof the guard), and de-duplication stay owned in ONE place — the
+// guard never re-implements them.
+export function extractClosingIssueNumbers(body) {
+  if (!body || typeof body !== "string") return [];
+  return extractCanonicalClosingRefs(body);
+}
+
+// True when the body carries any closing keyword.
+export function detectClosingKeyword(body) {
+  return extractClosingIssueNumbers(body).length > 0;
+}
+
+// The issue number from the body's first closing reference, or null when the
+// body carries none. Back-compat surface (create-pr's `--issue` missing-reference
+// check); the mismatch guard uses extractClosingIssueNumbers to see every one.
+export function extractClosingIssueNumber(body) {
+  const all = extractClosingIssueNumbers(body);
+  return all.length > 0 ? all[0] : null;
+}
+
+// Branch slug `[<prefix>/]issue-<N>[-<slug>]` -> N. Matches the dev-loop
+// worktree default branch name and the prefixed form (e.g. a `dl/`-prefixed
+// slug). Returns null when the branch encodes no issue number.
+const BRANCH_ISSUE_PATTERN = /(?:^|\/)issue-(\d+)(?:-|$)/u;
+export function extractIssueFromBranchSlug(branch) {
+  if (!branch || typeof branch !== "string") return null;
+  const match = BRANCH_ISSUE_PATTERN.exec(branch.trim());
+  return match ? Number(match[1]) : null;
+}
+
+// Resolve the issue a PR is expected to close from its own facts. The branch
+// slug is authoritative (it encodes the issue the loop cut the branch for);
+// the PR's GitHub-derived closingIssuesReferences is the fallback. Returns null
+// when neither yields an issue — a genuinely issue-less PR, which is exempt.
+export function resolveExpectedIssueFromPrContext(ctx) {
+  if (!ctx || typeof ctx !== "object") return null;
+  const fromBranch = extractIssueFromBranchSlug(ctx.headRefName);
+  if (fromBranch !== null) return fromBranch;
+  const refs = Array.isArray(ctx.closingIssuesReferences) ? ctx.closingIssuesReferences : [];
+  for (const ref of refs) {
+    const n = typeof ref === "number" ? ref : Number(ref?.number);
+    if (Number.isInteger(n) && n > 0) return n;
+  }
+  return null;
+}
+
+// Compare the body's closing reference against the branch's resolved issue.
+// Returns a named refusal string when they disagree, else null. A waiver
+// bypasses; an unresolved expected issue (issue-less) is exempt; a body with no
+// closing reference has nothing to mislink and is exempt (only a present-and-
+// disagreeing reference is refused, never a missing one).
+export function resolveClosingRefMismatch({ body, expectedIssue, allowCrossIssue = false }) {
+  if (allowCrossIssue) return null;
+  if (!Number.isInteger(expectedIssue)) return null;
+  const closing = extractClosingIssueNumbers(body);
+  if (closing.length === 0) return null;
+  // Refuse when ANY closing reference disagrees — GitHub closes every one, so a
+  // correct first reference does not excuse a wrong second (a single-issue
+  // dev-loop PR closes only its branch's issue; a deliberate multi/cross-issue
+  // reference uses the waiver).
+  const disagreeing = closing.find((n) => n !== expectedIssue);
+  if (disagreeing !== undefined) {
+    return `CLOSING-REF-BRANCH-MISMATCH: the body closes #${disagreeing} but the branch resolves to issue #${expectedIssue} — refusing a mismatched closing reference (pass --allow-cross-issue to record a deliberate cross-issue reference)`;
+  }
+  return null;
+}

package/src/loop/handoff-envelope.mjs

@@ -54,6 +54,16 @@ const STRATEGY_DEFAULT_STOP_RULES = Object.freeze({
   ],
 });
 
+const RECONCILIATION_ACCEPTANCE_TEMPLATE = deepFreeze({
+  criteria: [
+    { id: "reconcile", must: "Resolve the reported authoritative-state conflict before selecting or executing a strategy.", severity: "required" },
+  ],
+  evidence: ["commands-run", "validation-output"],
+  maxFinalizationTurns: 1,
+  needsAttentionAfterMs: DEFAULT_NEEDS_ATTENTION_MS,
+  activeNoticeAfterMs: DEFAULT_ACTIVE_NOTICE_MS,
+});
+
 // ---------------------------------------------------------------------------
 // Acceptance template table
 // ---------------------------------------------------------------------------
@@ -584,8 +594,45 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     throw new Error("handoff-envelope: resolverOutput is required and must be an object");
   }
 
-  const bundle = resolverOutput.bundle ?? resolverOutput;
-  const strategy = requireString(bundle.selectedStrategy, "resolverOutput.selectedStrategy");
+  const isWrapped = Object.hasOwn(resolverOutput, "bundle");
+  if (isWrapped && (!resolverOutput.bundle || typeof resolverOutput.bundle !== "object")) {
+    throw new Error("handoff-envelope: resolverOutput.bundle must be an object when present");
+  }
+  const bundle = isWrapped ? resolverOutput.bundle : resolverOutput;
+  const strategy = bundle.selectedStrategy === null
+    ? null
+    : requireString(bundle.selectedStrategy, "resolverOutput.selectedStrategy");
+  const routeKind = strategy === null
+    ? requireString(bundle.routeKind, "resolverOutput.routeKind")
+    : (trimmedOrNull(bundle.routeKind) ?? "route");
+  const selectedGate = trimmedOrNull(bundle.selectedGate);
+  const outerBundleKind = isWrapped ? trimmedOrNull(resolverOutput.bundleKind) : null;
+  const nestedBundleKind = trimmedOrNull(bundle.bundleKind);
+  if (outerBundleKind && nestedBundleKind && outerBundleKind !== nestedBundleKind) {
+    throw new Error(`handoff-envelope: outer bundleKind (${outerBundleKind}) and inner bundleKind (${nestedBundleKind}) must agree`);
+  }
+  const bundleKind = outerBundleKind ?? nestedBundleKind;
+  const isReconciliation = routeKind === "needs_reconcile"
+    && strategy === null
+    && selectedGate === "fail_closed_reconcile"
+    && bundleKind === "needs_reconcile";
+  if (isWrapped && isReconciliation && (
+    resolverOutput.bundleKind !== "needs_reconcile"
+    || bundle.bundleKind !== "needs_reconcile"
+    || resolverOutput.selectedStrategy !== "none"
+    || bundle.selectedStrategy !== null
+  )) {
+    throw new Error("handoff-envelope: wrapped needs_reconcile output requires exact outer and inner bundleKind needs_reconcile markers, outer selectedStrategy none, and inner selectedStrategy null");
+  }
+  if (bundleKind === "needs_reconcile" && !isReconciliation) {
+    throw new Error("handoff-envelope: outer/inner bundleKind needs_reconcile requires inner routeKind needs_reconcile, selectedGate fail_closed_reconcile, and selectedStrategy null");
+  }
+  if (routeKind === "needs_reconcile" && !isReconciliation) {
+    throw new Error("handoff-envelope: routeKind needs_reconcile requires outer bundleKind needs_reconcile, selectedGate fail_closed_reconcile, and selectedStrategy null");
+  }
+  if (strategy === null && !isReconciliation) {
+    throw new Error("handoff-envelope: a null resolverOutput.selectedStrategy is allowed only for the canonical needs_reconcile/fail_closed_reconcile tuple");
+  }
   const executionMode = requireString(bundle.executionMode, "resolverOutput.executionMode");
   const nextAction = requireString(bundle.nextAction, "resolverOutput.nextAction");
 
@@ -598,7 +645,9 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
   // profile instead of the default local-implementation gate. The spike
   // marker lives at the TOP level of the resolver output (the bundle does not
   // carry it), so it is read off `resolverOutput` directly.
-  const subGate = (strategy === INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION && isSpikeRun(resolverOutput))
+  const subGate = isReconciliation
+    ? selectedGate
+    : (strategy === INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION && isSpikeRun(resolverOutput))
     ? "spike"
     : resolveSubGate(strategy, gs);
   // Normalize each source independently, then fall back on the normalized result
@@ -609,10 +658,14 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
 
   const target = deriveTarget(bundle, repo);
   const requiredReads = deriveRequiredReads(bundle, resolverOutput);
-  const stopRules = deriveStopRules(settings, strategy);
+  const stopRules = isReconciliation
+    ? ["reconcile", ...(resolveHumanMergeOnly(settings) ? ["merge"] : [])]
+    : deriveStopRules(settings, strategy);
   const gateConfig = deriveGateConfig(settings, subGate);
   const derivedCwd = deriveCwd(bundle, { repoRoot: options.repoRoot, worktreeCwd: options.worktreeCwd });
-  const template = lookupAcceptanceTemplate(strategy, subGate);
+  const template = isReconciliation
+    ? RECONCILIATION_ACCEPTANCE_TEMPLATE
+    : lookupAcceptanceTemplate(strategy, subGate);
   // Lightweight PR-body-as-spec: retarget the phase-doc criterion
   // text to the PR description. Null/phase_doc leaves the criteria untouched, so
   // the non-lightweight path stays byte-identical.
@@ -650,6 +703,8 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     maxCopilotRounds: settings?.refinement?.maxCopilotRounds ?? 5,
     executionMode,
 
+    ...(isReconciliation ? { routeKind, selectedStrategy: null } : {}),
+
     nextAction,
     requiredReads,
 
@@ -660,7 +715,7 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     requireDraftFirst: settings?.workflow?.requireDraftFirst ?? false,
 
     cwd: derivedCwd,
-    worktreeRequired: true,
+    worktreeRequired: !isReconciliation,
 
     acceptance: {
       criteria: acceptanceCriteria,
@@ -832,6 +887,58 @@ export function validateHandoffEnvelope(envelope) {
     });
   }
 
+  // ----- terminal reconciliation tuple -----
+  // routeKind/selectedStrategy are omitted for ordinary routed envelopes to
+  // preserve the v1 shape. If either is present, both must identify the one
+  // supported no-strategy terminal envelope exactly; serialized/tampered
+  // envelopes receive the same fail-closed enforcement as the builder.
+  const hasRouteKind = Object.hasOwn(envelope, "routeKind");
+  const hasSelectedStrategy = Object.hasOwn(envelope, "selectedStrategy");
+  if (hasRouteKind || hasSelectedStrategy || envelope.currentGate === "fail_closed_reconcile") {
+    const reconciliationStopRulesAreCanonical = Array.isArray(envelope.stopRules)
+      && envelope.stopRules[0] === "reconcile"
+      && (envelope.stopRules.length === 1
+        || (envelope.stopRules.length === 2 && envelope.stopRules[1] === "merge"));
+    // Routing invariants only: acceptance prose remains the resolver's
+    // business, while nextAction must begin with one of the known fail-closed
+    // directives rather than arbitrary non-empty text.
+    const reconciliationCriterion = envelope.acceptance?.criteria;
+    const reconciliationAcceptanceIsCanonical = Array.isArray(reconciliationCriterion)
+      && reconciliationCriterion.some((criterion) => criterion?.id === "reconcile" && criterion?.severity === "required");
+    const normalizedNextAction = typeof envelope.nextAction === "string" ? envelope.nextAction.trim() : "";
+    const reconciliationNextActionIsActionable = [
+      "Reconcile ",
+      "Stop and reconcile ",
+      "Complete or explicitly skip ",
+      "Local implementation requires worktree isolation",
+    ].some((directive) => normalizedNextAction.startsWith(directive));
+    if (
+      envelope.routeKind !== "needs_reconcile"
+      || envelope.selectedStrategy !== null
+      || envelope.currentGate !== "fail_closed_reconcile"
+      || envelope.worktreeRequired !== false
+      || !reconciliationStopRulesAreCanonical
+      || !reconciliationAcceptanceIsCanonical
+      || !reconciliationNextActionIsActionable
+    ) {
+      errors.push({
+        field: "routeKind/selectedStrategy/currentGate/worktreeRequired/stopRules/acceptance.criteria",
+        reason: "terminal reconciliation must use the exact needs_reconcile / null / fail_closed_reconcile tuple, require no worktree, instruct reconciliation, stop at reconcile (plus optional merge), and carry a required reconcile acceptance criterion",
+        got: {
+          routeKind: envelope.routeKind,
+          selectedStrategy: envelope.selectedStrategy,
+          currentGate: envelope.currentGate,
+          worktreeRequired: envelope.worktreeRequired,
+          stopRules: envelope.stopRules,
+          nextAction: envelope.nextAction,
+          acceptanceCriteria: envelope.acceptance?.criteria,
+          acceptanceEvidence: envelope.acceptance?.evidence,
+          maxFinalizationTurns: envelope.acceptance?.maxFinalizationTurns,
+        },
+      });
+    }
+  }
+
   // ----- requiredReads -----
   if (!Array.isArray(envelope.requiredReads)) {
     errors.push({ field: "requiredReads", reason: "must be an array", got: envelope.requiredReads });

package/src/loop/issue-refinement-artifact.mjs

@@ -442,6 +442,24 @@ function rowIsSemantic(criterion, evidence) {
   return cellProseWordCount(criterion) >= 1 && cellProseWordCount(evidence) >= 1;
 }
 
+/**
+ * Resolve which columns hold the criterion and evidence by HEADER NAME, so a
+ * leading index column (`#`, `No`, `Idx`, empty, …) shifts the mapped columns
+ * off positions 0/1 without breaking detection. Returns `{ criterionCol,
+ * evidenceCol }` when both header families are named in distinct columns.
+ * Falls back to positions 0/1 for a matrix-heading table whose columns are not
+ * explicitly named (the pre-index-aware behavior); returns null otherwise.
+ */
+function resolveMatrixColumns(headerCells, underHeading) {
+  const criterionCol = headerCells.findIndex((h) => MATRIX_CRITERION_HEADER.test(h ?? ""));
+  const evidenceCol = headerCells.findIndex((h) => MATRIX_EVIDENCE_HEADER.test(h ?? ""));
+  if (criterionCol >= 0 && evidenceCol >= 0 && criterionCol !== evidenceCol) {
+    return { criterionCol, evidenceCol };
+  }
+  if (underHeading) return { criterionCol: 0, evidenceCol: 1 };
+  return null;
+}
+
 /**
  * Parse every GFM pipe table in a Markdown body (skipping fenced code spans via
  * the shared `stepFence`). Returns an array of
@@ -508,26 +526,27 @@ function parseMarkdownTables(body) {
  */
 export function detectAcDodMatrix(body = "") {
   const tables = parseMarkdownTables(body);
-  const candidates = tables.filter((t) => {
-    if (!Array.isArray(t.headerCells) || t.headerCells.length < 2) return false;
+  const candidates = [];
+  for (const t of tables) {
+    if (!Array.isArray(t.headerCells) || t.headerCells.length < 2) continue;
     const underHeading = typeof t.heading === "string" &&
       MATRIX_SECTION_PATTERNS.some((p) => p.test(t.heading));
-    const headerNamesMap =
-      MATRIX_CRITERION_HEADER.test(t.headerCells[0] ?? "") &&
-      MATRIX_EVIDENCE_HEADER.test(t.headerCells[1] ?? "");
-    return underHeading || headerNamesMap;
-  });
+    const cols = resolveMatrixColumns(t.headerCells, underHeading);
+    if (cols) candidates.push({ ...t, ...cols });
+  }
   if (candidates.length === 0) {
     return { found: false, valid: false, rowCount: 0, rows: [], reason: "No AC→DoD mapping matrix table found." };
   }
   // Prefer the first candidate that has >=1 semantic row; otherwise report the
   // first candidate as malformed.
   for (const table of candidates) {
+    const { criterionCol, evidenceCol } = table;
+    const minCells = Math.max(criterionCol, evidenceCol) + 1;
     const semanticRows = [];
     for (const cells of table.rows) {
-      if (cells.length < 2) continue;
-      const criterion = cells[0] ?? "";
-      const evidence = cells[1] ?? "";
+      if (cells.length < minCells) continue;
+      const criterion = cells[criterionCol] ?? "";
+      const evidence = cells[evidenceCol] ?? "";
       if (rowIsSemantic(criterion, evidence)) {
         semanticRows.push({ criterion, evidence });
       }
@@ -884,7 +903,7 @@ export const PR_BODY_SPEC_NARRATIVE_SECTIONS = Object.freeze({
 const CLOSING_ISSUE_REFERENCE_PATTERN =
   /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(?:[\w.-]+\/[\w.-]+)?#(\d+)/giu;
 
-function extractClosingIssueNumbers(body) {
+export function extractClosingIssueNumbers(body) {
   // Same fence-skip as sectionHasBody: a `Closes #N` line quoted inside a
   // ```fenced``` example (e.g. a PR-template sample) must not spoof the gate.
   let fence = null;

package/src/loop/retrospective-checkpoint.mjs

@@ -149,14 +149,13 @@ export function normalizeCheckpointCycleIdentity(identity) {
  * 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.
+ * when true, a newer PR merged into the configured base branch since the
+ * checkpoint's recorded discharge point (or ancestry/association could not
+ * be verified), so the checkpoint cannot cover the newer cycle — it fails
+ * closed to MISSING. The caller derives the boolean itself (this module stays
+ * pure/I/O-free) from local git ancestry plus authoritative commit-to-PR
+ * association, 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

package/src/loop/worktree-guard.mjs

@@ -35,12 +35,13 @@ export function isUnderWorktreePath(cwd) {
  * @returns {string | null} The main worktree path, or null if it cannot be parsed.
  */
 export function parseMainWorktreePath(worktreeListOutput) {
-  const firstLine = worktreeListOutput.split("\n")[0].trim();
-  if (!firstLine) return null;
-  // Find the first hex SHA (7+ chars) preceded by whitespace; take everything before it as the path.
-  const shaIdx = firstLine.search(/\s[0-9a-f]{7,64}\b/iu);
-  if (shaIdx === -1) return null;
-  return firstLine.slice(0, shaIdx).trim();
+  // The main worktree is the FIRST parseable entry — derived from the same
+  // parser `parseAllWorktreePaths` uses, so the two can never disagree about
+  // which path is the main checkout. Parsing only the raw first line would
+  // return null on a leading blank/SHA-less line while `parseAllWorktreePaths`
+  // still parses the real main line, nulling the main-checkout guard while the
+  // path stays admittable (the leading-blank-line fail-open).
+  return parseAllWorktreePaths(worktreeListOutput)[0] ?? null;
 }
 
 /**
@@ -115,10 +116,15 @@ export function isListedWorktree(cwd, worktreePaths) {
 /**
  * Resolve the root of the listed git worktree that contains `cwd`.
  *
- * Mirrors `isListedWorktree`'s matching (realpath-resolved, tmp/worktrees/-scoped,
- * exact-or-subdirectory) but returns the worktree ROOT instead of a boolean, so
- * callers can address files relative to the worktree's own subtree (`packages/`,
- * `node_modules/`) rather than the possibly-nested `cwd`.
+ * Returns the worktree ROOT (realpath-resolved, exact-or-subdirectory match)
+ * instead of a boolean, so callers can address files relative to the worktree's
+ * own subtree (`packages/`, `node_modules/`) rather than the possibly-nested
+ * `cwd`. Matches ANY listed worktree — not just `tmp/worktrees/`-scoped ones —
+ * so the core-isolation invariant is evaluable for a sibling/linked checkout
+ * that lives outside `tmp/worktrees/`; the caller decides admit/reject.
+ * When `cwd` sits under nested worktrees (a `tmp/worktrees/` child inside its
+ * parent checkout), the LONGEST matching root wins, so the innermost worktree's
+ * own subtree is addressed regardless of `git worktree list` order.
  *
  * @param {string} cwd - Absolute or relative path inside the worktree.
  * @param {string[]} worktreePaths - Array of paths from `parseAllWorktreePaths`.
@@ -128,16 +134,16 @@ export function resolveContainingWorktreeRoot(cwd, worktreePaths) {
   let resolvedCwd;
   try { resolvedCwd = realpathSync(cwd); } catch { resolvedCwd = cwd; }
   const normalizedCwd = resolvedCwd.replace(/\\/g, "/").replace(/\/+$/u, "");
+  let best = null;
   for (const p of worktreePaths) {
     let resolvedP;
     try { resolvedP = realpathSync(p); } catch { resolvedP = p; }
     const normalizedP = resolvedP.replace(/\\/g, "/").replace(/\/+$/u, "");
-    if (!isUnderWorktreePath(normalizedP)) continue;
     if (normalizedCwd === normalizedP || normalizedCwd.startsWith(normalizedP + "/")) {
-      return normalizedP;
+      if (best === null || normalizedP.length > best.length) best = normalizedP;
     }
   }
-  return null;
+  return best;
 }
 
 /**
@@ -191,6 +197,67 @@ export function isWorktreeCoreIsolated(cwd, worktreePaths) {
   return linkReal === coreReal;
 }
 
+/**
+ * Shared admit/reject decision for local-implementation worktree isolation.
+ *
+ * The single source of truth both enforcement sites route through
+ * (`pre-flight-gate.mjs` `checkWorktreeIsolation` and
+ * `resolve-dev-loop-startup.mjs`'s `local_implementation` block), so they
+ * cannot diverge. Each caller maps the returned `error`/`detail` to its own
+ * guidance/reason wording; this function owns only the decision.
+ *
+ * `tmp/worktrees/` stays the default and recommended location, but it is not
+ * the invariant. The real invariant is core isolation: a checkout's
+ * `node_modules/@dev-loops/core` resolves to its OWN `packages/core`.
+ * A checkout OUTSIDE `tmp/worktrees/` that is not the main checkout and
+ * satisfies that invariant is admitted rather than rejected on path prefix
+ * alone; one that does not satisfy it (its core link escapes its own
+ * `packages/core`) fails closed.
+ *
+ * Decision order:
+ *  - outside `tmp/worktrees/` + main checkout  -> reject `main_checkout_detected`
+ *  - outside `tmp/worktrees/` + unresolvable worktree root -> reject `not_in_worktree` (fail closed, no vacuous admit)
+ *  - outside `tmp/worktrees/` + core-isolated  -> ADMIT (verified-isolation)
+ *  - outside `tmp/worktrees/` + not isolated   -> reject `not_in_worktree`
+ *  - under `tmp/worktrees/` + not a real worktree -> reject `not_in_worktree`
+ *  - under `tmp/worktrees/` + core link escapes -> reject `core_link_escapes`
+ *  - otherwise -> ADMIT
+ *
+ * @param {object} params
+ * @param {string} params.cwd - Current working directory (absolute or relative).
+ * @param {string | null} params.mainWorktreePath - From `parseMainWorktreePath`.
+ * @param {string[]} params.allWorktreePaths - From `parseAllWorktreePaths`.
+ * @returns {{ ok: true } | { ok: false, error: string, detail: string }}
+ */
+export function classifyWorktreeIsolation({ cwd, mainWorktreePath, allWorktreePaths }) {
+  if (!isUnderWorktreePath(cwd)) {
+    if (mainWorktreePath !== null && isMainCheckout(cwd, mainWorktreePath)) {
+      return { ok: false, error: "main_checkout_detected", detail: "main_checkout" };
+    }
+    // Outside tmp/worktrees and not the main checkout: assert the REAL
+    // core-isolation invariant instead of rejecting on path prefix alone.
+    // The invariant is only meaningful for a checkout that resolves to a real
+    // listed git worktree root; when the root cannot be resolved (an unlisted
+    // checkout, or an empty/unparseable `git worktree list` — which also nulls
+    // mainWorktreePath and skips the main-checkout guard above) the core-isolation
+    // check would vacuously return true, so fail closed rather than admit.
+    if (resolveContainingWorktreeRoot(cwd, allWorktreePaths) === null) {
+      return { ok: false, error: "not_in_worktree", detail: "outside_not_isolated" };
+    }
+    if (isWorktreeCoreIsolated(cwd, allWorktreePaths)) {
+      return { ok: true };
+    }
+    return { ok: false, error: "not_in_worktree", detail: "outside_not_isolated" };
+  }
+  if (!isListedWorktree(cwd, allWorktreePaths)) {
+    return { ok: false, error: "not_in_worktree", detail: "fake_worktree" };
+  }
+  if (!isWorktreeCoreIsolated(cwd, allWorktreePaths)) {
+    return { ok: false, error: "core_link_escapes", detail: "core_escapes" };
+  }
+  return { ok: true };
+}
+
 
 /**
  * Realpath-normalize a path that MAY NOT EXIST yet.