changeledger 0.9.0 → 0.11.0

package/AGENTS.md

@@ -3,7 +3,7 @@
 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 — a normal agent must run `changeledger context` directly.
@@ -20,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

@@ -147,6 +147,11 @@ there is no linked or copied contract under `.changeledger/`. Run
 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
 
 Repos created before ChangeLedger 0.6 may have an older configuration schema.

package/bin/changeledger.mjs

@@ -18,7 +18,9 @@ import {
 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,
@@ -29,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';
@@ -41,9 +44,9 @@ const USAGE = `ChangeLedger (changeledger)
 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 | agent-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.`;
 
@@ -60,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)')
@@ -136,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}`);
@@ -146,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 commit: the clean subject gets a ChangeLedger: [#A] [#B] body.',
+      '',
+      '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')
@@ -153,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',
     [
@@ -173,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',
@@ -180,14 +258,15 @@ program
       '  changeledger context review',
       '  changeledger context release',
       '  changeledger context 20260630-225212',
+      '  changeledger context --have 0123456789ab',
     ].join('\n'),
   )
-  .action(action((input) => context(input)));
+  .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')
+  .argument('<role>', 'investigation | implementation | review | audit')
   .addHelpText(
     'after',
     [
@@ -195,10 +274,14 @@ program
       '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)));
@@ -206,8 +289,11 @@ program
 program
   .command('agent-context')
   .description('print a self-contained minimal context for a delegated role')
-  .argument('<role>', 'investigation | implementation | review')
-  .argument('[change-id]', 'optional for investigation; required for implementation and review')
+  .argument('<role>', 'investigation | implementation | review | audit')
+  .argument(
+    '[change-id]',
+    'optional for investigation; required for implementation, review and audit',
+  )
   .addHelpText(
     'after',
     [
@@ -216,11 +302,15 @@ program
       '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((role, changeId) => agentContext(role, changeId)));
@@ -356,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(
@@ -371,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')
@@ -465,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.9.0",
+  "version": "0.11.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

@@ -7,10 +7,11 @@ import { contractTemplatesDir } from '../paths.mjs';
 import { resolveChange } from '../repo.mjs';
 import { transversalPolicy } from './context.mjs';
 
-const ROLES = ['investigation', 'implementation', 'review'];
+const ROLES = ['investigation', 'implementation', 'review', 'audit'];
 const ALLOWED_STATUSES = {
   implementation: ['approved', 'in-progress'],
   review: ['in-review'],
+  audit: ['in-validation'],
 };
 
 function requireRepo(cwd) {

package/src/commands/agent-prompt.mjs

@@ -5,7 +5,7 @@ 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'];
+const ROLES = ['investigation', 'implementation', 'review', 'audit'];
 
 export function buildAgentPrompt(role) {
   if (!ROLES.includes(role)) {

package/src/commands/agent.mjs

@@ -212,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} ${v.reason}: "${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;

package/src/commands/commit.mjs

@@ -0,0 +1,44 @@
+// Executable commit contract: composes the canonical `[#id]` marker and
+// delegates to `git commit`, instead of relying on agents to remember the
+// convention documented in prose (templates/contract/implement.md).
+
+import { mutatingRun } from '../git.mjs';
+import { loadRepo } from '../repo.mjs';
+
+const SUBJECT_RE = /^[a-zA-Z]+\([^()]+\):\s+\S.*/;
+
+// Validates the subject, resolves the change id(s) to append, and creates the
+// commit. Never invokes git unless the subject and id resolution both succeed
+// — no partial/incorrect commit is ever created. Returns the final subject.
+export function commit({ message, ids = [] } = {}, cwd = process.cwd(), run = mutatingRun) {
+  if (!message || !SUBJECT_RE.test(message)) {
+    throw new Error(
+      `Subject must follow the conventional form "type(scope): description", got: "${message ?? ''}"`,
+    );
+  }
+
+  const repo = loadRepo(cwd);
+  let resolvedIds = ids;
+  if (!resolvedIds.length) {
+    const active = repo.changes.filter((c) => c.frontmatter.status === 'in-progress');
+    if (active.length !== 1) {
+      if (active.length === 0) {
+        throw new Error('No change is in-progress; pass --id <change-id> explicitly.');
+      }
+      const candidates = active.map((c) => c.frontmatter.id).join(', ');
+      throw new Error(
+        `Ambiguous: ${active.length} changes are in-progress (${candidates}); pass --id <change-id> explicitly.`,
+      );
+    }
+    resolvedIds = [active[0].frontmatter.id];
+  }
+
+  const markers = resolvedIds.map((id) => `[#${id}]`).join(' ');
+  const multiple = resolvedIds.length > 1;
+  const subject = multiple ? message : `${message} ${markers}`;
+  const args = multiple
+    ? ['commit', '-m', subject, '-m', `ChangeLedger: ${markers}`]
+    : ['commit', '-m', subject];
+  run(args, repo.repoRoot);
+  return subject;
+}

package/src/commands/context.mjs

@@ -1,8 +1,8 @@
 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 { findChangeledgerDir, integrationBranch, loadConfig } from '../config.mjs';
+import { beginSentinel, contentRev, endSentinel, VERSION } from '../framing.mjs';
 import { contractTemplatesDir } from '../paths.mjs';
 import { resolveChange } from '../repo.mjs';
 
@@ -31,9 +31,16 @@ function fragment(name) {
   return fs.readFileSync(path.join(contractTemplatesDir, `${name}.md`), 'utf8').trim();
 }
 
-function beginDelimiter(mode, changeId) {
+function beginDelimiter(mode, changeId, rev, extra = '') {
   const change = changeId ? ` — change: #${changeId}` : '';
-  return beginSentinel('CONTEXT', `mode: ${mode}${change} — v${VERSION}`);
+  const revPart = rev ? ` — rev:${rev}` : '';
+  return beginSentinel('CONTEXT', `mode: ${mode}${change} — v${VERSION}${revPart}${extra}`);
+}
+
+// Short confirmation body returned by `--have` when the caller's retained
+// revision still matches: no contract text, just the framed confirmation.
+function unchangedBody(rev) {
+  return `Context unchanged since rev:${rev}. Skip reload; continue with the retained capture.`;
 }
 
 // Resolved defaults so an agent never reads `.changeledger/config.yml` raw to
@@ -52,9 +59,12 @@ function effectiveTdd(config) {
 }
 
 // The transversal policy line every composition anchors on: effective language
-// and tdd with defaults already resolved.
+// and tdd with defaults already resolved. The integration branch appears only
+// when declared — absence means the repo keeps branch auto-detection.
 export function transversalPolicy(config) {
-  return `Effective policy: language=${effectiveLanguage(config)} — tdd=${effectiveTdd(config)}`;
+  const base = `Effective policy: language=${effectiveLanguage(config)} — tdd=${effectiveTdd(config)}`;
+  const branch = integrationBranch(config);
+  return branch ? `${base} — integration_branch=${branch}` : base;
 }
 
 // Type-specific policy for change-id contexts: adds review requirement and the
@@ -88,7 +98,11 @@ function dependencyBlock(dependsOn, cwd) {
   return `## Dependencies\n\n${lines.join('\n')}`;
 }
 
-function compose(mode, fragments, options = {}) {
+// Composes the body (everything between the BEGIN and END lines), derives its
+// `rev` from that body alone — never from the framing lines that quote it —
+// then returns both the rev and the full rendered text so callers can decide
+// whether a `--have` match makes the full body unnecessary.
+function composeResult(mode, fragments, options = {}) {
   const {
     changeText,
     incremental = true,
@@ -96,14 +110,15 @@ function compose(mode, fragments, options = {}) {
     policy = undefined,
     dependencies = undefined,
   } = options;
-  const sections = [beginDelimiter(mode, changeId)];
-  if (incremental) sections.push(INCREMENTAL_NOTICE);
-  if (policy) sections.push(policy);
-  sections.push(...fragments.map(fragment));
-  if (dependencies) sections.push(dependencies);
-  if (changeText) sections.push('---\n\n# Selected change\n', changeText.trim());
-  sections.push(END_DELIMITER);
-  return `${sections.join('\n\n')}\n`;
+  const body = [];
+  if (incremental) body.push(INCREMENTAL_NOTICE);
+  if (policy) body.push(policy);
+  body.push(...fragments.map(fragment));
+  if (dependencies) body.push(dependencies);
+  if (changeText) body.push('---\n\n# Selected change\n', changeText.trim());
+  const rev = contentRev(body.join('\n\n'));
+  const sections = [beginDelimiter(mode, changeId, rev), ...body, END_DELIMITER];
+  return { mode, changeId, rev, text: `${sections.join('\n\n')}\n` };
 }
 
 function requireRepo(cwd) {
@@ -112,14 +127,15 @@ function requireRepo(cwd) {
   return dir;
 }
 
-export function buildContext(input, cwd = process.cwd()) {
-  const changeledgerDir = requireRepo(cwd);
-  const config = loadConfig(changeledgerDir);
+function composeInput(input, cwd, config) {
   if (!input) {
-    return compose('core', ['core'], { incremental: false, policy: transversalPolicy(config) });
+    return composeResult('core', ['core'], {
+      incremental: false,
+      policy: transversalPolicy(config),
+    });
   }
   if (MODES.includes(input)) {
-    return compose(input, MODE_CONTEXT[input], { policy: transversalPolicy(config) });
+    return composeResult(input, MODE_CONTEXT[input], { policy: transversalPolicy(config) });
   }
 
   let resolved;
@@ -135,7 +151,7 @@ export function buildContext(input, cwd = process.cwd()) {
   const { id, status, type, depends_on: dependsOn } = parseChange(text).frontmatter;
   const selected = STATUS_CONTEXT[status];
   if (!selected) throw new Error(`No context mapping for change status "${status}"`);
-  return compose(selected.mode, selected.fragments, {
+  return composeResult(selected.mode, selected.fragments, {
     changeText: text,
     changeId: id,
     policy: changePolicyBlock(config, type),
@@ -143,6 +159,24 @@ export function buildContext(input, cwd = process.cwd()) {
   });
 }
 
-export function context(input, cwd = process.cwd(), output = console.log) {
-  output(buildContext(input, cwd).trimEnd());
+// `options.have` names a previously captured `rev`. A match returns a short
+// framed `unchanged` confirmation instead of the full contract body; any
+// mismatch (stale or invented) falls back to the complete normal output.
+export function buildContext(input, cwd = process.cwd(), options = {}) {
+  const changeledgerDir = requireRepo(cwd);
+  const config = loadConfig(changeledgerDir);
+  const result = composeInput(input, cwd, config);
+  if (options.have && options.have === result.rev) {
+    const sections = [
+      beginDelimiter(result.mode, result.changeId, result.rev, ' — unchanged'),
+      unchangedBody(result.rev),
+      END_DELIMITER,
+    ];
+    return `${sections.join('\n\n')}\n`;
+  }
+  return result.text;
+}
+
+export function context(input, options = {}, cwd = process.cwd(), output = console.log) {
+  output(buildContext(input, cwd, options).trimEnd());
 }