changeledger 0.4.0 → 0.6.0

package/AGENTS.md

@@ -5,15 +5,21 @@ under `.changeledger/changes/`, persistent truth under `.changeledger/specs/`.
 
 <!-- changeledger -->
 > [!IMPORTANT]
-> This repo uses **ChangeLedger**. Read and follow [`.changeledger/AGENTS.md`](.changeledger/AGENTS.md)
-> (the change contract). If it is missing, run `changeledger register`.
+> This repo uses **ChangeLedger**. Before creating or modifying files, run
+> `changeledger context` (or `changeledger context <change-id>`) and follow its output.
+> If the command is unavailable, stop and restore/install ChangeLedger; do not proceed from memory.
 
-The **canonical ChangeLedger contract** (the convention every consuming repo
-follows) is shipped as [`templates/AGENTS.md`](templates/AGENTS.md) and linked
-into each repo as `.changeledger/AGENTS.md`. Edit the convention there, not here.
+The canonical ChangeLedger contract is split into task-focused fragments under
+[`templates/contract/`](templates/contract/). The deterministic
+`changeledger context` command composes them; consuming repos keep only the
+bootstrap above, not a linked or copied contract.
 
 ## Project-specific notes
 
+- Product evolution follows the complexity budget and no-goals in
+  [`INTENT.md`](INTENT.md): prefer observed problems and a small deterministic,
+  local-first core; AI orchestration, memory and cloud services belong only in
+  optional integrations.
 - Managed with **pnpm**; lint/format via **Biome**. Runtime dependencies are
   allowed only when they are mature and justified: the CLI uses `yaml` for
   config/frontmatter parsing, and the viewer uses `lit-html`, `marked`,
@@ -21,5 +27,5 @@ into each repo as `.changeledger/AGENTS.md`. Edit the convention there, not here
 - `pnpm verify` (lint + test + `changeledger check`) is the full quality gate. The
   versioned `hooks/pre-commit` runs `lint-staged`, `pnpm test` and `changeledger check`
   so staged formatting stays compatible with partial commits.
-- The contract you edit for the convention is `templates/AGENTS.md` — it is the
-  artifact that `changeledger init`/`register` symlink into other repos.
+- Edit the convention in `templates/contract/`; keep each rule in one fragment
+  so task contexts compose without duplicated truth.

package/README.md

@@ -27,9 +27,10 @@ changeledger init
 changeledger view
 ```
 
-`changeledger init` creates `.changeledger/`, gives the project a stable identity and links the
-installed agent contract. The repository keeps only its configuration and
-documents; the CLI and viewer remain in the global package.
+`changeledger init` creates `.changeledger/`, gives the project a stable identity
+and installs a small context bootstrap in the project-owned `AGENTS.md`. The
+repository keeps only its configuration and documents; the CLI, viewer and
+canonical contract fragments remain in the global package.
 
 ## The workflow
 
@@ -62,8 +63,8 @@ other tools discover it through the repository's `AGENTS.md` reference.
 
 With the default Definition of Ready policy, `changeledger check` verifies that acceptance
 criteria are test-grade and mapped to actionable tasks. Repositories doing
-exploratory work can set `tdd: false`; the complete rules live in
-[`AGENTS.md`](AGENTS.md).
+exploratory work can set `tdd: false`; run `changeledger context spec` or
+`changeledger context implement` for the complete task-specific rules.
 
 ## Essential commands
 
@@ -71,7 +72,7 @@ exploratory work can set `tdd: false`; the complete rules live in
 
 ```sh
 changeledger init                         # initialize and register the current repository
-changeledger register                     # relink a moved or freshly cloned repository
+changeledger register                     # refresh registration and the context bootstrap
 changeledger view                         # view every registered project
 changeledger view .                       # view only the current project
 changeledger check [id]                   # validate the repository or one change
@@ -128,17 +129,38 @@ CI:
 changeledger check || exit 1
 ```
 
-The contract itself ships with the CLI and is linked as `.changeledger/AGENTS.md`. It is
-per-machine and gitignored, so upgrades do not leave committed copies behind.
-Run `changeledger register` after cloning, moving a repository or updating the global
-installation.
+The contract ships as task-focused fragments and is compiled on demand:
+
+```sh
+changeledger context                    # minimal non-negotiable core
+changeledger context <change-id>        # lifecycle-aware rules + selected change
+changeledger context review             # explicit task mode
+```
+
+`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.
+
+### Upgrading an existing repo's configuration
+
+Repos created before ChangeLedger 0.6 may have an older configuration schema.
+Run this to inspect and apply available migrations:
+
+```sh
+changeledger config migrate --dry-run   # preview changes without writing
+changeledger config migrate             # apply atomically
+changeledger check                      # confirm the repo is valid
+```
+
+Migrations are safe to run more than once — if the config is already current,
+the command reports so and exits without modifying any file.
 
 ## Compatibility and security
 
 - Node.js **24+**.
 - Tested on Linux, macOS and Windows.
-- On Windows, contract linking uses a symlink when permitted and falls back to a
-  copy when Developer Mode or administrator privileges are unavailable.
+- No symlink privileges are required on Windows; context fragments remain in the
+  installed package and the CLI prints them on demand.
 - The viewer binds to loopback and treats repository content as untrusted input.
   See [`SECURITY.md`](SECURITY.md) for the threat model and private reporting
   instructions.
@@ -151,7 +173,7 @@ latest `0.x` release to receive fixes.
 
 Contributions are welcome. Development setup, quality gates and repository
 conventions live in [`CONTRIBUTING.md`](CONTRIBUTING.md). The canonical agent
-contract is [`AGENTS.md`](AGENTS.md).
+contract is composed from [`templates/contract/`](templates/contract/).
 
 ## Language policy
 

package/bin/changeledger.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import {
   archive,
@@ -13,21 +14,27 @@ import {
   task,
 } from '../src/commands/agent.mjs';
 import { check } from '../src/commands/check.mjs';
+import { context } from '../src/commands/context.mjs';
 import { graduate, pendingGraduation, skipGraduation } from '../src/commands/graduate.mjs';
 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 { view } from '../src/commands/view.mjs';
+import { findChangeledgerDir } from '../src/config.mjs';
+import { applyMigration, SUPPORTED_SCHEMA_VERSION } from '../src/config-migration.mjs';
 import { nowUtc } from '../src/paths.mjs';
 
+const { version } = createRequire(import.meta.url)('../package.json');
+
 const USAGE = `ChangeLedger (changeledger)
 
   changeledger init                          set up .changeledger/ in the current repo (+ register it)
-  changeledger register                      (re)link this repo's path in the global registry
+  changeledger register                      refresh registration and context bootstrap
   changeledger new <type> <slug> <title>     scaffold a new change (slug is the English filename)
   changeledger view [port]                   launch the local viewer (default port 4040)
   changeledger check [id] [--json]           validate the repo or one change
+  changeledger context [mode|change-id]       print deterministic task context
   changeledger status <id> <status>          move a change's lifecycle status
   changeledger discard <id> "<reason>"       discard a change (terminal; keeps the record)
   changeledger review <id> pass              independent review passed → in-validation
@@ -43,6 +50,7 @@ const USAGE = `ChangeLedger (changeledger)
   changeledger graduate <change-id> <spec-slug> --into   graduate into an existing spec
   changeledger graduate <change-id> --skip [reason]   mark graduation reviewed, no spec
   changeledger graduate --pending                 list done changes not yet reviewed
+  changeledger config migrate [--dry-run]          migrate .changeledger/config.yml to schema ${SUPPORTED_SCHEMA_VERSION}
   changeledger release init <version>             initialize release history at X.Y.Z
   changeledger release plan [--json]              calculate the next portable SemVer release
   changeledger release record <version>           record the calculated release manifest`;
@@ -63,6 +71,7 @@ function action(fn) {
 program
   .name('changeledger')
   .description('ChangeLedger (changeledger)')
+  .version(version, '-v, --version', 'output the installed version (-V also accepted)')
   .helpOption('-h, --help', 'display help for command')
   .addHelpText('after', `\n${USAGE}`);
 
@@ -78,7 +87,7 @@ program
 
 program
   .command('register')
-  .description("(re)link this repo's path in the global registry")
+  .description('refresh registration and context bootstrap')
   .action(
     action(() => {
       const { id, path: p } = registerRepo();
@@ -122,6 +131,12 @@ program
     }
   });
 
+program
+  .command('context')
+  .description('print deterministic task context')
+  .argument('[mode-or-change-id]')
+  .action(action((input) => context(input)));
+
 program
   .command('status')
   .description("move a change's lifecycle status")
@@ -318,6 +333,24 @@ program
     }),
   );
 
+const configCommand = program
+  .command('config')
+  .description('inspect and manage the repo configuration');
+
+configCommand
+  .command('migrate')
+  .description('migrate .changeledger/config.yml to the current schema')
+  .option('--dry-run', 'show the migration plan and candidate YAML without writing')
+  .action(
+    action((options) => {
+      const changeledgerDir = findChangeledgerDir();
+      if (!changeledgerDir) throw new Error('Not a ChangeLedger repo.');
+      const configFile = `${changeledgerDir}/config.yml`;
+      const result = applyMigration(configFile, { dryRun: options.dryRun ?? false });
+      console.log(result);
+    }),
+  );
+
 const releaseCommand = program
   .command('release')
   .description('plan and record portable SemVer releases');
@@ -368,8 +401,10 @@ releaseCommand
     }),
   );
 
-if (process.argv.length <= 2) {
+// Normalize -V to --version so both short aliases work identically.
+const argv = process.argv.map((a) => (a === '-V' ? '--version' : a));
+if (argv.length <= 2) {
   console.log(USAGE);
 } else {
-  program.parse();
+  program.parse(argv);
 }

package/package.json

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

package/src/commands/agent.mjs

@@ -59,7 +59,7 @@ export function status(
 }
 
 // Records the verdict of the independent review (run by a delegated subagent
-// with clean context — see AGENTS.md §6). `pass` advances to human validation;
+// with clean context — see `changeledger context review`). `pass` advances to human validation;
 // `fail` routes it back: `retry` for a defect inside the contract (the
 // implementer fixes), `block` for one that escalates to a human. Requires the
 // change to be in-review.

package/src/commands/check.mjs

@@ -1,4 +1,5 @@
 import { checkRepo } from '../check.mjs';
+import { getSchemaVersion, SUPPORTED_SCHEMA_VERSION } from '../config-migration.mjs';
 import { checkContract } from '../contract.mjs';
 import { loadRepo } from '../repo.mjs';
 
@@ -22,7 +23,16 @@ export function check(args = [], cwd = process.cwd(), output = console) {
 
   const { errors, warnings } = checkRepo(repo, { id });
 
-  // Discovery validation needs the filesystem (root contract, symlink), so it
+  // Schema version detection — warn without mutating.
+  const schemaVersion = getSchemaVersion(repo.config);
+  if (!id && schemaVersion < SUPPORTED_SCHEMA_VERSION) {
+    warnings.push({
+      file: '.changeledger/config.yml',
+      message: `config schema ${schemaVersion} is outdated; run \`changeledger config migrate --dry-run\``,
+    });
+  }
+
+  // Discovery validation needs the filesystem (root contract bootstrap), so it
   // lives here, not in the pure validator. Repo-wide only.
   if (!id) {
     for (const message of checkContract(repo.repoRoot, repo.changeledgerDir)) {

package/src/commands/context.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseChange } from '../change.mjs';
+import { findChangeledgerDir } from '../config.mjs';
+import { contractTemplatesDir } from '../paths.mjs';
+import { resolveChange } from '../repo.mjs';
+
+const MODES = ['implement', 'review', 'spec', 'release'];
+const MODE_CONTEXT = {
+  implement: ['core', 'implement', 'readiness'],
+  review: ['core', 'review'],
+  spec: ['core', 'spec', 'readiness'],
+  release: ['core', 'release'],
+};
+const STATUS_CONTEXT = {
+  draft: { mode: 'spec', fragments: MODE_CONTEXT.spec },
+  approved: { mode: 'implement', fragments: MODE_CONTEXT.implement },
+  'in-progress': { mode: 'implement', fragments: MODE_CONTEXT.implement },
+  'in-review': { mode: 'review', fragments: ['core', 'review'] },
+  blocked: { mode: 'blocked', fragments: ['core', 'blocked'] },
+  'in-validation': { mode: 'validation', fragments: ['core', 'validation'] },
+  done: { mode: 'close', fragments: ['core', 'close'] },
+  discarded: { mode: 'discarded', fragments: ['core', 'discarded'] },
+};
+
+function fragment(name) {
+  return fs.readFileSync(path.join(contractTemplatesDir, `${name}.md`), 'utf8').trim();
+}
+
+function compose(mode, fragments, changeText) {
+  const sections = [`Mode: ${mode}`, ...fragments.map(fragment)];
+  if (changeText) sections.push('---\n\n# Selected change\n', changeText.trim());
+  return `${sections.join('\n\n')}\n`;
+}
+
+function requireRepo(cwd) {
+  if (!findChangeledgerDir(cwd)) {
+    throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+  }
+}
+
+export function buildContext(input, cwd = process.cwd()) {
+  requireRepo(cwd);
+  if (!input) return compose('core', ['core']);
+  if (MODES.includes(input)) return compose(input, MODE_CONTEXT[input]);
+
+  let resolved;
+  try {
+    resolved = resolveChange(cwd, input);
+  } catch {
+    throw new Error(
+      `Unknown context "${input}" — valid modes: ${MODES.join(', ')} (or pass a change id)`,
+    );
+  }
+
+  const text = fs.readFileSync(resolved.file, 'utf8');
+  const status = parseChange(text).frontmatter.status;
+  const selected = STATUS_CONTEXT[status];
+  if (!selected) throw new Error(`No context mapping for change status "${status}"`);
+  return compose(selected.mode, selected.fragments, text);
+}
+
+export function context(input, cwd = process.cwd(), output = console.log) {
+  output(buildContext(input, cwd).trimEnd());
+}

package/src/commands/init.mjs

@@ -2,20 +2,19 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { writeFileAtomic } from '../atomic-write.mjs';
-import { ensureGitignore, ensureReference, linkContract, rootContract } from '../contract.mjs';
+import { ensureReference, rootContract } from '../contract.mjs';
 import { templatesDir } from '../paths.mjs';
 import { register } from '../registry.mjs';
 import { serializeScalar } from '../yaml.mjs';
 
-// Sets up `.changeledger/` in the repo, gives it a stable identity, links the installed
-// AGENTS.md contract into `.changeledger/`, references it from the project's root
+// Sets up `.changeledger/`, installs the context bootstrap in the project-owned
 // AGENTS.md, and registers the repo in the global registry.
 export function init(cwd = process.cwd()) {
   const repoRoot = path.resolve(cwd);
   const changeledgerDir = path.join(repoRoot, '.changeledger');
   if (fs.existsSync(changeledgerDir)) {
     throw new Error(
-      '.changeledger/ already exists. Use `changeledger register` to (re)link this repo.',
+      '.changeledger/ already exists. Use `changeledger register` to refresh this repo.',
     );
   }
   // The root AGENTS.md is the project's own contract; we reference the tool's
@@ -34,9 +33,7 @@ export function init(cwd = process.cwd()) {
     `${fs.readFileSync(path.join(templatesDir, 'config.yml'), 'utf8')}\n# Project identity (stable; the global registry maps it to a path)\nproject_id: "${id}"\nproject_name: ${serializeScalar(name)}\n`,
   );
 
-  linkContract(changeledgerDir);
   ensureReference(repoRoot);
-  ensureGitignore(repoRoot);
 
   register({ id, name, path: repoRoot });
   return changeledgerDir;

package/src/commands/new.mjs

@@ -11,7 +11,7 @@ const LOCK_MTIME_STALE_MS = 30_000;
 
 // Scaffolds a new change file with the active stages for its type.
 // `slug` is the English filename slug (structure); `title` is the content title
-// (repo language). See AGENTS.md §7-§8.
+// (repo language). See `changeledger context spec`.
 export function newChange({ type, slug, title, owner, now }, cwd = process.cwd()) {
   const changeledgerDir = findChangeledgerDir(cwd);
   if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');

package/src/commands/register.mjs

@@ -1,13 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { findChangeledgerDir, loadConfig } from '../config.mjs';
-import { ensureGitignore, ensureReference, linkContract, rootContract } from '../contract.mjs';
+import { getSchemaVersion, SUPPORTED_SCHEMA_VERSION } from '../config-migration.mjs';
+import {
+  ensureReference,
+  removeLegacyContract,
+  removeLegacyGitignore,
+  rootContract,
+} from '../contract.mjs';
 import { register } from '../registry.mjs';
 
-// (Re)links the current repo's path to its config project_id in the global
-// registry, and regenerates the per-machine `.changeledger/AGENTS.md` contract link. Use
-// after moving the repo or cloning it on another machine.
-export function registerRepo(cwd = process.cwd()) {
+// Refreshes the repo bootstrap and registry path. Also migrates the per-machine
+// contract artifact left by legacy versions.
+export function registerRepo(cwd = process.cwd(), output = console) {
   const changeledgerDir = findChangeledgerDir(cwd);
   if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
 
@@ -16,11 +21,18 @@ export function registerRepo(cwd = process.cwd()) {
     throw new Error('config.yml has no project_id. Run `changeledger init` to create one.');
   }
 
+  const schemaVersion = getSchemaVersion(config);
+  if (schemaVersion < SUPPORTED_SCHEMA_VERSION) {
+    output.warn(
+      `warn  .changeledger/config.yml: config schema ${schemaVersion} is outdated; run \`changeledger config migrate --dry-run\``,
+    );
+  }
+
   const repoRoot = path.dirname(changeledgerDir);
   const name = config.project_name || path.basename(repoRoot);
 
-  linkContract(changeledgerDir);
-  ensureGitignore(repoRoot);
+  removeLegacyContract(changeledgerDir);
+  removeLegacyGitignore(repoRoot);
   if (fs.existsSync(rootContract(repoRoot))) ensureReference(repoRoot);
 
   register({ id: config.project_id, name, path: repoRoot });

package/src/commands/view.mjs

@@ -6,8 +6,12 @@ import { createRequestListener, staticFile } from '../viewer/server/router.mjs';
 import { hostnameOf, isAuthorizedWrite, isLocalHost } from '../viewer/server/security.mjs';
 
 export {
+  applyConfigMigration,
   changeStatus,
+  patchProjectConfig,
+  previewConfigMigration,
   readProjectConfig,
+  readProjectConfigStructured,
   repairProjectPath,
   resolveProjects,
   saveProjectConfig,

package/src/config-migration.mjs

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+import { writeFileAtomic } from './atomic-write.mjs';
+import { templatesDir } from './paths.mjs';
+
+export const SUPPORTED_SCHEMA_VERSION = 1;
+
+const CANONICAL_STATUSES = [
+  'draft',
+  'approved',
+  'in-progress',
+  'in-review',
+  'in-validation',
+  'blocked',
+  'done',
+  'discarded',
+];
+
+const BUILTIN_TYPES = ['feature', 'bug', 'refactor'];
+
+const BUILTIN_IMPACTS = {
+  feature: 'minor',
+  bug: 'patch',
+  audit: 'none',
+  refactor: 'none',
+  chore: 'none',
+};
+
+export function getSchemaVersion(config) {
+  const v = config.schema_version;
+  return typeof v === 'number' ? v : 0;
+}
+
+// Returns null when no migration needed; throws on invalid/future schema.
+// Otherwise returns { yaml: string, changes: string[] }.
+export function buildMigration(originalText) {
+  let doc;
+  try {
+    doc = parseDocument(originalText, { merge: false });
+  } catch (e) {
+    throw new Error(`Invalid YAML: ${e.message}`);
+  }
+  if (doc.errors.length) {
+    throw new Error(`Invalid YAML: ${doc.errors[0].message}`);
+  }
+
+  const config = doc.toJS() ?? {};
+  const current = getSchemaVersion(config);
+
+  if (current > SUPPORTED_SCHEMA_VERSION) {
+    throw new Error(
+      `config schema ${current} is newer than supported schema ${SUPPORTED_SCHEMA_VERSION}`,
+    );
+  }
+  if (current === SUPPORTED_SCHEMA_VERSION) {
+    return null;
+  }
+
+  const changes = [];
+
+  // schema_version: 1 — remove any existing value, then prepend to appear first
+  if (Object.hasOwn(config, 'schema_version')) {
+    doc.delete('schema_version');
+  }
+  doc.contents.items.unshift(doc.createPair('schema_version', 1));
+  changes.push('added schema_version: 1');
+
+  // tdd: true if absent
+  if (!Object.hasOwn(config, 'tdd')) {
+    doc.set('tdd', true);
+    changes.push('added tdd: true');
+  }
+
+  // specs_dir if absent
+  if (!Object.hasOwn(config, 'specs_dir')) {
+    doc.set('specs_dir', '.changeledger/specs');
+    changes.push('added specs_dir: .changeledger/specs');
+  }
+
+  // Canonical statuses — insert missing ones in canonical order
+  const statusesNode = doc.get('statuses', true);
+  if (statusesNode) {
+    const current_statuses = statusesNode.items.map((n) => String(n.value));
+    for (const status of CANONICAL_STATUSES) {
+      if (current_statuses.includes(status)) continue;
+      const insertBefore = findInsertBefore(current_statuses, CANONICAL_STATUSES, status);
+      const newNode = doc.createNode(status);
+      if (insertBefore === -1) {
+        statusesNode.items.push(newNode);
+        current_statuses.push(status);
+      } else {
+        statusesNode.items.splice(insertBefore, 0, newNode);
+        current_statuses.splice(insertBefore, 0, status);
+      }
+      changes.push(`added status: ${status}`);
+    }
+  }
+
+  // review_required: true for built-in types where key is absent
+  const configTypes = config.types ?? {};
+  for (const typeName of BUILTIN_TYPES) {
+    if (!Object.hasOwn(configTypes, typeName)) continue;
+    if (Object.hasOwn(configTypes[typeName], 'review_required')) continue;
+    doc.setIn(['types', typeName, 'review_required'], true);
+    changes.push(`added types.${typeName}.review_required: true`);
+  }
+
+  // release.impacts defaults for built-in types that exist in config.types
+  const currentImpacts = config.release?.impacts ?? {};
+  for (const [type, impact] of Object.entries(BUILTIN_IMPACTS)) {
+    if (!Object.hasOwn(configTypes, type)) continue;
+    if (Object.hasOwn(currentImpacts, type)) continue;
+    doc.setIn(['release', 'impacts', type], impact);
+    changes.push(`added release.impacts.${type}: ${impact}`);
+  }
+
+  // Remove legacy id_digits
+  if (Object.hasOwn(config, 'id_digits')) {
+    doc.delete('id_digits');
+    changes.push('removed legacy id_digits');
+  }
+
+  // Refresh managed comments from the current template, preserving custom comments.
+  const templateComments = loadTemplateComments();
+  const commentChanges = refreshManagedComments(doc, templateComments);
+  changes.push(...commentChanges);
+
+  return { yaml: doc.toString(), changes };
+}
+
+// Apply migration to a file (or dry-run). Returns summary string.
+export function applyMigration(configFile, { dryRun = false } = {}) {
+  let original;
+  try {
+    original = fs.readFileSync(configFile, 'utf8');
+  } catch (e) {
+    throw new Error(`Cannot read config: ${e.message}`);
+  }
+
+  const result = buildMigration(original);
+
+  if (!result) {
+    return `Config is already at schema ${SUPPORTED_SCHEMA_VERSION}. No changes needed.`;
+  }
+
+  const header = dryRun
+    ? `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION} (dry run)`
+    : `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION}`;
+
+  const summary = [header, ...result.changes.map((c) => `  - ${c}`)].join('\n');
+
+  if (!dryRun) {
+    writeFileAtomic(configFile, result.yaml);
+    return summary;
+  }
+
+  return `${summary}\n\n--- candidate YAML ---\n${result.yaml}`;
+}
+
+// Find the index in currentList where `status` should be inserted, based on
+// canonical order. Returns -1 to append at end.
+function findInsertBefore(currentList, canonicalOrder, status) {
+  const canonIdx = canonicalOrder.indexOf(status);
+  for (let i = canonIdx + 1; i < canonicalOrder.length; i++) {
+    const pos = currentList.indexOf(canonicalOrder[i]);
+    if (pos !== -1) return pos;
+  }
+  return -1;
+}
+
+// Reads the current template and returns a map of top-level key → commentBefore string.
+// Returns an empty map if the template is unreadable (comment refresh is optional).
+function loadTemplateComments() {
+  try {
+    const templateText = fs.readFileSync(path.join(templatesDir, 'config.yml'), 'utf8');
+    const templateDoc = parseDocument(templateText, { merge: false });
+    const comments = new Map();
+    for (const pair of templateDoc.contents.items) {
+      const key = pair.key?.value;
+      const comment = pair.key?.commentBefore;
+      if (key && comment !== undefined) {
+        comments.set(key, comment);
+      }
+    }
+    return comments;
+  } catch {
+    return new Map();
+  }
+}
+
+// Replace managed comments (those defined in the template) on existing keys,
+// preserving comments on custom/unknown keys.
+// doc.set() creates keys as plain strings (not Scalar nodes), so commentBefore
+// cannot be set on them directly. Convert string keys to Scalar nodes first.
+function refreshManagedComments(doc, templateComments) {
+  const changes = [];
+  for (const pair of doc.contents.items) {
+    // Normalise string-primitive keys to Scalar nodes so commentBefore is writable.
+    if (typeof pair.key === 'string') {
+      pair.key = doc.createNode(pair.key);
+    }
+    const key = pair.key?.value;
+    if (!key) continue;
+    if (!templateComments.has(key)) continue; // custom key — preserve its comment
+    const templateComment = templateComments.get(key);
+    const currentComment = pair.key?.commentBefore;
+    if (currentComment === templateComment) continue; // already matches
+    pair.key.commentBefore = templateComment;
+    changes.push(`refreshed comment for ${key}`);
+  }
+  return changes;
+}