@llman-sdd/core 0.3.1 → 0.5.1

package/src/spec/reqRegistry.ts

@@ -1,37 +1,53 @@
 /**
- * Global rN registry (spec-parsing capability): @req:rN ids form a single
- * global namespace across all capability specs; duplicates are reported with
- * the conflicting file pairs.
+ * Global rN registry (spec-parsing capability): @req:rN ids on `规则:` blocks
+ * form a single global namespace across all capability specs. A duplicate is
+ * any id carried by more than one rule — within one file or across files
+ * (r10: 按携带该 id 的规则条数 > 1 判定).
  */
 import type { CapabilityDoc } from './ir.ts';
 
+export interface RegistryOccurrence {
+  fileName: string;
+  /** 0-based index of the rule within its doc (in-file locating). */
+  ruleIndex: number;
+  title: string;
+}
+
 export interface RegistryDuplicate {
   reqId: string;
+  /** Unique files referencing the id (sorted, display surface). */
   files: string[];
+  /** Every rule occurrence referencing the id, in scan order. */
+  occurrences: RegistryOccurrence[];
 }
 
 export interface ReqRegistry {
-  /** reqId → files referencing it (sorted). */
-  byId: Map<string, string[]>;
+  /** reqId → every rule occurrence referencing it (scan order). */
+  byId: Map<string, RegistryOccurrence[]>;
   duplicates: RegistryDuplicate[];
 }
 
 export function buildReqRegistry(
   docs: readonly { fileName: string; doc: CapabilityDoc }[],
 ): ReqRegistry {
-  const byId = new Map<string, string[]>();
+  const byId = new Map<string, RegistryOccurrence[]>();
   for (const { fileName, doc } of docs) {
-    for (const scenario of doc.scenarios) {
-      for (const reqId of scenario.reqIds) {
-        const files = byId.get(reqId) ?? [];
-        if (!files.includes(fileName)) files.push(fileName);
-        byId.set(reqId, files);
-      }
-    }
+    doc.rules.forEach((rule, ruleIndex) => {
+      if (rule.reqId === '') return;
+      const occurrences = byId.get(rule.reqId) ?? [];
+      occurrences.push({ fileName, ruleIndex, title: rule.title });
+      byId.set(rule.reqId, occurrences);
+    });
   }
   const duplicates: RegistryDuplicate[] = [];
-  for (const [reqId, files] of byId) {
-    if (files.length > 1) duplicates.push({ reqId, files: files.toSorted() });
+  for (const [reqId, occurrences] of byId) {
+    if (occurrences.length > 1) {
+      duplicates.push({
+        reqId,
+        files: [...new Set(occurrences.map((o) => o.fileName))].toSorted(),
+        occurrences,
+      });
+    }
   }
   duplicates.sort((a, b) => a.reqId.localeCompare(b.reqId));
   return { byId, duplicates };

package/src/templates/embedded.ts

@@ -1,19 +1,13 @@
 /**
  * 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.
+ * Compiled binaries receive the table through the same build-time define
+ * mechanism as the version (see apps/cli/src/cli-shared.ts — the define read
+ * lives at the CLI seam, core only receives already-resolved values). Bun
+ * inlines define values as raw expressions; both the JSON-string form and a
+ * pre-parsed object literal are accepted below. Every non-compiled run
+ * (source, npm package, Node) leaves the value unset and falls back to the
+ * real filesystem via TEMPLATES_ROOT.
  */
 import type { TemplateIo } from './skills.ts';
 
@@ -37,9 +31,9 @@ export function resolveEmbeddedTable(value: unknown): Record<string, string> | u
   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);
+/** Resolve the caller-passed define value; undefined when absent or malformed. */
+export function embeddedTemplates(raw?: unknown): Record<string, string> | undefined {
+  return resolveEmbeddedTable(raw);
 }
 
 /**

package/src/templates/engine.ts

@@ -1,6 +1,6 @@
 /**
  * Template engine (init-generators capability, r17): nunjucks adapter with
- * minijinja-compatible semantics used by v1 — string-only globals, undefined
+ * minijinja-compatible semantics used by predecessor — string-only globals, undefined
  * renders empty (Lenient), nested `unit(id)` expansion capped at 32, and
  * trailing whitespace trimmed from the final product.
  */
@@ -22,22 +22,26 @@ export function renderWithUnits(
   units: UnitRegistry,
   vars: Record<string, string>,
   depth = 0,
+  opts: { throwOnUndefined?: boolean } = {},
 ): string {
   if (depth > MAX_UNIT_NESTING_DEPTH) {
     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). \r? first —
+  // template SOURCE is stripped before rendering (predecessor 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 });
+  const env = new nunjucks.Environment(null, {
+    autoescape: false,
+    throwOnUndefined: opts.throwOnUndefined === true,
+  });
   for (const [key, value] of Object.entries(vars)) {
     env.addGlobal(key, value);
   }
   env.addGlobal('unit', (id: string): string => {
     const content = units.get(id);
     if (content === undefined) throw new MissingUnitError(id);
-    return renderWithUnits(content, units, vars, depth + 1);
+    return renderWithUnits(content, units, vars, depth + 1, opts);
   });
   return env.renderString(source, {});
 }
@@ -47,6 +51,7 @@ export function renderTemplate(
   raw: string,
   units: UnitRegistry,
   vars: Record<string, string>,
+  opts: { throwOnUndefined?: boolean } = {},
 ): string {
-  return renderWithUnits(raw, units, vars, 0).trimEnd();
+  return renderWithUnits(raw, units, vars, 0, opts).trimEnd();
 }

package/src/templates/locale.ts

@@ -1,6 +1,6 @@
 /**
  * Locale normalization + fallback chain (init-generators capability, r18).
- * Port of v1 config.rs normalize_locale / locale_fallbacks.
+ * Port of predecessor config.rs normalize_locale / locale_fallbacks.
  */
 export function normalizeLocale(value: string): string {
   const trimmed = value.trim();

package/src/templates/skills.ts

@@ -2,7 +2,7 @@ import type { SddConfig } from '../config/schema.ts';
 import { renderTemplate, type UnitRegistry } from './engine.ts';
 /**
  * Skills rendering + init orchestration (init-generators capability, r19).
- * Port of v1 templates.rs / update_skills.rs / init.rs semantics.
+ * Port of predecessor templates.rs / update_skills.rs / init.rs semantics.
  */
 import { localeFallbacks } from './locale.ts';
 
@@ -37,6 +37,7 @@ export const UNIT_FILES: readonly string[] = [
   'skills/ethics-governance.md',
   'spec/feature-contract.md',
   'skills/structured-protocol.md',
+  'skills/cli-footer.md',
   'workflow/archive-freeze-guidance.md',
 ];
 
@@ -48,7 +49,7 @@ export const ETHICS_KEYS: readonly string[] = [
   'ethics.escalation_policy',
 ];
 
-/** Framework-derived run_command (v1 config.rs effective_run_command). */
+/** Framework-derived run_command (predecessor config.rs effective_run_command). */
 export function effectiveRunCommand(bdd: NonNullable<SddConfig['bdd']>): string {
   if (bdd.run_command) return bdd.run_command;
   switch (bdd.framework ?? '') {
@@ -65,15 +66,13 @@ export function effectiveRunCommand(bdd: NonNullable<SddConfig['bdd']>): string
   }
 }
 
-/** All-string globals (v1 BTreeMap<String, String> semantics). */
+/** All-string globals (predecessor BTreeMap<String, String> semantics). */
 export function buildTemplateVars(config: SddConfig, version: string): Record<string, string> {
   const vars: Record<string, string> = { llman_version: version };
   if (config.bdd) {
     vars['bdd_enabled'] = 'true';
     vars['bdd_framework'] = config.bdd.framework ?? '';
-    if (config.bdd.feature_dir) vars['bdd_feature_dir'] = config.bdd.feature_dir;
     vars['bdd_run_command'] = effectiveRunCommand(config.bdd);
-    if (config.bdd.default_language) vars['bdd_default_language'] = config.bdd.default_language;
     if (config.bdd.verify_prompt) vars['bdd_verify_prompt'] = config.bdd.verify_prompt;
   }
   const extras = new Set<string>(config.extra_skills ?? []);

package/src/validation/changeCheck.ts

@@ -1,6 +1,13 @@
-import { readBinding } from '../change/frontmatter.ts';
+import { stageFor, walkActiveChangeDirs } from '../change/collect.ts';
+import {
+  extractFrontmatter,
+  readBinding,
+  readNeedsSpecsChange,
+  specsLanded,
+} from '../change/frontmatter.ts';
+import { CLOSE_OUT_TASK_HINT, closeOutTaskLines, parseTaskCheckboxes } from '../change/tasks.ts';
 /**
- * Change-domain validation (v1 `commands/validate.rs` change path parity):
+ * Change-domain validation (predecessor `commands/validate.rs` change path parity):
  * frontmatter/depends_on gates, design/tasks constraints, completeness stage
  * INFO, pattern gate and task gates. IO + git injected (pure).
  */
@@ -10,7 +17,7 @@ export type ChangeIssueLevel = 'ERROR' | 'WARNING' | 'INFO';
 
 export interface ChangeIssue {
   level: ChangeIssueLevel;
-  /** v1-style anchor (issue path), e.g. `proposal.md/frontmatter.depends_on`. */
+  /** predecessor-style anchor (issue path), e.g. `proposal.md/frontmatter.depends_on`. */
   path: string;
   message: string;
 }
@@ -25,7 +32,6 @@ export interface ChangeCheckInput {
 
 export interface ChangeCheckConfig {
   strict_defer?: boolean | null;
-  min_completion_ratio?: number | null;
   change_id_pattern?: string | null;
 }
 
@@ -38,6 +44,62 @@ export interface ChangeFsIoLite {
 
 export const STAGE_ORDER = ['draft', 'designed', 'planned', 'full'] as const;
 
+/**
+ * r73 dependency-reference resolution: `active` matches a leaf change dir by
+ * name (nested groups included — same caliber as the CLI change scan),
+ * `archived` matches an `archive/<YYYY-MM-DD>-<id>` dir OR a flat frozen card
+ * `archive/<YYYY-MM-DD>-<id>.yaml` exactly (a suffix like
+ * `2026-01-01-the-other` must NOT satisfy id `other`). A missing
+ * `archive/` dir reads as empty and never throws.
+ */
+function resolveChangeRef(
+  io: ChangeFsIoLite,
+  changesRoot: string,
+  id: string,
+): 'active' | 'archived' | 'unknown' {
+  let active = false;
+  walkActiveChangeDirs(io, changesRoot, (_dir, name) => {
+    if (name === id) active = true;
+  });
+  if (active) return 'active';
+  const archive = `${changesRoot}/archive`;
+  const entries = io.exists(archive) && io.isDirectory(archive) ? io.listDir(archive) : [];
+  // `YYYY-MM-DD-` is 11 chars; the remainder must equal the id exactly.
+  const archived = entries.some((name) => {
+    if (!/^\d{4}-\d{2}-\d{2}-/u.test(name)) return false;
+    const base = name.endsWith('.yaml') ? name.slice(0, -'.yaml'.length) : name;
+    return base.slice(11) === id;
+  });
+  return archived ? 'archived' : 'unknown';
+}
+
+/**
+ * r87: global change-id uniqueness gate. Enumerates active change ids (leaf
+ * dir names), archived dir ids and frozen-card ids, and returns every id that
+ * appears more than once across the whole set. This is the cheap, enumerable
+ * form of the uniqueness contract: frozen ids are no longer hidden inside the
+ * cold backup, so collisions are checkable without thawing.
+ */
+export function checkGlobalChangeIdUniqueness(io: ChangeFsIoLite, changesRoot: string): string[] {
+  const archive = `${changesRoot}/archive`;
+  const entries = io.exists(archive) && io.isDirectory(archive) ? io.listDir(archive) : [];
+  const counts = new Map<string, number>();
+  walkActiveChangeDirs(io, changesRoot, (_dir, name) => {
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  });
+  for (const name of entries) {
+    if (!/^\d{4}-\d{2}-\d{2}-/u.test(name)) continue;
+    const base = name.endsWith('.yaml') ? name.slice(0, -'.yaml'.length) : name;
+    const id = base.slice(11);
+    if (id === '') continue;
+    counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+  return [...counts]
+    .filter(([, n]) => n > 1)
+    .map(([id]) => id)
+    .toSorted((a, b) => a.localeCompare(b));
+}
+
 export type StageGate = (typeof STAGE_ORDER)[number];
 
 export interface ChangeCheckResult {
@@ -46,11 +108,14 @@ export interface ChangeCheckResult {
   issues: ChangeIssue[];
 }
 
-/** Legacy pure gate (r47 surface) — kept for existing callers/tests. */
+/**
+ * Legacy pure gate (r47 surface) — structural checks only (tasks, binding,
+ * pattern); the stage-ordinal branch was removed with the dual-caliber gate
+ * (the artifact-presence `--stage` gate lives in validateChange).
+ */
 export function checkChangeDoc(
   input: ChangeCheckInput,
   config: ChangeCheckConfig,
-  opts: { stage?: StageGate } = {},
 ): ChangeCheckResult {
   const issues: ChangeIssue[] = [];
   if (input.totalTasks > 0 && input.completedTasks < input.totalTasks) {
@@ -61,18 +126,6 @@ export function checkChangeDoc(
       message: `${pending} unchecked task(s) in tasks.md`,
     });
   }
-  if (
-    config.min_completion_ratio !== undefined &&
-    config.min_completion_ratio !== null &&
-    input.totalTasks > 0 &&
-    input.completedTasks / input.totalTasks < config.min_completion_ratio
-  ) {
-    issues.push({
-      level: 'ERROR',
-      path: 'tasks.md',
-      message: `completion ratio below archive.min_completion_ratio (${config.min_completion_ratio})`,
-    });
-  }
   if (!input.hasBinding) {
     issues.push({
       level: 'WARNING',
@@ -81,23 +134,20 @@ export function checkChangeDoc(
     });
   }
   if (config.change_id_pattern) {
-    const re = new RegExp(config.change_id_pattern, 'u');
-    if (!re.test(input.name)) {
+    try {
+      const re = new RegExp(config.change_id_pattern, 'u');
+      if (!re.test(input.name)) {
+        issues.push({
+          level: 'ERROR',
+          path: 'change-id',
+          message: `Change id '${input.name}' does not match change_id.pattern '${config.change_id_pattern}' (active changes only; archived changes are not re-checked).`,
+        });
+      }
+    } catch (error) {
       issues.push({
         level: 'ERROR',
         path: 'change-id',
-        message: `Change id '${input.name}' does not match change_id.pattern '${config.change_id_pattern}' (sdd-workflow r29; scope: active changes only, archive/legacy shapes are not back-checked).`,
-      });
-    }
-  }
-  if (opts.stage !== undefined) {
-    const currentIdx = STAGE_ORDER.indexOf(input.stage);
-    const requiredIdx = STAGE_ORDER.indexOf(opts.stage);
-    if (currentIdx < requiredIdx) {
-      issues.push({
-        level: 'ERROR',
-        path: 'stage',
-        message: `stage \`${input.stage}\` is below the required \`${opts.stage}\``,
+        message: `change_id.pattern is not a valid regular expression: ${(error as Error).message}`,
       });
     }
   }
@@ -108,17 +158,17 @@ export type ChangeValidationConfig = ChangeCheckConfig;
 
 const COMPLETENESS: Record<string, string> = {
   draft:
-    "Change is in 'draft' stage (next: add design.md + tasks.md, then `llman sdd change start <id>` to enter a feature branch)",
+    "Change is in 'draft' stage (next: add design.md + tasks.md, then `llman-sdd change start <id>` to enter a feature branch)",
   designed:
-    "Change is in 'designed' stage (next: add tasks.md to reach 'planned', then `llman sdd change start` to enter feature branch and reach 'full')",
+    "Change is in 'designed' stage (next: add tasks.md to reach 'planned', then `llman-sdd change start` to enter feature branch and reach 'full')",
   planned:
-    "Change is in 'planned' stage (next: `llman sdd change start` to enter feature branch and reach 'full')",
-  full: "Change is bound and stage is 'full' (verify readiness via `llman sdd show <id> --json` readyToImplement)",
+    "Change is in 'planned' stage (next: `llman-sdd change start` to enter feature branch and reach 'full')",
+  full: "Change is bound and stage is 'full' (verify readiness via `llman-sdd show <id> --json` readyToImplement)",
 };
 
 /**
- * File-aware change validation with v1 messages/paths (used by the validate
- * command). `strict` escalates WARNING issues to ERROR (v1 build_report).
+ * File-aware change validation with predecessor messages/paths (used by the validate
+ * command). `strict` escalates WARNING issues to ERROR (predecessor build_report).
  * `git` (optional) enables the r63 completeness WARNINGs — Full-not-ready
  * with skill guidance, per change.
  */
@@ -137,12 +187,15 @@ export function validateChange(
   const dir = `${root}/llmanspec/changes/${id}/`;
   const baseDir = `${root}/llmanspec/changes`;
   const proposal = `${dir}proposal.md`;
+  // Probed once here: shared by the stage inference below and the --stage
+  // artifact gate at the end (predecessor issue order preserved).
+  const hasDesign = io.exists(`${dir}design.md`);
+  const hasTasks = io.exists(`${dir}tasks.md`);
   if (!io.exists(proposal)) {
     push('ERROR', 'proposal.md', 'Change is missing proposal.md.');
   } else {
     const text = io.readText(proposal);
-    const fmMatch = text.match(/^---\n([\s\S]*?)\n---/u);
-    const fm = fmMatch?.[1] ?? '';
+    const fm = extractFrontmatter(text) ?? '';
     const fmLines = fm.split('\n').map((l) => l.trim());
 
     for (const key of ['depends_on', 'blocks'] as const) {
@@ -180,13 +233,7 @@ export function validateChange(
           );
           continue;
         }
-        const depDir = `${baseDir}/${item}`;
-        const archived = `${baseDir}/archive`;
-        if (
-          !io.exists(`${depDir}/proposal.md`) &&
-          !io.exists(dir.replace(/\/[^/]+\/$/u, '/archive/')) &&
-          !io.listDir(archived).some((n) => n.endsWith(`-${item}`))
-        ) {
+        if (resolveChangeRef(io, baseDir, item) === 'unknown') {
           push(
             'ERROR',
             `proposal.md/frontmatter.${key}`,
@@ -196,7 +243,7 @@ export function validateChange(
       }
     }
 
-    // Unknown frontmatter field gate (v1).
+    // Unknown frontmatter field gate (predecessor).
     for (const l of fmLines) {
       if (l === '' || l.startsWith('-') || l.startsWith('#')) continue;
       const m = l.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:/u);
@@ -204,22 +251,14 @@ export function validateChange(
         push(
           'ERROR',
           'proposal.md/frontmatter',
-          `proposal.md frontmatter has unknown field '${m[1]}'; allowed fields are: ${ALLOWED_FIELDS.join(', ')}. Stage is inferred from on-disk artifacts (run \`llman sdd show\` / \`llman sdd list\`); do not store lifecycle state in frontmatter.`,
+          `proposal.md frontmatter has unknown field '${m[1]}'; allowed fields are: ${ALLOWED_FIELDS.join(', ')}. Stage is inferred from on-disk artifacts (run \`llman-sdd show\` / \`llman-sdd list\`); do not store lifecycle state in frontmatter.`,
         );
       }
     }
 
-    const hasDesign = io.exists(`${dir}design.md`);
-    const hasTasks = io.exists(`${dir}tasks.md`);
     const binding = readBinding(text);
-    const stage =
-      hasDesign && hasTasks
-        ? binding !== null
-          ? 'full'
-          : 'planned'
-        : hasDesign
-          ? 'designed'
-          : 'draft';
+    // stageFor (change/collect) is the monotonic stage SSOT (r34).
+    const stage = stageFor(hasDesign, hasTasks, binding !== null);
 
     if (hasTasks && !hasDesign) {
       push(
@@ -230,16 +269,7 @@ export function validateChange(
     }
 
     if (hasTasks) {
-      const tasks = io.readText(`${dir}tasks.md`);
-      let total = 0;
-      let completed = 0;
-      for (const line of tasks.split('\n')) {
-        const m = line.match(/^\s*-\s+\[( |x|X)\]/u);
-        if (m) {
-          total += 1;
-          if (m[1] !== ' ') completed += 1;
-        }
-      }
+      const { completed, total, pendingLines } = parseTaskCheckboxes(io.readText(`${dir}tasks.md`));
       if (total > 0 && completed < total) {
         const n = total - completed;
         push(
@@ -248,31 +278,41 @@ export function validateChange(
           `${n} unchecked task(s) in tasks.md`,
         );
       }
+      // D9/B23 (active changes only — validate domain): an unchecked task whose
+      // title starts with a close-out verb is a pipeline-step pseudo-task; the
+      // task gate requires every task checked, so it can never legitimately
+      // stay as a task. Match on the leading verb only, so "fix finalize task
+      // gate" (a task ABOUT close-out) is not flagged.
+      for (const line of closeOutTaskLines(pendingLines)) {
+        const title = line.replace(/^-\s+\[ \]\s*/u, '').trim();
+        push(
+          'WARNING',
+          'tasks',
+          `task "${title}" looks like a close-out step; ${CLOSE_OUT_TASK_HINT}`,
+        );
+      }
     }
 
-    // completeness INFO (v1 surface).
+    // completeness INFO (predecessor surface).
     push('INFO', 'completeness', COMPLETENESS[stage] ?? '');
 
-    // r63: Full-but-not-ready WARNING with skill guidance (v1 r1 surface).
+    // r63: Full-but-not-ready WARNING with skill guidance (predecessor r1 surface).
     if (opts.git !== undefined && binding !== null && stage === 'full') {
-      const needs =
-        text.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1] !== undefined
-          ? text.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1] === 'true'
-          : true;
-      const touched =
-        opts.git.runOpt(['diff', '--name-only', `${binding.baseBranch}...${binding.branch}`]) ?? '';
-      const landed = touched.includes('llmanspec/specs/');
+      const needs = readNeedsSpecsChange(fm);
+      const landed = specsLanded(opts.git, binding);
       if (!landed && needs) {
         push(
           'WARNING',
           'proposal.md',
-          `specs not landed: change bound to \`${binding.branch}\` but no changes under \`llmanspec/specs/\` on its bound branch. Edit live specs there and commit (or set \`needs_specs_change: false\` if this change has no live contract edits). Skill: llman-sdd-propose — do NOT re-run change start when already attached; apply only when \`llman-sdd show <id> --json\` reports readyToImplement=true (llman-sdd-apply).`,
+          `specs not landed: change bound to \`${binding.branch}\` but no changes under \`llmanspec/specs/\` on its bound branch. Edit live specs there and commit (or set \`needs_specs_change\` to false in the frontmatter if this change has no live contract edits). Skill: llman-sdd-propose — do NOT re-run change start when already attached; start llman-sdd-apply once the specs-landed gate passes (see \`llman-sdd show <id>\` gateChecks).`,
         );
       }
     }
   }
 
-  // pattern gate (v1 change-id path).
+  // pattern gate (predecessor change-id path). loadConfig compiles the pattern first
+  // on the CLI path; this branch defends direct core callers that build a
+  // ChangeCheckConfig without going through loadConfig.
   if (config.change_id_pattern) {
     try {
       const re = new RegExp(config.change_id_pattern, 'u');
@@ -280,18 +320,20 @@ export function validateChange(
         push(
           'ERROR',
           'change-id',
-          `Change id '${id}' does not match change_id.pattern '${config.change_id_pattern}' (sdd-workflow r29; scope: active changes only, archive/legacy shapes are not back-checked).`,
+          `Change id '${id}' does not match change_id.pattern '${config.change_id_pattern}' (active changes only; archived changes are not re-checked).`,
         );
       }
-    } catch {
-      /* compile already validated at load; ignore */
+    } catch (error) {
+      push(
+        'ERROR',
+        'change-id',
+        `change_id.pattern is not a valid regular expression: ${(error as Error).message}`,
+      );
     }
   }
 
-  // stage gate (v1 --stage: artifact presence per gate).
+  // stage gate (predecessor --stage: artifact presence per gate).
   if (opts.stage !== undefined) {
-    const hasDesign = io.exists(`${dir}design.md`);
-    const hasTasks = io.exists(`${dir}tasks.md`);
     if (opts.stage === 'designed' && !hasDesign) {
       push('ERROR', 'design.md', `Stage forced to 'designed' but design.md is missing`);
     }
@@ -320,22 +362,3 @@ const ALLOWED_FIELDS = [
   'base_sha',
   'needs_specs_change',
 ];
-
-export interface PlaceholderTarget {
-  featureDir: string;
-  featureName: string;
-  featurePath: string;
-}
-
-/** True when run_command carries any r48 placeholder. */
-export function hasPlaceholders(runCommand: string): boolean {
-  return /\{feature_dir\}|\{feature_name\}|\{feature_path\}/u.test(runCommand);
-}
-
-/** Expand {feature_dir}/{feature_name}/{feature_path} for one target (r48). */
-export function expandRunCommand(runCommand: string, target: PlaceholderTarget): string {
-  return runCommand
-    .replaceAll('{feature_dir}', target.featureDir)
-    .replaceAll('{feature_name}', target.featureName)
-    .replaceAll('{feature_path}', target.featurePath);
-}