changeledger 0.7.0 → 0.8.0

package/AGENTS.md

@@ -6,11 +6,13 @@ 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 — run `changeledger context` directly.
+> On the first invocation, retain complete stdout through the `CHANGELEDGER CONTEXT END` line:
+> no pipes, filters, summaries, previews or voluntary output limits. If the tool
+> exposes an output budget, reserve enough for the whole response. A missing END
+> after that is exceptional recovery: stop and re-run with a larger capture. If
+> the command is unavailable, stop and restore/install ChangeLedger; do not
+> proceed from memory.
 >
 > Do not create or modify files without an authorized change; the core context
 > defines the workflow, the task contexts, and the narrow operational exception.

package/bin/changeledger.mjs

@@ -27,7 +27,7 @@ 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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changeledger",
-  "version": "0.7.0",
+  "version": "0.8.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.mjs

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

package/src/commands/context.mjs

@@ -26,7 +26,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();
@@ -73,7 +73,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 +140,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,13 @@ 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 — run \`changeledger context\` directly.
+> On the first invocation, retain complete stdout through the \`CHANGELEDGER CONTEXT END\` line:
+> no pipes, filters, summaries, previews or voluntary output limits. If the tool
+> exposes an output budget, reserve enough for the whole response. A missing END
+> after that is exceptional recovery: stop and re-run with a larger capture. If
+> the command is unavailable, stop and restore/install ChangeLedger; do not
+> proceed from memory.
 >
 > Do not create or modify files without an authorized change; the core context
 > defines the workflow, the task contexts, and the narrow operational exception.

package/src/lifecycle.mjs

@@ -20,7 +20,8 @@ export const CANONICAL_STATUSES = [
 // absent and therefore rejected. `in-review` is optional by type;
 // `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.
+// terminal tombstone reachable only before either closing gate. `done` has one
+// policy-gated human reopen edge; generic agent commands do not own it.
 const TRANSITIONS = {
   draft: ['approved', 'discarded'],
   approved: ['in-progress', 'discarded'],
@@ -28,7 +29,7 @@ const TRANSITIONS = {
   'in-review': ['in-validation', 'in-progress', 'blocked'],
   'in-validation': ['done', 'in-progress'],
   blocked: ['in-progress', 'discarded'],
-  done: [],
+  done: ['in-progress'],
   discarded: [],
 };
 

package/src/metrics.mjs

@@ -42,8 +42,8 @@ function transitions(change) {
   return events;
 }
 
-// Time spent in each state: [{ state, ms }]. The final state runs until `now`
-// (or until it reached `done`).
+// Time spent in each state: [{ state, ms }]. A provisional `done` interval is
+// retained in the event stream but excluded from active-state duration.
 export function statusTimeline(change, now) {
   const events = transitions(change);
   if (!events.length) return [];
@@ -53,7 +53,7 @@ export function statusTimeline(change, now) {
     const endIso = events[i + 1]?.at ?? now;
     const end = Date.parse(endIso);
     if (Number.isNaN(start) || Number.isNaN(end)) continue;
-    // `done` is terminal — there is no meaningful dwell time in it.
+    // `done` is outside active work, including a provisional interval before reopen.
     if (events[i].state === 'done') continue;
     segs.push({ state: events[i].state, ms: Math.max(0, end - start) });
   }

package/src/viewer/domain.mjs

@@ -3,8 +3,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseDocument } from 'yaml';
 import { mutateFileAtomic } from '../atomic-write.mjs';
+import { parseChange } from '../change.mjs';
 import { checkRepo } from '../check.mjs';
-import { status as applyStatusCmd, validation as applyValidation } from '../commands/agent.mjs';
+import {
+  reopen as applyReopen,
+  status as applyStatusCmd,
+  validation as applyValidation,
+} from '../commands/agent.mjs';
 import { findChangeledgerDir, loadConfig, resolveRepoPath, resolveSpecsDir } from '../config.mjs';
 import {
   buildMigration,
@@ -14,7 +19,7 @@ import {
 import { computeMetrics } from '../metrics.mjs';
 import { nowUtc } from '../paths.mjs';
 import { listProjects, remove, update } from '../registry.mjs';
-import { loadRepo, loadRepoWithConfig } from '../repo.mjs';
+import { loadRepo, loadRepoWithConfig, resolveChange } from '../repo.mjs';
 import { parseYaml } from '../yaml.mjs';
 
 // Serializes a loaded repo into the flat shape the UI consumes.
@@ -115,10 +120,12 @@ export function changeStatus(projects, { project, id, status, reason }) {
   // the UI is bypassable.
   let current;
   try {
-    const change = loadRepo(proj.path).changes.find((c) => String(c.frontmatter.id) === String(id));
-    if (!change) return { code: 404, body: { error: `no change with id "${id}"` } };
-    current = change.frontmatter.status;
+    const { file } = resolveChange(proj.path, id);
+    current = parseChange(fs.readFileSync(file, 'utf8')).frontmatter.status;
   } catch (e) {
+    if (/^No change with id /.test(e.message)) {
+      return { code: 404, body: { error: `no change with id "${id}"` } };
+    }
     return { code: 400, body: { error: e.message } };
   }
   try {
@@ -128,11 +135,14 @@ export function changeStatus(projects, { project, id, status, reason }) {
       applyValidation(id, 'pass', {}, proj.path);
     } else if (current === 'in-validation' && status === 'in-progress') {
       applyValidation(id, 'fail', { reason }, proj.path);
+    } else if (current === 'done' && status === 'in-progress') {
+      applyReopen(id, reason, proj.path);
     } else {
       return {
         code: 403,
         body: {
-          error: 'the viewer only allows draft → approved and in-validation → done|in-progress',
+          error:
+            'the viewer only allows draft → approved, in-validation → done|in-progress, and eligible done → in-progress',
         },
       };
     }

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

@@ -2,6 +2,8 @@ export const VIEWER_STATE_KEY = 'changeledger.viewer-state.v1';
 
 const VALID_VIEWS = new Set(['board', 'table', 'graph', 'specs', 'metrics', 'projects']);
 const VALID_SORT_KEYS = new Set(['id', 'title', 'type', 'status', 'progress', 'deps']);
+const VALID_DETAIL_MODES = new Set(['side', 'floating']);
+const VALID_DETAIL_SIZES = new Set(['compact', 'wide', 'full']);
 let storage = null;
 
 const emptyProjectFilters = () => ({
@@ -31,6 +33,8 @@ export const state = {
   projectsList: [],
   localOnly: false,
   globalMode: false,
+  detailMode: 'side',
+  detailSize: 'wide',
 };
 
 function currentProjectFilters() {
@@ -71,6 +75,8 @@ export function serializeViewerState() {
     sortKey: state.sortKey,
     sortDir: state.sortDir,
     projects: state.projectFilters,
+    detailMode: state.detailMode,
+    detailSize: state.detailSize,
   };
 }
 
@@ -99,6 +105,8 @@ export function restoreViewerState(storageLike) {
   if (typeof snapshot.text === 'string') state.filters.text = snapshot.text;
   if (typeof snapshot.sortKey === 'string') state.sortKey = snapshot.sortKey;
   if (snapshot.sortDir === 1 || snapshot.sortDir === -1) state.sortDir = snapshot.sortDir;
+  state.detailMode = VALID_DETAIL_MODES.has(snapshot.detailMode) ? snapshot.detailMode : 'side';
+  state.detailSize = VALID_DETAIL_SIZES.has(snapshot.detailSize) ? snapshot.detailSize : 'wide';
   if (
     snapshot.projects &&
     typeof snapshot.projects === 'object' &&
@@ -224,3 +232,10 @@ export function toggleGlobalMode() {
   persistViewerState();
   return state.globalMode;
 }
+
+export function setDetailPresentation(mode, size) {
+  if (VALID_DETAIL_MODES.has(mode)) state.detailMode = mode;
+  if (VALID_DETAIL_SIZES.has(size)) state.detailSize = size;
+  persistViewerState();
+  return { mode: state.detailMode, size: state.detailSize };
+}

package/src/viewer/public/app.js

@@ -19,6 +19,7 @@ import {
   normalizeRepoState,
   restoreViewerState,
   selectProject,
+  setDetailPresentation,
   setOwnerFilter,
   setRepo,
   setSortKey,
@@ -36,7 +37,7 @@ import { boardStatuses, isVisible, passesTombstones } from './state.js';
 import { html, render as litRender, nothing } from './templates.js';
 import {
   card,
-  closeButton,
+  detailToolbar,
   sortIndicator,
   specBody,
   stageBlock,
@@ -50,6 +51,8 @@ export { cssIdent, esc, makeMermaidExpandable, safeHtml } from './security.js';
 export { boardStatuses, isVisible, passesTombstones } from './state.js';
 export {
   card,
+  detailPresentationControls,
+  detailToolbar,
   sortIndicator,
   stageBlock,
   statusSummary,
@@ -312,6 +315,73 @@ export async function runValidationSubmission({ root, request, onSuccess }) {
   return true;
 }
 
+export function reopenPanel(status) {
+  if (status !== 'done') return nothing;
+  return html`<section class="validation-actions" aria-labelledby="reopen-title">
+    <div class="validation-copy">
+      <span class="validation-kicker">Lifecycle correction</span>
+      <h2 id="reopen-title">Reopen completed change</h2>
+      <p>Return this change to active work while preserving why its completion was reconsidered.</p>
+    </div>
+    <div class="reopen-controls">
+      <div class="rejection-field">
+        <label for="reopen-reason">Reason for reopening</label>
+        <input
+          id="reopen-reason"
+          data-reopen-reason
+          type="text"
+          placeholder="What requires more work?"
+        />
+        <p class="validation-error" role="alert" hidden></p>
+      </div>
+      <button type="button" class="button button-danger" data-reopen>Reopen change</button>
+    </div>
+  </section>`;
+}
+
+export function bindReopenAction({ root, request, onSuccess }) {
+  const button = root.querySelector('[data-reopen]');
+  if (!button) return;
+  button.onclick = async () => {
+    const input = root.querySelector('[data-reopen-reason]');
+    const reason = input?.value.trim();
+    if (!reason) {
+      showValidationError(root, 'A reopening reason is required.');
+      input?.focus();
+      return false;
+    }
+    return runValidationSubmission({
+      root,
+      request: () => request(reason),
+      onSuccess,
+    });
+  };
+}
+
+export function applyDetailPresentation(root = document) {
+  const overlay = root.querySelector('#overlay');
+  const detail = root.querySelector('#detail');
+  if (!overlay || !detail) return;
+  overlay.dataset.detailMode = state.detailMode;
+  detail.dataset.detailSize = state.detailSize;
+}
+
+export function bindDetailPresentation(root = document) {
+  root.querySelectorAll('[data-detail-setting]').forEach((button) => {
+    button.onclick = () => {
+      const setting = button.dataset.detailSetting;
+      setDetailPresentation(
+        setting === 'mode' ? button.dataset.detailValue : state.detailMode,
+        setting === 'size' ? button.dataset.detailValue : state.detailSize,
+      );
+      applyDetailPresentation(root);
+      root.querySelectorAll(`[data-detail-setting="${setting}"]`).forEach((option) => {
+        option.setAttribute('aria-pressed', String(option === button));
+      });
+    };
+  });
+}
+
 async function submitValidation(id, status, reason) {
   const root = $('#detail');
   await runValidationSubmission({
@@ -325,6 +395,28 @@ async function submitValidation(id, status, reason) {
   });
 }
 
+export function resetDetailScroll(
+  detail,
+  schedule = globalThis.requestAnimationFrame?.bind(globalThis),
+) {
+  const reset = () => {
+    detail.scrollTo?.({ top: 0, left: 0, behavior: 'instant' });
+    detail.scrollTop = 0;
+  };
+  reset();
+  schedule?.(reset);
+}
+
+export function scrollToStage(stage) {
+  stage.scrollIntoView({ behavior: 'auto', block: 'start' });
+}
+
+function renderOpenedDetail(content) {
+  const detail = $('#detail');
+  litRender(content, detail);
+  resetDetailScroll(detail);
+}
+
 function openDetail(id) {
   const c = state.repo.changes.find((x) => String(x.id) === String(id));
   if (!c) return;
@@ -334,14 +426,11 @@ function openDetail(id) {
       ? html`<span class="pill ext" data-extdep=${d} style="cursor:pointer">depends on ${d}</span>`
       : html`<span class="pill" data-dep=${d} style="cursor:pointer">depends on #${d}</span>`;
   });
-  const pipeline = c.stages.map(
-    (s) => html`<span class="stage-chip" data-go=${`stage-${s.key}`}>${s.heading}</span>`,
-  );
   const stages = c.stages.map((s) => stageBlock(c, s));
 
-  litRender(
+  renderOpenedDetail(
     html`
-    ${closeButton()}
+    ${detailToolbar(state.detailMode, state.detailSize, c.stages)}
     <h1>${c.title}</h1>
     <div class="detail-meta">
       <span class="pill">#${c.id}</span>
@@ -352,16 +441,18 @@ function openDetail(id) {
       ${deps}
     </div>
     ${c.status === 'in-validation' ? validationPanel() : nothing}
-    <div class="pipeline">${pipeline}</div>
+    ${reopenPanel(c.status)}
     ${stages}
     <div id="git-section"></div>`,
-    $('#detail'),
   );
 
   resetValidationState($('#detail'));
 
   const overlay = $('#overlay');
   overlay.classList.remove('hidden');
+  document.documentElement.classList.add('detail-open');
+  applyDetailPresentation();
+  bindDetailPresentation();
   $('#detail').querySelector('.close').onclick = closeDetail;
   const accept = $('#detail').querySelector('[data-validation="pass"]');
   if (accept) accept.onclick = () => submitValidation(c.id, 'done');
@@ -378,14 +469,22 @@ function openDetail(id) {
       submitValidation(c.id, 'in-progress', reason);
     };
   }
+  bindReopenAction({
+    root: $('#detail'),
+    request: (reason) => postStatus(state.currentProject, c.id, 'in-progress', reason),
+    onSuccess: async () => {
+      invalidateCache();
+      await load();
+      openDetail(c.id);
+    },
+  });
   overlay.onclick = (e) => {
     if (e.target === overlay) closeDetail();
   };
   $('#detail')
     .querySelectorAll('[data-go]')
     .forEach((el) => {
-      el.onclick = () =>
-        $(`#${el.dataset.go}`).scrollIntoView({ behavior: 'smooth', block: 'start' });
+      el.onclick = () => scrollToStage($(`#${el.dataset.go}`));
     });
   $('#detail')
     .querySelectorAll('[data-dep]')
@@ -441,6 +540,7 @@ async function loadGitRefs(id) {
 
 function closeDetail() {
   $('#overlay').classList.add('hidden');
+  document.documentElement.classList.remove('detail-open');
 }
 
 let diagramLightbox = null;
@@ -584,9 +684,9 @@ function renderSpecs() {
 }
 
 function openSpec(s) {
-  litRender(
+  renderOpenedDetail(
     html`
-    ${closeButton()}
+    ${detailToolbar(state.detailMode, state.detailSize)}
     <h1>${s.title}</h1>
     <div class="detail-meta">
       <span class="pill">spec</span>
@@ -594,10 +694,12 @@ function openSpec(s) {
       ${(s.tags || []).map((t) => html`<span class="pill">${t}</span>`)}
     </div>
     ${specBody(s.body)}`,
-    $('#detail'),
   );
   const overlay = $('#overlay');
   overlay.classList.remove('hidden');
+  document.documentElement.classList.add('detail-open');
+  applyDetailPresentation();
+  bindDetailPresentation();
   const detail = $('#detail');
   detail.querySelector('.close').onclick = closeDetail;
   overlay.onclick = (e) => {

package/src/viewer/public/styles.css

@@ -23,12 +23,34 @@
   --status-discarded: #9aa0aa;
   --status-muted: #8b929e;
   font-family: "Avenir Next", Avenir, ui-sans-serif, sans-serif;
+  color-scheme: dark;
 }
 
 * {
   box-sizing: border-box;
 }
 
+html,
+body {
+  scrollbar-width: thin;
+  scrollbar-color: #3a414e transparent;
+}
+html::-webkit-scrollbar,
+body::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+html::-webkit-scrollbar-track,
+body::-webkit-scrollbar-track {
+  background: transparent;
+}
+html::-webkit-scrollbar-thumb,
+body::-webkit-scrollbar-thumb {
+  background: #3a414e;
+  border: 2px solid var(--bg);
+  border-radius: 999px;
+}
+
 body {
   margin: 0;
   background: var(--bg);
@@ -527,16 +549,31 @@ body {
   padding: 16px;
   overflow-x: auto;
   align-items: flex-start;
+}
+.board,
+.detail,
+.detail pre,
+.detail table {
   scrollbar-width: thin;
   scrollbar-color: #3a414e transparent;
 }
-.board::-webkit-scrollbar {
+.board::-webkit-scrollbar,
+.detail::-webkit-scrollbar,
+.detail pre::-webkit-scrollbar,
+.detail table::-webkit-scrollbar {
+  width: 8px;
   height: 8px;
 }
-.board::-webkit-scrollbar-track {
+.board::-webkit-scrollbar-track,
+.detail::-webkit-scrollbar-track,
+.detail pre::-webkit-scrollbar-track,
+.detail table::-webkit-scrollbar-track {
   background: transparent;
 }
-.board::-webkit-scrollbar-thumb {
+.board::-webkit-scrollbar-thumb,
+.detail::-webkit-scrollbar-thumb,
+.detail pre::-webkit-scrollbar-thumb,
+.detail table::-webkit-scrollbar-thumb {
   background: #3a414e;
   border: 2px solid var(--bg);
   border-radius: 999px;
@@ -545,10 +582,10 @@ body {
   background: var(--panel);
   border: 1px solid var(--line);
   border-radius: 12px;
-  width: clamp(238px, calc((100vw - 116px) / 7), 320px);
-  min-width: 238px;
-  max-width: 320px;
-  flex: 0 0 clamp(238px, calc((100vw - 116px) / 7), 320px);
+  width: clamp(190px, calc((100vw - 140px) / 6), 400px);
+  min-width: 190px;
+  max-width: 400px;
+  flex: 0 0 clamp(190px, calc((100vw - 140px) / 6), 400px);
 }
 .column-head {
   display: flex;
@@ -593,6 +630,8 @@ body {
   font-family: ui-monospace, monospace;
   color: var(--muted);
   font-size: 12px;
+  min-width: 0;
+  overflow-wrap: anywhere;
 }
 .type-tag {
   font-size: 10px;
@@ -625,6 +664,7 @@ body {
 .card-title {
   font-weight: 600;
   line-height: 1.3;
+  overflow-wrap: anywhere;
 }
 .progress {
   margin-top: 9px;
@@ -640,6 +680,7 @@ body {
 }
 .card-meta {
   display: flex;
+  flex-wrap: wrap;
   gap: 10px;
   margin-top: 7px;
   font-size: 11px;
@@ -689,6 +730,13 @@ body {
   gap: 10px;
   margin-top: 15px;
 }
+.reopen-controls {
+  display: grid;
+  grid-template-columns: minmax(190px, 1fr) auto;
+  align-items: end;
+  gap: 10px;
+  margin-top: 15px;
+}
 .rejection-field {
   display: flex;
   flex-direction: column;
@@ -750,6 +798,7 @@ body {
 }
 .owner {
   font-weight: 600;
+  overflow-wrap: anywhere;
 }
 .card.archived {
   opacity: 0.55;
@@ -847,21 +896,107 @@ body {
 }
 
 /* Overlay + detail */
+.detail-open {
+  overflow: hidden;
+}
 .overlay {
   position: fixed;
   inset: 0;
   background: rgba(0, 0, 0, 0.55);
   display: flex;
   justify-content: flex-end;
+  align-items: stretch;
   z-index: 20;
 }
 .detail {
-  width: min(720px, 92vw);
+  --detail-width: 960px;
+  container-type: inline-size;
+  position: relative;
+  width: min(var(--detail-width), calc(100vw - 48px));
   height: 100%;
   background: var(--bg);
   border-left: 1px solid var(--line);
   overflow-y: auto;
+  overflow-anchor: none;
   padding: 22px 26px 60px;
+  box-shadow: -24px 0 70px rgba(0, 0, 0, 0.28);
+}
+.detail[data-detail-size="compact"] {
+  --detail-width: 720px;
+}
+.detail[data-detail-size="wide"] {
+  --detail-width: 960px;
+}
+.detail[data-detail-size="full"] {
+  --detail-width: 1280px;
+}
+.overlay[data-detail-mode="floating"] {
+  align-items: center;
+  justify-content: center;
+  padding: 28px;
+}
+.overlay[data-detail-mode="floating"] .detail {
+  width: min(var(--detail-width), calc(100vw - 56px));
+  height: min(92vh, calc(100vh - 56px));
+  border: 1px solid var(--line);
+  border-radius: 16px;
+  box-shadow: 0 28px 90px rgba(0, 0, 0, 0.48);
+}
+.detail-toolbar {
+  position: sticky;
+  top: -22px;
+  z-index: 3;
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 12px;
+  margin: -22px -26px 20px;
+  padding: 14px 26px 10px;
+  border-bottom: 1px solid color-mix(in srgb, var(--line) 72%, transparent);
+  background: color-mix(in srgb, var(--bg) 92%, transparent);
+  backdrop-filter: blur(14px);
+}
+.detail-presentation {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  width: fit-content;
+}
+.detail-choice {
+  display: inline-flex;
+  padding: 3px;
+  border: 1px solid var(--line);
+  border-radius: 9px;
+  background: var(--panel);
+}
+.detail-option {
+  min-height: 28px;
+  padding: 4px 9px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--muted);
+  font: inherit;
+  font-size: 11px;
+  cursor: pointer;
+}
+.detail-option[aria-pressed="true"] {
+  background: var(--panel-2);
+  color: var(--text);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--accent) 42%, var(--line));
+}
+.detail-option:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+.detail pre {
+  max-width: 100%;
+  overflow-x: auto;
+}
+.detail table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
 }
 .detail h1 {
   font-size: 22px;
@@ -909,19 +1044,27 @@ body {
   outline-offset: 3px;
 }
 .close {
-  position: absolute;
-  top: 16px;
-  right: 22px;
+  justify-self: end;
+}
+.detail-toolbar-close {
+  grid-column: 3;
 }
 
 .pipeline {
   display: flex;
-  flex-wrap: wrap;
+  min-width: 0;
+  flex-wrap: nowrap;
   gap: 6px;
-  margin: 16px 0;
+  margin: 0;
+  padding: 3px 2px;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  scrollbar-width: thin;
 }
 .stage-chip {
+  flex: 0 0 auto;
   font-size: 12px;
+  font-family: inherit;
   padding: 5px 11px;
   border-radius: 999px;
   background: var(--panel);
@@ -937,6 +1080,7 @@ body {
 .stage {
   border-top: 1px solid var(--line);
   padding-top: 14px;
+  scroll-margin-top: 72px;
   margin-top: 18px;
 }
 .stage h2 {
@@ -1235,7 +1379,8 @@ body {
     width: 100%;
     flex: 0 0 auto;
   }
-  .validation-controls {
+  .validation-controls,
+  .reopen-controls {
     grid-template-columns: 1fr;
     align-items: stretch;
   }
@@ -1255,7 +1400,32 @@ body {
   }
   .detail {
     width: 100vw;
+    max-width: none;
+    height: 100vh;
+    max-height: none;
     padding: 18px 16px 60px;
+    border: 0;
+    border-radius: 0;
+  }
+  .overlay[data-detail-mode] {
+    align-items: stretch;
+    justify-content: stretch;
+    padding: 0;
+  }
+  .overlay[data-detail-mode] .detail {
+    width: 100vw;
+    height: 100vh;
+    max-height: none;
+    border: 0;
+    border-radius: 0;
+  }
+  .detail-toolbar {
+    top: -18px;
+    margin: -18px -16px 16px;
+    padding: 10px 16px 8px;
+  }
+  .detail-option {
+    padding-inline: 7px;
   }
   .grid th,
   .grid td {
@@ -1263,6 +1433,27 @@ body {
   }
 }
 
+/* Detail toolbar stacks its stage navigation onto its own row whenever the
+   detail panel itself lacks room, independent of the surrounding viewport —
+   this also covers the "Compact" width preset, not just narrow screens. */
+@container (max-width: 680px) {
+  .detail-toolbar {
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: 8px;
+  }
+  .detail-toolbar-close {
+    grid-column: 2;
+    grid-row: 1;
+  }
+  .pipeline {
+    grid-column: 1 / -1;
+    grid-row: 2;
+  }
+  .stage {
+    scroll-margin-top: 126px;
+  }
+}
+
 /* config editor tabs and form (113924) */
 .config-section {
   border-bottom: 1px solid var(--line);

package/src/viewer/public/view-parts.js

@@ -36,6 +36,58 @@ export function closeButton(label = 'Close detail', extraClass = '') {
   </button>`;
 }
 
+export function detailPresentationControls(mode = 'side', size = 'wide') {
+  const options = (values, selected, attr) =>
+    values.map(
+      ([value, label]) => html`<button
+        type="button"
+        class="detail-option"
+        data-detail-setting=${attr}
+        data-detail-value=${value}
+        aria-pressed=${String(selected === value)}
+      >${label}</button>`,
+    );
+  return html`<div class="detail-presentation" aria-label="Detail presentation">
+    <div class="detail-choice" role="group" aria-label="Layout">
+      ${options(
+        [
+          ['side', 'Side panel'],
+          ['floating', 'Floating modal'],
+        ],
+        mode,
+        'mode',
+      )}
+    </div>
+    <div class="detail-choice" role="group" aria-label="Width">
+      ${options(
+        [
+          ['compact', 'Compact'],
+          ['wide', 'Wide'],
+          ['full', 'Full'],
+        ],
+        size,
+        'size',
+      )}
+    </div>
+  </div>`;
+}
+
+export function detailToolbar(mode = 'side', size = 'wide', stages = []) {
+  const navigation = stages.length
+    ? html`<nav class="pipeline" aria-label="Change sections">
+      ${stages.map(
+        (stage) =>
+          html`<button type="button" class="stage-chip" data-go=${`stage-${stage.key}`}>${stage.heading}</button>`,
+      )}
+    </nav>`
+    : nothing;
+  return html`<div class="detail-toolbar" aria-label="Detail tools">
+    ${detailPresentationControls(mode, size)}
+    ${navigation}
+    ${closeButton('Close detail', 'detail-toolbar-close')}
+  </div>`;
+}
+
 export function validationPanel() {
   return html`<section class="validation-actions" aria-labelledby="validation-title">
     <div class="validation-copy">

package/templates/contract/close.md

@@ -39,6 +39,12 @@ 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.
 
+After `--into` or `--skip`, create one final closure commit that coalesces any
+pending `in-review → in-validation → done` ledger updates with the graduation
+decision and durable spec edit. Do not create separate commits whose only
+content is one of those transitions. If no lifecycle state is pending, the
+graduation or skip itself remains the meaningful closure evidence.
+
 Operational inspection and visibility:
 
 - `changeledger list [--status S] [--type T] [--json]`
@@ -47,4 +53,4 @@ Operational inspection and visibility:
 
 Use Mermaid where it communicates persistent relationships better than prose.
 After closure, share a brief retrospective. New work needs a newly authorized
-change; `done` never reopens.
+change; graduated, skipped, archived or released work never reopens.

package/templates/contract/core.md

@@ -5,11 +5,16 @@ reflection. Work is planned and documented before code is written.
 
 ## Read complete context before acting
 
-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.
+Running `changeledger context` is discovery, not compliance by itself. Capture the first invocation completely in one pass
+and read through the `CHANGELEDGER CONTEXT END` line, then follow the current mode. Never request a preview, summary
+or voluntary line, byte or token cap; if the tool exposes an output budget,
+reserve enough for the whole response. A missing END after this deliberate full
+capture is exceptional recovery: stop and re-run with a larger capture before
+planning or acting on the partial output.
+
+While the complete core remains available in the active conversation, a new
+human message alone does not trigger a reload. Load only the specialized mode or
+change-id context required by a real task or lifecycle transition.
 
 1. Work starts with conversation. Read-only investigation may clarify a request,
    but create no change or implementation artifact until there is enough clarity
@@ -19,12 +24,12 @@ files.
    agent decides how to divide and execute work within that authorized scope.
 3. Capture every authorized change in `.changeledger/changes/`. The document
    wins when code and documentation disagree.
-4. Never implement a `draft`. After approval, work one change at a time on a
-   non-main branch and commit the approved change document before code.
+4. Never implement a `draft`. After approval, implement one change at a time on
+   a non-main branch and commit the approved change document before code.
 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. Stop at `in-validation`. The agent never accepts on the human's behalf.
+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.
 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
@@ -59,6 +64,7 @@ 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
 ```
 
@@ -68,15 +74,16 @@ in-validation → in-progress                       [human rejection]
 - `in-review`: independent review required.
 - `in-validation`: stop and wait for human acceptance or rejection.
 - `blocked`: an impediment or decision needs resolution.
-- `done`: terminal; the human accepted the complete result.
+- `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`; the
-agent performs the other non-terminal moves. Use
+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. `done` and `discarded` never reopen;
-later reconsideration needs a newly authorized change.
+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/delegation.md

@@ -21,7 +21,8 @@ owns, what it returns and how the result integrates.
 - Verification may be delegated when it catches risk without merely repeating
   the implementer's work.
 - Configured review is special: a fresh clean-context subagent is a correctness
-  requirement, not an optimization.
+  requirement, not an optimization — and read-only: it reports, the
+  orchestrator alone records the verdict.
 
 ## Do not over-shard
 

package/templates/contract/implement.md

@@ -17,10 +17,17 @@ to a work branch or ask the human before continuing. Inspect the worktree first.
 unrelated changes exist, do not include them silently; ask the human whether to
 stash, commit, ignore or include them before changing the worktree.
 
-Commit the approved change documentation before touching implementation code.
-Implement one change at a time. Commit a completed unit before continuing when
-another task, change or edit of the same surface could make attribution
-ambiguous; do not wait until the end to reconstruct mixed diffs.
+After `approved → in-progress`, create a baseline commit of the approved change
+document before code. Implement one change at a time, even while another
+already-delivered change waits in `in-validation`.
+
+Commit completed units with their tasks and Log when later work could obscure
+attribution. Do not create a dedicated commit for a lifecycle-only transition.
+Coalesce it with the nearest meaningful commit; for example, include
+`in-progress → in-review` with the final implementation unit. Do not wait until
+the end to reconstruct mixed diffs. If a handoff precedes the next
+meaningful commit, one consolidated checkpoint persists pending state; record
+why and never create one per transition.
 
 Commit messages use the canonical shape:
 
@@ -44,25 +51,32 @@ Useful mutation commands:
 - `changeledger task <id> done|block <n> [reason]`
 - `changeledger log <id> "<message>"`
 - `changeledger owner <id> <name|->`
+- `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; otherwise move to `in-validation` and stop.
+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.
 
 ## Correction isolation
 
 After review `fail --retry`, keep the candidate correction uncommitted while a
 fresh clean-context reviewer checks it. If it fails again, iterate on that same
 diff. Do not start another task or change while a correction waits: the
-worktree is its isolation boundary. After `pass`, commit the confirmed correction
-with its related ledger truth before asking for human validation.
+worktree is its isolation boundary. After `pass`, commit the confirmed correction,
+tests and ledger before human validation; this is meaningful correction evidence,
+not a status-only commit.
 
 After human 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
-the same diff if it does not. After human acceptance, graduate or record a skip,
-then commit the correction with its ledger truth.
+the same diff if it does not. After human acceptance, graduate or record a skip
+and include correction plus ledger in the final closure commit.
 
 These exceptions prevent false fix attempts from becoming permanent history;
 they do not relax intermediate commits for already verified units.

package/templates/contract/review.md

@@ -21,6 +21,11 @@ Record exactly one verdict:
 - `changeledger review <id> fail --block "<reason>"` — correction requires scope
   or product judgment; move to `blocked` for the human.
 
+A review verdict alone needs no commit. A pass leaves `in-validation` for
+closure unless it confirms uncommitted correction; then correction, tests and
+ledger form a commit. Retry keeps the diff isolated. Handoff may use the
+implementation contract's checkpoint.
+
 After `fail --retry`, the correction remains uncommitted until another fresh
 reviewer passes it. After the transition, run `changeledger context <id>` before
 modifying implementation. After pass, commit correction + ledger before asking

package/templates/contract/validation.md

@@ -3,8 +3,22 @@
 Implementation and required review are complete. Do not modify the result or
 mark it done. Ask the human to test the whole change in the viewer.
 
+This stop is scoped to this change: the agent may start the next approved
+change unless its `depends_on` chain, direct or transitive, reaches this or
+another `in-validation` change. If every remaining approved change is
+blocked, it stops entirely and does not invent work or touch delivered
+results.
+
 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. `done` and `discarded`
-never reopen.
+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
+complete the original authorized scope; broader behavior needs a new change.
+`discarded` never reopens.
+
+The validation transition alone does not require a dedicated commit. After
+acceptance, resolve graduation or skip first; the close overlay then requires one
+final closure commit containing the pending lifecycle Log and graduation truth.
+After rejection, follow correction isolation instead of committing an
+unconfirmed attempt.