changeledger 0.8.0 → 0.10.0

package/src/commands/commit.mjs

@@ -0,0 +1,39 @@
+// 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 subject = `${message} ${resolvedIds.map((id) => `[#${id}]`).join(' ')}`;
+  run(['commit', '-m', subject], repo.repoRoot);
+  return subject;
+}

package/src/commands/context.mjs

@@ -1,13 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseChange } from '../change.mjs';
-import { findChangeledgerDir, loadConfig } from '../config.mjs';
-import { contractTemplatesDir, packageRoot } from '../paths.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';
 
-const VERSION = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
-const END_DELIMITER =
-  '===== CHANGELEDGER CONTEXT END — if this line is missing, the output was truncated: stop and re-run =====';
+const END_DELIMITER = endSentinel('CONTEXT');
 const MODES = ['implement', 'review', 'spec', 'release'];
 const MODE_CONTEXT = {
   implement: ['implement', 'delegation', 'handoff'],
@@ -32,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 `===== CHANGELEDGER CONTEXT BEGIN — 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
@@ -53,9 +59,12 @@ function effectiveTdd(config) {
 }
 
 // The transversal policy line every composition anchors on: effective language
-// and tdd with defaults already resolved.
-function transversalPolicy(config) {
-  return `Effective policy: language=${effectiveLanguage(config)} — tdd=${effectiveTdd(config)}`;
+// 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) {
+  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
@@ -89,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,
@@ -97,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) {
@@ -113,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;
@@ -136,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),
@@ -144,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());
 }

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,11 +34,23 @@ 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 — 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
@@ -47,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');
 
@@ -60,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;
 }
@@ -134,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\``);
     }
   }