@llman-sdd/core 0.3.0 → 0.5.0

package/src/index.ts

@@ -1,34 +1,12 @@
-// 版本 SSOT 是包描述文件(发布产物)/git tag(二进制,经 LLMAN_SDD_VERSION 注入)。
-// 运行时从所在包的 package.json 读取,避免双处维护。单文件二进制内
-// import.meta.url 指向 $bunfs 虚拟路径,package.json 不存在——此处必须容错,
-// 版本由构建期 define 注入,回退值不会对外暴露。
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-function readPackageVersion(): string {
-  try {
-    const pkg = JSON.parse(
-      readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),
-    ) as { version: string };
-    return pkg.version;
-  } catch {
-    return '0.0.0';
-  }
-}
-export const VERSION = readPackageVersion();
-
 export * from './ports.ts';
 
 export {
   EXTRA_SKILLS,
   archiveSchema,
   bddSchema,
-  bindingSchema,
   changeIdSchema,
-  scenarioAttrsBindingSchema,
   sddConfigSchema,
   sddSchema,
-  tagsBindingSchema,
   type SddConfig,
   type SddConfigInput,
 } from './config/schema.ts';
@@ -39,20 +17,17 @@ export {
   nextUniqueNumber,
   renderChangeIdTemplate,
 } from './config/changeId.ts';
-export {
-  ExtraSkillsError,
-  renderConfigOverview,
-  setExtraSkills,
-  skillsJson,
-} from './config/surface.ts';
+export { renderConfigOverview, skillsJson } from './config/surface.ts';
 
 export type {
   CapabilityDoc,
   CapabilityHeader,
-  ScenarioClassification,
+  RuleIR,
   ScenarioIR,
+  ScenarioStep,
   SpecStructuralError,
 } from './spec/ir.ts';
+export { specIdOf } from './spec/ir.ts';
 export {
   SpecParseError,
   localeToGherkinLang,
@@ -60,10 +35,23 @@ export {
   parseFeatureSource,
 } from './spec/parser.ts';
 export { buildReqRegistry, type ReqRegistry, type RegistryDuplicate } from './spec/reqRegistry.ts';
+export {
+  analyzeLegacy,
+  hasNativeRules,
+  migrateNativeSource,
+  type MigrateBlock,
+  type MigrateResult,
+} from './spec/migrateNative.ts';
+export {
+  MIGRATE_KINDS,
+  isMigrateKind,
+  migrateNoteFor,
+  migrateOverviewFor,
+  type MigrateKind,
+} from './project/migrateNotes.ts';
 export {
   addReq,
   addScenario,
-  allReqIds,
   AuthoringError,
   planDedupe,
   resolveReq,
@@ -79,6 +67,7 @@ export type {
   ValidationReport,
 } from './validation/validate.ts';
 export { validateAllSpecs, validateCapability, applyStrict } from './validation/validate.ts';
+export { buildDuplicatesFor, formatTotals } from './validation/validate.ts';
 export { splitVerb } from './config/changeId.ts';
 export {
   evaluateStaleness,
@@ -88,8 +77,7 @@ export {
 export {
   checkChangeDoc,
   validateChange,
-  expandRunCommand,
-  hasPlaceholders,
+  checkGlobalChangeIdUniqueness,
   STAGE_ORDER,
   type ChangeCheckConfig,
   type ChangeCheckInput,
@@ -99,19 +87,44 @@ export {
   type StageGate,
 } from './validation/changeCheck.ts';
 export { discoverSpecs, type DiscoveryIo } from './validation/discover.ts';
+export {
+  expandRunCommand,
+  runHarnessForSpecs,
+  type HarnessGate,
+  type HarnessRunner,
+  type HarnessRunOutcome,
+  type HarnessTarget,
+} from './validation/harness.ts';
 export type { ChangeBinding } from './change/frontmatter.ts';
-export { readBinding, writeBinding } from './change/frontmatter.ts';
+export {
+  readBinding,
+  writeBinding,
+  extractFrontmatter,
+  readNeedsSpecsChange,
+} from './change/frontmatter.ts';
 export {
   GitError,
   defaultBranch,
   isCleanTree,
   makeSpawnGit,
   currentBranch,
-  revParseHead,
+  worktreeList,
+  probeMainCheckout,
+  nonMainCheckoutWarning,
   type GitLike,
+  type WorktreeEntry,
+  type MainCheckoutProbe,
 } from './git/spawnGit.ts';
-export { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId, isLegalChangeId } from './change/id.ts';
-export { extractUniqueNumber, harvestUniqueNumbers } from './change/nextId.ts';
+export { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId } from './change/id.ts';
+export { parseTaskCheckboxes, type ParsedTaskCheckboxes } from './change/tasks.ts';
+export { CLOSE_OUT_TASK_HINT, closeOutTaskLines, isCloseOutTaskTitle } from './change/tasks.ts';
+export { decideCloseOutHarness, type CloseOutHarnessDecision } from './change/closeOutHarness.ts';
+export {
+  extractUniqueNumber,
+  collectNumbers,
+  harvestUniqueNumbers,
+  harvestAcrossWorktrees,
+} from './change/nextId.ts';
 export { ChangeIdResolveError, resolveChangeId, type ResolvedChangeId } from './change/resolve.ts';
 export {
   CHANGES_DIR,
@@ -130,16 +143,12 @@ export {
 export { normalizeLocale, localeFallbacks } from './templates/locale.ts';
 export {
   MAX_UNIT_NESTING_DEPTH,
-  MissingUnitError,
   renderTemplate,
   renderWithUnits,
   type UnitRegistry,
 } from './templates/engine.ts';
 export {
-  DEFAULT_SKILL_FILES,
   ETHICS_KEYS,
-  OPTIONAL_SKILL_FILES,
-  UNIT_FILES,
   buildTemplateVars,
   effectiveRunCommand,
   enforceEthicsGovernance,
@@ -165,27 +174,23 @@ export {
 } from './init/init.ts';
 export {
   collectChanges,
-  renderChangesList,
-  renderChangesJson,
   statusFor,
   stageFor,
-  relativeTime,
-  statusHuman,
+  countTasks,
+  firstH1,
   type ChangeFsIo,
   type ChangeStatus,
   type ChangeSummary,
-} from './report/collect.ts';
-export { graphMermaid, type GraphFsIo } from './report/graph.ts';
+} from './change/collect.ts';
+export { renderChangesJson, renderChangesList } from './report/collect.ts';
+export { graphData, graphMermaid, type GraphDataIr, type GraphFsIo } from './report/graph.ts';
+export { parseDeps } from './report/graph.ts';
+export { renderMachine, type MachineFormat } from './render/machine.ts';
 export { showChangeJson, type ShowDeps, type ShowFsIo } from './report/show.ts';
-export {
-  nextReqId,
-  scaffoldSpec,
-  skeletonContent,
-  type SpecHelperIo,
-} from './report/specHelpers.ts';
+export { nextReqId, scaffoldSpec, type SpecHelperIo } from './report/specHelpers.ts';
 export {
   collectSpecs,
-  morphologyOfScenarios,
+  morphologyOf,
   renderSpecsJson,
   renderSpecsList,
   type SpecMorphology,
@@ -193,10 +198,10 @@ export {
 } from './report/specs.ts';
 export {
   SevenZipError,
-  embeddedWasmBinary,
   makeWasmSevenZip,
   resolveEmbeddedWasmB64,
   type SevenZipPort,
+  type WasmSevenZipDeps,
 } from './archive/sevenzip.ts';
 export {
   ARCHIVE_DIR_REL,
@@ -210,18 +215,23 @@ export {
   type FreezeRunResult,
   type ThawResult,
 } from './archive/freeze.ts';
+export {
+  FROZEN_CARD_EXT,
+  composeFrozenCard,
+  frozenCardIdOf,
+  frozenCardName,
+  isFrozenCard,
+} from './archive/frozenCard.ts';
 export {
   buildReview,
   renderReviewHtml,
+  specRelFor,
   type ReviewInput,
   type ReviewKind,
   type ReviewResult,
   type ReviewSignal,
-  type TagBinding,
 } from './review/review.ts';
 export {
-  TREE_VERSION,
-  buildDocs,
   buildTreeIndex,
   computeSpecHash,
   type HashIo,
@@ -236,7 +246,6 @@ export {
   REBUILD_LOCK_REL,
   TREE_JSON_REL,
   checkIndexFreshness,
-  loadTree,
   loadTreeWithAutoRebuild,
   parseLock,
   rebuildIndex,
@@ -247,7 +256,6 @@ export {
   type RebuildResult,
 } from './context/indexStore.ts';
 export {
-  MAX_TOOL_ROUNDS,
   resolveChatConfig,
   runContextRetrieval,
   unavailableResult,

package/src/init/defaultConfig.ts

@@ -1,5 +1,5 @@
 /**
- * Default llmanspec/config.yaml templates, extracted verbatim from v1
+ * Default llmanspec/config.yaml templates, extracted verbatim from predecessor
  * (crates/llman-sdd/src/sdd/project/config.rs DEFAULT_CONFIG_EN/ZH_HANS).
  */
 export const LLMANSPEC_SCHEMA_URL =
@@ -26,8 +26,6 @@ locale: en
 # BDD integration (optional, uncomment to enable)
 # bdd:
 #   framework: pytest-bdd
-#   feature_dir: tests/features/
-#   # default_language: en
 #   # Filtered runners: include {feature_*} so validate --all/--specs runs per capability.
 #   # run_command: "pytest {feature_dir} -k {feature_name} -v"
 #   # Project-wide runners (no placeholders): validate --all/--specs runs the suite once (batch-once).
@@ -56,8 +54,6 @@ locale: zh-Hans
 # BDD 集成（可选，取消注释以启用）
 # bdd:
 #   framework: pytest-bdd
-#   feature_dir: tests/features/
-#   # default_language: zh-CN
 #   # 过滤型 runner：写 {feature_*}，validate --all/--specs 按 capability 分别执行。
 #   # run_command: "pytest {feature_dir} -k {feature_name} -v"
 #   # 项目级 runner（无占位符）：validate --all/--specs 整批只跑一次（batch-once）。

package/src/init/init.ts

@@ -31,19 +31,34 @@ export { effectiveRunCommand } from '../templates/skills.ts';
 const MARKER_START = '<!-- LLMANSPEC:START -->';
 const MARKER_END = '<!-- LLMANSPEC:END -->';
 
-/** Marker-block update: replace block body if present, else prepend the block. */
+/**
+ * Marker-block update: replace block body if present, else prepend the block.
+ * Formatter-friendly (0.0.78 parity): exactly one blank line after START and
+ * after END; on the END boundary an existing blank line is preserved verbatim
+ * and a missing one is inserted, so repeated updates never accumulate blanks.
+ */
 export function updateFileWithMarkers(content: string, body: string): string {
   if (content === '') {
-    return `${MARKER_START}\n${body}\n${MARKER_END}\n`;
+    return `${MARKER_START}\n\n${body}\n${MARKER_END}\n`;
   }
   const start = content.indexOf(MARKER_START);
   const end = content.indexOf(MARKER_END);
   if (start !== -1 && end !== -1) {
     if (end < start)
       throw new Error('Invalid marker state: end marker appears before start marker.');
-    return `${content.slice(0, start)}${MARKER_START}\n${body}\n${MARKER_END}${content.slice(end + MARKER_END.length)}`;
+    const suffix = content.slice(end + MARKER_END.length);
+    return `${content.slice(0, start)}${MARKER_START}\n\n${body}\n${MARKER_END}${separatorAfterEndMarker(suffix)}`;
   }
-  return `${MARKER_START}\n${body}\n${MARKER_END}\n${content}`;
+  return `${MARKER_START}\n\n${body}\n${MARKER_END}\n\n${content}`;
+}
+
+/** END-boundary suffix, guaranteed blank-line-separated from following content. */
+function separatorAfterEndMarker(suffix: string): string {
+  const br = /^\r?\n/u.exec(suffix);
+  if (br === null) return suffix === '' ? '\n' : `\n\n${suffix}`;
+  const rest = suffix.slice(br[0].length);
+  if (rest === '' || /^\r?\n/u.test(rest)) return suffix;
+  return `${br[0]}${suffix}`;
 }
 
 export const TEMPLATES_ROOT = join(import.meta.dirname, '..', '..', 'templates');

package/src/ports.ts

@@ -5,16 +5,10 @@
  * `node:fs`, `Bun.$`, or prompt libraries; runtimes wire adapters in.
  */
 
-/** Interaction port. v1 ships an @inquirer/prompts adapter; a future ink TUI
+/** Interaction port. predecessor ships an @inquirer/prompts adapter; a future ink TUI
  * ships its own adapter (the two must never run in the same process). */
 export interface PromptDriver {
   select<T extends string>(message: string, choices: readonly T[]): Promise<T>;
   multiselect<T extends string>(message: string, choices: readonly T[]): Promise<T[]>;
   confirm(message: string): Promise<boolean>;
 }
-
-/** Template rendering port (nunjucks adapter planned: autoescape off,
- * minijinja-compatible trim semantics, `unit()` registered via addGlobal). */
-export interface TemplateEngine {
-  render(template: string, context: Record<string, unknown>): string;
-}

package/src/project/migrateNotes.ts

@@ -0,0 +1,104 @@
+// Collaboration notes for `project migrate` — the predecessor (Rust ≤0.0.78) shipped two
+// one-shot migrations (toon2features / specs-flatten); this tool deliberately ships
+// none (peripheral-commands r35: the command outputs an explanation and never
+// migrates). Porting the implementations was surveyed on 2026-09-23 and
+// declined: specs-flatten fights this repo's directory-style coexistence direction,
+// and toon2features has no confirmed audience. Instead, `--kind <x>` prints
+// the equivalent manual-migration guidance so old command forms get useful
+// stdout instead of an unknown-option error.
+
+export const MIGRATE_KINDS = ['toon2features', 'specs-flatten'] as const;
+
+export type MigrateKind = (typeof MIGRATE_KINDS)[number];
+
+export function isMigrateKind(value: string): value is MigrateKind {
+  return (MIGRATE_KINDS as readonly string[]).includes(value);
+}
+
+const isZh = (locale: string): boolean => locale.trim().toLowerCase().startsWith('zh');
+
+const TOON2FEATURES_ZH = `llman-sdd project migrate --kind toon2features — 遗留 spec.toon → 单轨 .feature 协作说明
+
+背景:v1(Rust ≤0.0.78)以 specs/<cap>/spec.toon(表格形态)与散落 .feature 双轨存规格;v2 只读单轨 .feature(specs/<cap>.feature 或目录式 <cap>/<cap>.feature),spec.toon 会被静默忽略。本命令不执行迁移,以下为手工迁移指引。
+
+Agent 该做什么:
+1. 逐 capability 确认真的存在 spec.toon(无则跳过)。
+2. 读 spec.toon 表格并转换:requirements 表每行 → 在 <cap>.feature 写一个 @req:<id> + 规则: 块(id 进块头标签,statement 全文放描述);scenarios 表每行:有 GWT(假如/当/那么)且 req_id 已定义 → 作为嵌套 场景: 挂回该规则;无 GWT 或 req 未定义 → 在 proposal/design 记录理由后舍弃,不可静默丢弃。
+3. 目标 <cap>.feature 已存在时勿覆盖——人工合并两侧内容后再删除 spec.toon。
+4. 迁移后运行 llman-sdd validate --specs --strict 与项目 BDD 套件,全绿为收口标准。
+
+人类该做什么:
+- 审阅 diff 与 req 语义;把 # scope: 指向该规范管辖的真实源码目录(scope 承载 staleness 扫描,自引用无意义)。
+
+陷阱:
+- spec.toon 的引号转义存在两种历史风格("" 翻倍与 \\" 反斜杠),手工读表须逐一确认。
+- 任何一行无法解析都停下来人工判定,勿凭猜测整表转换。`;
+
+const TOON2FEATURES_EN = `llman-sdd project migrate --kind toon2features — legacy spec.toon → single-track .feature collaboration notes
+
+Background: v1 (Rust ≤0.0.78) stored specs dual-track — specs/<cap>/spec.toon (table form) plus scattered .feature files; v2 reads single-track .feature only (specs/<cap>.feature or directory-style <cap>/<cap>.feature) and silently ignores spec.toon. This command performs no migration; the notes below are the manual procedure.
+
+What the agent does:
+1. Per capability, confirm a spec.toon actually exists (skip otherwise).
+2. Read the spec.toon tables and convert: each requirements row → a @req:<id> 规则: block in <cap>.feature (id in the block header tag, statement verbatim in the description); each scenarios row: GWT-bearing (Given/When/Then) with a defined req_id → a nested 场景: under that rule; no GWT or undefined req_id → record the justification in proposal/design and drop — never silently.
+3. Never overwrite an existing <cap>.feature — merge both sides by hand, then delete spec.toon.
+4. After migration run llman-sdd validate --specs --strict and the project BDD suite; all-green is the bar.
+
+What the human does:
+- Review the diff and the req semantics; point # scope: at the real source directory the spec governs (scope drives staleness scanning; self-references are useless).
+
+Pitfalls:
+- spec.toon quoting has two historical escaping styles ("" doubling and \\" backslash); verify cell by cell.
+- Any unparseable row means stop and judge by hand — never convert a whole table on guesswork.`;
+
+const SPECS_FLATTEN_ZH = `llman-sdd project migrate --kind specs-flatten — 目录式 specs 归一为扁平 协作说明
+
+背景:v1 曾把 capability 放在 specs/<cap>/<cap>.feature 目录;v2 两种布局都能读,但扁平 specs/<cap>.feature 是唯一写入形态(spec add-* / skeleton 按扁平拼写),归一属可选整理。本命令不执行迁移,以下为手工指引。
+
+Agent 该做什么:
+1. 仅处理「目录内只有一个 <cap>.feature、无其他文件」的纯目录;目标 specs/<cap>.feature 已存在(冲突)、目录内有多个 .feature、或有附属文件 → 报告并跳过,勿强迁。
+2. 用 git mv specs/<cap>/<cap>.feature specs/<cap>.feature 保留历史,然后删除空目录。
+3. 检查该文件 # scope: 是否自引用自身路径,是则改写为真实源码目录。
+4. 迁移后运行 llman-sdd validate --specs 确认无 stale 警告。
+
+人类该做什么:
+- 审阅 git diff(move 保历史);确认 scope 指向真实管辖面。`;
+
+const SPECS_FLATTEN_EN = `llman-sdd project migrate --kind specs-flatten — directory-style specs → flat collaboration notes
+
+Background: v1 placed capabilities in specs/<cap>/<cap>.feature directories; v2 reads both layouts, but flat specs/<cap>.feature is the only write shape (spec add-* / skeleton spell flat paths), so flattening is optional housekeeping. This command performs no migration; the notes below are the manual procedure.
+
+What the agent does:
+1. Only handle pure directories (exactly one <cap>.feature inside, nothing else); if the target specs/<cap>.feature already exists (conflict), the directory holds multiple .feature files, or there are auxiliary entries → report and skip, never force.
+2. git mv specs/<cap>/<cap>.feature specs/<cap>.feature to preserve history, then remove the emptied directory.
+3. Check the file's # scope: for a self-referential path and rewrite it to the real source directory.
+4. After migration run llman-sdd validate --specs and confirm no stale warning remains.
+
+What the human does:
+- Review the git diff (moves keep history); confirm scope points at the real governed surface.`;
+
+const OVERVIEW_ZH =
+  'legacy 迁移实现不随本工具提供;v2 直接读取既有 llmanspec 布局(config.yaml / specs/*.feature / changes/),零迁移可读。\n' +
+  '两种历史迁移的协作说明:--kind toon2features | --kind specs-flatten。';
+
+const OVERVIEW_EN =
+  'Legacy migration implementations are not shipped; v2 reads existing llmanspec layouts directly (config.yaml / specs/*.feature / changes/), zero-migration readable.\n' +
+  'Collaboration notes for the two historical migrations: --kind toon2features | --kind specs-flatten.';
+
+/** stdout body for `project migrate --kind <kind>`; null when the kind is unknown. */
+export function migrateNoteFor(kind: string, locale: string): string | null {
+  const zh = isZh(locale);
+  switch (kind) {
+    case 'toon2features':
+      return zh ? TOON2FEATURES_ZH : TOON2FEATURES_EN;
+    case 'specs-flatten':
+      return zh ? SPECS_FLATTEN_ZH : SPECS_FLATTEN_EN;
+    default:
+      return null;
+  }
+}
+
+/** stdout body for bare `project migrate` (no --kind). */
+export function migrateOverviewFor(locale: string): string {
+  return isZh(locale) ? OVERVIEW_ZH : OVERVIEW_EN;
+}

package/src/render/machine.ts

@@ -0,0 +1,30 @@
+import { encode } from '@toon-format/toon';
+
+/**
+ * Machine-readable render targets shared by report commands (add-render-layer).
+ * Each command owns one canonical IR (exactly the payload its `--json` emits);
+ * every machine format renders from that single object, so formats can never
+ * drift the way hand-written per-command JSON did. `human` prose is
+ * deliberately out of scope — it stays per-command.
+ */
+export type MachineFormat = 'json' | 'compact-json' | 'toon';
+
+/**
+ * Render `ir` in the requested format. The returned string carries no trailing
+ * newline (callers `console.log` it, matching the pre-renderer byte layout).
+ *
+ * - `json`: 2-space pretty — byte-identical to the historical `--json` output.
+ * - `compact-json`: true minified single line (normalizes the historical
+ *   strip-newlines / indent-0 variants; same data, contract still "one line").
+ * - `toon`: TOON predecessor via the official encoder (comma delimiter default).
+ */
+export function renderMachine(ir: unknown, format: MachineFormat): string {
+  switch (format) {
+    case 'compact-json':
+      return JSON.stringify(ir);
+    case 'toon':
+      return encode(ir);
+    case 'json':
+      return JSON.stringify(ir, null, 2);
+  }
+}

package/src/report/collect.ts

@@ -1,128 +1,10 @@
+import { type ChangeSummary, statusFor } from '../change/collect.ts';
 /**
- * Change collection + rendering (peripheral-commands capability, r20).
- * Port of v1 commands/list.rs shapes. Pure — IO injected.
+ * Change list rendering (peripheral-commands capability, r20): presentation
+ * only — domain scan/stage derivation lives in change/collect.ts; this module
+ * renders what it produces. Pure — no IO.
  */
-import { readBinding } from '../change/frontmatter.ts';
-import { CHANGES_DIR } from '../change/lifecycle.ts';
-
-export interface ChangeFsIo {
-  exists(path: string): boolean;
-  readText(path: string): string;
-  listDir(path: string): string[];
-  isDirectory(path: string): boolean;
-  mtimeMs(path: string): number;
-}
-
-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 v1 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 } {
-  let completed = 0;
-  let total = 0;
-  for (const line of tasksMd.split('\n')) {
-    const m = line.match(/^\s*-\s+\[( |x|X)\]/u);
-    if (m) {
-      total += 1;
-      if (m[1] !== ' ') completed += 1;
-    }
-  }
-  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 maxDepth = opts.maxScanDepth ?? 8;
-  const out: ChangeSummary[] = [];
-  // r58: recursive, depth-limited proposal discovery (v1 --max-scan-depth parity)
-  const visit = (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`)) {
-        readChangeDir(child, name);
-      } else {
-        visit(child, depth + 1);
-      }
-    }
-  };
-  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,
-    });
-  };
-  visit(changesDir, 1);
-  // v1 lists newest-first
-  return out.toSorted((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
-}
+import { renderMachine } from '../render/machine.ts';
 
 export function statusHuman(c: ChangeSummary): string {
   const s = statusFor(c.totalTasks, c.completedTasks);
@@ -160,8 +42,11 @@ export function renderChangesList(changes: readonly ChangeSummary[], now: Date):
   return lines;
 }
 
-export function renderChangesJson(changes: readonly ChangeSummary[]): string {
-  return JSON.stringify(
+export function renderChangesJson(
+  changes: readonly ChangeSummary[],
+  mode: 'json' | 'compact-json' | 'toon' = 'json',
+): string {
+  return renderMachine(
     {
       changes: changes.map((c) => ({
         name: c.name,
@@ -174,7 +59,6 @@ export function renderChangesJson(changes: readonly ChangeSummary[]): string {
         status: statusFor(c.totalTasks, c.completedTasks),
       })),
     },
-    null,
-    2,
+    mode,
   );
 }