@dev-loops/core 1.0.0 → 1.0.2-pre.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.0",
+  "version": "1.0.2-pre.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -35,6 +35,7 @@
     "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
     "./loop/copilot-loop-state": "./src/loop/copilot-loop-state.mjs",
     "./loop/gate-carry-forward": "./src/loop/gate-carry-forward.mjs",
+    "./loop/gate-evidence-reconcile": "./src/loop/gate-evidence-reconcile.mjs",
     "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
@@ -67,6 +68,7 @@
     "./loop/run-context": "./src/loop/run-context.mjs",
     "./loop/run-inspection": "./src/loop/run-inspection.mjs",
     "./loop/run-post-merge-actions": "./src/loop/run-post-merge-actions.mjs",
+    "./loop/spec-authority": "./src/loop/spec-authority.mjs",
     "./loop/spike-exit-contract": "./src/loop/spike-exit-contract.mjs",
     "./loop/spike-intake-contract": "./src/loop/spike-intake-contract.mjs",
     "./loop/steering": "./src/loop/steering.mjs",
@@ -100,7 +102,7 @@
     "bin/**/*.mjs"
   ],
   "scripts": {
-    "test": "node --test ./test/*.test.mjs"
+    "test": "bun ../../scripts/run-bun-test.mjs ./test/*.test.mjs"
   },
   "publishConfig": {
     "access": "public",

package/src/claude/hook-decisions.mjs

@@ -369,6 +369,99 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
   };
 }
 
+/**
+ * Env var that authorizes a deliberate main-checkout mutation while a worktree
+ * cycle is active. Reuses the existing default-branch-guard override
+ * (`DEVLOOPS_ALLOW_MAIN`, GUARD_OVERRIDE_ENV) — both mean "I intend to operate on
+ * the primary checkout on purpose" — so the operator surface stays one flag.
+ */
+export const WORKTREE_CHECKOUT_GUARD_OVERRIDE_ENV = "DEVLOOPS_ALLOW_MAIN";
+
+/**
+ * Decide whether a PreToolUse Write/Edit is a WRONG-CHECKOUT mutation: the call
+ * context is operating inside a linked worktree (the active cycle worktree) but
+ * the target resolves to a TRACKED file in the MAIN checkout instead of that
+ * worktree.
+ *
+ * After `ensure-worktree.mjs` establishes an isolated worktree for a cycle, an
+ * absolute-path `Edit`/`Write` that names the main-checkout copy of a source
+ * file lands the change on the wrong checkout — silently, until a `git status`
+ * in the worktree turns up empty (observed in practice: six edits hit main
+ * before a self-caught restore). This guard catches that before it reaches a commit.
+ *
+ * The "active worktree" is anchored to the CALL CONTEXT's cwd, not to a durable
+ * marker: this repo accumulates many stale `tmp/worktrees/` worktrees, so "a
+ * worktree exists" cannot mean "a cycle is active". The worktree that CONTAINS
+ * cwd is the one this context is driving; a write escaping it into main is the
+ * wrong-checkout mistake.
+ *
+ * The hook resolves the facts (via the shared `worktree-guard.mjs` primitives)
+ * and passes booleans so this decider stays pure and unit-testable:
+ * - `activeWorktreeRoot`: the listed worktree root containing cwd, or null when
+ *   cwd is not inside any worktree (no active cycle context — AC3).
+ * - `isTargetUnderActiveWorktree`: the target resolves inside that worktree (a
+ *   legitimate in-worktree edit — AC2).
+ * - `isMainCheckoutTracked`: the target resolves under the main checkout AND is
+ *   a tracked (non-gitignored) file. The hook sets this true when the status is
+ *   UNRESOLVABLE (e.g. `git check-ignore` errored) so an ambiguous context fails
+ *   safe rather than silently allowing a wrong-checkout write (AC4).
+ * - `allowMainCheckout`: the deliberate-override signal (`DEVLOOPS_ALLOW_MAIN=1`)
+ *   for an intended main-checkout edit (AC3).
+ *
+ * @param {Object} params
+ * @param {string} params.filePath - Target file path (as supplied to the tool).
+ * @param {string|null} [params.activeWorktreeRoot] - Listed worktree root containing cwd, or null.
+ * @param {boolean} [params.isTargetUnderActiveWorktree] - Target is inside the active worktree.
+ * @param {boolean} [params.isMainCheckoutTracked] - Target is a tracked main-checkout file (or unresolvable).
+ * @param {boolean} [params.allowMainCheckout] - Deliberate override (DEVLOOPS_ALLOW_MAIN=1).
+ * @param {string|null} [params.suggestedWorktreePath] - The worktree-local path the write should target.
+ * @returns {HookDecision}
+ */
+export function decideWorktreeCheckoutGuard({
+  filePath,
+  activeWorktreeRoot = null,
+  isTargetUnderActiveWorktree = false,
+  isMainCheckoutTracked = false,
+  allowMainCheckout = false,
+  suggestedWorktreePath = null,
+}) {
+  // No active worktree context — this is the main checkout / orchestrator / a
+  // consumer repo's own interactive dev. A main-checkout edit is intended here
+  // (AC3). Also the only path that runs for repos never using dev-loop worktrees.
+  if (!activeWorktreeRoot) {
+    return ALLOW;
+  }
+  // Deliberate, operator-authorized main-checkout write during an active cycle (AC3).
+  if (allowMainCheckout) {
+    return ALLOW;
+  }
+  // Legitimate in-worktree edit — no false positive (AC2).
+  if (isTargetUnderActiveWorktree) {
+    return ALLOW;
+  }
+  // Outside the active worktree AND not a tracked main-checkout file: a scratch
+  // path (/tmp), a gitignored path, another worktree's file, or outside the repo
+  // entirely — none is the wrong-checkout mistake this guard exists to catch.
+  if (!isMainCheckoutTracked) {
+    return ALLOW;
+  }
+  // A worktree cycle is active and the target is a tracked main-checkout file
+  // (or an unresolvable/ambiguous context that fails safe — AC4). This is a
+  // wrong-checkout mutation (AC1).
+  const fix = suggestedWorktreePath
+    ? ` Edit the worktree copy instead: "${suggestedWorktreePath}".`
+    : "";
+  return {
+    decision: "deny",
+    reason:
+      `WORKTREE-WRONG-CHECKOUT-GUARD: wrong-checkout mutation blocked — a worktree cycle is active ` +
+      `("${activeWorktreeRoot}") but this Write/Edit targets the MAIN checkout's non-gitignored file ` +
+      `"${filePath}".${fix} A file mutation that lands on the main checkout while a worktree is ` +
+      "active is silently lost from the branch. Set DEVLOOPS_ALLOW_MAIN=1 only for a deliberate " +
+      "main-checkout edit. See skills/docs/worktree-guidance.md.",
+  };
+}
+
 /**
  * Env var that exempts an interactive session awaiting commit authorization from the
  * SubagentStop uncommitted-work guard (#1619).
@@ -384,21 +477,26 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
 export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
 
 /**
- * Env var that exempts an orchestrator-owned-commit dispatch from the SubagentStop
- * uncommitted-work guard (#1786).
+ * Subagent roles whose contract forbids committing to the repository (#1925).
  *
- * A "LOCAL EDITS ONLY: no commit" dispatch (e.g. the `developer`/`quality`/`docs` delegation
- * pattern in `skills/local-implementation/SKILL.md` "Delegation contract") tells the subagent to
- * make local edits and report changed files, leaving commit + push to the dispatching
- * orchestrator once it consolidates results. Without an exemption, that subagent's own
- * SubagentStop event still sees the dirty worktree it was told not to commit and deadlocks. The
- * dispatcher sets `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` for that dispatch to declare it owns the
- * commit — same opt-in `DEVLOOPS_*` signal shape as `DEVLOOPS_COMMIT_AUTH_PENDING`, but distinct:
- * this one exempts a non-interactive delegated dispatch whose commit responsibility sits with its
- * caller, not an interactive session awaiting operator authorization. Left unset, an ordinary
- * dispatch's commit-before-exit obligation stays enforced (fail closed by default).
+ * The `judge` and `review` agents are read-only over the repository: the judge writes only its
+ * own verdict artifact (under `tmp/`, gitignored) and the gate reviewer writes only its findings
+ * artifact (also under `tmp/`) — neither ever authors a tracked-file edit. So any uncommitted
+ * tracked change present in such a subagent's worktree is FOREIGN: it belongs to the orchestrator
+ * that dispatched it (a pending orchestrator edit that was in the shared worktree when the
+ * read-only pass ran), not to the read-only subagent. `LOCAL-COMMIT-BEFORE-EXIT` must not force
+ * one of these roles to author a commit of that foreign work — doing so violates the verdict-only
+ * contract (`agents/judge.agent.md`: "The only thing you write is your own verdict artifact").
+ * The data-loss protection is enforced against the OWNER of the edit (the orchestrator) on its own
+ * stop instead. This is intentionally scoped to read-only roles: editing roles (`developer`,
+ * `fixer`, `docs`, `quality`) and the orchestrator stay enforced (#1925 non-goal).
  */
-export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT";
+export const READONLY_SUBAGENT_ROLES = Object.freeze(["judge", "review"]);
+
+/** Whether `agentType` (Claude `agent_type` from the SubagentStop payload) is a read-only role. */
+export function isReadOnlySubagentRole(agentType) {
+  return typeof agentType === "string" && READONLY_SUBAGENT_ROLES.includes(agentType);
+}
 
 /**
  * Decide whether a SubagentStop must be blocked because the subagent's worktree has
@@ -408,10 +506,19 @@ export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS
  * uncommitted changes in a worktree are destroyed with no warning. `LOCAL-COMMIT-BEFORE-EXIT`
  * existed only as prose. This decider makes it mechanical: refuse the subagent stop when the
  * cwd is under `tmp/worktrees/` and `git status --porcelain` is non-empty, unless the session
- * is an interactive one awaiting commit authorization, or the dispatch is an explicit
- * orchestrator-owned-commit exemption (#1786) (either exempt). A clean worktree, a cwd
+ * is an interactive one awaiting commit authorization (exempt). A clean worktree, a cwd
  * outside `tmp/worktrees/`, and a git-error/empty-porcelain case all allow the stop.
  *
+ * Editing roles (`developer`/`fixer`/`docs`/`quality`) stay fully enforced: an editing
+ * sub-delegate commits its own work before exit (`LOCAL-COMMIT-BEFORE-EXIT`), so a dirty exit is
+ * always a real defect, never a sanctioned "orchestrator owns the commit" split. The removed
+ * `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT` env-var exemption (#1786) deadlocked such a role under a
+ * task-scoped no-commit instruction whenever the orchestrator could not set a per-dispatch env
+ * var (the Claude harness): the hook demanded a commit the session then denied, then re-blocked
+ * the exit (#1936). Disallowing the edit-here/commit-there split at the contract level makes the
+ * guard the enforcer and the deadlock structurally impossible while preserving data-loss
+ * protection. An orchestrator that wants one consolidated commit performs the edits itself.
+ *
  * Pure and side-effect free. The hook script gathers `cwd` and the `git status --porcelain`
  * output and calls this; the block decision is surfaced via exit code 2 + stderr JSON by the
  * hook (the SubagentStop contract differs from PreToolUse's `permissionDecision` form).
@@ -424,21 +531,38 @@ export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS
  * @param {boolean} [params.pendingCommitAuthorization] - True when the interactive session is
  *   awaiting commit authorization (exempt) — derived by the hook script from the
  *   `DEVLOOPS_COMMIT_AUTH_PENDING=1` opt-in env signal.
- * @param {boolean} [params.orchestratorOwnsCommit] - True when this dispatch is an explicit
- *   orchestrator-owned-commit exemption (exempt) — derived by the hook script from the
- *   `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` opt-in env signal.
+ * @param {string|null} [params.agentType] - Claude `agent_type` from the SubagentStop payload;
+ *   a read-only role (`judge`/`review`, per `READONLY_SUBAGENT_ROLES`) is exempt (#1925) — its
+ *   contract forbids commits, so any dirty tracked edit in its worktree is foreign
+ *   (orchestrator-owned) and must not be pinned on it.
  * @returns {HookDecision}
  */
-export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, orchestratorOwnsCommit = false }) {
+export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, agentType = null }) {
   if (typeof cwd !== "string" || !isUnderWorktreePath(cwd)) {
     return ALLOW;
   }
-  if (pendingCommitAuthorization || orchestratorOwnsCommit) {
+  if (pendingCommitAuthorization) {
     return ALLOW;
   }
   if (typeof porcelain !== "string" || porcelain.trim() === "") {
     return ALLOW;
   }
+  // Read-only role exemption (#1925): the worktree is dirty, but a `judge`/`review` subagent's
+  // contract forbids commits, so this pending tracked edit is foreign — it belongs to the
+  // orchestrator that dispatched this pass. Do not force a verdict-only role to commit it; allow
+  // the stop with an advisory naming the orchestrator as the actor responsible for the edit. The
+  // data-loss guard still fires against the orchestrator on its own (editing) stop.
+  if (isReadOnlySubagentRole(agentType)) {
+    return {
+      decision: "allow",
+      advisory: true,
+      reason:
+        `LOCAL-COMMIT-BEFORE-EXIT exempt for read-only role "${agentType}": the worktree has ` +
+        "uncommitted changes, but a verdict-only role must not author a commit of work it did not " +
+        "create. This pending edit is foreign — the ORCHESTRATOR that dispatched this pass owns it " +
+        "and is responsible for committing it before its own stop.",
+    };
+  }
   const dirty = porcelain
     .split("\n")
     .map((l) => l.trim())

package/src/config/config.mjs

@@ -563,17 +563,11 @@ function boardRefConfig(ownerKey) {
     });
 }
 
-const QueueBoardConfig = boardRefConfig("queue.board");
-
 /** 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."),
-  // Deprecated: superseded by `tracker.board` (issue #1408, the tracker-agnostic
-  // seam). Kept accepted for back-compat — see resolveTrackerBoard, which reads
-  // `tracker.board` first and falls back to this field with a load-time warning.
-  board: QueueBoardConfig.describe("Deprecated: use tracker.board instead. GitHub Projects board identifier.").optional(),
   archiveOlderThanDays: z.number().int().positive().describe("Archive done board items older than this many days.").optional(),
 });
 
@@ -583,7 +577,7 @@ const QueueConfig = z.strictObject({
  * at `resolveTrackerAdapter` call time, not at config-parse time — the
  * seam/resolver must not preclude a consumer registering an external
  * provider post-1.0 (`plugin`, reserved, not implemented in this pass).
- * `board` supersedes the deprecated `queue.board` (see resolveTrackerBoard).
+ * `board` is the canonical GitHub Projects board identifier (see resolveTrackerBoard).
  *
  * No generic `fieldMappings` (logical-column -> provider-status) key here:
  * the github provider's logical-column -> Status mapping IS the existing,
@@ -598,7 +592,7 @@ const QueueConfig = z.strictObject({
 const TrackerConfig = z.strictObject({
   provider: z.string().trim().min(1).describe("Tracker provider registry key. Built-in: \"github\" (default).").optional(),
   plugin: z.string().trim().min(1).describe("Reserved: module specifier for an external tracker provider plugin (post-1.0, not implemented in this pass).").optional(),
-  board: boardRefConfig("tracker.board").describe("Tracker board identifier; supersedes the deprecated queue.board.").optional(),
+  board: boardRefConfig("tracker.board").describe("Tracker board identifier.").optional(),
 });
 
 /**
@@ -940,13 +934,11 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
     maxParallel: 3,
     maxAutoFiledIssues: 10,
     reDispatchMaxRetries: 1,
-    // queue.board is intentionally absent from defaults — setting it is an
-    // explicit operator opt-in for Projects-based queue ordering.
   }),
   tracker: Object.freeze({
     provider: "github",
     // tracker.board is intentionally absent from defaults — setting it is an
-    // explicit operator opt-in (mirrors queue.board). The logical-column ->
+    // explicit operator opt-in for Projects-based queue ordering. The logical-column ->
     // Status mapping is queue.statusColumns (see TrackerConfig above), not a
     // tracker-owned default.
   }),
@@ -1285,7 +1277,7 @@ export function resolveRoleModel(config, { role, harness, kind } = {}) {
  * @typedef {object} ConfigLoadError
  * @property {string} path - Human-readable file path or layer name
  * @property {string} message - Error description
- * @property {"defaults"|"settings"|"extensionDefaults"|"merged"} layer - Which config layer failed
+ * @property {"extensionDefaults"|"defaults"|"devloops"|"merged"} layer - Which config layer failed
  */
 
 // ============================================================================
@@ -1499,10 +1491,11 @@ function configError(message, code, filePath) {
 }
 
 /**
- * Try to load and merge one config layer (defaults or settings).
+ * Try to load and merge one config layer (extensionDefaults, defaults, or
+ * devloops).
  * @param {Record<string, unknown>} merged - Current merged config
  * @param {string|string[]} basePaths - Config file base path(s) without extension
- * @param {"defaults"|"settings"} layer - Layer name
+ * @param {"extensionDefaults"|"defaults"|"devloops"} layer - Layer name
  * @param {string[]} warnings
  * @param {ConfigLoadError[]} errors
  * @param {{ warnOnMissing?: boolean }} [options]
@@ -1628,7 +1621,7 @@ async function applyLayer(merged, basePaths, layer, warnings, errors, options =
 
 /**
  * Load the dev-loop configuration with full precedence:
- *   settings.(yaml|yml|json) > legacy overrides.(yaml|yml|json) > repo .pi/dev-loop/defaults.(yaml|yml|json) > extension defaults > built-in defaults
+ *   repo .devloops > repo .pi/dev-loop/defaults.(yaml|yml|json) > extension defaults > built-in defaults
  *
  * Never throws for config-related problems.
  * Returns extension defaults (with built-in defaults as the final fallback) even when all repo-local config files are missing or broken.
@@ -1641,7 +1634,6 @@ export async function loadDevLoopConfig(options = {}) {
   const configDir = path.join(repoRoot, ".pi", "dev-loop");
   const defaultsPath = path.join(configDir, "defaults");
   const devloopsPath = path.join(repoRoot, ".devloops");
-  const settingsPaths = [path.join(configDir, "settings"), path.join(configDir, "overrides")];
 
   /** @type {string[]} */
   const warnings = [];
@@ -1678,79 +1670,7 @@ export async function loadDevLoopConfig(options = {}) {
 
   if (primaryExists) {
     // .devloops is the primary override — apply it
-    merged = await applyLayer(merged, devloopsPath, "settings", warnings, errors);
-
-    // Warn if legacy files still exist alongside .devloops (but don't load them —
-    // .devloops is authoritative; legacy must not override it)
-    let legacyAlongside = false;
-    for (const legacyPath of settingsPaths) {
-      for (const ext of [".yaml", ".yml", ".json"]) {
-        try {
-          await readFile(legacyPath + ext, "utf8");
-          legacyAlongside = true;
-          break;
-        } catch (err) {
-          if (err?.code !== "ENOENT") {
-            // File exists but is unreadable — treat as "found" so the
-            // deprecation warning fires (applyLayer is not called for legacy
-            // paths when .devloops is present, so the flag only controls the warning).
-            legacyAlongside = true;
-            break;
-          }
-        }
-      }
-      if (legacyAlongside) break;
-    }
-    if (legacyAlongside) {
-      warnings.push(
-        `Deprecated config path(s) found under .pi/dev-loop/settings.* or .pi/dev-loop/overrides.*. ` +
-        `Migrate to .devloops (or .devloops.yaml/.devloops.yml/.devloops.json) at repo root. ` +
-        `Legacy paths will be removed in a future version.`
-      );
-    }
-  } else {
-    // No .devloops — fall back to legacy .pi/dev-loop/settings.* or overrides.* (deprecated)
-    let legacyFound = false;
-    for (const legacyPath of settingsPaths) {
-      for (const ext of [".yaml", ".yml", ".json"]) {
-        try {
-          await readFile(legacyPath + ext, "utf8");
-          legacyFound = true;
-          break;
-        } catch (err) {
-          if (err?.code !== "ENOENT") {
-            // File exists but is unreadable — treat as "found" so the
-            // deprecation warning fires and applyLayer can surface the error
-            // (legacy applyLayer runs in this branch).
-            legacyFound = true;
-            break;
-          }
-        }
-      }
-      if (legacyFound) break;
-    }
-    if (legacyFound) {
-      warnings.push(
-        `Deprecated config path(s) found under .pi/dev-loop/settings.* or .pi/dev-loop/overrides.*. ` +
-        `Migrate to .devloops (or .devloops.yaml/.devloops.yml/.devloops.json) at repo root. ` +
-        `Legacy paths will be removed in a future version.`
-      );
-      merged = await applyLayer(merged, settingsPaths, "settings", warnings, errors);
-    }
-  }
-
-  // Deprecated `queue.board` -> `tracker.board` alias (issue #1408, the
-  // tracker-agnostic seam). Runs on the fully-merged object (unlike the
-  // `strategy: "github-first"` alias above, this only affects cross-layer
-  // MERGE PRECEDENCE, not per-layer schema validity — queue.board is still a
-  // valid FileConfigSchema shape on its own — so normalizing once here, after
-  // every layer has merged, is sufficient).
-  if (isPlainObject(merged.queue?.board) && !isPlainObject(merged.tracker?.board)) {
-    warnings.push(
-      `queue.board is a deprecated alias for tracker.board (issue #1408). ` +
-      `Update .devloops to set tracker.board instead; the alias will be removed in a future version.`
-    );
-    merged = { ...merged, tracker: { ...(merged.tracker ?? {}), board: merged.queue.board } };
+    merged = await applyLayer(merged, devloopsPath, "devloops", warnings, errors);
   }
 
   // Validate final merged config
@@ -3085,19 +3005,13 @@ export function resolveTrackerProvider(config) {
 }
 
 /**
- * Resolve the effective tracker board identifier. `tracker.board` is
- * canonical; `queue.board` is a DEPRECATED alias, already normalized onto
- * `tracker.board` by `loadDevLoopConfig` (with a load-time warning) for any
- * config that went through the loader. This resolver also accepts a
- * hand-built config object that sets `queue.board` directly (bypassing the
- * loader, e.g. in a test) and falls back to it — with no warning, since only
- * the loader surfaces warnings.
+ * Resolve the effective tracker board identifier. `tracker.board` is the
+ * canonical (and only) board config key.
  *
  * @param {DevLoopConfig} config
  * @returns {{ number?: number, title?: string } | null}
  */
 export function resolveTrackerBoard(config) {
   if (isPlainObject(config?.tracker?.board)) return config.tracker.board;
-  if (isPlainObject(config?.queue?.board)) return config.queue.board;
   return null;
 }

package/src/config/extension-defaults.yaml

@@ -65,7 +65,7 @@ gates:
       - name: config-drift
         persona: review
         prompt: |-
-          Cross-check config, schema, and documentation for contract drift: - Verify that configuration files (.pi/dev-loop/settings.yaml,
+          Cross-check config, schema, and documentation for contract drift: - Verify that configuration files (.devloops,
             package.json, CI workflows, skill manifests) agree on canonical
             status tokens, support floors, and required flags.
           - Flag any instance where two sources of truth disagree about the
@@ -199,7 +199,7 @@ gates:
       - name: docs-surface
         angles: [docs, link-check, config-drift, contract-surface]
       - name: process
-        angles: [scope, pr-description, gate-evidence, pr-checklist-matrix]
+        angles: [scope, pr-description, gate-evidence, pr-checklist]
       - name: correctness-input
         angles: [correctness, input-validation]
       - name: determinism-state
@@ -259,13 +259,24 @@ gates:
       - name: docs
         persona: docs
         prompt: "Review documentation correctness for the current change. Check that relative markdown links resolve, symlink-backed doc pointers resolve, navigable doc references are actual markdown links rather than bare backtick path mentions, command/script references still exist and use current names, and index/surface references match the current file tree. Also flag stale command references: removed or renamed npm scripts, CLI commands, or tool invocations that no longer match the current codebase. When the repo provides `scripts/docs/validate-links.mjs`, use it for the mechanical link pass; otherwise keep the review scoped to the touched doc surface and current change only."
-      - name: pr-checklist-matrix
+      - name: pr-checklist
         mandatory: true
         persona: review
         prompt: |-
-          Verify before approval that the PR checklist and AC/DoD/non-goals matrix are complete. - Every PR checkbox (`- [ ]`) must be checked. If any box is unchecked, flag it as a blocking finding. - The PR body must contain an AC/DoD/non-goals matrix that maps each acceptance criterion
-            to its definition-of-done item(s) and lists explicit non-goals.
-          - The matrix must have a markdown table with at least a header row and one content row. - Flag the matrix as incomplete if any acceptance criterion, definition-of-done item, or non-goal is missing.
+          Verify the PR carries self-contained list-form Acceptance criteria and Definition of done
+          CHECKLISTS (never a matrix/table on the PR, never checkboxes inside table cells) that are
+          faithfully DERIVED from the linked issue's authoritative AC→DoD mapping matrix (#1951).
+          Completeness is enforced deterministically (#1877): the pre_approval_gate fails closed on any
+          unchecked `- [ ]` in the PR body's AC/DoD checklist, so this angle's completeness duty is
+          machine-backed. Your remaining duty is TRUTHFULNESS + DERIVATION FIDELITY, which the machine
+          cannot check: verify that every checked `- [x]` box in the PR body's Acceptance criteria /
+          Definition of done checklists is actually satisfied by the implementation — cite concrete
+          code/test/behavior evidence; flag a dishonestly-ticked box as a blocking finding. Verify the
+          PR checklists faithfully reflect the issue matrix (every matrix row is represented, nothing
+          invented or dropped) and that declared non-goals are respected (no scope creep). Do NOT
+          require a matrix on the PR — the matrix lives on the issue; the PR carries the derived
+          checklists. The boundary is explicit: the deterministic block enforces completeness (nothing
+          left unchecked/forgotten); you verify each [x] is real and faithfully derived.
       - contradiction-lens
       - correctness-final
       - ui-validation
@@ -324,7 +335,7 @@ localImplementation:
     maxFiles: 2
     maxLines: 100
 
-# Queue defaults (repo-specific queue.board omitted by design).
+# Queue defaults (repo-specific tracker.board omitted by design).
 queue:
   maxParallel: 3
   # Local-first is PR-first (issues are skipped, #952), so auto-filing issues is

package/src/github/comment-id-guard.mjs

@@ -112,6 +112,44 @@ export function extractIssuePrIds(body) {
   return [...found];
 }
 
+// A consecutive run of number-sign(s) immediately before a digit. Strip EVERY
+// number-sign in the run (`#123` and `##123` alike leave `123`), or a leftover
+// still auto-links AND trips the decode-aware guard. A lookahead consumes only
+// the number-sign(s), keeping the digits.
+const BARE_ISSUE_PR_ID_RE = /#+(?=\d)/g;
+
+/**
+ * The sanctioned pre-guard transform for GENERATED comment bodies (#1922):
+ * neutralize a bare `#<digits>` auto-link token to a guard-safe, non-auto-linking
+ * form by stripping the leading `#` (`#123` -> `123`). Auto-link syntax requires
+ * the leading `#`, so the result neither auto-links on GitHub nor trips
+ * `guardCommentBodyNoIssuePrIds` — and because no decode path can reassemble a
+ * `#` from bare digits, the guard's entity-decode surface stays satisfied too.
+ *
+ * This is deliberately SEPARATE from `guardCommentBodyNoIssuePrIds`: the guard
+ * stays fail-closed for human-authored bodies (it must still REFUSE a bare id a
+ * person typed), while gate generators opt into this transform on their OWN
+ * generated finding text before handing it to the guard. It does NOT weaken the
+ * guard.
+ *
+ * Run on RAW text BEFORE any markdown sanitizer (sanitizeInline/sanitizeCodeSpan)
+ * emits its own numeric character references (e.g. `&#91;` for `[`): this strips
+ * `#` before digits without distinguishing an entity's digits from a bare id's,
+ * so applying it post-sanitize would corrupt an already-emitted entity
+ * (`&#91;` -> `&91;`).
+ *
+ * ponytail: strips only a LITERAL `#` before digits — every form a review agent
+ * actually authors (`#123`). It does NOT mirror the guard's full entity-decode
+ * surface; text already carrying an entity-encoded number-sign adjacent to
+ * digits (`&num;123`) is unreachable from reviewer prose, and the guard remains
+ * the fail-closed backstop for it. Returns non-string input unchanged (stringly
+ * callers coerce first).
+ */
+export function neutralizeBareIssuePrIds(value) {
+  if (typeof value !== "string") return value;
+  return value.replace(BARE_ISSUE_PR_ID_RE, "");
+}
+
 // A caller-supplied allowlist is normally already an array (or other
 // iterable) of ids. Guard the one mis-shaped input that would otherwise
 // silently produce the wrong set: a plain CSV string. `Array.from` over a

package/src/github/gh.mjs

@@ -92,3 +92,52 @@ export async function ghGraphql(query, vars, env, runChild = defaultRunChild, {
   }
   return payload;
 }
+
+const GET_USER_ID = [
+  "query($login:String!) {",
+  "  user(login:$login) { id }",
+  "}",
+].join("\n");
+
+const GET_ORG_ID = [
+  "query($login:String!) {",
+  "  organization(login:$login) { id }",
+  "}",
+].join("\n");
+
+/**
+ * Resolve a GitHub owner login to its node id and kind. Probes the user
+ * namespace first; a not-a-user probe failure (org logins make `gh api graphql`
+ * exit non-zero) falls through to the org namespace instead of throwing (#1949).
+ * A login that is neither a user nor an org fails closed with NO_USER_ID.
+ *
+ * The issue's "Proposed fix" wrapped only the user probe, but AC #3 requires
+ * NO_USER_ID for a genuinely non-existent owner; in production the org probe
+ * on a missing org also throws (non-zero exit), so both probes must be caught
+ * for the AC to hold. `cause` preserves the underlying org error for
+ * diagnostics. This does not change `ghGraphql`'s throw-on-non-zero-exit
+ * contract.
+ */
+export async function resolveOwner(login, env, runChild) {
+  try {
+    const userPayload = await ghGraphql(GET_USER_ID, { login }, env, runChild);
+    if (userPayload?.data?.user?.id) {
+      return { id: userPayload.data.user.id, kind: "user" };
+    }
+  } catch {
+    // not a user login → fall through to the org probe
+  }
+  let orgError;
+  try {
+    const orgPayload = await ghGraphql(GET_ORG_ID, { login }, env, runChild);
+    if (orgPayload?.data?.organization?.id) {
+      return { id: orgPayload.data.organization.id, kind: "org" };
+    }
+  } catch (err) {
+    orgError = err;
+  }
+  throw Object.assign(
+    new Error(`Could not resolve owner ID for "${login}"`),
+    { code: "NO_USER_ID", cause: orgError },
+  );
+}

package/src/loop/commit-msg-guard.mjs

@@ -84,7 +84,7 @@ if (process.env.CLAUDECODE === "1") {
     errors.push("missing required trailer: Co-Authored-By: Claude <model> <noreply@anthropic.com>");
   }
   if (!/^Claude-Session:\s*\S+/imu.test(message)) {
-    errors.push("missing required trailer: Claude-Session: <url>");
+    errors.push("missing required trailer: Claude-Session: <url> (e.g. Claude-Session: https://claude.ai/code/session_abc123)");
   }
 }