@llman-sdd/core 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {

package/src/archive/sevenzip.ts

@@ -61,7 +61,7 @@ function parseListNames(lines: string[]): string[] {
   for (const line of lines) {
     if (/^-+/u.test(line)) {
       rulesSeen += 1;
-      inTable = rulesSeen >= 2 && rulesSeen <= 2 ? true : inTable;
+      if (rulesSeen === 2) inTable = true;
       if (rulesSeen === 3) break;
       continue;
     }

package/src/context/indexStore.ts

@@ -1,12 +1,10 @@
 /**
  * Index orchestration (context-index capability, r26): rebuild writes the
  * pageindex tree under a create-new lock; check compares the stored spec_hash
- * against a fresh one.
+ * against a fresh one. All paths are ROOT-RELATIVE through the injected IO.
  */
-import { join } from 'node:path';
-
 import type { SpecEntry } from '../validation/validate.ts';
-import { buildTreeIndex, computeSpecHash, type HashIo, type SerializedTreeIndex } from './tree.ts';
+import { buildTreeIndex, computeSpecHash, type SerializedTreeIndex } from './tree.ts';
 
 export const CONTEXT_DIR_REL = 'llmanspec/.context';
 export const PAGEINDEX_DIR_REL = `${CONTEXT_DIR_REL}/pageindex`;
@@ -61,7 +59,6 @@ function acquireLock(io: IndexIo, lockPath: string): void {
 
 export function rebuildIndex(
   io: IndexIo,
-  root: string,
   specsDir: string,
   entries: readonly SpecEntry[],
   opts: RebuildOpts,
@@ -95,7 +92,7 @@ export interface FreshnessResult {
   lines: string[];
 }
 
-export function checkIndexFreshness(io: IndexIo, root: string, specsDir: string): FreshnessResult {
+export function checkIndexFreshness(io: IndexIo, specsDir: string): FreshnessResult {
   if (!io.exists(TREE_JSON_REL)) {
     return { fresh: false, lines: ['[pageindex] missing — run `index rebuild` first'] };
   }
@@ -119,14 +116,11 @@ export function checkIndexFreshness(io: IndexIo, root: string, specsDir: string)
 }
 
 /** Load the tree for retrieval (absent/corrupt → null). */
-export function loadTree(io: IndexIo, root: string): SerializedTreeIndex | null {
-  const path = join(root, TREE_JSON_REL);
-  if (!io.exists(path)) return null;
+export function loadTree(io: IndexIo): SerializedTreeIndex | null {
+  if (!io.exists(TREE_JSON_REL)) return null;
   try {
-    return JSON.parse(io.readText(path)) as SerializedTreeIndex;
+    return JSON.parse(io.readText(TREE_JSON_REL)) as SerializedTreeIndex;
   } catch {
     return null;
   }
 }
-
-export type { HashIo };

package/src/git/spawnGit.ts

@@ -76,14 +76,6 @@ export function defaultBranch(git: GitLike): string {
   );
 }
 
-export function mergeBase(a: string, b: string, git: GitLike): string {
-  return git.run(['merge-base', a, b]);
-}
-
-export function branchExists(branch: string, git: GitLike): boolean {
-  return git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]) !== null;
-}
-
 export function revParseHead(git: GitLike): string {
   return git.run(['rev-parse', 'HEAD']);
 }

package/src/index.ts

@@ -1,4 +1,21 @@
-export const VERSION = '0.1.0';
+// 版本 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';
 
@@ -48,9 +65,7 @@ export {
   defaultBranch,
   isCleanTree,
   makeSpawnGit,
-  mergeBase,
   currentBranch,
-  branchExists,
   revParseHead,
   type GitLike,
 } from './git/spawnGit.ts';
@@ -89,7 +104,19 @@ export {
   type SkillTemplate,
   type TemplateIo,
 } from './templates/skills.ts';
-export { runInit, updateFileWithMarkers, type InitResult } from './init/init.ts';
+export {
+  embeddedTemplates,
+  makeEmbeddedTemplateIo,
+  resolveEmbeddedTable,
+  templateKeyFor,
+} from './templates/embedded.ts';
+export {
+  TEMPLATES_ROOT,
+  runInit,
+  updateFileWithMarkers,
+  type InitIo,
+  type InitResult,
+} from './init/init.ts';
 export {
   collectChanges,
   renderChangesList,
@@ -132,6 +159,7 @@ export {
 } from './archive/freeze.ts';
 export {
   buildReview,
+  renderReviewHtml,
   type ReviewInput,
   type ReviewKind,
   type ReviewResult,

package/src/init/defaultConfig.ts

@@ -9,7 +9,7 @@ export const DEFAULT_CONFIG_EN = `schema: spec-driven
 locale: en
 
 # Optional extra skills (disabled by default, uncomment to enable).
-# On \`llman sdd init --update\`, managed candidates are:
+# On \`llman-sdd init --update\`, managed candidates are:
 #   default workflow skills + entries listed here (extra_skills extend).
 # Then \`.agents/skills/llman-sdd-*\` is scanned: anything not in that candidate
 # set is removed first, then candidates are written/updated. Only the
@@ -40,7 +40,7 @@ export const DEFAULT_CONFIG_ZH_HANS = `schema: spec-driven
 locale: zh-Hans
 
 # 可选额外技能（默认禁用，取消注释以启用）。
-# 运行 \`llman sdd init --update\` 时，管理候选集为：
+# 运行 \`llman-sdd init --update\` 时，管理候选集为：
 #   默认 workflow 技能 + 本列表（extra_skills 扩展）。
 # 然后扫描 \`.agents/skills/llman-sdd-*\`：不在候选集中的先删除，再写入/更新候选。
 # 仅处理 \`llman-sdd-\` 前缀（无此前缀的自定义技能不会被删）。

package/src/init/init.ts

@@ -2,9 +2,10 @@
  * init / --update orchestration (init-generators capability, r19).
  * Scaffold llmanspec/, write managed AGENTS.md blocks, render skills into
  * the .agents/skills namespace (SKILL.md per skill dir), and clean the
- * managed namespace.
+ * managed namespace. Pure: all paths are ROOT-RELATIVE strings resolved by
+ * the injected InitIo; template resources load through the injected
+ * TemplateIo (runtimes point it at TEMPLATES_ROOT).
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { loadConfig } from '../config/load.ts';
@@ -16,6 +17,7 @@ import {
   loadLocaleResource,
   loadSkillTemplates,
   skillCandidates,
+  type TemplateIo,
 } from '../templates/skills.ts';
 import {
   DEFAULT_CONFIG_EN,
@@ -46,11 +48,20 @@ export function updateFileWithMarkers(content: string, body: string): string {
 
 export const TEMPLATES_ROOT = join(import.meta.dirname, '..', '..', 'templates');
 
-function writeDefaultConfig(root: string, locale: string): void {
+/** Repo-root-relative filesystem effects needed by the init flow. */
+export interface InitIo {
+  exists(path: string): boolean;
+  readText(path: string): string;
+  writeText(path: string, content: string): void;
+  mkdirp(path: string): void;
+  listDir(path: string): string[];
+  removeDir(path: string): void;
+}
+
+function writeDefaultConfig(io: InitIo, locale: string): void {
   const raw = locale === 'zh-Hans' ? DEFAULT_CONFIG_ZH_HANS : DEFAULT_CONFIG_EN;
-  const dir = join(root, 'llmanspec');
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, 'config.yaml'), prependSchemaHeader(raw, LLMANSPEC_SCHEMA_URL));
+  io.mkdirp('llmanspec');
+  io.writeText('llmanspec/config.yaml', prependSchemaHeader(raw, LLMANSPEC_SCHEMA_URL));
 }
 
 export interface InitResult {
@@ -61,84 +72,63 @@ export interface InitResult {
   configPath: string;
 }
 
+const SKILLS_BASE = '.agents/skills';
+
 export function runInit(
-  root: string,
+  io: InitIo,
+  templates: TemplateIo,
   opts: { update: boolean; locale?: string; version: string },
 ): InitResult {
-  const llmanspecDir = join(root, 'llmanspec');
-  mkdirSync(llmanspecDir, { recursive: true });
+  io.mkdirp('llmanspec');
 
   // 1) config: create with defaults if missing, then always load.
-  const configPath = join(llmanspecDir, 'config.yaml');
-  if (!existsSync(configPath)) writeDefaultConfig(root, opts.locale ?? 'en');
-  const config = loadConfig(readFileSync(configPath, 'utf8'));
+  const configPath = 'llmanspec/config.yaml';
+  if (!io.exists(configPath)) writeDefaultConfig(io, opts.locale ?? 'en');
+  const config = loadConfig(io.readText(configPath));
 
   // 2) scaffold directories.
-  mkdirSync(join(llmanspecDir, 'specs'), { recursive: true });
-  mkdirSync(join(llmanspecDir, 'changes', 'archive'), { recursive: true });
-  const gitkeepSpecs = join(llmanspecDir, 'specs', '.gitkeep');
-  if (!existsSync(gitkeepSpecs)) writeFileSync(gitkeepSpecs, '');
-  const gitkeepArchive = join(llmanspecDir, 'changes', 'archive', '.gitkeep');
-  if (!existsSync(gitkeepArchive)) writeFileSync(gitkeepArchive, '');
+  io.mkdirp('llmanspec/specs');
+  io.mkdirp('llmanspec/changes/archive');
+  if (!io.exists('llmanspec/specs/.gitkeep')) io.writeText('llmanspec/specs/.gitkeep', '');
+  if (!io.exists('llmanspec/changes/archive/.gitkeep')) {
+    io.writeText('llmanspec/changes/archive/.gitkeep', '');
+  }
 
   // 3) AGENTS.md managed blocks (root + llmanspec), preserving content.
   const vars = buildTemplateVars(config, opts.version);
   const locales = localeFallbacks(config.locale);
-  // skills render owns the unit registry; stubs reuse the same registry load.
-  const skillTemplates = loadSkillTemplates(
-    { exists: (p) => existsSync(p), readText: (p) => readFileSync(p, 'utf8') },
-    TEMPLATES_ROOT,
-    config,
-    vars,
-  );
+  const skillTemplates = loadSkillTemplates(templates, TEMPLATES_ROOT, config, vars);
   enforceEthicsGovernance(skillTemplates);
 
-  const rootStubRaw = loadLocaleResource(
-    { exists: (p) => existsSync(p), readText: (p) => readFileSync(p, 'utf8') },
-    TEMPLATES_ROOT,
-    locales,
-    'agents-root-stub.md',
-  );
-  if (rootStubRaw !== null) {
-    const agentsPath = join(root, 'AGENTS.md');
-    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
-    const body = renderTemplate(rootStubRaw, new Map(), vars);
-    writeFileSync(agentsPath, updateFileWithMarkers(existing, body));
-  }
-  const llmanspecStubRaw = loadLocaleResource(
-    { exists: (p) => existsSync(p), readText: (p) => readFileSync(p, 'utf8') },
-    TEMPLATES_ROOT,
-    locales,
-    'llmanspec-agents-stub.md',
-  );
-  if (llmanspecStubRaw !== null) {
-    const agentsPath = join(llmanspecDir, 'AGENTS.md');
-    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
-    const body = renderTemplate(llmanspecStubRaw, new Map(), vars);
-    writeFileSync(agentsPath, updateFileWithMarkers(existing, body));
+  for (const [stubPath, agentsPath] of [
+    ['agents-root-stub.md', 'AGENTS.md'],
+    ['llmanspec-agents-stub.md', 'llmanspec/AGENTS.md'],
+  ] as const) {
+    const stubRaw = loadLocaleResource(templates, TEMPLATES_ROOT, locales, stubPath);
+    if (stubRaw === null) continue;
+    const existing = io.exists(agentsPath) ? io.readText(agentsPath) : '';
+    const body = renderTemplate(stubRaw, new Map(), vars);
+    io.writeText(agentsPath, updateFileWithMarkers(existing, body));
   }
 
   // 4) skills namespace cleanup (--update only): remove llman-sdd-* dirs
   // outside the candidate set; un-prefixed custom skills stay untouched.
   const removed: string[] = [];
-  const skillsBase = join(root, '.agents', 'skills');
-  if (opts.update && existsSync(skillsBase)) {
+  if (opts.update && io.exists(SKILLS_BASE)) {
     const candidates = new Set(skillCandidates(config).map((f) => f.replace(/\.md$/u, '')));
-    for (const entry of readdirSync(skillsBase)) {
+    for (const entry of io.listDir(SKILLS_BASE)) {
       if (entry.startsWith('llman-sdd-') && !candidates.has(entry)) {
-        rmSync(join(skillsBase, entry), { recursive: true, force: true });
+        io.removeDir(`${SKILLS_BASE}/${entry}`);
         removed.push(entry);
       }
     }
   }
 
   // 5) write candidates: rendered product trimmed + single trailing newline.
-  const skillsBase2 = join(root, '.agents', 'skills');
   for (const t of skillTemplates) {
     const dirName = t.name.replace(/\.md$/u, '');
-    const skillDir = join(skillsBase2, dirName);
-    mkdirSync(skillDir, { recursive: true });
-    writeFileSync(join(skillDir, 'SKILL.md'), `${t.content.trimEnd()}\n`);
+    io.mkdirp(`${SKILLS_BASE}/${dirName}`);
+    io.writeText(`${SKILLS_BASE}/${dirName}/SKILL.md`, `${t.content.trimEnd()}\n`);
   }
 
   return { skills: skillTemplates.map((t) => t.name.replace(/\.md$/u, '')), removed, configPath };

package/src/report/collect.ts

@@ -43,7 +43,7 @@ export function stageFor(
   return 'draft';
 }
 
-function countTasks(tasksMd: string): { completed: number; total: number } {
+export function countTasks(tasksMd: string): { completed: number; total: number } {
   let completed = 0;
   let total = 0;
   for (const line of tasksMd.split('\n')) {
@@ -56,7 +56,7 @@ function countTasks(tasksMd: string): { completed: number; total: number } {
   return { completed, total };
 }
 
-function firstH1(md: string): string {
+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();
@@ -123,7 +123,7 @@ export function relativeTime(from: Date, now: Date): string {
   return `${Math.floor(hours / 24)}d ago`;
 }
 
-function pad(s: string, width: number): string {
+export function pad(s: string, width: number): string {
   return s.length >= width ? s : s + ' '.repeat(width - s.length);
 }
 

package/src/report/graph.ts

@@ -18,6 +18,26 @@ interface GraphNode {
   dependsOn: string[];
 }
 
+/** Extract depends_on entries from a proposal's YAML frontmatter. */
+function parseDeps(proposal: string): string[] {
+  const fm = proposal.match(/^---\n([\s\S]*?)\n---/u);
+  const deps: string[] = [];
+  if (!fm?.[1]) return deps;
+  let inDeps = false;
+  for (const line of fm[1].split('\n')) {
+    if (/^depends_on:\s*$/u.test(line)) {
+      inDeps = true;
+      continue;
+    }
+    if (inDeps) {
+      const m = line.match(/^\s*-\s+(\S+)/u);
+      if (m?.[1]) deps.push(m[1]);
+      else if (line.trim() !== '') inDeps = false;
+    }
+  }
+  return deps;
+}
+
 function collectNodes(io: GraphFsIo, root: string): GraphNode[] {
   const nodes: GraphNode[] = [];
   const scan = (dir: string, archived: boolean, stripDatePrefix: boolean): void => {
@@ -29,24 +49,7 @@ function collectNodes(io: GraphFsIo, root: string): GraphNode[] {
       const proposal = `${full}/proposal.md`;
       if (!io.exists(proposal)) continue;
       const id = archived && stripDatePrefix ? name.replace(/^\d{4}-\d{2}-\d{2}-/u, '') : name;
-      const deps: string[] = [];
-      const fm = io.readText(proposal).match(/^---\n([\s\S]*?)\n---/u);
-      if (fm?.[1]) {
-        const lines = fm[1].split('\n');
-        let inDeps = false;
-        for (const line of lines) {
-          if (/^depends_on:\s*$/u.test(line)) {
-            inDeps = true;
-            continue;
-          }
-          if (inDeps) {
-            const m = line.match(/^\s*-\s+(\S+)/u);
-            if (m?.[1]) deps.push(m[1]);
-            else if (line.trim() !== '') inDeps = false;
-          }
-        }
-      }
-      nodes.push({ id, archived, dependsOn: deps });
+      nodes.push({ id, archived, dependsOn: parseDeps(io.readText(proposal)) });
     }
   };
   scan(`${root}/${CHANGES_DIR}`, false, false);
@@ -59,23 +62,8 @@ function collectNodes(io: GraphFsIo, root: string): GraphNode[] {
       const id = name.replace(/^\d{4}-\d{2}-\d{2}-/u, '');
       if (!referenced.has(id)) continue;
       // archived nodes keep their real depends_on — v1 emits their edges too
-      const deps: string[] = [];
       const proposal = `${archiveDir}/${name}/proposal.md`;
-      if (io.exists(proposal)) {
-        const fm = io.readText(proposal).match(/^---\n([\s\S]*?)\n---/u);
-        let inDeps = false;
-        for (const line of fm?.[1]?.split('\n') ?? []) {
-          if (/^depends_on:\s*$/u.test(line)) {
-            inDeps = true;
-            continue;
-          }
-          if (inDeps) {
-            const m = line.match(/^\s*-\s+(\S+)/u);
-            if (m?.[1]) deps.push(m[1]);
-            else if (line.trim() !== '') inDeps = false;
-          }
-        }
-      }
+      const deps = io.exists(proposal) ? parseDeps(io.readText(proposal)) : [];
       nodes.push({ id, archived: true, dependsOn: deps });
     }
   }

package/src/report/show.ts

@@ -1,53 +1,34 @@
 import { readBinding } from '../change/frontmatter.ts';
 import { CHANGES_DIR } from '../change/lifecycle.ts';
-import { isCleanTree, currentBranch, makeSpawnGit } from '../git/spawnGit.ts';
-import { discoverSpecs, type DiscoveryIo } from '../validation/discover.ts';
+import { currentBranch, isCleanTree, type GitLike } from '../git/spawnGit.ts';
+import { discoverSpecs } from '../validation/discover.ts';
 /**
  * show change JSON (peripheral-commands capability, r21): v1 field set and
  * gate structure (clean-tree / on-bound-branch / stage-complete /
  * specs-landed / tasks-done / validate). Object keys are inserted in v1's
- * order; consumers compare structurally.
+ * order; consumers compare structurally. Effects flow through the injected
+ * FsIo and GitLike ports — this module stays pure.
  */
 import { validateAllSpecs } from '../validation/validate.ts';
-import { stageFor, type ChangeFsIo } from './collect.ts';
+import { countTasks, firstH1, stageFor, type ChangeFsIo } from './collect.ts';
 
-export interface ShowFsIo extends ChangeFsIo {
-  readText(path: string): string;
-}
+export type ShowFsIo = ChangeFsIo;
 
 export interface ShowDeps {
+  /** Single IO for change docs, tasks, and spec scope checks. */
   io: ShowFsIo;
-  discovery: DiscoveryIo;
+  git: GitLike;
   root: string;
   specsDir: string;
-  now: Date;
-}
-
-function parseTasks(md: string): { completed: number; total: number } {
-  let completed = 0;
-  let total = 0;
-  for (const line of md.split('\n')) {
-    const m = line.match(/^\s*-\s+\[( |x|X)\]/u);
-    if (m) {
-      total += 1;
-      if (m[1] !== ' ') completed += 1;
-    }
-  }
-  return { completed, total };
-}
-
-function existsSyncLike(deps: ShowDeps, p: string): boolean {
-  return deps.io.exists(p) || deps.discovery.exists(p);
 }
 
 export function showChangeJson(deps: ShowDeps, id: string): Record<string, unknown> {
-  const { io, discovery, root, now } = deps;
+  const { io, git, root } = deps;
   const dir = `${root}/${CHANGES_DIR}/${id}`;
   const proposalPath = `${dir}/proposal.md`;
   if (!io.exists(proposalPath)) throw new Error(`change not found: ${id}`);
 
   const proposal = io.readText(proposalPath);
-  const titleMatch = proposal.match(/^#\s+(.*)$/mu);
   const hasDesign = io.exists(`${dir}/design.md`);
   const hasTasks = io.exists(`${dir}/tasks.md`);
   const binding = readBinding(proposal);
@@ -57,10 +38,9 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     io.exists(`${dir}/${f}`),
   );
   const { completed, total } = hasTasks
-    ? parseTasks(io.readText(`${dir}/tasks.md`))
+    ? countTasks(io.readText(`${dir}/tasks.md`))
     : { completed: 0, total: 0 };
 
-  const git = makeSpawnGit(root);
   const cleanTree = isCleanTree(git);
   const onBoundBranch = binding !== null && currentBranch(git) === binding.branch;
 
@@ -77,9 +57,7 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
   const needsSpecsChange = declaredNeeds !== undefined ? declaredNeeds === 'true' : true;
 
   const tasksDone = total > 0 && completed >= total;
-  const specReport = validateAllSpecs(discoverSpecs(deps.specsDir, discovery), {
-    exists: (p: string) => existsSyncLike(deps, p),
-  });
+  const specReport = validateAllSpecs(discoverSpecs(deps.specsDir, io), io);
   const validateOk = !specReport.failed && (total === 0 || tasksDone);
 
   const stageComplete = stage === 'full';
@@ -93,7 +71,7 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     {
       name: 'on-bound-branch',
       pass: onBoundBranch,
-      hint: onBoundBranch ? '' : 'change is not attached; run `llman sdd change start <id>`',
+      hint: onBoundBranch ? '' : 'change is not attached; run `llman-sdd change start <id>`',
     },
     {
       name: 'stage-complete',
@@ -115,15 +93,14 @@ export function showChangeJson(deps: ShowDeps, id: string): Record<string, unkno
     {
       name: 'validate',
       pass: validateOk,
-      hint: validateOk ? '' : 'fix issues reported by `llman sdd validate <id> --strict`',
+      hint: validateOk ? '' : 'fix issues reported by `llman-sdd validate <id> --strict`',
     },
   ];
-  void now;
 
   return {
     id,
     path: id,
-    title: titleMatch?.[1]?.trim() ?? '',
+    title: firstH1(proposal),
     stage,
     artifacts,
     readyToImplement: gateChecks.every((g) => g.pass),

package/src/report/specs.ts

@@ -3,8 +3,9 @@
  * aligned with v1 — rules = @human scenarios; enforced = rules carrying an
  * @req link that has an executable acceptance scenario; pending = the rest.
  */
-import type { CapabilityDoc, ScenarioIR } from '../spec/ir.ts';
+import type { CapabilityDoc } from '../spec/ir.ts';
 import type { SpecEntry } from '../validation/validate.ts';
+import { pad } from './collect.ts';
 
 export interface SpecMorphology {
   ruleCount: number;
@@ -35,7 +36,7 @@ function morphologyOf(doc: CapabilityDoc): SpecMorphology {
   return {
     ruleCount: rules.length,
     ruleEnforcedCount: enforced.length,
-    ruleManualCount: rules.filter((r: ScenarioIR) => r.manual).length,
+    ruleManualCount: rules.filter((r) => r.manual).length,
     rulePendingCount: rules.length - enforced.length,
     acceptanceCount: acceptance.length,
     orphanAcceptanceCount: orphan.length,
@@ -43,23 +44,22 @@ function morphologyOf(doc: CapabilityDoc): SpecMorphology {
 }
 
 export function collectSpecs(entries: readonly SpecEntry[]): SpecSummary[] {
-  return entries.map((e) => ({
-    id: e.doc.header.capability ?? e.fileName,
-    title: e.doc.header.capability ?? e.fileName,
-    purpose: e.doc.header.purpose ?? '',
-    validScope: (e.doc.header.scope ?? '')
-      .split(',')
-      .map((s) => s.trim())
-      .filter((s) => s !== ''),
-    requirementCount: morphologyOf(e.doc).ruleCount,
-    health: null,
-    staleness: null,
-    morphology: morphologyOf(e.doc),
-  }));
-}
-
-function pad(s: string, width: number): string {
-  return s.length >= width ? s : s + ' '.repeat(width - s.length);
+  return entries.map((e) => {
+    const morphology = morphologyOf(e.doc);
+    return {
+      id: e.doc.header.capability ?? e.fileName,
+      title: e.doc.header.capability ?? e.fileName,
+      purpose: e.doc.header.purpose ?? '',
+      validScope: (e.doc.header.scope ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s !== ''),
+      requirementCount: morphology.ruleCount,
+      health: null,
+      staleness: null,
+      morphology,
+    };
+  });
 }
 
 export function renderSpecsList(summaries: readonly SpecSummary[]): string[] {

package/src/review/review.ts

@@ -50,15 +50,8 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
     (c) => c.totalTasks > 0 && c.completedTasks < c.totalTasks,
   );
   const signals: ReviewSignal[] = [];
-  let critical = 0;
-  let warning = 0;
   const push = (kind: ReviewKind, capability: string, count: number, detail = ''): void => {
     signals.push({ kind, capability, count, detail });
-    if (kind === 'validate') {
-      critical += count;
-    } else if (count > 0) {
-      warning += count;
-    }
   };
 
   const sweep = validateAllSpecs(entries, io);
@@ -103,13 +96,13 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
     'locked',
     '-',
     0,
-    `${boundChangeCount} bound change(s); inspect with \`llman sdd change diff <id>\``,
+    `${boundChangeCount} bound change(s); inspect with \`llman-sdd change diff <id>\``,
   );
   push(
     'validate',
     '-',
     failed.length,
-    failed.length > 0 ? 'validate --all failed; run `llman sdd validate --all` for details' : 'ok',
+    failed.length > 0 ? 'validate --all failed; run `llman-sdd validate --all` for details' : 'ok',
   );
 
   const warningCount = signals
@@ -140,3 +133,35 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
     exitCode: criticalCount > 0 ? 1 : 0,
   };
 }
+
+/** `review --export-html`: fill the v1 shared/review.html template (pure —
+ * callers read the template; CLI passes it via core's TEMPLATES_ROOT). */
+export function renderReviewHtml(
+  template: string,
+  result: {
+    signals: readonly { kind: string; capability: string; count: number; detail: string }[];
+    summary: { criticalCount: number; warningCount: number };
+  },
+): string {
+  const esc = (input: string): string =>
+    input
+      .replaceAll('&', '&amp;')
+      .replaceAll('<', '&lt;')
+      .replaceAll('>', '&gt;')
+      .replaceAll('"', '&quot;');
+  let mermaid = 'graph TD\n';
+  const sigJson: unknown[] = [];
+  result.signals.forEach((s, idx) => {
+    const label = esc(
+      `${s.capability} [${s.kind}] = ${s.count} — ${s.detail === '' ? 'ok' : s.detail}`,
+    );
+    mermaid += `    s${idx}["${label}"]\n`;
+    sigJson.push({ kind: s.kind, capability: s.capability, count: s.count, detail: s.detail });
+  });
+  return template
+    .replaceAll('__CRITICAL__', String(result.summary.criticalCount))
+    .replaceAll('__WARNING__', String(result.summary.warningCount))
+    .replaceAll('__SIGNALS__', JSON.stringify(sigJson))
+    .replaceAll('__MERMAID__', mermaid)
+    .replaceAll('__GENERATED__', new Date().toISOString());
+}