@llman-sdd/cli 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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.1",
     "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/archive.ts

@@ -14,6 +14,7 @@ import type { Command } from 'commander';
 
 import { CliError } from '../cli-shared.ts';
 import { makeCliGit, makeIo } from '../io.ts';
+import { progressNote } from '../progress.ts';
 
 /**
  * r24: warn (never block) when freeze/thaw runs outside the main checkout —
@@ -69,6 +70,8 @@ export function registerArchive(program: Command): void {
             for (const line of await runList(io, sz, root)) console.log(line);
             return;
           }
+          // 7z 压缩可能耗时 — 进度提示防止看上去卡住(B1);dry-run/list 不走压缩
+          if (!options.dryRun) progressNote('freeze.pack', root);
           const result = await runFreeze(io, sz, root, {
             before: options.before,
             keepRecent: Number(options.keepRecent),
@@ -105,6 +108,8 @@ export function registerArchive(program: Command): void {
       const sz = await makeEmbeddedSevenZip();
       const io = makeIo(root);
       try {
+        // 7z 解包可能耗时 — 进度提示防止看上去卡住(B1)
+        progressNote('thaw.unpack', root);
         const result = await runThaw(io, sz, root, options.change, { dest: options.dest });
         for (const line of result.lines) console.log(line);
       } catch (error) {

package/src/commands/change.ts

@@ -1,5 +1,5 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 
 import {
   CLOSE_OUT_TASK_HINT,
@@ -291,9 +291,9 @@ export function registerChange(program: Command): void {
           skipCleanTree: true,
           today: new Date().toISOString().slice(0, 10),
         });
-        const archiveName = (result.archiveDir ?? '').slice(
-          (result.archiveDir ?? '').lastIndexOf('/') + 1,
-        );
+        // node:path.basename — platform-aware (win32 backslashes would defeat
+        // a hand-rolled lastIndexOf('/')).
+        const archiveName = basename(result.archiveDir ?? '');
         console.log(`Change '${id}' archived as '${archiveName}'.`);
         if (result.executedIn !== null) {
           console.log(`executed in target worktree ${result.executedIn}`);

package/src/commands/context.ts

@@ -9,6 +9,7 @@ import {
 import type { Command } from 'commander';
 
 import { CliError, loadSpecEntries, newIo, resolveBackend } from '../cli-shared.ts';
+import { progressNote } from '../progress.ts';
 
 // (err path below converted to CliError; resolveBackend may also throw CliError)
 
@@ -45,6 +46,8 @@ export function registerContext(program: Command): void {
         console.log(JSON.stringify(unavailableResult(), null, 2));
         return;
       }
+      // LLM 链路可能是秒级 — 进度提示防止看上去卡住(B1)
+      progressNote('context.retrieve', process.cwd());
       const result = await runContextRetrieval({
         config,
         task: options.task ?? '',

package/src/commands/init.ts

@@ -1,11 +1,22 @@
 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';
+import { progressNote } from '../progress.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 +24,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 +43,30 @@ export function registerInit(program: Command): void {
           root = resolve(path);
           mkdirSync(root, { recursive: true });
         }
+        const repoRootInstance = isRepoRootInstance(root);
+        // 模板生成/子根扫块可能耗时 — 进度提示防止看上去卡住(B1)
+        progressNote('init.generate', 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 = [
@@ -252,24 +319,28 @@ function warnDirtySpecsOnDefaultBranch(): void {
 let harnessBannerShown = false;
 
 /**
- * r13/r48 trigger state: the nested guard env and the check flags are read
+ * r13/r48 trigger state: the nested guard env and the check flag are read
  * here (CLI boundary) and injected into core as parameters — core harness
- * logic never touches process.env. Commander tri-state (both flags declared):
- * --check → check=true, --no-check → check=false, absent → undefined.
+ * logic never touches process.env. Commander binary state:
+ * --check → check=true, absent → undefined.
  */
 function makeHarnessGate(options: { check?: boolean }): HarnessGate {
   const runCommand = loadCliConfig()?.specs?.check_command ?? null;
   const configured = runCommand !== null && runCommand !== '';
   return {
     nested: process.env.LLMAN_SDD_HARNESS_ACTIVE === '1',
-    check: options.check === false ? 'off' : options.check === true ? 'on' : 'default',
+    // Opt-in harness (2026-10 decision): absent → 'off' — structure/state gate
+    // only; --check → 'on' (explicit full harness). The CLI never sends
+    // 'default'; core still treats a received 'default' as
+    // run-if-configured (its own contract).
+    check: options.check === true ? 'on' : 'off',
     runner: configured ? makeCliHarnessRunner() : undefined,
     runCommand,
     cwd: process.cwd(),
     onBeforeFirstRun: (expanded: string): void => {
       if (harnessBannerShown) return;
       harnessBannerShown = true;
-      console.error(`running spec check: ${expanded} (use --no-check to skip)`);
+      console.error(`running spec check: ${expanded} (explicit --check harness run)`);
     },
   };
 }
@@ -285,9 +356,16 @@ 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)');
+    .option('--check', 'run the spec check (full harness) explicitly — opt-in, default skips');
   addReportOutputOptions(validate);
   validate.action(
     (
@@ -304,6 +382,8 @@ export function registerValidate(program: Command): void {
         includeInfo?: boolean;
         output?: string;
         check?: boolean;
+        directory?: string;
+        allRoots?: boolean;
       },
     ) => {
       if (!assertCompactJsonPairing(options)) return;
@@ -323,6 +403,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 +483,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 +580,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/io.ts

@@ -14,10 +14,20 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 
 import { makeSpawnGit, type GitLike } from '@llman-sdd/core';
 
+/**
+ * Platform-aware parent directory (node:path.dirname, never hand-rolled
+ * '/' slicing): on win32, join() yields backslashes and a lastIndexOf('/')
+ * fallback would resolve to '.', so mkdir of a nested new dir would fail with
+ * ENOENT. Exported for unit-test guards (A2 platform compat).
+ */
+export function parentOf(p: string): string {
+  return dirname(p);
+}
+
 export interface CliIo {
   exists(path: string): boolean;
   readText(path: string): string;
@@ -37,7 +47,6 @@ export interface CliIo {
 
 export function makeIo(root: string): CliIo {
   const full = (p: string): string => (isAbsolute(p) ? p : join(root, p));
-  const parentOf = (p: string): string => p.slice(0, p.lastIndexOf('/')) || '.';
   return {
     exists: (p) => existsSync(full(p)),
     readText: (p) => readFileSync(full(p), 'utf8'),

package/src/progress.ts

@@ -0,0 +1,59 @@
+/**
+ * Localized stage-progress notes (B1): genuinely long-running operations print
+ * a short one-line stderr note in the project locale (zh → zh-Hans text,
+ * everything else English) so neither humans nor agents mistake progress for a
+ * hang. Progress ALWAYS goes to stderr (capture contract: results on stdout,
+ * progress on stderr); each key fires at most once per process; notes are only
+ * emitted before the long op itself, never ahead of domain errors.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+type Locale = 'zh' | 'en';
+
+const NOTES: Record<string, Record<Locale, string>> = {
+  'context.retrieve': {
+    zh: '正在检索 specs 上下文(LLM)...',
+    en: 'Retrieving spec context (LLM)...',
+  },
+  'init.generate': {
+    zh: '正在初始化 llmanspec/ 与 skills...',
+    en: 'Initializing llmanspec/ and skills...',
+  },
+  'freeze.pack': {
+    zh: '正在压缩冻结归档(7z)...',
+    en: 'Packing freeze archive (7z)...',
+  },
+  'thaw.unpack': {
+    zh: '正在解包冻结归档(7z)...',
+    en: 'Unpacking freeze archive (7z)...',
+  },
+};
+
+/** Resolve the note text for a locale (pure; exported for unit tests). */
+export function resolveNote(key: string, locale: Locale): string | undefined {
+  return NOTES[key]?.[locale];
+}
+
+/** Detect the project locale from llmanspec/config.yaml (zh-* → zh, else en). */
+export function detectLocale(cwd: string): Locale {
+  try {
+    const cfg = readFileSync(join(cwd, 'llmanspec', 'config.yaml'), 'utf8');
+    const m = cfg.match(/^locale:\s*([A-Za-z-]+)/mu);
+    if (m?.[1]?.startsWith('zh') ?? false) return 'zh';
+  } catch {
+    // No config at cwd — English fallback.
+  }
+  return 'en';
+}
+
+const shown = new Set<string>();
+
+/** Print a localized progress note to stderr once per key per process. */
+export function progressNote(key: string, cwd: string = process.cwd()): void {
+  if (shown.has(key)) return;
+  const text = resolveNote(key, detectLocale(cwd));
+  if (text === undefined) return;
+  shown.add(key);
+  process.stderr.write(`${text}\n`);
+}