changeledger 0.5.0 → 0.6.0

package/README.md

@@ -139,8 +139,21 @@ 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 and migrate
-legacy repositories.
+`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
 

package/bin/changeledger.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import {
   archive,
@@ -20,8 +21,12 @@ 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)
@@ -45,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`;
@@ -65,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}`);
 
@@ -326,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');
@@ -376,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.5.0",
+  "version": "0.6.0",
   "description": "Turn conversations into buildable changes.",
   "type": "module",
   "bin": {

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,6 +23,15 @@ export function check(args = [], cwd = process.cwd(), output = console) {
 
   const { errors, warnings } = checkRepo(repo, { id });
 
+  // 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) {

package/src/commands/register.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { findChangeledgerDir, loadConfig } from '../config.mjs';
+import { getSchemaVersion, SUPPORTED_SCHEMA_VERSION } from '../config-migration.mjs';
 import {
   ensureReference,
   removeLegacyContract,
@@ -11,7 +12,7 @@ import { register } from '../registry.mjs';
 
 // Refreshes the repo bootstrap and registry path. Also migrates the per-machine
 // contract artifact left by legacy versions.
-export function registerRepo(cwd = process.cwd()) {
+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.');
 
@@ -20,6 +21,13 @@ 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);
 

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;
+}

package/src/viewer/domain.mjs

@@ -1,10 +1,16 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { parseDocument } from 'yaml';
 import { mutateFileAtomic } from '../atomic-write.mjs';
 import { checkRepo } from '../check.mjs';
 import { status as applyStatusCmd, validation as applyValidation } from '../commands/agent.mjs';
 import { findChangeledgerDir, loadConfig, resolveRepoPath, resolveSpecsDir } from '../config.mjs';
+import {
+  buildMigration,
+  getSchemaVersion,
+  SUPPORTED_SCHEMA_VERSION,
+} from '../config-migration.mjs';
 import { computeMetrics } from '../metrics.mjs';
 import { nowUtc } from '../paths.mjs';
 import { listProjects, remove, update } from '../registry.mjs';
@@ -209,12 +215,21 @@ export function saveProjectConfig(projects, payload, { mutateConfig = mutateFile
       if (revision(before) !== payload.revision) {
         throw new Error('configuration changed on disk; reload before saving');
       }
+      const currentSchema = getSchemaVersion(parseYaml(before));
+      if (currentSchema > SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(
+          `config schema ${currentSchema} is newer than supported schema ${SUPPORTED_SCHEMA_VERSION}`,
+        );
+      }
       return payload.content;
     });
   } catch (error) {
     if (error.message === 'configuration changed on disk; reload before saving') {
       return { code: 409, body: { error: error.message } };
     }
+    if (/^config schema \d+ is newer than supported schema \d+$/.test(error.message)) {
+      return { code: 400, body: { error: error.message } };
+    }
     return { code: 400, body: { error: 'unable to save project configuration' } };
   }
   return {
@@ -264,3 +279,268 @@ export function unregisterProject(projects, payload, { localOnly = false } = {})
   }
   return { code: 200, body: { ok: true } };
 }
+
+// Returns config content + schema metadata without mutating anything.
+export function readProjectConfigStructured(projects, id) {
+  const found = projectFor(projects, id);
+  if (!found.project) return found;
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+  const content = fs.readFileSync(file, 'utf8');
+  const config = parseYaml(content);
+  const schemaVersion = getSchemaVersion(config);
+  return {
+    code: 200,
+    body: {
+      content,
+      revision: revision(content),
+      schemaVersion,
+      supported: SUPPORTED_SCHEMA_VERSION,
+      config,
+    },
+  };
+}
+
+// Applies a semantic patch (allowlisted fields only) to the YAML AST, preserving
+// comments, unknown keys and fields the form does not represent.
+export function patchProjectConfig(projects, payload, { mutateConfig = mutateFileAtomic } = {}) {
+  const found = projectFor(projects, payload.project);
+  if (!found.project) return found;
+  if (!payload.patch || typeof payload.patch !== 'object' || Array.isArray(payload.patch)) {
+    return { code: 400, body: { error: 'patch must be an object' } };
+  }
+  if (typeof payload.revision !== 'string') {
+    return { code: 400, body: { error: 'revision is required' } };
+  }
+  // Explicitly reject attempts to change identity fields via patch.
+  if ('project_id' in payload.patch) {
+    return { code: 400, body: { error: 'project_id cannot be changed from the viewer' } };
+  }
+  if ('schema_version' in payload.patch) {
+    return { code: 400, body: { error: 'schema_version cannot be changed via patch' } };
+  }
+
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+
+  let result;
+  try {
+    mutateConfig(file, (before) => {
+      if (revision(before) !== payload.revision) {
+        throw new Error('configuration changed on disk; reload before saving');
+      }
+
+      const doc = parseDocument(before, { merge: false });
+      const config = doc.toJS() ?? {};
+
+      // Fail closed for future schema
+      const schemaVersion = getSchemaVersion(config);
+      if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(
+          `config schema ${schemaVersion} is newer than supported schema ${SUPPORTED_SCHEMA_VERSION}`,
+        );
+      }
+
+      applyPatch(doc, payload.patch, config);
+
+      const patched = doc.toString();
+      const candidate = parseYaml(patched);
+
+      // Identity guard
+      if (String(candidate.project_id ?? '') !== String(found.project.id)) {
+        throw new Error('project_id cannot be changed from the viewer');
+      }
+
+      // Structural validation
+      const repo = loadRepo(found.project.path);
+      resolveRepoPath(repo.repoRoot, candidate.changes_dir, 'changes_dir');
+      resolveSpecsDir(repo.repoRoot, candidate);
+      const candidateRepo = loadRepoWithConfig(repo.repoRoot, repo.changeledgerDir, candidate);
+      const { errors } = checkRepo(candidateRepo);
+      if (errors.length) throw new Error(errors[0].message);
+
+      result = { content: patched, rev: revision(patched) };
+      return patched;
+    });
+  } catch (error) {
+    if (error.message === 'configuration changed on disk; reload before saving') {
+      return { code: 409, body: { error: error.message } };
+    }
+    return { code: 400, body: { error: error.message } };
+  }
+
+  return { code: 200, body: { ok: true, revision: result.rev } };
+}
+
+// Preview the migration without writing. Returns summary + candidate YAML.
+export function previewConfigMigration(projects, id, rev) {
+  const found = projectFor(projects, id);
+  if (!found.project) return found;
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+  const content = fs.readFileSync(file, 'utf8');
+  if (rev && revision(content) !== rev) {
+    return { code: 409, body: { error: 'configuration changed on disk; reload before saving' } };
+  }
+  let migrationResult;
+  try {
+    migrationResult = buildMigration(content);
+  } catch (e) {
+    return { code: 400, body: { error: e.message } };
+  }
+  if (!migrationResult) {
+    return {
+      code: 200,
+      body: {
+        already_current: true,
+        message: `Config is already at schema ${SUPPORTED_SCHEMA_VERSION}`,
+      },
+    };
+  }
+  return {
+    code: 200,
+    body: {
+      summary: `Config migration 0 → ${SUPPORTED_SCHEMA_VERSION} (dry run)`,
+      changes: migrationResult.changes,
+      yaml: migrationResult.yaml,
+    },
+  };
+}
+
+// Apply the migration atomically. Uses the same engine as `changeledger config migrate`.
+// Revision check and write are inside mutateFileAtomic to avoid TOCTOU races.
+export function applyConfigMigration(projects, payload, { mutateConfig = mutateFileAtomic } = {}) {
+  const found = projectFor(projects, payload.project);
+  if (!found.project) return found;
+  if (typeof payload.revision !== 'string') {
+    return { code: 400, body: { error: 'revision is required' } };
+  }
+  const file = path.join(found.project.path, '.changeledger', 'config.yml');
+
+  let result;
+  try {
+    mutateConfig(file, (before) => {
+      if (revision(before) !== payload.revision) {
+        throw new Error('configuration changed on disk; reload before saving');
+      }
+      let migrationResult;
+      try {
+        migrationResult = buildMigration(before);
+      } catch (e) {
+        throw new Error(e.message);
+      }
+      if (!migrationResult) {
+        result = { already_current: true, rev: payload.revision };
+        return undefined; // no write needed
+      }
+      result = { ok: true, rev: revision(migrationResult.yaml) };
+      return migrationResult.yaml;
+    });
+  } catch (error) {
+    if (error.message === 'configuration changed on disk; reload before saving') {
+      return { code: 409, body: { error: error.message } };
+    }
+    return { code: 400, body: { error: error.message } };
+  }
+
+  if (result.already_current) {
+    return { code: 200, body: { already_current: true, revision: result.rev } };
+  }
+  return { code: 200, body: { ok: true, revision: result.rev } };
+}
+
+// Allowlisted fields the form patch may update.
+const PATCH_ALLOWED = new Set([
+  'project_name',
+  'language',
+  'tdd',
+  'changes_dir',
+  'specs_dir',
+  'statuses',
+  'stages',
+  'readiness',
+  'types',
+  'release',
+]);
+
+const CANONICAL_STATUSES_REQUIRED = new Set([
+  'draft',
+  'approved',
+  'in-progress',
+  'in-review',
+  'in-validation',
+  'blocked',
+  'done',
+  'discarded',
+]);
+
+const CANONICAL_STAGES_REQUIRED = new Set([
+  'request',
+  'investigation',
+  'proposal',
+  'specification',
+  'plan',
+  'log',
+]);
+
+function applyPatch(doc, patch, currentConfig) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (!PATCH_ALLOWED.has(key)) continue;
+
+    if (key === 'types') {
+      applyTypesPatch(doc, value, currentConfig.types ?? {});
+    } else if (key === 'release') {
+      applyReleasePatch(doc, value);
+    } else if (key === 'readiness') {
+      applyReadinessPatch(doc, value);
+    } else if (key === 'statuses') {
+      applyRequiredListPatch(doc, 'statuses', value, CANONICAL_STATUSES_REQUIRED);
+    } else if (key === 'stages') {
+      applyRequiredListPatch(doc, 'stages', value, CANONICAL_STAGES_REQUIRED);
+    } else {
+      doc.set(key, value);
+    }
+  }
+}
+
+function applyRequiredListPatch(doc, key, proposed, required) {
+  if (!Array.isArray(proposed) || proposed.some((value) => typeof value !== 'string')) {
+    throw new Error(`${key} must be a list of strings`);
+  }
+  const duplicate = proposed.find((value, index) => proposed.indexOf(value) !== index);
+  if (duplicate) throw new Error(`${key} contains duplicate value "${duplicate}"`);
+  const missing = [...required].find((value) => !proposed.includes(value));
+  if (missing) throw new Error(`${key} cannot remove required value "${missing}"`);
+  doc.set(key, proposed);
+}
+
+function applyTypesPatch(doc, typesPatch, currentTypes) {
+  for (const [typeName, typeDef] of Object.entries(typesPatch)) {
+    if (!Object.hasOwn(currentTypes, typeName)) continue; // don't add new types
+    if (!typeDef || typeof typeDef !== 'object') continue;
+    if (Array.isArray(typeDef.stages)) {
+      doc.setIn(['types', typeName, 'stages'], typeDef.stages);
+    }
+    if (typeof typeDef.review_required === 'boolean') {
+      doc.setIn(['types', typeName, 'review_required'], typeDef.review_required);
+    } else if (typeDef.review_required === null) {
+      doc.deleteIn(['types', typeName, 'review_required']);
+    }
+  }
+}
+
+function applyReleasePatch(doc, releasePatch) {
+  if (releasePatch.impacts && typeof releasePatch.impacts === 'object') {
+    for (const [type, impact] of Object.entries(releasePatch.impacts)) {
+      if (impact === null) doc.deleteIn(['release', 'impacts', type]);
+      else doc.setIn(['release', 'impacts', type], impact);
+    }
+  }
+}
+
+function applyReadinessPatch(doc, readinessPatch) {
+  if (!readinessPatch || typeof readinessPatch !== 'object') return;
+  if (Array.isArray(readinessPatch.target_patterns)) {
+    doc.setIn(['readiness', 'target_patterns'], readinessPatch.target_patterns);
+  }
+  if (Array.isArray(readinessPatch.verification_patterns)) {
+    doc.setIn(['readiness', 'verification_patterns'], readinessPatch.verification_patterns);
+  }
+}