changeledger 0.8.0 → 0.9.0

package/AGENTS.md

@@ -6,8 +6,12 @@ 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.
-> On the first invocation, retain complete stdout through the `CHANGELEDGER CONTEXT END` line:
+> 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

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 {
@@ -34,9 +38,10 @@ 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.8.0",
+  "version": "0.9.0",
   "description": "Turn conversations into buildable changes.",
   "type": "module",
   "bin": {

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

@@ -23,7 +23,7 @@ export function status(
   id,
   newStatus,
   cwd = process.cwd(),
-  { ownerHandle = defaultOwnerHandle } = {},
+  { ownerHandle = defaultOwnerHandle, actor = 'human' } = {},
 ) {
   const { config, file } = locate(cwd, id);
   if (newStatus === 'discarded') {
@@ -34,6 +34,9 @@ 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(', ')}`);
   }
@@ -41,7 +44,7 @@ export function status(
   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');
+      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
@@ -110,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;
@@ -137,7 +140,7 @@ export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
       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;
@@ -145,9 +148,9 @@ export function validation(id, verdict, { reason } = {}, cwd = process.cwd()) {
   return file;
 }
 
-// Human-only correction path while `done` is still provisional. Graduation,
+// 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()) {
+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);
@@ -171,7 +174,7 @@ export function reopen(id, reason, cwd = process.cwd()) {
         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 appendLog(text, nowUtc(), `status: done → in-progress (${actor} reopened): ${reason}`);
     });
     return file;
   });

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'],
@@ -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)}`;
 }
 

package/src/contract.mjs

@@ -37,8 +37,12 @@ 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.
-> On the first invocation, retain complete stdout through the \`CHANGELEDGER CONTEXT END\` line:
+> 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

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} =====`;
+}

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 // The change lifecycle as an explicit, testable graph — the single authority on
 // which status moves are legal. Shared by the CLI (`changeledger status`) and the viewer
 // so both decide validity the same way. The viewer layers an extra human-only
-// policy on top (approval plus final acceptance/rejection); it never relaxes
+// policy on top (approval plus final acceptance); it never relaxes
 // this graph.
 
 export const CANONICAL_STATUSES = [
@@ -21,7 +21,7 @@ export const CANONICAL_STATUSES = [
 // `in-validation` is the universal human gate before done. Review or validation
 // may route back to in-progress, while review may also block. `discarded` is a
 // terminal tombstone reachable only before either closing gate. `done` has one
-// policy-gated human reopen edge; generic agent commands do not own it.
+// policy-gated provisional reopen edge; generic status commands do not own it.
 const TRANSITIONS = {
   draft: ['approved', 'discarded'],
   approved: ['in-progress', 'discarded'],

package/src/viewer/domain.mjs

@@ -130,7 +130,7 @@ export function changeStatus(projects, { project, id, status, reason }) {
   }
   try {
     if (current === 'draft' && status === 'approved') {
-      applyStatusCmd(id, status, proj.path);
+      applyStatusCmd(id, status, proj.path, { actor: 'human' });
     } else if (current === 'in-validation' && status === 'done') {
       applyValidation(id, 'pass', {}, proj.path);
     } else if (current === 'in-validation' && status === 'in-progress') {

package/src/viewer/public/app-state.js

@@ -7,8 +7,9 @@ const VALID_DETAIL_SIZES = new Set(['compact', 'wide', 'full']);
 let storage = null;
 
 const emptyProjectFilters = () => ({
-  type: 'all',
-  owner: 'all',
+  types: [],
+  owners: [],
+  includeUnassigned: false,
   statuses: [],
   showArchived: false,
   showDiscarded: false,
@@ -21,6 +22,9 @@ export const state = {
     text: '',
     type: 'all',
     owner: 'all',
+    types: new Set(),
+    owners: new Set(),
+    includeUnassigned: false,
     statuses: new Set(),
     showArchived: false,
     showDiscarded: false,
@@ -39,8 +43,9 @@ export const state = {
 
 function currentProjectFilters() {
   return {
-    type: state.filters.type,
-    owner: state.filters.owner,
+    types: [...state.filters.types],
+    owners: [...state.filters.owners],
+    includeUnassigned: state.filters.includeUnassigned,
     statuses: [...state.filters.statuses],
     showArchived: state.filters.showArchived,
     showDiscarded: state.filters.showDiscarded,
@@ -53,8 +58,23 @@ function saveCurrentProjectFilters() {
 
 function applyProjectFilters(id) {
   const filters = state.projectFilters[id] ?? emptyProjectFilters();
-  state.filters.type = typeof filters.type === 'string' ? filters.type : 'all';
-  state.filters.owner = typeof filters.owner === 'string' ? filters.owner : 'all';
+  state.filters.types = new Set(
+    Array.isArray(filters.types)
+      ? filters.types.filter((value) => typeof value === 'string')
+      : typeof filters.type === 'string' && filters.type !== 'all'
+        ? [filters.type]
+        : [],
+  );
+  state.filters.type = state.filters.types.size === 1 ? [...state.filters.types][0] : 'all';
+  state.filters.owners = new Set(
+    Array.isArray(filters.owners)
+      ? filters.owners.filter((value) => typeof value === 'string')
+      : typeof filters.owner === 'string' && filters.owner !== 'all'
+        ? [filters.owner]
+        : [],
+  );
+  state.filters.owner = state.filters.owners.size === 1 ? [...state.filters.owners][0] : 'all';
+  state.filters.includeUnassigned = filters.includeUnassigned === true;
   state.filters.statuses = new Set(
     Array.isArray(filters.statuses)
       ? filters.statuses.filter((value) => typeof value === 'string')
@@ -144,9 +164,13 @@ export function normalizeRepoState(repo) {
   }
   if (state.sortDir !== 1 && state.sortDir !== -1) state.sortDir = 1;
   if (!repo.types.includes(state.filters.type)) state.filters.type = 'all';
+  state.filters.types = new Set(
+    [...state.filters.types].filter((type) => repo.types.includes(type)),
+  );
   const owners = new Set(repo.changes.map((change) => change.owner).filter(Boolean));
   if (state.filters.owner !== 'all' && !owners.has(state.filters.owner))
     state.filters.owner = 'all';
+  state.filters.owners = new Set([...state.filters.owners].filter((owner) => owners.has(owner)));
   const statuses = new Set(repo.statuses);
   state.filters.statuses = new Set(
     [...state.filters.statuses].filter((status) => statuses.has(status)),
@@ -168,16 +192,48 @@ export function setTextFilter(text) {
   persistViewerState();
 }
 
+export function toggleTypeFilter(type) {
+  if (state.filters.types.has(type)) state.filters.types.delete(type);
+  else state.filters.types.add(type);
+  state.filters.type = state.filters.types.size === 1 ? [...state.filters.types][0] : 'all';
+  persistViewerState();
+}
+
 export function setTypeFilter(type) {
+  state.filters.types = new Set(type === 'all' ? [] : [type]);
   state.filters.type = type;
   persistViewerState();
 }
 
+export function toggleOwnerFilter(owner) {
+  if (state.filters.owners.has(owner)) state.filters.owners.delete(owner);
+  else state.filters.owners.add(owner);
+  state.filters.owner = state.filters.owners.size === 1 ? [...state.filters.owners][0] : 'all';
+  persistViewerState();
+}
+
 export function setOwnerFilter(owner) {
+  state.filters.owners = new Set(owner === 'all' ? [] : [owner]);
   state.filters.owner = owner;
   persistViewerState();
 }
 
+export function toggleUnassignedOwner() {
+  state.filters.includeUnassigned = !state.filters.includeUnassigned;
+  persistViewerState();
+}
+
+export function clearTypeFilters() {
+  state.filters.types.clear();
+  persistViewerState();
+}
+
+export function clearOwnerFilters() {
+  state.filters.owners.clear();
+  state.filters.includeUnassigned = false;
+  persistViewerState();
+}
+
 export function toggleStatusFilter(status) {
   if (state.filters.statuses.has(status)) state.filters.statuses.delete(status);
   else state.filters.statuses.add(status);

package/src/viewer/public/app.js

@@ -13,24 +13,27 @@ import {
   searchAllProjects,
 } from './api.js';
 import {
+  clearOwnerFilters,
   clearStatusFilters,
+  clearTypeFilters,
   initializeProjects,
   invalidateCache,
   normalizeRepoState,
   restoreViewerState,
   selectProject,
   setDetailPresentation,
-  setOwnerFilter,
   setRepo,
   setSortKey,
   setTextFilter,
-  setTypeFilter,
   setView,
   state,
   toggleGlobalMode,
+  toggleOwnerFilter,
   toggleShowArchived,
   toggleShowDiscarded,
   toggleStatusFilter,
+  toggleTypeFilter,
+  toggleUnassignedOwner,
 } from './app-state.js';
 import { cssIdent, initMermaid, makeMermaidExpandable, renderMermaid } from './security.js';
 import { boardStatuses, isVisible, passesTombstones } from './state.js';
@@ -115,27 +118,74 @@ export function showNoProjects(root = document) {
 
 // Rebuilt on each project load (types/statuses can differ per project).
 function hydrateFilters() {
-  litRender(
-    html`<option value="all">All types</option>
-      ${state.repo.types.map((t) => html`<option value=${t}>${t}</option>`)}`,
-    $('#type-filter'),
-  );
-  $('#type-filter').value = state.filters.type;
   $('#lang').textContent = state.repo.language;
-
   const owners = [...new Set(state.repo.changes.map((c) => c.owner).filter(Boolean))].sort();
-  litRender(
-    html`<option value="all">All owners</option>
-      ${owners.map((o) => html`<option value=${o}>${o}</option>`)}`,
+  renderChoiceFilter(
+    $('#type-filter'),
+    'Type',
+    state.repo.types,
+    state.filters.types,
+    toggleTypeFilter,
+    clearTypeFilters,
+  );
+  renderChoiceFilter(
     $('#owner-filter'),
+    'Owner',
+    owners,
+    state.filters.owners,
+    toggleOwnerFilter,
+    clearOwnerFilters,
+    true,
   );
-  if (state.filters.owner !== 'all' && !owners.includes(state.filters.owner)) setOwnerFilter('all');
-  $('#owner-filter').value = state.filters.owner;
-  $('#owner-filter').style.display = owners.length ? '' : 'none';
-
   renderStatusFilter();
 }
 
+export function choiceFilterSummary(label, selected, includeUnassigned = false) {
+  const count = selected.size + Number(includeUnassigned);
+  if (count === 1 && includeUnassigned) return 'Unassigned';
+  return count
+    ? count === 1
+      ? [...selected][0]
+      : `${count} selected`
+    : `All ${label.toLowerCase()}s`;
+}
+
+function renderChoiceFilter(host, label, choices, selected, toggle, clear, owners = false) {
+  const summary = choiceFilterSummary(label, selected, owners && state.filters.includeUnassigned);
+  litRender(
+    html`<details class="filter-menu">
+      <summary class="filter-trigger">
+        <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 3.25h12M4.25 8h7.5M6.5 12.75h3"></path></svg>
+        <span>${summary}</span>
+        <svg class="filter-chevron" viewBox="0 0 16 16" aria-hidden="true"><path d="m4.5 6.25 3.5 3.5 3.5-3.5"></path></svg>
+      </summary>
+      <div class="filter-popover">
+        <div class="filter-heading"><span>${label}</span><button type="button" data-clear>Clear</button></div>
+        <div class="filter-options">
+          ${choices.map((choice) => html`<label class="check-option"><input type="checkbox" data-choice=${choice} .checked=${selected.has(choice)} /><span class="check-box" aria-hidden="true"></span><span>${choice}</span></label>`)}
+          ${owners ? html`<label class="check-option"><input type="checkbox" data-unassigned .checked=${state.filters.includeUnassigned} /><span class="check-box" aria-hidden="true"></span><span>Unassigned</span></label>` : nothing}
+        </div>
+      </div>
+    </details>`,
+    host,
+  );
+  host.querySelectorAll('[data-choice]').forEach((input) => {
+    input.onchange = () => {
+      toggle(input.dataset.choice);
+      render();
+    };
+  });
+  if (owners)
+    host.querySelector('[data-unassigned]').onchange = () => {
+      toggleUnassignedOwner();
+      render();
+    };
+  host.querySelector('[data-clear]').onclick = () => {
+    clear();
+    render();
+  };
+}
+
 function renderStatusFilter() {
   const sf = $('#status-filter');
   litRender(
@@ -1556,16 +1606,13 @@ function bootstrap() {
     if (active) enterGlobal();
     else activateView(state.currentView);
   };
-  $('#type-filter').onchange = (e) => {
-    setTypeFilter(e.target.value);
-    render();
-  };
-  $('#owner-filter').onchange = (e) => {
-    setOwnerFilter(e.target.value);
-    render();
-  };
   document.addEventListener('pointerdown', (event) => {
-    closeStatusMenuOnOutsideClick($('#status-filter .filter-menu'), event.target);
+    closeFilterMenusOnOutsideClick(
+      ['#type-filter', '#owner-filter', '#status-filter'].map((selector) =>
+        $(`${selector} .filter-menu`),
+      ),
+      event.target,
+    );
   });
   $('#view-board').onclick = () => activateView('board');
   $('#view-table').onclick = () => activateView('table');
@@ -1594,10 +1641,12 @@ function bootstrap() {
   setInterval(load, 5000);
 }
 
-export function closeStatusMenuOnOutsideClick(menu, target) {
-  if (!menu?.open || menu.contains(target)) return false;
-  menu.open = false;
-  return true;
+export function closeFilterMenusOnOutsideClick(menus, target) {
+  return menus.reduce((closed, menu) => {
+    if (!menu?.open || menu.contains(target)) return closed;
+    menu.open = false;
+    return true;
+  }, false);
 }
 
 // Only a real browser page with the app shell bootstraps; importing the module

package/src/viewer/public/index.html

@@ -26,8 +26,8 @@
       <select id="project" class="filter" title="Project"></select>
       <input id="search" class="search" type="search" placeholder="Search anything…" />
       <button type="button" id="toggle-global" class="chip" title="Search across all projects">Global</button>
-      <select id="type-filter" class="filter"></select>
-      <select id="owner-filter" class="filter"></select>
+      <div id="type-filter"></div>
+      <div id="owner-filter"></div>
       <div id="status-filter"></div>
       <div class="spacer"></div>
       <div class="tabs">

package/src/viewer/public/state.js

@@ -22,8 +22,12 @@ function haystack(c) {
 // predicate so the rule is testable.
 export function isVisible(c, f) {
   if (!passesTombstones(c, f)) return false;
-  if (f.type !== 'all' && c.type !== f.type) return false;
-  if (f.owner !== 'all' && c.owner !== f.owner) return false;
+  const types = f.types ?? new Set(f.type && f.type !== 'all' ? [f.type] : []);
+  const owners = f.owners ?? new Set(f.owner && f.owner !== 'all' ? [f.owner] : []);
+  if (types.size && !types.has(c.type)) return false;
+  if (owners.size || f.includeUnassigned) {
+    if (c.owner ? !owners.has(c.owner) : !f.includeUnassigned) return false;
+  }
   if (f.statuses.size && !f.statuses.has(c.status)) return false;
   const q = f.text.toLowerCase();
   if (!q) return true;

package/templates/contract/agent-contexts/implementation.md

@@ -0,0 +1,18 @@
+# Implementation Delegate
+
+This is a self-contained delegated context. It replaces the ChangeLedger core
+for this role; do not run `changeledger context` or load another ChangeLedger
+context.
+
+Implement only the bounded assignment in the delegation prompt and follow the
+selected change's Specification and Plan exactly. With `tdd=on`, write the
+failing test for each assigned criterion, make it pass, then refactor.
+
+Modify only the files assigned in the delegation prompt. You share the worktree:
+do not revert or overwrite others' work; stop and report any overlap instead of
+resolving it silently. Do not change Git state, mutate the ledger or delegate
+any part of the work. Lifecycle, tasks, Log, review and integration remain the
+orchestrator's responsibility.
+
+Return the files changed, criteria covered, tests run and their results, plus
+any overlap or uncertainty. The orchestrator integrates and records the work.

package/templates/contract/agent-contexts/investigation.md

@@ -0,0 +1,14 @@
+# Investigation Delegate
+
+This is a self-contained delegated context. It replaces the ChangeLedger core
+for this role; do not run `changeledger context` or load another ChangeLedger
+context.
+
+Answer only the investigation question and ownership boundary in the delegation
+prompt. This role is read-only: do not modify files, Git state or the ledger, and
+do not delegate any part of the work.
+
+Inspect the smallest useful surface. Return concrete findings and evidence such
+as file:line references, constraints, risks and a root-cause statement when
+applicable. State what could not be determined. Do not implement fixes or create
+ChangeLedger artifacts.

package/templates/contract/agent-contexts/review.md

@@ -0,0 +1,22 @@
+# Independent Review Delegate
+
+This is a self-contained delegated context. It replaces the ChangeLedger core
+for this role; do not run `changeledger context` or load another ChangeLedger
+context.
+
+Review with clean context and do not trust the implementer's summary. This role
+is read-only: do not modify files, Git state or the ledger, do not record the
+verdict, and do not delegate any part of the work.
+
+Inspect the selected change, every `CRn`, every Plan task, tests, the actual diff
+and absence of TODO/FIXME, dead code or unrelated residue. Confirm tasks are
+true rather than merely checked off and that implementation did not drift from
+the authorized document.
+
+Deep security, SAST and lint belong to dedicated tools. You may run them
+read-only and report their evidence; ChangeLedger does not reimplement them.
+
+Return per-criterion PASS/FAIL evidence and one recommended outcome: pass,
+fail-retry with a reason for a fixable defect inside scope, or fail-block with a
+reason when correction needs scope or product judgment. The orchestrator alone
+records the verdict.

package/templates/contract/agent-prompts/implementation.md

@@ -0,0 +1,38 @@
+# Delegation skeleton — role: implementation
+
+Fill every `{{placeholder}}` before handing this prompt to the subagent. Delete
+guidance in parentheses. The delegate writes code within a bounded ownership; the
+orchestrator keeps the ledger and integration.
+
+---
+
+You are an IMPLEMENTATION delegate. Do not delegate any part of this to another
+agent; execute it yourself.
+
+Why this is delegated: {{reason}} (why a separate agent, e.g. a disjoint write
+set that parallelizes safely, a sufficient cheaper model for well-specified
+execution).
+
+Your prompt identifies you as a ChangeLedger delegate. As your only ChangeLedger
+load, run `changeledger agent-context implementation {{change_id}}` and read it
+through its END sentinel; do not load the orchestrator core. It supplies the
+selected change with its acceptance criteria and Plan.
+
+Files you own: {{files}} (the only paths you may modify).
+
+Boundaries — expressed by effect, not by tool name: modify only the files under
+your ownership above; do not revert or overwrite anyone else's work; if you find
+your change overlaps another change's surface, stop and report it instead of
+resolving it silently. Do not mutate the ledger — status, task, log, review and
+graduation transitions are the orchestrator's; you implement and report.
+
+Expected output: {{expected_output}} (the code plus the tests that prove the
+cited criteria, red-green; state which criteria you covered).
+
+Difficulty or risk that set the model choice: {{difficulty_or_risk}}.
+
+Return to the orchestrator only what changed and how it was verified — the files
+touched, the tests run and their result, and any overlap you hit.
+
+Integration criterion: {{integration}} (how the orchestrator merges/verifies your
+work, e.g. it re-runs the full gate and records the ledger transitions).

package/templates/contract/agent-prompts/investigation.md

@@ -0,0 +1,41 @@
+# Delegation skeleton — role: investigation
+
+Fill every `{{placeholder}}` before handing this prompt to the subagent. Delete
+guidance in parentheses. This is a read-only inquiry: the delegate answers a
+question, it does not change anything.
+
+---
+
+You are an INVESTIGATION delegate. Do not delegate any part of this to another
+agent; execute it yourself.
+
+Why this is delegated: {{reason}} (why a separate agent, e.g. protect main
+context, parallelize an independent question, bring a stronger model to hard
+analysis).
+
+Question you own: {{question}} (the single question or area to investigate;
+state it concretely).
+
+Your prompt identifies you as a ChangeLedger delegate. As your only ChangeLedger
+load, run `changeledger agent-context investigation {{change_id}}` and read it
+through its END sentinel; do not load the orchestrator core. There may be no
+change yet: work without a change id. If the optional id below is empty, omit it
+from the command.
+
+Optional selected change: {{change_id}} (leave empty when investigating before a
+change exists).
+
+Boundaries — expressed by effect, not by tool name: do not modify any file, do
+not change Git state, and do not mutate the ledger (no status, task, log, review
+or graduation). Inspect and read only.
+
+Expected output: {{expected_output}} (what the answer must contain, e.g. a
+file:line map, a root-cause statement, a constraints/risks list).
+
+Difficulty or risk that set the model choice: {{difficulty_or_risk}}.
+
+Return to the orchestrator only findings/data — no narrative, no fixes. State
+clearly what you could not determine.
+
+Integration criterion: {{integration}} (how the orchestrator will use the answer,
+e.g. it feeds the Investigation stage of the change).

package/templates/contract/agent-prompts/review.md

@@ -0,0 +1,36 @@
+# Delegation skeleton — role: review
+
+Fill every `{{placeholder}}` before handing this prompt to the subagent. Delete
+guidance in parentheses. The reviewer is a fresh, clean-context, read-only check;
+the orchestrator alone records the verdict.
+
+---
+
+You are an INDEPENDENT REVIEW delegate with clean context. Do not delegate any
+part of this to another agent; execute it yourself.
+
+Why this is delegated: {{reason}} (independence is a correctness requirement, not
+an optimization — a fresh reviewer that does not trust the implementer's summary).
+
+Your prompt identifies you as a ChangeLedger delegate. As your only ChangeLedger
+load, run `changeledger agent-context review {{change_id}}` and read it through
+its END sentinel; do not load the orchestrator core. Use the inspection
+checklist that agent-context gives you.
+
+Change under review: {{change_id}}.
+
+Boundaries — expressed by effect, not by tool name: do not modify any file, do
+not change Git state, and do not mutate the ledger. You inspect and report only;
+you never record the verdict — the orchestrator does that.
+
+Expected output: {{expected_output}} (per-criterion PASS/FAIL with concrete
+evidence, plus any drift or residue found).
+
+Difficulty or risk that set the model choice: {{difficulty_or_risk}}.
+
+Return to the orchestrator a single recommended verdict — one of pass, fail-retry
+with a reason, or fail-block with a reason — with the evidence behind it. The
+orchestrator records it.
+
+Integration criterion: {{integration}} (how the orchestrator acts on the verdict,
+e.g. it records pass and moves the change to in-validation).

package/templates/contract/budgets.yml

@@ -0,0 +1,16 @@
+{
+  "base": {
+    "core": { "target": { "lines": 125, "bytes": 7500 }, "hard": { "lines": 140, "bytes": 9000 } },
+    "spec": { "target": { "lines": 280, "bytes": 12000 }, "hard": { "lines": 310, "bytes": 13500 } },
+    "implement": { "target": { "lines": 185, "bytes": 8500 }, "hard": { "lines": 205, "bytes": 10000 } },
+    "review": { "target": { "lines": 70, "bytes": 3500 }, "hard": { "lines": 85, "bytes": 4500 } },
+    "release": { "target": { "lines": 45, "bytes": 2500 }, "hard": { "lines": 60, "bytes": 3500 } }
+  },
+  "agent": { "target": { "lines": 45, "bytes": 2000 }, "hard": { "lines": 60, "bytes": 3000 } }
+  ,"overlays": {
+    "blocked": { "target": { "lines": 70, "bytes": 3000 }, "hard": { "lines": 84, "bytes": 3600 } },
+    "in-validation": { "target": { "lines": 45, "bytes": 1700 }, "hard": { "lines": 54, "bytes": 2040 } },
+    "done": { "target": { "lines": 90, "bytes": 3500 }, "hard": { "lines": 108, "bytes": 4200 } },
+    "discarded": { "target": { "lines": 40, "bytes": 1300 }, "hard": { "lines": 48, "bytes": 1560 } }
+  }
+}

package/templates/contract/close.md

@@ -20,24 +20,29 @@ tags: []
 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
+For a new spec, follow this ordered recipe — `--new` alone does not finish it:
+
+1. `changeledger graduate <id> <spec-slug> --new` creates a seed from the
+   change's Specification or Proposal but leaves graduation pending; it does not
+   set `reviewed: true`.
+2. Rewrite the seed as concise durable current truth and remove the explicit
+   scaffold marker.
+3. `changeledger graduate <id> <spec-slug> --into` finalizes it; `--into`
+   refuses an unrefined marked scaffold and sets `reviewed: true`.
+
+Alternatives to the two-step:
+
+- For an existing spec, edit its body first, then run
   `changeledger graduate <id> <spec-slug> --into`. It refreshes `updated`, records
-  the link and does not overwrite the body.
+  the link, does not overwrite the body and sets `reviewed: true`.
 - `changeledger graduate <id> --skip [reason]` records that no persistent truth
-  changed.
+  changed and sets `reviewed: true`.
 - `changeledger graduate --pending` lists accepted changes whose decision is
   unresolved.
 
-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.
+`reviewed: true` 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 flag.
 
 After `--into` or `--skip`, create one final closure commit that coalesces any
 pending `in-review → in-validation → done` ledger updates with the graduation

package/templates/contract/core.md

@@ -29,11 +29,11 @@ change-id context required by a real task or lifecycle transition.
 5. Keep lifecycle, tasks, ownership and Log current while working.
 6. For types that require review, use a fresh clean-context reviewer before
    human validation.
-7. `in-validation` stops only that change; the agent never accepts on the human's behalf, but may start another approved change unless it or its `depends_on` chain (direct or transitive) reaches an `in-validation` change.
+7. `in-validation` stops only that change; the agent never accepts on the human's behalf, but may reject with a reason and start another approved change unless its `depends_on` chain (direct or transitive) reaches an `in-validation` 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.
+   change, then graduate persistent truth or run `changeledger graduate <id>
+   --skip [reason]`; archive only after that decision. The close overlay owns
+   the full graduation recipe.
 
 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,
@@ -48,42 +48,43 @@ Files are the source of truth and may be edited directly. CLI helpers are
 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
-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.
+Delegate only with a clear boundary and benefit. Each delegation prompt states at least
+ownership, expected output and integration criterion; the task context carries the full
+prompt contract. Get a complete role skeleton to fill in with `changeledger agent-prompt
+<role>` (investigation | implementation | review). 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.
 
 ## Lifecycle
 
-```text
-draft → approved → in-progress
-in-progress → in-review → in-validation → done   [review required]
-in-progress → in-validation → done               [no review required]
-in-review → in-progress                           [review retry]
-in-review → blocked → in-progress                 [review escalation]
-in-validation → in-progress                       [human rejection]
-done → in-progress                                [human reopen before durable closure]
-(draft | approved | in-progress | blocked) → discarded
-```
-
 - `draft`: documentation awaiting human approval; no implementation.
 - `approved`: ready to start after the Git/worktree checks.
 - `in-progress`: implementation underway.
 - `in-review`: independent review required.
-- `in-validation`: stop and wait for human acceptance or rejection.
+- `in-validation`: stop for human acceptance or a reasoned rejection.
 - `blocked`: an impediment or decision needs resolution.
 - `done`: the human accepted the complete result; provisional until durable closure.
 - `discarded`: terminal tombstone; never reopen it.
 
-`changeledger status <id> <status>` enforces agent-owned transitions and does not accept `done` or `discarded`.
-The viewer owns `draft → approved` and `in-validation → done|in-progress`, plus
-eligible `done → in-progress` with a reason; the agent performs other moves. Use
-`changeledger discard <id> "<reason>"`: the discard reason is required and
-logged, and dependencies remain resolvable. `discarded` never reopens. A `done`
-change can reopen only to finish its original scope before graduation/skip,
-archive or release; after durable closure, later work needs a new change.
+Who owns each transition and how it is performed:
+
+| Transition | Owner | Mechanism |
+|---|---|---|
+| draft → approved | human | viewer |
+| approved → in-progress; blocked → in-progress; in-progress → in-review | agent | `changeledger status` |
+| in-progress → in-validation (no review) | agent | `changeledger status` |
+| in-review → in-validation | orchestrator | `changeledger review <id> pass` |
+| in-review → in-progress | orchestrator | `changeledger review <id> fail --retry` |
+| in-review → blocked | orchestrator | `changeledger review <id> fail --block` |
+| in-validation → done | human | viewer |
+| in-validation → in-progress | agent or human | `changeledger validation <id> fail "<reason>"` or viewer |
+| done → in-progress (pending closure) | agent or human | `changeledger reopen <id> "<reason>"` or viewer |
+| draft/approved/in-progress/blocked → discarded | agent (authorized) | `changeledger discard <id> "<reason>"` |
+
+`changeledger status <id> <status>` performs the agent-owned moves and does not accept `approved`, `done`, `discarded` or reopening.
+The discard reason is required and logged, and dependencies remain resolvable; `discarded` never reopens.
+A `done` change can reopen only to finish its original scope before graduation/skip, archive or release;
+after durable closure, later work needs a new change.
 
 ## Context modes
 

package/templates/contract/implement.md

@@ -54,13 +54,15 @@ Useful mutation commands:
 - `changeledger review <id> pass|fail`
 - `changeledger check [id]`
 
-When implementation and every task are complete, move to `in-review` if the
-type requires independent review, loading `changeledger context review`
-once first — it stays valid for the rest of the cycle, do not reload it just
-to record the verdict unless context was lost (compaction, a new session) —
-and recording the delegate's verdict yourself with `review <id> pass|fail`
-(never `log`+`status`). Otherwise move to `in-validation` and stop — its
-closing has no CLI, only the human does it.
+When implementation and every task are complete, move to `in-review` if the type
+requires independent review by running this ordered gate — do not reconstruct it from memory:
+1. Confirm every Plan task is complete and its verification passes.
+2. `changeledger status <id> in-review`.
+3. Load `changeledger context review` once; do not reload it to record the verdict unless context was lost (compaction, a new session).
+4. Delegate to a fresh, read-only reviewer with clean context; it reports but never records the verdict itself.
+5. Record the delegate's verdict yourself with `changeledger review <id> pass|fail` — never `log`+`status`.
+
+`in-validation`: human accepts; agent rejects with `changeledger validation <id> fail "<reason>"`.
 
 ## Correction isolation
 
@@ -71,7 +73,7 @@ worktree is its isolation boundary. After `pass`, commit the confirmed correctio
 tests and ledger before human validation; this is meaningful correction evidence,
 not a status-only commit.
 
-After human rejection (`in-validation → in-progress`), run
+After a rejection (`in-validation → in-progress`), run
 `changeledger context <id>` before modifying implementation; keep the correction
 uncommitted until the human confirms it fixes the reported failure. Do not start
 another task or change while a correction waits; iterate on

package/templates/contract/review.md

@@ -2,17 +2,15 @@
 
 Review-required work must be checked by a fresh subagent with clean context and
 a model sized to the review difficulty. Independence is correctness, not an
-optimization; do not trust the implementer's summary.
+optimization.
 
-Inspect the selected change, every `CRn`, every Plan task, tests, the actual diff
-and absence of TODO/FIXME, dead code or unrelated residue. Confirm tasks are
-true rather than merely checked off and that implementation did not drift from
-the approved document.
+Get the bounded prompt with `changeledger agent-prompt review`; the delegate
+then loads `changeledger agent-context review <id>`. That self-contained capsule
+owns the inspection checklist, read-only boundary and evidence contract. Do not
+copy its checklist into this orchestrator context.
 
-Deep security, SAST and lint belong to dedicated tools. The reviewer may run
-them and record their evidence; ChangeLedger does not reimplement them.
-
-Record exactly one verdict:
+The orchestrator records exactly one verdict; the read-only reviewer reports its
+finding but never runs the verdict command:
 
 - `changeledger review <id> pass` — criteria and Plan pass; move to
   `in-validation`.

package/templates/contract/validation.md

@@ -13,7 +13,7 @@ Acceptance reaches `done`. Rejection requires a reason and returns the same
 change to `in-progress`; run `changeledger context <id>` before modifying
 implementation, update Specification/Plan as needed and repeat review when
 configured. The agent never accepts on the human's behalf. Before graduation,
-skip, archive or release, the human may reopen `done` with a reason only to
+skip, archive or release, agent/human may reopen `done` with reason only to
 complete the original authorized scope; broader behavior needs a new change.
 `discarded` never reopens.