agentic-workflow-manager 9.18.0 → 9.20.0

package/dist/tests/commands/change/new.test.js

@@ -0,0 +1,1126 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const commander_1 = require("commander");
+const child_process_1 = __importDefault(require("child_process"));
+const helpers_1 = require("../../core/changes/helpers");
+const change_1 = require("../../../src/commands/change");
+const store_1 = require("../../../src/core/journal/store");
+const ledgerStore = __importStar(require("../../../src/core/ledger/store"));
+const receipt_1 = require("../../../src/core/changes/receipt");
+const parse_1 = require("../../../src/core/changes/parse");
+const renderModule = __importStar(require("../../../src/core/changes/render"));
+const validate_shape_1 = require("../../../src/core/changes/validate-shape");
+const types_1 = require("../../../src/core/changes/types");
+const REAL_CHANGES_DIR = path_1.default.resolve(__dirname, '..', '..', '..', '..', 'docs', 'changes');
+const listReal = () => { try {
+    return fs_1.default.readdirSync(REAL_CHANGES_DIR).sort();
+}
+catch {
+    return null;
+} };
+const realBefore = listReal();
+let repo;
+const now = () => new Date('2026-10-17T12:00:00.000Z');
+const pass = { overall: 'pass', sensors: [{ name: 'lint', status: 'pass', errors: [] }] };
+const RECEIPT_TIME = '2026-10-17T11:00:00.000Z';
+const REMEDY = 'commit your work, then run awm sensors run';
+const REMEDY_SPLIT = 'split the change into smaller ones';
+const REMEDY_SENSORS = 'reduce the sensors listed in .awm/sensors.json (the sensor receipt makes the record too large)';
+function receiptForHead() {
+    (0, receipt_1.writeReceipt)(repo.root, (0, receipt_1.buildReceipt)({ commit: repo.git('rev-parse', 'HEAD'), ranAt: RECEIPT_TIME, cliVersion: '9.20.0', output: pass }));
+}
+// One template repository for the whole file (it also holds HOME and AWM_HOME on a throwaway home); every test gets a copy.
+let template;
+beforeAll(() => {
+    template = (0, helpers_1.makeRepo)();
+    template.git('checkout', '-q', '-b', 'feat/x');
+    template.commit({ 'cli/src/a.ts': '1' }, 'feat(changes): a');
+});
+afterAll(() => template.cleanup());
+function newRepo() {
+    repo = (0, helpers_1.cloneRepo)(template);
+}
+/** A fresh repository for every test: for tests that write a record, move HEAD or change the tree. */
+function freshRepo() {
+    beforeEach(newRepo);
+    afterEach(() => { jest.restoreAllMocks(); repo.cleanup(); });
+}
+/**
+ * One repository (with a receipt for HEAD) for a whole group. Only for tests that are refused before anything is written
+ * (they never change HEAD, the tree that matters, or docs/changes): they would otherwise pay for a repository each.
+ */
+function sharedRepo() {
+    beforeAll(() => { newRepo(); receiptForHead(); });
+    afterAll(() => repo.cleanup());
+}
+// The command writes only into the throwaway repository: the real checkout is never touched.
+afterEach(() => expect(listReal()).toEqual(realBefore));
+afterAll(() => expect(listReal()).toEqual(realBefore));
+/** Replaces one fs function for the calls `match` selects (by their arguments); every other call reaches the real one. */
+function interceptFs(name, match, replace) {
+    const real = fs_1.default[name];
+    return jest.spyOn(fs_1.default, name).mockImplementation(((...args) => (match(args) ? replace(real, args) : real(...args))));
+}
+const baseIs = (arg, name) => typeof arg === 'string' && path_1.default.basename(arg) === name;
+const isRecordsDirArg = (arg) => baseIs(arg, 'changes') && baseIs(path_1.default.dirname(String(arg)), 'docs');
+const recordsDir = () => path_1.default.join(repo.root, 'docs', 'changes');
+const file = () => path_1.default.join(recordsDir(), '2026-10-17-change-record.md');
+const run = (slug, opts = {}, deps = { now }) => (0, change_1.runChangeNew)(repo.root, slug, opts, deps);
+const read = () => fs_1.default.readFileSync(file(), 'utf8');
+const frontmatter = (text) => {
+    const split = (0, parse_1.splitRecord)(text);
+    if (!split.ok)
+        throw new Error('not a record');
+    const loaded = (0, parse_1.loadFrontmatter)(split.frontmatterText);
+    if (!loaded.ok)
+        throw new Error('bad yaml');
+    return loaded.value;
+};
+/** The failure contract: exit 2, nothing on stdout, `code: <one line of at most 300 units>` (+ an optional remedy line). */
+function expectFailure(r, code, remedy) {
+    expect(r.code).toBe(2);
+    expect(r.stdout).toBe('');
+    const lines = r.stderr.split('\n');
+    expect(lines[lines.length - 1]).toBe('');
+    expect(lines[0].startsWith(`${code}: `)).toBe(true);
+    expect(lines[0].length).toBeLessThanOrEqual(300);
+    expect(r.stderr).not.toMatch(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u2028\u2029]/);
+    if (remedy !== undefined)
+        expect(lines[1]).toBe(`  remedy: ${remedy}`);
+    expect(lines.length).toBe(remedy === undefined ? 2 : 3);
+}
+const recordFiles = () => { try {
+    return fs_1.default.readdirSync(recordsDir()).sort();
+}
+catch {
+    return [];
+} };
+describe('test isolation', () => {
+    freshRepo();
+    test('HOME and AWM_HOME point into the throwaway home', () => {
+        expect(process.env.HOME).toBe(repo.home);
+        expect(process.env.AWM_HOME).toBe(path_1.default.join(repo.home, '.awm'));
+        expect(fs_1.default.realpathSync.native(repo.root).startsWith(fs_1.default.realpathSync.native(os_1.default.tmpdir()))).toBe(true);
+    });
+});
+describe('awm change new: receipt and clean tree (R3.6)', () => {
+    freshRepo();
+    test('a missing receipt fails with receipt-missing and the remedy, writing nothing', () => {
+        expectFailure(run('change-record'), 'receipt-missing', REMEDY);
+        expect(recordFiles()).toEqual([]);
+    });
+    test('an untracked file outside docs/changes fails with tree-dirty and the remedy', () => {
+        receiptForHead();
+        fs_1.default.writeFileSync(path_1.default.join(repo.root, 'dirty.ts'), 'x');
+        expectFailure(run('change-record'), 'tree-dirty', REMEDY);
+        expect(recordFiles()).toEqual([]);
+    });
+    test('a modified tracked file fails with tree-dirty', () => {
+        receiptForHead();
+        fs_1.default.writeFileSync(path_1.default.join(repo.root, 'cli', 'src', 'a.ts'), '2');
+        expectFailure(run('change-record'), 'tree-dirty', REMEDY);
+    });
+    test('another uncommitted record in docs/changes does not make the tree dirty', () => {
+        receiptForHead();
+        fs_1.default.mkdirSync(recordsDir(), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(recordsDir(), '2026-10-01-other.md'), 'draft');
+        expect(run('change-record').code).toBe(0);
+    });
+    test('a receipt for another commit is receipt-missing', () => {
+        receiptForHead();
+        repo.commit({ 'cli/src/b.ts': '1' }, 'fix(changes): b');
+        expectFailure(run('change-record'), 'receipt-missing', REMEDY);
+    });
+    test('a tampered receipt is receipt-invalid', () => {
+        receiptForHead();
+        const receiptFile = path_1.default.join(repo.root, '.awm', 'sensors', 'runs', `${repo.git('rev-parse', 'HEAD')}.json`);
+        fs_1.default.writeFileSync(receiptFile, fs_1.default.readFileSync(receiptFile, 'utf8').replace('"pass"', '"fail"'));
+        expectFailure(run('change-record'), 'receipt-invalid', REMEDY);
+        expect(recordFiles()).toEqual([]);
+    });
+});
+describe('awm change new: skeleton (R3.7, R3.9)', () => {
+    freshRepo();
+    test('prints the created path and writes exactly that file', () => {
+        receiptForHead();
+        const r = run('change-record');
+        expect(r).toEqual({ code: 0, stdout: 'Created docs/changes/2026-10-17-change-record.md\n', stderr: '' });
+        expect(recordFiles()).toEqual(['2026-10-17-change-record.md']);
+    });
+    test('derives type, scope, semver, breaking and modules from the branch commits', () => {
+        receiptForHead();
+        run('change-record');
+        const fm = frontmatter(read());
+        expect(fm).toMatchObject({ schema: 'awm.change-record/v1', id: '2026-10-17-change-record', type: 'feat', scope: 'changes', semver: 'minor', breaking: false, modules: ['cli/src'] });
+    });
+    test('copies commit, overall, sensors and the digest of the receipt into verification', () => {
+        receiptForHead();
+        run('change-record');
+        const expected = {
+            commit: repo.git('rev-parse', 'HEAD'),
+            overall: 'pass',
+            sensors: { lint: 'pass' },
+            receipt_digest: expect.stringMatching(/^sha256:[0-9a-f]{64}$/),
+        };
+        expect(frontmatter(read()).verification).toEqual(expected);
+    });
+    test('the digest is the receipt digest, not a recomputation of the record', () => {
+        receiptForHead();
+        const receiptFile = path_1.default.join(repo.root, '.awm', 'sensors', 'runs', `${repo.git('rev-parse', 'HEAD')}.json`);
+        const digest = JSON.parse(fs_1.default.readFileSync(receiptFile, 'utf8')).digest;
+        run('change-record');
+        expect(frontmatter(read()).verification.receipt_digest).toBe(digest);
+    });
+    test('every narrative field and every body section carries the pending marker', () => {
+        receiptForHead();
+        run('change-record');
+        const text = read();
+        const fm = frontmatter(text);
+        expect(fm.title).toBe(types_1.PENDING_MARKER);
+        expect(fm.summary_short).toBe(types_1.PENDING_MARKER);
+        expect(fm.manual_validation).toEqual([{ step: types_1.PENDING_MARKER, expected: types_1.PENDING_MARKER }]);
+        expect(fm.risks).toEqual([types_1.PENDING_MARKER]);
+        expect(fm.rollback).toBe(types_1.PENDING_MARKER);
+        for (const heading of ['## Qué se hizo', '## Qué se probó', '## Qué falta validar', '## Riesgos y rollback']) {
+            expect(text).toContain(`${heading}\n\n${types_1.PENDING_MARKER}\n`);
+        }
+    });
+    test('the skeleton fails validation only because of its pending markers', () => {
+        receiptForHead();
+        run('change-record');
+        const { diagnostics } = (0, validate_shape_1.validateRecordShape)('2026-10-17-change-record.md', read(), { root: repo.root });
+        expect(diagnostics.map((d) => d.code)).toEqual(['pending-content']);
+    });
+    test('once the markers are replaced the record passes validateRecordShape', () => {
+        repo.commit({ 'docs/plans/p.md': 'plan' }, 'docs: plan');
+        receiptForHead();
+        run('change-record', { plan: 'docs/plans/p.md', issue: 'https://github.com/o/r/issues/217', model: 'm1', session: 's1' });
+        const filled = read().split(types_1.PENDING_MARKER).join('written by the agent');
+        const r = (0, validate_shape_1.validateRecordShape)('2026-10-17-change-record.md', filled, { root: repo.root });
+        expect(r.diagnostics).toEqual([]);
+        expect(r.record?.verification.commit).toBe(repo.git('rev-parse', 'HEAD'));
+    });
+    test('links carry --plan and --issue exactly as given', () => {
+        repo.commit({ 'docs/plans/p.md': 'plan' }, 'docs: plan');
+        receiptForHead();
+        run('change-record', { plan: 'docs/plans/p.md', issue: 'https://github.com/o/r/issues/217' });
+        expect(frontmatter(read()).links).toEqual({ plan: 'docs/plans/p.md', issue: 'https://github.com/o/r/issues/217' });
+    });
+    test('without --plan and --issue there is no links key', () => {
+        receiptForHead();
+        run('change-record');
+        expect(frontmatter(read())).not.toHaveProperty('links');
+    });
+    test('the record ends with a newline and uses LF only', () => {
+        receiptForHead();
+        run('change-record');
+        const text = read();
+        expect(text.endsWith('\n')).toBe(true);
+        expect(text).not.toContain('\r');
+    });
+    test('a record is written outside the cwd-relative path: running from a subdirectory writes at the repo root', () => {
+        receiptForHead();
+        const sub = path_1.default.join(repo.root, 'cli', 'src');
+        expect((0, change_1.runChangeNew)(sub, 'change-record', {}, { now }).code).toBe(0);
+        expect(recordFiles()).toEqual(['2026-10-17-change-record.md']);
+        expect(fs_1.default.existsSync(path_1.default.join(sub, 'docs'))).toBe(false);
+    });
+    test('the date comes from the injected clock, in UTC', () => {
+        receiptForHead();
+        run('change-record', {}, { now: () => new Date('2027-01-02T23:59:59.000Z') });
+        expect(recordFiles()).toEqual(['2027-01-02-change-record.md']);
+    });
+    test.each([
+        ['an invalid date', () => new Date(NaN)],
+        ['a year beyond 9999', () => new Date('+010000-01-01T00:00:00.000Z')],
+        ['a clock that throws', () => { throw new Error('boom'); }],
+        ['a clock that returns a string', (() => 'x')],
+    ])('an unusable clock (%s) fails with date-invalid and writes nothing', (_name, bad) => {
+        receiptForHead();
+        expectFailure(run('change-record', {}, { now: bad }), 'date-invalid');
+        expect(recordFiles()).toEqual([]);
+    });
+});
+describe('awm change new: generated record is checked before it is written (R3.4 size bound)', () => {
+    freshRepo();
+    test('R3.4 a receipt that makes the record exceed 64 KiB fails with record-too-large and a remedy naming the sensors, and writes nothing', () => {
+        const sensors = Array.from({ length: 700 }, (_, i) => ({ name: `sensor-${String(i).padStart(4, '0')}-${'x'.repeat(100)}`, status: 'pass', errors: [] }));
+        (0, receipt_1.writeReceipt)(repo.root, (0, receipt_1.buildReceipt)({ commit: repo.git('rev-parse', 'HEAD'), ranAt: RECEIPT_TIME, cliVersion: '9.20.0', output: { overall: 'pass', sensors } }));
+        const r = run('change-record');
+        // The receipt, not the directories, is the cause: the remedy says so (R3.4).
+        expectFailure(r, 'record-too-large', REMEDY_SENSORS);
+        expect(recordFiles()).toEqual([]);
+    });
+    test('R3.4 a change touching thousands of directories fails with record-too-large (not a cryptic skeleton-invalid) and writes nothing', () => {
+        // One fast-import commit adds a file in each of 4000 vendor directories: `modules` alone is far over 64 KiB.
+        const files = Object.fromEntries(Array.from({ length: 4000 }, (_, i) => [`vendor/package-${String(i).padStart(5, '0')}/index.js`, '1']));
+        (0, helpers_1.importCommits)(repo, [{ message: 'feat(vendor): import vendored packages', files, date: '2026-10-17T10:00:00Z' }]);
+        receiptForHead();
+        const r = run('change-record');
+        expectFailure(r, 'record-too-large', REMEDY_SPLIT);
+        expect(r.stderr).not.toContain('skeleton-invalid');
+        expect(recordFiles()).toEqual([]);
+    });
+});
+describe('awm change new: the 65536-byte boundary of the record (R3.4, R1.8)', () => {
+    freshRepo();
+    // The record grows by exactly one byte per character of a sensor name (ASCII), while the number of sensors is fixed. Filler
+    // sensors of 100 characters move the size in steps of about 111 bytes, less than the 127 bytes one variable name can add, so
+    // some filler count has the limit inside the variable name's range.
+    const sensorList = (fillers, variable) => [
+        ...Array.from({ length: fillers }, (_, i) => ({ name: `f${String(i).padStart(4, '0')}${'x'.repeat(95)}`, status: 'pass', errors: [] })),
+        { name: `v${'x'.repeat(variable - 1)}`, status: 'pass', errors: [] },
+    ];
+    const setReceipt = (fillers, variable) => {
+        (0, receipt_1.writeReceipt)(repo.root, (0, receipt_1.buildReceipt)({ commit: repo.git('rev-parse', 'HEAD'), ranAt: RECEIPT_TIME, cliVersion: '9.20.0', output: { overall: 'pass', sensors: sensorList(fillers, variable) } }));
+    };
+    /** Largest n in [lo, hi] for which `fits(n)` holds, `fits` being true up to a point and false after it. */
+    const largest = (lo, hi, fits) => {
+        let a = lo;
+        let b = hi;
+        while (a < b) {
+            const mid = Math.ceil((a + b) / 2);
+            if (fits(mid))
+                a = mid;
+            else
+                b = mid - 1;
+        }
+        return a;
+    };
+    /** Runs `attempt` for a receipt of (fillers, variable); `bytes` is the size of the file it wrote, null when it failed as too large. */
+    function findBoundary(attempt) {
+        const fits = (fillers, variable) => { setReceipt(fillers, variable); return attempt().bytes; };
+        const fillers = largest(0, 700, (k) => fits(k, 1) !== null);
+        const variable = largest(1, 128, (l) => fits(fillers, l) !== null);
+        return { fillers, variable, atLimit: fits(fillers, variable), oneMore: variable < 128 ? fits(fillers, variable + 1) : -1 };
+    }
+    test('change new: a record of exactly 65536 bytes is written, one of 65537 is record-too-large', () => {
+        const attempt = () => {
+            const r = run('change-record');
+            if (r.code === 0) {
+                const bytes = fs_1.default.statSync(file()).size;
+                fs_1.default.rmSync(file());
+                return { bytes };
+            }
+            expect(r.stderr).toContain('record-too-large');
+            return { bytes: null };
+        };
+        const found = findBoundary(attempt);
+        expect(found.variable).toBeLessThan(128);
+        expect(found.atLimit).toBe(65536);
+        expect(found.oneMore).toBeNull();
+    });
+    test('change new --refresh: a refreshed record of exactly 65536 bytes is written, one of 65537 is record-too-large', () => {
+        setReceipt(0, 1);
+        expect(run('change-record').code).toBe(0);
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): record');
+        const original = read();
+        const attempt = () => {
+            const r = run('change-record', { refresh: true });
+            if (r.code === 0) {
+                const bytes = fs_1.default.statSync(file()).size;
+                fs_1.default.writeFileSync(file(), original);
+                return { bytes };
+            }
+            expect(r.stderr).toContain('record-too-large');
+            expect(read()).toBe(original);
+            return { bytes: null };
+        };
+        const found = findBoundary(attempt);
+        expect(found.variable).toBeLessThan(128);
+        expect(found.atLimit).toBe(65536);
+        expect(found.oneMore).toBeNull();
+    });
+    test('the remedy names the cause: a receipt that is too large asks to reduce the sensors, in new and in refresh alike', () => {
+        setReceipt(0, 1);
+        run('change-record');
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): record');
+        setReceipt(700, 100);
+        expectFailure(run('change-record', { refresh: true }), 'record-too-large', REMEDY_SENSORS);
+    });
+});
+describe('awm change new: HEAD moving while the command runs', () => {
+    freshRepo();
+    test('a HEAD that moves before the record is written is head-moved and nothing is written', () => {
+        receiptForHead();
+        const moving = () => { repo.commit({ 'cli/src/late.ts': '1' }, 'fix(core): late'); return now(); };
+        expectFailure(run('change-record', {}, { now: moving }), 'head-moved');
+        expect(recordFiles()).toEqual([]);
+    });
+    test('a HEAD that moves before a refresh is written is head-moved and the record is untouched', () => {
+        receiptForHead();
+        run('change-record');
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): record');
+        receiptForHead();
+        const before = read();
+        const spy = interceptFs('readFileSync', (a) => baseIs(a[0], path_1.default.basename(file())), (real, a) => {
+            const out = real(...a);
+            spy.mockRestore();
+            repo.commit({ 'cli/src/late.ts': '1' }, 'fix(core): late');
+            return out;
+        });
+        expectFailure(run('change-record', { refresh: true }), 'head-moved');
+        expect(read()).toBe(before);
+    });
+});
+describe('awm change new: HEAD is pinned before the derivation', () => {
+    freshRepo();
+    /** Runs `act` once, right before (or after) the first git call whose first argument is `sub`. */
+    function onGit(sub, when, act) {
+        const real = child_process_1.default.execFileSync;
+        let fired = false;
+        return jest.spyOn(child_process_1.default, 'execFileSync').mockImplementation(((...args) => {
+            const git = Array.isArray(args[1]) ? args[1] : [];
+            const hit = !fired && args[0] === 'git' && git.includes(sub);
+            if (hit)
+                fired = true;
+            if (hit && when === 'before')
+                act();
+            const out = real(...args);
+            if (hit && when === 'after')
+                act();
+            return out;
+        }));
+    }
+    const land = () => {
+        // A commit lands and leaves an untracked file: with no early check the dirty-tree diagnostic would come first.
+        repo.commit({ 'cli/src/late.ts': '1' }, 'fix(core): late');
+        fs_1.default.writeFileSync(path_1.default.join(repo.root, 'late-untracked.txt'), 'x');
+    };
+    test('a commit landing between the pin and the derivation is head-moved, not a record of mixed commits', () => {
+        receiptForHead();
+        onGit('merge-base', 'after', land);
+        expectFailure(run('change-record'), 'head-moved');
+        expect(recordFiles()).toEqual([]);
+    });
+    test('the message says HEAD moved during derivation', () => {
+        receiptForHead();
+        onGit('merge-base', 'after', land);
+        expect(run('change-record').stderr).toContain('HEAD moved during derivation');
+    });
+    test('a commit landing after the derivation but before the write is head-moved', () => {
+        receiptForHead();
+        onGit('status', 'before', () => repo.commit({ 'cli/src/late.ts': '1' }, 'fix(core): late'));
+        expectFailure(run('change-record'), 'head-moved');
+        expect(recordFiles()).toEqual([]);
+    });
+});
+describe('awm change new: provenance (R3.8)', () => {
+    freshRepo();
+    const writeJournalWith = (patch) => {
+        (0, store_1.initJournal)(repo.root, 'feat/x');
+        const state = readStateOrThrow();
+        patch(state);
+        (0, store_1.writeJournal)(repo.root, 'feat/x', state);
+    };
+    function readStateOrThrow() {
+        const r = (0, store_1.readJournal)(repo.root, 'feat/x');
+        if (!r.state)
+            throw new Error('no journal');
+        return r.state;
+    }
+    test('omits the provenance key entirely when no source exists', () => {
+        receiptForHead();
+        run('change-record');
+        expect(frontmatter(read())).not.toHaveProperty('provenance');
+    });
+    test('model and session come only from flags', () => {
+        receiptForHead();
+        run('change-record', { model: 'm1', session: 'https://claude.ai/code/session_x' });
+        expect(frontmatter(read()).provenance).toEqual({ model: 'm1', session: 'https://claude.ai/code/session_x' });
+    });
+    test('agent and timestamps come from the branch journal', () => {
+        writeJournalWith((s) => { s.admissionContext = { provider: 'claude-code' }; s.cycle.completedAt = '2026-10-17T10:30:00.000Z'; s.cycle.startedAt = '2026-10-17T09:00:00.000Z'; });
+        receiptForHead();
+        run('change-record', { model: 'm1' });
+        expect(frontmatter(read()).provenance).toEqual({ agent: 'claude-code', started_at: '2026-10-17T09:00:00.000Z', finished_at: '2026-10-17T10:30:00.000Z', model: 'm1' });
+    });
+    test('a journal without admissionContext and completedAt yields only started_at', () => {
+        writeJournalWith((s) => { s.cycle.startedAt = '2026-10-17T09:00:00.000Z'; });
+        receiptForHead();
+        run('change-record');
+        expect(frontmatter(read()).provenance).toEqual({ started_at: '2026-10-17T09:00:00.000Z' });
+    });
+    test('a journal timestamp that is not canonical ISO is omitted, never copied', () => {
+        writeJournalWith((s) => { s.cycle.startedAt = 'yesterday'; s.admissionContext = { provider: 'codex' }; });
+        receiptForHead();
+        expect(run('change-record').code).toBe(0);
+        expect(frontmatter(read()).provenance).toEqual({ agent: 'codex' });
+    });
+    test('a corrupt journal is ignored: no journal keys and no error', () => {
+        (0, store_1.initJournal)(repo.root, 'feat/x');
+        const journalFile = path_1.default.join(repo.root, '.awm', 'journal', 'feat_2Fx', 'state.json');
+        fs_1.default.writeFileSync(journalFile, '{ not json');
+        receiptForHead();
+        expect(run('change-record', { model: 'm1' }).code).toBe(0);
+        expect(frontmatter(read()).provenance).toEqual({ model: 'm1' });
+    });
+    test('a journal of another branch is not used', () => {
+        (0, store_1.initJournal)(repo.root, 'other');
+        const other = (0, store_1.readJournal)(repo.root, 'other').state;
+        if (!other)
+            throw new Error('no journal');
+        (0, store_1.writeJournal)(repo.root, 'other', { ...other, admissionContext: { provider: 'codex' } });
+        receiptForHead();
+        run('change-record');
+        expect(frontmatter(read())).not.toHaveProperty('provenance');
+    });
+    test('the branch whose journal is read is named by the ledger helper the journal writers use (one helper, not a copy)', () => {
+        writeJournalWith((s) => { s.admissionContext = { provider: 'claude-code' }; });
+        repo.git('checkout', '-q', '-b', 'somewhere-else');
+        const named = jest.spyOn(ledgerStore, 'detectBranch').mockReturnValue('feat/x');
+        receiptForHead();
+        run('change-record');
+        expect(named).toHaveBeenCalledWith(repo.root);
+        expect(frontmatter(read()).provenance).toMatchObject({ agent: 'claude-code' });
+    });
+    test('a detached HEAD has no journal and is not an error', () => {
+        repo.git('checkout', '-q', '--detach');
+        receiptForHead();
+        expect(run('change-record').code).toBe(0);
+        expect(frontmatter(read())).not.toHaveProperty('provenance');
+    });
+});
+describe('awm change new: no overwrite (R3.10)', () => {
+    freshRepo();
+    test('refuses to overwrite on the same date and leaves the file untouched', () => {
+        receiptForHead();
+        run('change-record');
+        fs_1.default.writeFileSync(file(), 'edited by hand');
+        expectFailure(run('change-record'), 'record-exists', 'use --refresh to update derived fields');
+        expect(read()).toBe('edited by hand');
+    });
+    test('refuses the same slug on another date', () => {
+        receiptForHead();
+        run('change-record');
+        const before = read();
+        expectFailure(run('change-record', {}, { now: () => new Date('2026-10-20T12:00:00.000Z') }), 'record-exists', 'use --refresh to update derived fields');
+        expect(recordFiles()).toEqual(['2026-10-17-change-record.md']);
+        expect(read()).toBe(before);
+    });
+    test('a different slug is not blocked by an existing record', () => {
+        receiptForHead();
+        run('change-record');
+        expect(run('change-record-2').code).toBe(0);
+        expect(recordFiles()).toEqual(['2026-10-17-change-record-2.md', '2026-10-17-change-record.md']);
+    });
+    test('a slug that is only a prefix of an existing slug is not blocked', () => {
+        receiptForHead();
+        run('change-record-long');
+        expect(run('change-record').code).toBe(0);
+    });
+    (0, helpers_1.posixOnly)('a symlink named like the record counts as existing and its target is not written', () => {
+        receiptForHead();
+        fs_1.default.mkdirSync(recordsDir(), { recursive: true });
+        const outside = path_1.default.join(repo.home, 'outside.md');
+        fs_1.default.writeFileSync(outside, 'precious');
+        fs_1.default.symlinkSync(outside, file());
+        expectFailure(run('change-record'), 'record-exists', 'use --refresh to update derived fields');
+        expect(fs_1.default.readFileSync(outside, 'utf8')).toBe('precious');
+    });
+    test('a listing that misses an existing file still never overwrites it (exclusive create)', () => {
+        receiptForHead();
+        run('change-record');
+        fs_1.default.writeFileSync(file(), 'edited by hand');
+        interceptFs('readdirSync', (a) => isRecordsDirArg(a[0]), () => []);
+        expectFailure(run('change-record'), 'record-exists', 'use --refresh to update derived fields');
+        expect(read()).toBe('edited by hand');
+    });
+    test('an unreadable docs/changes listing fails closed instead of creating', () => {
+        receiptForHead();
+        fs_1.default.mkdirSync(recordsDir(), { recursive: true });
+        interceptFs('readdirSync', (a) => isRecordsDirArg(a[0]), () => { throw Object.assign(new Error('denied'), { code: 'EACCES' }); });
+        expectFailure(run('change-record'), 'io-failed');
+        jest.restoreAllMocks();
+        expect(fs_1.default.readdirSync(recordsDir())).toEqual([]);
+    });
+    test('a failed write leaves no partial file behind', () => {
+        receiptForHead();
+        // Only the write through the descriptor of the new record fails (the create itself succeeded).
+        interceptFs('writeFileSync', (a) => typeof a[0] === 'number', () => { throw Object.assign(new Error('full'), { code: 'ENOSPC' }); });
+        expectFailure(run('change-record'), 'io-failed');
+        expect(recordFiles()).toEqual([]);
+    });
+});
+describe('awm change new: slug validation (R3.12)', () => {
+    sharedRepo();
+    const BAD_SLUGS = ['../evil', 'a/b', 'a\\b', 'Upper', 'a_b', '', '-a', 'a-', 'a--b', 'a b', 'a\nb', 'a'.repeat(65), 'é', '.hidden'];
+    test.each(BAD_SLUGS)('rejects the slug %j before building any path', (slug) => {
+        expectFailure(run(slug), 'slug-invalid');
+        expect(fs_1.default.existsSync(recordsDir())).toBe(false);
+    });
+    test.each([['undefined', undefined], ['an object with toString', { toString: () => 'ok' }]])('a non-string slug (%s) is slug-invalid, not a throw', (_name, slug) => {
+        expectFailure((0, change_1.runChangeNew)(repo.root, slug, {}, { now }), 'slug-invalid');
+    });
+    test('a hostile slug never reaches the diagnostic raw', () => {
+        const r = run('a\u2028b\u001b[31m'.repeat(40));
+        expectFailure(r, 'slug-invalid');
+        expect(r.stderr).not.toContain('\u001b');
+    });
+    test('the whole first line, code included, is clipped to 300 units for a hostile slug', () => {
+        const r = run('\0'.repeat(80));
+        expectFailure(r, 'slug-invalid');
+        expect(r.stderr.split('\n')[0].length).toBe(300);
+        expect(r.stderr.split('\n')[0].endsWith('…')).toBe(true);
+    });
+});
+describe('awm change new: path safety (R3.12)', () => {
+    freshRepo();
+    test('accepts a slug of exactly 64 characters', () => {
+        receiptForHead();
+        expect(run('a'.repeat(64)).code).toBe(0);
+    });
+    (0, helpers_1.posixOnly)('refuses a symlinked docs/changes and writes nothing through it', () => {
+        receiptForHead();
+        const outside = fs_1.default.mkdtempSync(path_1.default.join(repo.home, 'out-'));
+        fs_1.default.mkdirSync(path_1.default.join(repo.root, 'docs'), { recursive: true });
+        fs_1.default.symlinkSync(outside, recordsDir());
+        expectFailure(run('ok'), 'unsafe-path');
+        expect(fs_1.default.readdirSync(outside)).toEqual([]);
+    });
+    (0, helpers_1.posixOnly)('refuses a symlinked docs and creates nothing through it', () => {
+        receiptForHead();
+        const outside = fs_1.default.mkdtempSync(path_1.default.join(repo.home, 'out-'));
+        fs_1.default.symlinkSync(outside, path_1.default.join(repo.root, 'docs'));
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'chore: link docs');
+        receiptForHead();
+        expectFailure(run('ok'), 'unsafe-path');
+        expect(fs_1.default.readdirSync(outside)).toEqual([]);
+    });
+    test('refuses when docs/changes is a regular file', () => {
+        receiptForHead();
+        fs_1.default.mkdirSync(path_1.default.join(repo.root, 'docs'), { recursive: true });
+        fs_1.default.writeFileSync(recordsDir(), 'x');
+        expectFailure(run('ok'), 'unsafe-path');
+        expect(fs_1.default.readFileSync(recordsDir(), 'utf8')).toBe('x');
+    });
+    (0, helpers_1.posixOnly)('refuses to refresh through a symlinked docs/changes', () => {
+        receiptForHead();
+        const outside = fs_1.default.mkdtempSync(path_1.default.join(repo.home, 'out-'));
+        fs_1.default.writeFileSync(path_1.default.join(outside, '2026-10-17-ok.md'), 'precious');
+        fs_1.default.mkdirSync(path_1.default.join(repo.root, 'docs'), { recursive: true });
+        fs_1.default.symlinkSync(outside, recordsDir());
+        expectFailure(run('ok', { refresh: true }), 'unsafe-path');
+        expect(fs_1.default.readFileSync(path_1.default.join(outside, '2026-10-17-ok.md'), 'utf8')).toBe('precious');
+    });
+    (0, helpers_1.posixOnly)('a link planted in place of docs while it is being created is refused, and nothing is created through it', () => {
+        receiptForHead();
+        const outside = fs_1.default.mkdtempSync(path_1.default.join(repo.home, 'out-'));
+        interceptFs('mkdirSync', (a) => baseIs(a[0], 'docs'), (_real, a) => { fs_1.default.symlinkSync(outside, String(a[0])); });
+        expectFailure(run('ok'), 'unsafe-path');
+        expect(fs_1.default.readdirSync(outside)).toEqual([]);
+    });
+    (0, helpers_1.posixOnly)('a link planted in place of changes while it is being created is refused, and nothing is created through it', () => {
+        receiptForHead();
+        const outside = fs_1.default.mkdtempSync(path_1.default.join(repo.home, 'out-'));
+        interceptFs('mkdirSync', (a) => isRecordsDirArg(a[0]), (_real, a) => { fs_1.default.symlinkSync(outside, String(a[0])); });
+        expectFailure(run('ok'), 'unsafe-path');
+        expect(fs_1.default.readdirSync(outside)).toEqual([]);
+    });
+    test('creates docs/changes when it does not exist yet', () => {
+        receiptForHead();
+        expect(fs_1.default.existsSync(path_1.default.join(repo.root, 'docs'))).toBe(false);
+        expect(run('ok').code).toBe(0);
+        expect(fs_1.default.statSync(recordsDir()).isDirectory()).toBe(true);
+    });
+    test('a failure before the write never creates docs/changes', () => {
+        expectFailure(run('ok'), 'receipt-missing', REMEDY);
+        expect(fs_1.default.existsSync(path_1.default.join(repo.root, 'docs'))).toBe(false);
+    });
+});
+/** The command refuses `opts` as `flag-invalid`, names `what`, and writes nothing. */
+const badFlag = (opts, what) => {
+    const r = run('ok', opts);
+    expectFailure(r, 'flag-invalid');
+    expect(r.stderr).toContain(what);
+    expect(recordFiles()).toEqual([]);
+};
+describe('awm change new: refused flags (R3.12, R3.11b)', () => {
+    sharedRepo();
+    const bad = badFlag;
+    test.each([
+        ['http is refused', 'http://example.com/1'],
+        ['a non-URL is refused', 'not a url'],
+        ['javascript: is refused', 'javascript:alert(1)'],
+        ['embedded credentials are refused', 'https://user@example.com/1'],
+        ['whitespace is refused', 'https://example.com/a b'],
+        ['a line break is refused', 'https://example.com/a\nb: c'],
+        ['a host-less https is refused', 'https://'],
+        ['a very long URL is refused', `https://example.com/${'a'.repeat(3000)}`],
+        ['a lone surrogate is refused', 'https://example.com/\ud800'],
+    ])('--issue: %s', (_name, issue) => bad({ issue }, '--issue'));
+    test.each([
+        ['a line break', 'a\nb'],
+        ['a control character', 'a\u0000b'],
+        ['U+2028', 'a\u2028b'],
+        ['an empty value', ''],
+        ['a blank value', '   '],
+        ['201 characters', 'm'.repeat(201)],
+        ['201 code points', '\u{1F600}'.repeat(201)],
+        ['a lone surrogate', 'a\ud800b'],
+    ])('--model: %s is refused', (_name, model) => bad({ model }, '--model'));
+    test.each([['a line break', 'a\r\nb'], ['201 characters', 's'.repeat(201)], ['a blank value', ' ']])('--session: %s is refused', (_name, session) => bad({ session }, '--session'));
+    test.each([
+        ['--model as a number', { model: 5 }, '--model'],
+        ['--plan as an array', { plan: ['a'] }, '--plan'],
+        ['--refresh as a string', { refresh: 'yes' }, '--refresh'],
+    ])('a flag that is not the right type is refused (%s)', (_name, opts, what) => bad(opts, what));
+    test.each([
+        ['a missing file', 'docs/plans/missing.md'],
+        ['.. segments', '../outside.md'],
+        ['an absolute path', path_1.default.join(path_1.default.sep, 'etc', 'passwd')],
+        ['a backslash path', 'docs\\plans\\p.md'],
+        ['a drive-letter path', 'C:/plan.md'],
+        ['a directory', 'cli'],
+    ])('--plan: %s is refused', (_name, plan) => bad({ plan }, '--plan'));
+    test('a hostile --plan value never reaches the diagnostic raw', () => {
+        const r = run('ok', { plan: 'a\u001b[31m\nb' });
+        expectFailure(r, 'flag-invalid');
+        expect(r.stderr).not.toContain('\u001b');
+    });
+    test('a non-object opts is flag-invalid, not a throw', () => {
+        expectFailure((0, change_1.runChangeNew)(repo.root, 'ok', 'x', { now }), 'flag-invalid');
+    });
+    test.each([
+        ['--plan', { plan: 'README.md' }],
+        ['--issue', { issue: 'https://example.com/1' }],
+        ['--model', { model: 'm1' }],
+        ['--session', { session: 's1' }],
+    ])('--refresh together with %s is flag-invalid and writes nothing', (flag, opts) => {
+        const r = run('ok', { ...opts, refresh: true });
+        expectFailure(r, 'flag-invalid');
+        expect(r.stderr).toContain('--refresh');
+        expect(r.stderr).toContain(flag);
+        expect(fs_1.default.existsSync(path_1.default.join(repo.root, 'docs'))).toBe(false);
+    });
+});
+describe('awm change new: --plan through links', () => {
+    freshRepo();
+    beforeEach(() => receiptForHead());
+    (0, helpers_1.posixOnly)('--plan: a symlink is refused', () => {
+        fs_1.default.symlinkSync(path_1.default.join(repo.root, 'README.md'), path_1.default.join(repo.root, 'link.md'));
+        badFlag({ plan: 'link.md' }, '--plan');
+    });
+    (0, helpers_1.posixOnly)('--plan: a file reached through a symlinked directory outside the repository is refused', () => {
+        const outside = fs_1.default.mkdtempSync(path_1.default.join(repo.home, 'out-'));
+        fs_1.default.writeFileSync(path_1.default.join(outside, 'p.md'), 'x');
+        fs_1.default.symlinkSync(outside, path_1.default.join(repo.root, 'plans'));
+        badFlag({ plan: 'plans/p.md' }, '--plan');
+    });
+});
+describe('awm change new: accepted flags', () => {
+    freshRepo();
+    beforeEach(() => receiptForHead());
+    test.each([
+        ['--issue https', { issue: 'https://example.com/1' }],
+        ['--model of 200 characters', { model: 'm'.repeat(200) }],
+        ['--model of 200 code points', { model: '\u{1F600}'.repeat(200) }],
+        ['--session', { session: 'abc' }],
+        ['--plan an existing repo file', { plan: 'README.md' }],
+    ])('%s is accepted', (_name, opts) => {
+        expect(run('ok', opts).code).toBe(0);
+    });
+});
+describe('awm change new: unsafe --base (R3.5)', () => {
+    sharedRepo();
+    test.each(['-x', '--upload-pack=evil', 'a..b', 'a b', 'a\nb', 'HEAD~1', 'a^', 'a:b', 'a@{1}', ''])('an unsafe --base %j is invalid-input', (base) => {
+        expectFailure(run('ok', { base }), 'invalid-input');
+    });
+    test('a hostile --base is echoed escaped, on one line of at most 300 units', () => {
+        const r = run('ok', { base: '\0\u001b[31m'.repeat(80) });
+        expectFailure(r, 'invalid-input');
+        expect(r.stderr).toContain('\\u0000');
+    });
+});
+describe('awm change new: base and derivation diagnostics (R3.1, R3.2, R3.5)', () => {
+    freshRepo();
+    test('an unknown --base is base-unresolved with its remedy', () => {
+        receiptForHead();
+        expectFailure(run('ok', { base: 'nope' }), 'base-unresolved', 'pass --base <ref>');
+    });
+    test('no main, master or origin/HEAD is base-unresolved', () => {
+        repo.git('branch', '-m', 'main', 'trunk');
+        receiptForHead();
+        expectFailure(run('ok'), 'base-unresolved', 'pass --base <ref>');
+    });
+    test('an explicit --base is used instead of main', () => {
+        repo.git('branch', 'trunk', 'main');
+        repo.commit({ 'cli/src/b.ts': '1' }, 'fix(core): b');
+        receiptForHead();
+        repo.git('branch', 'mid', 'HEAD~1');
+        run('change-record', { base: 'mid' });
+        expect(frontmatter(read())).toMatchObject({ type: 'fix', scope: 'core', semver: 'patch', modules: ['cli/src'] });
+    });
+    test('a branch with no commits beyond the base is no-commits', () => {
+        repo.git('checkout', '-q', 'main');
+        expectFailure(run('ok'), 'no-commits');
+    });
+    test('only non-conventional commits is no-conventional-commits', () => {
+        repo.git('checkout', '-q', '-b', 'feat/z', 'main');
+        repo.commit({ 'cli/src/z.ts': '1' }, 'update some things');
+        expectFailure(run('ok'), 'no-conventional-commits');
+    });
+    test('base and HEAD without a common ancestor is base-unresolved', () => {
+        repo.git('checkout', '-q', '--orphan', 'orphan');
+        repo.git('rm', '-rf', '-q', '.');
+        repo.commit({ 'o.ts': '1' }, 'feat: orphan');
+        receiptForHead();
+        expectFailure(run('ok'), 'base-unresolved', 'pass --base <ref>');
+    });
+    test('outside a git repository it fails with not-a-git-repo', () => {
+        expectFailure((0, change_1.runChangeNew)((0, helpers_1.nonRepoDir)(repo), 'ok', {}, { now }), 'not-a-git-repo');
+    });
+    test('a non-string cwd fails without throwing', () => {
+        expectFailure((0, change_1.runChangeNew)(undefined, 'ok', {}, { now }), 'invalid-input');
+    });
+});
+describe('awm change new --refresh (R3.11)', () => {
+    freshRepo();
+    function recordCommitted(mutate = (t) => t) {
+        receiptForHead();
+        run('change-record');
+        const edited = mutate(read().split(types_1.PENDING_MARKER).join('written by agent'));
+        fs_1.default.writeFileSync(file(), edited);
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): record');
+        repo.commit({ 'cli/src/core/b.ts': '1' }, 'fix(core): b');
+        receiptForHead();
+        return edited;
+    }
+    const strip = (s) => s.replace(/^(type|scope|semver|breaking|modules|verification):[\s\S]*?(?=^[a-z_]+:|^---$)/gm, '');
+    test('recomputes the derived fields and verification', () => {
+        recordCommitted();
+        const r = run('change-record', { refresh: true });
+        expect(r).toEqual({ code: 0, stdout: 'Refreshed docs/changes/2026-10-17-change-record.md\n', stderr: '' });
+        const fm = frontmatter(read());
+        expect(fm.verification.commit).toBe(repo.git('rev-parse', 'HEAD'));
+        expect(fm.modules).toEqual(['cli/src', 'cli/src/core']);
+        expect(fm).toMatchObject({ type: 'feat', scope: 'changes', semver: 'minor' });
+    });
+    test('every byte outside the derived keys and verification is unchanged', () => {
+        const edited = recordCommitted();
+        run('change-record', { refresh: true });
+        expect(strip(read())).toBe(strip(edited));
+        expect(read()).not.toBe(edited);
+    });
+    test('the refreshed record still validates', () => {
+        recordCommitted();
+        run('change-record', { refresh: true });
+        expect((0, validate_shape_1.validateRecordShape)('2026-10-17-change-record.md', read(), { root: repo.root }).diagnostics).toEqual([]);
+    });
+    test('refresh works on the record of another date', () => {
+        recordCommitted();
+        run('change-record', { refresh: true }, { now: () => new Date('2030-01-01T00:00:00.000Z') });
+        expect(frontmatter(read()).id).toBe('2026-10-17-change-record');
+    });
+    test('a CRLF record keeps CRLF everywhere and its other bytes', () => {
+        const edited = recordCommitted((t) => t.replace(/\n/g, '\r\n'));
+        run('change-record', { refresh: true });
+        const after = read();
+        expect(after).not.toMatch(/[^\r]\n/);
+        expect(strip(after.replace(/\r\n/g, '\n'))).toBe(strip(edited.replace(/\r\n/g, '\n')));
+        expect(frontmatter(after).verification.commit).toBe(repo.git('rev-parse', 'HEAD'));
+    });
+    test('refresh does not require a clean tree for docs/changes itself but still refuses other changes', () => {
+        recordCommitted();
+        fs_1.default.writeFileSync(path_1.default.join(repo.root, 'dirty.ts'), 'x');
+        expectFailure(run('change-record', { refresh: true }), 'tree-dirty', REMEDY);
+    });
+    test('refresh needs a receipt for HEAD', () => {
+        recordCommitted();
+        fs_1.default.rmSync(path_1.default.join(repo.root, '.awm', 'sensors'), { recursive: true });
+        expectFailure(run('change-record', { refresh: true }), 'receipt-missing', REMEDY);
+    });
+    test('a missing record is record-missing and creates nothing', () => {
+        receiptForHead();
+        expectFailure(run('change-record', { refresh: true }), 'record-missing', 'run awm change new change-record to create it');
+        expect(fs_1.default.existsSync(path_1.default.join(repo.root, 'docs'))).toBe(false);
+    });
+    test('an existing docs/changes without that slug is record-missing', () => {
+        receiptForHead();
+        run('other');
+        expectFailure(run('change-record', { refresh: true }), 'record-missing', 'run awm change new change-record to create it');
+    });
+    test('two records with the same slug are record-ambiguous and neither is modified', () => {
+        receiptForHead();
+        run('change-record');
+        run('change-record', {}, { now });
+        fs_1.default.copyFileSync(file(), path_1.default.join(recordsDir(), '2026-11-01-change-record.md'));
+        const before = recordFiles().map((f) => fs_1.default.readFileSync(path_1.default.join(recordsDir(), f), 'utf8'));
+        expectFailure(run('change-record', { refresh: true }), 'record-ambiguous');
+        expect(recordFiles().map((f) => fs_1.default.readFileSync(path_1.default.join(recordsDir(), f), 'utf8'))).toEqual(before);
+    });
+    test('a broken record is record-invalid and untouched', () => {
+        receiptForHead();
+        fs_1.default.mkdirSync(recordsDir(), { recursive: true });
+        fs_1.default.writeFileSync(file(), '---\n: : :\n---\n');
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): broken');
+        receiptForHead();
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+        expect(read()).toBe('---\n: : :\n---\n');
+    });
+    test('a record missing a derived key is record-invalid and untouched', () => {
+        receiptForHead();
+        run('change-record');
+        const broken = read().replace(/^semver: .*\n/m, '');
+        fs_1.default.writeFileSync(file(), broken);
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): broken');
+        receiptForHead();
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+        expect(read()).toBe(broken);
+    });
+    test('R3.4 a refresh that would push the record over 64 KiB is record-too-large with a remedy, and the record is untouched', () => {
+        receiptForHead();
+        run('change-record');
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): record');
+        const files = Object.fromEntries(Array.from({ length: 4000 }, (_, i) => [`vendor/package-${String(i).padStart(5, '0')}/index.js`, '1']));
+        (0, helpers_1.importCommits)(repo, [{ message: 'feat(vendor): import vendored packages', files, date: '2026-10-17T10:30:00Z' }]);
+        receiptForHead();
+        const before = read();
+        expectFailure(run('change-record', { refresh: true }), 'record-too-large', REMEDY_SPLIT);
+        expect(read()).toBe(before);
+    });
+    test('a record already over 64 KiB on disk is record-invalid and untouched (it cannot be read for a rewrite)', () => {
+        receiptForHead();
+        run('change-record');
+        fs_1.default.writeFileSync(file(), `${read()}\n${'x'.repeat(70 * 1024)}\n`);
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): huge');
+        receiptForHead();
+        const before = read();
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+        expect(read()).toBe(before);
+    });
+    test('a record that is not valid UTF-8 is record-invalid and untouched', () => {
+        receiptForHead();
+        run('change-record');
+        const bytes = Buffer.concat([fs_1.default.readFileSync(file()), Buffer.from([0xff, 0xfe, 0x0a])]);
+        fs_1.default.writeFileSync(file(), bytes);
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): bytes');
+        receiptForHead();
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+        expect(fs_1.default.readFileSync(file()).equals(bytes)).toBe(true);
+    });
+    test('a record with a UTF-8 BOM is record-invalid and its bytes are untouched', () => {
+        receiptForHead();
+        run('change-record');
+        const bytes = Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), fs_1.default.readFileSync(file())]);
+        fs_1.default.writeFileSync(file(), bytes);
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): bom');
+        receiptForHead();
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+        expect(fs_1.default.readFileSync(file()).equals(bytes)).toBe(true);
+    });
+    test('a record without a BOM but with non-ASCII text still refreshes and keeps those bytes', () => {
+        receiptForHead();
+        run('change-record');
+        fs_1.default.writeFileSync(file(), fs_1.default.readFileSync(file(), 'utf8').split(types_1.PENDING_MARKER).join('Qué se probó ñandú \u{1F600}'));
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): text');
+        repo.commit({ 'cli/src/core/b.ts': '1' }, 'fix(core): b');
+        receiptForHead();
+        expect(run('change-record', { refresh: true }).code).toBe(0);
+        expect(read()).toContain('Qué se probó ñandú \u{1F600}');
+        expect(read().charCodeAt(0)).toBe('-'.charCodeAt(0));
+    });
+    test('a record larger than the record limit is record-invalid', () => {
+        receiptForHead();
+        run('change-record');
+        fs_1.default.appendFileSync(file(), 'x'.repeat(70 * 1024));
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): big');
+        receiptForHead();
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+    });
+    test('a record whose derived keys are quoted is refreshed and still validates', () => {
+        receiptForHead();
+        run('change-record');
+        const quoted = read().replace(/^(type|semver) *:/gm, '"$1" :');
+        fs_1.default.writeFileSync(file(), quoted.split(types_1.PENDING_MARKER).join('written by agent'));
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): quoted');
+        repo.commit({ 'cli/src/core/b.ts': '1' }, 'fix(core): b');
+        receiptForHead();
+        expect(run('change-record', { refresh: true }).code).toBe(0);
+        expect(read()).not.toContain('"semver"');
+        expect((0, validate_shape_1.validateRecordShape)('2026-10-17-change-record.md', read(), { root: repo.root }).diagnostics).toEqual([]);
+    });
+    (0, helpers_1.posixOnly)('a record that is a symlink is refused and its target untouched', () => {
+        receiptForHead();
+        fs_1.default.mkdirSync(recordsDir(), { recursive: true });
+        const outside = path_1.default.join(repo.home, 'real.md');
+        fs_1.default.writeFileSync(outside, 'precious');
+        fs_1.default.symlinkSync(outside, file());
+        expectFailure(run('change-record', { refresh: true }), 'unsafe-path');
+        expect(fs_1.default.readFileSync(outside, 'utf8')).toBe('precious');
+    });
+    test('a record that is a directory is record-invalid', () => {
+        receiptForHead();
+        fs_1.default.mkdirSync(file(), { recursive: true });
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+    });
+    test('a failed write keeps the old content and leaves no temporary file', () => {
+        const edited = recordCommitted();
+        interceptFs('renameSync', (a) => baseIs(a[1], path_1.default.basename(file())), () => { throw Object.assign(new Error('nope'), { code: 'EPERM' }); });
+        expectFailure(run('change-record', { refresh: true }), 'io-failed');
+        jest.restoreAllMocks();
+        expect(read()).toBe(edited);
+        expect(recordFiles()).toEqual(['2026-10-17-change-record.md']);
+    });
+    test('refresh accepts --base', () => {
+        recordCommitted();
+        expect(run('change-record', { refresh: true, base: 'main' }).code).toBe(0);
+    });
+    test('a derived key spelled with a YAML escape is record-invalid and the bytes are untouched', () => {
+        receiptForHead();
+        run('change-record');
+        const bytes = Buffer.from(read().replace(/^type: .*$/m, '"t\\x79pe": fix'));
+        expect(bytes.toString('utf8')).toContain('"t\\x79pe": fix');
+        fs_1.default.writeFileSync(file(), bytes);
+        repo.git('add', '-A');
+        repo.git('commit', '-q', '-m', 'docs(changes): escaped key');
+        receiptForHead();
+        expectFailure(run('change-record', { refresh: true }), 'record-invalid');
+        expect(fs_1.default.readFileSync(file()).equals(bytes)).toBe(true);
+    });
+    describe('a record that changes between being read and being written', () => {
+        /** Lets the real splice run, then edits the record as a concurrent editor would. */
+        function editDuringRefresh(edit) {
+            const real = renderModule.refreshDerived;
+            jest.spyOn(renderModule, 'refreshDerived').mockImplementation((...args) => { const out = real(...args); edit(); return out; });
+        }
+        const later = new Date(Date.now() + 60_000);
+        test.each([
+            ['it grows', () => fs_1.default.appendFileSync(file(), 'edited meanwhile\n')],
+            ['it keeps its size but is rewritten later', () => { const t = fs_1.default.readFileSync(file(), 'utf8'); fs_1.default.writeFileSync(file(), t.replace('written by agent', 'written by human')); fs_1.default.utimesSync(file(), later, later); }],
+            ['only its modification time moves', () => fs_1.default.utimesSync(file(), later, later)],
+        ])('%s: record-changed, and the editor\'s version is kept', (_name, edit) => {
+            recordCommitted();
+            editDuringRefresh(edit);
+            expectFailure(run('change-record', { refresh: true }), 'record-changed');
+            jest.restoreAllMocks();
+            // The editor's version stands: the record still has the derived values of the commit it was written for.
+            expect(frontmatter(read()).modules).toEqual(['cli/src']);
+        });
+        (0, helpers_1.posixOnly)('it is replaced by a symlink: record-changed, and the link target is untouched', () => {
+            recordCommitted();
+            const outside = path_1.default.join(repo.home, 'real.md');
+            fs_1.default.writeFileSync(outside, 'precious');
+            editDuringRefresh(() => { fs_1.default.rmSync(file()); fs_1.default.symlinkSync(outside, file()); });
+            expectFailure(run('change-record', { refresh: true }), 'record-changed');
+            jest.restoreAllMocks();
+            expect(fs_1.default.readFileSync(outside, 'utf8')).toBe('precious');
+            expect(fs_1.default.lstatSync(file()).isSymbolicLink()).toBe(true);
+        });
+        test('an untouched record is refreshed (the check is not always failing)', () => {
+            recordCommitted();
+            editDuringRefresh(() => undefined);
+            expect(run('change-record', { refresh: true }).code).toBe(0);
+        });
+    });
+    (0, helpers_1.posixOnly)('refresh keeps the file mode', () => {
+        recordCommitted();
+        fs_1.default.chmodSync(file(), 0o640);
+        run('change-record', { refresh: true });
+        expect(fs_1.default.statSync(file()).mode & 0o777).toBe(0o640);
+    });
+});
+describe('registerChangeCommand', () => {
+    freshRepo();
+    function program() {
+        const p = new commander_1.Command();
+        p.exitOverride();
+        (0, change_1.registerChangeCommand)(p, { now });
+        return p;
+    }
+    let savedExit;
+    let out;
+    let err;
+    beforeEach(() => {
+        savedExit = process.exitCode;
+        out = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        err = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        // The action reads process.cwd(); pointing it at the repository needs no chdir (a process cannot delete its own cwd on Windows).
+        jest.spyOn(process, 'cwd').mockImplementation(() => repo.root);
+    });
+    afterEach(() => { process.exitCode = savedExit; });
+    test('registers change new with its documented flags', () => {
+        const change = program().commands.find((c) => c.name() === 'change');
+        const sub = change?.commands.find((c) => c.name() === 'new');
+        expect(sub?.options.map((o) => o.long).sort()).toEqual(['--base', '--issue', '--model', '--plan', '--refresh', '--session']);
+    });
+    test('the change command describes both of its subcommands', () => {
+        expect(program().commands.find((c) => c.name() === 'change')?.description()).toBe('create and validate the Change Record of the current branch');
+    });
+    test('runs from the cwd, prints the created path and leaves the exit code alone', async () => {
+        receiptForHead();
+        await program().parseAsync(['node', 'awm', 'change', 'new', 'change-record', '--model', 'm1']);
+        expect(out).toHaveBeenCalledWith('Created docs/changes/2026-10-17-change-record.md\n');
+        expect(process.exitCode).toBe(savedExit);
+        expect(frontmatter(read()).provenance.model).toBe('m1');
+    });
+    test('a failure writes the diagnostic to stderr and sets exit code 2', async () => {
+        await program().parseAsync(['node', 'awm', 'change', 'new', 'change-record']);
+        expect(err).toHaveBeenCalledWith(expect.stringContaining('receipt-missing: '));
+        expect(process.exitCode).toBe(2);
+    });
+    test('--refresh reaches the command', async () => {
+        receiptForHead();
+        await program().parseAsync(['node', 'awm', 'change', 'new', 'change-record', '--refresh']);
+        expect(err).toHaveBeenCalledWith(expect.stringContaining('record-missing: '));
+    });
+    test('a cwd that is not accessible is reported, not thrown', async () => {
+        jest.spyOn(process, 'cwd').mockImplementation(() => { throw Object.assign(new Error('gone'), { code: 'ENOENT' }); });
+        await program().parseAsync(['node', 'awm', 'change', 'new', 'x']);
+        expect(process.exitCode).toBe(2);
+        expect(err).toHaveBeenCalledWith(expect.stringMatching(/^[a-z-]+: /));
+    });
+});