@llman-sdd/core 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -107,6 +107,16 @@ export {
   type StageGate,
 } from './validation/changeCheck.ts';
 export { discoverSpecs, type DiscoveryIo } from './validation/discover.ts';
+export {
+  discoverRoots,
+  isValidRoot,
+  resolveInstanceRoot,
+  scopeCrossings,
+  ROOT_EXCLUDED_DIRS,
+  type RootEntry,
+  type RootsIo,
+  type ScopeCrossing,
+} from './validation/roots.ts';
 export {
   expandRunCommand,
   runHarnessForSpecs,
@@ -187,6 +197,7 @@ export {
 } from './templates/embedded.ts';
 export {
   TEMPLATES_ROOT,
+  refreshSubRootBlocks,
   runInit,
   updateFileWithMarkers,
   type InitIo,

package/src/init/init.ts

@@ -80,7 +80,7 @@ function writeDefaultConfig(io: InitIo, locale: string): void {
 }
 
 export interface InitResult {
-  /** Skill dirs written, in render order. */
+  /** Skill dirs written, in render order ([] when skills injection is off). */
   skills: string[];
   /** llman-sdd-* directories removed by --update namespace cleanup. */
   removed: string[];
@@ -89,10 +89,31 @@ export interface InitResult {
 
 const SKILLS_BASE = '.agents/skills';
 
+/** Managed AGENTS.md marker blocks (root + llmanspec), content-preserving. */
+function writeManagedBlocks(
+  io: InitIo,
+  templates: TemplateIo,
+  config: ReturnType<typeof loadConfig>,
+  version: string,
+): void {
+  const vars = buildTemplateVars(config, version);
+  const locales = localeFallbacks(config.locale);
+  for (const [stubPath, agentsPath] of [
+    ['agents-root-stub.md', 'AGENTS.md'],
+    ['llmanspec-agents-stub.md', 'llmanspec/AGENTS.md'],
+  ] as const) {
+    const stubRaw = loadLocaleResource(templates, TEMPLATES_ROOT, locales, stubPath);
+    if (stubRaw === null) continue;
+    const existing = io.exists(agentsPath) ? io.readText(agentsPath) : '';
+    const body = renderTemplate(stubRaw, new Map(), vars);
+    io.writeText(agentsPath, updateFileWithMarkers(existing, body));
+  }
+}
+
 export function runInit(
   io: InitIo,
   templates: TemplateIo,
-  opts: { update: boolean; locale?: string; version: string },
+  opts: { update: boolean; locale?: string; version: string; skills: boolean },
 ): InitResult {
   io.mkdirp('llmanspec');
 
@@ -110,26 +131,15 @@ export function runInit(
   }
 
   // 3) AGENTS.md managed blocks (root + llmanspec), preserving content.
+  writeManagedBlocks(io, templates, config, opts.version);
   const vars = buildTemplateVars(config, opts.version);
-  const locales = localeFallbacks(config.locale);
   const skillTemplates = loadSkillTemplates(templates, TEMPLATES_ROOT, config, vars);
   enforceEthicsGovernance(skillTemplates);
 
-  for (const [stubPath, agentsPath] of [
-    ['agents-root-stub.md', 'AGENTS.md'],
-    ['llmanspec-agents-stub.md', 'llmanspec/AGENTS.md'],
-  ] as const) {
-    const stubRaw = loadLocaleResource(templates, TEMPLATES_ROOT, locales, stubPath);
-    if (stubRaw === null) continue;
-    const existing = io.exists(agentsPath) ? io.readText(agentsPath) : '';
-    const body = renderTemplate(stubRaw, new Map(), vars);
-    io.writeText(agentsPath, updateFileWithMarkers(existing, body));
-  }
-
   // 4) skills namespace cleanup (--update only): remove llman-sdd-* dirs
   // outside the candidate set; un-prefixed custom skills stay untouched.
   const removed: string[] = [];
-  if (opts.update && io.exists(SKILLS_BASE)) {
+  if (opts.skills && opts.update && io.exists(SKILLS_BASE)) {
     const candidates = new Set(skillCandidates(config).map((f) => f.replace(/\.md$/u, '')));
     for (const entry of io.listDir(SKILLS_BASE)) {
       if (entry.startsWith('llman-sdd-') && !candidates.has(entry)) {
@@ -140,6 +150,12 @@ export function runInit(
   }
 
   // 5) write candidates: rendered product trimmed + single trailing newline.
+  // Sub-root instances default to no skills injection (r93): the agent skill
+  // surface stays at the repo root and sub-root navigation lives in the
+  // managed blocks; --skills opts a sub-root in.
+  if (!opts.skills) {
+    return { skills: [], removed, configPath };
+  }
   for (const t of skillTemplates) {
     const dirName = t.name.replace(/\.md$/u, '');
     io.mkdirp(`${SKILLS_BASE}/${dirName}`);
@@ -148,3 +164,16 @@ export function runInit(
 
   return { skills: skillTemplates.map((t) => t.name.replace(/\.md$/u, '')), removed, configPath };
 }
+
+/**
+ * r93 --update sweep: refresh the managed blocks of one discovered sub-root
+ * (blocks only — no scaffold, no config touch, no skills). Returns false for
+ * a missing config (discovery guarantees validity; a race is not fatal).
+ */
+export function refreshSubRootBlocks(io: InitIo, templates: TemplateIo, version: string): boolean {
+  const configPath = 'llmanspec/config.yaml';
+  if (!io.exists(configPath)) return false;
+  const config = loadConfig(io.readText(configPath));
+  writeManagedBlocks(io, templates, config, version);
+  return true;
+}

package/src/report/specHelpers.ts

@@ -39,20 +39,19 @@ function collectSpecEntries(io: SpecHelperIo, specsDir: string): ParsedEntry[] {
 }
 
 /**
- * predecessor parity (`req_registry.rs::next_req_id_from_index`): smallest free
- * rN over the requirement handles (`@req` on `规则:` headers) only. The id set
- * comes from the global req registry fed with the parsed specs.
+ * Max+1 over the requirement handles (`@req` on `规则:` headers) only — the id
+ * set comes from the global req registry fed with the parsed specs. Deliberately
+ * divergent from the predecessor's smallest-free semantics
+ * (`req_registry.rs::next_req_id_from_index`): handing out freed ids aliases
+ * references archived in past changes (issue #5) — retired ranges are never
+ * reused. See change `align-next-req-id-max-plus-one` design for the trade-off.
  */
 export function nextReqId(io: SpecHelperIo, specsDir: string): string {
   const entries = collectSpecEntries(io, specsDir);
-  const used = new Set(
-    [...buildReqRegistry(entries).byId.keys()].map((reqId) =>
-      Math.trunc(Number(reqId.replace(/^r/u, ''))),
-    ),
+  const used = [...buildReqRegistry(entries).byId.keys()].map((reqId) =>
+    Math.trunc(Number(reqId.replace(/^r/u, ''))),
   );
-  let n = 1;
-  while (used.has(n)) n += 1;
-  return `r${n}`;
+  return `r${Math.max(0, ...used) + 1}`;
 }
 
 export function skeletonContent(capability: string, reqId: string, locale: string): string {

package/src/validation/roots.ts

@@ -0,0 +1,123 @@
+/**
+ * Instance-root discovery (subproject-llmanspec-discovery, r91-r92): the
+ * unified-root axiom — every llman-sdd operation targets one llmanspec/
+ * directory; the repo root is just the default instance and a workspace
+ * subpackage carrying its own llmanspec/ is another instance of the same
+ * shape. Pure: filesystem access only through the injected IO.
+ */
+
+export interface RootsIo {
+  exists(path: string): boolean;
+  isDirectory(path: string): boolean;
+  listDir(path: string): string[];
+}
+
+export interface RootEntry {
+  /** Directory containing the llmanspec/ instance (the instance root). */
+  rootDir: string;
+  /** The llmanspec directory itself. */
+  llmanspecDir: string;
+}
+
+/** Directory names never descended into during discovery. */
+export const ROOT_EXCLUDED_DIRS: ReadonlySet<string> = new Set(['node_modules', 'target', '.git']);
+
+const joinPath = (dir: string, name: string): string =>
+  dir.endsWith('/') ? `${dir}${name}` : `${dir}/${name}`;
+
+/**
+ * A directory counts as an llmanspec root when it carries `config.yaml` or a
+ * `specs/` subdir — bare `llmanspec/` scaffolds in flight are not instances.
+ */
+export function isValidRoot(llmanspecDir: string, io: RootsIo): boolean {
+  if (!io.isDirectory(llmanspecDir)) return false;
+  return io.exists(`${llmanspecDir}/config.yaml`) || io.isDirectory(`${llmanspecDir}/specs`);
+}
+
+/**
+ * Discover instance roots under `startDir` (convention scan). The start dir
+ * itself is checked first (depth 0 — the git-root instance), then subdirs
+ * depth-first in stable sort order; `llmanspec/` contents are never descended
+ * into and excluded names are pruned. `maxDepth` mirrors the global
+ * --max-scan-depth knob (default 8).
+ */
+export function discoverRoots(
+  startDir: string,
+  io: RootsIo,
+  opts: { maxDepth?: number } = {},
+): RootEntry[] {
+  const maxDepth = opts.maxDepth ?? 8;
+  const roots: RootEntry[] = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    const llmanspecDir = joinPath(dir, 'llmanspec');
+    if (isValidRoot(llmanspecDir, io)) roots.push({ rootDir: dir, llmanspecDir });
+    let names: string[];
+    try {
+      names = io.listDir(dir);
+    } catch {
+      return;
+    }
+    for (const name of names.toSorted()) {
+      if (name.startsWith('.') || ROOT_EXCLUDED_DIRS.has(name)) continue;
+      const full = joinPath(dir, name);
+      if (!io.isDirectory(full)) continue;
+      if (name === 'llmanspec') continue;
+      walk(full, depth + 1);
+    }
+  };
+  walk(startDir, 0);
+  return roots;
+}
+
+export interface ScopeCrossing {
+  scope: string;
+  rootDir: string;
+}
+
+/**
+ * Single-ownership rule (r92): a file path belongs to exactly one llmanspec
+ * root. Scope entries are resolved against the owning instance root; a scope
+ * that reaches into another root's instance directory crosses the boundary
+ * and is reported with the offending scope and the other root. Ancestor roots
+ * are exempt: a sub-root scoping its own subtree always resolves under the
+ * ancestor's directory, but ownership there belongs to the descendant.
+ */
+export function scopeCrossings(
+  scopePaths: readonly string[],
+  instanceRootDir: string,
+  otherRoots: readonly RootEntry[],
+): ScopeCrossing[] {
+  const crossings: ScopeCrossing[] = [];
+  for (const raw of scopePaths) {
+    const scope = raw.trim().replace(/^\.\//u, '').replace(/\/+$/u, '');
+    if (scope === '') continue;
+    const abs = joinPath(instanceRootDir, scope);
+    for (const other of otherRoots) {
+      if (other.rootDir === instanceRootDir) continue;
+      // Ancestor exemption: our own subtree necessarily sits inside the
+      // ancestor's directory — the ancestor does not own it.
+      if (instanceRootDir.startsWith(`${other.rootDir}/`)) continue;
+      if (abs === other.rootDir || abs.startsWith(`${other.rootDir}/`)) {
+        crossings.push({ scope: raw.trim(), rootDir: other.rootDir });
+        break;
+      }
+    }
+  }
+  return crossings;
+}
+
+/**
+ * Nearest instance root at or above `startDir` (inclusive) — the cwd
+ * resolution behind "cd into the subpackage and run" (r94). Returns null when
+ * no ancestor carries a valid llmanspec root.
+ */
+export function resolveInstanceRoot(startDir: string, io: RootsIo): string | null {
+  let dir = startDir;
+  for (;;) {
+    if (isValidRoot(joinPath(dir, 'llmanspec'), io)) return dir;
+    const parent = dir.replace(/\/+$/u, '').replace(/\/[^/]+$/u, '');
+    if (parent === '' || parent === dir) return null;
+    dir = parent;
+  }
+}