changeledger 0.6.4 → 0.8.0

package/AGENTS.md

@@ -5,12 +5,17 @@ under `.changeledger/changes/`, persistent truth under `.changeledger/specs/`.
 
 <!-- changeledger -->
 > [!IMPORTANT]
-> This repo uses **ChangeLedger**. Before creating or modifying files, run
-> `changeledger context` directly, read its complete output, and follow it.
-> Do not pipe, filter, summarize, limit, or truncate the output before reading it.
-> If the output is truncated/incomplete, stop and restore complete context before
-> proceeding. If the command is unavailable, stop and restore/install
-> ChangeLedger; do not proceed from memory.
+> This repo uses **ChangeLedger**. Immediately after reading this file — before
+> planning, investigating, or acting — run `changeledger context` directly.
+> On the first invocation, retain complete stdout through the `CHANGELEDGER CONTEXT END` line:
+> no pipes, filters, summaries, previews or voluntary output limits. If the tool
+> exposes an output budget, reserve enough for the whole response. A missing END
+> after that is exceptional recovery: stop and re-run with a larger capture. If
+> the command is unavailable, stop and restore/install ChangeLedger; do not
+> proceed from memory.
+>
+> Do not create or modify files without an authorized change; the core context
+> defines the workflow, the task contexts, and the narrow operational exception.
 
 The canonical ChangeLedger contract is split into task-focused fragments under
 [`templates/contract/`](templates/contract/). The deterministic
@@ -25,8 +30,10 @@ bootstrap above, not a linked or copied contract.
   optional integrations.
 - Managed with **pnpm**; lint/format via **Biome**. Runtime dependencies are
   allowed only when they are mature and justified: the CLI uses `yaml` for
-  config/frontmatter parsing, and the viewer uses `lit-html`, `marked`,
-  `dompurify` and `mermaid` for templating, Markdown, sanitization and diagrams.
+  config/frontmatter parsing and `commander` for argument/option/subcommand
+  parsing with built-in errors and help, and the viewer uses `lit-html`,
+  `marked`, `dompurify` and `mermaid` for templating, Markdown, sanitization and
+  diagrams.
 - `pnpm verify` (lint + test + `changeledger check`) is the full quality gate. The
   versioned `hooks/pre-commit` runs `lint-staged`, `pnpm test` and `changeledger check`
   so staged formatting stays compatible with partial commits.

package/bin/changeledger.mjs

@@ -27,38 +27,20 @@ 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 { applyMigration } from '../src/config-migration.mjs';
 import { nowUtc } from '../src/paths.mjs';
 
 const { version } = createRequire(import.meta.url)('../package.json');
 
 const USAGE = `ChangeLedger (changeledger)
 
-  changeledger init                          set up .changeledger/ in the current repo (+ register it)
-  changeledger register                      refresh registration and context bootstrap
-  changeledger new <type> <slug> <title>     scaffold a new change (slug is the English filename)
-  changeledger view [port]                   launch the local viewer (default port 4040)
-  changeledger check [id] [--json]           validate the repo or one change
-  changeledger context [mode|change-id]       print deterministic task context
-  changeledger status <id> <status>          move a change's lifecycle status
-  changeledger discard <id> "<reason>"       discard a change (terminal; keeps the record)
-  changeledger review <id> pass              independent review passed → in-validation
-  changeledger review <id> fail --retry|--block "<reason>"   review failed → in-progress|blocked
-  changeledger owner <id> <name|->           set or clear a change's owner
-  changeledger archive <id> / unarchive <id>   hide/show a change in the viewer
-  changeledger archive --graduated [--dry-run] archive done changes already graduated/skipped
-  changeledger log <id> <message>            append a timestamped Log entry
-  changeledger task <id> done|block <n> [reason]   mark a Plan task
-  changeledger list [--status S] [--type T] [--json]   list changes
-  changeledger show <id> [--json]            print a change
-  changeledger graduate <change-id> <spec-slug> --new   create a spec scaffold to refine
-  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`;
+Run \`changeledger context\` first in any repo — it is the mandatory bootstrap.
+
+  changeledger init | register | new | view | check | context
+  changeledger status | discard | review | owner | archive | unarchive
+  changeledger log | task | list | show | graduate | config | release
+
+Run \`changeledger <command> --help\` for that command's syntax, values and examples.`;
 
 const program = new Command();
 
@@ -78,7 +60,11 @@ program
   .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}`);
+  .addHelpText(
+    'after',
+    '\nRun `changeledger context` first in any repo — it is the mandatory bootstrap.\n' +
+      "Run `changeledger <command> --help` for that command's syntax, values and examples.",
+  );
 
 program
   .command('init')
@@ -103,10 +89,18 @@ program
 program
   .command('new')
   .description('scaffold a new change')
-  .argument('<type>')
-  .argument('<slug>')
-  .argument('<title...>')
-  .option('--owner <name>', 'set the initial owner')
+  .argument('<type>', 'a type key configured in .changeledger/config.yml (types:)')
+  .argument('<slug>', 'English filename slug, e.g. self-describing-cli-help')
+  .argument('<title...>', 'content title, written in the repo language (config.yml: language)')
+  .option('--owner <name>', 'set the initial owner (defaults to unassigned)')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Example:',
+      '  changeledger new feature self-describing-cli-help "Self-describing CLI help"',
+    ].join('\n'),
+  )
   .action(
     action((type, slug, titleParts, options) => {
       const title = titleParts.join(' ').trim();
@@ -117,8 +111,19 @@ program
 
 program
   .command('view')
-  .description('launch the local viewer')
-  .argument('[args...]')
+  .description('launch the local viewer (all registered projects, or one repo with `.`)')
+  .argument('[args...]', 'optional "." for local-only mode and/or a port (default 4040)')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger view              # every registered project, port 4040',
+      '  changeledger view .            # only the current repo, port 4040',
+      '  changeledger view 4041         # every registered project, port 4041',
+      '  changeledger view . 4041       # only the current repo, port 4041',
+    ].join('\n'),
+  )
   .action(action((args) => view(args)));
 
 program
@@ -139,14 +144,61 @@ program
 program
   .command('context')
   .description('print deterministic task context')
-  .argument('[mode-or-change-id]')
+  .argument(
+    '[mode-or-change-id]',
+    'spec|implement|review|release, or a change id (pack inferred from its status)',
+  )
+  .addHelpText(
+    'after',
+    [
+      '',
+      'With no argument: prints the mandatory bootstrap core. Always run this first —',
+      'every mode and change id below is incremental and extends the core already read,',
+      'it never replaces it.',
+      '',
+      'Explicit modes (pass one literally):',
+      '  spec        author or refine a change',
+      '  implement   execute an approved change',
+      '  review      independently verify completed work',
+      '  release     plan portable delivery metadata',
+      '',
+      'Change id (e.g. changeledger context 20260630-225212): loads the pack inferred',
+      "from that change's current lifecycle status — you never choose this pack",
+      'yourself. Lifecycle overlays such as blocked, validation, close and discarded',
+      'are inferred the same way from the change id; they are not modes you pass',
+      'explicitly.',
+      '',
+      'Examples:',
+      '  changeledger context',
+      '  changeledger context spec',
+      '  changeledger context implement',
+      '  changeledger context review',
+      '  changeledger context release',
+      '  changeledger context 20260630-225212',
+    ].join('\n'),
+  )
   .action(action((input) => context(input)));
 
 program
   .command('status')
-  .description("move a change's lifecycle status")
+  .description("move a change's lifecycle status (agent-owned, non-terminal moves only)")
   .argument('<id>')
-  .argument('<status>')
+  .argument(
+    '<status>',
+    'a status configured in .changeledger/config.yml (statuses:), e.g. approved, in-progress, in-review, blocked',
+  )
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Terminal moves are not accepted here: use `changeledger discard <id> "<reason>"`',
+      'to discard, and human validation in the viewer to reach done.',
+      '',
+      'Examples:',
+      '  changeledger status <id> in-progress',
+      '  changeledger status <id> blocked',
+    ].join('\n'),
+  )
   .action(
     action((id, st) => {
       status(id, st);
@@ -197,7 +249,16 @@ program
   .command('owner')
   .description("set or clear a change's owner")
   .argument('<id>')
-  .argument('<name>')
+  .argument('<name>', 'owner handle, or "-" to clear it')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger owner <id> jdoe',
+      '  changeledger owner <id> -   # clears the owner',
+    ].join('\n'),
+  )
   .action(
     action((id, name) => {
       owner(id, name);
@@ -208,9 +269,19 @@ program
 program
   .command('archive')
   .description('hide a change in the viewer, or archive all graduated done changes')
-  .argument('[id]')
-  .option('--graduated', 'archive done changes already graduated or skipped')
-  .option('--dry-run', 'show what would be archived without writing')
+  .argument('[id]', 'a change id; mutually exclusive with --graduated')
+  .option('--graduated', 'archive every done change already graduated or skipped (takes no id)')
+  .option('--dry-run', 'preview --graduated without writing; requires --graduated')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger archive <id>',
+      '  changeledger archive --graduated',
+      '  changeledger archive --graduated --dry-run',
+    ].join('\n'),
+  )
   .action(
     action((id, options) => {
       if (options.graduated) {
@@ -257,8 +328,17 @@ program
   .description('mark a Plan task')
   .argument('<id>')
   .argument('<action>', 'done|block')
-  .argument('<n>')
-  .argument('[reason...]')
+  .argument('<n>', 'the Plan task index, 1-based, in document order')
+  .argument('[reason...]', 'required when action is block; ignored when action is done')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger task <id> done 1',
+      '  changeledger task <id> block 2 "waiting on design decision"',
+    ].join('\n'),
+  )
   .action(
     action((id, taskAction, nStr, reasonParts) => {
       const n = Number(nStr);
@@ -270,9 +350,21 @@ program
 program
   .command('list')
   .description('list changes')
-  .option('--status <status>', 'filter by status')
-  .option('--type <type>', 'filter by type')
+  .option(
+    '--status <status>',
+    'filter by a status configured in .changeledger/config.yml (statuses:)',
+  )
+  .option('--type <type>', 'filter by a type configured in .changeledger/config.yml (types:)')
   .option('--json', 'print JSON')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger list --status approved',
+      '  changeledger list --type feature --json',
+    ].join('\n'),
+  )
   .action(
     action((options) => {
       const items = list({ status: options.status, type: options.type });

package/package.json

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

package/src/check.mjs

@@ -1,6 +1,8 @@
 // Pure validator: takes a loaded repo ({ config, changes }) and returns
 // { errors, warnings }. No IO — the `changeledger check` command does the IO and printing.
 
+import { parseChange } from './change.mjs';
+import { CANONICAL_STATUSES, canTransition, parseLogEvent } from './lifecycle.mjs';
 import { compareVersions, parseVersion, RELEASE_IMPACTS } from './release.mjs';
 
 const REQUIRED = ['id', 'title', 'type', 'status', 'created', 'depends_on'];
@@ -81,13 +83,14 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
 
     if (fm.status === 'done' && tasks.some((t) => t.state !== 'done')) {
       const pending = tasks.filter((t) => t.state !== 'done').length;
-      warn(c, `status is "done" but ${pending} task(s) are not done`);
+      err(c, `status is "done" but ${pending} task(s) are not done`);
     }
     if (fm.status === 'blocked' && tasks.length && !tasks.some((t) => t.state === 'blocked')) {
       warn(c, 'status is "blocked" but no task is marked [!]');
     }
 
     checkCoverage(c, fm, active, config, warn, err);
+    checkLifecycleSequence(c, fm, err);
   }
 
   // Aggregate checks only make sense over the whole repo.
@@ -129,6 +132,41 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
   return { errors, warnings };
 }
 
+// Reuses the scoped validator for a selected change, optionally replacing its
+// in-memory text with a candidate that has not been written yet. Callers gate
+// mutations on errors only; warnings remain informational by contract.
+export function checkSelectedChange(repo, id, candidateText) {
+  let changes = repo.changes;
+  if (candidateText !== undefined) {
+    const index = changes.findIndex((c) => String(c.frontmatter?.id) === String(id));
+    if (index !== -1) {
+      const current = changes[index];
+      const candidate = { ...current, text: candidateText, ...parseChange(candidateText) };
+      changes = changes.with(index, candidate);
+    }
+  }
+  return checkRepo({ ...repo, changes }, { id });
+}
+
+export function assertSelectedChangeValid(repo, id, candidateText) {
+  const { errors } = checkSelectedChange(repo, id, candidateText);
+  if (!errors.length) return;
+  throw new Error(
+    `change ${id} failed scoped validation:\n${errors.map((error) => `- ${error.message}`).join('\n')}`,
+  );
+}
+
+// Validates one already-resolved file without loading or parsing siblings. This
+// is the write-gate path for operations whose scope is exactly one change.
+export function assertChangeTextValid(config, name, text) {
+  const parsed = parseChange(text);
+  const id = parsed.frontmatter.id;
+  assertSelectedChangeValid(
+    { config, changes: [{ name, text, ...parsed }], specs: [], releases: [] },
+    id,
+  );
+}
+
 function checkReleases(releases, changesById, err) {
   const seenVersions = new Set();
   const releasedChanges = new Map();
@@ -288,10 +326,73 @@ function checkConflictMarkers(c, err) {
   }
 }
 
-// Definition-of-Ready coverage: when `tdd` is on (default), a change being built
-// (approved/in-progress) whose type activates `## Specification` must map
-// criteria ↔ Plan tasks both ways. Warnings only — it nudges, never blocks.
-// It checks coverage, not whether a criterion is "test-grade" (not parseable).
+// Lifecycle history recorded under the previous contract (before
+// `in-validation` became the universal human gate) stays readable without
+// relaxing the current graph for new work (20260630-225210 CR3). Two bounded
+// allowances, both covered by fixtures mirroring real history:
+// - LEGACY_EDGES: closing/skipping edges old flows wrote literally.
+// - Gap resync: old writers did not log every early move (draft → approved,
+//   approved → in-progress). An explicit `status:` origin may fast-forward the
+//   reconstruction, but only forward and only across pre-review states —
+//   implied review/validation origins always require the exact sequence.
+const LEGACY_EDGES = new Set(['in-review→done', 'in-progress→done', 'draft→in-progress']);
+const LEGACY_RESYNC_RANK = { draft: 0, approved: 1, 'in-progress': 2 };
+const CANONICAL = new Set(CANONICAL_STATUSES);
+
+// Replays `## Log` lifecycle events from `draft` against the transition graph
+// in lifecycle.mjs. Stops at the first inconsistency to avoid cascading noise.
+// Changes using non-canonical statuses are left alone — the graph cannot
+// reason about states it does not model.
+function checkLifecycleSequence(c, fm, err) {
+  const lines = (c.text ?? '').split('\n');
+  let inLog = false;
+  let current = 'draft';
+  let events = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s/.test(line)) {
+      inLog = /^##\s+Log\s*$/.test(line);
+      continue;
+    }
+    if (!inLog) continue;
+    const event = parseLogEvent(line);
+    if (!event) continue;
+    if (!CANONICAL.has(event.from) || !CANONICAL.has(event.to)) return;
+    events += 1;
+    if (event.from !== current) {
+      const legacyGap =
+        event.explicit &&
+        LEGACY_RESYNC_RANK[current] !== undefined &&
+        LEGACY_RESYNC_RANK[event.from] !== undefined &&
+        LEGACY_RESYNC_RANK[event.from] > LEGACY_RESYNC_RANK[current];
+      if (!legacyGap) {
+        err(
+          c,
+          `Log line ${i + 1}: transition "${event.from} → ${event.to}" starts from "${event.from}" but the reconstructed status is "${current}"`,
+        );
+        return;
+      }
+      current = event.from;
+    }
+    if (!canTransition(event.from, event.to) && !LEGACY_EDGES.has(`${event.from}→${event.to}`)) {
+      err(c, `Log line ${i + 1}: invalid lifecycle transition "${event.from} → ${event.to}"`);
+      return;
+    }
+    current = event.to;
+  }
+  if (events && CANONICAL.has(fm.status) && current !== fm.status) {
+    err(c, `Log reconstructs status "${current}" but frontmatter says "${fm.status}"`);
+  }
+}
+
+// Definition-of-Ready coverage: when `tdd` is on (default), a change whose type
+// activates `## Specification` is checked in draft, approved and in-progress.
+// Draft reports everything as warnings. In approved/in-progress, readiness
+// defects (criterion missing Given/When/Then, reference to an unknown
+// criterion, CR-bearing task without target+verification) are errors, while
+// coverage gaps (uncovered criterion, non-support task without a CR) stay
+// warnings. Only the Given/When/Then structure is machine-checkable; semantic
+// test-grade quality remains the documenting agent's judgment.
 function checkCoverage(c, fm, active, config, warn, err = () => {}) {
   if (config?.tdd === false) return;
   if (!active?.includes('specification')) return;

package/src/commands/agent.mjs

@@ -2,18 +2,21 @@
 // (list/show). Files remain the source of truth; these are optional helpers
 // that inject correct timestamps/markers and validate transitions.
 
+import fs from 'node:fs';
 import path from 'node:path';
-import { mutateFileAtomic } from '../atomic-write.mjs';
+import { mutateFileAtomic, withFileLock } from '../atomic-write.mjs';
 import { parseChange } from '../change.mjs';
+import { assertChangeTextValid } from '../check.mjs';
 import { ownerHandle as defaultOwnerHandle } from '../git.mjs';
 import { assertTransition } from '../lifecycle.mjs';
 import { nowUtc } from '../paths.mjs';
+import { resolveReleasesDir } from '../release.mjs';
 import { loadRepo, resolveChange } from '../repo.mjs';
 import { appendLog, setArchived, setOwner, setStatus, setTask } from '../writer.mjs';
 
 function locate(cwd, id) {
-  const { config, file } = resolveChange(cwd, id);
-  return { config, file };
+  const { config, file, repoRoot } = resolveChange(cwd, id);
+  return { config, file, repoRoot };
 }
 
 export function status(
@@ -37,6 +40,9 @@ export function status(
   const autoOwner = newStatus === 'in-progress' ? ownerHandle(path.dirname(file)) : '';
   mutateFileAtomic(file, (text) => {
     const fm = parseChange(text).frontmatter;
+    if (fm.status === 'done' && newStatus === 'in-progress') {
+      throw new Error('only the human-facing viewer can reopen a done change');
+    }
     // Validate the move before any in-memory mutation, so an illegal transition
     // leaves the file byte-for-byte unchanged. The review gate reads review_required
     // from the change's type.
@@ -126,17 +132,51 @@ export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
       reviewRequired: Boolean(config.types?.[fm.type]?.review_required),
     });
     text = setStatus(text, target);
-    return appendLog(
+    text = appendLog(
       text,
       nowUtc(),
       verdict === 'pass'
         ? 'validation → done (human accepted)'
         : `validation → in-progress (human rejected): ${reason}`,
     );
+    if (verdict === 'pass') assertChangeTextValid(config, path.basename(file), text);
+    return text;
   });
   return file;
 }
 
+// Human-only correction path while `done` is still provisional. Graduation,
+// skip, archive and release membership are durable boundaries and fail closed.
+export function reopen(id, reason, cwd = process.cwd()) {
+  if (!String(reason ?? '').trim()) throw new Error('reopen requires a reason');
+  const { config, file, repoRoot } = locate(cwd, id);
+  const releasesDir = resolveReleasesDir(repoRoot);
+  fs.mkdirSync(releasesDir, { recursive: true });
+  return withFileLock(path.join(releasesDir, '.history'), () => {
+    const released = loadRepo(cwd).releases.some((release) =>
+      (release.changes ?? []).some((changeId) => String(changeId) === String(id)),
+    );
+    mutateFileAtomic(file, (text) => {
+      const change = { ...parseChange(text), text };
+      const fm = change.frontmatter;
+      if (fm.status !== 'done')
+        throw new Error(`reopen requires status done (current: ${fm.status})`);
+      if (fm.reviewed === true) throw new Error('cannot reopen: graduation is already reviewed');
+      if (hasGraduationResolution(change))
+        throw new Error('cannot reopen: graduation is already resolved');
+      if (fm.archived === true) throw new Error('cannot reopen: change is archived');
+      if (released) throw new Error('cannot reopen: change belongs to a recorded release');
+      assertTransition('done', 'in-progress', {
+        type: fm.type,
+        reviewRequired: Boolean(config.types?.[fm.type]?.review_required),
+      });
+      text = setStatus(text, 'in-progress');
+      return appendLog(text, nowUtc(), `status: done → in-progress (human reopened): ${reason}`);
+    });
+    return file;
+  });
+}
+
 // name '-' clears the owner.
 export function owner(id, name, cwd = process.cwd()) {
   const { file } = locate(cwd, id);