@llman-sdd/core 0.5.1 → 0.7.0

package/package.json

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

package/src/change/closeOutHarness.ts

@@ -1,29 +1,33 @@
 /**
- * Whether a close-out (finalize / archive) must run bdd.run_command before
+ * Whether a close-out (finalize / archive) must run specs.check_command before
  * any merge or rename. Pure: the CLI supplies the flags, the spec scan, and
  * the nested-invocation bit.
  */
 
 export type CloseOutHarnessDecision =
-  | { kind: 'skip'; announce: boolean }
+  | { kind: 'skip'; announce: boolean; warning?: string }
   | { kind: 'abort'; message: string }
   | { kind: 'run'; command: string };
 
 export function decideCloseOutHarness(input: {
   noCheck: boolean;
   needsSpecsChange: boolean;
-  hasExecutable: boolean;
   runCommand: string | null;
   nested: boolean;
 }): CloseOutHarnessDecision {
   if (input.noCheck) return { kind: 'skip', announce: true };
-  if (!input.needsSpecsChange || !input.hasExecutable) return { kind: 'skip', announce: false };
+  if (!input.needsSpecsChange) return { kind: 'skip', announce: false };
   const command = input.runCommand?.trim() ?? '';
   if (command === '') {
-    return { kind: 'abort', message: 'executable scenarios have no bdd.run_command' };
+    return {
+      kind: 'skip',
+      announce: false,
+      warning:
+        'specs.check_command is not configured — close-out skips spec verification. Configure it to gate close-out (see migrations/v0.5-v0.6/README.md).',
+    };
   }
   if (input.nested) {
-    return { kind: 'abort', message: 'bdd harness skipped: nested invocation' };
+    return { kind: 'abort', message: 'spec check skipped: nested invocation' };
   }
   return { kind: 'run', command };
 }

package/src/config/load.ts

@@ -28,7 +28,52 @@ export class ConfigValidationError extends Error {
   }
 }
 
-export function loadConfig(source: string): SddConfig {
+/**
+ * Legacy `bdd:` section elevation (specs-check-config-and-unbound-feed):
+ * a present `bdd` block is recognised at load time and elevated onto the new
+ * `specs` semantics (`run_command` → `check_command`, `framework`/`verify_prompt`
+ * carried under the same names). The new-form `specs` block wins on key conflicts;
+ * the legacy block only fills gaps. Any undeclared legacy subkeys (bindings,
+ * default_language, feature_dir …) are dropped. Pure — never mutates the input;
+ * the caller decides how to surface the migration warning.
+ */
+export function elevateLegacyBdd(data: unknown): { data: unknown; legacyBddElevated: boolean } {
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    return { data, legacyBddElevated: false };
+  }
+  const rec: Record<string, unknown> = { ...(data as Record<string, unknown>) };
+  const bdd = rec['bdd'];
+  if (bdd === undefined || bdd === null || typeof bdd !== 'object' || Array.isArray(bdd)) {
+    return { data, legacyBddElevated: false };
+  }
+  const legacy = bdd as Record<string, unknown>;
+  const specs =
+    typeof rec['specs'] === 'object' && rec['specs'] !== null && !Array.isArray(rec['specs'])
+      ? (rec['specs'] as Record<string, unknown>)
+      : {};
+  const merged: Record<string, unknown> = { ...specs };
+  if (merged['check_command'] === undefined && typeof legacy['run_command'] === 'string') {
+    merged['check_command'] = legacy['run_command'];
+  }
+  if (merged['framework'] === undefined && typeof legacy['framework'] === 'string') {
+    merged['framework'] = legacy['framework'];
+  }
+  if (merged['verify_prompt'] === undefined && typeof legacy['verify_prompt'] === 'string') {
+    merged['verify_prompt'] = legacy['verify_prompt'];
+  }
+  delete rec['bdd'];
+  rec['specs'] = merged;
+  return { data: rec, legacyBddElevated: true };
+}
+
+/**
+ * Load + validate, returning the parsed config and whether a legacy `bdd:`
+ * section was elevated. The CLI surfaces the migration warning from the flag.
+ */
+export function loadConfigDetail(source: string): {
+  config: SddConfig;
+  legacyBddElevated: boolean;
+} {
   let data: unknown;
   try {
     data = parse(source);
@@ -37,7 +82,8 @@ export function loadConfig(source: string): SddConfig {
       `YAML parse error: ${error instanceof Error ? error.message : String(error)}`,
     ]);
   }
-  const result = sddConfigSchema.safeParse(data);
+  const elevated = elevateLegacyBdd(data);
+  const result = sddConfigSchema.safeParse(elevated.data);
   if (!result.success) {
     const issues = result.error.issues.map((iss) => {
       const path = iss.path.map(String).join('/');
@@ -58,5 +104,9 @@ export function loadConfig(source: string): SddConfig {
       throw new ConfigValidationError([(error as Error).message]);
     }
   }
-  return result.data;
+  return { config: result.data, legacyBddElevated: elevated.legacyBddElevated };
+}
+
+export function loadConfig(source: string): SddConfig {
+  return loadConfigDetail(source).config;
 }

package/src/config/schema.ts

@@ -15,18 +15,18 @@ export const EXTRA_SKILLS = [
   'llman-sdd-research',
 ] as const;
 
-export const bddSchema = z.object({
+export const specsSchema = z.object({
   framework: z
     .string()
     .default('')
     .describe(
-      'BDD framework identifier (optional). Only used to derive a default run_command when run_command is unset.',
+      'BDD framework identifier (optional). Only used to derive a default check_command when check_command is unset.',
     ),
-  run_command: z
+  check_command: z
     .string()
     .nullish()
     .describe(
-      'Harness command executed by validate for spec targets (skip with --no-check). Placeholders: {feature_path}, {feature_dir}, {feature_name}; without placeholders it runs once per validate invocation (batch-once).',
+      'Spec verification command executed by validate for spec targets (skip with --no-check). Placeholders: {feature_path}, {feature_dir}, {feature_name}; without placeholders it runs once per validate invocation (batch-once). Legacy `bdd.run_command` is elevated onto this key at load time.',
     ),
   verify_prompt: z.string().nullish().describe('Extra prompt text injected during verify phase.'),
 });
@@ -82,10 +82,10 @@ export const sddConfigSchema = z.object({
   archive: archiveSchema
     .nullish()
     .describe('Archive behaviour settings (defer tracking, completion gates).'),
-  bdd: bddSchema
+  specs: specsSchema
     .nullish()
     .describe(
-      'BDD integration settings. When defined, enables feature-as-spec mode and BDD-aware verify prompts.',
+      'Spec verification integration settings. When defined, enables feature-as-spec mode and verification-aware verify prompts. Legacy `bdd` section is elevated onto this field at load time.',
     ),
   sdd: sddSchema
     .nullish()

package/src/config/surface.ts

@@ -18,7 +18,7 @@ export function renderConfigOverview(source: string): string[] {
     `schema: ${config.schema}`,
     `locale: ${config.locale}`,
     `extra_skills (enabled/total): ${enabled} / ${EXTRA_SKILLS.length}`,
-    `bdd: ${config.bdd ? 'on' : 'off'}`,
+    `specs: ${config.specs ? 'on' : 'off'}`,
     `archive: ${archiveConfigured ? 'configured' : 'default'}`,
   ];
 }

package/src/index.ts

@@ -3,14 +3,20 @@ export * from './ports.ts';
 export {
   EXTRA_SKILLS,
   archiveSchema,
-  bddSchema,
   changeIdSchema,
   sddConfigSchema,
+  specsSchema,
   sddSchema,
   type SddConfig,
   type SddConfigInput,
 } from './config/schema.ts';
-export { ConfigValidationError, MAX_REPORTED_ISSUES, loadConfig } from './config/load.ts';
+export {
+  ConfigValidationError,
+  MAX_REPORTED_ISSUES,
+  elevateLegacyBdd,
+  loadConfig,
+  loadConfigDetail,
+} from './config/load.ts';
 export {
   ChangeIdError,
   compileChangeIdPattern,
@@ -27,7 +33,7 @@ export type {
   ScenarioStep,
   SpecStructuralError,
 } from './spec/ir.ts';
-export { specIdOf } from './spec/ir.ts';
+export { ruleHasRunnableScenario, specIdOf } from './spec/ir.ts';
 export {
   SpecParseError,
   localeToGherkinLang,
@@ -101,6 +107,16 @@ export {
   type StageGate,
 } from './validation/changeCheck.ts';
 export { discoverSpecs, type DiscoveryIo } from './validation/discover.ts';
+export {
+  discoverRoots,
+  isValidRoot,
+  resolveInstanceRoot,
+  scopeCrossings,
+  ROOT_EXCLUDED_DIRS,
+  type RootEntry,
+  type RootsIo,
+  type ScopeCrossing,
+} from './validation/roots.ts';
 export {
   expandRunCommand,
   runHarnessForSpecs,
@@ -164,7 +180,7 @@ export {
 export {
   ETHICS_KEYS,
   buildTemplateVars,
-  effectiveRunCommand,
+  effectiveCheckCommand,
   enforceEthicsGovernance,
   loadLocaleResource,
   loadSkillTemplates,
@@ -181,6 +197,7 @@ export {
 } from './templates/embedded.ts';
 export {
   TEMPLATES_ROOT,
+  refreshSubRootBlocks,
   runInit,
   updateFileWithMarkers,
   type InitIo,
@@ -197,6 +214,12 @@ export {
   type ChangeSummary,
 } from './change/collect.ts';
 export { renderChangesJson, renderChangesList } from './report/collect.ts';
+export {
+  buildUnboundFeed,
+  collectUnboundRequirements,
+  type UnboundFeed,
+  type UnboundRequirement,
+} from './report/unbound.ts';
 export { graphData, graphMermaid, type GraphDataIr, type GraphFsIo } from './report/graph.ts';
 export { parseDeps } from './report/graph.ts';
 export { renderMachine, type MachineFormat } from './render/machine.ts';

package/src/init/defaultConfig.ts

@@ -23,13 +23,13 @@ locale: en
 #   - llman-sdd-wayfinder
 #   - llman-sdd-research
 
-# BDD integration (optional, uncomment to enable)
-# bdd:
+# Spec verification (optional, uncomment to enable)
+# specs:
 #   framework: pytest-bdd
 #   # Filtered runners: include {feature_*} so validate --all/--specs runs per capability.
-#   # run_command: "pytest {feature_dir} -k {feature_name} -v"
+#   # check_command: "pytest {feature_dir} -k {feature_name} -v"
 #   # Project-wide runners (no placeholders): validate --all/--specs runs the suite once (batch-once).
-#   # run_command: "cargo test --features bdd"
+#   # check_command: "cargo test --features bdd"
 #   # verify_prompt: |
 #   #   Map test failures to requirement IDs.
 `;
@@ -51,13 +51,13 @@ locale: zh-Hans
 #   - llman-sdd-wayfinder
 #   - llman-sdd-research
 
-# BDD 集成（可选，取消注释以启用）
-# bdd:
+# Spec 验证（可选，取消注释以启用）
+# specs:
 #   framework: pytest-bdd
 #   # 过滤型 runner：写 {feature_*}，validate --all/--specs 按 capability 分别执行。
-#   # run_command: "pytest {feature_dir} -k {feature_name} -v"
+#   # check_command: "pytest {feature_dir} -k {feature_name} -v"
 #   # 项目级 runner（无占位符）：validate --all/--specs 整批只跑一次（batch-once）。
-#   # run_command: "cargo test --features bdd"
+#   # check_command: "cargo test --features bdd"
 #   # verify_prompt: |
 #   #   将测试失败映射到对应的 requirement ID。
 `;

package/src/init/init.ts

@@ -26,7 +26,7 @@ import {
   prependSchemaHeader,
 } from './defaultConfig.ts';
 
-export { effectiveRunCommand } from '../templates/skills.ts';
+export { effectiveCheckCommand } from '../templates/skills.ts';
 
 const MARKER_START = '<!-- LLMANSPEC:START -->';
 const MARKER_END = '<!-- LLMANSPEC:END -->';
@@ -80,7 +80,7 @@ function writeDefaultConfig(io: InitIo, locale: string): void {
 }
 
 export interface InitResult {
-  /** Skill dirs written, in render order. */
+  /** Skill dirs written, in render order ([] when skills injection is off). */
   skills: string[];
   /** llman-sdd-* directories removed by --update namespace cleanup. */
   removed: string[];
@@ -89,10 +89,31 @@ export interface InitResult {
 
 const SKILLS_BASE = '.agents/skills';
 
+/** Managed AGENTS.md marker blocks (root + llmanspec), content-preserving. */
+function writeManagedBlocks(
+  io: InitIo,
+  templates: TemplateIo,
+  config: ReturnType<typeof loadConfig>,
+  version: string,
+): void {
+  const vars = buildTemplateVars(config, version);
+  const locales = localeFallbacks(config.locale);
+  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));
+  }
+}
+
 export function runInit(
   io: InitIo,
   templates: TemplateIo,
-  opts: { update: boolean; locale?: string; version: string },
+  opts: { update: boolean; locale?: string; version: string; skills: boolean },
 ): InitResult {
   io.mkdirp('llmanspec');
 
@@ -110,26 +131,15 @@ export function runInit(
   }
 
   // 3) AGENTS.md managed blocks (root + llmanspec), preserving content.
+  writeManagedBlocks(io, templates, config, opts.version);
   const vars = buildTemplateVars(config, opts.version);
-  const locales = localeFallbacks(config.locale);
   const skillTemplates = loadSkillTemplates(templates, TEMPLATES_ROOT, config, vars);
   enforceEthicsGovernance(skillTemplates);
 
-  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[] = [];
-  if (opts.update && io.exists(SKILLS_BASE)) {
+  if (opts.skills && opts.update && io.exists(SKILLS_BASE)) {
     const candidates = new Set(skillCandidates(config).map((f) => f.replace(/\.md$/u, '')));
     for (const entry of io.listDir(SKILLS_BASE)) {
       if (entry.startsWith('llman-sdd-') && !candidates.has(entry)) {
@@ -140,6 +150,12 @@ export function runInit(
   }
 
   // 5) write candidates: rendered product trimmed + single trailing newline.
+  // Sub-root instances default to no skills injection (r93): the agent skill
+  // surface stays at the repo root and sub-root navigation lives in the
+  // managed blocks; --skills opts a sub-root in.
+  if (!opts.skills) {
+    return { skills: [], removed, configPath };
+  }
   for (const t of skillTemplates) {
     const dirName = t.name.replace(/\.md$/u, '');
     io.mkdirp(`${SKILLS_BASE}/${dirName}`);
@@ -148,3 +164,16 @@ export function runInit(
 
   return { skills: skillTemplates.map((t) => t.name.replace(/\.md$/u, '')), removed, configPath };
 }
+
+/**
+ * r93 --update sweep: refresh the managed blocks of one discovered sub-root
+ * (blocks only — no scaffold, no config touch, no skills). Returns false for
+ * a missing config (discovery guarantees validity; a race is not fatal).
+ */
+export function refreshSubRootBlocks(io: InitIo, templates: TemplateIo, version: string): boolean {
+  const configPath = 'llmanspec/config.yaml';
+  if (!io.exists(configPath)) return false;
+  const config = loadConfig(io.readText(configPath));
+  writeManagedBlocks(io, templates, config, version);
+  return true;
+}

package/src/report/specHelpers.ts

@@ -39,20 +39,19 @@ function collectSpecEntries(io: SpecHelperIo, specsDir: string): ParsedEntry[] {
 }
 
 /**
- * predecessor parity (`req_registry.rs::next_req_id_from_index`): smallest free
- * rN over the requirement handles (`@req` on `规则:` headers) only. The id set
- * comes from the global req registry fed with the parsed specs.
+ * Max+1 over the requirement handles (`@req` on `规则:` headers) only — the id
+ * set comes from the global req registry fed with the parsed specs. Deliberately
+ * divergent from the predecessor's smallest-free semantics
+ * (`req_registry.rs::next_req_id_from_index`): handing out freed ids aliases
+ * references archived in past changes (issue #5) — retired ranges are never
+ * reused. See change `align-next-req-id-max-plus-one` design for the trade-off.
  */
 export function nextReqId(io: SpecHelperIo, specsDir: string): string {
   const entries = collectSpecEntries(io, specsDir);
-  const used = new Set(
-    [...buildReqRegistry(entries).byId.keys()].map((reqId) =>
-      Math.trunc(Number(reqId.replace(/^r/u, ''))),
-    ),
+  const used = [...buildReqRegistry(entries).byId.keys()].map((reqId) =>
+    Math.trunc(Number(reqId.replace(/^r/u, ''))),
   );
-  let n = 1;
-  while (used.has(n)) n += 1;
-  return `r${n}`;
+  return `r${Math.max(0, ...used) + 1}`;
 }
 
 export function skeletonContent(capability: string, reqId: string, locale: string): string {

package/src/report/specs.ts

@@ -1,19 +1,20 @@
 /**
- * Specs listing (peripheral-commands capability, r20/r21): morphology counts.
- * Native model — rules = `规则:` blocks; enforced = rules with at least one
- * nested executable scenario; pending = bare rules; acceptance = nested
- * scenarios; featureScenarioCount = top-level feature-level examples.
+ * Specs listing (peripheral-commands capability, r20/r21/r90): morphology
+ * counts. Native model — rules = `规则:` blocks; bound = rules with at least
+ * one runnable nested executable scenario; unbound = rules without any runnable
+ * nested scenario (@skip/@experimental-only or stepless scenarios do not bind);
+ * acceptance = nested scenarios; featureScenarioCount = top-level examples.
+ * Machine field names follow the requirement terminology (r90).
  */
 import { renderMachine } from '../render/machine.ts';
-import { specIdOf } from '../spec/ir.ts';
+import { ruleHasRunnableScenario, specIdOf } 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;
-  ruleEnforcedCount: number;
-  rulePendingCount: number;
+  requirementBoundCount: number;
+  requirementUnboundCount: number;
   acceptanceCount: number;
   featureScenarioCount: number;
 }
@@ -30,16 +31,14 @@ export interface SpecSummary {
 }
 
 /** Morphology counts shared by `list --specs`, `show <spec> --json`, and the
- * CLI text render — rules with executable scenarios are enforced; bare rules
- * without any nested scenario are pending; top-level examples are counted
- * separately with no rule accounting. */
+ * CLI text render — bound/unbound follow the runnable-scenario definition; top-level
+ * examples are counted separately with no rule accounting. */
 export function morphologyOf(doc: CapabilityDoc): SpecMorphology {
   const rules = doc.rules;
   const acceptance = rules.flatMap((r) => r.scenarios);
   return {
-    ruleCount: rules.length,
-    ruleEnforcedCount: rules.filter((r) => r.scenarios.length > 0).length,
-    rulePendingCount: rules.filter((r) => r.scenarios.length === 0).length,
+    requirementBoundCount: rules.filter(ruleHasRunnableScenario).length,
+    requirementUnboundCount: rules.filter((r) => !ruleHasRunnableScenario(r)).length,
     acceptanceCount: acceptance.length,
     featureScenarioCount: doc.orphans.length,
   };
@@ -48,6 +47,7 @@ export function morphologyOf(doc: CapabilityDoc): SpecMorphology {
 export function collectSpecs(entries: readonly SpecEntry[]): SpecSummary[] {
   return entries.map((e) => {
     const morphology = morphologyOf(e.doc);
+    const total = morphology.requirementBoundCount + morphology.requirementUnboundCount;
     return {
       id: specIdOf(e),
       title: specIdOf(e),
@@ -56,7 +56,7 @@ export function collectSpecs(entries: readonly SpecEntry[]): SpecSummary[] {
         .split(',')
         .map((s) => s.trim())
         .filter((s) => s !== ''),
-      requirementCount: morphology.ruleCount,
+      requirementCount: total,
       health: null,
       staleness: null,
       morphology,
@@ -70,7 +70,7 @@ export function renderSpecsList(summaries: readonly SpecSummary[]): string[] {
   for (const s of summaries) {
     const m = s.morphology;
     lines.push(
-      `  ${pad(s.id, idWidth)}rules ${m.ruleCount}  enforced ${m.ruleEnforcedCount}  pending ${m.rulePendingCount}  acceptance ${m.acceptanceCount}`,
+      `  ${pad(s.id, idWidth)}requirements ${s.requirementCount}  bound ${m.requirementBoundCount}  unbound ${m.requirementUnboundCount}  acceptance ${m.acceptanceCount}`,
     );
   }
   return lines;

package/src/report/unbound.ts

@@ -0,0 +1,70 @@
+/**
+ * `spec unbound` retrieval (peripheral-commands capability, r89): the
+ * implementation-readiness feed of unbound requirements. "Unbound" follows the
+ * single global definition — a requirement without any runnable nested scenario
+ * (@skip/@experimental-only or stepless included) — same口径 as review's
+ * `unbound` signal, validate's aggregate INFO and list/show morphology (r90).
+ *
+ * Ordering is deterministic: capability files in discovery (sorted) order,
+ * then rules in document order — agents can consume the feed incrementally.
+ * Pure — no filesystem access.
+ */
+import { ruleHasRunnableScenario, specIdOf } from '../spec/ir.ts';
+import type { SpecEntry } from '../validation/validate.ts';
+
+export interface UnboundRequirement {
+  /** The `@req:<id>` handle (requirement id). */
+  reqId: string;
+  /** The `规则:` block title. */
+  title: string;
+  /** Free-form requirement statement (block description, as authored). */
+  statement: string;
+  /** Capability (spec) id owning the requirement. */
+  capability: string;
+  /** Repo-root-relative path of the capability's main .feature file. */
+  featurePath: string;
+}
+
+/** All unbound requirements across the given specs, in deterministic order. */
+export function collectUnboundRequirements(entries: readonly SpecEntry[]): UnboundRequirement[] {
+  const out: UnboundRequirement[] = [];
+  for (const entry of entries) {
+    const capability = specIdOf(entry);
+    for (const rule of entry.doc.rules) {
+      if (ruleHasRunnableScenario(rule)) continue;
+      out.push({
+        reqId: rule.reqId,
+        title: rule.title,
+        statement: rule.description,
+        capability,
+        featurePath: entry.fileName,
+      });
+    }
+  }
+  return out;
+}
+
+export interface UnboundFeed {
+  /** Total unbound requirements before any limit. */
+  total: number;
+  /** Entries actually returned (limit applied). */
+  returned: number;
+  /** `total - returned`; 0 means everything was returned. */
+  remaining: number;
+  /** Self-introspection hint when remaining > 0 (empty otherwise). */
+  hint: string;
+  requirements: UnboundRequirement[];
+}
+
+/**
+ * Build the `spec unbound` feed under a hard limit. `limit` semantics are
+ * uniform across every output mode: default 1, `--limit 0` returns all.
+ */
+export function buildUnboundFeed(entries: readonly SpecEntry[], limit: number): UnboundFeed {
+  const all = collectUnboundRequirements(entries);
+  const shown = limit === 0 ? all : all.slice(0, limit);
+  const returned = shown.length;
+  const remaining = all.length - returned;
+  const hint = remaining > 0 ? `… 还有 ${remaining} 条未绑定需求,用 --limit 0 列出全部` : '';
+  return { total: all.length, returned, remaining, hint, requirements: shown };
+}

package/src/review/review.ts

@@ -1,5 +1,5 @@
 import type { GitLike } from '../git/spawnGit.ts';
-import { specIdOf } from '../spec/ir.ts';
+import { ruleHasRunnableScenario, specIdOf } from '../spec/ir.ts';
 import { evaluateStaleness, notApplicableStaleness } from '../validation/staleness.ts';
 /**
  * Review aggregation (review-freeze capability, r23): five-signal review over
@@ -7,7 +7,7 @@ import { evaluateStaleness, notApplicableStaleness } from '../validation/stalene
  */
 import { validateAllSpecs, type SpecEntry, type SpecIo } from '../validation/validate.ts';
 
-export type ReviewKind = 'pending' | 'stale' | 'locked' | 'validate';
+export type ReviewKind = 'unbound' | 'stale' | 'locked' | 'validate';
 
 export interface ReviewSignal {
   kind: ReviewKind;
@@ -66,13 +66,13 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
     // r33: per-capability signals honor the --capability filter; locked and
     // validate stay global regardless.
     if (input.capability !== undefined && cap !== input.capability) continue;
-    // Native model: rules are `规则:` blocks; a rule without nested scenarios
-    // is "bare" (pending — candidate for conversion/compaction). Top-level
-    // scenarios outside any rule are plain feature-level examples with no
-    // special signal.
-    const pending = entry.doc.rules.filter((r) => r.scenarios.length === 0);
+    // Native model: rules are `规则:` blocks; a rule without any runnable
+    // nested scenario is unbound (not bound to real logic — 0 scenarios or
+    // all @skip/@experimental/stepless). Top-level scenarios outside any rule
+    // are plain feature-level examples with no special signal.
+    const unbound = entry.doc.rules.filter((r) => !ruleHasRunnableScenario(r)).length;
 
-    push('pending', cap, pending.length);
+    push('unbound', cap, unbound);
 
     // staleness (predecessor evaluate): real base-ref/scope evaluation.
     let staleInfo = notApplicableStaleness();
@@ -143,7 +143,7 @@ export function buildReview(input: ReviewInput, io: SpecIo): ReviewResult {
 
   const lines: string[] = [`Review: critical=${criticalCount} warning=${warningCount}`];
   for (const cap of sorted.map((e) => specIdOf(e))) {
-    for (const kind of ['pending', 'stale'] as const) {
+    for (const kind of ['unbound', 'stale'] as const) {
       const s = signals.find((x) => x.kind === kind && x.capability === cap);
       if (!s) continue;
       lines.push(`${kind}: ${cap} (${s.count})`);

package/src/spec/ir.ts

@@ -66,6 +66,16 @@ export interface CapabilityDoc {
   errors: SpecStructuralError[];
 }
 
+/**
+ * Whether a requirement is bound to real logic — it has at least one runnable
+ * nested scenario (not `@skip`/`@experimental` and carrying steps). Single
+ * authority for the `bound`/`unbound` definition shared by review's `unbound`
+ * signal, validate's aggregate INFO, list/show morphology and `spec unbound`.
+ */
+export function ruleHasRunnableScenario(rule: RuleIR): boolean {
+  return rule.scenarios.some((s) => s.runnable && s.stepCount > 0);
+}
+
 /**
  * Single spec-id caliber (r25) for every consumer that labels a discovered
  * spec entry: the `# capability:` header wins, else the fileName minus the

package/src/templates/skills.ts

@@ -49,10 +49,10 @@ export const ETHICS_KEYS: readonly string[] = [
   'ethics.escalation_policy',
 ];
 
-/** 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 ?? '') {
+/** Framework-derived check_command (predecessor config.rs effective_run_command). */
+export function effectiveCheckCommand(specs: NonNullable<SddConfig['specs']>): string {
+  if (specs.check_command) return specs.check_command;
+  switch (specs.framework ?? '') {
     case 'pytest-bdd':
       return 'pytest {feature_dir} -k {feature_name} -v';
     case 'rstest-bdd':
@@ -62,18 +62,18 @@ export function effectiveRunCommand(bdd: NonNullable<SddConfig['bdd']>): string
     case 'behave':
       return 'behave {feature_path}';
     default:
-      return "echo 'No run_command configured. Set bdd.run_command in config.yaml'";
+      return "echo 'No check_command configured. Set specs.check_command in config.yaml'";
   }
 }
 
 /** 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 ?? '';
-    vars['bdd_run_command'] = effectiveRunCommand(config.bdd);
-    if (config.bdd.verify_prompt) vars['bdd_verify_prompt'] = config.bdd.verify_prompt;
+  if (config.specs) {
+    vars['specs_enabled'] = 'true';
+    vars['specs_framework'] = config.specs.framework ?? '';
+    vars['specs_check_command'] = effectiveCheckCommand(config.specs);
+    if (config.specs.verify_prompt) vars['specs_verify_prompt'] = config.specs.verify_prompt;
   }
   const extras = new Set<string>(config.extra_skills ?? []);
   for (const name of OPTIONAL_SKILL_FILES) {

package/src/validation/harness.ts

@@ -1,6 +1,6 @@
 /**
- * BDD harness execution for validate (validation capability, r13/r48):
- * expands bdd.run_command per capability, executes each expanded command
+ * Spec verification check execution for validate (validation capability, r13/r48):
+ * expands specs.check_command per capability, executes each expanded command
  * string at most once per validate invocation (batch-once), and maps results
  * to per-capability issues. Pure — the subprocess runs through the injected
  * HarnessRunner; this module never reads the environment or the wall clock
@@ -10,7 +10,7 @@
 import type { ValidationItem } from './validate.ts';
 
 /**
- * Harness runner port (r13/r48): executes one expanded bdd.run_command
+ * Harness runner port (r13/r48): executes one expanded specs.check_command
  * string; the CLI adapter owns the subprocess (and the nested-invocation
  * guard env it exports). exitCode is null only when the command could not
  * start (spawnError then carries the reason). Lives here rather than in
@@ -39,7 +39,7 @@ export interface HarnessGate {
   /** LLMAN_SDD_HARNESS_ACTIVE=1 was set by an enclosing validate invocation. */
   nested: boolean;
   check: 'default' | 'on' | 'off';
-  /** Undefined when bdd.run_command is not configured (non-empty string). */
+  /** Undefined when specs.check_command is not configured (non-empty string). */
   runner: HarnessRunner | undefined;
   runCommand: string | null;
   /** Project root — the cwd every harness subprocess runs in. */
@@ -75,7 +75,7 @@ const OUTPUT_TAIL = 200;
 
 /**
  * Trigger matrix (r13): --no-check skips silently; a nested invocation skips
- * with a per-spec INFO; an explicit --check without a configured run_command
+ * with a per-spec INFO; an explicit --check without a configured check_command
  * yields a single INFO on the first spec; otherwise every expanded command
  * executes at most once (cache keyed by the expanded string).
  */
@@ -91,7 +91,7 @@ export function runHarnessForSpecs(
         {
           level: 'INFO',
           id: target.featurePath,
-          message: 'bdd harness skipped: nested invocation',
+          message: 'spec check skipped: nested invocation',
         },
       ]);
     }
@@ -104,7 +104,7 @@ export function runHarnessForSpecs(
         {
           level: 'INFO',
           id: first.featurePath,
-          message: '--check has no effect: bdd.run_command is not configured',
+          message: '--check has no effect: specs.check_command is not configured',
         },
       ]);
     }
@@ -123,14 +123,14 @@ export function runHarnessForSpecs(
             {
               level: 'INFO',
               id: target.featurePath,
-              message: `bdd harness passed (cached): ${expanded}`,
+              message: `spec check passed (cached): ${expanded}`,
             },
           ]
         : [
             {
               level: 'ERROR',
               id: target.featurePath,
-              message: `bdd harness failed (cached result of ${expanded}): ${cached.failureSummary}`,
+              message: `spec check failed (cached result of ${expanded}): ${cached.failureSummary}`,
             },
           ];
     } else {
@@ -142,13 +142,13 @@ export function runHarnessForSpecs(
       const result = gate.runner.run(expanded, gate.cwd);
       const firstError =
         result.spawnError !== undefined
-          ? `bdd harness could not start: ${expanded}: ${result.spawnError}`
+          ? `spec check could not start: ${expanded}: ${result.spawnError}`
           : result.exitCode === 0
             ? null
-            : `bdd harness failed (exit ${result.exitCode}): ${expanded}: ${result.output.slice(-OUTPUT_TAIL)}`;
+            : `spec check failed (exit ${result.exitCode}): ${expanded}: ${result.output.slice(-OUTPUT_TAIL)}`;
       issues =
         firstError === null
-          ? [{ level: 'INFO', id: target.featurePath, message: `bdd harness passed: ${expanded}` }]
+          ? [{ level: 'INFO', id: target.featurePath, message: `spec check passed: ${expanded}` }]
           : [{ level: 'ERROR', id: target.featurePath, message: firstError }];
       cache.set(expanded, {
         success: firstError === null,

package/src/validation/roots.ts

@@ -0,0 +1,123 @@
+/**
+ * Instance-root discovery (subproject-llmanspec-discovery, r91-r92): the
+ * unified-root axiom — every llman-sdd operation targets one llmanspec/
+ * directory; the repo root is just the default instance and a workspace
+ * subpackage carrying its own llmanspec/ is another instance of the same
+ * shape. Pure: filesystem access only through the injected IO.
+ */
+
+export interface RootsIo {
+  exists(path: string): boolean;
+  isDirectory(path: string): boolean;
+  listDir(path: string): string[];
+}
+
+export interface RootEntry {
+  /** Directory containing the llmanspec/ instance (the instance root). */
+  rootDir: string;
+  /** The llmanspec directory itself. */
+  llmanspecDir: string;
+}
+
+/** Directory names never descended into during discovery. */
+export const ROOT_EXCLUDED_DIRS: ReadonlySet<string> = new Set(['node_modules', 'target', '.git']);
+
+const joinPath = (dir: string, name: string): string =>
+  dir.endsWith('/') ? `${dir}${name}` : `${dir}/${name}`;
+
+/**
+ * A directory counts as an llmanspec root when it carries `config.yaml` or a
+ * `specs/` subdir — bare `llmanspec/` scaffolds in flight are not instances.
+ */
+export function isValidRoot(llmanspecDir: string, io: RootsIo): boolean {
+  if (!io.isDirectory(llmanspecDir)) return false;
+  return io.exists(`${llmanspecDir}/config.yaml`) || io.isDirectory(`${llmanspecDir}/specs`);
+}
+
+/**
+ * Discover instance roots under `startDir` (convention scan). The start dir
+ * itself is checked first (depth 0 — the git-root instance), then subdirs
+ * depth-first in stable sort order; `llmanspec/` contents are never descended
+ * into and excluded names are pruned. `maxDepth` mirrors the global
+ * --max-scan-depth knob (default 8).
+ */
+export function discoverRoots(
+  startDir: string,
+  io: RootsIo,
+  opts: { maxDepth?: number } = {},
+): RootEntry[] {
+  const maxDepth = opts.maxDepth ?? 8;
+  const roots: RootEntry[] = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    const llmanspecDir = joinPath(dir, 'llmanspec');
+    if (isValidRoot(llmanspecDir, io)) roots.push({ rootDir: dir, llmanspecDir });
+    let names: string[];
+    try {
+      names = io.listDir(dir);
+    } catch {
+      return;
+    }
+    for (const name of names.toSorted()) {
+      if (name.startsWith('.') || ROOT_EXCLUDED_DIRS.has(name)) continue;
+      const full = joinPath(dir, name);
+      if (!io.isDirectory(full)) continue;
+      if (name === 'llmanspec') continue;
+      walk(full, depth + 1);
+    }
+  };
+  walk(startDir, 0);
+  return roots;
+}
+
+export interface ScopeCrossing {
+  scope: string;
+  rootDir: string;
+}
+
+/**
+ * Single-ownership rule (r92): a file path belongs to exactly one llmanspec
+ * root. Scope entries are resolved against the owning instance root; a scope
+ * that reaches into another root's instance directory crosses the boundary
+ * and is reported with the offending scope and the other root. Ancestor roots
+ * are exempt: a sub-root scoping its own subtree always resolves under the
+ * ancestor's directory, but ownership there belongs to the descendant.
+ */
+export function scopeCrossings(
+  scopePaths: readonly string[],
+  instanceRootDir: string,
+  otherRoots: readonly RootEntry[],
+): ScopeCrossing[] {
+  const crossings: ScopeCrossing[] = [];
+  for (const raw of scopePaths) {
+    const scope = raw.trim().replace(/^\.\//u, '').replace(/\/+$/u, '');
+    if (scope === '') continue;
+    const abs = joinPath(instanceRootDir, scope);
+    for (const other of otherRoots) {
+      if (other.rootDir === instanceRootDir) continue;
+      // Ancestor exemption: our own subtree necessarily sits inside the
+      // ancestor's directory — the ancestor does not own it.
+      if (instanceRootDir.startsWith(`${other.rootDir}/`)) continue;
+      if (abs === other.rootDir || abs.startsWith(`${other.rootDir}/`)) {
+        crossings.push({ scope: raw.trim(), rootDir: other.rootDir });
+        break;
+      }
+    }
+  }
+  return crossings;
+}
+
+/**
+ * Nearest instance root at or above `startDir` (inclusive) — the cwd
+ * resolution behind "cd into the subpackage and run" (r94). Returns null when
+ * no ancestor carries a valid llmanspec root.
+ */
+export function resolveInstanceRoot(startDir: string, io: RootsIo): string | null {
+  let dir = startDir;
+  for (;;) {
+    if (isValidRoot(joinPath(dir, 'llmanspec'), io)) return dir;
+    const parent = dir.replace(/\/+$/u, '').replace(/\/[^/]+$/u, '');
+    if (parent === '' || parent === dir) return null;
+    dir = parent;
+  }
+}

package/src/validation/validate.ts

@@ -5,7 +5,7 @@
  * injected via SpecIo.
  */
 import type { CapabilityDoc } from '../spec/ir.ts';
-import { specIdOf } from '../spec/ir.ts';
+import { ruleHasRunnableScenario, specIdOf } from '../spec/ir.ts';
 import { buildReqRegistry } from '../spec/reqRegistry.ts';
 
 export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
@@ -140,16 +140,17 @@ export function validateCapability(
   // (native Gherkin); they carry no rule handle, so no warning or signal —
   // they simply aren't part of rule accounting.
 
-  // Bare-rule aggregate (r134 migrated): rules with no nested executable
-  // scenario, aggregated per capability (never one issue per rule), INFO so it
-  // never blocks anything. The real accountability lives in the review
-  // `pending` signal and the specs-compact workflow.
-  const bare = rules.filter((r) => r.scenarios.length === 0).length;
-  if (bare > 0) {
+  // Unbound-requirement aggregate (r12/r90): rules without any runnable nested
+  // scenario (@skip/@experimental-only or stepless included), aggregated per
+  // capability (never one issue per rule), INFO so it never blocks anything.
+  // The real accountability lives in the review `unbound` signal, the
+  // `spec unbound` feed and the specs-compact workflow.
+  const unbound = rules.filter((r) => !ruleHasRunnableScenario(r)).length;
+  if (unbound > 0) {
     push(
       'INFO',
       coveragePath(cap),
-      `${bare} bare rule(s) without any executable scenario — convert to 场景: or compact`,
+      `${unbound} unbound requirement(s) without any runnable scenario — bind via 场景: or compact`,
     );
   }
 

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

@@ -76,7 +76,7 @@ Run the project gates as appropriate:
 - SDD validation: `llman-sdd validate <id> --strict`
 
 **Gate evidence**:
-- Close-out runs the configured `bdd.run_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
+- Close-out runs the configured `specs.check_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
 - Gate verdicts MUST come from the real harness: MUST NOT obtain a "pass" via `--no-check`; on harness failure, find the root cause first (leaked env vars, nested-invocation guards, wrong cwd …) — MUST NOT label it an "inherent/self-referential property" and bypass it.
 - Before/after criteria (counts, baselines) MUST be measured on the change branch (against the freshly computed merge-base); a value measured on the default branch is usually trivially the baseline and proves nothing.
 - Refactors and bulk replacements: MUST compare the test count before and after; all-green gates with fewer tests is a failure.

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

@@ -46,7 +46,7 @@ flowchart LR
    - Write decisions back: resolved decisions go into the change's `proposal.md` "Open Questions" section.
    - 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, run `llman-sdd validate <spec> --strict` first for the structural gates (Gherkin / `@req` linkage / dual-write / req_id uniqueness); when `bdd.run_command` is configured, validate executes that harness by default (`--no-check` skips it). Failing items are pinned down in the default TOON output's `items[].issues[]`; `--output human` prints `FAIL <item_type>/<id>` lines.
+   - When diagnosing validation errors, run `llman-sdd validate <spec> --strict` first for the structural gates (Gherkin / `@req` linkage / dual-write / req_id uniqueness); when `specs.check_command` is configured, validate executes that harness by default (`--no-check` skips it). Failing items are pinned down in the default TOON output's `items[].issues[]`; `--output human` prints `FAIL <item_type>/<id>` lines.
 5. Explore options and tradeoffs (2–3 options).
 6. Assess change scale to determine if full SDD is needed.
 7. When something crystallizes, offer to capture it (don't auto-write):

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

@@ -83,11 +83,11 @@ llman-sdd validate <change-id> --strict
 ```
 This MUST pass before proceeding; failing items are listed one by one in the validate output's `items[].issues[]` — fix each and re-run.
 
-### 4a) Optional BDD runner (`bdd:` block)
-- Read `llmanspec/config.yaml`. Is there a `bdd:` block?
-  - **Yes**: `bdd.run_command` declares the project's BDD execution entry; validate executes it by default when its target set includes specs (`--no-check` skips). Authoring follows 4b regardless.
-  - **No**: if this change involves executable behavior scenarios (Given/When/Then the user will want to run), ask **once, up front** whether to enable a `bdd:` runner block (adds a `bdd:` block to `config.yaml` — runner only, does not change the lifecycle). If **yes**: show the exact `bdd:` block to add (pick a `run_command` matching the project's test framework — `cargo test --features bdd` for rstest-bdd, `pytest {feature_dir} -k {feature_name} -v` for pytest-bdd), let the user confirm or edit, write it to `config.yaml`, then proceed with 4b. If **no**: features still validate structurally; BDD execution responsibility stays with the project test suite.
-- **Do NOT silently add the `bdd:` block** — always ask first. Adding it declares the project-wide BDD execution entry.
+### 4a) Optional BDD runner (`specs:` block)
+- Read `llmanspec/config.yaml`. Is there a `specs:` block?
+  - **Yes**: `specs.check_command` declares the project's BDD execution entry; validate executes it by default when its target set includes specs (`--no-check` skips). Authoring follows 4b regardless.
+  - **No**: if this change involves executable behavior scenarios (Given/When/Then the user will want to run), ask **once, up front** whether to enable a `specs:` verification runner block (adds a `specs:` block to `config.yaml` — runner only, does not change the lifecycle). If **yes**: show the exact `specs:` block to add (pick a `check_command` matching the project's test framework — `cargo test --features bdd` for rstest-bdd, `pytest {feature_dir} -k {feature_name} -v` for pytest-bdd), let the user confirm or edit, write it to `config.yaml`, then proceed with 4b. If **no**: features still validate structurally; BDD execution responsibility stays with the project test suite.
+- **Do NOT silently add the `specs:` block** — always ask first. Adding it declares the project-wide BDD execution entry.
 
 ### 4b) Single-track feature authoring
 - Planning docs may briefly live on the default branch; **do not** edit `llmanspec/specs/**` on the default branch. After binding, landing specs and implementation happen on the bound branch.

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

@@ -12,12 +12,12 @@ Validate change/spec format and staleness.
 ## Steps
 1. Single item: `llman-sdd validate <id>`; batch: `llman-sdd validate --all` (or `--changes` / `--specs`); use `--strict` in CI/automation.
 2. On failure, summarize the errors and propose minimal, concrete fixes.
-{% if bdd_enabled %}
+{% if specs_enabled %}
 3. **BDD checks**:
    - Validate `.feature` Gherkin and `@req` / dual-write gates on the **bound branch**; `.feature` is the harness authority — executable GWT lives only there.
    - Lifecycle gates: `change start` / `attach` (bind branch), `finalize` (close-out; auto commit `archive(sdd): <id>`, `--no-commit` to skip) / `diff` (read-only).
-   - `llman-sdd validate --specs` enforces structural and contract gates; when `bdd.run_command` is configured it also executes that harness by default (`--no-check` skips it, `--check` is a compat alias); a placeholder-free command runs at most once per invocation.
-   - `list --specs --json` shows `morphology` (ruleCount / ruleEnforcedCount / rulePendingCount / acceptanceCount / featureScenarioCount).
+   - `llman-sdd validate --specs` enforces structural and contract gates; when `specs.check_command` is configured it also executes that harness by default (`--no-check` skips it, `--check` is a compat alias); a placeholder-free command runs at most once per invocation.
+   - `list --specs --json` shows `morphology` (requirementCount / requirementBoundCount / requirementUnboundCount / acceptanceCount / featureScenarioCount).
    - Change JSON status fields: `stage` (draft/designed/planned/full) / `specsLanded` / `needsSpecsChange` / `readyToImplement` (`show --output json`).
 {% endif %}
 

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

@@ -26,7 +26,7 @@ flowchart LR
 - **Apply must be all-green first**: don't verify unimplemented changes.
 - **CRITICAL must be fixed**: zero CRITICAL before archive.
 - **Rerun the gates yourself**: MUST rerun `llman-sdd validate <id> --strict` (real harness) and the project gates; MUST NOT trust gate verdicts in the implementer's report — a mismatch is CRITICAL.
-- **`--no-check` is not evidence**: gate evidence obtained with `--no-check` → CRITICAL. Close-out runs the configured `bdd.run_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
+- **`--no-check` is not evidence**: gate evidence obtained with `--no-check` → CRITICAL. Close-out runs the configured `specs.check_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
 - **Don't ask "should I continue?"**: run the full verification flow and output a complete report.
 
 {{ unit("skills/stage-guard") }}
@@ -34,7 +34,7 @@ flowchart LR
 ## Steps
 1. Select the change id (or ask the user to pick from `llman-sdd list --json`).
 2. Fast validation gate: `llman-sdd validate <id> --strict`.
-   - When diagnosing structural issues (Gherkin parse / `@req` linkage / dual-write / req_id uniqueness), run the structural validation first (when `bdd.run_command` is configured, validate executes that harness by default — `--no-check` skips it; a harness failure lands as an ERROR on its spec item). Failing items are listed one by one in the default TOON output's `items[].issues[]` (`--output human` prints `FAIL <item_type>/<id>` lines above the `Totals` line).
+   - When diagnosing structural issues (Gherkin parse / `@req` linkage / dual-write / req_id uniqueness), run the structural validation first (when `specs.check_command` is configured, validate executes that harness by default — `--no-check` skips it; a harness failure lands as an ERROR on its spec item). Failing items are listed one by one in the default TOON output's `items[].issues[]` (`--output human` prints `FAIL <item_type>/<id>` lines above the `Totals` line).
 3. Read: `llmanspec/specs/**` (`<capability>.feature`, the single source of truth) on the branch, `proposal.md` and `design.md` (if present), `tasks.md`; ignore residual old docs under `changes/<id>/specs/`.
 4. **Dual-axis review (kept separate so neither masks the other)** — diff against `git diff <merge-base>...HEAD` (merge-base is COMPUTED via `git merge-base <local-default> HEAD`; the stored base_sha is audit-only and MUST NOT feed range math):
    - **Spec axis**: does the implementation satisfy the `规则:` block requirement statement (free-text description, judged by its semantics) and the nested `场景:` GWT steps? Missing/partial behaviors, wrong implementations, and scope creep not asked for by the spec → suggest minimal fixes or artifact updates. Check where before/after evidence (counts, baselines) was taken: it MUST be measured on the change branch (against the freshly computed merge-base); a value measured on the default branch is usually trivially the baseline and proves nothing.
@@ -55,13 +55,13 @@ flowchart LR
      | Middle Man (just delegates) | cut it, call direct |
      | Refused Bequest (subclass rejects most inheritance) | use composition |
    - The two axes may be reviewed in parallel (sub-agents); the report MUST present them separately, MUST NOT merge or cross-rerank (one axis passing must not mask the other failing).
-5. **BDD verification** — only when `config.yaml` has a `bdd:` block:
+5. **BDD verification** — only when `config.yaml` has a `specs:` block:
    - Confirm the change is branch-bound and you are on that branch.
-   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; when `bdd.run_command` is configured the harness runs by default (`--no-check` skips it) and a failure maps to an ERROR on the matching spec item.
+   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; when `specs.check_command` is configured the harness runs by default (`--no-check` skips it) and a failure maps to an ERROR on the matching spec item.
    - Optional read-only review: `llman-sdd change diff <id>` (or `--export-patch <path>`) — review/export only, never an apply step.
    - Next step after verify passes: `llman-sdd-archive` (not inline finalize here).
-{% if bdd_verify_prompt %}
-   - Extra requirement: {{ bdd_verify_prompt }}
+{% if specs_verify_prompt %}
+   - Extra requirement: {{ specs_verify_prompt }}
 {% endif %}
 6. Produce a short report: **CRITICAL** (must fix before archive) / **WARNING** (should fix) / **SUGGESTION** (nice to have).
 7. **Human review gate**: once the report has no CRITICAL findings and before suggesting archive, run `llman-sdd review`: exit code zero → suggest `llman-sdd-archive`; non-zero = CRITICAL → fix via `llman-sdd-apply`, then re-run review; MUST NOT enter finalize/archive with CRITICAL findings open.

package/templates/zh-Hans/skills/llman-sdd-apply.md

@@ -76,7 +76,7 @@ flowchart LR
 - SDD 校验：`llman-sdd validate <id> --strict`
 
 **门禁证据**：
-- 收口会执行已配置的 `bdd.run_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
+- 收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
 - 门禁结论 MUST 来自真实 harness：MUST NOT 以 `--no-check` 取得「通过」；harness 失败 MUST 先查根因（环境变量泄漏、嵌套调用守卫、工作目录错误等），MUST NOT 以「固有/自指属性」定性后绕过。
 - 前后对比类判据（计数、基线）MUST 在 change 分支上测量（相对现算 merge-base）；默认分支测得的值通常恒为基线，不构成证据。
 - 重构或批量替换类 task：MUST 对比改动前后测试用例数；门禁全绿但用例数下降视为失败。

package/templates/zh-Hans/skills/llman-sdd-explore.md

@@ -46,7 +46,7 @@ flowchart LR
    - 决策回写：已解决的决策写进该 change 的 `proposal.md`「Open Questions」段。
    - 完成判据：每个待定决策都已解决或显式推迟。未触发时保持默认（问 1–3 个问题）。
 4. 涉及某个 change id 时，读 `llmanspec/changes/<id>/` 下的工件。
-   - 诊断校验错误先跑 `llman-sdd validate <spec> --strict` 过结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性）；配置了 `bdd.run_command` 时 validate 缺省执行该 harness（`--no-check` 跳过）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条指明；`--output human` 输出人读 `FAIL <item_type>/<id>` 行。
+   - 诊断校验错误先跑 `llman-sdd validate <spec> --strict` 过结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性）；配置了 `specs.check_command` 时 validate 缺省执行该 harness（`--no-check` 跳过）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条指明；`--output human` 输出人读 `FAIL <item_type>/<id>` 行。
 5. 探索 2–3 个选项与权衡。
 6. 判断变更规模，确定是否走完整 SDD。
 7. 结论清晰时建议用户记录（勿自动写）：

package/templates/zh-Hans/skills/llman-sdd-propose.md

@@ -83,11 +83,11 @@ llman-sdd validate <change-id> --strict
 ```
 MUST 通过才能继续；失败项在 validate 输出的 `items[].issues[]` 逐条指明，按条修复后重跑。
 
-### 4a) 可选 BDD runner（`bdd:` 段）
-- 读 `llmanspec/config.yaml` 是否含 `bdd:` 段：
-  - **有**：`bdd.run_command` 是项目的 BDD 执行入口；validate 在目标集含 spec 时缺省执行它（`--no-check` 跳过）。撰写仍按 4b。
-  - **无**：若本次 change 含可执行行为场景（用户会想运行的 Given/When/Then），**一次性前置**询问是否启用 `bdd:` runner 段（会向 `config.yaml` 加一个 `bdd:` 段——仅 runner，不改生命周期）。**是**：展示要加的精确 `bdd:` 段（`run_command` 选匹配项目测试框架的——rstest-bdd 用 `cargo test --features bdd`，pytest-bdd 用 `pytest {feature_dir} -k {feature_name} -v`），用户确认或修改后写入 `config.yaml`，再按 4b 继续。**否**：feature 仍做结构校验；BDD 执行责任始终在项目测试套件。
-- **MUST NOT 静默添加 `bdd:` 段**——总是先问。添加它会向全项目声明 BDD 执行入口。
+### 4a) 可选 BDD runner（`specs:` 段）
+- 读 `llmanspec/config.yaml` 是否含 `specs:` 段：
+  - **有**：`specs.check_command` 是项目的 BDD 执行入口；validate 在目标集含 spec 时缺省执行它（`--no-check` 跳过）。撰写仍按 4b。
+  - **无**：若本次 change 含可执行行为场景（用户会想运行的 Given/When/Then），**一次性前置**询问是否启用 `specs:` 验证 runner 段（会向 `config.yaml` 加一个 `specs:` 段——仅 runner，不改生命周期）。**是**：展示要加的精确 `specs:` 段（`check_command` 选匹配项目测试框架的——rstest-bdd 用 `cargo test --features bdd`，pytest-bdd 用 `pytest {feature_dir} -k {feature_name} -v`），用户确认或修改后写入 `config.yaml`，再按 4b 继续。**否**：feature 仍做结构校验；BDD 执行责任始终在项目测试套件。
+- **MUST NOT 静默添加 `specs:` 段**——总是先问。添加它会向全项目声明 BDD 执行入口。
 
 ### 4b) 单轨 feature 撰写
 - 规划文档可短暂留在默认分支；**不要**在默认分支编辑 `llmanspec/specs/**`。绑定分支后，落地 specs 与实现都在绑定分支上。

package/templates/zh-Hans/skills/llman-sdd-validate.md

@@ -12,12 +12,12 @@ metadata:
 ## 步骤
 1. 单个：`llman-sdd validate <id>`；批量：`llman-sdd validate --all`（或 `--changes` / `--specs`）；CI/自动化用 `--strict`。
 2. 校验失败时汇总错误，给出最小可执行的修复建议。
-{% if bdd_enabled %}
-3. **BDD 校验**：
+{% if specs_enabled %}
+3. **Spec 校验**：
    - 在**绑定分支**上验证 `.feature` Gherkin 与 `@req` / 双写门禁；`.feature` 是 harness 权威——可执行 GWT 只在其中维护。
    - 生命周期门禁：`change start` / `attach`（绑定分支）、`finalize`（收口；自动提交 `archive(sdd): <id>`，`--no-commit` 跳过）/ `diff`（只读）。
-   - `llman-sdd validate --specs` 做结构与合约门禁；配置 `bdd.run_command` 时缺省执行该 harness（`--no-check` 跳过，`--check` 为兼容别名），无占位符的命令每次调用至多执行一次。
-   - `list --specs --json` 查看 `morphology`（ruleCount / ruleEnforcedCount / rulePendingCount / acceptanceCount / featureScenarioCount）。
+   - `llman-sdd validate --specs` 做结构与合约门禁；配置 `specs.check_command` 时缺省执行该 harness（`--no-check` 跳过，`--check` 为兼容别名），无占位符的命令每次调用至多执行一次。
+   - `list --specs --json` 查看 `morphology`（requirementCount / requirementBoundCount / requirementUnboundCount / acceptanceCount / featureScenarioCount）。
    - change JSON 状态字段：`stage`（draft/designed/planned/full）/ `specsLanded` / `needsSpecsChange` / `readyToImplement`（`show --output json`）。
 {% endif %}
 

package/templates/zh-Hans/skills/llman-sdd-verify.md

@@ -26,7 +26,7 @@ flowchart LR
 - **必须先 apply 全绿**：未完成实现的 change 跳过验证。
 - **CRITICAL 必须修复**：归档前清零。
 - **亲自复跑门禁**：MUST 亲自重跑 `llman-sdd validate <id> --strict`（真实 harness）与项目门禁，MUST NOT 采信实现者报告的门禁结论；复跑结果与报告不符 → CRITICAL。
-- **`--no-check` 不是证据**：以 `--no-check` 取得的门禁证据 → CRITICAL。收口会执行已配置的 `bdd.run_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
+- **`--no-check` 不是证据**：以 `--no-check` 取得的门禁证据 → CRITICAL。收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
 - **不要问「要不要继续」**：跑完整验证流程，输出完整报告。
 
 {{ unit("skills/stage-guard") }}
@@ -34,7 +34,7 @@ flowchart LR
 ## 步骤
 1. 确定 change id（不明确时让用户从 `llman-sdd list --json` 选）。
 2. 快速校验门禁：`llman-sdd validate <id> --strict`。
-   - 诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / req_id 唯一性）先跑结构校验（配置 `bdd.run_command` 时 validate 缺省执行该 harness，`--no-check` 跳过；harness 失败以 ERROR 落在对应 spec 条目）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条列出（`--output human` 输出 `FAIL <item_type>/<id>` 行，位于 `Totals` 上方）。
+   - 诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / req_id 唯一性）先跑结构校验（配置 `specs.check_command` 时 validate 缺省执行该 harness，`--no-check` 跳过；harness 失败以 ERROR 落在对应 spec 条目）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条列出（`--output human` 输出 `FAIL <item_type>/<id>` 行，位于 `Totals` 上方）。
 3. 阅读：分支上的 `llmanspec/specs/**`（`<capability>.feature`，唯一事实来源）、`proposal.md` 与 `design.md`（如有）、`tasks.md`；`changes/<id>/specs/` 若有残留旧文档可忽略。
 4. **双轴审查（两轴分离，互不掩盖）**——对比 diff（`git diff <merge-base>...HEAD`，merge-base 现算 `git merge-base <本地默认分支> HEAD`；存储的 base_sha 仅审计、MUST NOT 参与范围计算）：
    - **合约轴**：实现是否满足 `规则:` 块的需求表述(描述为自由文本,以其语义为准)与嵌套 `场景:` 的 GWT 步骤？缺失/部分实现、错误实现、spec 未要求的超范围改动 → 给最小修复建议或建议更新工件。前后对比类证据（计数、基线）核对测量位置：MUST 在 change 分支上测量（相对现算 merge-base）；默认分支测得的值通常恒为基线，不构成证据。
@@ -55,13 +55,13 @@ flowchart LR
      | Middle Man（只转发） | 删掉直连 |
      | Refused Bequest（子类拒绝大部分继承） | 改组合 |
    - 两轴可并行（sub-agent）审查；报告 MUST 分离呈现，MUST NOT 合并或交叉重排（一轴通过不能掩盖另一轴失败）。
-5. **BDD 验证**——仅当 `config.yaml` 含 `bdd:` 段：
+5. **Spec 验证**——仅当 `config.yaml` 含 `specs:` 段：
    - 确认 change 已绑定分支且当前在该分支上。
-   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；配置 `bdd.run_command` 时缺省执行该 harness（`--no-check` 跳过），失败映射为对应 spec 条目的 ERROR。
+   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；配置 `specs.check_command` 时缺省执行该 harness（`--no-check` 跳过），失败映射为对应 spec 条目的 ERROR。
    - 可选只读审查：`llman-sdd change diff <id>`（或 `--export-patch <path>`）——仅审查/导出，绝不当作 apply 步骤。
    - verify 通过后下一步 `llman-sdd-archive`（勿在此 inline finalize）。
-{% if bdd_verify_prompt %}
-   - 额外要求: {{ bdd_verify_prompt }}
+{% if specs_verify_prompt %}
+   - 额外要求: {{ specs_verify_prompt }}
 {% endif %}
 6. 输出简短报告：**CRITICAL**（归档前必须修复）/ **WARNING**（建议修复）/ **SUGGESTION**（可选优化）。
 7. **人审关卡**：报告无 CRITICAL 后、建议归档前跑 `llman-sdd review`：退出码零 → 建议 `llman-sdd-archive`；非零 = CRITICAL → 用 `llman-sdd-apply` 修复后重跑 review；MUST NOT 带 CRITICAL 进入 finalize/archive。