@llman-sdd/cli 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/cli",
-  "version": "0.5.1",
+  "version": "0.7.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.1",
+    "@llman-sdd/core": "0.7.0",
     "commander": "^15.0.0"
   },
   "engines": {

package/src/cli-shared.ts

@@ -4,13 +4,16 @@
  * Command modules depend one-way on this file; it must not import any of them.
  */
 import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 
 import {
   discoverSpecs,
   embeddedTemplates,
   loadConfig,
+  loadConfigDetail,
   makeEmbeddedTemplateIo,
   resolveChangeId,
+  resolveInstanceRoot,
   type TemplateIo,
 } from '@llman-sdd/core';
 import type { Command } from 'commander';
@@ -74,10 +77,49 @@ export function loadSpecEntries(): ReturnType<typeof discoverSpecs> {
   return discoverSpecs('llmanspec/specs', newIo());
 }
 
+/**
+ * Per-root specs dir (r94): the nearest llmanspec/ instance at or above the
+ * start dir (--directory override). Identity 'llmanspec/specs' when the cwd
+ * is itself the instance root — legacy relative output paths stay
+ * byte-identical there.
+ */
+export function resolveRootSpecsDir(directory?: string): string {
+  const start = directory ?? process.cwd();
+  const root = resolveInstanceRoot(start, newIo());
+  if (root === null) {
+    throw new CliError(`no llman spec root at or above: ${start}`);
+  }
+  return root === process.cwd() ? 'llmanspec/specs' : join(root, 'llmanspec', 'specs');
+}
+
+/** Spec entries of the resolved instance root (per-root registry, r94). */
+export function loadRootSpecEntries(directory?: string): ReturnType<typeof discoverSpecs> {
+  return discoverSpecs(resolveRootSpecsDir(directory), 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/init.ts

@@ -1,11 +1,21 @@
 import { mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-import { runInit } from '@llman-sdd/core';
+import { discoverRoots, refreshSubRootBlocks, runInit } from '@llman-sdd/core';
 import type { Command } from 'commander';
 
 import { CliError, templateIo, version } from '../cli-shared.ts';
-import { makeIo } from '../io.ts';
+import { makeCliGit, makeIo } from '../io.ts';
+
+/**
+ * r93: the repo-root instance (git toplevel, or outside any repo) carries the
+ * agent skill surface; a sub-root init defaults to blocks-only. `--skills`
+ * opts a sub-root in.
+ */
+function isRepoRootInstance(root: string): boolean {
+  const toplevel = makeCliGit(root).runOpt(['rev-parse', '--show-toplevel']);
+  return toplevel === null || resolve(toplevel) === root;
+}
 
 export function registerInit(program: Command): void {
   program
@@ -13,10 +23,17 @@ export function registerInit(program: Command): void {
     .description('Initialize llmanspec in your project (--update to refresh existing)')
     .argument('[path]', 'target directory (created when missing; defaults to cwd)')
     .option('--update', 'refresh an existing installation')
+    .option(
+      '--skills',
+      'inject .agents/skills at a sub-root instance (repo-root instances always inject)',
+    )
     .option('--locale <locale>', 'locale for generated templates (defaults to config or en)')
     .option('--lang <locale>', 'alias of --locale')
     .action(
-      (path: string | undefined, options: { update?: boolean; locale?: string; lang?: string }) => {
+      (
+        path: string | undefined,
+        options: { update?: boolean; skills?: boolean; locale?: string; lang?: string },
+      ) => {
         if (options.locale !== undefined && options.lang !== undefined) {
           throw new CliError('--locale and --lang are mutually exclusive (they are aliases)');
         }
@@ -25,13 +42,28 @@ export function registerInit(program: Command): void {
           root = resolve(path);
           mkdirSync(root, { recursive: true });
         }
+        const repoRootInstance = isRepoRootInstance(root);
         const result = runInit(makeIo(root), templateIo, {
           update: options.update ?? false,
           locale: options.locale ?? options.lang,
           version,
+          skills: options.skills === true || repoRootInstance,
         });
+        let swept = '';
+        if ((options.update ?? false) && repoRootInstance) {
+          // r93 --update sweep: refresh managed blocks of every discovered
+          // sub-root (blocks only; skills stay a repo-root surface).
+          const subRoots = discoverRoots(root, makeIo(root)).filter((r) => r.rootDir !== root);
+          const refreshed: string[] = [];
+          for (const sub of subRoots) {
+            if (refreshSubRootBlocks(makeIo(sub.rootDir), templateIo, version)) {
+              refreshed.push(sub.rootDir);
+            }
+          }
+          if (refreshed.length > 0) swept = `, blocks refreshed: ${refreshed.join(', ')}`;
+        }
         const removed = result.removed.length > 0 ? `, removed: ${result.removed.join(', ')}` : '';
-        console.log(`initialized llmanspec (${result.skills.length} skills${removed})`);
+        console.log(`initialized llmanspec (${result.skills.length} skills${removed}${swept})`);
       },
     );
 }

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,26 @@ 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,
+  loadRootSpecEntries,
+  newIo,
+  resolveOutMode,
+  resolveRootSpecsDir,
+} from '../cli-shared.ts';
 
 /** Walk paths collecting .feature files (directories recurse). */
 function collectFeatureFiles(paths: string[]): string[] {
@@ -51,13 +62,18 @@ export function registerSpec(program: Command): void {
     .description('Generate a single-track spec skeleton for a capability')
     .argument('<capability>')
     .option('--force', 'overwrite an existing spec file')
-    .action((capability: string, options: { force?: boolean }) => {
+    .option(
+      '--directory <path>',
+      'instance root resolution start (default: nearest llmanspec/ at or above cwd)',
+    )
+    .action((capability: string, options: { force?: boolean; directory?: string }) => {
       const locale = loadCliConfig()?.locale ?? 'en';
-      const path = join('llmanspec', 'specs', `${capability}.feature`);
+      const specsDir = resolveRootSpecsDir(options.directory);
+      const path = join(specsDir, `${capability}.feature`);
       if (!options.force && existsSync(path)) {
         throw new CliError(`spec already exists: ${path} (use --force to overwrite)`);
       }
-      const written = scaffoldSpec(newIo(), 'llmanspec/specs', capability, locale, {
+      const written = scaffoldSpec(newIo(), specsDir, capability, locale, {
         force: options.force,
       });
       console.log(`wrote ${written}`);
@@ -65,10 +81,14 @@ export function registerSpec(program: Command): void {
 
   spec
     .command('next-req-id')
-    .description('Allocate the next free global req id (rN)')
+    .description('Allocate the next global req id (max in use + 1, rN)')
     .option('--json', 'emit {reqId}')
-    .action((options: { json?: boolean }) => {
-      const reqId = nextReqId(newIo(), 'llmanspec/specs');
+    .option(
+      '--directory <path>',
+      'instance root resolution start (default: nearest llmanspec/ at or above cwd)',
+    )
+    .action((options: { json?: boolean; directory?: string }) => {
+      const reqId = nextReqId(newIo(), resolveRootSpecsDir(options.directory));
       if (options.json) console.log(JSON.stringify({ reqId }, null, 2));
       else console.log(reqId);
     });
@@ -81,16 +101,31 @@ export function registerSpec(program: Command): void {
     .argument('<req_id>')
     .requiredOption('--title <title>', 'rule title')
     .requiredOption('--statement <statement>', 'rule statement (free text; multiple lines via \\n)')
-    .action((capability: string, reqId: string, options: { title: string; statement: string }) => {
-      const io = newIo();
-      const path = addReq(io, 'llmanspec/specs', loadSpecEntries(), {
-        capability,
-        reqId,
-        title: options.title,
-        statement: options.statement,
-      });
-      console.log(path);
-    });
+    .option(
+      '--directory <path>',
+      'instance root resolution start (default: nearest llmanspec/ at or above cwd)',
+    )
+    .action(
+      (
+        capability: string,
+        reqId: string,
+        options: { title: string; statement: string; directory?: string },
+      ) => {
+        const io = newIo();
+        const path = addReq(
+          io,
+          resolveRootSpecsDir(options.directory),
+          loadRootSpecEntries(options.directory),
+          {
+            capability,
+            reqId,
+            title: options.title,
+            statement: options.statement,
+          },
+        );
+        console.log(path);
+      },
+    );
 
   spec
     .command('add-scenario')
@@ -101,22 +136,31 @@ export function registerSpec(program: Command): void {
     .option('--given <given>', 'Given step (optional)')
     .requiredOption('--when <when>', 'When step')
     .requiredOption('--then <then>', 'Then step')
+    .option(
+      '--directory <path>',
+      'instance root resolution start (default: nearest llmanspec/ at or above cwd)',
+    )
     .action(
       (
         capability: string,
         reqId: string,
         scenarioId: string,
-        options: { given?: string; when: string; then: string },
+        options: { given?: string; when: string; then: string; directory?: string },
       ) => {
         const io = newIo();
-        const path = addScenario(io, 'llmanspec/specs', loadSpecEntries(), {
-          capability,
-          reqId,
-          scenarioId,
-          given: options.given,
-          when: options.when,
-          thenText: options.then,
-        });
+        const path = addScenario(
+          io,
+          resolveRootSpecsDir(options.directory),
+          loadRootSpecEntries(options.directory),
+          {
+            capability,
+            reqId,
+            scenarioId,
+            given: options.given,
+            when: options.when,
+            thenText: options.then,
+          },
+        );
         console.log(path);
       },
     );
@@ -166,8 +210,12 @@ export function registerSpec(program: Command): void {
     .command('resolve-req')
     .description('Resolve an rN to its capability and statement')
     .argument('<req_id>')
-    .action((reqId: string) => {
-      const resolved = resolveReq(loadSpecEntries(), reqId);
+    .option(
+      '--directory <path>',
+      'instance root resolution start (default: nearest llmanspec/ at or above cwd)',
+    )
+    .action((reqId: string, options: { directory?: string }) => {
+      const resolved = resolveReq(loadRootSpecEntries(options.directory), reqId);
       if (resolved === null) {
         throw new CliError(`req id not found: ${reqId}`);
       }
@@ -178,4 +226,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(loadRootSpecEntries(), 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

@@ -1,3 +1,5 @@
+import { relative } from 'node:path';
+
 import {
   applyStrict,
   buildDuplicatesFor,
@@ -5,11 +7,14 @@ import {
   collectChanges,
   currentBranch,
   defaultBranch,
+  discoverRoots,
   evaluateStaleness,
   formatTotals,
   notApplicableStaleness,
   renderMachine,
+  resolveInstanceRoot,
   runHarnessForSpecs,
+  scopeCrossings,
   specRelFor,
   specIdOf,
   STAGE_ORDER,
@@ -17,6 +22,7 @@ import {
   validateChange,
   type ChangeIssue,
   type HarnessGate,
+  type RootEntry,
   type StalenessInfo,
 } from '@llman-sdd/core';
 import type { Command } from 'commander';
@@ -51,13 +57,34 @@ function compareItems(a: VItem, b: VItem): number {
   return a.id < b.id ? -1 : a.id > b.id ? 1 : a.type.localeCompare(b.type);
 }
 
+/**
+ * Multi-root context of the specs being validated (r91-r92): `repoRelPrefix`
+ * lifts instance-root-relative scopes into repo-relative paths for the
+ * staleness diff match ('' when the instance root is the git toplevel —
+ * byte-identical legacy behavior); `otherRoots` feeds the single-ownership
+ * crossings that surface as ERROR issues.
+ */
+export interface InstanceContext {
+  repoRelPrefix: string;
+  otherRoots: RootEntry[];
+}
+
 function specV1Items(
-  opts: { strict?: boolean; harness?: HarnessGate; harnessOnlyIds?: string[] },
+  opts: {
+    strict?: boolean;
+    harness?: HarnessGate;
+    harnessOnlyIds?: string[];
+    instance?: InstanceContext;
+  },
   entries: ReturnType<typeof loadSpecEntries> = loadSpecEntries(),
 ): VItem[] {
   const io = newIo();
   const git = makeCliGit(process.cwd());
   const duplicatesFor = buildDuplicatesFor(entries);
+  const liftScope = (scope: string): string =>
+    opts.instance !== undefined && opts.instance.repoRelPrefix !== ''
+      ? `${opts.instance.repoRelPrefix}/${scope}`
+      : scope;
 
   const items: VItem[] = [];
   for (const entry of entries) {
@@ -65,12 +92,13 @@ function specV1Items(
     const verdict = validateCapability(entry as never, duplicatesFor, io, {
       strict: opts.strict === true,
     });
+    const scopes = entry.doc.header.scope?.split(',').map((s) => s.trim()) ?? [];
     const specRel = specRelFor(entry.fileName);
     const staleness = evaluateStaleness({
       git,
       root: process.cwd(),
       specRel,
-      scope: entry.doc.header.scope?.split(',').map((s) => s.trim()) ?? [],
+      scope: scopes.map(liftScope),
       baseRefEnv: process.env.LLMANSPEC_BASE_REF,
     });
     let issues: ChangeIssue[] = verdict.items.map((i) => ({
@@ -78,6 +106,18 @@ function specV1Items(
       path: i.id,
       message: i.message,
     }));
+    if (opts.instance !== undefined) {
+      for (const crossing of scopeCrossings(scopes, process.cwd(), opts.instance.otherRoots)) {
+        issues = [
+          ...issues,
+          {
+            level: 'ERROR',
+            path: 'single-ownership',
+            message: `scope '${crossing.scope}' crosses sub-root '${crossing.rootDir}' — migrate these specs into that root or narrow the scope (one path, one root)`,
+          },
+        ];
+      }
+    }
     if (opts.strict === true) issues = [...issues, ...applyStrict(staleness.issues)];
     else issues = [...issues, ...staleness.issues];
     items.push({
@@ -201,9 +241,33 @@ function renderValidateText(items: VItem[]): void {
   console.log(formatTotals(passed, failed, items.length));
 }
 
-function renderValidateReport(items: VItem[], mode: 'json' | 'compact-json' | 'toon'): void {
+function gitToplevelOrCwd(): string {
+  const toplevel = makeCliGit(process.cwd()).runOpt(['rev-parse', '--show-toplevel']);
+  return toplevel ?? process.cwd();
+}
+
+/**
+ * Multi-root context of the cwd instance (r91-r92): empty otherRoots + ''
+ * prefix when run at a lone root — legacy byte-identical behavior.
+ */
+function instanceContextFor(maxDepth: number): InstanceContext {
+  const toplevel = gitToplevelOrCwd();
+  const otherRoots = discoverRoots(toplevel, newIo(), { maxDepth }).filter(
+    (r) => r.rootDir !== process.cwd(),
+  );
+  const repoRelPrefix = toplevel === process.cwd() ? '' : relative(toplevel, process.cwd());
+  return { repoRelPrefix, otherRoots };
+}
+
+interface RootReport {
+  root: string;
+  items: VItem[];
+  summary: ReturnType<typeof summarizeItems>;
+}
+
+function summarizeItems(items: VItem[]) {
   const types = [...new Set(items.map((i) => i.type))] as string[];
-  const summary = {
+  return {
     totals: {
       items: items.length,
       passed: items.filter((i) => i.valid).length,
@@ -222,7 +286,10 @@ function renderValidateReport(items: VItem[], mode: 'json' | 'compact-json' | 't
       {},
     ),
   };
-  console.log(renderMachine({ items, summary, version: '1.0' }, mode));
+}
+
+function renderValidateReport(items: VItem[], mode: 'json' | 'compact-json' | 'toon'): void {
+  console.log(renderMachine({ items, summary: summarizeItems(items), version: '1.0' }, mode));
 }
 
 const SPEC_NEXT_STEPS = [
@@ -258,7 +325,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 +336,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)`);
     },
   };
 }
@@ -285,9 +352,17 @@ export function registerValidate(program: Command): void {
     .option('--type <type>', 'force disambiguation: change | spec')
     .option('--stage <stage>', 'change stage gate: draft | designed | planned | full')
     .option('--strict', 'warnings also make the exit code non-zero')
+    .option(
+      '--directory <path>',
+      'instance root resolution start (default: nearest llmanspec/ at or above cwd)',
+    )
+    .option(
+      '--all-roots',
+      'aggregate: validate every discovered llmanspec root (specs scope, any root red → non-zero exit)',
+    )
     .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(
     (
@@ -304,6 +379,8 @@ export function registerValidate(program: Command): void {
         includeInfo?: boolean;
         output?: string;
         check?: boolean;
+        directory?: string;
+        allRoots?: boolean;
       },
     ) => {
       if (!assertCompactJsonPairing(options)) return;
@@ -323,6 +400,77 @@ export function registerValidate(program: Command): void {
       ) {
         throw new CliError(`invalid --stage: ${options.stage}`);
       }
+      const maxDepth = cliMaxScanDepth(program);
+
+      // ---- aggregate over every discovered root (r91) ----
+      if (options.allRoots === true) {
+        if (item !== undefined) {
+          throw new CliError('--all-roots validates every root; drop the <item> argument');
+        }
+        const start = options.directory ?? gitToplevelOrCwd();
+        const roots = discoverRoots(start, newIo(), { maxDepth });
+        if (roots.length === 0) {
+          throw new CliError(`no llmanspec roots discovered under: ${start}`);
+        }
+        const originalCwd = process.cwd();
+        const reports: RootReport[] = [];
+        let anyFail = false;
+        try {
+          for (const root of roots) {
+            process.chdir(root.rootDir);
+            const items = specV1Items({
+              strict: options.strict,
+              harness: makeHarnessGate(options),
+              instance: instanceContextFor(maxDepth),
+            });
+            const visible = keepInfo ? items : items.map(stripInfo);
+            if (visible.some((i) => !i.valid)) anyFail = true;
+            reports.push({
+              root: relative(start, root.rootDir) || '.',
+              items: visible,
+              summary: summarizeItems(visible),
+            });
+          }
+        } finally {
+          process.chdir(originalCwd);
+        }
+        if (outMode === 'human') {
+          for (const report of reports) {
+            console.log(`root ${report.root}`);
+            renderValidateText(report.items);
+          }
+        } else {
+          const totals = reports.reduce(
+            (acc, r) => ({
+              items: acc.items + r.summary.totals.items,
+              passed: acc.passed + r.summary.totals.passed,
+              failed: acc.failed + r.summary.totals.failed,
+            }),
+            { items: 0, passed: 0, failed: 0 },
+          );
+          console.log(
+            renderMachine({ roots: reports, summary: { totals }, version: '1.0' }, outMode),
+          );
+        }
+        if (anyFail) console.error('Error: validation failed');
+        exitWith(anyFail ? 1 : 0);
+        return;
+      }
+
+      // ---- instance root resolution: --directory start, else nearest
+      // ancestor llmanspec/ ("cd into the subpackage and run", r94). A no-op
+      // when cwd already sits at a root (byte-identical legacy path). ----
+      if (options.directory !== undefined) {
+        const root = resolveInstanceRoot(options.directory, newIo());
+        if (root === null) {
+          throw new CliError(`no llmanspec root at or above: ${options.directory}`);
+        }
+        process.chdir(root);
+      } else {
+        const root = resolveInstanceRoot(process.cwd(), newIo());
+        if (root !== null && root !== process.cwd()) process.chdir(root);
+      }
+
       const harness = makeHarnessGate(options);
 
       // ---- single item (auto-disambiguate: spec first, then change) ----
@@ -332,7 +480,12 @@ export function registerValidate(program: Command): void {
           options.type === 'change' ? undefined : entries.find((e) => specIdOf(e) === item);
         if (specEntry !== undefined) {
           const items = specV1Items(
-            { strict: options.strict, harness, harnessOnlyIds: [item] },
+            {
+              strict: options.strict,
+              harness,
+              harnessOnlyIds: [item],
+              instance: instanceContextFor(maxDepth),
+            },
             entries,
           );
           const mine = items.find((i) => i.id === item);
@@ -424,10 +577,18 @@ export function registerValidate(program: Command): void {
       const effectiveChanges = defaultSpecsOnly ? false : changeScope;
 
       let items: VItem[] = [];
-      if (effectiveSpecs) items = items.concat(specV1Items({ strict: options.strict, harness }));
+      if (effectiveSpecs) {
+        items = items.concat(
+          specV1Items({
+            strict: options.strict,
+            harness,
+            instance: instanceContextFor(maxDepth),
+          }),
+        );
+      }
       if (effectiveChanges) {
         const names = collectChanges(newIo(), process.cwd(), new Date(), {
-          maxScanDepth: cliMaxScanDepth(program),
+          maxScanDepth: maxDepth,
         }).map((c) => c.name);
         items = items.concat(
           changeV1Items(names, { stage: options.stage, strict: options.strict }),

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;