changeledger 0.6.4 → 0.8.0

package/src/commands/context.mjs

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

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

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

package/src/contract.mjs

@@ -36,12 +36,17 @@ const LEGACY_CONTRACT_HASHES = new Set([
 
 export const REFERENCE = `${MARKER}
 > [!IMPORTANT]
-> This repo uses **ChangeLedger**. Before creating or modifying files, run
-> \`changeledger context\` directly, read its complete output, and follow it.
-> Do not pipe, filter, summarize, limit, or truncate the output before reading it.
-> If the output is truncated/incomplete, stop and restore complete context before
-> proceeding. If the command is unavailable, stop and restore/install
-> ChangeLedger; do not proceed from memory.
+> This repo uses **ChangeLedger**. Immediately after reading this file — before
+> planning, investigating, or acting — run \`changeledger context\` directly.
+> 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.
 `;
 
 export const contractLink = (changeledgerDir) => path.join(changeledgerDir, 'AGENTS.md');

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

package/src/metrics.mjs

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