changeledger 0.6.3 → 0.7.0

package/AGENTS.md

@@ -5,12 +5,15 @@ 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 and
+> read its complete output through the `CHANGELEDGER CONTEXT END` line. If that
+> line is missing, the output was truncated: stop and re-run the command
+> directly, without pipes or filters. 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 +28,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/README.md

@@ -96,9 +96,11 @@ changeledger discard <id> <reason>
 ### Preserve completed truth
 
 ```sh
-changeledger graduate <id> <spec-slug>           # create a persistent spec
-changeledger graduate <id> <spec-slug> --into    # update an existing spec's provenance
+changeledger graduate <id> <spec-slug> --new     # create a marked scaffold; remains pending
+# refine the scaffold and remove its marker
+changeledger graduate <id> <spec-slug> --into    # finalize an existing refined spec
 changeledger graduate <id> --skip [reason]       # record that no spec is needed
+changeledger graduate --pending                  # list unresolved graduation decisions
 changeledger archive --graduated [--dry-run]     # hide resolved changes from the board
 ```
 

package/bin/changeledger.mjs

@@ -15,7 +15,12 @@ import {
 } from '../src/commands/agent.mjs';
 import { check } from '../src/commands/check.mjs';
 import { context } from '../src/commands/context.mjs';
-import { graduate, pendingGraduation, skipGraduation } from '../src/commands/graduate.mjs';
+import {
+  graduate,
+  pendingGraduation,
+  scaffoldSpec,
+  skipGraduation,
+} from '../src/commands/graduate.mjs';
 import { init } from '../src/commands/init.mjs';
 import { newChange } from '../src/commands/new.mjs';
 import { registerRepo } from '../src/commands/register.mjs';
@@ -29,31 +34,13 @@ 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>   graduate a change to a new spec
-  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();
 
@@ -73,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')
@@ -98,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();
@@ -112,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
@@ -134,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);
@@ -192,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);
@@ -203,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) {
@@ -252,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);
@@ -265,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 });
@@ -298,7 +395,8 @@ program
   .argument('[change-id]')
   .argument('[spec-slug]')
   .argument('[reason...]')
-  .option('--into', 'graduate into an existing spec')
+  .option('--new', 'create a spec scaffold without resolving graduation')
+  .option('--into', 'finalize graduation into an existing refined spec')
   .option('--skip', 'mark graduation reviewed without a spec')
   .option('--pending', 'list done changes not yet reviewed')
   .addHelpText(
@@ -306,7 +404,7 @@ program
     [
       '',
       'Examples:',
-      '  changeledger graduate <change-id> <spec-slug>',
+      '  changeledger graduate <change-id> <spec-slug> --new',
       '  changeledger graduate <change-id> <spec-slug> --into',
       '  changeledger graduate <change-id> --skip [reason]',
       '  changeledger graduate --pending',
@@ -314,7 +412,15 @@ program
   )
   .action(
     action((id, slug, reasonParts, options) => {
+      const modeCount = [options.new, options.into, options.skip, options.pending].filter(
+        Boolean,
+      ).length;
+      const modeUsage =
+        'Usage: changeledger graduate requires exactly one mode: --new, --into, --skip, or --pending';
+      if (modeCount !== 1) throw new Error(modeUsage);
+
       if (options.pending) {
+        if (id || slug || reasonParts.length) throw new Error(modeUsage);
         const items = pendingGraduation();
         if (!items.length) console.log('No changes pending graduation.');
         for (const c of items) console.log(`#${c.id}  ${c.title}`);
@@ -327,7 +433,15 @@ program
         console.log(`#${id} graduation skipped`);
         return;
       }
-      if (!id || !slug) throw new Error('Usage: changeledger graduate <change-id> <spec-slug>');
+
+      if (!id || !slug || reasonParts.length) throw new Error(modeUsage);
+      if (options.new) {
+        const file = scaffoldSpec(id, slug);
+        console.log(
+          `Created spec scaffold ${file}. Refine it, then run: changeledger graduate ${id} ${slug} --into`,
+        );
+        return;
+      }
       const file = graduate(id, slug, process.cwd(), { into: options.into });
       console.log(`Graduated #${id} → ${file}`);
     }),

package/package.json

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

package/src/check.mjs

@@ -1,6 +1,7 @@
 // Pure validator: takes a loaded repo ({ config, changes }) and returns
 // { errors, warnings }. No IO — the `changeledger check` command does the IO and printing.
 
+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'];
@@ -88,6 +89,7 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
     }
 
     checkCoverage(c, fm, active, config, warn, err);
+    checkLifecycleSequence(c, fm, err);
   }
 
   // Aggregate checks only make sense over the whole repo.
@@ -288,10 +290,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/context.mjs

@@ -1,14 +1,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseChange } from '../change.mjs';
-import { findChangeledgerDir } from '../config.mjs';
-import { contractTemplatesDir } from '../paths.mjs';
+import { findChangeledgerDir, loadConfig } from '../config.mjs';
+import { contractTemplatesDir, packageRoot } from '../paths.mjs';
 import { resolveChange } from '../repo.mjs';
 
+const VERSION = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
+const END_DELIMITER =
+  '===== CHANGELEDGER CONTEXT END — if this line is missing, the output was truncated: stop and re-run =====';
 const MODES = ['implement', 'review', 'spec', 'release'];
 const MODE_CONTEXT = {
-  implement: ['implement', 'delegation', 'readiness', 'handoff'],
-  review: ['review', 'delegation', 'handoff'],
+  implement: ['implement', 'delegation', 'handoff'],
+  review: ['review', 'handoff'],
   spec: ['spec', 'delegation', 'readiness'],
   release: ['release'],
 };
@@ -23,30 +26,102 @@ const STATUS_CONTEXT = {
   discarded: { mode: 'discarded', fragments: ['discarded'] },
 };
 const INCREMENTAL_NOTICE = `This incremental context extends the complete core context already read.
-If the complete base output has not been read, stop and run \`changeledger context\` directly before proceeding.`;
+If you have not read the core output through its \`CHANGELEDGER CONTEXT END\` line, stop and run \`changeledger context\` directly before proceeding.`;
 
 function fragment(name) {
   return fs.readFileSync(path.join(contractTemplatesDir, `${name}.md`), 'utf8').trim();
 }
 
-function compose(mode, fragments, changeText, incremental = true) {
-  const sections = [`Mode: ${mode}`];
+function beginDelimiter(mode, changeId) {
+  const change = changeId ? ` — change: #${changeId}` : '';
+  return `===== CHANGELEDGER CONTEXT BEGIN — mode: ${mode}${change} — v${VERSION} =====`;
+}
+
+// Resolved defaults so an agent never reads `.changeledger/config.yml` raw to
+// discover the repo's effective policy. Keep these aligned with the shipped
+// template config and the Definition of Ready contract.
+const DEFAULT_LANGUAGE = 'en';
+const DEFAULT_TDD = true;
+
+function effectiveLanguage(config) {
+  return config?.language ?? DEFAULT_LANGUAGE;
+}
+
+function effectiveTdd(config) {
+  const value = config?.tdd ?? DEFAULT_TDD;
+  return value ? 'on' : 'off';
+}
+
+// The transversal policy line every composition anchors on: effective language
+// and tdd with defaults already resolved.
+function transversalPolicy(config) {
+  return `Effective policy: language=${effectiveLanguage(config)} — tdd=${effectiveTdd(config)}`;
+}
+
+// Type-specific policy for change-id contexts: adds review requirement and the
+// active stages the type actually uses, so the agent does not infer them.
+function changePolicyBlock(config, type) {
+  const typeConfig = config?.types?.[type] ?? {};
+  const reviewRequired = typeConfig.review_required === true ? 'yes' : 'no';
+  const stages = Array.isArray(typeConfig.stages) ? typeConfig.stages.join(', ') : '';
+  const lines = [
+    `${transversalPolicy(config)} — review_required(${type})=${reviewRequired}`,
+    `Active stages(${type})=${stages}`,
+  ];
+  return lines.join('\n');
+}
+
+// One line per local dependency (id, title, status); external `project:id`
+// references stay references, never pretending local resolution.
+function dependencyBlock(config, repoRoot, dependsOn, cwd) {
+  if (!Array.isArray(dependsOn) || dependsOn.length === 0) return undefined;
+  const lines = dependsOn.map((raw) => {
+    const dep = String(raw);
+    if (dep.includes(':')) return `- #${dep} — external reference (not resolved locally)`;
+    try {
+      const resolved = resolveChange(cwd, dep);
+      const { frontmatter } = parseChange(fs.readFileSync(resolved.file, 'utf8'));
+      return `- #${dep} — ${frontmatter.title} — ${frontmatter.status}`;
+    } catch {
+      return `- #${dep} — unresolved local dependency`;
+    }
+  });
+  return `## Dependencies\n\n${lines.join('\n')}`;
+}
+
+function compose(mode, fragments, options = {}) {
+  const {
+    changeText,
+    incremental = true,
+    changeId = undefined,
+    policy = undefined,
+    dependencies = undefined,
+  } = options;
+  const sections = [beginDelimiter(mode, changeId)];
   if (incremental) sections.push(INCREMENTAL_NOTICE);
+  if (policy) sections.push(policy);
   sections.push(...fragments.map(fragment));
+  if (dependencies) sections.push(dependencies);
   if (changeText) sections.push('---\n\n# Selected change\n', changeText.trim());
+  sections.push(END_DELIMITER);
   return `${sections.join('\n\n')}\n`;
 }
 
 function requireRepo(cwd) {
-  if (!findChangeledgerDir(cwd)) {
-    throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
-  }
+  const dir = findChangeledgerDir(cwd);
+  if (!dir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+  return dir;
 }
 
 export function buildContext(input, cwd = process.cwd()) {
-  requireRepo(cwd);
-  if (!input) return compose('core', ['core'], undefined, false);
-  if (MODES.includes(input)) return compose(input, MODE_CONTEXT[input]);
+  const changeledgerDir = requireRepo(cwd);
+  const config = loadConfig(changeledgerDir);
+  if (!input) {
+    return compose('core', ['core'], { incremental: false, policy: transversalPolicy(config) });
+  }
+  if (MODES.includes(input)) {
+    return compose(input, MODE_CONTEXT[input], { policy: transversalPolicy(config) });
+  }
 
   let resolved;
   try {
@@ -58,10 +133,15 @@ export function buildContext(input, cwd = process.cwd()) {
   }
 
   const text = fs.readFileSync(resolved.file, 'utf8');
-  const status = parseChange(text).frontmatter.status;
+  const { id, status, type, depends_on: dependsOn } = parseChange(text).frontmatter;
   const selected = STATUS_CONTEXT[status];
   if (!selected) throw new Error(`No context mapping for change status "${status}"`);
-  return compose(selected.mode, selected.fragments, text);
+  return compose(selected.mode, selected.fragments, {
+    changeText: text,
+    changeId: id,
+    policy: changePolicyBlock(config, type),
+    dependencies: dependencyBlock(config, resolved.repoRoot, dependsOn, cwd),
+  });
 }
 
 export function context(input, cwd = process.cwd(), output = console.log) {

package/src/commands/graduate.mjs

@@ -1,6 +1,6 @@
-// Graduates a change to a spec: scaffolds the spec file (frontmatter + a body
-// seeded from the change's Specification/Proposal) and links it back in the
-// change's Log. The final wording stays a manual/agent task.
+// Graduation is intentionally two-phase for a new spec. `scaffoldSpec` creates
+// an editable seed without resolving the change; `graduate --into` links only
+// after the durable wording has been reviewed.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,55 +13,73 @@ import { slugify } from '../slug.mjs';
 import { appendLog, setReviewed, setSpecUpdated } from '../writer.mjs';
 import { serializeScalar } from '../yaml.mjs';
 
-// `into: true` graduates into an EXISTING spec — it refreshes the spec's
-// `updated` and links it back, but leaves the body to the agent (who knows what
-// to refine). Without `into`, a new spec is scaffolded and an existing one is an
-// error. Both routes share the same change-side record (marker + reviewed).
-export function graduate(id, slug, cwd = process.cwd(), { into = false } = {}) {
-  const { config, repoRoot, file: changeFile } = resolveChange(cwd, id);
+const SPEC_SCAFFOLD_MARKER = '<!-- changeledger:spec-scaffold -->';
 
-  const specsDir = resolveSpecsDir(repoRoot, config);
+function graduationTarget(id, slug, cwd) {
+  const resolved = resolveChange(cwd, id);
+  const specsDir = resolveSpecsDir(resolved.repoRoot, resolved.config);
   const specName = `${slugify(slug)}.md`;
-  const specFile = path.join(specsDir, specName);
+  return { ...resolved, specsDir, specName, specFile: path.join(specsDir, specName) };
+}
 
-  // Validate preconditions before acquiring the change file lock — ensures no
-  // write happens at all when the existence check fails (CR1).
-  const exists = fs.existsSync(specFile);
-  if (into && !exists)
-    throw new Error(`Spec "${specName}" does not exist — drop --into to create it`);
-  if (!into && exists) throw new Error(`Spec "${specName}" already exists`);
+function requireDone(changeText) {
+  const change = parseChange(changeText);
+  if (change.frontmatter.status !== 'done') {
+    throw new Error('only done changes can be graduated/skipped');
+  }
+  return change;
+}
 
-  mutateFileAtomic(changeFile, (changeText) => {
-    const change = parseChange(changeText);
-    if (change.frontmatter.status !== 'done') {
-      throw new Error('only done changes can be graduated/skipped');
-    }
+export function scaffoldSpec(id, slug, cwd = process.cwd()) {
+  const { file: changeFile, specsDir, specName, specFile } = graduationTarget(id, slug, cwd);
+  if (fs.existsSync(specFile)) throw new Error(`Spec "${specName}" already exists`);
 
-    if (into) {
-      // Refresh the spec's updated; the body stays the agent's to edit.
-      writeFileAtomic(specFile, setSpecUpdated(fs.readFileSync(specFile, 'utf8'), nowUtc()));
-    } else {
-      const seedStage =
-        change.stages.find((s) => s.key === 'specification') ??
-        change.stages.find((s) => s.key === 'proposal');
-      const seed = seedStage ? seedStage.body : '';
-      const title = change.frontmatter.title;
-
-      const content = `---
-title: ${serializeScalar(title)}
+  const change = requireDone(fs.readFileSync(changeFile, 'utf8'));
+  const seedStage =
+    change.stages.find((stage) => stage.key === 'specification') ??
+    change.stages.find((stage) => stage.key === 'proposal');
+  const seed = seedStage ? seedStage.body : '';
+  const content = `---
+title: ${serializeScalar(change.frontmatter.title)}
 updated: ${nowUtc()}
 tags: [${change.frontmatter.type}]
 ---
 
-# ${title}
+# ${change.frontmatter.title}
 
-> Graduado del change ${id}.
+${SPEC_SCAFFOLD_MARKER}
+
+> Scaffold from change ${id}; replace this seed with durable current truth before --into.
 
 ${seed}
 `;
-      fs.mkdirSync(specsDir, { recursive: true });
-      writeFileAtomic(specFile, content);
+
+  fs.mkdirSync(specsDir, { recursive: true });
+  writeFileAtomic(specFile, content);
+  return specFile;
+}
+
+// Finalizes graduation into an EXISTING, manually refined spec. The command
+// refreshes `updated` and links it back, but never overwrites the body.
+export function graduate(id, slug, cwd = process.cwd(), { into = false } = {}) {
+  if (!into) {
+    throw new Error('graduation mode required: use --new, --into, or --skip');
+  }
+  const { file: changeFile, specName, specFile } = graduationTarget(id, slug, cwd);
+
+  if (!fs.existsSync(specFile)) {
+    throw new Error(`Spec "${specName}" does not exist — use --new to create a scaffold`);
+  }
+
+  mutateFileAtomic(changeFile, (changeText) => {
+    requireDone(changeText);
+    const specText = fs.readFileSync(specFile, 'utf8');
+    if (specText.includes(SPEC_SCAFFOLD_MARKER)) {
+      throw new Error(
+        `Spec "${specName}" still contains the scaffold marker — refine it and remove the marker before --into`,
+      );
     }
+    writeFileAtomic(specFile, setSpecUpdated(specText, nowUtc()));
 
     let text = appendLog(changeText, nowUtc(), `graduado a spec \`${specName}\``);
     text = setReviewed(text, true);

package/src/commands/view.mjs

@@ -21,8 +21,28 @@ export {
 } from '../viewer/domain.mjs';
 export { createRequestListener, hostnameOf, isAuthorizedWrite, isLocalHost, staticFile };
 
+// Explicit grammar: `.` selects local-only mode, a bare integer selects the
+// port (default 4040), both may combine, and anything else is rejected
+// instead of being silently ignored.
+function parseViewArgs(args) {
+  let localOnly = false;
+  let port = 4040;
+  const unknown = [];
+  for (const a of args) {
+    if (a === '.') localOnly = true;
+    else if (/^\d+$/.test(a)) port = Number(a);
+    else unknown.push(a);
+  }
+  if (unknown.length) {
+    throw new Error(
+      `Unknown argument(s) for "changeledger view": ${unknown.join(', ')} — usage: changeledger view [.] [port]`,
+    );
+  }
+  return { localOnly, port };
+}
+
 export async function view(args = [], cwd = process.cwd()) {
-  const localOnly = args.includes('.');
+  const { localOnly, port: requestedPort } = parseViewArgs(args);
   resolveProjects(cwd, localOnly); // fail fast if local mode outside a repo
 
   const token = crypto.randomBytes(16).toString('hex');
@@ -31,10 +51,11 @@ export async function view(args = [], cwd = process.cwd()) {
   server.headersTimeout = 10_000;
 
   const host = '127.0.0.1';
-  const port = await listen(server, host, Number(args.find((a) => /^\d+$/.test(a))) || 4040);
+  const port = await listen(server, host, requestedPort);
   const url = `http://${host}:${port}`;
   console.log(`ChangeLedger viewer → ${url}  (Ctrl+C to stop)`);
   openBrowser(url);
+  return server;
 }
 
 function listen(server, host, port, attempts = 10) {

package/src/contract.mjs

@@ -36,12 +36,15 @@ const LEGACY_CONTRACT_HASHES = new Set([
 
 export const REFERENCE = `${MARKER}
 > [!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 and
+> read its complete output through the \`CHANGELEDGER CONTEXT END\` line. If that
+> line is missing, the output was truncated: stop and re-run the command
+> directly, without pipes or filters. 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.
 `;
 
 export const contractLink = (changeledgerDir) => path.join(changeledgerDir, 'AGENTS.md');

package/src/lifecycle.mjs

@@ -55,3 +55,19 @@ export function assertTransition(from, to, { type, reviewRequired = false } = {}
     throw new Error(`${type} changes must be reviewed before validation — move to in-review first`);
   }
 }
+
+// A lifecycle event recorded in `## Log`. `status:` lines carry an explicit
+// origin; review/validation verdict lines imply it (the writer only emits them
+// from in-review / in-validation). Non-lifecycle entries (owner, graduation,
+// free notes) return null.
+const LOG_EVENT =
+  /\*\*([^*]+)\*\*\s*—\s*(?:status:\s*([a-z-]+)\s*→\s*([a-z-]+)|(review)\s*→\s*([a-z-]+)|(validation)\s*→\s*([a-z-]+))/;
+
+export function parseLogEvent(line) {
+  const m = line.match(LOG_EVENT);
+  if (!m) return null;
+  const at = m[1].trim();
+  if (m[2]) return { at, from: m[2], to: m[3], explicit: true };
+  if (m[4]) return { at, from: 'in-review', to: m[5], explicit: false };
+  return { at, from: 'in-validation', to: m[7], explicit: false };
+}

package/src/metrics.mjs

@@ -3,16 +3,19 @@
 // Everything is reconstructed from `created` plus the `## Log` status
 // transitions. The viewer renders the result.
 
+import { parseLogEvent } from './lifecycle.mjs';
+
 const ACTIVE = ['approved', 'in-progress', 'in-review', 'in-validation', 'blocked'];
 
 function logBody(change) {
   return (change.stages ?? []).find((s) => s.key === 'log')?.body ?? '';
 }
 
+// Same event grammar as `changeledger check`'s sequence validation — one shared
+// parser so metrics and validation cannot drift (20260630-225210 CR5).
 function logTransition(line) {
-  const m = line.match(/\*\*([^*]+)\*\*\s*—\s*(?:status:.*|review|validation)\s*→\s*([a-z-]+)\b/);
-  if (!m) return null;
-  return { at: m[1].trim(), state: m[2].trim() };
+  const event = parseLogEvent(line);
+  return event ? { at: event.at, state: event.to } : null;
 }
 
 // The moment a change reached `done`: the last lifecycle transition to done, or

package/templates/contract/close.md

@@ -1,6 +1,8 @@
 # Closing Accepted Work
 
-The human accepted this change. Resolve persistent truth before archiving.
+The human accepted this change. Resolve persistent truth before archiving. Run
+`changeledger context <id>` after acceptance even if the base context was loaded
+earlier; this lifecycle-specific close overlay is not part of the base context.
 Changes describe a journey; `.changeledger/specs/*.md` describe the current
 capability, architecture or domain truth that code reflects.
 
@@ -15,19 +17,25 @@ tags: []
 ---
 ```
 
-Choose one graduation outcome:
-
-- `changeledger graduate <id> <spec-slug>` creates a new spec seeded from the
-  change's Specification and Proposal; refine its wording manually.
-- `changeledger graduate <id> <spec-slug> --into` links an existing spec and
-  refreshes `updated` without overwriting the spec body (the agent edits the body manually).
+Choose exactly one explicit graduation mode. A positional slug without a mode
+is an error, so words such as `skip` or `skip-*` can never silently become specs.
+
+- For a new spec, run `changeledger graduate <id> <spec-slug> --new`. This creates
+  a seed from the change's Specification or Proposal but leaves graduation
+  pending. Rewrite it as concise durable current truth and remove the explicit
+  scaffold marker. Then run `changeledger graduate <id> <spec-slug> --into` to
+  finalize it. `--into` refuses an unrefined marked scaffold.
+- For an existing spec, the agent edits its body first, then runs
+  `changeledger graduate <id> <spec-slug> --into`. It refreshes `updated`, records
+  the link and does not overwrite the body.
 - `changeledger graduate <id> --skip [reason]` records that no persistent truth
   changed.
 - `changeledger graduate --pending` lists accepted changes whose decision is
   unresolved.
 
-Graduation and skip both set `reviewed: true` on the change: it means the
-persistent-truth question was settled, not necessarily that a spec was created.
+Finalization with `--into` and skip both set `reviewed: true` on the change;
+`--new` does not. The boolean means the persistent-truth question was settled,
+not necessarily that a spec was created.
 The graduation link remains derivable from the Log marker `graduado a spec`,
 which carries the spec link, rather than from the boolean flag.
 

package/templates/contract/core.md

@@ -3,14 +3,13 @@
 Documents under `.changeledger/` are the source of truth. Code is their
 reflection. Work is planned and documented before code is written.
 
-## Non-negotiable fast path
+## Read complete context before acting
 
-Running `changeledger context` is discovery, not compliance by itself. Run it
-directly, without piping, filtering, summarizing, limiting or truncating output
-before reading it. Read the complete output and follow the current mode. If the
-output is truncated or incomplete, including through tools such as `head`,
-`tail`, `sed` or `grep`, stop and restore complete context before creating or
-modifying files.
+Running `changeledger context` is discovery, not compliance by itself. Read the
+complete output through the `CHANGELEDGER CONTEXT END` line, then follow the
+current mode. If that line is missing, the output was truncated. Stop and re-run
+the command directly, without pipes or filters, before creating or modifying
+files.
 
 1. Work starts with conversation. Read-only investigation may clarify a request,
    but create no change or implementation artifact until there is enough clarity
@@ -26,8 +25,10 @@ modifying files.
 6. For types that require review, use a fresh clean-context reviewer before
    human validation.
 7. Stop at `in-validation`. The agent never accepts on the human's behalf.
-8. After human acceptance, graduate persistent truth or record an explicit skip,
-   then archive the done change.
+8. After human acceptance, reload `changeledger context <id>` for the `done`
+   change, then graduate persistent truth (a new spec is a two-step `--new`
+   then `--into`) or run `changeledger graduate <id> --skip [reason]`; archive
+   only after that decision.
 
 If no approved or in-progress change applies, do not silently edit repository
 files. Create or update a change, or ask the human whether a purely operational,
@@ -43,7 +44,8 @@ optional and preferred for error-prone operations such as timestamps, lifecycle
 transitions and task markers.
 
 Delegate only with a clear boundary and benefit. Each delegation prompt states
-ownership, expected output and integration criterion; coding agents must know
+at least ownership, expected output and integration criterion; the task context
+carries the full prompt contract. Coding agents must know
 they share the codebase and must not revert others' work. Do not over-shard or
 overlap write surfaces without an explicit integration plan. Size the model to
 the task's difficulty and risk.
@@ -80,8 +82,11 @@ later reconsideration needs a newly authorized change.
 
 Valid modes: implement, review, spec, release.
 
-Run these only after reading the complete base output. Each mode and change-id
-context extends the core context already read without repeating it.
+Escalate to a mode before acting. Before documenting, run
+`changeledger context spec`. Before executing, run `changeledger context
+implement` or `changeledger context <change-id>`. Run each only after reading
+the complete base output. Every mode and change-id context extends the core
+context already read; it never repeats it.
 
 - `changeledger context spec`: author or refine a change.
 - `changeledger context implement`: execute an approved change.
@@ -97,4 +102,5 @@ Prefer structured CLI queries before scanning files:
 - `changeledger graduate --pending`: find accepted changes whose graduation decision is unresolved.
 
 Run `changeledger help` or `changeledger <command> --help` for exact CLI syntax.
-Structure is always English; narrative content follows `.changeledger/config.yml`.
+Structure is always English. Each context delivers the effective policy that
+applies to its task, so you never read `.changeledger/config.yml` raw to operate.

package/templates/contract/readiness.md

@@ -37,6 +37,9 @@ evidence in the task instead of listing every possible manual phrase in config.
 
 `changeledger check` reports missing Given/When/Then, uncovered or unknown CRs,
 tasks without traceability and CR-bearing tasks without configured target and
-verification. Gaps are warnings in `draft` and errors in `approved` or
-`in-progress`. Truly operational `(support)` tasks are exempt; observable
+verification. Every diagnostic is a warning in `draft`. In `approved` or
+`in-progress`, readiness defects (missing Given/When/Then, unknown criterion
+references, CR-bearing tasks without target and verification) are errors, while
+coverage gaps (uncovered criteria, non-support tasks without a CR) stay
+warnings. Truly operational `(support)` tasks are exempt; observable
 implementation is not.