@llman-sdd/core 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,7 @@
     "7z-wasm": "^1.2.0",
     "@cucumber/gherkin": "^42.0.1",
     "@cucumber/messages": "^34.2.1",
+    "@toon-format/toon": "^4.1.1",
     "nunjucks": "^3.2.4",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"

package/src/archive/freeze.ts

@@ -1,12 +1,22 @@
 /**
  * Archive freeze/thaw orchestration (review-freeze capability, r24/r25).
- * Port of v1 change/freeze.rs: candidates = dated archive dirs; freeze adds
- * them into `freezed_changes.7z.archived` (7z a updates existing archives)
- * then removes the originals; thaw extracts selected dirs back into place.
- * All filesystem effects flow through the injected FreezeIo.
+ * Candidates = dated archive dirs; freeze writes a flat relationship-index
+ * card `<YYYY-MM-DD>-<id>.yaml` (only `title` + `depends_on`), adds the body
+ * files into `freezed_changes.7z.archived` (7z a updates existing archives),
+ * then removes the original dirs; thaw extracts selected dirs back and removes
+ * the card. All filesystem effects flow through the injected FreezeIo.
  */
 import { join } from 'node:path';
 
+import { firstH1 } from '../change/collect.ts';
+import { extractFrontmatter } from '../change/frontmatter.ts';
+import {
+  FROZEN_CARD_EXT,
+  composeFrozenCard,
+  frozenCardIdOf,
+  frozenCardName,
+  isFrozenCard,
+} from './frozenCard.ts';
 import type { SevenZipPort } from './sevenzip.ts';
 
 export const FREEZE_ARCHIVE_NAME = 'freezed_changes.7z.archived';
@@ -15,8 +25,13 @@ export const ARCHIVE_DIR_REL = 'llmanspec/changes/archive';
 export interface FreezeIo {
   exists(path: string): boolean;
   listDir(path: string): string[];
+  readText(path: string): string;
+  writeText(path: string, content: string): void;
+  isDirectory(path: string): boolean;
   /** rm -rf */
   removeDir(path: string): void;
+  /** Remove a single file. */
+  remove(path: string): void;
   mkdirp(path: string): void;
   /** Move a directory within the repo (same-device; adapter may copy). */
   moveDir(from: string, to: string): void;
@@ -24,6 +39,11 @@ export interface FreezeIo {
 
 const DATED_RE = /^\d{4}-\d{2}-\d{2}-/u;
 
+/**
+ * r24: freeze candidates = date-prefixed entries that are directories with a
+ * proposal.md body (i.e. not yet frozen — frozen dirs have been replaced by
+ * the flat `<date>-<id>.yaml` card, which is a file, not a dir).
+ */
 export function freezeCandidates(
   io: FreezeIo,
   archiveDir: string,
@@ -32,7 +52,7 @@ export function freezeCandidates(
   const all = io.exists(archiveDir)
     ? io
         .listDir(archiveDir)
-        .filter((n) => DATED_RE.test(n))
+        .filter((n) => DATED_RE.test(n) && !isFrozenCard(n) && io.isDirectory(`${archiveDir}/${n}`))
         .toSorted()
     : [];
   let candidates = opts.before ? all.filter((n) => n.slice(0, 10) < (opts.before ?? '')) : [...all];
@@ -72,8 +92,31 @@ export async function runFreeze(
       ],
     };
   }
+
+  // Card = authoritative record that bodies are in the cold backup. Write
+  // cards first; on `7z add` failure roll them back and keep the original dirs.
   const archiveAbs = join(rootAbs, ARCHIVE_DIR_REL, FREEZE_ARCHIVE_NAME);
-  await sz.add(archiveAbs, join(rootAbs, ARCHIVE_DIR_REL), candidates);
+
+  const cards: Array<{ datedId: string; source: string }> = [];
+  for (const c of candidates) {
+    const proposalRel = `${ARCHIVE_DIR_REL}/${c}/proposal.md`;
+    const proposal = io.exists(proposalRel) ? io.readText(proposalRel) : '';
+    const frontmatter = extractFrontmatter(proposal) ?? '';
+    cards.push({
+      datedId: c,
+      source: composeFrozenCard(firstH1(proposal), frontmatter),
+    });
+  }
+
+  for (const card of cards) {
+    io.writeText(`${ARCHIVE_DIR_REL}/${frozenCardName(card.datedId)}`, card.source);
+  }
+  try {
+    await sz.add(archiveAbs, join(rootAbs, ARCHIVE_DIR_REL), candidates);
+  } catch (error) {
+    for (const card of cards) io.remove(`${ARCHIVE_DIR_REL}/${frozenCardName(card.datedId)}`);
+    throw error;
+  }
   for (const c of candidates) {
     io.removeDir(`${ARCHIVE_DIR_REL}/${c}`);
   }
@@ -85,25 +128,39 @@ export async function runFreeze(
   };
 }
 
+/**
+ * r24: `--list` enumerates frozen changes from the flat cards on disk (no 7z
+ * parse needed). Legacy entries frozen without cards (predecessor format) are
+ * derived from the 7z listing so old archives stay listable (r25 legacy compat).
+ */
 export async function runList(io: FreezeIo, sz: SevenZipPort, rootAbs: string): Promise<string[]> {
+  let names = new Set<string>();
+  const archiveDirRel = ARCHIVE_DIR_REL;
+  if (io.exists(archiveDirRel)) {
+    for (const name of io.listDir(archiveDirRel)) {
+      if (isFrozenCard(name) && frozenCardIdOf(name) !== null) {
+        names.add(name.slice(0, -FROZEN_CARD_EXT.length));
+      }
+    }
+  }
   const archiveAbs = join(rootAbs, ARCHIVE_DIR_REL, FREEZE_ARCHIVE_NAME);
-  if (!io.exists(archiveAbs)) {
-    return [`freeze archive not found: ./${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME}`];
+  if (io.exists(archiveAbs)) {
+    // Legacy/unexpected entries present only inside the 7z (no card on disk).
+    const entries = (await sz.listEntries(archiveAbs)).map((n) => n.replace(/\/$/u, ''));
+    const top = (n: string): string => n.split('/')[0] ?? n;
+    for (const e of entries.map(top).filter((n) => DATED_RE.test(n))) {
+      if (!names.has(e)) names.add(e);
+    }
   }
-  // Real 7z lists file paths under their directory (`<dir>/proposal.md`);
-  // directory entries themselves are skipped by parseListNames. Derive the
-  // archived change names from the leading path segment.
-  const entries = (await sz.listEntries(archiveAbs)).map((n) => n.replace(/\/$/u, ''));
-  const top = (n: string): string => n.split('/')[0] ?? n;
-  const unique = [...new Set(entries.map(top).filter((n) => DATED_RE.test(n)))].toSorted();
-  if (unique.length === 0) {
+  const sorted = [...names].toSorted();
+  if (sorted.length === 0) {
     return [
       `Freeze archive ${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME} contains no archived changes`,
     ];
   }
   return [
-    `Frozen archived changes in ${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME} (${unique.length}):`,
-    ...unique.map((c) => `  - ${c}`),
+    `Frozen archived changes in ${ARCHIVE_DIR_REL}/${FREEZE_ARCHIVE_NAME} (${sorted.length}):`,
+    ...sorted.map((c) => `  - ${c}`),
   ];
 }
 
@@ -130,7 +187,16 @@ export async function runThaw(
   io.removeDir(tmpRel);
   try {
     await sz.extractAll(archiveAbs, tmpAbs);
-    const available = new Set(io.listDir(tmpRel).filter((n) => DATED_RE.test(n)));
+    const available = new Set(
+      io.exists(tmpRel) ? io.listDir(tmpRel).filter((n) => DATED_RE.test(n)) : [],
+    );
+    // Cards on disk also count as available (they are the authoritative record
+    // that bodies are in the cold backup, even before any extraction listing).
+    for (const name of io.exists(ARCHIVE_DIR_REL) ? io.listDir(ARCHIVE_DIR_REL) : []) {
+      if (isFrozenCard(name) && frozenCardIdOf(name) !== null) {
+        available.add(name.slice(0, -FROZEN_CARD_EXT.length));
+      }
+    }
     const missing = names.filter((n) => !available.has(n));
     if (missing.length > 0) {
       throw new Error(
@@ -143,6 +209,8 @@ export async function runThaw(
         throw new Error(`target already exists: ${name}`);
       }
       io.moveDir(`${tmpRel}/${name}`, `${destRel}/${name}`);
+      const cardRel = `${ARCHIVE_DIR_REL}/${frozenCardName(name)}`;
+      if (io.exists(cardRel)) io.remove(cardRel);
       restored.push(name);
     }
     return {

package/src/archive/frozenCard.ts

@@ -0,0 +1,105 @@
+/**
+ * Frozen-change relationship-index card contract (review-freeze capability,
+ * r24/r25): `freeze` replaces a dated archive dir with a flat card
+ * `<YYYY-MM-DD>-<id>.yaml` whose content carries only the change's `title`
+ * (proposal H1) and `depends_on` (proposal frontmatter) — a human/agent
+ * readable navigation index. id and date are implied by the file name; bodies
+ * live in the 7z cold backup. Cards are the authoritative record that a change
+ * is in the cold backup.
+ *
+ * The card is a fenced YAML document (same `---` convention as proposal.md) so
+ * existing frontmatter readers (`extractFrontmatter` / `parseDeps`) work
+ * unchanged — parseDeps on a card text reads the preserved `depends_on`.
+ *
+ * Depends_on extraction is deliberately dependency-free (no `yaml` package):
+ * it recognizes single-line flow `[a, b]`, block `- item` lists and multi-line
+ * flow blocks, then normalizes to a single-line flow array so `parseDeps`
+ * reads it unchanged. Anything unparseable degrades to `depends_on: []` (never
+ * blocks the freeze).
+ *
+ * Pure string logic — all filesystem effects live in freeze.ts (FreezeIo).
+ */
+
+export const FROZEN_CARD_EXT = '.yaml';
+
+/** `2026-01-01-old` → `2026-01-01-old.yaml` */
+export function frozenCardName(datedId: string): string {
+  return `${datedId}${FROZEN_CARD_EXT}`;
+}
+
+/** id for a card filename (`2026-01-01-old.yaml` → `old`); null when not a card. */
+export function frozenCardIdOf(name: string): string | null {
+  const m = name.match(/^\d{4}-\d{2}-\d{2}-(.+)\.yaml$/u);
+  return m?.[1] ?? null;
+}
+
+export function isFrozenCard(name: string): boolean {
+  return frozenCardIdOf(name) !== null;
+}
+
+function escapeYamlScalar(value: string): string {
+  return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+}
+
+/** Normalize a flow-list inner string (comma-separated, quotes stripped). */
+function splitFlowItems(inner: string): string[] {
+  const out: string[] = [];
+  for (const raw of inner.split(',')) {
+    const item = raw.trim().replaceAll(/^['"]|['"]$/gu, '');
+    if (item !== '') out.push(item);
+  }
+  return out;
+}
+
+function toFlow(items: string[]): string {
+  return items.length === 0 ? 'depends_on: []' : `depends_on: [${items.join(', ')}]`;
+}
+
+/**
+ * Extract `depends_on` from a proposal frontmatter block. Falls back to
+ * `depends_on: []` when absent/empty/unparseable — a malformed dependency list
+ * never breaks the freeze.
+ */
+export function extractDependsOn(frontmatter: string): string {
+  const lines = frontmatter.split('\n');
+  const flowIdx = lines.findIndex((l) => /^depends_on\s*:\s*\[/u.test(l));
+  if (flowIdx !== -1) {
+    // Single-line flow `depends_on: [a, b]` (may span lines).
+    let acc = (lines[flowIdx] ?? '').replace(/^depends_on\s*:/u, '').trim();
+    let j = flowIdx;
+    while (!/\]\s*$/u.test(acc) && j < lines.length - 1) {
+      j++;
+      acc += ` ${(lines[j] ?? '').trim()}`;
+    }
+    const inner = acc.replace(/^\[/u, '').replace(/\]\s*/u, '');
+    return toFlow(splitFlowItems(inner));
+  }
+  const blockIdx = lines.findIndex((l) => /^depends_on\s*:\s*$/u.test(l));
+  if (blockIdx !== -1) {
+    // Block list `- a` lines.
+    const items: string[] = [];
+    for (const l of lines.slice(blockIdx + 1)) {
+      const m = l.match(/^\s*-\s+(\S+)/u);
+      if (m?.[1]) items.push(m[1].replaceAll(/['"]/gu, ''));
+      // multi-line flow handled below
+      else if (/^\s*\[/u.test(l)) break;
+      else if (l.trim() !== '') break;
+    }
+    if (items.length > 0) return toFlow(items);
+    // Multi-line flow `[\n a,\n b\n ]`.
+    let acc = lines
+      .slice(blockIdx + 1)
+      .join(' ')
+      .replace(/^[^[]*\[/u, '');
+    acc = (acc.split(']')[0] ?? '').trim();
+    if (acc !== '') return toFlow(splitFlowItems(acc));
+    return 'depends_on: []';
+  }
+  return 'depends_on: []';
+}
+
+/** Compose a relationship-index card: `title` + `depends_on` inside fences. */
+export function composeFrozenCard(title: string, frontmatter: string): string {
+  const dependsOn = extractDependsOn(frontmatter);
+  return ['---', `title: "${escapeYamlScalar(title)}"`, dependsOn, '---'].join('\n') + '\n';
+}

package/src/archive/sevenzip.ts

@@ -1,5 +1,4 @@
 import { Buffer } from 'node:buffer';
-import { mkdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
 
 /**
@@ -9,12 +8,12 @@ import { basename, join } from 'node:path';
  * (WASM 7z refuses existing -o dirs). Spike-proven on Bun: compress / list /
  * extract keep directory structure.
  *
- * Compiled single-file binaries have no on-disk 7zz.wasm (Emscripten would
- * probe $bunfs and abort), so build-binary.ts additionally injects the wasm
- * base64 via the literal define `process.env.LLMAN_SDD_EMBEDDED_7ZZ_WASM_B64`
- * (define only rewrites literal member access — do not route through a
- * variable). Unset in source/npm/Node runs → glue loads the .wasm from disk
- * as before.
+ * Purity: the wasm payload and the extraction-dir creation are caller-injected
+ * (`wasmB64` / `mkdirp`). Compiled binaries carry no on-disk 7zz.wasm
+ * (Emscripten would probe $bunfs and abort), so the CLI seam passes the
+ * build-time base64 define through `wasmB64`
+ * (see apps/cli/src/commands/archive.ts); unset in source/npm/Node runs →
+ * glue loads the .wasm from disk as before.
  */
 import SevenZip from '7z-wasm';
 
@@ -57,9 +56,12 @@ export function resolveEmbeddedWasmB64(value: unknown): Uint8Array | undefined {
   return new Uint8Array(bytes);
 }
 
-/** Read the build-injected wasm; undefined when absent or malformed. */
-export function embeddedWasmBinary(): Uint8Array | undefined {
-  return resolveEmbeddedWasmB64(process.env.LLMAN_SDD_EMBEDDED_7ZZ_WASM_B64);
+/** Caller-injected side effects for the 7z adapter (see module doc). */
+export interface WasmSevenZipDeps {
+  /** Base64 wasm blob (build-time define at the CLI seam); undefined → disk. */
+  wasmB64?: string;
+  /** Create the extraction target directory recursively. */
+  mkdirp: (dir: string) => void;
 }
 
 async function initModule(
@@ -105,8 +107,8 @@ function parseListNames(lines: string[]): string[] {
   return names;
 }
 
-export async function makeWasmSevenZip(): Promise<SevenZipPort> {
-  const wasmBinary = embeddedWasmBinary();
+export async function makeWasmSevenZip(deps: WasmSevenZipDeps): Promise<SevenZipPort> {
+  const wasmBinary = resolveEmbeddedWasmB64(deps.wasmB64);
   return {
     async add(archivePath: string, baseDir: string, entries: string[]): Promise<void> {
       const mod = await initModule(undefined, wasmBinary);
@@ -129,7 +131,7 @@ export async function makeWasmSevenZip(): Promise<SevenZipPort> {
     async extractAll(archivePath: string, destDir: string): Promise<void> {
       const mod = await initModule(undefined, wasmBinary);
       const archMount = mount(mod, 1, join(archivePath, '..'));
-      mkdirSync(destDir, { recursive: true });
+      deps.mkdirp(destDir);
       const destMount = mount(mod, 2, destDir);
       mod.FS.chdir(destMount);
       const rc = mod.callMain(['x', `${archMount}/${basename(archivePath)}`, '-y']);

package/src/change/closeOutHarness.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether a close-out (finalize / archive) must run bdd.run_command before
+ * any merge or rename. Pure: the CLI supplies the flags, the spec scan, and
+ * the nested-invocation bit.
+ */
+
+export type CloseOutHarnessDecision =
+  | { kind: 'skip'; announce: boolean }
+  | { kind: 'abort'; message: string }
+  | { kind: 'run'; command: string };
+
+export function decideCloseOutHarness(input: {
+  noCheck: boolean;
+  needsSpecsChange: boolean;
+  hasExecutable: boolean;
+  runCommand: string | null;
+  nested: boolean;
+}): CloseOutHarnessDecision {
+  if (input.noCheck) return { kind: 'skip', announce: true };
+  if (!input.needsSpecsChange || !input.hasExecutable) return { kind: 'skip', announce: false };
+  const command = input.runCommand?.trim() ?? '';
+  if (command === '') {
+    return { kind: 'abort', message: 'executable scenarios have no bdd.run_command' };
+  }
+  if (input.nested) {
+    return { kind: 'abort', message: 'bdd harness skipped: nested invocation' };
+  }
+  return { kind: 'run', command };
+}

package/src/change/collect.ts

@@ -0,0 +1,140 @@
+import { readBinding } from './frontmatter.ts';
+/**
+ * Change collection + stage derivation (change domain, peripheral-commands
+ * capability r20/r34 shapes; predecessor commands/list.rs port). Pure — IO injected.
+ * Lives in change/ (not report/) so the domain never imports its renderers:
+ * report/{show,specs}.ts and validation/changeCheck.ts consume this one-way.
+ */
+import { CHANGES_DIR } from './lifecycle.ts';
+import { parseTaskCheckboxes } from './tasks.ts';
+
+export interface ChangeFsIo {
+  exists(path: string): boolean;
+  readText(path: string): string;
+  listDir(path: string): string[];
+  isDirectory(path: string): boolean;
+  mtimeMs(path: string): number;
+}
+
+/** Minimal structural io for the active-change walk (r58/r73 shared caliber). */
+export interface ChangeScanIo {
+  exists(path: string): boolean;
+  listDir(path: string): string[];
+  isDirectory(path: string): boolean;
+}
+
+/**
+ * r58/r73 shared walk: visits every active change dir (a dir directly holding
+ * proposal.md) under changesRoot — nested groups allowed, leaf name = change
+ * id, `archive/` and dot-dirs skipped, depth-limited. The CLI change scan and
+ * the dependency-reference resolver share this one traversal.
+ */
+export function walkActiveChangeDirs(
+  io: ChangeScanIo,
+  changesRoot: string,
+  visit: (dir: string, name: string) => void,
+  opts: { maxScanDepth?: number } = {},
+): void {
+  if (!io.exists(changesRoot) || !io.isDirectory(changesRoot)) return;
+  const maxDepth = opts.maxScanDepth ?? 8;
+  const walk = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    for (const name of io.listDir(dir).toSorted()) {
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) visit(child, name);
+      else walk(child, depth + 1);
+    }
+  };
+  walk(changesRoot, 1);
+}
+
+export interface ChangeSummary {
+  name: string;
+  path: string;
+  title: string;
+  stage: 'draft' | 'designed' | 'planned' | 'full';
+  hasBinding: boolean;
+  completedTasks: number;
+  totalTasks: number;
+  lastModified: Date;
+  idleDays: number;
+}
+
+export type ChangeStatus = 'no-tasks' | 'complete' | 'in-progress';
+
+export function statusFor(total: number, completed: number): ChangeStatus {
+  if (total === 0) return 'no-tasks';
+  return completed >= total ? 'complete' : 'in-progress';
+}
+
+export function stageFor(
+  hasDesign: boolean,
+  hasTasks: boolean,
+  hasBinding: boolean,
+): ChangeSummary['stage'] {
+  // Monotonic predecessor parity (r34): design.md gates designed, tasks.md only
+  // upgrades on top of design, binding only upgrades the complete set.
+  if (hasDesign && hasTasks && hasBinding) return 'full';
+  if (hasDesign && hasTasks) return 'planned';
+  if (hasDesign) return 'designed';
+  return 'draft';
+}
+
+export function countTasks(tasksMd: string): { completed: number; total: number } {
+  const { completed, total } = parseTaskCheckboxes(tasksMd);
+  return { completed, total };
+}
+
+export function firstH1(md: string): string {
+  for (const line of md.split('\n')) {
+    const m = line.match(/^#\s+(.*)$/u);
+    if (m?.[1]) return m[1].trim();
+  }
+  return '';
+}
+
+export function collectChanges(
+  io: ChangeFsIo,
+  root: string,
+  now: Date,
+  opts: { maxScanDepth?: number } = {},
+): ChangeSummary[] {
+  const changesDir = `${root}/${CHANGES_DIR}`;
+  if (!io.exists(changesDir) || !io.isDirectory(changesDir)) return [];
+  const out: ChangeSummary[] = [];
+  const readChangeDir = (dir: string, name: string): void => {
+    const proposal = `${dir}/proposal.md`;
+    const hasDesign = io.exists(`${dir}/design.md`);
+    const hasTasks = io.exists(`${dir}/tasks.md`);
+    const hasBinding = readBinding(io.readText(proposal)) !== null;
+    const { completed, total } = hasTasks
+      ? countTasks(io.readText(`${dir}/tasks.md`))
+      : { completed: 0, total: 0 };
+
+    // lastModified = newest mtime across the change dir
+    let latest = io.mtimeMs(proposal);
+    for (const f of [hasDesign ? `${dir}/design.md` : null, hasTasks ? `${dir}/tasks.md` : null]) {
+      if (f) latest = Math.max(latest, io.mtimeMs(f));
+    }
+    const lastModified = new Date(latest);
+    const idleDays = Math.floor((now.getTime() - lastModified.getTime()) / 86_400_000);
+
+    out.push({
+      name,
+      path: name,
+      title: firstH1(io.readText(proposal)),
+      stage: stageFor(hasDesign, hasTasks, hasBinding),
+      hasBinding,
+      completedTasks: completed,
+      totalTasks: total,
+      lastModified,
+      idleDays,
+    });
+  };
+  // r58: recursive, depth-limited proposal discovery (predecessor --max-scan-depth parity)
+  walkActiveChangeDirs(io, changesDir, readChangeDir, { maxScanDepth: opts.maxScanDepth });
+  // predecessor lists newest-first
+  return out.toSorted((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+}

package/src/change/frontmatter.ts

@@ -5,20 +5,62 @@
  */
 import { parseDocument } from 'yaml';
 
+import type { GitLike } from '../git/spawnGit.ts';
+
 export interface ChangeBinding {
   branch: string;
   baseBranch: string;
   baseSha: string;
 }
 
+/**
+ * Single frontmatter splitter (r73): the block starts with `---\n` at offset 0
+ * and closes at the first standalone `---` line (followed by `\n` or EOF).
+ * Every read path (extractFrontmatter / readBinding / parseDeps /
+ * needs_specs_change) and the write path share this one contract.
+ */
 function splitFrontmatter(proposal: string): { body: string; frontmatter: string | null } {
   if (!proposal.startsWith('---\n')) return { body: proposal, frontmatter: null };
-  const end = proposal.indexOf('\n---\n', 4);
-  if (end === -1) return { body: proposal, frontmatter: null };
-  return {
-    frontmatter: proposal.slice(4, end + 1),
-    body: proposal.slice(end + 5),
-  };
+  const rest = proposal.slice(4);
+  let pos = 0;
+  while (pos <= rest.length) {
+    const nl = rest.indexOf('\n', pos);
+    const lineEnd = nl === -1 ? rest.length : nl;
+    if (rest.slice(pos, lineEnd) === '---') {
+      return {
+        frontmatter: pos === 0 ? '' : rest.slice(0, pos - 1),
+        body: nl === -1 ? '' : rest.slice(nl + 1),
+      };
+    }
+    if (nl === -1) return { body: proposal, frontmatter: null };
+    pos = nl + 1;
+  }
+  return { body: proposal, frontmatter: null };
+}
+
+/** Frontmatter block content (between the delimiters), or null without a block. */
+export function extractFrontmatter(proposal: string): string | null {
+  return splitFrontmatter(proposal).frontmatter;
+}
+
+/**
+ * r73: `needs_specs_change` is read from the frontmatter block only — a
+ * body line with the same text must not flip the verdict. Default true.
+ */
+export function readNeedsSpecsChange(frontmatter: string | null): boolean {
+  const m = frontmatter?.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1];
+  return m === undefined ? true : m === 'true';
+}
+
+/**
+ * r73: live specs landed on the bound branch — per-line prefix match on
+ * `diff --name-only <base_branch>...<branch>` (a path like
+ * `docs/llmanspec/specs/x` must not count as landed).
+ */
+export function specsLanded(git: GitLike, binding: ChangeBinding): boolean {
+  const touched =
+    git.runOpt(['diff', '--name-only', `${binding.baseBranch}...${binding.branch}`]) ?? '';
+  return touched.split('\n').some((line) => line.startsWith('llmanspec/specs/'));
 }
 
 export function readBinding(proposal: string): ChangeBinding | null {

package/src/change/id.ts

@@ -1,5 +1,5 @@
 /**
- * Change id derivation (change-lifecycle capability): v1 `change/new.rs`
+ * Change id derivation (change-lifecycle capability): predecessor `change/new.rs`
  * `derive_change_id` parity — pure kebab sanitization (lowercase alnum,
  * separators), no verb requirement, empty/oversized handling.
  */
@@ -8,11 +8,7 @@ const ID_CAP = 60;
 
 export class ChangeIdError extends Error {}
 
-export function isLegalChangeId(id: string): boolean {
-  return /^[a-z0-9-]+$/u.test(id) && id.length > 0 && id.length <= ID_CAP;
-}
-
-/** v1 parity: sanitize to lowercase kebab (ASCII alnum only; CJK/punct dropped). */
+/** predecessor parity: sanitize to lowercase kebab (ASCII alnum only; CJK/punct dropped). */
 export function deriveChangeId(description: string): string {
   const trimmed = description.trim();
   if (trimmed === '') {