@llman-sdd/core 0.6.0 → 0.7.1

package/package.json

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

package/src/archive/freeze.ts

@@ -147,6 +147,8 @@ export async function runList(io: FreezeIo, sz: SevenZipPort, rootAbs: string):
   if (io.exists(archiveAbs)) {
     // Legacy/unexpected entries present only inside the 7z (no card on disk).
     const entries = (await sz.listEntries(archiveAbs)).map((n) => n.replace(/\/$/u, ''));
+    // 7z entry names always use '/' per archive contract — POSIX by contract, not
+    // platform-native; do not switch to node:path here.
     const top = (n: string): string => n.split('/')[0] ?? n;
     for (const e of entries.map(top).filter((n) => DATED_RE.test(n))) {
       if (!names.has(e)) names.add(e);

package/src/change/lifecycle.ts

@@ -84,6 +84,8 @@ function resolveWorktreePath(
   naming: 'id' | 'hash' | undefined,
 ): string {
   const toplevel = git.run(['rev-parse', '--show-toplevel']);
+  // git rev-parse --show-toplevel emits forward-slash paths even on win32
+  // (git-for-Windows normalizes) — POSIX by contract; keep '/'-splitting.
   const cut = toplevel.lastIndexOf('/');
   const basename = toplevel.slice(cut + 1);
   const name =

package/src/config/schema.ts

@@ -26,7 +26,7 @@ export const specsSchema = z.object({
     .string()
     .nullish()
     .describe(
-      'Spec verification command executed by validate for spec targets (skip with --no-check). Placeholders: {feature_path}, {feature_dir}, {feature_name}; without placeholders it runs once per validate invocation (batch-once). Legacy `bdd.run_command` is elevated onto this key at load time.',
+      'Spec verification command executed by validate for spec targets (opt-in via --check; default skips). Placeholders: {feature_path}, {feature_dir}, {feature_name}; without placeholders it runs once per validate invocation (batch-once). Legacy `bdd.run_command` is elevated onto this key at load time.',
     ),
   verify_prompt: z.string().nullish().describe('Extra prompt text injected during verify phase.'),
 });

package/src/index.ts

@@ -1,5 +1,3 @@
-export * from './ports.ts';
-
 export {
   EXTRA_SKILLS,
   archiveSchema,
@@ -107,6 +105,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 +195,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/spec/migrateNative.ts

@@ -141,8 +141,7 @@ export function migrateNativeSource(source: string): MigrateResult {
   for (const b of blocks) {
     if (!b.isRule) continue;
     rules++;
-    out.push(`  @req:${b.reqIds[0] ?? ''}`);
-    out.push(`  ${kw.rule}: ${b.title}`);
+    out.push(`  @req:${b.reqIds[0] ?? ''}`, `  ${kw.rule}: ${b.title}`);
     for (const line of b.descriptionLines) {
       const text = stripBullet(line);
       if (text !== '') out.push(`    ${text}`);

package/src/spec/parser.ts

@@ -96,7 +96,8 @@ function extractHeader(source: string): CapabilityHeader {
 }
 
 interface RawTags {
-  names: string[]; // without leading '@'
+  // Tag names are stored here without the leading '@'.
+  names: string[];
   reqId: string;
 }
 

package/src/validation/harness.ts

@@ -57,6 +57,8 @@ export interface HarnessRunOutcome {
 
 /** Plain-text placeholder expansion — capability ids are kebab-constrained. */
 export function expandRunCommand(command: string, target: HarnessTarget): string {
+  // featurePath is a repo-relative spec path (llmanspec/specs/x.feature), POSIX by
+  // contract on every host — keep '/'-splitting, do not switch to node:path here.
   const dirEnd = target.featurePath.lastIndexOf('/');
   const featureDir = dirEnd === -1 ? target.featurePath : target.featurePath.slice(0, dirEnd);
   return command
@@ -74,7 +76,7 @@ interface CacheEntry {
 const OUTPUT_TAIL = 200;
 
 /**
- * Trigger matrix (r13): --no-check skips silently; a nested invocation skips
+ * Trigger matrix (r13): default skips; a nested invocation skips
  * with a per-spec INFO; an explicit --check without a configured check_command
  * yields a single INFO on the first spec; otherwise every expanded command
  * executes at most once (cache keyed by the expanded 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;
+  }
+}

package/templates/en/skills/llman-sdd-apply.md

@@ -75,9 +75,16 @@ Run the project gates as appropriate:
 - Edit `llmanspec/specs/<capability>.feature` on the branch as needed (flat or directory main file; canonical native layout: `@req:<id>` on the `规则:` block header, nested `场景:` as executable examples); run `llman-sdd validate --specs` after spec edits; commit on the branch freely.
 - SDD validation: `llman-sdd validate <id> --strict`
 
+**Verification ladder (opt-in discipline, escalate by cost)**:
+- L1 minimal unit: `bun test tests/unit/<relevant>` (<1s, direct import), covers only the current change point.
+- L2 targeted behavior: `bun test tests/bdd -t "<scenario/rule title pattern>"` — exercises only the relevant real-CLI path.
+- L3 explicit full harness: `llman-sdd validate --check` (with `specs.check_command` configured; plain `validate` no longer runs the harness).
+- L4 close-out backstop: `change finalize` runs the real harness pre-merge — at least one full run per close-out.
+- Self-heal loops default to L1/L2 for fast reproduction; use L3 only when full-acceptance evidence is needed; avoid paying full-suite cost needlessly.
+
 **Gate evidence**:
-- Close-out runs the configured `specs.check_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
-- Gate verdicts MUST come from the real harness: MUST NOT obtain a "pass" via `--no-check`; on harness failure, find the root cause first (leaked env vars, nested-invocation guards, wrong cwd …) — MUST NOT label it an "inherent/self-referential property" and bypass it.
+- Plain `validate` is structure/state-only and claims no harness evidence; harness evidence MUST come from explicit `--check` or close-out acceptance.
+- Gate verdicts MUST come from the real harness: claiming a harness pass requires `--check` (or close-out); the default structural gate is not a pass; on harness failure, find the root cause first (leaked env vars, nested-invocation guards, wrong cwd …) — MUST NOT label it an "inherent/self-referential property" and bypass it.
 - Before/after criteria (counts, baselines) MUST be measured on the change branch (against the freshly computed merge-base); a value measured on the default branch is usually trivially the baseline and proves nothing.
 - Refactors and bulk replacements: MUST compare the test count before and after; all-green gates with fewer tests is a failure.
 

package/templates/en/skills/llman-sdd-explore.md

@@ -46,7 +46,7 @@ flowchart LR
    - Write decisions back: resolved decisions go into the change's `proposal.md` "Open Questions" section.
    - Completion criterion: every pending decision is resolved or explicitly deferred. When not triggered, the default (ask 1–3 questions) behavior is unchanged.
 4. If a change id is relevant, read its artifacts under `llmanspec/changes/<id>/`.
-   - When diagnosing validation errors, run `llman-sdd validate <spec> --strict` first for the structural gates (Gherkin / `@req` linkage / dual-write / req_id uniqueness); when `specs.check_command` is configured, validate executes that harness by default (`--no-check` skips it). Failing items are pinned down in the default TOON output's `items[].issues[]`; `--output human` prints `FAIL <item_type>/<id>` lines.
+   - When diagnosing validation errors, run `llman-sdd validate <spec> --strict` first for the structural gates (Gherkin / `@req` linkage / dual-write / req_id uniqueness); when `specs.check_command` is configured, validate only executes that harness with explicit `--check` (default skips). Failing items are pinned down in the default TOON output's `items[].issues[]`; `--output human` prints `FAIL <item_type>/<id>` lines.
 5. Explore options and tradeoffs (2–3 options).
 6. Assess change scale to determine if full SDD is needed.
 7. When something crystallizes, offer to capture it (don't auto-write):

package/templates/en/skills/llman-sdd-propose.md

@@ -85,7 +85,7 @@ This MUST pass before proceeding; failing items are listed one by one in the val
 
 ### 4a) Optional BDD runner (`specs:` block)
 - Read `llmanspec/config.yaml`. Is there a `specs:` block?
-  - **Yes**: `specs.check_command` declares the project's BDD execution entry; validate executes it by default when its target set includes specs (`--no-check` skips). Authoring follows 4b regardless.
+  - **Yes**: `specs.check_command` declares the project's BDD execution entry; validate runs it only via explicit `--check` (default skips — structure-only). Authoring follows 4b regardless.
   - **No**: if this change involves executable behavior scenarios (Given/When/Then the user will want to run), ask **once, up front** whether to enable a `specs:` verification runner block (adds a `specs:` block to `config.yaml` — runner only, does not change the lifecycle). If **yes**: show the exact `specs:` block to add (pick a `check_command` matching the project's test framework — `cargo test --features bdd` for rstest-bdd, `pytest {feature_dir} -k {feature_name} -v` for pytest-bdd), let the user confirm or edit, write it to `config.yaml`, then proceed with 4b. If **no**: features still validate structurally; BDD execution responsibility stays with the project test suite.
 - **Do NOT silently add the `specs:` block** — always ask first. Adding it declares the project-wide BDD execution entry.
 

package/templates/en/skills/llman-sdd-validate.md

@@ -16,7 +16,7 @@ Validate change/spec format and staleness.
 3. **BDD checks**:
    - Validate `.feature` Gherkin and `@req` / dual-write gates on the **bound branch**; `.feature` is the harness authority — executable GWT lives only there.
    - Lifecycle gates: `change start` / `attach` (bind branch), `finalize` (close-out; auto commit `archive(sdd): <id>`, `--no-commit` to skip) / `diff` (read-only).
-   - `llman-sdd validate --specs` enforces structural and contract gates; when `specs.check_command` is configured it also executes that harness by default (`--no-check` skips it, `--check` is a compat alias); a placeholder-free command runs at most once per invocation.
+   - `llman-sdd validate --specs` enforces structural and contract gates; when `specs.check_command` is configured the full harness runs only with explicit `--check` (default skips — structure-only); a placeholder-free command runs at most once per invocation.
    - `list --specs --json` shows `morphology` (requirementCount / requirementBoundCount / requirementUnboundCount / acceptanceCount / featureScenarioCount).
    - Change JSON status fields: `stage` (draft/designed/planned/full) / `specsLanded` / `needsSpecsChange` / `readyToImplement` (`show --output json`).
 {% endif %}

package/templates/en/skills/llman-sdd-verify.md

@@ -25,8 +25,8 @@ flowchart LR
 
 - **Apply must be all-green first**: don't verify unimplemented changes.
 - **CRITICAL must be fixed**: zero CRITICAL before archive.
-- **Rerun the gates yourself**: MUST rerun `llman-sdd validate <id> --strict` (real harness) and the project gates; MUST NOT trust gate verdicts in the implementer's report — a mismatch is CRITICAL.
-- **`--no-check` is not evidence**: gate evidence obtained with `--no-check` → CRITICAL. Close-out runs the configured `specs.check_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
+- **Rerun the gates yourself**: MUST rerun `llman-sdd validate <id> --check --strict` (real harness evidence) and the project gates; MUST NOT trust gate verdicts in the implementer's report — a mismatch is CRITICAL.
+- **Harness evidence requires `--check`**: plain `validate` does not run the harness; claiming full-harness evidence MUST use explicit `--check` — the default structural gate is not a pass. Close-out runs the configured `specs.check_command`, so do not run it again just before close-out.
 - **Don't ask "should I continue?"**: run the full verification flow and output a complete report.
 
 {{ unit("skills/stage-guard") }}
@@ -34,7 +34,7 @@ flowchart LR
 ## Steps
 1. Select the change id (or ask the user to pick from `llman-sdd list --json`).
 2. Fast validation gate: `llman-sdd validate <id> --strict`.
-   - When diagnosing structural issues (Gherkin parse / `@req` linkage / dual-write / req_id uniqueness), run the structural validation first (when `specs.check_command` is configured, validate executes that harness by default — `--no-check` skips it; a harness failure lands as an ERROR on its spec item). Failing items are listed one by one in the default TOON output's `items[].issues[]` (`--output human` prints `FAIL <item_type>/<id>` lines above the `Totals` line).
+   - When diagnosing structural issues (Gherkin parse / `@req` linkage / dual-write / req_id uniqueness), run the structural validation first (the full harness only runs via explicit `--check`; plain `validate` no longer runs it by default; a harness failure lands as an ERROR on its spec item). Failing items are listed one by one in the default TOON output's `items[].issues[]` (`--output human` prints `FAIL <item_type>/<id>` lines above the `Totals` line).
 3. Read: `llmanspec/specs/**` (`<capability>.feature`, the single source of truth) on the branch, `proposal.md` and `design.md` (if present), `tasks.md`; ignore residual old docs under `changes/<id>/specs/`.
 4. **Dual-axis review (kept separate so neither masks the other)** — diff against `git diff <merge-base>...HEAD` (merge-base is COMPUTED via `git merge-base <local-default> HEAD`; the stored base_sha is audit-only and MUST NOT feed range math):
    - **Spec axis**: does the implementation satisfy the `规则:` block requirement statement (free-text description, judged by its semantics) and the nested `场景:` GWT steps? Missing/partial behaviors, wrong implementations, and scope creep not asked for by the spec → suggest minimal fixes or artifact updates. Check where before/after evidence (counts, baselines) was taken: it MUST be measured on the change branch (against the freshly computed merge-base); a value measured on the default branch is usually trivially the baseline and proves nothing.
@@ -57,7 +57,7 @@ flowchart LR
    - The two axes may be reviewed in parallel (sub-agents); the report MUST present them separately, MUST NOT merge or cross-rerank (one axis passing must not mask the other failing).
 5. **BDD verification** — only when `config.yaml` has a `specs:` block:
    - Confirm the change is branch-bound and you are on that branch.
-   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; when `specs.check_command` is configured the harness runs by default (`--no-check` skips it) and a failure maps to an ERROR on the matching spec item.
+   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; the full harness only runs via explicit `--check` (default skips) and a failure maps to an ERROR on the matching spec item.
    - Optional read-only review: `llman-sdd change diff <id>` (or `--export-patch <path>`) — review/export only, never an apply step.
    - Next step after verify passes: `llman-sdd-archive` (not inline finalize here).
 {% if specs_verify_prompt %}

package/templates/zh-Hans/skills/llman-sdd-apply.md

@@ -75,9 +75,16 @@ flowchart LR
 - 分支上按需编辑 `llmanspec/specs/<capability>.feature`（扁平或目录主文件；统一原生分层：`@req:<id>` 挂 `规则:` 块头、嵌套 `场景:` 为可执行示例），spec 改动后跑 `llman-sdd validate --specs`；分支上可自由提交。
 - SDD 校验：`llman-sdd validate <id> --strict`
 
+**验证阶梯（opt-in 纪律，按成本逐级扩大）**：
+- L1 最小单元：`bun test tests/unit/<相关>`（<1s，直接导入），仅覆盖当前改动点。
+- L2 定向行为：`bun test tests/bdd -t "<场景/规则标题模式>"`——只跑相关场景的真实 CLI 链路。
+- L3 显式全量：`llman-sdd validate --check`（配置 `specs.check_command` 时执行全量 harness；缺省 validate 不再执行 harness）。
+- L4 收口兜底：`change finalize` 预合并强制真实 harness——每次收口至少 1 次全量。
+- 自修复循环默认用 L1/L2 快速复现；只有需要全量验收时才 L3；避免无谓白付全量成本。
+
 **门禁证据**：
-- 收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
-- 门禁结论 MUST 来自真实 harness：MUST NOT 以 `--no-check` 取得「通过」；harness 失败 MUST 先查根因（环境变量泄漏、嵌套调用守卫、工作目录错误等），MUST NOT 以「固有/自指属性」定性后绕过。
+- 缺省 `validate` 只做结构/状态门，不声明 harness 证据；harness 证据 MUST 经显式 `--check` 或收口验收取得。
+- 门禁结论 MUST 来自真实 harness：声称 harness 合格时 MUST 已用 `--check`（或收口）；缺省结构门的通过不是通过；harness 失败 MUST 先查根因（环境变量泄漏、嵌套调用守卫、工作目录错误等），MUST NOT 以「固有/自指属性」定性后绕过。
 - 前后对比类判据（计数、基线）MUST 在 change 分支上测量（相对现算 merge-base）；默认分支测得的值通常恒为基线，不构成证据。
 - 重构或批量替换类 task：MUST 对比改动前后测试用例数；门禁全绿但用例数下降视为失败。
 

package/templates/zh-Hans/skills/llman-sdd-explore.md

@@ -46,7 +46,7 @@ flowchart LR
    - 决策回写：已解决的决策写进该 change 的 `proposal.md`「Open Questions」段。
    - 完成判据：每个待定决策都已解决或显式推迟。未触发时保持默认（问 1–3 个问题）。
 4. 涉及某个 change id 时，读 `llmanspec/changes/<id>/` 下的工件。
-   - 诊断校验错误先跑 `llman-sdd validate <spec> --strict` 过结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性）；配置了 `specs.check_command` 时 validate 缺省执行该 harness（`--no-check` 跳过）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条指明；`--output human` 输出人读 `FAIL <item_type>/<id>` 行。
+   - 诊断校验错误先跑 `llman-sdd validate <spec> --strict` 过结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性）；配置了 `specs.check_command` 时 validate 仅经显式 `--check` 执行该 harness（缺省跳过）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条指明；`--output human` 输出人读 `FAIL <item_type>/<id>` 行。
 5. 探索 2–3 个选项与权衡。
 6. 判断变更规模，确定是否走完整 SDD。
 7. 结论清晰时建议用户记录（勿自动写）：

package/templates/zh-Hans/skills/llman-sdd-propose.md

@@ -85,7 +85,7 @@ MUST 通过才能继续；失败项在 validate 输出的 `items[].issues[]` 逐
 
 ### 4a) 可选 BDD runner（`specs:` 段）
 - 读 `llmanspec/config.yaml` 是否含 `specs:` 段：
-  - **有**：`specs.check_command` 是项目的 BDD 执行入口；validate 在目标集含 spec 时缺省执行它（`--no-check` 跳过）。撰写仍按 4b。
+  - **有**：`specs.check_command` 是项目的 BDD 执行入口；validate 仅在显式 `--check` 时执行它（缺省跳过，仅结构/状态门）。撰写仍按 4b。
   - **无**：若本次 change 含可执行行为场景（用户会想运行的 Given/When/Then），**一次性前置**询问是否启用 `specs:` 验证 runner 段（会向 `config.yaml` 加一个 `specs:` 段——仅 runner，不改生命周期）。**是**：展示要加的精确 `specs:` 段（`check_command` 选匹配项目测试框架的——rstest-bdd 用 `cargo test --features bdd`，pytest-bdd 用 `pytest {feature_dir} -k {feature_name} -v`），用户确认或修改后写入 `config.yaml`，再按 4b 继续。**否**：feature 仍做结构校验；BDD 执行责任始终在项目测试套件。
 - **MUST NOT 静默添加 `specs:` 段**——总是先问。添加它会向全项目声明 BDD 执行入口。
 

package/templates/zh-Hans/skills/llman-sdd-validate.md

@@ -16,7 +16,7 @@ metadata:
 3. **Spec 校验**：
    - 在**绑定分支**上验证 `.feature` Gherkin 与 `@req` / 双写门禁；`.feature` 是 harness 权威——可执行 GWT 只在其中维护。
    - 生命周期门禁：`change start` / `attach`（绑定分支）、`finalize`（收口；自动提交 `archive(sdd): <id>`，`--no-commit` 跳过）/ `diff`（只读）。
-   - `llman-sdd validate --specs` 做结构与合约门禁；配置 `specs.check_command` 时缺省执行该 harness（`--no-check` 跳过，`--check` 为兼容别名），无占位符的命令每次调用至多执行一次。
+   - `llman-sdd validate --specs` 做结构与合约门禁；配置 `specs.check_command` 时全量 harness 仅经显式 `--check` 执行（缺省跳过，仅结构/状态门），无占位符的命令每次调用至多执行一次。
    - `list --specs --json` 查看 `morphology`（requirementCount / requirementBoundCount / requirementUnboundCount / acceptanceCount / featureScenarioCount）。
    - change JSON 状态字段：`stage`（draft/designed/planned/full）/ `specsLanded` / `needsSpecsChange` / `readyToImplement`（`show --output json`）。
 {% endif %}

package/templates/zh-Hans/skills/llman-sdd-verify.md

@@ -25,8 +25,8 @@ flowchart LR
 
 - **必须先 apply 全绿**：未完成实现的 change 跳过验证。
 - **CRITICAL 必须修复**：归档前清零。
-- **亲自复跑门禁**：MUST 亲自重跑 `llman-sdd validate <id> --strict`（真实 harness）与项目门禁，MUST NOT 采信实现者报告的门禁结论；复跑结果与报告不符 → CRITICAL。
-- **`--no-check` 不是证据**：以 `--no-check` 取得的门禁证据 → CRITICAL。收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
+- **亲自复跑门禁**：MUST 亲自重跑 `llman-sdd validate <id> --check --strict`（真实 harness 证据）与项目门禁，MUST NOT 采信实现者报告的门禁结论；复跑结果与报告不符 → CRITICAL。
+- **harness 证据必须 `--check`**：缺省 `validate` 不执行 harness，声称全量 harness 证据 MUST 经显式 `--check`（缺省结构门的通过不是通过）；收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍。
 - **不要问「要不要继续」**：跑完整验证流程，输出完整报告。
 
 {{ unit("skills/stage-guard") }}
@@ -34,7 +34,7 @@ flowchart LR
 ## 步骤
 1. 确定 change id（不明确时让用户从 `llman-sdd list --json` 选）。
 2. 快速校验门禁：`llman-sdd validate <id> --strict`。
-   - 诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / req_id 唯一性）先跑结构校验（配置 `specs.check_command` 时 validate 缺省执行该 harness，`--no-check` 跳过；harness 失败以 ERROR 落在对应 spec 条目）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条列出（`--output human` 输出 `FAIL <item_type>/<id>` 行，位于 `Totals` 上方）。
+   - 诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / req_id 唯一性）先跑结构校验（全量 harness 仅经显式 `--check` 执行，缺省不再自动执行；harness 失败以 ERROR 落在对应 spec 条目）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条列出（`--output human` 输出 `FAIL <item_type>/<id>` 行，位于 `Totals` 上方）。
 3. 阅读：分支上的 `llmanspec/specs/**`（`<capability>.feature`，唯一事实来源）、`proposal.md` 与 `design.md`（如有）、`tasks.md`；`changes/<id>/specs/` 若有残留旧文档可忽略。
 4. **双轴审查（两轴分离，互不掩盖）**——对比 diff（`git diff <merge-base>...HEAD`，merge-base 现算 `git merge-base <本地默认分支> HEAD`；存储的 base_sha 仅审计、MUST NOT 参与范围计算）：
    - **合约轴**：实现是否满足 `规则:` 块的需求表述(描述为自由文本,以其语义为准)与嵌套 `场景:` 的 GWT 步骤？缺失/部分实现、错误实现、spec 未要求的超范围改动 → 给最小修复建议或建议更新工件。前后对比类证据（计数、基线）核对测量位置：MUST 在 change 分支上测量（相对现算 merge-base）；默认分支测得的值通常恒为基线，不构成证据。
@@ -57,7 +57,7 @@ flowchart LR
    - 两轴可并行（sub-agent）审查；报告 MUST 分离呈现，MUST NOT 合并或交叉重排（一轴通过不能掩盖另一轴失败）。
 5. **Spec 验证**——仅当 `config.yaml` 含 `specs:` 段：
    - 确认 change 已绑定分支且当前在该分支上。
-   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；配置 `specs.check_command` 时缺省执行该 harness（`--no-check` 跳过），失败映射为对应 spec 条目的 ERROR。
+   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；全量 harness 仅经 `--check` 显式执行（缺省跳过），失败映射为对应 spec 条目的 ERROR。
    - 可选只读审查：`llman-sdd change diff <id>`（或 `--export-patch <path>`）——仅审查/导出，绝不当作 apply 步骤。
    - verify 通过后下一步 `llman-sdd-archive`（勿在此 inline finalize）。
 {% if specs_verify_prompt %}

package/src/ports.ts

@@ -1,14 +0,0 @@
-/**
- * Ports (spec monorepo-structure r3): domain logic must not touch the
- * filesystem, git subprocesses, or the terminal directly — side effects are
- * injected through these interfaces. Nothing under packages/core may import
- * `node:fs`, `Bun.$`, or prompt libraries; runtimes wire adapters in.
- */
-
-/** Interaction port. predecessor ships an @inquirer/prompts adapter; a future ink TUI
- * ships its own adapter (the two must never run in the same process). */
-export interface PromptDriver {
-  select<T extends string>(message: string, choices: readonly T[]): Promise<T>;
-  multiselect<T extends string>(message: string, choices: readonly T[]): Promise<T[]>;
-  confirm(message: string): Promise<boolean>;
-}