@dev-loops/core 1.0.0-rc.7 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.0-rc.7",
+  "version": "1.0.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -53,6 +53,7 @@
     "./loop/refinement-grill-state": "./src/loop/refinement-grill-state.mjs",
     "./loop/queue-board-ordering": "./src/loop/queue-board-ordering.mjs",
     "./loop/default-branch-guard": "./src/loop/default-branch-guard.mjs",
+    "./loop/commit-msg-guard": "./src/loop/commit-msg-guard.mjs",
     "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
     "./loop/queue-membership": "./src/loop/queue-membership.mjs",

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
@@ -263,9 +263,15 @@ gates:
         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.
+          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, 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. Also verify the checked
+          content mirrors the linked issue's AC/DoD/Non-goals matrix and that declared non-goals are
+          respected (no scope creep). The boundary is explicit: the deterministic block enforces
+          completeness (nothing left unchecked/forgotten); you verify each [x] is real.
       - contradiction-lens
       - correctness-final
       - ui-validation
@@ -324,7 +330,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/loop/commit-msg-guard.mjs

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Enforces the commit-message contract AT COMMIT TIME (issue #1869): the
+ * attribution trailers, the no-bare-#N rule, and the conventional-commit
+ * subject form were previously prose-only — nothing checked them, so a
+ * non-compliant commit landed silently. Installed alongside the
+ * default-branch guard (see default-branch-guard.mjs), through the same
+ * ensure-worktree provisioning path, so it rides into every worktree too.
+ *
+ * The rendered hook is a single self-contained Node script (ESM: this repo's
+ * root package.json is `"type": "module"`, and Node resolves an
+ * extensionless direct-run script's module type by walking up for the
+ * nearest package.json — verified empirically, not merely assumed). Keeping
+ * the ENTIRE check inline in the rendered script (rather than requiring a
+ * sibling file back into the checkout) means the installed hook keeps
+ * working even if the checkout that installed it is later removed or moved
+ * — the same self-containment default-branch-guard's hooks rely on.
+ */
+export const COMMIT_MSG_GUARD_MARKER = "dev-loops:commit-msg-guard";
+export const COMMIT_MSG_WAIVER_MARKER = `${COMMIT_MSG_GUARD_MARKER}:allow`;
+
+// Ownership check mirrors default-branch-guard's: the marker must be its own
+// line (a `//` comment, since the rendered hook is JS), not merely mentioned,
+// so a foreign hook that references us in prose is still left untouched.
+const GUARD_MARKER_LINE = new RegExp(`^// ${COMMIT_MSG_GUARD_MARKER}$`, "mu");
+
+/**
+ * Renders the commit-msg hook as a standalone, runnable Node script. The
+ * validation logic below is the ONLY copy of it — there is no separate JS
+ * implementation this must stay in sync with, exactly like renderGuardHook's
+ * shell body has none either. Tests exercise it by actually running it (see
+ * commit-msg-guard.test.mjs), the same way default-branch-guard.test.mjs
+ * drives real git rather than asserting on rendered text.
+ *
+ * String.raw, not a plain template literal: the generated script is full of
+ * regex backslash escapes (\s, \d, \b, \.) that a normal template literal
+ * would silently strip (an unrecognized string escape drops its backslash),
+ * corrupting every regex in the installed hook. String.raw keeps every
+ * backslash literal while still substituting the ${...} marker constants.
+ * The generated script deliberately uses NO template literals of its own
+ * (string concatenation instead) — a literal backtick would otherwise close
+ * THIS OUTER template early.
+ */
+export function renderCommitMsgGuardHook() {
+  return String.raw`#!/usr/bin/env node
+// ${COMMIT_MSG_GUARD_MARKER}
+// Enforces the commit-message contract (issue #1869): attribution trailers,
+// no bare non-issue #<digits>, and a conventional-commit subject. A
+// per-commit waiver line (${COMMIT_MSG_WAIVER_MARKER}) skips every check
+// below for a deliberate exception.
+import { readFileSync } from "node:fs";
+
+// git invokes commit-msg with ONLY the message-file path (unlike
+// prepare-commit-msg, which also gets a source/sha) — no signal distinguishes
+// an ordinary commit from a merge/squash at this hook. A default, unedited
+// merge message ("Merge branch '...'", "Merge pull request #...", "Merge tag
+// '...'"), a default git-revert message (Revert "..."), or a
+// git commit --fixup/--squash autosquash subject (fixup! ... / squash! ...)
+// is git/tooling-generated, not operator-authored prose, so each is exempt by
+// its own recognizable shape rather than forced through a conventional-commit
+// subject and trailers it was never meant to carry.
+const [, , msgPath] = process.argv;
+const message = readFileSync(msgPath, "utf8");
+const subjectLine = message.split("\n", 1)[0] || "";
+if (
+  /^Merge (branch|tag|remote-tracking branch|pull request) /u.test(subjectLine) ||
+  /^Revert "/u.test(subjectLine) ||
+  /^(fixup|squash)! /u.test(subjectLine)
+) process.exit(0);
+
+if (/^${COMMIT_MSG_GUARD_MARKER}:allow\b/mu.test(message)) process.exit(0);
+
+const errors = [];
+
+// Trailers are required only for an AGENT-authored commit: Claude Code sets
+// CLAUDECODE=1 in every shell it spawns (the same harness-detection signal
+// packages/core/src/loop/run-context.mjs's isClaudeHarness checks) — a plain
+// human commit (CLAUDECODE unset) is never "Claude", so requiring a Claude
+// co-author trailer on it would misattribute the commit, not enforce honesty.
+if (process.env.CLAUDECODE === "1") {
+  if (!/^Co-Authored-By:\s*Claude\s+.+\s+<noreply@anthropic\.com>\s*$/imu.test(message)) {
+    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>");
+  }
+}
+
+// A genuine "Closes #N" / "Fixes #N" / "Refs #N" reference (optionally a
+// comma/and-joined list, and optionally the trailer colon form "Closes: #N")
+// is allowed and stripped first; any #<digits> left over is a bare non-issue
+// enumeration, which GitHub auto-links to an unrelated issue/PR when
+// rendered.
+const withoutAllowedRefs = message.replace(
+  /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|refs?|references?):?\s+#\d+(?:\s*(?:,|and)\s*#\d+)*/giu,
+  "",
+);
+if (/#\d+/u.test(withoutAllowedRefs)) {
+  errors.push('bare #<digits> reference found; use "Closes #N" / "Fixes #N" / "Refs #N" for a genuine issue reference, or reword a non-issue enumeration (e.g. "defect N")');
+}
+
+if (!/^(feat|fix|chore|docs|test|refactor|revert|perf|style|ci|build)\([^()\n]+\): .+\S/u.test(subjectLine)) {
+  errors.push("subject must be conventional-commit form \"type(scope): summary\" (type one of feat/fix/chore/docs/test/refactor/revert/perf/style/ci/build)");
+}
+
+if (errors.length > 0) {
+  console.error("dev-loops: WORKTREE-COMMIT-MSG-GUARD refuses this commit — contract violation(s):");
+  for (const error of errors) console.error("  - " + error);
+  console.error("  Waiver: add a \"${COMMIT_MSG_WAIVER_MARKER}\" line to the commit message for a deliberate exception.");
+  process.exit(1);
+}
+process.exit(0);
+`;
+}
+
+/**
+ * Install the commit-msg guard into a repository's hook directory. Mirrors
+ * default-branch-guard's install-refusal checks (a caller with an unsafe
+ * `core.hooksPath`, a non-absolute/non-git `gitDir`, or a linked worktree's
+ * OWN gitdir must never report success for a hook that can never fire) and
+ * its atomic write + foreign-hook preservation — duplicated rather than
+ * shared, since it is one hook, not a family; see default-branch-guard.mjs
+ * for the family version if a third hook installer ever needs the same
+ * shape factored out.
+ *
+ * @param {{ gitDir: string, hooksPathOverride?: string|null }} target
+ */
+export function installCommitMsgGuard({ gitDir, hooksPathOverride = null }) {
+  const refuse = (reason) => ({ ok: false, installed: false, refreshed: false, skipped: true, reason });
+
+  if (typeof hooksPathOverride === "string") {
+    const configured = hooksPathOverride.trim();
+    return configured.length > 0
+      ? refuse(`core.hooksPath is set to ${JSON.stringify(configured)} — install the guard there, or unset it`)
+      : refuse("core.hooksPath is set to an empty string — git runs no hooks at all");
+  }
+  if (typeof gitDir !== "string" || !path.isAbsolute(gitDir)) {
+    return refuse(`gitDir must be an absolute path; got ${JSON.stringify(gitDir)}`);
+  }
+  if (!fs.existsSync(path.join(gitDir, "HEAD"))) {
+    return refuse(`gitDir ${JSON.stringify(gitDir)} does not look like a git directory (no HEAD file)`);
+  }
+  if (fs.existsSync(path.join(gitDir, "commondir"))) {
+    return refuse(`gitDir ${JSON.stringify(gitDir)} is a linked worktree's own git directory, not the common one — hooks installed there never run`);
+  }
+
+  const hooksDir = path.join(gitDir, "hooks");
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, "commit-msg");
+
+  const existing = fs.existsSync(hookPath) ? fs.readFileSync(hookPath, "utf8") : null;
+  const ours = existing === null || GUARD_MARKER_LINE.test(existing);
+  if (!ours) {
+    return { ok: true, installed: false, refreshed: false, skipped: true, reason: "a pre-existing hook is present and was left untouched" };
+  }
+
+  // Same atomic tmp-write + rename as default-branch-guard: the hooks dir is
+  // shared across worktrees, so a direct writeFileSync would be visible
+  // mid-write to a concurrent install or a real commit racing this one.
+  const tmpPath = path.join(hooksDir, `.commit-msg.tmp-${process.pid}-${Date.now()}`);
+  fs.writeFileSync(tmpPath, renderCommitMsgGuardHook(), { mode: 0o755 });
+  fs.chmodSync(tmpPath, 0o755);
+  fs.renameSync(tmpPath, hookPath);
+
+  return { ok: true, installed: existing === null, refreshed: existing !== null, skipped: false };
+}

package/src/loop/gate-fanin.mjs

@@ -63,13 +63,19 @@ export function scheduleFanoutWaves(dispatchGroups, maxConcurrent = 4) {
 }
 
 /**
- * Adaptive 429-backoff concurrency (issue #1601): halve the active batch before
- * escalating to foreground one-at-a-time fallback. On a 429, the conductor
- * recomputes the wave plan with `backoffMaxConcurrent(maxConcurrent)` and
- * retries the failed wave; if a single-unit wave still 429s, it falls back to
- * foreground (one-at-a-time) dispatch. The backoff is recorded in the round's
- * provenance (see skills/docs/gate-review-sub-loop-contract.md). Pure; never
- * returns 0 (a backoff from 1 stays 1 → foreground fallback owns that path).
+ * Adaptive concurrency backoff (issue #1601; retry discipline refined by #1907):
+ * halve the active batch before escalating to foreground one-at-a-time fallback.
+ * A transient dispatch failure (429/5xx) is first retried on the SAME unit with
+ * exponential backoff — safe because a reviewer's findings artifact is an
+ * idempotent single-write at a deterministic path — and the conductor reduces
+ * concurrency ONLY after that unit's retries are exhausted (~3 failed attempts),
+ * recomputing the wave plan with `backoffMaxConcurrent(maxConcurrent)` and
+ * retrying the reduced wave; if a single-unit wave still fails, it falls back to
+ * foreground (one-at-a-time) dispatch. This "retry the unit before reducing
+ * concurrency" ordering is owned by GATE-EXEC-DISPATCH-RETRY-BACKOFF in
+ * skills/docs/gate-review-sub-loop-contract.md; the backoff is recorded in the
+ * round's provenance. Pure; never returns 0 (a backoff from 1 stays 1 →
+ * foreground fallback owns that path).
  * @param {number} maxConcurrent
  * @returns {number}
  */