@llman-sdd/cli 0.6.0 → 0.7.0

package/package.json

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

package/src/cli-shared.ts

@@ -4,6 +4,7 @@
  * 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,
@@ -12,6 +13,7 @@ import {
   loadConfigDetail,
   makeEmbeddedTemplateIo,
   resolveChangeId,
+  resolveInstanceRoot,
   type TemplateIo,
 } from '@llman-sdd/core';
 import type { Command } from 'commander';
@@ -75,6 +77,26 @@ 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;

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/spec.ts

@@ -20,9 +20,10 @@ import {
   addReportOutputOptions,
   CliError,
   loadCliConfig,
-  loadSpecEntries,
+  loadRootSpecEntries,
   newIo,
   resolveOutMode,
+  resolveRootSpecsDir,
 } from '../cli-shared.ts';
 
 /** Walk paths collecting .feature files (directories recurse). */
@@ -61,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}`);
@@ -75,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);
     });
@@ -91,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')
@@ -111,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);
       },
     );
@@ -176,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}`);
       }
@@ -201,7 +239,7 @@ export function registerSpec(program: Command): void {
         throw new CliError(`invalid --limit: ${raw} (non-negative integer)`, 2);
       }
       const limit = Number(raw);
-      const feed: UnboundFeed = buildUnboundFeed(loadSpecEntries(), limit);
+      const feed: UnboundFeed = buildUnboundFeed(loadRootSpecEntries(), limit);
       const mode = resolveOutMode(options.output, options.json, options.compactJson);
       if (mode !== 'human') {
         console.log(renderMachine(feed, mode));

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 = [
@@ -285,6 +352,14 @@ 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 spec check')
     .option('--check', 'run the spec check (default when specs.check_command is configured)');
@@ -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 }),