changeledger 0.8.0 → 0.10.0

package/AGENTS.md

@@ -3,11 +3,15 @@
 This is the ChangeLedger repo itself. It dogfoods its own format: changes live
 under `.changeledger/changes/`, persistent truth under `.changeledger/specs/`.
 
-<!-- changeledger -->
+<!-- CHANGELEDGER BOOTSTRAP BEGIN v2 -->
 > [!IMPORTANT]
 > This repo uses **ChangeLedger**. Immediately after reading this file — before
-> planning, investigating, or acting — run `changeledger context` directly.
-> On the first invocation, retain complete stdout through the `CHANGELEDGER CONTEXT END` line:
+> 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>`
+> runs `changeledger agent-context <role> [change-id]` instead; the role in the
+> prompt and command must match. No other agent may skip the core context.
+> On the first invocation, retain complete stdout through the `CHANGELEDGER CONTEXT END` line,
+> or the `CHANGELEDGER AGENT CONTEXT END` line for that delegated path:
 > no pipes, filters, summaries, previews or voluntary output limits. If the tool
 > exposes an output budget, reserve enough for the whole response. A missing END
 > after that is exceptional recovery: stop and re-run with a larger capture. If
@@ -16,6 +20,10 @@ under `.changeledger/changes/`, persistent truth under `.changeledger/specs/`.
 >
 > 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.
+<!-- CHANGELEDGER BOOTSTRAP END -->
 
 The canonical ChangeLedger contract is split into task-focused fragments under
 [`templates/contract/`](templates/contract/). The deterministic

package/README.md

@@ -137,11 +137,20 @@ The contract ships as task-focused fragments and is compiled on demand:
 changeledger context                    # minimal non-negotiable core
 changeledger context <change-id>        # lifecycle-aware rules + selected change
 changeledger context review             # explicit task mode
+changeledger agent-prompt <role>         # portable delegation skeleton
+changeledger agent-context <role> [id]  # self-contained context for that delegate
 ```
 
 `init` places a small fail-closed bootstrap in the project-owned `AGENTS.md`;
 there is no linked or copied contract under `.changeledger/`. Run
-`changeledger register` after upgrading to refresh that bootstrap.
+`changeledger register` after upgrading to refresh that bootstrap. Normal agents
+load `context`; a delegated leaf identified by `agent-prompt` loads only its
+matching `agent-context`, without the orchestrator core.
+
+Roles are `investigation`, `implementation`, `review` and `audit`. `audit` is a
+read-only inspection of a change already in `in-validation` — after review has
+already passed — for a human or orchestrator to consult before accepting or
+rejecting it; it never moves the change or records a verdict.
 
 ### Upgrading an existing repo's configuration
 

package/bin/changeledger.mjs

@@ -8,13 +8,19 @@ import {
   list,
   log,
   owner,
+  reopen,
   review,
   show,
   status,
   task,
+  validation,
 } from '../src/commands/agent.mjs';
+import { agentContext } from '../src/commands/agent-context.mjs';
+import { agentPrompt } from '../src/commands/agent-prompt.mjs';
 import { check } from '../src/commands/check.mjs';
+import { commit } from '../src/commands/commit.mjs';
 import { context } from '../src/commands/context.mjs';
+import { fix } from '../src/commands/fix.mjs';
 import {
   graduate,
   pendingGraduation,
@@ -25,6 +31,7 @@ import { init } from '../src/commands/init.mjs';
 import { newChange } from '../src/commands/new.mjs';
 import { registerRepo } from '../src/commands/register.mjs';
 import { initReleaseHistory, recordRelease, releasePlan } from '../src/commands/release.mjs';
+import { runSearch } from '../src/commands/search.mjs';
 import { view } from '../src/commands/view.mjs';
 import { findChangeledgerDir } from '../src/config.mjs';
 import { applyMigration } from '../src/config-migration.mjs';
@@ -34,11 +41,12 @@ const { version } = createRequire(import.meta.url)('../package.json');
 
 const USAGE = `ChangeLedger (changeledger)
 
-Run \`changeledger context\` first in any repo — it is the mandatory bootstrap.
+Run \`changeledger context\` first in any repo unless a ChangeLedger delegation
+prompt identifies your role and tells you to run \`agent-context\` instead.
 
-  changeledger init | register | new | view | check | context
-  changeledger status | discard | review | owner | archive | unarchive
-  changeledger log | task | list | show | graduate | config | release
+  changeledger init | register | new | view | check | fix | context | agent-context
+  changeledger commit | status | discard | review | owner | archive
+  changeledger log | task | list | show | search | graduate | config | release
 
 Run \`changeledger <command> --help\` for that command's syntax, values and examples.`;
 
@@ -55,6 +63,11 @@ function action(fn) {
   };
 }
 
+// Collects a repeatable option (e.g. `--id`) into an array across invocations.
+function collect(value, previous) {
+  return previous.concat([value]);
+}
+
 program
   .name('changeledger')
   .description('ChangeLedger (changeledger)')
@@ -62,7 +75,7 @@ program
   .helpOption('-h, --help', 'display help for command')
   .addHelpText(
     'after',
-    '\nRun `changeledger context` first in any repo — it is the mandatory bootstrap.\n' +
+    '\nRun `changeledger context` first unless a ChangeLedger delegation prompt tells your role to use `agent-context`.\n' +
       "Run `changeledger <command> --help` for that command's syntax, values and examples.",
   );
 
@@ -131,9 +144,25 @@ program
   .description('validate the repo or one change')
   .argument('[id]')
   .option('--json', 'print JSON')
+  .option(
+    '--commits [base]',
+    'lint commit subjects on <base>..HEAD for the [#id] marker (base auto-detected if omitted)',
+  )
+  .addHelpText(
+    'after',
+    ['', 'Examples:', '  changeledger check --commits', '  changeledger check --commits main'].join(
+      '\n',
+    ),
+  )
   .action((id, options) => {
     try {
-      const args = [...(id ? [id] : []), ...(options.json ? ['--json'] : [])];
+      const args = [
+        ...(id ? [id] : []),
+        ...(options.json ? ['--json'] : []),
+        ...(options.commits !== undefined
+          ? ['--commits', ...(typeof options.commits === 'string' ? [options.commits] : [])]
+          : []),
+      ];
       process.exit(check(args));
     } catch (e) {
       console.error(`Error: ${e.message}`);
@@ -141,6 +170,52 @@ program
     }
   });
 
+program
+  .command('fix')
+  .description('repair mechanical, unambiguous format defects (or one change)')
+  .argument('[id]')
+  .option('--dry-run', 'print the proposed diff without writing')
+  .action((id, options) => {
+    try {
+      const args = [...(id ? [id] : []), ...(options.dryRun ? ['--dry-run'] : [])];
+      process.exit(fix(args));
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('commit')
+  .description('compose the canonical [#id] marker and create a git commit')
+  .requiredOption('-m, --message <subject>', 'conventional subject: type(scope): description')
+  .option(
+    '--id <change-id>',
+    'change id to reference (repeatable); auto-resolved from the single in-progress change if omitted',
+    collect,
+    [],
+  )
+  .addHelpText(
+    'after',
+    [
+      '',
+      'When --id is omitted, the single in-progress change is used automatically;',
+      'zero or multiple in-progress changes require --id explicitly. Repeat --id',
+      'for a multi-id subject: each id gets its own bracket ([#A] [#B]).',
+      '',
+      'Examples:',
+      '  changeledger commit -m "feat(cli): add helper"',
+      '  changeledger commit -m "feat(cli): add helper" --id 20260711-000001',
+      '  changeledger commit -m "feat(cli): add helper" --id 20260711-000001 --id 20260711-000002',
+    ].join('\n'),
+  )
+  .action(
+    action((options) => {
+      const subject = commit({ message: options.message, ids: options.id });
+      console.log(`Committed: ${subject}`);
+    }),
+  );
+
 program
   .command('context')
   .description('print deterministic task context')
@@ -148,6 +223,10 @@ program
     '[mode-or-change-id]',
     'spec|implement|review|release, or a change id (pack inferred from its status)',
   )
+  .option(
+    '--have <rev>',
+    'skip the full reload when this matches the current rev (short `unchanged` confirmation instead)',
+  )
   .addHelpText(
     'after',
     [
@@ -168,6 +247,10 @@ program
       'are inferred the same way from the change id; they are not modes you pass',
       'explicitly.',
       '',
+      'Each BEGIN line carries `rev:<hash>`. After a compaction, pass the rev your',
+      'retained capture carried as `--have <rev>`: a match prints a short confirmation',
+      'instead of reloading the full body; a mismatch prints the complete output.',
+      '',
       'Examples:',
       '  changeledger context',
       '  changeledger context spec',
@@ -175,9 +258,62 @@ program
       '  changeledger context review',
       '  changeledger context release',
       '  changeledger context 20260630-225212',
+      '  changeledger context --have 0123456789ab',
+    ].join('\n'),
+  )
+  .action(action((input, options) => context(input, { have: options.have })));
+
+program
+  .command('agent-prompt')
+  .description('print a portable delegation prompt skeleton for a role')
+  .argument('<role>', 'investigation | implementation | review | audit')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Prints a fill-in-the-blanks delegation prompt for the given role. Works',
+      'outside a ChangeLedger repo — the skeletons ship inside the package.',
+      '',
+      '`audit` is a read-only inspection of a change already in `in-validation`,',
+      'after review already passed; it never issues a verdict or moves the change.',
+      '',
+      'Examples:',
+      '  changeledger agent-prompt investigation',
+      '  changeledger agent-prompt implementation',
+      '  changeledger agent-prompt review',
+      '  changeledger agent-prompt audit',
+    ].join('\n'),
+  )
+  .action(action((role) => agentPrompt(role)));
+
+program
+  .command('agent-context')
+  .description('print a self-contained minimal context for a delegated role')
+  .argument('<role>', 'investigation | implementation | review | audit')
+  .argument(
+    '[change-id]',
+    'optional for investigation; required for implementation, review and audit',
+  )
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Use only when a delegation prompt emitted by `changeledger agent-prompt`',
+      'identifies you as that role. This replaces the normal core bootstrap for',
+      'the delegated leaf; normal agents still run `changeledger context` first.',
+      '',
+      '`audit` requires a change in `in-validation`; it is read-only inspection',
+      'after review already passed, and never issues a verdict or moves the change.',
+      '',
+      'Examples:',
+      '  changeledger agent-context investigation',
+      '  changeledger agent-context investigation <id>',
+      '  changeledger agent-context implementation <id>',
+      '  changeledger agent-context review <id>',
+      '  changeledger agent-context audit <id>',
     ].join('\n'),
   )
-  .action(action((input) => context(input)));
+  .action(action((role, changeId) => agentContext(role, changeId)));
 
 program
   .command('status')
@@ -192,7 +328,7 @@ program
     [
       '',
       'Terminal moves are not accepted here: use `changeledger discard <id> "<reason>"`',
-      'to discard, and human validation in the viewer to reach done.',
+      'to discard. Only human validation in the viewer can reach done.',
       '',
       'Examples:',
       '  changeledger status <id> in-progress',
@@ -201,11 +337,41 @@ program
   )
   .action(
     action((id, st) => {
-      status(id, st);
+      status(id, st, process.cwd(), { actor: 'agent' });
       console.log(`#${id} → ${st}`);
     }),
   );
 
+program
+  .command('validation')
+  .description('reject an in-validation change; accepting it remains human-only')
+  .argument('<id>')
+  .argument('<verdict>', 'fail')
+  .argument('<reason...>')
+  .action(
+    action((id, verdict, reasonParts) => {
+      if (verdict !== 'fail')
+        throw new Error(
+          'validation only accepts fail; human validation in the viewer accepts changes',
+        );
+      const reason = reasonParts.join(' ').trim();
+      validation(id, 'fail', { reason, actor: 'agent' });
+      console.log(`#${id} validation fail`);
+    }),
+  );
+
+program
+  .command('reopen')
+  .description('reopen a provisional done change with a reason')
+  .argument('<id>')
+  .argument('<reason...>')
+  .action(
+    action((id, reasonParts) => {
+      reopen(id, reasonParts.join(' ').trim(), process.cwd(), { actor: 'agent' });
+      console.log(`#${id} → in-progress`);
+    }),
+  );
+
 program
   .command('discard')
   .description('discard a change (terminal; keeps the record and reason)')
@@ -280,6 +446,8 @@ program
       '  changeledger archive <id>',
       '  changeledger archive --graduated',
       '  changeledger archive --graduated --dry-run',
+      '',
+      'To reverse an archive, edit `archived: false` in the change frontmatter directly.',
     ].join('\n'),
   )
   .action(
@@ -295,22 +463,11 @@ program
       }
       if (options.dryRun) throw new Error('--dry-run requires --graduated');
       if (!id) throw new Error('archive requires <id> or --graduated');
-      archive(id, true);
+      archive(id);
       console.log(`#${id} archived`);
     }),
   );
 
-program
-  .command('unarchive')
-  .description('show a change in the viewer')
-  .argument('<id>')
-  .action(
-    action((id) => {
-      archive(id, false);
-      console.log(`#${id} unarchived`);
-    }),
-  );
-
 program
   .command('log')
   .description('append a timestamped Log entry')
@@ -389,6 +546,32 @@ program
     }),
   );
 
+program
+  .command('search')
+  .description('deterministic lexical search over changes (incl. archived) and specs')
+  .argument('<query...>', 'search terms')
+  .option('--limit <n>', 'max results (default 10)')
+  .option(
+    '--type <type>',
+    'filter by a change type configured in .changeledger/config.yml (types:); excludes specs',
+  )
+  .option(
+    '--status <status>',
+    'filter by a change status configured in .changeledger/config.yml (statuses:); excludes specs',
+  )
+  .option('--json', 'print JSON')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger search wallet',
+      '  changeledger search wallet --type bug --status done',
+      '  changeledger search "app check" --json',
+    ].join('\n'),
+  )
+  .action(action((queryParts, options) => runSearch(queryParts, options)));
+
 program
   .command('graduate')
   .description('graduate a done change to persistent truth')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changeledger",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Turn conversations into buildable changes.",
   "type": "module",
   "bin": {

package/src/check.mjs

@@ -2,6 +2,7 @@
 // { errors, warnings }. No IO — the `changeledger check` command does the IO and printing.
 
 import { parseChange } from './change.mjs';
+import { hasFixableDefects } from './fix.mjs';
 import { CANONICAL_STATUSES, canTransition, parseLogEvent } from './lifecycle.mjs';
 import { compareVersions, parseVersion, RELEASE_IMPACTS } from './release.mjs';
 
@@ -32,6 +33,7 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
     const fm = c.frontmatter ?? {};
 
     checkConflictMarkers(c, err);
+    checkAutoFixable(c, fm, warn);
 
     for (const k of REQUIRED) if (!(k in fm)) err(c, `missing frontmatter "${k}"`);
     if (fm.created && !ISO_UTC.test(fm.created)) err(c, `created not ISO 8601 UTC: ${fm.created}`);
@@ -317,6 +319,16 @@ function* graduationMarkers(change) {
 // underline, but ChangeLedger uses ATX headings, so this is safe in practice.
 const CONFLICT = /^(<{7}|={7}|>{7})(\s|$)/;
 
+// Hints at `changeledger fix` rather than duplicating its repair rules: reuses
+// the same pure detector so the two commands can never disagree about what
+// counts as auto-fixable.
+function checkAutoFixable(c, fm, warn) {
+  if (typeof c.text !== 'string') return;
+  if (hasFixableDefects(c.text)) {
+    warn(c, `auto-fixable format defect(s) found; run: changeledger fix ${fm.id ?? ''}`.trimEnd());
+  }
+}
+
 function checkConflictMarkers(c, err) {
   if (typeof c.text !== 'string') return;
   const lines = c.text.split('\n');

package/src/commands/agent-context.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseChange } from '../change.mjs';
+import { findChangeledgerDir, loadConfig } from '../config.mjs';
+import { beginSentinel, endSentinel, VERSION } from '../framing.mjs';
+import { contractTemplatesDir } from '../paths.mjs';
+import { resolveChange } from '../repo.mjs';
+import { transversalPolicy } from './context.mjs';
+
+const ROLES = ['investigation', 'implementation', 'review', 'audit'];
+const ALLOWED_STATUSES = {
+  implementation: ['approved', 'in-progress'],
+  review: ['in-review'],
+  audit: ['in-validation'],
+};
+
+function requireRepo(cwd) {
+  const dir = findChangeledgerDir(cwd);
+  if (!dir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+  return dir;
+}
+
+function capsule(role) {
+  return fs
+    .readFileSync(path.join(contractTemplatesDir, 'agent-contexts', `${role}.md`), 'utf8')
+    .trim();
+}
+
+function selectedChange(role, changeId, cwd) {
+  if (role !== 'investigation' && !changeId) {
+    throw new Error(`role ${role} requires a change id`);
+  }
+  if (!changeId) return undefined;
+
+  const resolved = resolveChange(cwd, changeId);
+  const text = fs.readFileSync(resolved.file, 'utf8');
+  const { id, status } = parseChange(text).frontmatter;
+  const allowed = ALLOWED_STATUSES[role];
+  if (allowed && !allowed.includes(status)) {
+    const expected = allowed.join(' or ');
+    throw new Error(`role ${role} requires change status ${expected}; got ${status}`);
+  }
+  return { id, text };
+}
+
+export function buildAgentContext(role, changeId, cwd = process.cwd()) {
+  if (!ROLES.includes(role)) {
+    throw new Error(`Unknown role "${role}" — valid roles: ${ROLES.join(', ')}`);
+  }
+  const changeledgerDir = requireRepo(cwd);
+  const selected = selectedChange(role, changeId, cwd);
+  const change = selected ? ` — change: #${selected.id}` : '';
+  const sections = [
+    beginSentinel('AGENT CONTEXT', `role: ${role}${change} — v${VERSION}`),
+    transversalPolicy(loadConfig(changeledgerDir)),
+    capsule(role),
+  ];
+  if (selected) sections.push('---\n\n# Selected change', selected.text.trim());
+  sections.push(endSentinel('AGENT CONTEXT'));
+  return `${sections.join('\n\n')}\n`;
+}
+
+export function agentContext(role, changeId, cwd = process.cwd(), output = console.log) {
+  output(buildAgentContext(role, changeId, cwd).trimEnd());
+}

package/src/commands/agent-prompt.mjs

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { beginSentinel, endSentinel, VERSION } from '../framing.mjs';
+import { contractTemplatesDir } from '../paths.mjs';
+
+// Portable role skeletons ship inside the package, so this command works even
+// outside an initialized ChangeLedger repo — it never reads project config.
+const ROLES = ['investigation', 'implementation', 'review', 'audit'];
+
+export function buildAgentPrompt(role) {
+  if (!ROLES.includes(role)) {
+    throw new Error(`Unknown role "${role}" — valid roles: ${ROLES.join(', ')}`);
+  }
+  const file = path.join(contractTemplatesDir, 'agent-prompts', `${role}.md`);
+  const body = fs.readFileSync(file, 'utf8').trim();
+  const begin = beginSentinel('AGENT PROMPT', `role: ${role} — v${VERSION}`);
+  return `${begin}\n\n${body}\n\n${endSentinel('AGENT PROMPT')}\n`;
+}
+
+export function agentPrompt(role, output = console.log) {
+  output(buildAgentPrompt(role).trimEnd());
+}

package/src/commands/agent.mjs

@@ -23,7 +23,7 @@ export function status(
   id,
   newStatus,
   cwd = process.cwd(),
-  { ownerHandle = defaultOwnerHandle } = {},
+  { ownerHandle = defaultOwnerHandle, actor = 'human' } = {},
 ) {
   const { config, file } = locate(cwd, id);
   if (newStatus === 'discarded') {
@@ -34,6 +34,9 @@ export function status(
   if (newStatus === 'done') {
     throw new Error('to complete a change use human validation in the viewer');
   }
+  if (newStatus === 'approved' && actor !== 'human') {
+    throw new Error('only the human-facing viewer can approve a draft change');
+  }
   if (!(config.statuses ?? []).includes(newStatus)) {
     throw new Error(`Invalid status "${newStatus}". Valid: ${(config.statuses ?? []).join(', ')}`);
   }
@@ -41,7 +44,7 @@ export function status(
   mutateFileAtomic(file, (text) => {
     const fm = parseChange(text).frontmatter;
     if (fm.status === 'done' && newStatus === 'in-progress') {
-      throw new Error('only the human-facing viewer can reopen a done change');
+      throw new Error('to reopen a done change use `changeledger reopen <id> "<reason>"`');
     }
     // Validate the move before any in-memory mutation, so an illegal transition
     // leaves the file byte-for-byte unchanged. The review gate reads review_required
@@ -110,7 +113,7 @@ export function review(id, verdict, { mode, reason } = {}, cwd = process.cwd())
 
 // Records the human verdict for the complete change. This is intentionally
 // separate from `status`: only the human-facing viewer may close a change.
-export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
+export function validation(id, verdict, { reason, actor = 'human' } = {}, cwd = process.cwd()) {
   const { config, file } = locate(cwd, id);
   mutateFileAtomic(file, (text) => {
     const fm = parseChange(text).frontmatter;
@@ -137,7 +140,7 @@ export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
       nowUtc(),
       verdict === 'pass'
         ? 'validation → done (human accepted)'
-        : `validation → in-progress (human rejected): ${reason}`,
+        : `validation → in-progress (${actor} rejected): ${reason}`,
     );
     if (verdict === 'pass') assertChangeTextValid(config, path.basename(file), text);
     return text;
@@ -145,9 +148,9 @@ export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
   return file;
 }
 
-// Human-only correction path while `done` is still provisional. Graduation,
+// Correction path while `done` is still provisional. Graduation,
 // skip, archive and release membership are durable boundaries and fail closed.
-export function reopen(id, reason, cwd = process.cwd()) {
+export function reopen(id, reason, cwd = process.cwd(), { actor = 'human' } = {}) {
   if (!String(reason ?? '').trim()) throw new Error('reopen requires a reason');
   const { config, file, repoRoot } = locate(cwd, id);
   const releasesDir = resolveReleasesDir(repoRoot);
@@ -171,7 +174,7 @@ export function reopen(id, reason, cwd = process.cwd()) {
         reviewRequired: Boolean(config.types?.[fm.type]?.review_required),
       });
       text = setStatus(text, 'in-progress');
-      return appendLog(text, nowUtc(), `status: done → in-progress (human reopened): ${reason}`);
+      return appendLog(text, nowUtc(), `status: done → in-progress (${actor} reopened): ${reason}`);
     });
     return file;
   });
@@ -209,11 +212,11 @@ export function discard(id, reason, cwd = process.cwd()) {
   return file;
 }
 
-export function archive(id, on, cwd = process.cwd()) {
+export function archive(id, cwd = process.cwd()) {
   const { file } = locate(cwd, id);
   mutateFileAtomic(file, (text) => {
-    text = setArchived(text, on);
-    return appendLog(text, nowUtc(), on ? 'archived' : 'unarchived');
+    text = setArchived(text, true);
+    return appendLog(text, nowUtc(), 'archived');
   });
   return file;
 }

package/src/commands/check.mjs

@@ -1,12 +1,67 @@
 import { checkRepo } from '../check.mjs';
+import { findChangeledgerDir, integrationBranch, loadConfig } from '../config.mjs';
 import { getSchemaVersion, SUPPORTED_SCHEMA_VERSION } from '../config-migration.mjs';
 import { checkContract } from '../contract.mjs';
+import { defaultBaseBranch, lintCommitRange } from '../git.mjs';
 import { loadRepo } from '../repo.mjs';
 
+// Declared integration branch, when a ChangeLedger repo (and the key) exists.
+// Outside a repo the lint still works on plain git, so absence is undefined,
+// not an error; a malformed declared value still fails fast in
+// `integrationBranch`.
+function configuredIntegrationBranch(cwd) {
+  const changeledgerDir = findChangeledgerDir(cwd);
+  if (!changeledgerDir) return undefined;
+  return integrationBranch(loadConfig(changeledgerDir));
+}
+
+// Lints `base..HEAD` for the canonical `[#id]` commit marker (merges and
+// `chore(release)` prep are exempt) — no ChangeLedger repo required, just git.
+function checkCommits(args, commitsIdx, cwd, output, json) {
+  const provided = args[commitsIdx + 1];
+  const base = provided && !provided.startsWith('--') ? provided : undefined;
+
+  let resolvedBase;
+  let violations;
+  try {
+    resolvedBase = base ?? configuredIntegrationBranch(cwd) ?? defaultBaseBranch(cwd);
+    violations = lintCommitRange(cwd, `${resolvedBase}..HEAD`);
+  } catch (e) {
+    if (json)
+      output.log(
+        JSON.stringify(
+          { errors: [{ file: '(commits)', message: e.message }], warnings: [] },
+          null,
+          2,
+        ),
+      );
+    else output.error(`  error  (commits): ${e.message}`);
+    return 1;
+  }
+
+  const errors = violations.map((v) => ({
+    file: '(commits)',
+    message: `${v.sha} missing [#id] marker: "${v.subject}"`,
+  }));
+
+  if (json) {
+    output.log(JSON.stringify({ errors, warnings: [] }, null, 2));
+    return errors.length ? 1 : 0;
+  }
+
+  for (const e of errors) output.error(`  error  ${e.file}: ${e.message}`);
+  const scope = `commits ${resolvedBase}..HEAD`;
+  if (!errors.length) output.log(`✓ ${scope} valid`);
+  else output.log(`\n${errors.length} error(s) — ${scope}`);
+  return errors.length ? 1 : 0;
+}
+
 // Validates the repo (or a single change with `changeledger check <id>`). Prints findings
 // and returns an exit code (1 if errors).
 export function check(args = [], cwd = process.cwd(), output = console) {
   const json = args.includes('--json');
+  const commitsIdx = args.indexOf('--commits');
+  if (commitsIdx !== -1) return checkCommits(args, commitsIdx, cwd, output, json);
   const id = args.find((a) => !a.startsWith('--'));
 
   let repo;