ushman-ledger 1.1.0 → 1.2.0

package/AGENTS.md

@@ -23,13 +23,17 @@ An append-only ledger library and CLI for ushman v4 workspaces. It owns ledger s
 ## Read order
 
 1. `README.md`
-2. `src/schema/entry.ts`
-3. `src/storage/filesystem.ts`
-4. `src/record.ts`
-5. `src/handle.ts`
-6. `src/coverage.ts`
-7. `src/doctor.ts`
-8. `src/cli.ts`
+2. `src/schema/entry-core.ts`
+3. `src/schema/entry-read.ts`
+4. `src/schema/entry-write.ts`
+5. `src/schema/entry-migrations.ts`
+6. `src/schema/entry.ts`
+7. `src/storage/filesystem.ts`
+8. `src/record.ts`
+9. `src/handle.ts`
+10. `src/coverage.ts`
+11. `src/doctor.ts`
+12. `src/cli.ts`
 
 ## Commands
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.1.0] - 2026-05-23
+
+- Added `change-log` records, narrative note subkinds, and `migration-log-md` / `workspace-narrative-md` render targets.
+- Split entry schema parsing into focused read/write/core modules and moved compatibility coercions behind dedicated parse migrations.
+- Extracted patch-source resolution behind a dedicated resolver with focused tests and more actionable hash mismatch failures.
+
 ## [1.0.1] - 2026-05-16
 
 - Tightened the schema surface to the ledger primitives the v4 orchestrator actively uses.

package/README.md

@@ -9,6 +9,7 @@ Append-only workspace ledger library and CLI for ushman v4 workspaces.
 - Content-hash idempotency
 - Patch blob storage
 - Retro / JSONL / timeline / dependency-graph rendering
+- Change-log / workspace narrative markdown rendering
 - Archive integrity output
 - Doctor and coverage helpers
 
@@ -58,6 +59,7 @@ await ledger.record(
 );
 
 await ledger.render({ to: 'retro' });
+await ledger.render({ to: 'migration-log-md' });
 await ledger.archive('/tmp/ledger.tgz');
 ```
 
@@ -67,22 +69,37 @@ await ledger.archive('/tmp/ledger.tgz');
 ushman-ledger record --workspace=<ws> --kind=tool-invocation --phase=capture --summary="capture started"
 ushman-ledger record --workspace=<ws> --kind=agent-patch --phase=cleanup --summary="capture git diff" --rationale="track working tree change" --diff-from-git=HEAD
 ushman-ledger record --workspace=<ws> --kind=operator-decision --phase=cleanup --summary="manual override" --action=ledger-hand-edit --check-id=manual-review --rationale="operator edited the ledger after audit"
+ushman-ledger record --workspace=<ws> --kind=change-log --subkind=semantic-cleanup --phase=cleanup --summary="split schema modules" --diff=/tmp/change.patch --hypothesis="smaller schema modules keep the public API stable" --commands=$'bun test\nbun run typecheck' --smoke-result=pass --parity-status=green --rollback-plan="revert the schema split"
 ushman-ledger note regression --workspace=<ws> --phase=cleanup --summary="runtime drift" --body=/tmp/note.md
+ushman-ledger note cleanup-wave --workspace=<ws> --phase=cleanup --summary="wave 1" --body=/tmp/narrative.md
 ushman-ledger list --workspace=<ws> --json
 ushman-ledger render --workspace=<ws> --to=retro
+ushman-ledger render --workspace=<ws> --to=migration-log-md
+ushman-ledger render --workspace=<ws> --to=workspace-narrative-md
 ushman-ledger render --workspace=<ws> --to=jsonl --out=/tmp/ledger.jsonl
 ushman-ledger render --workspace=<ws> --to=dependency-graph --out=/tmp/ledger.mmd
 ushman-ledger archive --workspace=<ws> --out=/tmp/ledger.tgz
 ushman-ledger doctor --workspace=<ws>
 ```
 
-Valid record kinds: `tool-invocation`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`
+Valid record kinds: `tool-invocation`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`, `change-log`
 
 Valid phases: `capture`, `intake`, `seed`, `vendor-extract`, `cleanup`, `parity`, `characterize`, `equiv`, `analyze`, `recover`, `ship`, `migration`
 
-Valid note subkinds: `regression`, `automation`, `retro`, `operator`, `tooling-gap`
+Valid note subkinds: `regression`, `automation`, `retro`, `operator`, `tooling-gap`, `cleanup-wave`, `verified-flow`, `open-issue`, `decomposition-wave`, `semantic-cleanup-summary`
 
-Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`
+Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `migration-log-md`, `workspace-narrative-md`
+
+## Change-log records
+
+`change-log` entries are append-only structured narrative records for migration and cleanup work. They accept:
+
+- `subkind`: `pre-change-checkpoint`, `semantic-cleanup`, `vendor-extract`, `decomposition`, `rollback`, `hotfix`, `smoke`
+- `filesChanged`: explicit CSV paths via `--files-changed`, or automatic diffstat-style derivation from `--diff` / `--diff-from-git`
+- optional narrative fields: `hypothesis`, `commandsRun`, `smokeResult`, `smokeNotes`, `parityStatus`, `rollbackPlan`
+- `rollsBack`: required when `subkind=rollback`
+
+`migration-log-md` renders only `change-log` entries. `workspace-narrative-md` renders only the dedicated narrative note subkinds.
 
 ## Workspace prerequisite
 
@@ -164,7 +181,9 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`
   pending-archives/
   blobs/
   render.md
+  render.migration-log.md
   render.timeline.html
+  render.workspace-narrative.md
   <phase>/
     <timestamp>-<sequence>-<hash>.json
 ```

package/dist/blobs.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, stat } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { sha256File, sha256Hex } from "./json.js";
 import { resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
@@ -34,11 +34,11 @@ export const storePatchBlob = async (workspaceRoot, patchText) => {
     const blobPath = buildBlobPath(workspaceRoot, blobSha256);
     let shouldWrite = true;
     try {
-        await stat(blobPath);
         shouldWrite = (await sha256File(blobPath)) !== blobSha256;
     }
     catch (error) {
-        if (error.code !== 'ENOENT') {
+        const code = error.code;
+        if (code !== 'ENOENT') {
             throw error;
         }
     }

package/dist/builders.d.ts

@@ -104,6 +104,49 @@ export declare const buildCorrectionRecord: (input: BuildRecordInput<Extract<Led
     phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
     summary: string;
 };
+/** Build a `change-log` record. */
+export declare const buildChangeLogRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "change-log";
+}>>) => {
+    commandsRun?: string[] | undefined;
+    filesChanged: {
+        added?: number | undefined;
+        path: string;
+        removed?: number | undefined;
+    }[];
+    hypothesis?: string | undefined;
+    kind: "change-log";
+    parityStatus?: "not-run" | "green" | "yellow" | "red" | undefined;
+    rollbackPlan?: string | undefined;
+    rollsBack?: string | undefined;
+    smokeNotes?: string | undefined;
+    smokeResult?: "pass" | "fail" | "partial" | "not-run" | undefined;
+    subkind: "vendor-extract" | "pre-change-checkpoint" | "semantic-cleanup" | "decomposition" | "rollback" | "hotfix" | "smoke";
+    details?: {
+        [x: string]: unknown;
+    } | undefined;
+    emitter: {
+        tool: string;
+        user?: string | undefined;
+        version: string;
+    };
+    idempotencyKey?: string | undefined;
+    links?: ({
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } & {
+        [key: string]: unknown;
+    }) | undefined;
+    phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+};
 /** Build a `strip-decision-reverted` record. */
 export declare const buildStripDecisionRevertedRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
     kind: "strip-decision-reverted";

package/dist/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AACA,OAAO,EAEH,KAAK,YAAY,EAKpB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,gBAAgB,CAAC,OAAO,SAAS,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,GACpC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3E,CAAC;AAEP,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,GACnC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK1E,CAAC;AAEP,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAItG,CAAC;AAEP,gDAAgD;AAChD,eAAO,MAAM,gCAAgC,GACzC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjF,CAAC"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,YAAY,EAIpB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,gBAAgB,CAAC,OAAO,SAAS,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,GACpC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3E,CAAC;AAEP,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,GACnC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK1E,CAAC;AAEP,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAItG,CAAC;AAEP,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIrG,CAAC;AAEP,gDAAgD;AAChD,eAAO,MAAM,gCAAgC,GACzC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjF,CAAC"}

package/dist/builders.js

@@ -1,10 +1,10 @@
 import * as v from 'valibot';
-import { CorrectionRecordSchema, OperatorDecisionPayloadSchema, OperatorDecisionRecordSchema, StripDecisionRevertedRecordSchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
+import { ChangeLogRecordSchema, CorrectionRecordSchema, OperatorDecisionRecordSchema, StripDecisionRevertedRecordSchema, ValidatorResultRecordSchema, } from "./schema/entry.js";
 /** Build an `operator-decision` record with a validated structured payload. */
 export const buildOperatorDecisionRecord = (input) => v.parse(OperatorDecisionRecordSchema, {
     ...input,
     kind: 'operator-decision',
-    payload: v.parse(OperatorDecisionPayloadSchema, input.payload),
+    payload: input.payload,
 });
 /** Build a `validator-result` record. */
 export const buildValidatorResultRecord = (input) => v.parse(ValidatorResultRecordSchema, {
@@ -16,6 +16,11 @@ export const buildCorrectionRecord = (input) => v.parse(CorrectionRecordSchema,
     ...input,
     kind: 'correction',
 });
+/** Build a `change-log` record. */
+export const buildChangeLogRecord = (input) => v.parse(ChangeLogRecordSchema, {
+    ...input,
+    kind: 'change-log',
+});
 /** Build a `strip-decision-reverted` record. */
 export const buildStripDecisionRevertedRecord = (input) => v.parse(StripDecisionRevertedRecordSchema, {
     ...input,

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoBA,KAAK,UAAU,GAAG;IACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C,CAAC;AAqjBF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,OAAO,CAAC,UAAU,CAAM,KAAG,OAAO,CAAC,MAAM,CAqC7G,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAE1F,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmDA,KAAK,UAAU,GAAG;IACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C,CAAC;AAiwBF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,OAAO,CAAC,UAAU,CAAM,KAAG,OAAO,CAAC,MAAM,CAqC7G,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAE1F,CAAC"}

package/dist/cli.js

@@ -7,12 +7,33 @@ import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import * as v from 'valibot';
 import { openLedger } from "./handle.js";
-import { LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord } from "./schema/entry.js";
+import { deriveFilesChangedFromPatch } from "./patch-resolver.js";
+import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord, WorkspaceRelativePathSchema, } from "./schema/entry.js";
 import { NoteSubkindSchema } from "./schema/note.js";
 import { LEDGER_LIBRARY_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
+const GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const GIT_DIFF_TIMEOUT_MS = 30_000;
-const RENDER_TARGETS = ['retro', 'jsonl', 'timeline-html', 'dependency-graph'];
+const RENDER_TARGETS = [
+    'retro',
+    'jsonl',
+    'timeline-html',
+    'dependency-graph',
+    'migration-log-md',
+    'workspace-narrative-md',
+];
+const CHANGE_LOG_RECORD_ONLY_FLAGS = [
+    'commands',
+    'commands-from',
+    'files-changed',
+    'hypothesis',
+    'parity-status',
+    'rollback-plan',
+    'rolls-back',
+    'smoke-notes',
+    'smoke-result',
+    'subkind',
+];
 class CliUsageError extends Error {
 }
 const DEFAULT_CONTEXT = {
@@ -34,12 +55,12 @@ const renderValidValues = () => `Valid values:
 const renderHelp = (commandName) => `${commandName}
 
 Commands:
-  ${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--from-stdin]
+  ${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]
   ${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
   ${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
   ${commandName} show [--workspace=<ws>] <entry-id>
   ${commandName} tail [--workspace=<ws>] [--phase=<phase>] [--limit=<n>]
-  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph] [--phase=<phase>] [--out=<file>]
+  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
   ${commandName} archive [--workspace=<ws>] --out=<file.tgz>
   ${commandName} doctor [--workspace=<ws>]
   ${commandName} --version
@@ -48,7 +69,7 @@ ${renderValidValues()}`;
 const renderCommandHelp = (commandName, command) => {
     switch (command) {
         case 'record':
-            return `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--from-stdin]
+            return `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]
 
 ${renderValidValues()}`;
         case 'note':
@@ -60,7 +81,7 @@ ${renderValidValues()}`;
 
 ${renderValidValues()}`;
         case 'render':
-            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--out=<file>]
+            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
 
 ${renderValidValues()}`;
         default:
@@ -99,6 +120,9 @@ const parseArgv = (argv) => {
 };
 const getFlag = (flags, name) => {
     const value = flags[name];
+    if (value === true) {
+        throw new CliUsageError(`Missing value for --${name}.`);
+    }
     return typeof value === 'string' ? value : undefined;
 };
 const hasFlag = (flags, name) => flags[name] === true || typeof flags[name] === 'string';
@@ -140,7 +164,7 @@ const materializeGitDiff = async (workspaceRoot, gitRef) => {
     try {
         const { stdout } = await execFileAsync('git', ['diff', gitRef], {
             cwd: workspaceRoot,
-            maxBuffer: 10 * 1024 * 1024,
+            maxBuffer: GIT_DIFF_MAX_BUFFER_BYTES,
             timeout: GIT_DIFF_TIMEOUT_MS,
         });
         tempDir = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-git-diff-'));
@@ -234,18 +258,121 @@ const parseRenderTarget = (flags) => {
     }
     return target;
 };
+const splitCommandLines = (value) => value
+    .split(/\r?\n/u)
+    .map((command) => command.trim())
+    .filter((command) => command.length > 0);
+const getUsedFlags = (flags, names) => names.filter((name) => hasFlag(flags, name)).map((name) => `--${name}`);
+const rejectUnsupportedFlags = (supportedKindLabel, flags, names) => {
+    const usedFlags = getUsedFlags(flags, names);
+    if (usedFlags.length === 0) {
+        return;
+    }
+    throw new CliUsageError(`${usedFlags.join(', ')} ${usedFlags.length === 1 ? 'is' : 'are'} only supported for ${supportedKindLabel} records.`);
+};
+const parseRequiredChangeLogSubkind = (flags) => {
+    const subkind = getRequiredString(flags, 'subkind');
+    if (!ChangeLogSubkindSchema.options.includes(subkind)) {
+        throw new CliUsageError(`Invalid --subkind value: ${subkind}. Expected one of: ${ChangeLogSubkindSchema.options.join(', ')}.`);
+    }
+    return subkind;
+};
+const parseOptionalChangeLogPicklist = ({ flagName, flags, options, }) => {
+    const value = getFlag(flags, flagName);
+    if (!value) {
+        return undefined;
+    }
+    if (!options.includes(value)) {
+        throw new CliUsageError(`Invalid --${flagName} value: ${value}. Expected one of: ${options.join(', ')}.`);
+    }
+    return value;
+};
+const parseFilesChangedCsv = (raw) => {
+    const uniquePaths = [
+        ...new Set(raw
+            .split(',')
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)
+            .map((filePath) => {
+            try {
+                return v.parse(WorkspaceRelativePathSchema, filePath);
+            }
+            catch {
+                throw new CliUsageError(`--files-changed path is not a normalized workspace-relative path: ${filePath}`);
+            }
+        })),
+    ];
+    if (uniquePaths.length === 0) {
+        throw new CliUsageError('--files-changed must include at least one workspace-relative path.');
+    }
+    return uniquePaths.map((filePath) => ({ path: filePath }));
+};
+const readCommandLines = async (flags) => {
+    const inlineCommands = getFlag(flags, 'commands');
+    const commandsFrom = getFlag(flags, 'commands-from');
+    if (inlineCommands && commandsFrom) {
+        throw new CliUsageError('Use either --commands or --commands-from, not both.');
+    }
+    if (commandsFrom) {
+        const commandsPath = path.resolve(commandsFrom);
+        await ensureFileExists(commandsPath, '--commands-from');
+        return splitCommandLines(await readFile(commandsPath, 'utf8'));
+    }
+    if (inlineCommands) {
+        return splitCommandLines(inlineCommands);
+    }
+    return undefined;
+};
+const resolveDiffInput = async ({ flags, kind, workspaceRoot, }) => {
+    const diffPath = getFlag(flags, 'diff');
+    const diffFromGit = getFlag(flags, 'diff-from-git');
+    if (diffPath && diffFromGit) {
+        throw new CliUsageError('Use either --diff or --diff-from-git, not both.');
+    }
+    if (!diffPath && !diffFromGit) {
+        return {};
+    }
+    if (kind !== 'agent-patch' && kind !== 'operator-patch' && kind !== 'change-log') {
+        throw new CliUsageError('--diff and --diff-from-git are only supported for patch and change-log records.');
+    }
+    if (diffPath) {
+        const resolvedDiffPath = path.resolve(diffPath);
+        await ensureFileExists(resolvedDiffPath, '--diff');
+        return {
+            diffPath: resolvedDiffPath,
+            patchText: kind === 'change-log' ? await readFile(resolvedDiffPath, 'utf8') : undefined,
+        };
+    }
+    const materialized = await materializeGitDiff(workspaceRoot, diffFromGit ?? '');
+    return {
+        cleanupTempDir: materialized.tempDir,
+        diffPath: materialized.patchPath,
+        gitRef: diffFromGit,
+        patchText: kind === 'change-log' ? await readFile(materialized.patchPath, 'utf8') : undefined,
+    };
+};
 const validateRecordStdinFlags = (flags) => {
     const conflictingFlags = [
         'agent',
         'action',
         'check-id',
+        'commands',
+        'commands-from',
         'diff',
         'diff-from-git',
+        'files-changed',
+        'hypothesis',
         'idempotency-key',
         'kind',
         'operator',
+        'parity-status',
         'phase',
         'rationale',
+        'rollback-plan',
+        'rolls-back',
+        'smoke-notes',
+        'smoke-result',
+        'subkind',
         'summary',
     ].filter((flagName) => hasFlag(flags, flagName));
     if (conflictingFlags.length === 0) {
@@ -257,6 +384,9 @@ const validateRecordStdinFlags = (flags) => {
 };
 const buildBaseRecordFromFlags = (parsed, context) => {
     const kind = getRequiredKind(parsed.flags);
+    if (kind !== 'change-log') {
+        rejectUnsupportedFlags('change-log', parsed.flags, CHANGE_LOG_RECORD_ONLY_FLAGS);
+    }
     const record = {
         emitter: {
             tool: context.defaultEmitter.tool,
@@ -296,43 +426,68 @@ const buildBaseRecordFromFlags = (parsed, context) => {
             rationale: rationale ?? '',
         };
     }
+    if (kind === 'change-log') {
+        record.subkind = parseRequiredChangeLogSubkind(parsed.flags);
+    }
     const idempotencyKey = getFlag(parsed.flags, 'idempotency-key');
     if (idempotencyKey) {
         record.idempotencyKey = idempotencyKey;
     }
     return { kind, record };
 };
-const applyPatchInputToRecord = async ({ kind, record, workspaceRoot, parsed, }) => {
-    const diffPath = getFlag(parsed.flags, 'diff');
-    if (diffPath) {
-        if (kind !== 'agent-patch' && kind !== 'operator-patch') {
-            throw new CliUsageError('--diff is only supported for patch records.');
-        }
-        await ensureFileExists(path.resolve(diffPath), '--diff');
-        record.diffPath = diffPath;
-    }
-    const diffFromGit = getFlag(parsed.flags, 'diff-from-git');
-    if (!diffFromGit) {
-        return {};
-    }
+const applyPatchInputToRecord = async ({ kind, patchInput, record, }) => {
     if (kind !== 'agent-patch' && kind !== 'operator-patch') {
-        throw new CliUsageError('--diff-from-git is only supported for patch records.');
-    }
-    if (diffPath) {
-        throw new CliUsageError('Use either --diff or --diff-from-git, not both.');
+        return {};
     }
-    const materialized = await materializeGitDiff(workspaceRoot, diffFromGit);
     return {
-        cleanupTempDir: materialized.tempDir,
+        cleanupTempDir: patchInput.cleanupTempDir,
         record: {
             ...record,
-            diffPath: materialized.patchPath,
-            links: {
-                gitRef: diffFromGit,
-            },
+            diffPath: patchInput.diffPath,
+            links: patchInput.gitRef
+                ? {
+                    ...record.links,
+                    gitRef: patchInput.gitRef,
+                }
+                : record.links,
         },
     };
 };
+const applyChangeLogFlagsToRecord = async ({ flags, patchInput, record, }) => {
+    const filesChangedFlag = getFlag(flags, 'files-changed');
+    if (filesChangedFlag && patchInput.patchText) {
+        throw new CliUsageError('Use either --files-changed or --diff/--diff-from-git to populate change-log files.');
+    }
+    return {
+        ...record,
+        commandsRun: await readCommandLines(flags),
+        filesChanged: filesChangedFlag
+            ? parseFilesChangedCsv(filesChangedFlag)
+            : patchInput.patchText
+                ? deriveFilesChangedFromPatch(patchInput.patchText)
+                : undefined,
+        hypothesis: getFlag(flags, 'hypothesis'),
+        links: patchInput.gitRef
+            ? {
+                ...record.links,
+                gitRef: patchInput.gitRef,
+            }
+            : record.links,
+        parityStatus: parseOptionalChangeLogPicklist({
+            flagName: 'parity-status',
+            flags,
+            options: ChangeLogParityStatusSchema.options,
+        }),
+        rollbackPlan: getFlag(flags, 'rollback-plan'),
+        rollsBack: getFlag(flags, 'rolls-back'),
+        smokeNotes: getFlag(flags, 'smoke-notes'),
+        smokeResult: parseOptionalChangeLogPicklist({
+            flagName: 'smoke-result',
+            flags,
+            options: ChangeLogSmokeResultSchema.options,
+        }),
+    };
+};
 const buildRecordFromFlags = async (parsed, context) => {
     const workspaceRoot = getWorkspaceRoot(parsed.flags);
     if (hasFlag(parsed.flags, 'from-stdin')) {
@@ -344,17 +499,41 @@ const buildRecordFromFlags = async (parsed, context) => {
         };
     }
     const { kind, record } = buildBaseRecordFromFlags(parsed, context);
-    const patchInput = await applyPatchInputToRecord({
-        kind,
-        parsed,
-        record,
-        workspaceRoot,
-    });
-    return {
-        cleanupTempDir: patchInput.cleanupTempDir,
-        record: patchInput.record ?? record,
-        workspaceRoot,
-    };
+    let diffInput;
+    try {
+        diffInput = await resolveDiffInput({
+            flags: parsed.flags,
+            kind,
+            workspaceRoot,
+        });
+        if (kind === 'change-log') {
+            return {
+                cleanupTempDir: diffInput.cleanupTempDir,
+                record: await applyChangeLogFlagsToRecord({
+                    flags: parsed.flags,
+                    patchInput: diffInput,
+                    record,
+                }),
+                workspaceRoot,
+            };
+        }
+        const patchInput = await applyPatchInputToRecord({
+            kind,
+            patchInput: diffInput,
+            record,
+        });
+        return {
+            cleanupTempDir: patchInput.cleanupTempDir,
+            record: patchInput.record ?? record,
+            workspaceRoot,
+        };
+    }
+    catch (error) {
+        if (diffInput?.cleanupTempDir) {
+            await rm(diffInput.cleanupTempDir, { force: true, recursive: true });
+        }
+        throw error;
+    }
 };
 const buildNoteRecord = async (parsed, context) => {
     const [subkind] = parsed.positionals;
@@ -462,8 +641,10 @@ const runRenderCli = async (parsed, context) => {
     const target = parseRenderTarget(parsed.flags);
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const content = await ledger.render({
+        limit: parseLimit(parsed.flags),
         out: getFlag(parsed.flags, 'out'),
         phase: parseOptionalPhase(parsed.flags),
+        since: parseSince(parsed.flags),
         to: target,
     });
     if (!getFlag(parsed.flags, 'out')) {

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAsL1E,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO;;;EAyCzF,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AA8V1E,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO;;;EAyCzF,CAAC"}