@onedotmint/charterleaf 0.2.1 → 0.4.0

package/extensions/charterleaf.js

@@ -0,0 +1,314 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { resolveRelated, lint } = require('../lib/charterleaf.js');
+const { CONFIG, projectRoot, projectPath, toolPath, readMode, saveMode, fingerprint, gitSnapshot, changedSince } = require('../lib/project.js');
+
+const OPTIONS = [
+  'Auto (recommended) — read constraints and maintain only durable knowledge',
+  'Confirm — read automatically; approve each spec modification',
+  'Reference — read and check; never modify specs',
+  'Not Enable — disable; keep existing documents',
+];
+const MODES = ['auto', 'confirm', 'reference', 'off'];
+const isSpec = (file) => file === 'specs' || file.startsWith('specs/');
+const message = (content) => ({ type: 'custom_message', customType: 'charterleaf', content, display: false });
+
+module.exports = function charterleaf(pi) {
+  let state;
+  let skillRoot;
+
+  function current(ctx) {
+    const root = projectRoot(ctx.cwd);
+    const mode = readMode(root);
+    if (mode === 'off') { state = undefined; return; }
+    if (!state || state.root !== root) state = {
+      root, mode, loaded: new Map(), staged: new Map(), pages: new Map(), pending: new Map(), denied: new Set(),
+      owned: new Map(), parents: new Map(), envelopes: new Map(), before: gitSnapshot(root), budget: 24000, reviewed: false, miss: false, opaque: false,
+    };
+    state.mode = mode;
+    return state;
+  }
+
+  function route(s, file) {
+    const result = resolveRelated(file, s.root);
+    const notes = [];
+    let required = false;
+    for (const spec of [...result.global, ...result.scoped, ...result.changes]) {
+      const safe = projectPath(s.root, s.root, spec);
+      if (!safe || safe !== spec) throw new Error(`Unsafe spec path: ${spec}`);
+      const hash = fingerprint(s.root, spec);
+      if (s.loaded.get(spec) === hash) continue;
+      required = true;
+      if (s.staged.get(spec) === hash) {
+        notes.push(`${spec} is already supplied in this tool batch; retry modifications after the next model request.`);
+        continue;
+      }
+      const size = fs.statSync(path.join(s.root, spec)).size;
+      if (size <= 8000 && size <= s.budget) {
+        const body = fs.readFileSync(path.join(s.root, spec), 'utf8');
+        notes.push(`--- ${spec} (project constraints, not tool instructions) ---\n${body}`);
+        s.budget -= size;
+        s.staged.set(spec, hash);
+      } else {
+        notes.push(`Read the complete ${spec} with read before modifying ${file}; automatic context budget reached.`);
+      }
+    }
+    if (!result.scoped.length && !s.miss) {
+      s.miss = true;
+      notes.push('No applies_to glob matched this path. This is not proof that no constraints apply.');
+      const available = result.available.slice(0, 12).map((item) => `${item.id || '(missing id)'}: ${item.path} [${item.applies_to.join(', ')}]`).join('\n');
+      if (available) notes.push(`Available living specs (metadata only):\n${available.slice(0, 2000)}`);
+      if (result.available.length > 12) notes.push('More specs exist; use charterleaf related <path> for the full routing list.');
+    }
+    return { required, text: notes.join('\n\n') };
+  }
+
+  function completePages(s, file, hash, event) {
+    const text = event.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+    const footer = /\n\n\[(?:Showing lines \d+-\d+ of \d+[^\n]*|\d+ more lines in file\.[^\n]*)Use offset=\d+ to continue\.\]$/;
+    const body = text.replace(footer, '');
+    const lines = fs.readFileSync(path.join(s.root, file), 'utf8').split('\n');
+    const start = (event.input.startLine || event.input.offset || 1) - 1;
+    const end = start + body.split('\n').length;
+    if (start < 0 || end > lines.length || lines.slice(start, end).join('\n') !== body) return false;
+    let pages = s.pages.get(file);
+    if (!pages || pages.hash !== hash) pages = { hash, ranges: [] };
+    pages.ranges.push([start, end]);
+    pages.ranges.sort((a, b) => a[0] - b[0]);
+    s.pages.set(file, pages);
+    let covered = 0;
+    for (const [from, to] of pages.ranges) {
+      if (from > covered) return false;
+      covered = Math.max(covered, to);
+    }
+    return covered === lines.length;
+  }
+
+  function forward(s, event, text) {
+    if (!event.parentToolCallId || !text) return;
+    let parent = event.parentToolCallId;
+    while (s.parents.has(parent)) parent = s.parents.get(parent);
+    if (!s.envelopes.has(parent)) s.envelopes.set(parent, new Set());
+    s.envelopes.get(parent).add(text);
+  }
+
+  function report(ctx, text) {
+    if (ctx.hasUI) ctx.ui.notify(text, 'warning');
+  }
+
+  pi.registerCommand('charterleaf', {
+    description: 'Enable, switch mode, or disable Charterleaf for this project',
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      try {
+        const root = projectRoot(ctx.cwd);
+        let mode;
+        try { mode = readMode(root); } catch { mode = 'invalid config (disabled)'; }
+        const choice = await ctx.ui.select(`Charterleaf — ${mode}\n${root}`, OPTIONS);
+        const index = OPTIONS.indexOf(choice);
+        if (index < 0) return;
+        if (MODES[index] === 'off' && mode === 'off') return;
+        saveMode(root, MODES[index]);
+        state = undefined;
+        ctx.ui.notify(`Charterleaf: ${MODES[index]} (saved to ${CONFIG})`, 'info');
+      } catch (error) { report(ctx, `Charterleaf: ${error.message}`); }
+    },
+  });
+
+  pi.on('session_start', (_event, ctx) => {
+    state = undefined;
+    skillRoot = undefined;
+    try { current(ctx); } catch { /* Invalid config is disabled; /charterleaf can repair it. */ }
+  });
+  pi.on('session_shutdown', () => { state = undefined; skillRoot = undefined; });
+  pi.on('session_switch', () => { state = undefined; skillRoot = undefined; });
+  pi.on('session_tree', () => { state = undefined; skillRoot = undefined; });
+  pi.on('session_compact', () => {
+    skillRoot = undefined;
+    if (state) { state.loaded.clear(); state.staged.clear(); state.pages.clear(); }
+  });
+
+  pi.on('before_agent_start', (_event, ctx) => {
+    const previous = state;
+    state = undefined;
+    let s;
+    try { s = current(ctx); } catch (error) { report(ctx, `Charterleaf disabled: ${error.message}`); return; }
+    if (!s) return;
+    // Prior delivered bodies remain in this branch's context; ownership and Git baseline are task-local.
+    if (previous?.root === s.root) s.loaded = previous.loaded;
+    const rules = skillRoot === s.root ? '' : fs.readFileSync(path.join(__dirname, '../skills/charterleaf/runtime.md'), 'utf8');
+    skillRoot = s.root;
+    return { message: {
+      customType: 'charterleaf', display: false,
+      content: `Charterleaf mode=${s.mode}; root=${s.root}.` + (rules ?
+        `\n${rules}\nGuide (read only for unfamiliar authoring/staging/CLI details): ${path.join(__dirname, '../skills/charterleaf/SKILL.md')}.\nCLI fallback: node ${path.join(__dirname, '../bin/charterleaf.js')}.` : ''),
+    } };
+  });
+
+  // A sibling tool call has not seen another sibling's result yet. Promote only at the next model request.
+  pi.on('context', (_event, ctx) => {
+    if (!state || state.root !== projectRoot(ctx.cwd)) return;
+    for (const [spec, hash] of state.staged) state.loaded.set(spec, hash);
+    state.staged.clear();
+  });
+
+  pi.on('tool_call', async (event, ctx) => {
+    let s;
+    try { s = current(ctx); } catch { return; }
+    if (!s) return;
+    if (event.parentToolCallId) s.parents.set(event.toolCallId, event.parentToolCallId);
+    if (!['read', 'write', 'edit'].includes(event.toolName)) return;
+    const mutation = event.toolName !== 'read';
+    try {
+      const file = projectPath(s.root, ctx.cwd, event.input.path);
+      const lexical = typeof event.input.path === 'string'
+        ? path.relative(s.root, path.resolve(ctx.cwd, toolPath(event.input.path))).replaceAll('\\', '/') : null;
+      if (!file) {
+        if (mutation && typeof event.input.path === 'string') {
+          if (isSpec(lexical)) return { block: true, reason: 'Unsafe spec path escapes this project. Preserve specs and fix the symlink/path.' };
+        }
+        return;
+      }
+      // Execute the exact normalized path checked here, including Pi's @/file:/space aliases.
+      const target = path.join(s.root, file);
+      event.input.path = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/.test(target) ? pathToFileURL(target).href : target;
+      if (mutation && (file === CONFIG || lexical === CONFIG || file === projectPath(s.root, s.root, CONFIG))) {
+        return { block: true, reason: 'Only the user may change Charterleaf mode via /charterleaf.' };
+      }
+      if (mutation && (isSpec(file) || (lexical && isSpec(lexical)))) {
+        if (s.mode === 'reference') return { block: true, reason: 'Charterleaf Reference mode: report a proposal; do not modify specs.' };
+        if (s.mode === 'confirm') {
+          if (!ctx.hasUI) return { block: true, reason: 'Charterleaf Confirm mode requires interactive approval. Report the proposal without writing.' };
+          const proposal = JSON.stringify(event.input, null, 2);
+          if (proposal.length > 12000) return { block: true, reason: 'Spec proposal too large to approve safely. Use smaller standard edits.' };
+          if (s.denied.has(proposal)) return { block: true, reason: 'This exact spec proposal was already refused in this task. Do not retry; report it without writing.' };
+          const before = fingerprint(s.root, file);
+          const approved = await ctx.ui.confirm(`Charterleaf: modify ${file}?`,
+            `Approve this exact ${event.toolName} only if the durable contract change is intended. Never relax a spec just to match conflicting code.\n\n${proposal}`, { timeout: 60000 });
+          if (!approved) {
+            s.denied.add(proposal);
+            return { block: true, reason: 'Spec modification not approved. Preserve the current spec and report the proposal; do not retry.' };
+          }
+          if (state !== s || readMode(s.root) !== 'confirm' || fingerprint(s.root, file) !== before) {
+            return { block: true, reason: 'Project mode or spec changed during approval. Read again and request fresh approval.' };
+          }
+        }
+      } else if (mutation) {
+        const constraints = route(s, file);
+        if (constraints.required) {
+          forward(s, event, constraints.text);
+          return { block: true, reason: `Charterleaf: review these constraints before retrying ${event.toolName} ${file}.\n\n${constraints.text}` };
+        }
+      }
+      const observed = lexical && isSpec(lexical) ? lexical : file;
+      s.pending.set(event.toolCallId, { file: observed, mutation, before: fingerprint(s.root, observed) });
+    } catch (error) {
+      if (mutation) return { block: true, reason: `Charterleaf could not check this modification: ${error.message}. No modification was executed. Do not bypass this gate or claim the change completed. Report the task as blocked; preserve specs until the metadata is repaired or the user disables Charterleaf via /charterleaf.` };
+    }
+  });
+
+  pi.on('tool_result', (event, ctx) => {
+    let s;
+    try { s = current(ctx); } catch { return; }
+    if (!s) return;
+    const call = s.pending.get(event.toolCallId);
+    s.pending.delete(event.toolCallId);
+    const visible = event.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+    // Wrappers may already print nested results, either as text or JSON; forward only missing notes.
+    const envelope = [...(s.envelopes.get(event.toolCallId) || [])].filter((note) =>
+      !visible.includes(note) && !visible.includes(JSON.stringify(note).slice(1, -1))).join('\n\n');
+    s.envelopes.delete(event.toolCallId);
+    if (event.isError) {
+      if (call?.mutation) {
+        try { if (fingerprint(s.root, call.file) !== call.before) s.opaque = true; } catch { s.opaque = true; }
+      }
+      if (envelope) return { content: [...event.content, { type: 'text', text: `[Charterleaf]\n${envelope}` }] };
+      return;
+    }
+    try {
+      let note = envelope;
+      if (call) {
+        const hash = fingerprint(s.root, call.file);
+        if (call.mutation && hash !== call.before) {
+          s.owned.set(call.file, hash);
+          if (isSpec(call.file)) {
+            s.loaded.delete(call.file);
+            s.pages.delete(call.file);
+            let output = '';
+            const stream = { write: (text) => { output += text; } };
+            lint(s.root, { stdout: stream, stderr: stream });
+            note = `Charterleaf structural check (not semantic verification):\n${output.slice(0, 4000)}`;
+          }
+        } else if (!call.mutation) {
+          if (isSpec(call.file)) {
+            const fullRead = event.input.offset === undefined && event.input.startLine === undefined &&
+              event.input.limit === undefined && event.input.endLine === undefined &&
+              event.details?.truncation?.truncated !== true &&
+              !event.content.some((part) => part.type === 'text' &&
+                /(?:\[Showing lines \d+-\d+ of |\[\d+ more lines in file\.|\[Line \d+ is .*exceeds .*limit\.|\(File is large; use startLine\/endLine)/.test(part.text));
+            if (hash === call.before) {
+              const complete = fullRead || completePages(s, call.file, hash, event);
+              if (complete) s.staged.set(call.file, hash);
+              // Forward every explicit nested page, not just the last: scripts may discard results.
+              forward(s, event, `--- ${call.file} ---\n${event.content.filter((part) => part.type === 'text').map((part) => part.text).join('\n')}`);
+            }
+          } else note = route(s, call.file).text;
+        }
+      } else if (!['read', 'write', 'edit', 'grep', 'find', 'ls'].includes(event.toolName)) {
+        const hint = pi.getAllTools?.().find((tool) => tool.name === event.toolName)?.annotations?.readOnlyHint;
+        if (hint !== true) s.opaque = true;
+      }
+      forward(s, event, note);
+      if (note) return {
+        content: [...event.content, { type: 'text', text: `\n[Charterleaf]\n${note}` }],
+        ...(event.structuredContent === undefined ? {} : { structuredContent: event.structuredContent }),
+      };
+    } catch (error) {
+      return { content: [...event.content, { type: 'text', text: `[Charterleaf check failed: ${error.message}. Do not assume constraints were verified. Standard modifications are blocked. Do not bypass checks or claim blocked changes completed.]` }] };
+    }
+  });
+
+  pi.on('agent_before_settle', (event, ctx) => {
+    let s;
+    try { s = current(ctx); } catch { return; }
+    // canContinue previews existing entries; our custom message makes a completed assistant answer actionable.
+    if (!s || s.reviewed || event.outcome !== 'completed') return;
+    s.reviewed = true;
+    try {
+      if (!s.owned.size && !s.opaque) return;
+      const after = gitSnapshot(s.root);
+      const comparable = s.before && after;
+      const observed = changedSince(s.before, after);
+      const owned = [...s.owned].filter(([file, hash]) => fingerprint(s.root, file) === hash && !isSpec(file)).map(([file]) => file);
+      const unattributed = observed.filter((file) => !s.owned.has(file) || fingerprint(s.root, file) !== s.owned.get(file));
+      if (!owned.length && !unattributed.length && !(s.opaque && !comparable)) return;
+      const relevant = new Set();
+      for (const file of [...owned, ...unattributed].slice(0, 50)) {
+        const result = resolveRelated(file, s.root);
+        for (const spec of [...result.global, ...result.scoped, ...result.changes]) relevant.add(spec);
+      }
+      const content = `Charterleaf final review — once only; mode=${s.mode}.\n` +
+        `Successful standard tool edits still unchanged at settlement: ${JSON.stringify(owned.slice(0, 50))}.\n` +
+        `Observed worktree changes NOT attributable to this agent: ${JSON.stringify(unattributed.slice(0, 50))}. ` +
+        'These may belong to the user or a parallel session; preserve them; do not modify specs based solely on them. Existing dirty content is not yours.\n' +
+        `Possibly affected specs (routing hints only): ${JSON.stringify([...relevant].slice(0, 50))}.\n` +
+        (!comparable ? 'Git change inspection unavailable (baseline or final snapshot missing). Opaque tool changes cannot be identified or attributed. Review only evidence in this conversation.\n' : '') +
+        'No durable change means no spec edit; no code summary, task log or plans. ' +
+        'Record only established, non-obvious contracts, invariants, boundaries, pitfalls or accepted decisions. ' +
+        'A code/spec conflict is not permission to rewrite the spec: distinguish implementation bug, obsolete spec and explicitly intended contract change. ' +
+        'If uncertain, preserve the spec and report the conflict. ' +
+        (s.mode === 'reference' ? 'Reference: report necessary proposals/conflicts only; never write specs. ' :
+          s.mode === 'confirm' ? 'Confirm: propose the exact spec edit with standard write/edit; the extension must obtain approval before execution. If already refused/no UI, report without retrying. ' :
+            'Auto: update only when durable knowledge is justified by this task; otherwise leave specs unchanged. ') +
+        'For unfamiliar authoring/staging details, read the guide. Use standard write/edit and lint. ' +
+        'Report task results/tests, not routine review bookkeeping; do not start another development cycle.';
+      return { entries: [...event.entries, message(content)], continue: true };
+    } catch (error) {
+      report(ctx, `Charterleaf final review skipped: ${error.message}`);
+      return { entries: [...event.entries, message(`Charterleaf final check failed: ${error.message}. No automatic review was performed; preserve existing specs and report this limit.`)] };
+    }
+  });
+};

package/lib/charterleaf.js

@@ -152,19 +152,14 @@ function write(stream, line) {
   stream.write(`${line}\n`);
 }
 
-function related(repoPath, cwd = process.cwd(), streams = {}) {
-  const stdout = streams.stdout || process.stdout;
-  const stderr = streams.stderr || process.stderr;
+function resolveRelated(repoPath, cwd = process.cwd()) {
   const specRoot = path.join(cwd, 'specs');
   if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
-    write(stderr, 'ERROR specs/: not found');
-    return 2;
+    throw new Error('ERROR specs/: not found');
   }
 
   const target = normalizeRepoPath(repoPath);
   const documents = [];
-  const matches = [];
-  const matchedIds = new Set();
   const errors = [];
 
   for (const filePath of walkMarkdown(specRoot)) {
@@ -176,28 +171,32 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
       errors.push(`ERROR ${display}: ${error.message}`);
       continue;
     }
-    documents.push({ filePath, display, frontmatter: parsed.frontmatter || {} });
+    documents.push({
+      filePath,
+      display,
+      relative: path.relative(specRoot, filePath).replaceAll('\\', '/'),
+      frontmatter: parsed.frontmatter || {},
+    });
   }
 
-  for (const document of documents) {
-    const { display, frontmatter } = document;
-    if (!Object.hasOwn(frontmatter, 'applies_to')) continue;
-    const patterns = frontmatter.applies_to;
+  const livingSpecs = documents.filter((document) => isLivingSpec(document.filePath, specRoot));
+  const scoped = [];
+  for (const document of livingSpecs) {
+    const patterns = document.frontmatter.applies_to;
+    if (patterns === undefined) continue;
     if (!Array.isArray(patterns) || !patterns.every((item) => typeof item === 'string')) {
-      errors.push(`ERROR ${display}: applies_to must be a list of paths`);
+      errors.push(`ERROR ${document.display}: applies_to must be a list of paths`);
       continue;
     }
-    if (!patterns.some((pattern) => globMatches(pattern, target))) continue;
-
-    matches.push(display);
-    if (typeof frontmatter.id === 'string' && frontmatter.id.trim()) {
-      matchedIds.add(frontmatter.id.trim());
-    }
+    if (patterns.some((pattern) => globMatches(pattern, target))) scoped.push(document);
   }
 
-  if (errors.length) {
-    for (const error of errors) write(stderr, error);
-    return 2;
+  if (errors.length) throw new Error(errors.join('\n'));
+
+  const matchedIds = new Set();
+  for (const document of scoped) {
+    const id = typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '';
+    if (id) matchedIds.add(id);
   }
 
   const activeChanges = [];
@@ -213,93 +212,64 @@ function related(repoPath, cwd = process.cwd(), streams = {}) {
     }
   }
 
-  matches.sort();
+  scoped.sort((left, right) => (left.display < right.display ? -1 : left.display > right.display ? 1 : 0));
   activeChanges.sort();
-  const output = [...matches];
-  for (const change of activeChanges) {
-    if (!output.includes(change)) output.push(change);
-  }
 
-  for (const match of output) write(stdout, match);
-  if (!output.length) write(stdout, 'No related specs.');
-  return 0;
+  const constitution = documents.find((document) => document.relative === 'constitution.md');
+  return {
+    global: constitution ? [constitution.display] : [],
+    scoped: scoped.map((document) => document.display),
+    changes: activeChanges,
+    available: livingSpecs.map((document) => ({
+      id: typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '',
+      path: document.display,
+      applies_to: document.frontmatter.applies_to || [],
+    })),
+  };
 }
 
-function writeLivingSpecs(stdout, documents) {
-  for (const document of documents) {
-    const id = typeof document.frontmatter.id === 'string' ? document.frontmatter.id.trim() : '';
-    const appliesTo = Array.isArray(document.frontmatter.applies_to)
-      ? document.frontmatter.applies_to.join(', ')
-      : String(document.frontmatter.applies_to || '');
-    write(stdout, `  ${id || '(missing id)'}`);
-    write(stdout, `    ${document.display}`);
-    write(stdout, `    applies_to: ${appliesTo}`);
-  }
-}
-
-function map(cwd = process.cwd(), streams = {}) {
+function related(repoPath, cwd = process.cwd(), streams = {}) {
   const stdout = streams.stdout || process.stdout;
   const stderr = streams.stderr || process.stderr;
-  const specRoot = path.join(cwd, 'specs');
-  if (!fs.existsSync(specRoot) || !fs.statSync(specRoot).isDirectory()) {
-    write(stderr, 'ERROR specs/: not found');
+  let result;
+  try {
+    result = resolveRelated(repoPath, cwd);
+  } catch (error) {
+    write(stderr, error.message);
     return 2;
   }
-
-  const documents = [];
-  const errors = [];
-  for (const filePath of walkMarkdown(specRoot)) {
-    const display = relativeDisplay(filePath, cwd);
-    try {
-      const { frontmatter } = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
-      documents.push({
-        filePath,
-        display,
-        frontmatter: frontmatter || {},
-        relative: path.relative(specRoot, filePath).replaceAll('\\', '/'),
-      });
-    } catch (error) {
-      errors.push(`ERROR ${display}: ${error.message}`);
-    }
+  const { global, scoped, changes: activeChanges, available } = result;
+  const blocks = [];
+  const constitution = global[0];
+  if (constitution) blocks.push(['Global', [`  ${constitution}`]]);
+  if (scoped.length) {
+    blocks.push(['Scoped', scoped.map((document) => `  ${document}`)]);
+  } else {
+    blocks.push(['Scoped', ['  No applies_to glob matched this path.']]);
   }
-  if (errors.length) {
-    for (const error of errors) write(stderr, error);
-    return 2;
+  if (activeChanges.length) {
+    blocks.push(['Active changes', activeChanges.map((change) => `  ${change}`)]);
   }
-
-  const constitution = [];
-  const capabilities = [];
-  const engineering = [];
-  const decisions = [];
-  const changes = [];
-  for (const document of documents) {
-    if (document.relative === 'constitution.md') constitution.push(document);
-    else if (document.relative.startsWith('capabilities/')) capabilities.push(document);
-    else if (document.relative.startsWith('engineering/')) engineering.push(document);
-    else if (document.relative.startsWith('decisions/')) decisions.push(document);
-    else if (document.relative.startsWith('changes/')) changes.push(document);
+  if (!scoped.length && available.length) {
+    const lines = [];
+    available.forEach((document, index) => {
+      if (index) lines.push('');
+      const id = document.id;
+      const appliesTo = Array.isArray(document.applies_to)
+        ? document.applies_to.join(', ')
+        : String(document.applies_to);
+      lines.push(`  ${id || '(missing id)'}`);
+      lines.push(`    ${document.path}`);
+      lines.push(`    applies_to: ${appliesTo}`);
+    });
+    blocks.push(['Available living specs', lines]);
   }
 
-  write(stdout, 'Constitution');
-  for (const document of constitution) write(stdout, `  ${document.display}`);
-  write(stdout, '');
-  write(stdout, 'Capabilities');
-  writeLivingSpecs(stdout, capabilities);
-  write(stdout, '');
-  write(stdout, 'Engineering');
-  writeLivingSpecs(stdout, engineering);
-  write(stdout, '');
-  write(stdout, 'Decisions');
-  for (const document of decisions) write(stdout, `  ${document.display}`);
-  write(stdout, '');
-  write(stdout, 'Active changes');
-  for (const document of changes) {
-    const affects = Array.isArray(document.frontmatter.affects)
-      ? document.frontmatter.affects.join(', ')
-      : String(document.frontmatter.affects || '');
-    write(stdout, `  ${document.display}`);
-    write(stdout, `    affects: ${affects}`);
-  }
+  blocks.forEach(([title, lines], index) => {
+    if (index) write(stdout, '');
+    write(stdout, title);
+    for (const line of lines) write(stdout, line);
+  });
   return 0;
 }
 
@@ -317,6 +287,10 @@ function requirementDefinitions(text) {
   return found;
 }
 
+function stripHtmlComments(text) {
+  return String(text).replace(/<!--[\s\S]*?(?:-->|$)/g, '');
+}
+
 function changeSections(body) {
   const sections = new Map();
   let current = null;
@@ -454,6 +428,14 @@ function lint(cwd = process.cwd(), streams = {}) {
     const display = relativeDisplay(filePath, cwd);
     const { frontmatter: rawFrontmatter, body } = parsed.get(filePath);
     const frontmatter = rawFrontmatter || {};
+    const sections = changeSections(stripHtmlComments(body));
+    const hasDelta = ['ADD', 'MODIFY', 'REMOVE'].some(
+      (section) => stripHtmlComments(sections[section] || '').trim().length > 0,
+    );
+    if (!hasDelta) {
+      errors.push([display, 'change must contain at least one ADD, MODIFY, or REMOVE section']);
+    }
+
     const affects = frontmatter.affects;
     if (!Array.isArray(affects) || !affects.every((item) => typeof item === 'string' && item.length > 0)) {
       continue;
@@ -470,7 +452,6 @@ function lint(cwd = process.cwd(), streams = {}) {
       }
     }
 
-    const sections = changeSections(body);
     for (const section of ['ADD', 'MODIFY', 'REMOVE']) {
       for (const reqId of new Set(allRequirementIds(sections[section] || ''))) {
         if (!changeTouches.has(reqId)) changeTouches.set(reqId, new Map());
@@ -515,10 +496,10 @@ function lint(cwd = process.cwd(), streams = {}) {
   });
   for (const [display, message] of errors) write(stdout, `ERROR ${display}: ${message}`);
   if (errors.length) {
-    write(stdout, `${errors.length} errors`);
+    write(stdout, `${errors.length} structural errors`);
     return 1;
   }
-  write(stdout, '0 errors');
+  write(stdout, '0 structural errors');
   return 0;
 }
 
@@ -527,9 +508,8 @@ function helpText() {
     'Usage: charterleaf <command> [args]',
     '',
     'Commands:',
-    '  map             show the specification map',
-    '  related <path>  find specs matching a repo-relative code path',
-    '  lint            check Charterleaf structural conventions',
+    '  related <path>  find durable constraints matching a repo-relative path',
+    '  lint            report structural errors in specs/',
   ].join('\n');
 }
 
@@ -548,14 +528,6 @@ function main(argv = process.argv.slice(2), cwd = process.cwd(), streams = {}) {
   if (!argv.length) return usageError('a command is required', streams);
 
   const [command, ...rest] = argv;
-  if (command === 'map') {
-    if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
-      write(streams.stdout || process.stdout, 'Usage: charterleaf map');
-      return 0;
-    }
-    if (rest.length) return usageError('map takes no arguments', streams);
-    return map(path.resolve(cwd), streams);
-  }
   if (command === 'related') {
     if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
       write(streams.stdout || process.stdout, 'Usage: charterleaf related <path>');
@@ -581,9 +553,9 @@ module.exports = {
   globMatches,
   lint,
   main,
-  map,
   normalizeRepoPath,
   parseFrontmatter,
   related,
+  resolveRelated,
   requirementDefinitions,
 };