@llman-sdd/cli 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Spec-driven development workflow CLI (the `llman-sdd` command)",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
     "build": "bun run ./scripts/build-binary.ts"
   },
   "dependencies": {
-    "@llman-sdd/core": "0.5.0",
+    "@llman-sdd/core": "0.6.0",
     "commander": "^15.0.0"
   },
   "engines": {

package/src/cli-shared.ts

@@ -9,6 +9,7 @@ import {
   discoverSpecs,
   embeddedTemplates,
   loadConfig,
+  loadConfigDetail,
   makeEmbeddedTemplateIo,
   resolveChangeId,
   type TemplateIo,
@@ -74,10 +75,29 @@ export function loadSpecEntries(): ReturnType<typeof discoverSpecs> {
   return discoverSpecs('llmanspec/specs', newIo());
 }
 
+/** One-time legacy `bdd:` migration warning — printed to stderr by the first
+ * config-reading command of a process (specs-check-config-and-unbound-feed). */
+let legacyBddWarningShown = false;
+
+function warnLegacyBdd(elevated: boolean): void {
+  if (!elevated || legacyBddWarningShown) return;
+  legacyBddWarningShown = true;
+  console.error(
+    '[WARNING] llmanspec/config.yaml uses the legacy `bdd:` section — migrate to `specs:` (`bdd.run_command` → `specs.check_command`). See migrations/v0.5-v0.6/README.md.',
+  );
+}
+
+/** Surface the legacy-section warning from a raw config source (config command). */
+export function warnLegacyBddOnce(source: string): void {
+  if (legacyBddWarningShown) return;
+  warnLegacyBdd(loadConfigDetail(source).legacyBddElevated);
+}
+
 export function loadCliConfig(): ReturnType<typeof loadConfig> | null {
-  return existsSync('llmanspec/config.yaml')
-    ? loadConfig(readFileSync('llmanspec/config.yaml', 'utf8'))
-    : null;
+  if (!existsSync('llmanspec/config.yaml')) return null;
+  const detail = loadConfigDetail(readFileSync('llmanspec/config.yaml', 'utf8'));
+  warnLegacyBdd(detail.legacyBddElevated);
+  return detail.config;
 }
 
 export function cliMaxScanDepth(program: Command): number {

package/src/commands/change.ts

@@ -40,21 +40,15 @@ function runValidateSweep(): boolean {
   return report.verdicts.some((v) => !v.ok);
 }
 
-/** r81: run or refuse the acceptance command before any merge or rename. */
+/** r81: run or refuse the spec verification command before any merge or rename. */
 function enforceCloseOutHarness(id: string, noCheck: boolean): void {
   const proposalPath = `llmanspec/changes/${id}/proposal.md`;
   const proposal = existsSync(proposalPath) ? readFileSync(proposalPath, 'utf8') : '';
   const needsSpecsChange = readNeedsSpecsChange(extractFrontmatter(proposal));
-  const hasExecutable = loadSpecEntries().some(
-    (entry) =>
-      entry.doc.rules.some((r) => r.scenarios.some((s) => s.runnable && s.stepCount > 0)) ||
-      entry.doc.orphans.some((s) => s.runnable && s.stepCount > 0),
-  );
-  const runCommand = loadCliConfig()?.bdd?.run_command ?? null;
+  const runCommand = loadCliConfig()?.specs?.check_command ?? null;
   const decision = decideCloseOutHarness({
     noCheck,
     needsSpecsChange,
-    hasExecutable,
     runCommand,
     nested: process.env.LLMAN_SDD_HARNESS_ACTIVE === '1',
   });
@@ -62,13 +56,14 @@ function enforceCloseOutHarness(id: string, noCheck: boolean): void {
     throw new CliError(`close-out aborted: ${decision.message}`);
   }
   if (decision.kind === 'skip') {
-    if (decision.announce) console.error('bdd harness skipped: --no-check');
+    if (decision.announce) console.error('spec check skipped: --no-check');
+    if (decision.warning !== undefined) console.error(`[WARNING] ${decision.warning}`);
     return;
   }
   const result = makeCliHarnessRunner().run(decision.command, process.cwd());
   if (result.spawnError !== undefined || result.exitCode !== 0) {
     const why = result.spawnError ?? `exit ${result.exitCode}`;
-    throw new CliError(`close-out aborted: bdd harness failed (${why})`);
+    throw new CliError(`close-out aborted: spec check failed (${why})`);
   }
 }
 

package/src/commands/config.ts

@@ -3,7 +3,12 @@ import { readFileSync } from 'node:fs';
 import { renderConfigOverview, renderMachine, skillsJson } from '@llman-sdd/core';
 import type { Command } from 'commander';
 
-import { addReportOutputOptions, resolveOutMode, skillDesc } from '../cli-shared.ts';
+import {
+  addReportOutputOptions,
+  resolveOutMode,
+  skillDesc,
+  warnLegacyBddOnce,
+} from '../cli-shared.ts';
 
 export function registerConfig(program: Command): void {
   const configCmd = program
@@ -12,6 +17,7 @@ export function registerConfig(program: Command): void {
 
   configCmd.description('Print a read-only llmanspec/config.yaml overview').action(() => {
     const source = readFileSync('llmanspec/config.yaml', 'utf8');
+    warnLegacyBddOnce(source);
     console.log(renderConfigOverview(source).join('\n'));
   });
 
@@ -19,7 +25,9 @@ export function registerConfig(program: Command): void {
   addReportOutputOptions(skills);
   skills.action((options: { json?: boolean; output?: string; compactJson?: boolean }) => {
     const path = 'llmanspec/config.yaml';
-    const info = skillsJson(readFileSync(path, 'utf8'));
+    const source = readFileSync(path, 'utf8');
+    warnLegacyBddOnce(source);
+    const info = skillsJson(source);
     const mode = resolveOutMode(options.output, options.json, options.compactJson);
     if (mode !== 'human') {
       console.log(renderMachine(info, mode));

package/src/commands/project.ts

@@ -1,4 +1,4 @@
-import { migrateNoteFor, migrateOverviewFor, planDedupe } from '@llman-sdd/core';
+import { buildReqRegistry, migrateNoteFor, migrateOverviewFor, planDedupe } from '@llman-sdd/core';
 import type { Command } from 'commander';
 
 import { CliError, loadCliConfig, loadSpecEntries, newIo } from '../cli-shared.ts';
@@ -11,20 +11,10 @@ export function registerProject(program: Command): void {
     .description('Remap globally duplicated req ids (report with --dry-run)')
     .option('--dry-run', 'report the remap plan without writing')
     .action((options: { dryRun?: boolean }) => {
-      // dedupe registry covers requirement handles (`@req` on 规则: headers) only.
+      // dedupe registry covers requirement handles (`@req` on 规则: headers) only;
+      // duplicates follow the occurrence model (同文件内共用或跨文件均算)
       const entries = loadSpecEntries();
-      const owners = new Map<string, string[]>();
-      for (const e of entries) {
-        for (const rule of e.doc.rules) {
-          if (rule.reqId === '') continue;
-          const list = owners.get(rule.reqId) ?? [];
-          if (!list.includes(e.fileName)) list.push(e.fileName);
-          owners.set(rule.reqId, list);
-        }
-      }
-      const duplicates = [...owners.entries()]
-        .filter(([, files]) => files.length > 1)
-        .map(([reqId, files]) => ({ reqId, files }));
+      const { duplicates } = buildReqRegistry(entries);
       if (duplicates.length === 0) {
         console.log('No colliding req_id values in llmanspec/specs.');
         return;

package/src/commands/review.ts

@@ -26,7 +26,7 @@ import { makeCliGit } from '../io.ts';
 export function registerReview(program: Command): void {
   const review = program
     .command('review')
-    .description('Aggregate review: pending/unbound/stale signals plus a validate sweep');
+    .description('Aggregate review: unbound/stale signals plus a validate sweep');
 
   review.option('--capability <capability>', 'restrict the sweep to one capability/spec id');
   addReportOutputOptions(review);

package/src/commands/show.ts

@@ -209,7 +209,7 @@ export function registerShow(program: Command): void {
         const raw = readFileSync(specPath, 'utf8').trimEnd();
         const summary = collectSpecs(entries).find((x) => x.id === item);
         const morphology = summary
-          ? `\n\n## Morphology\nruleCount=${summary.morphology.ruleCount} enforced=${summary.morphology.ruleEnforcedCount} pending=${summary.morphology.rulePendingCount} acceptanceCount=${summary.morphology.acceptanceCount}`
+          ? `\n\n## Morphology\nrequirements=${summary.requirementCount} bound=${summary.morphology.requirementBoundCount} unbound=${summary.morphology.requirementUnboundCount} acceptanceCount=${summary.morphology.acceptanceCount}`
           : '';
         console.log(`## Spec\n${raw}${morphology}`);
         return;

package/src/commands/spec.ts

@@ -5,15 +5,25 @@ import { createInterface } from 'node:readline';
 import {
   addReq,
   addScenario,
+  buildUnboundFeed,
   hasNativeRules,
   migrateNativeSource,
   nextReqId,
+  renderMachine,
   resolveReq,
   scaffoldSpec,
+  type UnboundFeed,
 } from '@llman-sdd/core';
 import type { Command } from 'commander';
 
-import { CliError, loadCliConfig, loadSpecEntries, newIo } from '../cli-shared.ts';
+import {
+  addReportOutputOptions,
+  CliError,
+  loadCliConfig,
+  loadSpecEntries,
+  newIo,
+  resolveOutMode,
+} from '../cli-shared.ts';
 
 /** Walk paths collecting .feature files (directories recurse). */
 function collectFeatureFiles(paths: string[]): string[] {
@@ -178,4 +188,31 @@ export function registerSpec(program: Command): void {
       console.log('harness:');
       for (const h of resolved.harness) console.log(`  - ${h}`);
     });
+
+  const unbound = spec
+    .command('unbound')
+    .description('List unbound requirements (no runnable nested scenario) for implementation')
+    .option('--limit <N>', 'max entries to return (default 1; 0 = all)');
+  addReportOutputOptions(unbound);
+  unbound.action(
+    (options: { limit?: string; output?: string; json?: boolean; compactJson?: boolean }) => {
+      const raw = options.limit ?? '1';
+      if (!/^\d+$/u.test(raw)) {
+        throw new CliError(`invalid --limit: ${raw} (non-negative integer)`, 2);
+      }
+      const limit = Number(raw);
+      const feed: UnboundFeed = buildUnboundFeed(loadSpecEntries(), limit);
+      const mode = resolveOutMode(options.output, options.json, options.compactJson);
+      if (mode !== 'human') {
+        console.log(renderMachine(feed, mode));
+        return;
+      }
+      console.log(`spec unbound: ${feed.returned} shown of ${feed.total} total`);
+      for (const r of feed.requirements) {
+        console.log(`  - [${r.reqId}] ${r.featurePath} :: ${r.title}`);
+        for (const line of r.statement.split('\n')) console.log(`      ${line}`);
+      }
+      if (feed.hint !== '') console.log(feed.hint);
+    },
+  );
 }

package/src/commands/validate.ts

@@ -258,7 +258,7 @@ let harnessBannerShown = false;
  * --check → check=true, --no-check → check=false, absent → undefined.
  */
 function makeHarnessGate(options: { check?: boolean }): HarnessGate {
-  const runCommand = loadCliConfig()?.bdd?.run_command ?? null;
+  const runCommand = loadCliConfig()?.specs?.check_command ?? null;
   const configured = runCommand !== null && runCommand !== '';
   return {
     nested: process.env.LLMAN_SDD_HARNESS_ACTIVE === '1',
@@ -269,7 +269,7 @@ function makeHarnessGate(options: { check?: boolean }): HarnessGate {
     onBeforeFirstRun: (expanded: string): void => {
       if (harnessBannerShown) return;
       harnessBannerShown = true;
-      console.error(`running bdd harness: ${expanded} (use --no-check to skip)`);
+      console.error(`running spec check: ${expanded} (use --no-check to skip)`);
     },
   };
 }
@@ -286,8 +286,8 @@ export function registerValidate(program: Command): void {
     .option('--stage <stage>', 'change stage gate: draft | designed | planned | full')
     .option('--strict', 'warnings also make the exit code non-zero')
     .option('--include-info', 'keep INFO-level issues (default: WARNING and above)')
-    .option('--no-check', 'skip the bdd harness')
-    .option('--check', 'run the bdd harness (default when bdd.run_command is configured)');
+    .option('--no-check', 'skip the spec check')
+    .option('--check', 'run the spec check (default when specs.check_command is configured)');
   addReportOutputOptions(validate);
   validate.action(
     (

package/src/harness.ts

@@ -1,6 +1,6 @@
 /**
  * CLI HarnessRunner adapter (validation r13/r48): executes the expanded
- * bdd.run_command through `sh -c` in the project root, exporting
+ * specs.check_command through `sh -c` in the project root, exporting
  * LLMAN_SDD_HARNESS_ACTIVE=1 so harness-spawned validate invocations skip
  * execution (nested guard). Windows (no sh) is out of scope for this change —
  * the spawnError branch surfaces it as an ERROR. stdout and stderr are merged;