@llman-sdd/core 0.1.2 → 0.1.4

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());
+}

package/src/spec/ir.ts

@@ -41,3 +41,10 @@ export interface CapabilityDoc {
   scenarios: ScenarioIR[];
   errors: SpecStructuralError[];
 }
+
+/**
+ * v1 wording: constraint statements must contain one of these tokens.
+ * Shared by the parser (structural error) and validation (verdict gate) so
+ * the two MUST-word checks cannot drift apart.
+ */
+export const MUST_WORD_RE = /\bMUST\b|\bSHALL\b|必须|不得|禁止/u;

package/src/spec/parser.ts

@@ -9,7 +9,13 @@
 import { AstBuilder, GherkinClassicTokenMatcher, Parser } from '@cucumber/gherkin';
 import type { GherkinDocument } from '@cucumber/messages';
 
-import type { CapabilityDoc, CapabilityHeader, ScenarioIR, SpecStructuralError } from './ir.ts';
+import {
+  MUST_WORD_RE,
+  type CapabilityDoc,
+  type CapabilityHeader,
+  type ScenarioIR,
+  type SpecStructuralError,
+} from './ir.ts';
 
 export class SpecParseError extends Error {}
 
@@ -73,7 +79,6 @@ function classify(tags: string[]): {
   classification: ScenarioIR['classification'];
   manual: boolean;
   errors: SpecStructuralError[];
-  name: string;
 } {
   const errors: SpecStructuralError[] = [];
   const has = (t: string): boolean => tags.includes(t);
@@ -99,7 +104,7 @@ function classify(tags: string[]): {
     : executable
       ? 'executable'
       : 'unclassified';
-  return { classification, manual, errors, name: label };
+  return { classification, manual, errors };
 }
 
 /** Parse one capability .feature source into the single-track IR. */
@@ -148,7 +153,7 @@ export function parseCapability(source: string, fileName = '<inline>'): Capabili
       text: s.text.trim(),
     }));
 
-    if (kind.classification === 'human' && !/\bMUST\b|\bSHALL\b/u.test(statement)) {
+    if (kind.classification === 'human' && !MUST_WORD_RE.test(statement)) {
       errors.push({
         code: 'rule:missing-must-word',
         message: `@human 规则场景描述必须含 MUST/SHALL(scenario: ${scenario.name})`,

package/src/templates/embedded.ts

@@ -0,0 +1,68 @@
+/**
+ * Embedded template table for single-file binaries.
+ *
+ * Bun 1.4.x offers no embedding that survives our Node >= 24 dual-runtime
+ * constraint: `with { type: "text" }` works in compiled output (probed on
+ * 1.4.2) but Node cannot load that attribute, and `assets`/`?raw`/`?asset`
+ * never land in the bundle — so templates are injected through the same
+ * build-time `define` mechanism as LLMAN_SDD_VERSION: build-binary.ts
+ * collects packages/core/templates into a root-relative path→content map and
+ * sets process.env.LLMAN_SDD_EMBEDDED_TEMPLATES to that JSON. Bun inlines
+ * define values as raw expressions — the JSON is a valid object literal, so
+ * in the compiled binary the expression IS the table object itself, while a
+ * JSON string reaches these callers through the same expression in other
+ * engines or when force-set via env. Both forms are accepted below; every
+ * non-compiled run (source, npm package, Node) leaves the define unset and
+ * falls back to the real filesystem via TEMPLATES_ROOT.
+ */
+import type { TemplateIo } from './skills.ts';
+
+function isTable(value: unknown): value is Record<string, string> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Normalize a define/raw value into the template table; undefined when bad. */
+export function resolveEmbeddedTable(value: unknown): Record<string, string> | undefined {
+  if (value === undefined || value === '') return undefined;
+  if (isTable(value)) return value;
+  if (typeof value === 'string') {
+    try {
+      const table: unknown = JSON.parse(value);
+      if (isTable(table)) return table;
+    } catch {
+      // A malformed define must not silently yield a half-broken binary; treat
+      // as absent so the missing file surfaces loudly on first read.
+    }
+  }
+  return undefined;
+}
+
+/** Read the build-injected table; undefined when absent or malformed. */
+export function embeddedTemplates(): Record<string, string> | undefined {
+  return resolveEmbeddedTable(process.env.LLMAN_SDD_EMBEDDED_TEMPLATES);
+}
+
+/**
+ * Embedded keys are relative to the templates root while callers address
+ * files by `join(TEMPLATES_ROOT, rel)`, so the key is the segment after the
+ * last `/templates/` boundary — correct for both source-mode (repository
+ * path) and $bunfs-mode (`/$bunfs/root/...` → `/templates/...`) roots.
+ */
+export function templateKeyFor(path: string): string {
+  const marker = '/templates/';
+  const idx = path.lastIndexOf(marker);
+  return idx === -1 ? path : path.slice(idx + marker.length);
+}
+
+/** TemplateIo over the embedded table (no filesystem access). */
+export function makeEmbeddedTemplateIo(table: Record<string, string>): TemplateIo {
+  return {
+    exists: (p: string): boolean => templateKeyFor(p) in table,
+    readText: (p: string): string => {
+      const key = templateKeyFor(p);
+      const content = table[key];
+      if (content === undefined) throw new Error(`embedded template not found: ${key}`);
+      return content;
+    },
+  };
+}

package/src/templates/engine.ts

@@ -27,8 +27,9 @@ export function renderWithUnits(
     throw new Error(`unit nesting exceeded ${MAX_UNIT_NESTING_DEPTH}`);
   }
   // minijinja keep_trailing_newline=false: a single trailing newline of the
-  // template SOURCE is stripped before rendering (v1 parity).
-  const source = raw.replace(/\n$/u, '').replace(/\r\n$/u, '');
+  // template SOURCE is stripped before rendering (v1 parity). \r? first —
+  // stripping \n alone would strand a trailing \r for CRLF sources.
+  const source = raw.replace(/\r?\n$/u, '');
   const env = new nunjucks.Environment(null, { autoescape: false });
   for (const [key, value] of Object.entries(vars)) {
     env.addGlobal(key, value);

package/src/validation/validate.ts

@@ -4,6 +4,7 @@
  * filesystem access is injected via SpecIo.
  */
 import type { CapabilityDoc } from '../spec/ir.ts';
+import { MUST_WORD_RE } from '../spec/ir.ts';
 import { buildReqRegistry } from '../spec/reqRegistry.ts';
 
 export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
@@ -20,9 +21,6 @@ export interface SpecEntry {
   doc: CapabilityDoc;
 }
 
-/** v1 wording: constraint statements must contain one of these tokens. */
-const MUST_WORD_RE = /\bMUST\b|\bSHALL\b|必须|不得|禁止/u;
-
 export interface SpecIo {
   exists(path: string): boolean;
 }
@@ -83,9 +81,9 @@ export function validateCapability(
   // rule scenarios) — all ERROR level (v1 verdict parity). Header gates and
   // the MUST-word gate are owned by this layer (mapped below), so the
   // parser's duplicate findings are skipped here.
-  const OWNED_BY_THIS_LAYER = new Set(['missing-header:', 'rule:missing-must-word']);
+  const OWNED_BY_THIS_LAYER = ['missing-header:', 'rule:missing-must-word'];
   for (const err of doc.errors) {
-    if ([...OWNED_BY_THIS_LAYER].some((prefix) => err.code.startsWith(prefix))) continue;
+    if (OWNED_BY_THIS_LAYER.some((prefix) => err.code.startsWith(prefix))) continue;
     items.push({ level: 'ERROR', id: `${cap}/${err.code}`, message: err.message });
   }
 

package/templates/en/agents-root-stub.md

@@ -6,4 +6,4 @@ This project uses llman SDD. Read `llmanspec/config.yaml` for SDD command behavi
 
 Use `/llman-sdd-explore` to get started, then follow the pipeline: `/llman-sdd-propose` → `/llman-sdd-apply` → `/llman-sdd-verify` → `/llman-sdd-archive`.
 
-Keep this managed block so `llman sdd init --update` can refresh it.
+Keep this managed block so `llman-sdd init --update` can refresh it.

package/templates/en/skills/llman-sdd-apply-cycle.md

@@ -16,13 +16,13 @@ End-to-end closed loop for one change (manual). Requires Branch binding and `rea
 
 ### 0) Gate + status
 ```bash
-llman sdd show <change-id> --json --type change
+llman-sdd show <change-id> --json --type change
 ```
-> Stage gate: decide from `stage` / `readyToImplement` in `llman sdd show <id> --json --type change`; full decision table lives in llman-sdd-apply.
+> Stage gate: decide from `stage` / `readyToImplement` in `llman-sdd show <id> --json --type change`; full decision table lives in llman-sdd-apply.
 
 - Must be on the bound non-default branch.
 - If `readyToImplement` is not true → STOP (finish Specs landing or `needs_specs_change: false`); **do not** finalize yet.
-- Track progress via `tasks.md` checkboxes (or `llman sdd list` task counts); still read `tasks.md`, proposal/design, and live `llmanspec/specs/**` on the bound branch (SSOT).
+- Track progress via `tasks.md` checkboxes (or `llman-sdd list` task counts); still read `tasks.md`, proposal/design, and live `llmanspec/specs/**` on the bound branch (SSOT).
 
 ### 1) Loop: implement → test
 For each incomplete task:
@@ -33,7 +33,7 @@ For each incomplete task:
 
 ### 2) Validate
 ```bash
-llman sdd validate <change-id> --strict --no-interactive
+llman-sdd validate <change-id> --strict --no-interactive
 ```
 On failure, fix and retry (same self-repair budget as `llman-sdd-apply`: cap 8 rounds).
 
@@ -42,7 +42,7 @@ Prefer `llman-sdd-verify` (or equivalent dual-axis self-check). CRITICAL → STO
 
 ### 4) Archive
 ```bash
-llman sdd change finalize <change-id>
+llman-sdd change finalize <change-id>
 ```
 (dirty tree OK; auto merge (squash default) + docs rename + **auto commit** `archive(sdd): <change-id>` in one process. `--no-commit` skips the auto commit for manual/CI histories — then commit with `git add -A && git commit -m "archive(sdd): <change-id>"`.)
 
@@ -71,5 +71,5 @@ push / hosting PR only when the user explicitly asks.
 - `ethics.refusal_contract`: after 3 gate/validation failures, report blocker; do not force-archive
 - `ethics.escalation_policy`: if changing SDD workflow specs/templates, pause for user confirm before archive
 
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.

package/templates/en/skills/llman-sdd-apply.md

@@ -42,7 +42,7 @@ flowchart LR
 ## Commit Policy
 
 - **Commits on the change branch are free** (no mid-flight archive point; `change finalize` needs no clean tree): segment by task or milestone when it helps review, or keep the working tree dirty and let finalize make ONE close commit — both are first-class. `change checkpoint` no longer exists (calling it exits non-zero and points to finalize), so there is no mid-flight "archive point" to maintain; `change finalize` handles both shapes (it does NOT require a clean tree).
-- **Default close-out**: after all tasks pass gates and verify is green, `llman sdd change finalize <id>` auto-commits `archive(sdd): <change-id>` (uncommitted impl diff + frontmatter + archive rename in one commit). Do not run finalize inside the apply loop. `--no-commit` skips the auto commit (manual/CI histories; pre-commit-hook conflicts).
+- **Default close-out**: after all tasks pass gates and verify is green, `llman-sdd change finalize <id>` auto-commits `archive(sdd): <change-id>` (uncommitted impl diff + frontmatter + archive rename in one commit). Do not run finalize inside the apply loop. `--no-commit` skips the auto commit (manual/CI histories; pre-commit-hook conflicts).
 - **Blocker interrupt**: when you must STOP on a blocker, make ONE work-in-progress commit (e.g. `wip(sdd): <change-id> <summary>`) to preserve the state, then report.
 
 ## Steps
@@ -51,18 +51,18 @@ flowchart LR
 - Read and obey: `llmanspec/config.yaml`, `AGENTS.md` (if present).
 - `git status --porcelain`:
   - If working tree is dirty and changes don't belong to the current change: `git stash push -u -m "llman-sdd-apply autopilot backup"`.
-- Run `llman sdd validate --all --strict --no-interactive`:
+- Run `llman-sdd validate --all --strict --no-interactive`:
   - If it fails for reasons unrelated to the current change, stop and report (inconsistent artifacts prevent SSOT-driven implementation).
-- **Check spec valid_scope integrity**: use `llman sdd list --specs --json` to list all specs, then for each spec verify every path in its `valid_scope` exists on disk. If any scope file/directory is missing, stop and suggest updating the spec (remove the deleted path from `valid_scope`).
+- **Check spec valid_scope integrity**: use `llman-sdd list --specs --json` to list all specs, then for each spec verify every path in its `valid_scope` exists on disk. If any scope file/directory is missing, stop and suggest updating the spec (remove the deleted path from `valid_scope`).
 
 ### 1) Select change id and check prerequisites
 - If a change id is provided, use it directly.
-- Otherwise infer from context; if ambiguous, run `llman sdd list --json` and let user pick.
+- Otherwise infer from context; if ambiguous, run `llman-sdd list --json` and let user pick.
 - Always announce: "Using change: <id>" and how to override.
-- Confirm you are on the non-default feature branch bound via `llman sdd change start <id>` or `change attach <id>` (`--force` only to rebind). Specs/features on the branch are SSOT — do not author under `changes/<id>/specs/`.
+- Confirm you are on the non-default feature branch bound via `llman-sdd change start <id>` or `change attach <id>` (`--force` only to rebind). Specs/features on the branch are SSOT — do not author under `changes/<id>/specs/`.
 {{ unit("skills/stage-guard") }}
-- Use `llman sdd context --task "<goal from proposal>" --paths "<scope from specs>"` to get relevant specs.
-  - If context is unavailable, run `llman sdd index rebuild` and retry.
+- Use `llman-sdd context --task "<goal from proposal>" --paths "<scope from specs>"` to get relevant specs.
+  - If context is unavailable, run `llman-sdd index rebuild` and retry.
 
 ### 2) Read SSOT artifacts
 You must read through:
@@ -89,8 +89,8 @@ For each unchecked task:
 Run project gate commands (adapt to the actual project):
 - Relevant test suite: `just test` or `cargo test --all`
 - Format/lint: `just check` or `just lint` + `just fmt`
-- Git-native: stay on the bound feature branch; edit live `llmanspec/specs/<capability>.feature` (flat, or directory `llmanspec/specs/<capability>/` main file; rules `@human`, acceptance `@executable`) as needed; run `llman sdd validate --specs` after spec edits; commit on the branch freely (segmented or leave dirty for finalize). Do not use `change delta` / solidify / feature_delta; `change checkpoint` is removed.
-- SDD validation: `llman sdd validate <id> --strict --no-interactive`
+- Git-native: stay on the bound feature branch; edit live `llmanspec/specs/<capability>.feature` (flat, or directory `llmanspec/specs/<capability>/` main file; rules `@human`, acceptance `@executable`) as needed; run `llman-sdd validate --specs` after spec edits; commit on the branch freely (segmented or leave dirty for finalize). Do not use `change delta` / solidify / feature_delta; `change checkpoint` is removed.
+- SDD validation: `llman-sdd validate <id> --strict --no-interactive`
 
 **On failure → enter self-healing loop (don't ask "should I continue?"):**
 1. Parse failure cause (test failure / lint / format / validation error).
@@ -107,7 +107,7 @@ Run project gate commands (adapt to the actual project):
 
 **Self-healing cap: 8 rounds**; exceeding this is a blocker: stop and output a blocker report (last failing command + output summary + what you tried).
 
-**Human review checkpoint (after each task batch passes the gates)**: once a batch is green, before starting the next batch or producing the completion report, run `llman sdd review`:
+**Human review checkpoint (after each task batch passes the gates)**: once a batch is green, before starting the next batch or producing the completion report, run `llman-sdd review`:
 
 - Exit code zero → continue.
 - Non-zero exit = CRITICAL findings: STOP, fix, re-run review; MUST NOT enter the next batch or emit the completion report with CRITICAL findings open.
@@ -118,8 +118,8 @@ Then suggest running `llman-sdd-verify` for the verification phase.
 
 > 💡 Implementation done → next: `llman-sdd-verify` (verify)
 
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
 
 {{ unit("skills/validation-hints") }}
 

package/templates/en/skills/llman-sdd-arch-review.md

@@ -59,7 +59,7 @@ Run `llman-sdd-explore`'s **grilling branch** (trigger "deep-dig") to walk the d
 ## Output
 Candidate list (text; optional HTML report written to OS temp dir, not the repo) + the grilling decision record after the user picks one (write back to proposal; contract edits only via Specs landing into live `.feature`).
 
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
 
 {{ unit("skills/structured-protocol") }}

package/templates/en/skills/llman-sdd-archive.md

@@ -26,7 +26,7 @@ flowchart LR
 
 - **Must pass verify phase all-green first**: don't archive changes that haven't passed verification.
 - **Must already have Branch binding**: `change start` / `attach` done; otherwise STOP.
-- **SSOT validation**: every change must pass `llman sdd validate <id> --strict --no-interactive` before archiving.
+- **SSOT validation**: every change must pass `llman-sdd validate <id> --strict --no-interactive` before archiving.
 - **Don't ask "should I continue?"**: execute the full batch to completion unless you hit an unresolvable error.
 - **Close-out MUST NOT default to PR/push**: finalize performs a local merge (squash by default) + rename + one close-out commit (`archive(sdd): <id>`). `git push` / hosting PR are optional — only when the user or project explicitly requires remote review. **Agent MUST NOT** push or open a PR by default on this skill's account.
 
@@ -37,34 +37,34 @@ flowchart LR
 - If unexpected changes exist, handle them (stash or report).
 
 ### 1) Confirm target changes
-- Determine target IDs: single or batch (from user input or `llman sdd list --json`).
+- Determine target IDs: single or batch (from user input or `llman-sdd list --json`).
 - Always announce: "Archiving IDs: <id1>, <id2>, ...".
 - Confirm each change has passed verify phase all-green.
 
 ### 2) Archive one by one
-- **Human review checkpoint (before each id is archived, including batches)**: run `llman sdd review --capability <id>`. Exit code zero → continue; non-zero = CRITICAL findings: STOP, fix, re-run; MUST NOT archive with CRITICAL findings open.
-- Validate each first: `llman sdd validate <id> --strict --no-interactive`.
+- **Human review checkpoint (before each id is archived, including batches)**: run `llman-sdd review --capability <id>`. Exit code zero → continue; non-zero = CRITICAL findings: STOP, fix, re-run; MUST NOT archive with CRITICAL findings open.
+- Validate each first: `llman-sdd validate <id> --strict --no-interactive`.
 - Validation failure → STOP and report; don't skip validation and force archive.
-- Optional preview: `llman sdd change archive <id> --dry-run`.
+- Optional preview: `llman-sdd change archive <id> --dry-run`.
 - Execute archive:
-  - default: `llman sdd change archive <id>`
-  - tooling-only: `llman sdd change archive <id> --skip-specs`
+  - default: `llman-sdd change archive <id>`
+  - tooling-only: `llman-sdd change archive <id> --skip-specs`
   - **stop immediately on first failure**, report remaining unprocessed IDs.
 - **Git-native close-out**:
   - Prerequisites: Branch binding done (`change start` / `attach`); still on the bound branch (or the target branch after the auto merge).
   - `change archive` / `change finalize` run the **auto merge** (target `--into` > binding `base_branch` > default branch; method squash by default or `ff`; if the target is held by another worktree the merge is skipped with an explicit manual command), **then** rename change docs into `changes/archive/` — rename is never rolled back on merge failure and degradation is reported explicitly.
-  - Legacy `*.feature.delta.toon` or `spec.toon` under specs is a migration blocker — run `llman sdd project migrate --kind toon2features`.
+  - Legacy `*.feature.delta.toon` or `spec.toon` under specs is a migration blocker — run `llman-sdd project migrate --kind toon2features`.
   - **Default: `change finalize` (one-command close)** — gates → auto merge → docs rename → **auto commit** `archive(sdd): <change-id>` (squash default: impl diff + rename collapse into ONE commit on the target; no manual `git commit` needed; locked-rule edits are a report-only WARNING — warn, never block):
     ```text
     1. Implement live specs + code (working tree may stay dirty; commits on the branch are free — segmented or none)
-    2. llman sdd change finalize <id>    # gates + merge (squash default) + rename + auto commit
+    2. llman-sdd change finalize <id>    # gates + merge (squash default) + rename + auto commit
     3. optional: git commit --amend    # adjust the message; git branch -D <feature>  # after squash the branch is no longer an ancestor; -d gets refused
     ```
     `--no-commit` skips the auto commit (CI / pre-commit-hook conflicts): finalize then leaves the tree dirty and prints the manual `git commit` command. Idempotent retry: a rerun after a failed auto commit detects the already-archived rename and finishes the commit.
   - **Fallback: plain `change archive <id>`** — same merge + rename, no auto commit; requires a clean tree. `checkpointed`/`checkpoint_sha` fields went away with checkpoint (no mid-flight archive point; `change finalize` needs no clean tree) — nothing to write beforehand, and nothing to review for the snapshot (use `change diff` instead).
 
 ### 3) Full validation
-- After all archives complete: `llman sdd validate --all --strict --no-interactive`.
+- After all archives complete: `llman-sdd validate --all --strict --no-interactive`.
 - Confirm post-archive spec artifacts are consistent.
 
 ### 4) Commit guidance
@@ -77,8 +77,8 @@ flowchart LR
 
 {{ unit("workflow/archive-freeze-guidance") }}
 
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
 
 {{ unit("skills/validation-hints") }}
 

package/templates/en/skills/llman-sdd-continue.md

@@ -12,30 +12,30 @@ Use this skill to continue an existing change and create the next missing artifa
 ## Steps
 1. Identify the change id:
    - If provided by the user, use it.
-   - Otherwise run `llman sdd list --json` and ask which change to continue.
+   - Otherwise run `llman-sdd list --json` and ask which change to continue.
    - Always announce: "Using change: <id>".
 2. Read the change directory: `llmanspec/changes/<id>/`.
-> Stage gate: decide from `stage` / `readyToImplement` in `llman sdd show <id> --json --type change`; full decision table lives in llman-sdd-apply.
+> Stage gate: decide from `stage` / `readyToImplement` in `llman-sdd show <id> --json --type change`; full decision table lives in llman-sdd-apply.
 3. Determine the next artifact to create (in order):
    1) `proposal.md`
    2) `design.md` (only if design tradeoffs matter)
    3) `tasks.md`
-   4) `llman sdd change start <id>` (or `change attach <id>` if the branch already exists) — Branch binding
+   4) `llman-sdd change start <id>` (or `change attach <id>` if the branch already exists) — Branch binding
    5) Edit live `llmanspec/specs/<capability>.feature` (flat, or directory main file) on the **bound branch** and commit — Specs landing (or set `needs_specs_change: false` when there is no contract edit)
 4. Create exactly ONE missing artifact (or one live spec/feature edit on the bound branch).
    - Do NOT implement application code in continue mode.
    - Do NOT create `*.feature.delta.toon`, `spec.toon`, or files under `changes/<id>/specs/`.
    - Do NOT edit shared `llmanspec/specs/**` before start/attach.
-5. If all artifacts already exist, suggest next actions from `llman sdd show <id> --json`:
+5. If all artifacts already exist, suggest next actions from `llman-sdd show <id> --json`:
    - `readyToImplement=false` → finish Specs landing (or `needs_specs_change: false`); do **not** suggest apply yet
    - `readyToImplement=true` → Implement: `llman-sdd-apply`
    - After verify → Archive: `llman-sdd-archive`
-   - Validate: `llman sdd validate <id> --strict --no-interactive`
-   - Review: `llman sdd change diff <id>` (read-only)
+   - Validate: `llman-sdd validate <id> --strict --no-interactive`
+   - Review: `llman-sdd change diff <id>` (read-only)
 
 {{ unit("skills/git-native-flow") }}
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
 {{ unit("skills/validation-hints") }}
 
 {{ unit("skills/structured-protocol") }}

package/templates/en/skills/llman-sdd-draft.md

@@ -31,13 +31,13 @@ flowchart LR
 - **MUST NOT create tasks/design/specs/attach**: this skill creates only the `proposal.md` draft shell. Full planning artifacts belong to `llman-sdd-propose`.
 - **MUST NOT run triage or assess change scale**: that is propose's job. If the user wants to start implementing, suggest `llman-sdd-propose`.
 - **Scope boundary**: if the description clearly involves MUST/SHALL behavioral contract changes or multi-file impact, suggest `llman-sdd-propose` instead of stopping at a draft — but still create the draft shell first so the idea isn't lost.
-- **Frontmatter has a fixed schema**: when fleshing out `proposal.md`, only the allowed fields in `llmanspec/AGENTS.md` "Change Proposal Frontmatter SSOT" are accepted (including `depends_on`, `blocks`, `branch`, `base_sha`, `needs_specs_change`). `status`/`title`/`priority`/`author` etc. are rejected by `llman sdd validate` as ERROR. Lifecycle stage is inferred — query it via `llman sdd show`/`list`, never store it in frontmatter. Do not re-declare frontmatter fields in the prose body (no `## Status` block); the body H1 is a human-readable title, not a repeat of the change id.
+- **Frontmatter has a fixed schema**: when fleshing out `proposal.md`, only the allowed fields in `llmanspec/AGENTS.md` "Change Proposal Frontmatter SSOT" are accepted (including `depends_on`, `blocks`, `branch`, `base_sha`, `needs_specs_change`). `status`/`title`/`priority`/`author` etc. are rejected by `llman-sdd validate` as ERROR. Lifecycle stage is inferred — query it via `llman-sdd show`/`list`, never store it in frontmatter. Do not re-declare frontmatter fields in the prose body (no `## Status` block); the body H1 is a human-readable title, not a repeat of the change id.
 
 ## Steps
 
 ### 0) Preflight
 - Read `llmanspec/config.yaml` for project context, rules, locale.
-- `llmanspec/` must exist; if missing, tell the user to run `llman sdd init`, then STOP.
+- `llmanspec/` must exist; if missing, tell the user to run `llman-sdd init`, then STOP.
 
 ### 1) Capture the description
 - Take the user's description as-is (e.g. "draft: add a export-to-json command", "note down: we should support worktrees for sdd changes").
@@ -45,7 +45,7 @@ flowchart LR
 
 ### 2) Create the draft shell
 ```bash
-llman sdd change new --from "<user description>"
+llman-sdd change new --from "<user description>"
 ```
 - The CLI generates a legal kebab-case id (sanitized + validated), creates `llmanspec/changes/<derived id>/proposal.md` (a skeleton with `## Why` / `## What Changes` TODO sections), and prints the final id + path.
 - If the derived id collides with an existing change, the CLI fails non-zero; suggest rephrasing the description or using `--force` to overwrite (rare for drafts).
@@ -58,7 +58,7 @@ llman sdd change new --from "<user description>"
 
 > 💡 Draft captured → next: edit `proposal.md`, then `llman-sdd-propose` to formalize.
 
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
 
 {{ unit("skills/ethics-governance") }}

package/templates/en/skills/llman-sdd-explore.md

@@ -43,9 +43,9 @@ flowchart LR
 - Willing to hold multiple options and tradeoffs
 
 ## Suggested moves
-1. Use `llman sdd context --task "<task>" --paths "<files>"` to quickly locate relevant specs.
+1. Use `llman-sdd context --task "<task>" --paths "<files>"` to quickly locate relevant specs.
    - Read the `direct` spec files (these are the contracts you must understand).
-   - If context is unavailable, rebuild with `llman sdd index rebuild` (default `pageindex`, no model needed) and retry.
+   - If context is unavailable, rebuild with `llman-sdd index rebuild` (default `pageindex`, no model needed) and retry.
 2. Clarify the goal and constraints (ask 1–3 questions).
 3. **Grilling branch (optional, only when the user explicitly triggers)**: triggers on "deep-dig" / "grill" / "one at a time" / "nail it down". Walks the decision tree one question at a time:
    - **Ask one question at a time**, with your recommended answer, waiting for feedback before the next.
@@ -54,7 +54,7 @@ flowchart LR
    - **Write decisions back**: resolved decisions go into the change's `proposal.md` "Open Questions" section (planning shell; OK briefly on the default branch).
    - **Completion criterion**: every pending decision is resolved or explicitly deferred. When not triggered, the default (ask 1–3 questions) behavior is unchanged.
 4. If a change id is relevant, read its artifacts under `llmanspec/changes/<id>/`.
-   - When diagnosing validation errors, prefer `llman sdd validate <spec> --strict --no-check` (fast mode, skips the potentially slow `bdd.run_command`); resolve structural gates first (Gherkin / `@req` linkage / dual-write / req_id uniqueness), then run full mode (`--check` or `cargo test --features bdd`). The `FAIL <item_type>/<id>` lines in the output pin down each failing item.
+   - When diagnosing validation errors, prefer `llman-sdd validate <spec> --strict --no-check` (fast mode, skips the potentially slow `bdd.run_command`); resolve structural gates first (Gherkin / `@req` linkage / dual-write / req_id uniqueness), then run full mode (`--check` or `cargo test --features bdd`). The `FAIL <item_type>/<id>` lines in the output pin down each failing item.
 5. Explore options and tradeoffs (2–3 options).
 6. Assess change scale (triage) to determine if full SDD is needed.
 7. When something crystallizes, offer to capture it (don't auto-write):
@@ -72,7 +72,7 @@ If the user asks you to implement while in explore mode, STOP and remind them to
 
 > 💡 Explore done → next: `llman-sdd-propose` (propose) or `llman-sdd-quick` (quick path)
 
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
 
 {{ unit("skills/structured-protocol") }}

package/templates/en/skills/llman-sdd-ff.md

@@ -19,20 +19,20 @@ Run the propose-equivalent path quickly: planning shell → Branch binding → S
 ## Steps
 
 1. Ask the user for a short description, change id (or derive), impacted capability, and confirm the final id.
-2. Ensure `llman sdd init` has been run (`llmanspec/` exists).
+2. Ensure `llman-sdd init` has been run (`llmanspec/` exists).
 3. If `llmanspec/changes/<id>/` exists: ask fill-missing vs new id; do not overwrite without confirmation.
 4. Create the **planning shell** (OK briefly on the default branch):
-   - `llman sdd change new <id>` (or hand-write) → flesh out `proposal.md`
+   - `llman-sdd change new <id>` (or hand-write) → flesh out `proposal.md`
    - `design.md` (if needed)
    - `tasks.md`
-5. **Branch binding**: `llman sdd change start <id>` (clean tree on default branch) or create a branch then `change attach <id>`.
+5. **Branch binding**: `llman-sdd change start <id>` (clean tree on default branch) or create a branch then `change attach <id>`.
 6. **Specs landing**: on the bound branch, edit live `llmanspec/specs/<capability>.feature` (flat, or directory main file) and commit; or set `needs_specs_change: false` when there is no contract edit.
-7. Validate: `llman sdd validate <id> --strict --no-interactive`.
-8. Confirm `readyToImplement=true` via `llman sdd show <id> --json`, then suggest `llman-sdd-apply` (do not suggest apply before ready).
+7. Validate: `llman-sdd validate <id> --strict --no-interactive`.
+8. Confirm `readyToImplement=true` via `llman-sdd show <id> --json`, then suggest `llman-sdd-apply` (do not suggest apply before ready).
 
 {{ unit("skills/git-native-flow-brief") }}
-> For command details run `llman sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman sdd list --specs` or `llman sdd show <capability>`.
+> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
+> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
 {{ unit("skills/validation-hints") }}
 
 {{ unit("skills/ethics-governance") }}