@llman-sdd/core 0.3.1 → 0.5.0

package/src/report/graph.ts

@@ -1,387 +1,15 @@
 /**
  * Change dependency graph (peripheral-commands capability, r21/r30/r54):
- * v1 `commands/graph.rs` observable contract — scope parsing, connected
+ * predecessor `commands/graph.rs` observable contract — scope parsing, connected
  * component subgraphs, conditional classDef, empty placeholder, bidirectional
  * seed BFS, error paths. Pure: IO injected.
+ *
+ * Implementation split under `graph/` (pure mechanical move, no behavior
+ * change); this file stays the public barrel.
  */
 
-import { CHANGES_DIR } from '../change/lifecycle.ts';
-
-export interface GraphFsIo {
-  exists(path: string): boolean;
-  readText(path: string): string;
-  listDir(path: string): string[];
-  isDirectory(path: string): boolean;
-}
-
-interface GraphNode {
-  id: string;
-  archived: boolean;
-  /** true = directory on disk; false = phantom (frozen/removed dependency). */
-  present: boolean;
-}
-
-interface DepEdge {
-  from: string;
-  to: string;
-}
-
-export class GraphError extends Error {}
-
-function extractArchivedId(name: string): string | null {
-  const m = name.match(/^\d{4}-\d{2}-\d{2}-(.+)$/u);
-  return m ? (m[1] ?? null) : null;
-}
-
-/** Extract depends_on entries (flow + block styles, r30). */
-export function parseDeps(proposal: string): string[] {
-  const fm = proposal.match(/^---\n([\s\S]*?)\n---/u);
-  const deps: string[] = [];
-  if (!fm?.[1]) return deps;
-  let inDeps = false;
-  for (const line of fm[1].split('\n')) {
-    const flow = line.match(/^depends_on:\s*\[([^\]]*)\]\s*$/u);
-    if (flow) {
-      for (const item of flow[1]?.split(',') ?? []) {
-        const dep = item.trim().replaceAll(/^['"]|['"]$/gu, '');
-        if (dep !== '' && !/^[0-9]+$/u.test(dep)) deps.push(dep);
-      }
-      inDeps = false;
-      continue;
-    }
-    if (/^depends_on:\s*$/u.test(line)) {
-      inDeps = true;
-      continue;
-    }
-    if (inDeps) {
-      const m = line.match(/^\s*-\s+(\S+)/u);
-      if (m?.[1] && !/^[0-9]+$/u.test(m[1])) deps.push(m[1]);
-      else if (line.trim() !== '') inDeps = false;
-    }
-  }
-  return deps;
-}
-
-type ScopeKind = 'active' | 'archived';
-
-function parseScope(scope: string): ScopeKind[] {
-  if (scope === 'all') return ['active', 'archived'];
-  const kinds: ScopeKind[] = [];
-  for (const part of scope.split(',')) {
-    const t = part.trim();
-    if (t === 'active') kinds.push('active');
-    else if (t === 'archived') kinds.push('archived');
-    else {
-      throw new GraphError(
-        `Unknown scope: '${flagClean(t)}'. Supported: active, archived, all (or comma-separated like active,archived)`,
-      );
-    }
-  }
-  if (kinds.length === 0) throw new GraphError('Scope cannot be empty');
-  return kinds;
-}
-
-function flagClean(v: string): string {
-  return v;
-}
-
-/** Active nodes: dirs (recursively) with a proposal.md (v1 discovery). */
-function collectActiveNodes(io: GraphFsIo, root: string): GraphNode[] {
-  const out: GraphNode[] = [];
-  const changesDir = `${root}/${CHANGES_DIR}`;
-  if (!io.exists(changesDir) || !io.isDirectory(changesDir)) return out;
-  const visit = (dir: string): void => {
-    for (const name of io.listDir(dir).toSorted()) {
-      if (name === 'archive' || name.startsWith('.')) continue;
-      const child = `${dir}/${name}`;
-      if (!io.isDirectory(child)) continue;
-      if (io.exists(`${child}/proposal.md`)) {
-        out.push({ id: name, archived: false, present: true });
-      } else {
-        visit(child);
-      }
-    }
-  };
-  visit(changesDir);
-  return out;
-}
-
-function collectArchivedNodes(io: GraphFsIo, root: string): GraphNode[] {
-  const archiveDir = `${root}/${CHANGES_DIR}/archive`;
-  if (!io.exists(archiveDir) || !io.isDirectory(archiveDir)) return [];
-  const out: GraphNode[] = [];
-  const seen = new Set<string>();
-  for (const name of io.listDir(archiveDir)) {
-    const child = `${archiveDir}/${name}`;
-    if (!io.isDirectory(child)) continue;
-    const id = extractArchivedId(name);
-    if (id !== null && !seen.has(id)) {
-      seen.add(id);
-      out.push({ id, archived: true, present: true });
-    }
-  }
-  return out;
-}
-
-function collectNodes(io: GraphFsIo, root: string, kinds: ScopeKind[]): GraphNode[] {
-  const combined: GraphNode[] = [];
-  const seen = new Set<string>();
-  for (const kind of kinds) {
-    const nodes = kind === 'active' ? collectActiveNodes(io, root) : collectArchivedNodes(io, root);
-    for (const node of nodes) {
-      if (!seen.has(node.id)) {
-        seen.add(node.id);
-        combined.push(node);
-      }
-    }
-  }
-  return combined;
-}
-
-function proposalFor(io: GraphFsIo, root: string, node: GraphNode): string {
-  if (node.archived) {
-    const archiveDir = `${root}/${CHANGES_DIR}/archive`;
-    // latest matching dirtategy: pick the newest date-prefixed dir
-    let best = '';
-    let bestDate = '';
-    for (const name of io.listDir(archiveDir)) {
-      const id = extractArchivedId(name);
-      if (id !== node.id) continue;
-      const date = name.slice(0, 10);
-      if (best === '' || date > bestDate) {
-        best = name;
-        bestDate = date;
-      }
-    }
-    const p = `${archiveDir}/${best}/proposal.md`;
-    return io.exists(p) ? io.readText(p) : '';
-  }
-  const changesDir = `${root}/${CHANGES_DIR}`;
-  const found: string[] = [];
-  const visit = (dir: string): void => {
-    for (const name of io.listDir(dir).toSorted()) {
-      if (name === 'archive' || name.startsWith('.')) continue;
-      const child = `${dir}/${name}`;
-      if (!io.isDirectory(child)) continue;
-      if (io.exists(`${child}/proposal.md`)) {
-        if (name === node.id) found.push(`${child}/proposal.md`);
-        continue;
-        // ^ leaf change dir — do not descend further
-      }
-      visit(child);
-    }
-  };
-  visit(changesDir);
-  if (found.length === 0) return '';
-  return io.readText(found[0] ?? '');
-}
-
-interface RelationMaps {
-  depends: Map<string, string[]>;
-  reverse: Map<string, string[]>;
-  nodeSet: Set<string>;
-}
-
-function buildMaps(io: GraphFsIo, root: string, nodes: GraphNode[]): RelationMaps {
-  const depends = new Map<string, string[]>();
-  const reverse = new Map<string, string[]>();
-  const nodeSet = new Set<string>();
-  for (const node of nodes) {
-    nodeSet.add(node.id);
-    if (!node.present) continue;
-    for (const dep of parseDeps(proposalFor(io, root, node))) {
-      depends.set(node.id, [...(depends.get(node.id) ?? []), dep]);
-      reverse.set(dep, [...(reverse.get(dep) ?? []), node.id]);
-    }
-  }
-  return { depends, reverse, nodeSet };
-}
-
-function buildDefaultNodes(io: GraphFsIo, root: string, kinds: ScopeKind[]): GraphNode[] {
-  const nodes = collectNodes(io, root, kinds);
-  const nodeIds = new Set(nodes.map((n) => n.id));
-  const all = collectNodes(io, root, ['active', 'archived']);
-  const allMap = new Map(all.map((n) => [n.id, n]));
-
-  const missing: string[] = [];
-  for (const node of all) {
-    if (!nodeIds.has(node.id) || !node.present) continue;
-    for (const dep of parseDeps(proposalFor(io, root, node))) {
-      if (!nodeIds.has(dep)) missing.push(dep);
-    }
-  }
-  const seenMissing = new Set<string>();
-  for (const dep of missing) {
-    if (seenMissing.has(dep)) continue;
-    seenMissing.add(dep);
-    const existing = allMap.get(dep);
-    if (existing !== undefined) nodes.push(existing);
-    else nodes.push({ id: dep, archived: false, present: false });
-  }
-  return nodes;
-}
-
-function collectEdges(io: GraphFsIo, root: string, nodes: GraphNode[]): DepEdge[] {
-  const nodeIds = new Set(nodes.map((n) => n.id));
-  const edges: DepEdge[] = [];
-  for (const node of nodes) {
-    if (!node.present) continue;
-    for (const dep of parseDeps(proposalFor(io, root, node))) {
-      if (nodeIds.has(dep)) edges.push({ from: node.id, to: dep });
-    }
-  }
-  return edges;
-}
-
-function connectedComponents(nodeIds: string[], edges: DepEdge[]): string[][] {
-  if (nodeIds.length === 0) return [];
-  const parent = new Map<string, string>(nodeIds.map((id) => [id, id]));
-  const find = (x: string): string => {
-    let root = parent.get(x) ?? x;
-    while (parent.get(root) !== root) root = parent.get(root) ?? root;
-    return root;
-  };
-  const union = (a: string, b: string): void => {
-    const ra = find(a);
-    const rb = find(b);
-    if (ra !== rb) parent.set(ra, rb);
-  };
-  for (const edge of edges) union(edge.from, edge.to);
-  const groups = new Map<string, string[]>();
-  for (const id of nodeIds) {
-    const root = find(id);
-    groups.set(root, [...(groups.get(root) ?? []), id]);
-  }
-  return [...groups.values()].toSorted((a, b) => b.length - a.length);
-}
-
-function componentLabel(nodes: GraphNode[], ids: Set<string>): string {
-  const comp = nodes.filter((n) => ids.has(n.id));
-  const allActive = comp.every((n) => !n.archived && n.present);
-  const allArchived = comp.every((n) => n.archived);
-  if (allActive) return 'Active';
-  if (allArchived) return 'Done';
-  return 'Mixed';
-}
-
-const sanitize = (id: string): string => id.replaceAll('-', '_');
-
-export interface GraphOptions {
-  scope?: string;
-  depth?: number;
-  seed?: string;
-}
-
-export function graphMermaid(io: GraphFsIo, root: string, opts: GraphOptions = {}): string[] {
-  const scope = opts.scope ?? 'active';
-  const kinds = parseScope(scope);
-
-  let nodes: GraphNode[];
-  if (opts.seed !== undefined) {
-    nodes = buildSeedNeighborhood(io, root, opts.seed, opts.depth ?? 1, kinds);
-  } else {
-    nodes = buildDefaultNodes(io, root, kinds);
-  }
-
-  if (nodes.length === 0) {
-    return [
-      'flowchart TD',
-      opts.seed !== undefined
-        ? `    empty["Change '${opts.seed}' not found or has no relationships"]`
-        : `    empty["No changes in scope '${scope}'"]`,
-    ];
-  }
-
-  const edges = collectEdges(io, root, nodes);
-  const nodeIds = nodes.map((n) => n.id);
-  const components = connectedComponents(nodeIds, edges);
-  const hasArchived = nodes.some((n) => n.archived);
-  const hasMissing = nodes.some((n) => !n.present);
-
-  const lines = ['flowchart TD'];
-  if (components.length > 1) {
-    components.forEach((comp, idx) => {
-      const ids = new Set(comp);
-      const label = componentLabel(nodes, ids);
-      lines.push(`    subgraph sg${idx + 1}["${label}"]`);
-      renderNodesAndEdges(nodes, edges, ids, lines, true);
-      lines.push('    end');
-    });
-  } else {
-    renderNodesAndEdges(nodes, edges, new Set(nodeIds), lines, false);
-  }
-  if (hasArchived) lines.push('    classDef archived fill:#d4edda,stroke:#28a745,color:#333');
-  if (hasMissing) lines.push('    classDef missing fill:#f8d7da,stroke:#dc3545,color:#333');
-  return lines;
-}
-
-function renderNodesAndEdges(
-  nodes: GraphNode[],
-  edges: DepEdge[],
-  ids: Set<string>,
-  lines: string[],
-  indented: boolean,
-): void {
-  const pad = indented ? '        ' : '    ';
-  for (const node of nodes) {
-    if (!ids.has(node.id)) continue;
-    if (!node.present) lines.push(`${pad}${sanitize(node.id)}["${node.id} ⚠ missing"]:::missing`);
-    else if (node.archived)
-      lines.push(`${pad}${sanitize(node.id)}["${node.id} ✓ done"]:::archived`);
-    else lines.push(`${pad}${sanitize(node.id)}["${node.id}"]`);
-  }
-  for (const edge of edges) {
-    if (!ids.has(edge.from)) continue;
-    lines.push(`${pad}${sanitize(edge.from)} -->|depends on| ${sanitize(edge.to)}`);
-  }
-}
-
-/** Seed neighborhood: bidirectional BFS (depends_on + reverse) over both sets. */
-function buildSeedNeighborhood(
-  io: GraphFsIo,
-  root: string,
-  seedId: string,
-  maxDepth: number,
-  _kinds: ScopeKind[],
-): GraphNode[] {
-  const resolved = resolveSeedId(io, root, seedId);
-  const allNodes = collectNodes(io, root, ['active', 'archived']);
-  const nodeMap = new Map(allNodes.map((n) => [n.id, n]));
-  if (!nodeMap.has(resolved)) {
-    const prefix = resolved.split('-')[0] ?? '';
-    const suggestions = [...nodeMap.keys()].filter((k) => k.startsWith(prefix));
-    const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : '';
-    throw new GraphError(`change '${seedId}' not found.${hint}`);
-  }
-  const maps = buildMaps(io, root, allNodes);
-  const visited = new Set<string>([resolved]);
-  const queue: [string, number][] = [[resolved, 0]];
-  while (queue.length > 0) {
-    const [current, depth] = queue.shift() as [string, number];
-    if (depth >= maxDepth) continue;
-    const neighbors = [...(maps.depends.get(current) ?? []), ...(maps.reverse.get(current) ?? [])];
-    for (const neighbor of neighbors) {
-      if (maps.nodeSet.has(neighbor) && !visited.has(neighbor)) {
-        visited.add(neighbor);
-        queue.push([neighbor, depth + 1]);
-      }
-    }
-  }
-  const result = [...visited]
-    .filter((id) => nodeMap.has(id))
-    .map((id) => nodeMap.get(id) as GraphNode);
-  result.sort((a, b) => a.id.localeCompare(b.id));
-  return result;
-}
-
-function resolveSeedId(io: GraphFsIo, root: string, seedId: string): string {
-  const active = collectActiveNodes(io, root);
-  const archived = collectArchivedNodes(io, root);
-  const all = [...active.map((n) => n.id), ...archived.map((n) => n.id)];
-  if (all.includes(seedId)) return seedId;
-  const viaPrefix = all.filter((id) => id.startsWith(seedId));
-  if (viaPrefix.length === 1) return viaPrefix[0] ?? seedId;
-  const viaArchivedPrefix = archived.map((n) => n.id).filter((id) => id.startsWith(seedId));
-  if (viaArchivedPrefix.length === 1) return viaArchivedPrefix[0] ?? seedId;
-  return seedId;
-}
+export { GraphError, type GraphFsIo } from './graph/types.ts';
+export type { GraphOptions, GraphNodeIr, GraphEdgeIr, GraphDataIr } from './graph/types.ts';
+export { parseDeps } from './graph/deps.ts';
+export { graphData } from './graph/graphData.ts';
+export { graphMermaid } from './graph/render.ts';

package/src/report/show.ts

@@ -1,16 +1,21 @@
-import { readBinding } from '../change/frontmatter.ts';
+import { countTasks, firstH1, stageFor, type ChangeFsIo } from '../change/collect.ts';
+import {
+  extractFrontmatter,
+  readBinding,
+  readNeedsSpecsChange,
+  specsLanded as specsLandedOf,
+} from '../change/frontmatter.ts';
 import { CHANGES_DIR } from '../change/lifecycle.ts';
 import { currentBranch, isCleanTree, type GitLike } from '../git/spawnGit.ts';
 import { discoverSpecs } from '../validation/discover.ts';
 /**
- * show change JSON (peripheral-commands capability, r21): v1 field set and
+ * show change JSON (peripheral-commands capability, r21): predecessor field set and
  * gate structure (clean-tree / on-bound-branch / stage-complete /
- * specs-landed / tasks-done / validate). Object keys are inserted in v1's
+ * specs-landed / tasks-done / validate). Object keys are inserted in predecessor's
  * order; consumers compare structurally. Effects flow through the injected
  * FsIo and GitLike ports — this module stays pure.
  */
 import { validateAllSpecs } from '../validation/validate.ts';
-import { countTasks, firstH1, stageFor, type ChangeFsIo } from './collect.ts';
 
 export type ShowFsIo = ChangeFsIo;
 
@@ -45,7 +50,7 @@ export function showChangeJson(
     ? countTasks(io.readText(`${dir}/tasks.md`))
     : { completed: 0, total: 0 };
 
-  // v1 parity: show works (gracefully degraded gates) outside a git repo.
+  // predecessor parity: show works (gracefully degraded gates) outside a git repo.
   let cleanTree = false;
   let current = null;
   try {
@@ -57,16 +62,11 @@ export function showChangeJson(
   const onBoundBranch = binding !== null && current === binding.branch;
 
   // specs landing: bound changes must have touched llmanspec/specs/ since base
-  let specsLanded = false;
+  let landedOnBranch = false;
   if (binding !== null) {
-    const touched =
-      git.runOpt(['diff', '--name-only', `${binding.baseBranch}...${binding.branch}`]) ?? '';
-    specsLanded = touched.includes('llmanspec/specs/');
+    landedOnBranch = specsLandedOf(git, binding);
   }
-  // needs_specs_change is an explicit frontmatter declaration (default true)
-  const fmMatch = proposal.match(/^---\n([\s\S]*?)\n---/u);
-  const declaredNeeds = fmMatch?.[1]?.match(/^needs_specs_change:\s*(true|false)\s*$/mu)?.[1];
-  const needsSpecsChange = declaredNeeds !== undefined ? declaredNeeds === 'true' : true;
+  const needsSpecsChange = readNeedsSpecsChange(extractFrontmatter(proposal));
 
   const tasksDone = total > 0 && completed >= total;
   const specReport = validateAllSpecs(discoverSpecs(deps.specsDir, io), io);
@@ -77,7 +77,7 @@ export function showChangeJson(
     : !hasTasks
       ? 'add tasks.md (current: designed → planned)'
       : stage === 'planned'
-        ? 'bind via `llman sdd change start <id>` (planned → full)'
+        ? 'bind via `llman-sdd change start <id>` (planned → full)'
         : '';
   const tasksHint =
     total > 0 && completed < total
@@ -93,7 +93,7 @@ export function showChangeJson(
     {
       name: 'on-bound-branch',
       pass: onBoundBranch,
-      hint: onBoundBranch ? '' : 'change is not attached; run `llman sdd change start <id>`',
+      hint: onBoundBranch ? '' : 'change is not attached; run `llman-sdd change start <id>`',
     },
     {
       name: 'stage-complete',
@@ -102,11 +102,11 @@ export function showChangeJson(
     },
     {
       name: 'specs-landed',
-      pass: specsLanded || !needsSpecsChange,
+      pass: landedOnBranch || !needsSpecsChange,
       hint:
-        specsLanded || !needsSpecsChange
+        landedOnBranch || !needsSpecsChange
           ? ''
-          : 'edit live specs on the bound branch and commit (or needs_specs_change: false)',
+          : 'edit live specs on the bound branch and commit (or set needs_specs_change to false)',
     },
     {
       name: 'tasks-done',
@@ -116,7 +116,7 @@ export function showChangeJson(
     {
       name: 'validate',
       pass: validateOk,
-      hint: validateOk ? '' : 'fix issues reported by `llman sdd validate <id> --strict`',
+      hint: validateOk ? '' : 'fix issues reported by `llman-sdd validate <id> --strict`',
     },
   ];
 
@@ -127,11 +127,9 @@ export function showChangeJson(
     stage,
     artifacts,
     readyToImplement: gateChecks.every((g) => g.pass),
-    specsLanded,
+    specsLanded: landedOnBranch,
     needsSpecsChange,
     attached: binding !== null,
-    deltaCount: 0,
-    deltas: [] as string[],
     gateChecks,
     matchedViaPrefix: opts.matchedViaPrefix === true,
   };

package/src/report/specHelpers.ts

@@ -1,4 +1,5 @@
-import { parseCapability } from '../spec/parser.ts';
+import { localeToGherkinLang, parseCapability } from '../spec/parser.ts';
+import { buildReqRegistry } from '../spec/reqRegistry.ts';
 /**
  * Spec authoring helpers (peripheral-commands capability, r22):
  * skeleton generation + global next req id. Pure, IO injected.
@@ -14,31 +15,40 @@ export interface SpecHelperIo {
   listDir(path: string): string[];
 }
 
-/**
- * v1 parity (`req_registry.rs::next_req_id_from_index`): smallest free rN over
- * the RULE (@human) req ids only; acceptance-only req tags do not occupy ids.
- */
-export function nextReqId(io: SpecHelperIo, specsDir: string): string {
-  const used = new Set<number>();
+interface ParsedEntry {
+  fileName: string;
+  doc: ReturnType<typeof parseCapability>;
+}
+
+function collectSpecEntries(io: SpecHelperIo, specsDir: string): ParsedEntry[] {
+  const entries: ParsedEntry[] = [];
   const walk = (dir: string): void => {
     if (!io.exists(dir)) return;
     for (const name of io.listDir(dir)) {
       const full = `${dir}/${name}`;
       if (name.endsWith('.feature')) {
-        const doc = parseCapability(io.readText(full), full);
-        for (const scenario of doc.scenarios) {
-          if (scenario.classification !== 'human') continue;
-          for (const reqId of scenario.reqIds) {
-            const n = Math.trunc(Number(reqId.replace(/^r/u, '')));
-            if (Number.isFinite(n)) used.add(n);
-          }
-        }
+        entries.push({ fileName: full, doc: parseCapability(io.readText(full), full) });
       } else if (io.isDirectory(full)) {
         walk(full);
       }
     }
   };
   walk(specsDir);
+  return entries;
+}
+
+/**
+ * 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.
+ */
+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, ''))),
+    ),
+  );
   let n = 1;
   while (used.has(n)) n += 1;
   return `r${n}`;
@@ -46,15 +56,27 @@ export function nextReqId(io: SpecHelperIo, specsDir: string): string {
 
 export function skeletonContent(capability: string, reqId: string, locale: string): string {
   const zh = localeFallbacks(locale)[0] === 'zh-Hans';
+  // r7: the `# language:` header derives from the locale mapping — never a
+  // second hardcoded caliber.
+  const language = localeToGherkinLang(zh ? 'zh-Hans' : 'en');
   const header = zh
-    ? `# language: zh-CN\n# capability: ${capability}\n# purpose: TODO: 一句话描述该能力与其目的。\n# scope: src/`
-    : `# language: en\n# capability: ${capability}\n# purpose: TODO: Describe this capability and its purpose.\n# scope: src/`;
+    ? `# language: ${language}\n# capability: ${capability}\n# purpose: TODO: 一句话描述该能力与其目的。\n# scope: llmanspec/`
+    : `# language: ${language}\n# capability: ${capability}\n# purpose: TODO: Describe this capability and its purpose.\n# scope: llmanspec/`;
   const feature = zh ? `功能: ${capability}` : `Feature: ${capability}`;
-  const scenario = zh ? '场景: TODO-rule' : 'Scenario: TODO-rule';
-  return `${header}\n\n${feature}\n\n  @req:${reqId} @human\n  ${scenario}\n    System MUST ...\n`;
+  const ruleKw = zh ? '规则' : 'Rule';
+  const scenarioKw = zh ? '场景' : 'Scenario';
+  const ruleTitle = 'TODO-rule';
+  const ruleDesc = zh ? 'TODO: 需求描述(自由文本)。' : 'TODO: requirement statement (free text).';
+  const scTitle = 'TODO-acceptance';
+  // native v2 skeleton: a `规则:` block (with @req handle) + one nested example
+  return (
+    `${header}\n\n${feature}\n\n  @req:${reqId}\n  ${ruleKw}: ${ruleTitle}\n` +
+    `    ${ruleDesc}\n\n    ${scenarioKw}: ${scTitle}\n` +
+    `      假如 TODO 前置\n      当 TODO 动作\n      那么 TODO 断言\n`
+  );
 }
 
-/** `spec skeleton <cap>`: write llmanspec/specs/<cap>.feature + scaffold scope dir. */
+/** `spec skeleton <cap>`: write llmanspec/specs/<cap>.feature (no repo-root src/). */
 export function scaffoldSpec(
   io: SpecHelperIo,
   specsDir: string,
@@ -65,7 +87,6 @@ export function scaffoldSpec(
   const reqId = nextReqId(io, specsDir);
   const path = `${specsDir}/${capability}.feature`;
   if (!opts.force && io.exists(path)) throw new Error(`spec already exists: ${path}`);
-  io.mkdirp('src/');
   io.writeText(path, skeletonContent(capability, reqId, locale));
   return path;
 }