@llman-sdd/core 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.5.0",
+  "version": "0.6.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,14 +33,28 @@ export type {
   ScenarioStep,
   SpecStructuralError,
 } from './spec/ir.ts';
-export { specIdOf } from './spec/ir.ts';
+export { ruleHasRunnableScenario, specIdOf } from './spec/ir.ts';
 export {
   SpecParseError,
   localeToGherkinLang,
   parseCapability,
   parseFeatureSource,
+  sourceDialect,
 } from './spec/parser.ts';
-export { buildReqRegistry, type ReqRegistry, type RegistryDuplicate } from './spec/reqRegistry.ts';
+export {
+  BLOCK_KEYWORD_LINE_RE,
+  officialKeywords,
+  officialKeywordsOrEn,
+  stepKeywordToOfficialKind,
+  STEP_KIND_BY_KEYWORD,
+  type GherkinKeywords,
+} from './spec/keywords.ts';
+export {
+  buildReqRegistry,
+  type RegistryDuplicate,
+  type RegistryOccurrence,
+  type ReqRegistry,
+} from './spec/reqRegistry.ts';
 export {
   analyzeLegacy,
   hasNativeRules,
@@ -150,7 +170,7 @@ export {
 export {
   ETHICS_KEYS,
   buildTemplateVars,
-  effectiveRunCommand,
+  effectiveCheckCommand,
   enforceEthicsGovernance,
   loadLocaleResource,
   loadSkillTemplates,
@@ -183,11 +203,22 @@ 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';
 export { showChangeJson, type ShowDeps, type ShowFsIo } from './report/show.ts';
-export { nextReqId, scaffoldSpec, type SpecHelperIo } from './report/specHelpers.ts';
+export {
+  nextReqId,
+  scaffoldSpec,
+  skeletonContent,
+  type SpecHelperIo,
+} from './report/specHelpers.ts';
 export {
   collectSpecs,
   morphologyOf,

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 -->';

package/src/report/specHelpers.ts

@@ -1,3 +1,4 @@
+import { officialKeywords, officialKeywordsOrEn } from '../spec/keywords.ts';
 import { localeToGherkinLang, parseCapability } from '../spec/parser.ts';
 import { buildReqRegistry } from '../spec/reqRegistry.ts';
 /**
@@ -57,22 +58,23 @@ export function nextReqId(io: SpecHelperIo, specsDir: string): string {
 export function skeletonContent(capability: string, reqId: string, locale: string): string {
   const zh = localeFallbacks(locale)[0] === 'zh-Hans';
   // r7: the `# language:` header derives from the locale mapping — never a
-  // second hardcoded caliber.
-  const language = localeToGherkinLang(zh ? 'zh-Hans' : 'en');
+  // second hardcoded caliber. Table-less locales fall back to en wholesale
+  // (header + keywords same-source) so the skeleton stays parseable.
+  const mapped = localeToGherkinLang(locale);
+  const language = officialKeywords(mapped) !== null ? mapped : 'en';
+  const kw = officialKeywordsOrEn(language);
   const header = zh
     ? `# language: ${language}\n# capability: ${capability}\n# purpose: TODO: 一句话描述该能力与其目的。\n# scope: llmanspec/`
     : `# language: ${language}\n# capability: ${capability}\n# purpose: TODO: Describe this capability and its purpose.\n# scope: llmanspec/`;
-  const feature = zh ? `功能: ${capability}` : `Feature: ${capability}`;
-  const ruleKw = zh ? '规则' : 'Rule';
-  const scenarioKw = zh ? '场景' : 'Scenario';
-  const ruleTitle = 'TODO-rule';
   const ruleDesc = zh ? 'TODO: 需求描述(自由文本)。' : 'TODO: requirement statement (free text).';
-  const scTitle = 'TODO-acceptance';
-  // native v2 skeleton: a `规则:` block (with @req handle) + one nested example
+  // Skeleton placeholder prose is not vocabulary — the zh/en copy stays; keywords do not.
+  const steps = zh
+    ? `      ${kw.given} TODO 前置\n      ${kw.when} TODO 动作\n      ${kw.thenText} TODO 断言`
+    : `      ${kw.given} TODO precondition\n      ${kw.when} TODO action\n      ${kw.thenText} TODO assertion`;
+  // native v2 skeleton: a rule block (with @req handle) + one nested example
   return (
-    `${header}\n\n${feature}\n\n  @req:${reqId}\n  ${ruleKw}: ${ruleTitle}\n` +
-    `    ${ruleDesc}\n\n    ${scenarioKw}: ${scTitle}\n` +
-    `      假如 TODO 前置\n      当 TODO 动作\n      那么 TODO 断言\n`
+    `${header}\n\n${kw.feature}: ${capability}\n\n  @req:${reqId}\n  ${kw.rule}: TODO-rule\n` +
+    `    ${ruleDesc}\n\n    ${kw.scenario}: TODO-acceptance\n${steps}\n`
   );
 }
 

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})`);