changeledger 0.9.0 → 0.10.0

package/src/commands/fix.mjs

@@ -0,0 +1,72 @@
+import { writeFileAtomic } from '../atomic-write.mjs';
+import { computeFixes } from '../fix.mjs';
+import { loadRepo } from '../repo.mjs';
+
+// Repairs mechanical, unambiguous format defects (`changeledger fix [id] [--dry-run]`).
+// Ambiguous defects are never touched — they are listed under "requires manual fix".
+export function fix(args = [], cwd = process.cwd(), output = console) {
+  const dryRun = args.includes('--dry-run');
+  const id = args.find((a) => !a.startsWith('--'));
+
+  let repo;
+  try {
+    repo = loadRepo(cwd);
+  } catch (e) {
+    output.error(`  error  (repo): ${e.message}`);
+    return 1;
+  }
+
+  let targets = repo.changes;
+  if (id) {
+    targets = repo.changes.filter((c) => String(c.frontmatter?.id) === String(id));
+    if (!targets.length) {
+      output.error(`  error  no change with id "${id}"`);
+      return 1;
+    }
+  }
+
+  let anyChanged = false;
+  let anyManual = false;
+
+  for (const c of targets) {
+    const { text: fixedText, applied, manual, changed } = computeFixes(c.text);
+
+    if (manual.length) {
+      anyManual = true;
+      output.log(`requires manual fix — ${c.name}:`);
+      for (const m of manual) output.log(`  - ${m}`);
+    }
+
+    if (!changed) {
+      output.log(id ? 'nothing to fix' : `${c.name}: nothing to fix`);
+      continue;
+    }
+
+    anyChanged = true;
+    if (dryRun) {
+      output.log(`--- ${c.name} (dry run)`);
+      for (const line of diffLines(c.text, fixedText)) output.log(line);
+      continue;
+    }
+
+    writeFileAtomic(c.file, fixedText);
+    output.log(`fixed — ${c.name}:`);
+    for (const a of applied) output.log(`  - ${a}`);
+  }
+
+  if (!anyChanged && !anyManual) output.log('nothing to fix');
+  return 0;
+}
+
+function diffLines(before, after) {
+  const a = before.split('\n');
+  const b = after.split('\n');
+  const out = [];
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    if (a[i] === b[i]) continue;
+    if (a[i] !== undefined) out.push(`- ${a[i]}`);
+    if (b[i] !== undefined) out.push(`+ ${b[i]}`);
+  }
+  return out;
+}

package/src/commands/register.mjs

@@ -33,7 +33,15 @@ export function registerRepo(cwd = process.cwd(), output = console) {
 
   removeLegacyContract(changeledgerDir);
   removeLegacyGitignore(repoRoot);
-  if (fs.existsSync(rootContract(repoRoot))) ensureReference(repoRoot);
+  if (fs.existsSync(rootContract(repoRoot))) {
+    for (const { name, status } of ensureReference(repoRoot)) {
+      if (status === 'updated') {
+        output.warn(
+          `warn  ${name}: ChangeLedger bootstrap was outdated; updated to the current version`,
+        );
+      }
+    }
+  }
 
   register({ id: config.project_id, name, path: repoRoot });
   return { id: config.project_id, name, path: repoRoot };

package/src/commands/search.mjs

@@ -0,0 +1,56 @@
+// `changeledger search` — deterministic lexical discovery over changes
+// (including archived) and specs. See change 20260711-103758.
+
+import { loadRepo } from '../repo.mjs';
+import { buildCorpus, searchDocuments } from '../search.mjs';
+
+// Runs the search against the repo at `cwd` and returns ranked hits. Pure
+// query, no mutation.
+export function search(query, { limit, type, status } = {}, cwd = process.cwd()) {
+  const { changes, specs } = loadRepo(cwd);
+  const corpus = buildCorpus({ changes, specs });
+  return searchDocuments(corpus, query, { limit, type, status });
+}
+
+function formatLabel(hit) {
+  return hit.kind === 'spec' ? hit.ref : `${hit.ref} ${hit.status} ${hit.type}`;
+}
+
+// A non-numeric or <1 `--limit` used to degrade silently to "no matches"
+// (see change 20260711-160443); fail fast with a clear error instead.
+function parseLimit(limitStr) {
+  if (limitStr === undefined) return undefined;
+  const n = Number(limitStr);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`--limit must be a whole number >= 1, got "${limitStr}"`);
+  }
+  return n;
+}
+
+// CLI entry point: prints text or `--json`, and `no matches` when nothing scores.
+export function runSearch(queryParts, options = {}, cwd = process.cwd()) {
+  const query = queryParts.join(' ').trim();
+  const limit = parseLimit(options.limit);
+  const hits = search(query, { limit, type: options.type, status: options.status }, cwd);
+
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        hits.map(({ ref, title, score, snippet }) => ({ ref, title, score, snippet })),
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (!hits.length) {
+    console.log('no matches');
+    return;
+  }
+
+  for (const hit of hits) {
+    console.log(`${formatLabel(hit)} — ${hit.title}`);
+    console.log(`  ${hit.snippet}`);
+  }
+}

package/src/config-migration.mjs

@@ -4,7 +4,7 @@ import { parseDocument } from 'yaml';
 import { writeFileAtomic } from './atomic-write.mjs';
 import { templatesDir } from './paths.mjs';
 
-export const SUPPORTED_SCHEMA_VERSION = 1;
+export const SUPPORTED_SCHEMA_VERSION = 2;
 
 const CANONICAL_STATUSES = [
   'draft',
@@ -59,13 +59,33 @@ export function buildMigration(originalText) {
 
   const changes = [];
 
-  // schema_version: 1 — remove any existing value, then prepend to appear first
-  if (Object.hasOwn(config, 'schema_version')) {
-    doc.delete('schema_version');
+  // schema_version — update in place when the key exists at version >= 1 (keeps
+  // its comment and position); otherwise remove any explicit 0 and prepend so
+  // the key appears first.
+  if (Object.hasOwn(config, 'schema_version') && current >= 1) {
+    doc.set('schema_version', SUPPORTED_SCHEMA_VERSION);
+    changes.push(`updated schema_version: ${current} → ${SUPPORTED_SCHEMA_VERSION}`);
+  } else {
+    if (Object.hasOwn(config, 'schema_version')) {
+      doc.delete('schema_version');
+    }
+    doc.contents.items.unshift(doc.createPair('schema_version', SUPPORTED_SCHEMA_VERSION));
+    changes.push(`added schema_version: ${SUPPORTED_SCHEMA_VERSION}`);
+  }
+
+  if (current < 1) {
+    migrateToV1(doc, config, changes);
   }
-  doc.contents.items.unshift(doc.createPair('schema_version', 1));
-  changes.push('added schema_version: 1');
+  migrateToV2(doc, config, changes);
+
+  // No line wrapping and no flow padding: keeps untouched flow sequences
+  // (statuses, stages) byte-identical to their common written form.
+  const yaml = doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+  return { yaml, changes, fromVersion: current };
+}
 
+// 0 → 1: structural additions and managed-comment refresh.
+function migrateToV1(doc, config, changes) {
   // tdd: true if absent
   if (!Object.hasOwn(config, 'tdd')) {
     doc.set('tdd', true);
@@ -125,8 +145,23 @@ export function buildMigration(originalText) {
   const templateComments = loadTemplateComments();
   const commentChanges = refreshManagedComments(doc, templateComments);
   changes.push(...commentChanges);
+}
 
-  return { yaml: doc.toString(), changes };
+// 1 → 2: additive quick type. Existing custom `quick` definitions and impacts
+// are never touched.
+function migrateToV2(doc, config, changes) {
+  const configTypes = config.types ?? {};
+  if (!Object.hasOwn(configTypes, 'quick')) {
+    const stagesNode = doc.createNode(['request', 'log']);
+    stagesNode.flow = true;
+    doc.setIn(['types', 'quick', 'stages'], stagesNode);
+    changes.push('added types.quick with stages: [request, log]');
+  }
+  const currentImpacts = config.release?.impacts ?? {};
+  if (!Object.hasOwn(currentImpacts, 'quick')) {
+    doc.setIn(['release', 'impacts', 'quick'], 'patch');
+    changes.push('added release.impacts.quick: patch');
+  }
 }
 
 // Apply migration to a file (or dry-run). Returns summary string.
@@ -145,8 +180,8 @@ export function applyMigration(configFile, { dryRun = false } = {}) {
   }
 
   const header = dryRun
-    ? `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION} (dry run)`
-    : `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION}`;
+    ? `Config migration ${result.fromVersion} → ${SUPPORTED_SCHEMA_VERSION} (dry run)`
+    : `Config migration ${result.fromVersion} → ${SUPPORTED_SCHEMA_VERSION}`;
 
   const summary = [header, ...result.changes.map((c) => `  - ${c}`)].join('\n');
 

package/src/config.mjs

@@ -69,6 +69,19 @@ function isInside(root, target) {
   return target === root || target.startsWith(root + path.sep);
 }
 
+// Optional declared integration branch: change branches start from it and
+// merge back into it. Absent means the caller keeps its current auto-detection
+// (`defaultBaseBranch`); a present but malformed value fails fast instead of
+// silently falling back.
+export function integrationBranch(config) {
+  const value = config?.git?.integration_branch;
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('config "git.integration_branch" must be a non-empty string');
+  }
+  return value.trim();
+}
+
 // Single source of the specs directory: the configured `specs_dir` or the
 // default, always resolved through the containment guard. Shared by `loadRepo`
 // and `graduate` so a graduated spec lands where the repo will later read it.

package/src/contract.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { writeFileAtomic } from './atomic-write.mjs';
 
 const CONTRACT_FILES = ['AGENTS.md', 'CLAUDE.md'];
-const MARKER = '<!-- changeledger -->';
+const LEGACY_MARKER = '<!-- changeledger -->';
 const LEGACY_ENTRY = '.changeledger/AGENTS.md';
 // Exact SHA-256 digests of every historical templates/AGENTS.md payload. A
 // regular file is removed only when it is byte-identical to a contract version
@@ -34,8 +34,16 @@ const LEGACY_CONTRACT_HASHES = new Set([
   '99a42380f3835e1f706b986b86e58e33f12d68de4a69d94eb50845e790e05f71',
 ]);
 
-export const REFERENCE = `${MARKER}
-> [!IMPORTANT]
+// Bootstrap block format version. Independent of the package version: bump
+// only when the delimited block's shape or required content changes in a way
+// that must be detected and re-registered in consuming repos.
+export const BOOTSTRAP_VERSION = 2;
+
+const BEGIN_RE = /<!-- CHANGELEDGER BOOTSTRAP BEGIN v(\d+) -->/;
+const END_MARKER = '<!-- CHANGELEDGER BOOTSTRAP END -->';
+const beginMarker = (version) => `<!-- CHANGELEDGER BOOTSTRAP BEGIN v${version} -->`;
+
+export const REFERENCE = `> [!IMPORTANT]
 > This repo uses **ChangeLedger**. Immediately after reading this file — before
 > planning, investigating, or acting — a normal agent must run \`changeledger context\` directly.
 > Only a delegated leaf whose prompt was emitted by \`changeledger agent-prompt <role>\`
@@ -51,8 +59,15 @@ export const REFERENCE = `${MARKER}
 >
 > Do not create or modify files without an authorized change; the core context
 > defines the workflow, the task contexts, and the narrow operational exception.
+> After a compaction, verify a retained capture with \`changeledger context
+> [mode] --have <rev>\` (the BEGIN line's \`rev:\`) instead of recapturing in
+> full; a mismatch still returns the complete output.
 `;
 
+function bootstrapBlock(version = BOOTSTRAP_VERSION) {
+  return `${beginMarker(version)}\n${REFERENCE}${END_MARKER}\n`;
+}
+
 export const contractLink = (changeledgerDir) => path.join(changeledgerDir, 'AGENTS.md');
 export const rootContract = (repoRoot) => path.join(repoRoot, 'AGENTS.md');
 
@@ -64,28 +79,66 @@ function isPlainFile(file) {
   }
 }
 
-function replaceReference(text) {
-  const start = text.indexOf(MARKER);
-  if (start === -1) return `${text}${text.endsWith('\n') ? '' : '\n'}\n${REFERENCE}`;
+function insertBlock(text) {
+  const sep = text.length === 0 || text.endsWith('\n') ? '' : '\n';
+  const gap = text.length === 0 ? '' : '\n';
+  return `${text}${sep}${gap}${bootstrapBlock()}`;
+}
+
+// Migrate the legacy `<!-- changeledger -->` marker and its contiguous
+// blockquote to the delimited format.
+function migrateLegacy(text, start) {
   const tail = text.slice(start).split('\n');
   let consumed = 1;
   while (consumed < tail.length && tail[consumed].startsWith('>')) consumed += 1;
   const before = text.slice(0, start);
   const after = tail.slice(consumed).join('\n').replace(/^\n+/, '');
-  return `${before}${REFERENCE}${after ? `\n${after}` : ''}`;
+  return `${before}${bootstrapBlock()}${after ? `\n${after}` : ''}`;
+}
+
+// Replace only the interior of an existing BEGIN/END block, preserving
+// everything outside the delimiters byte-for-byte.
+function replaceDelimited(text, beginIndex, version) {
+  const endIndex = text.indexOf(END_MARKER, beginIndex);
+  if (endIndex === -1) {
+    throw new Error(
+      'Malformed ChangeLedger bootstrap: found a BEGIN marker without a matching END marker',
+    );
+  }
+  const before = text.slice(0, beginIndex);
+  const after = text.slice(endIndex + END_MARKER.length).replace(/^\n/, '');
+  const newText = `${before}${bootstrapBlock()}${after}`;
+  const status =
+    version < BOOTSTRAP_VERSION ? 'updated' : newText === text ? 'unchanged' : 'replaced';
+  return { text: newText, status, fromVersion: version };
+}
+
+// Compute the delimited bootstrap block for `text`, inserting it, replacing
+// it, or migrating the legacy marker as needed.
+export function applyBootstrap(text) {
+  const beginMatch = BEGIN_RE.exec(text);
+  if (beginMatch) {
+    return replaceDelimited(text, beginMatch.index, Number(beginMatch[1]));
+  }
+  const legacyIndex = text.indexOf(LEGACY_MARKER);
+  if (legacyIndex !== -1) {
+    return { text: migrateLegacy(text, legacyIndex), status: 'migrated' };
+  }
+  return { text: insertBlock(text), status: 'inserted' };
 }
 
-// Add or replace the managed bootstrap block in project-owned agent files.
+// Add, replace, or migrate the managed bootstrap block in project-owned agent
+// files. Returns the files touched with the transition applied to each.
 export function ensureReference(repoRoot) {
   const touched = [];
   for (const name of CONTRACT_FILES) {
     const file = path.join(repoRoot, name);
     if (!isPlainFile(file)) continue;
     const text = fs.readFileSync(file, 'utf8');
-    const updated = replaceReference(text);
-    if (updated === text) continue;
+    const { text: updated, status, fromVersion } = applyBootstrap(text);
+    if (status === 'unchanged') continue;
     writeFileAtomic(file, updated);
-    touched.push(name);
+    touched.push({ name, status, fromVersion });
   }
   return touched;
 }
@@ -138,9 +191,10 @@ export function checkContract(repoRoot) {
     const file = path.join(repoRoot, name);
     if (!isPlainFile(file)) continue;
     const text = fs.readFileSync(file, 'utf8');
-    if (!text.includes(MARKER)) {
+    const { status } = applyBootstrap(text);
+    if (status === 'inserted') {
       errors.push(`${name} has no ChangeLedger reference — run \`changeledger register\``);
-    } else if (!text.includes(REFERENCE.trim())) {
+    } else if (status !== 'unchanged') {
       errors.push(`${name} has an outdated ChangeLedger reference — run \`changeledger register\``);
     }
   }

package/src/fix.mjs

@@ -0,0 +1,127 @@
+// Mechanical, unambiguous repairs for format defects `changeledger check` can
+// only diagnose. Pure text-in/text-out — no IO. The `fix` command (and its
+// `--dry-run`) do the reading/writing; `check` reuses `hasFixableDefects` to
+// print a hint without duplicating the repair rules.
+//
+// Repairs (in order, per `## Plan` task line):
+//   1. Checkbox marker variants `[ x ]` / `[X]` -> `[x]`.
+//   2. A `(CRn) — verify: X` block reordered to `; verify: X (CRn)`.
+//   3. A resolution suffix using a single hyphen instead of an em dash.
+//   4. A near-ISO resolution timestamp normalized to strict ISO 8601 UTC.
+//
+// A task whose CR reference is not declared in `## Specification` is left
+// completely untouched and reported under `manual` — the defect requires
+// judgment (unknown criterion), not a mechanical rewrite.
+import { parseChange } from './change.mjs';
+
+const TASK_LINE = /^(\s*-\s)\[([^\]]*)\](\s+)(.*)$/;
+const REORDERED_VERIFY = /^(.*?)\s*\(([^)]*\bCR\d+[^)]*)\)\s*—\s*verify:\s*(.+)$/;
+const NEAR_ISO = /^(\d{4})-(\d{1,2})-(\d{1,2})[ T](\d{1,2}):(\d{2}):(\d{2})(?:\.\d+)?(Z)?$/;
+
+export function computeFixes(text) {
+  const criteria = new Set(parseChange(text).criteria ?? []);
+  const lines = text.split('\n');
+  const outLines = [];
+  const applied = [];
+  const manual = [];
+  let inPlan = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    if (/^##\s+/.test(rawLine)) {
+      inPlan = /^##\s+Plan\s*$/.test(rawLine);
+      outLines.push(rawLine);
+      continue;
+    }
+    if (!inPlan) {
+      outLines.push(rawLine);
+      continue;
+    }
+    const result = fixTaskLine(rawLine, criteria, i + 1);
+    outLines.push(result.line);
+    applied.push(...result.applied);
+    manual.push(...result.manual);
+  }
+
+  return { text: outLines.join('\n'), applied, manual, changed: applied.length > 0 };
+}
+
+export function hasFixableDefects(text) {
+  if (typeof text !== 'string') return false;
+  try {
+    return computeFixes(text).changed;
+  } catch {
+    return false;
+  }
+}
+
+function fixTaskLine(rawLine, declaredCR, lineNo) {
+  const m = rawLine.match(TASK_LINE);
+  if (!m) return { line: rawLine, applied: [], manual: [] };
+  const [, prefix, markerRaw, gap, restRaw] = m;
+
+  // A task referencing an undeclared criterion needs judgment, not a rewrite —
+  // leave the entire line untouched.
+  const referenced = restRaw.match(/CR\d+/g) ?? [];
+  const unknown = [...new Set(referenced.filter((cr) => !declaredCR.has(cr)))];
+  if (unknown.length) {
+    return {
+      line: rawLine,
+      applied: [],
+      manual: [`line ${lineNo}: references unknown criterion ${unknown.join(', ')}`],
+    };
+  }
+
+  const applied = [];
+  let rest = restRaw;
+
+  let marker = markerRaw;
+  if (marker.trim().toLowerCase() === 'x' && marker !== 'x') {
+    marker = 'x';
+    applied.push(`line ${lineNo}: checkbox marker normalized to [x]`);
+  }
+  const state = marker === 'x' ? 'done' : marker === '!' ? 'blocked' : 'todo';
+
+  const reorder = rest.match(REORDERED_VERIFY);
+  if (reorder) {
+    const [, target, crBlock, verify] = reorder;
+    rest = `${target.trim()}; verify: ${verify.trim()} (${crBlock.trim()})`;
+    applied.push(`line ${lineNo}: reordered verify suffix before (${crBlock.trim()})`);
+  }
+
+  // The resolution suffix is the LAST separator: a description may legitimately
+  // contain an em dash, so only a hyphen sitting after every em dash is a defect.
+  if (
+    (state === 'done' || state === 'blocked') &&
+    rest.lastIndexOf(' - ') > rest.lastIndexOf(' — ')
+  ) {
+    const hyphenIdx = rest.lastIndexOf(' - ');
+    if (hyphenIdx !== -1) {
+      rest = `${rest.slice(0, hyphenIdx)} — ${rest.slice(hyphenIdx + 3)}`;
+      applied.push(`line ${lineNo}: resolution suffix hyphen normalized to em dash`);
+    }
+  }
+
+  if (state === 'done') {
+    const dash = rest.lastIndexOf(' — ');
+    if (dash !== -1) {
+      const suffix = rest.slice(dash + 3);
+      const normalized = normalizeIsoTimestamp(suffix);
+      if (normalized && normalized !== suffix) {
+        rest = `${rest.slice(0, dash)} — ${normalized}`;
+        applied.push(`line ${lineNo}: resolution timestamp normalized to ISO 8601 UTC`);
+      }
+    }
+  }
+
+  if (!applied.length) return { line: rawLine, applied: [], manual: [] };
+  return { line: `${prefix}[${marker}]${gap}${rest}`, applied, manual: [] };
+}
+
+function normalizeIsoTimestamp(text) {
+  const m = text.trim().match(NEAR_ISO);
+  if (!m) return null;
+  const [, y, mo, d, h, mi, s] = m;
+  const pad = (v) => v.padStart(2, '0');
+  return `${y}-${pad(mo)}-${pad(d)}T${pad(h)}:${mi}:${s}Z`;
+}

package/src/framing.mjs

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { packageRoot } from './paths.mjs';
@@ -20,3 +21,10 @@ export function beginSentinel(kind, meta) {
 export function endSentinel(kind) {
   return `===== CHANGELEDGER ${kind} END — ${TRUNCATION_SUFFIX} =====`;
 }
+
+// 12-hex-char content revision for a composed body. Callers hash the body
+// only (never the BEGIN/END lines themselves) so the revision never
+// references its own framing.
+export function contentRev(body) {
+  return crypto.createHash('sha256').update(body).digest('hex').slice(0, 12);
+}

package/src/git.mjs

@@ -6,8 +6,56 @@ import { execFileSync } from 'node:child_process';
 
 const SEP = String.fromCharCode(31); // ASCII unit separator — safe field delimiter
 
-function defaultRun(args, cwd) {
-  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+// Repo-location env vars git itself exports while running a hook (e.g. this
+// project's own pre-commit). Left inherited, a child `git` call would silently
+// target the hook's repo/worktree instead of the given `cwd` — strip them so
+// every invocation stays anchored on `cwd`.
+const GIT_LOCATION_ENV_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR',
+  'GIT_CEILING_DIRECTORIES',
+];
+
+function sanitizedEnv() {
+  const env = { ...process.env };
+  for (const key of GIT_LOCATION_ENV_VARS) delete env[key];
+  return env;
+}
+
+// Exported so other commands (e.g. `changeledger commit`) share the same
+// GIT_* sanitization instead of re-implementing it.
+export function defaultRun(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    env: sanitizedEnv(),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+}
+
+// Run variant for mutating git commands (e.g. `commit`), where git's stderr is
+// the only clue to a failure (failed hook, nothing staged, missing identity,
+// lock). Pipes stderr and, on failure, throws an Error whose message includes
+// the captured diagnostic. Query paths keep `defaultRun` and degrade silently.
+export function mutatingRun(args, cwd) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      env: sanitizedEnv(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    const detail = [e.stderr, e.stdout]
+      .map((s) => (typeof s === 'string' ? s.trim() : ''))
+      .filter(Boolean)
+      .join('\n');
+    throw new Error(detail ? `${e.message}\n${detail}` : e.message, { cause: e });
+  }
 }
 
 // Local git identity (`git config user.name`), or '' if unavailable. Tolerant.
@@ -39,6 +87,75 @@ export function ownerHandle(cwd, run = defaultRun, ghRun = defaultGhRun) {
   return githubLogin(ghRun) || gitUser(cwd, run);
 }
 
+// Detects the branch `changeledger check --commits` should diff against when
+// no base is given: the remote's HEAD if configured, else a local `main` or
+// `master`. Throws with actionable guidance if neither is resolvable.
+export function defaultBaseBranch(repoRoot, run = defaultRun) {
+  try {
+    const out = run(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], repoRoot);
+    const name = out.trim().replace(/^origin\//, '');
+    if (name) return name;
+  } catch {
+    // no configured remote HEAD — fall through to local candidates
+  }
+  for (const candidate of ['main', 'master']) {
+    try {
+      run(['rev-parse', '--verify', '--quiet', candidate], repoRoot);
+      return candidate;
+    } catch {
+      // candidate branch does not exist locally — try the next one
+    }
+  }
+  throw new Error(
+    'Could not detect a default branch (no origin/HEAD, main, or master); pass one explicitly: changeledger check --commits <base>',
+  );
+}
+
+// Commits in `range` (e.g. `main..HEAD`): sha, subject and whether each is a
+// merge (more than one parent) — the git metadata `check --commits` lints.
+export function commitsInRange(repoRoot, range, run = defaultRun) {
+  let out;
+  try {
+    out = run(['log', range, `--pretty=format:%H${SEP}%P${SEP}%s`], repoRoot);
+  } catch (e) {
+    throw new Error(`git log failed for range "${range}": ${e.message}`);
+  }
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, parents, subject] = line.split(SEP);
+      return {
+        sha,
+        subject,
+        isMerge: parents.trim().split(/\s+/).filter(Boolean).length > 1,
+      };
+    });
+}
+
+// A well-formed marker is one or more `[#id]` groups, each separated by a
+// single space, terminating the subject — the canonical multi-id shape is
+// separate brackets (`[#A] [#B]`), never a comma list in one bracket.
+const MARKER_RE = /(\[#[^\]\s]+\])(\s\[#[^\]\s]+\])*$/;
+export function hasCommitMarker(subject) {
+  return MARKER_RE.test(subject.trim());
+}
+
+// Lints `range`: every non-merge commit must carry a well-formed `[#id]`
+// marker, except `chore(release)` prep commits. Returns only the violations
+// (sha + subject); never throws for a clean range.
+export function lintCommitRange(repoRoot, range, run = defaultRun) {
+  const commits = commitsInRange(repoRoot, range, run);
+  const violations = [];
+  for (const c of commits) {
+    if (c.isMerge) continue;
+    if (/^chore\(release\):/.test(c.subject)) continue;
+    if (!hasCommitMarker(c.subject))
+      violations.push({ sha: c.sha.slice(0, 7), subject: c.subject });
+  }
+  return violations;
+}
+
 export function gitRefs(repoRoot, id, run = defaultRun) {
   const refs = { commits: [], branches: [] };
   if (!id) return refs;