changeledger 0.7.0 → 0.9.0

package/AGENTS.md

@@ -6,11 +6,17 @@ under `.changeledger/changes/`, persistent truth under `.changeledger/specs/`.
 <!-- changeledger -->
 > [!IMPORTANT]
 > 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.
+> planning, investigating, or acting — a normal agent must run `changeledger context` directly.
+> Only a delegated leaf whose prompt was emitted by `changeledger agent-prompt <role>`
+> runs `changeledger agent-context <role> [change-id]` instead; the role in the
+> prompt and command must match. No other agent may skip the core context.
+> On the first invocation, retain complete stdout through the `CHANGELEDGER CONTEXT END` line,
+> or the `CHANGELEDGER AGENT CONTEXT END` line for that delegated path:
+> 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.

package/README.md

@@ -137,11 +137,15 @@ The contract ships as task-focused fragments and is compiled on demand:
 changeledger context                    # minimal non-negotiable core
 changeledger context <change-id>        # lifecycle-aware rules + selected change
 changeledger context review             # explicit task mode
+changeledger agent-prompt <role>         # portable delegation skeleton
+changeledger agent-context <role> [id]  # self-contained context for that delegate
 ```
 
 `init` places a small fail-closed bootstrap in the project-owned `AGENTS.md`;
 there is no linked or copied contract under `.changeledger/`. Run
-`changeledger register` after upgrading to refresh that bootstrap.
+`changeledger register` after upgrading to refresh that bootstrap. Normal agents
+load `context`; a delegated leaf identified by `agent-prompt` loads only its
+matching `agent-context`, without the orchestrator core.
 
 ### Upgrading an existing repo's configuration
 

package/bin/changeledger.mjs

@@ -8,11 +8,15 @@ import {
   list,
   log,
   owner,
+  reopen,
   review,
   show,
   status,
   task,
+  validation,
 } from '../src/commands/agent.mjs';
+import { agentContext } from '../src/commands/agent-context.mjs';
+import { agentPrompt } from '../src/commands/agent-prompt.mjs';
 import { check } from '../src/commands/check.mjs';
 import { context } from '../src/commands/context.mjs';
 import {
@@ -27,16 +31,17 @@ 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)
 
-Run \`changeledger context\` first in any repo — it is the mandatory bootstrap.
+Run \`changeledger context\` first in any repo unless a ChangeLedger delegation
+prompt identifies your role and tells you to run \`agent-context\` instead.
 
-  changeledger init | register | new | view | check | context
+  changeledger init | register | new | view | check | context | agent-context
   changeledger status | discard | review | owner | archive | unarchive
   changeledger log | task | list | show | graduate | config | release
 
@@ -62,7 +67,7 @@ program
   .helpOption('-h, --help', 'display help for command')
   .addHelpText(
     'after',
-    '\nRun `changeledger context` first in any repo — it is the mandatory bootstrap.\n' +
+    '\nRun `changeledger context` first unless a ChangeLedger delegation prompt tells your role to use `agent-context`.\n' +
       "Run `changeledger <command> --help` for that command's syntax, values and examples.",
   );
 
@@ -179,6 +184,47 @@ program
   )
   .action(action((input) => context(input)));
 
+program
+  .command('agent-prompt')
+  .description('print a portable delegation prompt skeleton for a role')
+  .argument('<role>', 'investigation | implementation | review')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Prints a fill-in-the-blanks delegation prompt for the given role. Works',
+      'outside a ChangeLedger repo — the skeletons ship inside the package.',
+      '',
+      'Examples:',
+      '  changeledger agent-prompt investigation',
+      '  changeledger agent-prompt implementation',
+      '  changeledger agent-prompt review',
+    ].join('\n'),
+  )
+  .action(action((role) => agentPrompt(role)));
+
+program
+  .command('agent-context')
+  .description('print a self-contained minimal context for a delegated role')
+  .argument('<role>', 'investigation | implementation | review')
+  .argument('[change-id]', 'optional for investigation; required for implementation and review')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Use only when a delegation prompt emitted by `changeledger agent-prompt`',
+      'identifies you as that role. This replaces the normal core bootstrap for',
+      'the delegated leaf; normal agents still run `changeledger context` first.',
+      '',
+      'Examples:',
+      '  changeledger agent-context investigation',
+      '  changeledger agent-context investigation <id>',
+      '  changeledger agent-context implementation <id>',
+      '  changeledger agent-context review <id>',
+    ].join('\n'),
+  )
+  .action(action((role, changeId) => agentContext(role, changeId)));
+
 program
   .command('status')
   .description("move a change's lifecycle status (agent-owned, non-terminal moves only)")
@@ -192,7 +238,7 @@ program
     [
       '',
       'Terminal moves are not accepted here: use `changeledger discard <id> "<reason>"`',
-      'to discard, and human validation in the viewer to reach done.',
+      'to discard. Only human validation in the viewer can reach done.',
       '',
       'Examples:',
       '  changeledger status <id> in-progress',
@@ -201,11 +247,41 @@ program
   )
   .action(
     action((id, st) => {
-      status(id, st);
+      status(id, st, process.cwd(), { actor: 'agent' });
       console.log(`#${id} → ${st}`);
     }),
   );
 
+program
+  .command('validation')
+  .description('reject an in-validation change; accepting it remains human-only')
+  .argument('<id>')
+  .argument('<verdict>', 'fail')
+  .argument('<reason...>')
+  .action(
+    action((id, verdict, reasonParts) => {
+      if (verdict !== 'fail')
+        throw new Error(
+          'validation only accepts fail; human validation in the viewer accepts changes',
+        );
+      const reason = reasonParts.join(' ').trim();
+      validation(id, 'fail', { reason, actor: 'agent' });
+      console.log(`#${id} validation fail`);
+    }),
+  );
+
+program
+  .command('reopen')
+  .description('reopen a provisional done change with a reason')
+  .argument('<id>')
+  .argument('<reason...>')
+  .action(
+    action((id, reasonParts) => {
+      reopen(id, reasonParts.join(' ').trim(), process.cwd(), { actor: 'agent' });
+      console.log(`#${id} → in-progress`);
+    }),
+  );
+
 program
   .command('discard')
   .description('discard a change (terminal; keeps the record and reason)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changeledger",
-  "version": "0.7.0",
+  "version": "0.9.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 { parseChange } from './change.mjs';
 import { CANONICAL_STATUSES, canTransition, parseLogEvent } from './lifecycle.mjs';
 import { compareVersions, parseVersion, RELEASE_IMPACTS } from './release.mjs';
 
@@ -82,7 +83,7 @@ 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 [!]');
@@ -131,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();

package/src/commands/agent-context.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseChange } from '../change.mjs';
+import { findChangeledgerDir, loadConfig } from '../config.mjs';
+import { beginSentinel, endSentinel, VERSION } from '../framing.mjs';
+import { contractTemplatesDir } from '../paths.mjs';
+import { resolveChange } from '../repo.mjs';
+import { transversalPolicy } from './context.mjs';
+
+const ROLES = ['investigation', 'implementation', 'review'];
+const ALLOWED_STATUSES = {
+  implementation: ['approved', 'in-progress'],
+  review: ['in-review'],
+};
+
+function requireRepo(cwd) {
+  const dir = findChangeledgerDir(cwd);
+  if (!dir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+  return dir;
+}
+
+function capsule(role) {
+  return fs
+    .readFileSync(path.join(contractTemplatesDir, 'agent-contexts', `${role}.md`), 'utf8')
+    .trim();
+}
+
+function selectedChange(role, changeId, cwd) {
+  if (role !== 'investigation' && !changeId) {
+    throw new Error(`role ${role} requires a change id`);
+  }
+  if (!changeId) return undefined;
+
+  const resolved = resolveChange(cwd, changeId);
+  const text = fs.readFileSync(resolved.file, 'utf8');
+  const { id, status } = parseChange(text).frontmatter;
+  const allowed = ALLOWED_STATUSES[role];
+  if (allowed && !allowed.includes(status)) {
+    const expected = allowed.join(' or ');
+    throw new Error(`role ${role} requires change status ${expected}; got ${status}`);
+  }
+  return { id, text };
+}
+
+export function buildAgentContext(role, changeId, cwd = process.cwd()) {
+  if (!ROLES.includes(role)) {
+    throw new Error(`Unknown role "${role}" — valid roles: ${ROLES.join(', ')}`);
+  }
+  const changeledgerDir = requireRepo(cwd);
+  const selected = selectedChange(role, changeId, cwd);
+  const change = selected ? ` — change: #${selected.id}` : '';
+  const sections = [
+    beginSentinel('AGENT CONTEXT', `role: ${role}${change} — v${VERSION}`),
+    transversalPolicy(loadConfig(changeledgerDir)),
+    capsule(role),
+  ];
+  if (selected) sections.push('---\n\n# Selected change', selected.text.trim());
+  sections.push(endSentinel('AGENT CONTEXT'));
+  return `${sections.join('\n\n')}\n`;
+}
+
+export function agentContext(role, changeId, cwd = process.cwd(), output = console.log) {
+  output(buildAgentContext(role, changeId, cwd).trimEnd());
+}

package/src/commands/agent-prompt.mjs

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { beginSentinel, endSentinel, VERSION } from '../framing.mjs';
+import { contractTemplatesDir } from '../paths.mjs';
+
+// Portable role skeletons ship inside the package, so this command works even
+// outside an initialized ChangeLedger repo — it never reads project config.
+const ROLES = ['investigation', 'implementation', 'review'];
+
+export function buildAgentPrompt(role) {
+  if (!ROLES.includes(role)) {
+    throw new Error(`Unknown role "${role}" — valid roles: ${ROLES.join(', ')}`);
+  }
+  const file = path.join(contractTemplatesDir, 'agent-prompts', `${role}.md`);
+  const body = fs.readFileSync(file, 'utf8').trim();
+  const begin = beginSentinel('AGENT PROMPT', `role: ${role} — v${VERSION}`);
+  return `${begin}\n\n${body}\n\n${endSentinel('AGENT PROMPT')}\n`;
+}
+
+export function agentPrompt(role, output = console.log) {
+  output(buildAgentPrompt(role).trimEnd());
+}

package/src/commands/agent.mjs

@@ -2,25 +2,28 @@
 // (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(
   id,
   newStatus,
   cwd = process.cwd(),
-  { ownerHandle = defaultOwnerHandle } = {},
+  { ownerHandle = defaultOwnerHandle, actor = 'human' } = {},
 ) {
   const { config, file } = locate(cwd, id);
   if (newStatus === 'discarded') {
@@ -31,12 +34,18 @@ export function status(
   if (newStatus === 'done') {
     throw new Error('to complete a change use human validation in the viewer');
   }
+  if (newStatus === 'approved' && actor !== 'human') {
+    throw new Error('only the human-facing viewer can approve a draft change');
+  }
   if (!(config.statuses ?? []).includes(newStatus)) {
     throw new Error(`Invalid status "${newStatus}". Valid: ${(config.statuses ?? []).join(', ')}`);
   }
   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('to reopen a done change use `changeledger reopen <id> "<reason>"`');
+    }
     // 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.
@@ -104,7 +113,7 @@ export function review(id, verdict, { mode, reason } = {}, cwd = process.cwd())
 
 // Records the human verdict for the complete change. This is intentionally
 // separate from `status`: only the human-facing viewer may close a change.
-export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
+export function validation(id, verdict, { reason, actor = 'human' } = {}, cwd = process.cwd()) {
   const { config, file } = locate(cwd, id);
   mutateFileAtomic(file, (text) => {
     const fm = parseChange(text).frontmatter;
@@ -126,17 +135,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}`,
+        : `validation → in-progress (${actor} rejected): ${reason}`,
     );
+    if (verdict === 'pass') assertChangeTextValid(config, path.basename(file), text);
+    return text;
   });
   return file;
 }
 
+// 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(), { actor = 'human' } = {}) {
+  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 (${actor} reopened): ${reason}`);
+    });
+    return file;
+  });
+}
+
 // name '-' clears the owner.
 export function owner(id, name, cwd = process.cwd()) {
   const { file } = locate(cwd, id);

package/src/commands/context.mjs

@@ -2,12 +2,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseChange } from '../change.mjs';
 import { findChangeledgerDir, loadConfig } from '../config.mjs';
-import { contractTemplatesDir, packageRoot } from '../paths.mjs';
+import { beginSentinel, endSentinel, VERSION } from '../framing.mjs';
+import { contractTemplatesDir } 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 END_DELIMITER = endSentinel('CONTEXT');
 const MODES = ['implement', 'review', 'spec', 'release'];
 const MODE_CONTEXT = {
   implement: ['implement', 'delegation', 'handoff'],
@@ -26,7 +25,7 @@ const STATUS_CONTEXT = {
   discarded: { mode: 'discarded', fragments: ['discarded'] },
 };
 const INCREMENTAL_NOTICE = `This incremental context extends the complete core context already read.
-If you have not read the core output through its \`CHANGELEDGER CONTEXT END\` line, stop and run \`changeledger context\` directly before proceeding.`;
+Its one-pass full-capture rule applies here; a partial view is invalid.`;
 
 function fragment(name) {
   return fs.readFileSync(path.join(contractTemplatesDir, `${name}.md`), 'utf8').trim();
@@ -34,7 +33,7 @@ function fragment(name) {
 
 function beginDelimiter(mode, changeId) {
   const change = changeId ? ` — change: #${changeId}` : '';
-  return `===== CHANGELEDGER CONTEXT BEGIN — mode: ${mode}${change} — v${VERSION} =====`;
+  return beginSentinel('CONTEXT', `mode: ${mode}${change} — v${VERSION}`);
 }
 
 // Resolved defaults so an agent never reads `.changeledger/config.yml` raw to
@@ -54,7 +53,7 @@ function effectiveTdd(config) {
 
 // The transversal policy line every composition anchors on: effective language
 // and tdd with defaults already resolved.
-function transversalPolicy(config) {
+export function transversalPolicy(config) {
   return `Effective policy: language=${effectiveLanguage(config)} — tdd=${effectiveTdd(config)}`;
 }
 
@@ -73,7 +72,7 @@ function changePolicyBlock(config, type) {
 
 // One line per local dependency (id, title, status); external `project:id`
 // references stay references, never pretending local resolution.
-function dependencyBlock(config, repoRoot, dependsOn, cwd) {
+function dependencyBlock(dependsOn, cwd) {
   if (!Array.isArray(dependsOn) || dependsOn.length === 0) return undefined;
   const lines = dependsOn.map((raw) => {
     const dep = String(raw);
@@ -140,7 +139,7 @@ export function buildContext(input, cwd = process.cwd()) {
     changeText: text,
     changeId: id,
     policy: changePolicyBlock(config, type),
-    dependencies: dependencyBlock(config, resolved.repoRoot, dependsOn, cwd),
+    dependencies: dependencyBlock(dependsOn, cwd),
   });
 }
 

package/src/commands/graduate.mjs

@@ -6,6 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { mutateFileAtomic, writeFileAtomic } from '../atomic-write.mjs';
 import { parseChange } from '../change.mjs';
+import { assertChangeTextValid } from '../check.mjs';
 import { findChangeledgerDir, loadConfig, resolveRepoPath, resolveSpecsDir } from '../config.mjs';
 import { nowUtc } from '../paths.mjs';
 import { resolveChange } from '../repo.mjs';
@@ -30,11 +31,23 @@ function requireDone(changeText) {
   return change;
 }
 
+function requireGraduationReady(config, changeFile, changeText) {
+  const change = requireDone(changeText);
+  assertChangeTextValid(config, path.basename(changeFile), changeText);
+  return change;
+}
+
 export function scaffoldSpec(id, slug, cwd = process.cwd()) {
-  const { file: changeFile, specsDir, specName, specFile } = graduationTarget(id, slug, cwd);
+  const {
+    config,
+    file: changeFile,
+    specsDir,
+    specName,
+    specFile,
+  } = graduationTarget(id, slug, cwd);
+  const change = requireGraduationReady(config, changeFile, fs.readFileSync(changeFile, 'utf8'));
   if (fs.existsSync(specFile)) throw new Error(`Spec "${specName}" already exists`);
 
-  const change = requireDone(fs.readFileSync(changeFile, 'utf8'));
   const seedStage =
     change.stages.find((stage) => stage.key === 'specification') ??
     change.stages.find((stage) => stage.key === 'proposal');
@@ -65,14 +78,15 @@ 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);
+  const { config, file: changeFile, specName, specFile } = graduationTarget(id, slug, cwd);
+  requireGraduationReady(config, changeFile, fs.readFileSync(changeFile, 'utf8'));
 
   if (!fs.existsSync(specFile)) {
     throw new Error(`Spec "${specName}" does not exist — use --new to create a scaffold`);
   }
 
   mutateFileAtomic(changeFile, (changeText) => {
-    requireDone(changeText);
+    requireGraduationReady(config, changeFile, changeText);
     const specText = fs.readFileSync(specFile, 'utf8');
     if (specText.includes(SPEC_SCAFFOLD_MARKER)) {
       throw new Error(
@@ -91,12 +105,10 @@ export function graduate(id, slug, cwd = process.cwd(), { into = false } = {}) {
 // Marks a done change's graduation as reviewed without creating a spec (e.g. a
 // bug/chore with no persistent truth). Records the reason in the Log.
 export function skipGraduation(id, reason, cwd = process.cwd()) {
-  const { file: changeFile } = resolveChange(cwd, id);
+  const { config, file: changeFile } = resolveChange(cwd, id);
   const message = reason ? `graduation skipped: ${reason}` : 'graduation skipped';
   mutateFileAtomic(changeFile, (text) => {
-    const change = parseChange(text);
-    if (change.frontmatter.status !== 'done')
-      throw new Error('only done changes can be graduated/skipped');
+    requireGraduationReady(config, changeFile, text);
 
     text = appendLog(text, nowUtc(), message);
     return setReviewed(text, true);

package/src/commands/view.mjs

@@ -41,7 +41,11 @@ function parseViewArgs(args) {
   return { localOnly, port };
 }
 
-export async function view(args = [], cwd = process.cwd()) {
+export async function view(
+  args = [],
+  cwd = process.cwd(),
+  { openBrowser: shouldOpen = true } = {},
+) {
   const { localOnly, port: requestedPort } = parseViewArgs(args);
   resolveProjects(cwd, localOnly); // fail fast if local mode outside a repo
 
@@ -54,7 +58,7 @@ export async function view(args = [], cwd = process.cwd()) {
   const port = await listen(server, host, requestedPort);
   const url = `http://${host}:${port}`;
   console.log(`ChangeLedger viewer → ${url}  (Ctrl+C to stop)`);
-  openBrowser(url);
+  if (shouldOpen) openBrowser(url);
   return server;
 }
 

package/src/contract.mjs

@@ -37,11 +37,17 @@ const LEGACY_CONTRACT_HASHES = new Set([
 export const REFERENCE = `${MARKER}
 > [!IMPORTANT]
 > 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.
+> planning, investigating, or acting — a normal agent must run \`changeledger context\` directly.
+> Only a delegated leaf whose prompt was emitted by \`changeledger agent-prompt <role>\`
+> runs \`changeledger agent-context <role> [change-id]\` instead; the role in the
+> prompt and command must match. No other agent may skip the core context.
+> On the first invocation, retain complete stdout through the \`CHANGELEDGER CONTEXT END\` line,
+> or the \`CHANGELEDGER AGENT CONTEXT END\` line for that delegated path:
+> 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.

package/src/framing.mjs

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { packageRoot } from './paths.mjs';
+
+// Single source of the installed version and the anti-truncation sentinels, so
+// `context`, `agent-prompt` and `agent-context` share framing and never diverge
+// through independent copies.
+export const VERSION = JSON.parse(
+  fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
+).version;
+
+const TRUNCATION_SUFFIX = 'if this line is missing, the output was truncated: stop and re-run';
+
+// `kind` names the payload (e.g. "CONTEXT", "AGENT PROMPT"); `meta` is the
+// already-formatted descriptor (e.g. "mode: implement — v0.8.0").
+export function beginSentinel(kind, meta) {
+  return `===== CHANGELEDGER ${kind} BEGIN — ${meta} =====`;
+}
+
+export function endSentinel(kind) {
+  return `===== CHANGELEDGER ${kind} END — ${TRUNCATION_SUFFIX} =====`;
+}