@llman-sdd/core 0.3.1 → 0.5.0

package/src/validation/validate.ts

@@ -1,18 +1,18 @@
 /**
  * Validation engine (validation capability): aggregates Phase-2 parse errors
- * plus the verdict-equivalent gates (r11/r12, ordered to match v1
+ * plus the verdict-equivalent gates (r11/r12, ordered to match predecessor
  * `spec/validation.rs` observable issue order). Pure — filesystem access is
  * injected via SpecIo.
  */
 import type { CapabilityDoc } from '../spec/ir.ts';
-import { MUST_WORD_RE } from '../spec/ir.ts';
+import { specIdOf } from '../spec/ir.ts';
 import { buildReqRegistry } from '../spec/reqRegistry.ts';
 
 export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
 
 export interface ValidationItem {
   level: ValidationLevel;
-  /** Gate anchor, e.g. `t/rule/ok` or `t/valid_scope` (v1-style `path`). */
+  /** Gate anchor, e.g. `t/rule/ok` or `t/valid_scope` (predecessor-style `path`). */
   id: string;
   message: string;
 }
@@ -41,7 +41,6 @@ export interface ValidationReport {
 }
 
 const rulesPath = (cap: string): string => `${cap}/rules`;
-const acceptanceReqPath = (cap: string, name: string): string => `${cap}/acceptance/${name}/@req`;
 const coveragePath = (cap: string): string => `${cap}/coverage`;
 
 export function validateCapability(
@@ -51,7 +50,7 @@ export function validateCapability(
   opts: { strict?: boolean } = {},
 ): SpecVerdict {
   const { doc } = entry;
-  const cap = doc.header.capability ?? entry.fileName;
+  const cap = specIdOf(entry);
   const strict = opts.strict === true;
   const items: ValidationItem[] = [];
 
@@ -59,27 +58,23 @@ export function validateCapability(
     items.push({ level, id, message });
   };
 
-  // Header gates (r12 / v1 spec_meta). v1 treats a missing `# capability:`
+  // Header gates (r12 / predecessor spec_meta). predecessor treats a missing `# capability:`
   // header as a parse-level failure: only `file` + registry-scan issues are
   // emitted and all single-track gates are skipped.
   if (doc.header.capability === null) {
-    const msg = `spec \`${cap}\`: missing \`# capability:\` header comment (spec-format r133)`;
+    const msg = `spec \`${cap}\`: missing \`# capability:\` header comment`;
     push('ERROR', 'file', msg);
     push('ERROR', 'llmanspec/specs', `Failed to scan req_id index: ${msg}`);
     return { fileName: entry.fileName, capability: cap, ok: false, items };
   }
   if (doc.header.purpose === null || doc.header.purpose.trim() === '') {
-    push(
-      'ERROR',
-      `${cap}/purpose`,
-      '`# purpose:` header comment must not be empty (spec-format r133)',
-    );
+    push('ERROR', `${cap}/purpose`, '`# purpose:` header comment must not be empty');
   }
   if (doc.header.scope === null) {
     push(
       'ERROR',
       `${cap}/valid_scope`,
-      'Spec valid_scope must not be empty (add it inside the .toon document).',
+      'Spec valid_scope must not be empty (declare it in the "# scope:" header comment).',
     );
   } else {
     // r42: missing valid_scope paths are independent failures —
@@ -112,86 +107,50 @@ export function validateCapability(
     push('ERROR', `${cap}/feature`, 'Feature line must carry a title');
   }
 
-  // Parser-level structural errors (mutual exclusion, removed-tag migration,
-  // nested rule scenarios). Header gates and the MUST-word gate are owned here
-  // (mapped below), so the parser's duplicate findings are skipped.
-  const OWNED_BY_THIS_LAYER = ['missing-header:', 'rule:missing-must-word'];
+  // Parser-level structural errors. Header gates are owned here (mapped below);
+  // the parser's duplicate header findings are skipped.
+  const OWNED_BY_THIS_LAYER = ['missing-header:'];
   for (const err of doc.errors) {
     if (OWNED_BY_THIS_LAYER.some((prefix) => err.code.startsWith(prefix))) continue;
     push('ERROR', err.code.startsWith('file') ? 'file' : `${cap}/${err.code}`, err.message);
   }
 
-  // Single-track gates (v1 validate_single_track order).
-  const human = doc.scenarios.filter((s) => s.classification === 'human');
-  const acceptance = doc.scenarios.filter((s) => s.classification === 'executable');
+  // Native single-track gates: `规则:` blocks with `@req` handles; nested
+  // `场景:` are their executable examples; top-level scenarios are orphans.
+  const rules = doc.rules;
 
-  if (human.length === 0) {
-    push('ERROR', rulesPath(cap), 'spec must define at least one @human constraint scenario');
+  if (rules.length === 0) {
+    push('ERROR', rulesPath(cap), 'spec must define at least one rule');
   }
 
-  for (const scenario of doc.scenarios) {
-    const anchor = `${cap}/rule/${scenario.name}`;
-    if (scenario.classification === 'human') {
-      if (scenario.reqIds.length === 0) {
-        push('ERROR', anchor, '@human constraint scenario must carry an @req:<req_id> tag');
-      }
-      if (!MUST_WORD_RE.test(scenario.statement)) {
-        push('ERROR', anchor, 'constraint statement must contain MUST/SHALL (or 必须/不得/禁止)');
-      }
-    } else if (scenario.classification === 'executable') {
-      // (pairing handled below, after all rule req ids are known)
-    } else {
+  for (const rule of rules) {
+    const anchor = `${cap}/rule/${rule.title}`;
+    if (rule.reqId === '') {
+      push('ERROR', anchor, 'rule must carry an @req:<req_id> tag on the rule header');
+    } else if (duplicatesFor(rule.reqId)) {
       push(
-        'WARNING',
-        `${cap}/scenario/${scenario.name}`,
-        `scenario \`${scenario.name}\` carries neither @human nor @executable; tag it or drop it`,
+        'ERROR',
+        `${cap}/registry/${rule.reqId}`,
+        `global duplicate req_id \`${rule.reqId}\` used by multiple capabilities`,
       );
     }
-    for (const reqId of scenario.reqIds) {
-      if (duplicatesFor(reqId)) {
-        push(
-          'ERROR',
-          `${cap}/registry/${reqId}`,
-          `global duplicate req_id \`${reqId}\` used by multiple capabilities`,
-        );
-      }
-    }
   }
 
-  // Dangling acceptance @req links (v1 order: acceptance/@req then coverage).
-  const ruleReqIds = new Set(human.flatMap((s) => s.reqIds));
-  for (const sc of acceptance) {
-    // r65: orphan acceptance scenario — no @req link at all (v1 r132 WARNING).
-    if (sc.reqIds.length === 0) {
-      push(
-        'WARNING',
-        `${cap}/acceptance/${sc.name}`,
-        `orphan acceptance scenario \`${sc.name}\` has no @req:<req_id> link`,
-      );
-    }
-    for (const rid of sc.reqIds) {
-      if (!ruleReqIds.has(rid)) {
-        push(
-          'ERROR',
-          acceptanceReqPath(cap, sc.name),
-          `@req:${rid} on acceptance scenario \`${sc.name}\` has no matching @human constraint`,
-        );
-      }
-    }
-  }
+  // Top-level `场景:` outside any rule are plain feature-level examples
+  // (native Gherkin); they carry no rule handle, so no warning or signal —
+  // they simply aren't part of rule accounting.
 
-  // Rule coverage INFO (r134 pending rules).
-  for (const sc of human) {
-    for (const rid of sc.reqIds) {
-      const covered = acceptance.some((a) => a.reqIds.includes(rid));
-      if (!covered) {
-        push(
-          'INFO',
-          coveragePath(cap),
-          `rule ${rid} is pending: no @executable acceptance scenario`,
-        );
-      }
-    }
+  // Bare-rule aggregate (r134 migrated): rules with no nested executable
+  // scenario, aggregated per capability (never one issue per rule), INFO so it
+  // never blocks anything. The real accountability lives in the review
+  // `pending` signal and the specs-compact workflow.
+  const bare = rules.filter((r) => r.scenarios.length === 0).length;
+  if (bare > 0) {
+    push(
+      'INFO',
+      coveragePath(cap),
+      `${bare} bare rule(s) without any executable scenario — convert to 场景: or compact`,
+    );
   }
 
   return {
@@ -202,13 +161,28 @@ export function validateCapability(
   };
 }
 
-export function validateAllSpecs(entries: readonly SpecEntry[], io: SpecIo): ValidationReport {
+/**
+ * Shared req_id duplicate gate — single source of truth for the CLI
+ * (`validate <spec>` path) and the full sweep. The registry is built from the
+ * already-parsed docs, so a duplicate is reported for every involved
+ * capability regardless of unrelated parse errors elsewhere (r12 acceptance:
+ * 重复 req_id MUST 对每个涉事 capability 判 ERROR — the 前代 "structural error
+ * aborts the index scan" guard is intentionally dropped; a parse-failed spec
+ * merely omits the scenarios it could not decode, never invents ids).
+ */
+export function buildDuplicatesFor(entries: readonly SpecEntry[]): (reqId: string) => boolean {
   const registry = buildReqRegistry(entries);
   const duplicateIds = new Set(registry.duplicates.flatMap((d) => d.reqId));
-  // v1 parity: a structural error anywhere aborts the req_id index scan, so
-  // the duplicate gate only fires when every spec parses cleanly.
-  const structurallyClean = entries.every((e) => e.doc.errors.length === 0);
-  const duplicatesFor = (reqId: string): boolean => structurallyClean && duplicateIds.has(reqId);
+  return (reqId: string): boolean => duplicateIds.has(reqId);
+}
+
+/** `Totals:` report line — single wording source for the engine and the CLI. */
+export function formatTotals(passed: number, failed: number, total: number): string {
+  return `Totals: ${passed} passed, ${failed} failed (${total} items)`;
+}
+
+export function validateAllSpecs(entries: readonly SpecEntry[], io: SpecIo): ValidationReport {
+  const duplicatesFor = buildDuplicatesFor(entries);
 
   const verdicts = entries.map((e) => validateCapability(e, duplicatesFor, io));
   const failed = verdicts.some((v) => !v.ok);
@@ -221,14 +195,12 @@ export function validateAllSpecs(entries: readonly SpecEntry[], io: SpecIo): Val
       lines.push(`  [${item.level}] ${item.id}: ${item.message}`);
     }
   }
-  lines.push(
-    `Totals: ${passed} passed, ${verdicts.length - passed} failed (${verdicts.length} items)`,
-  );
+  lines.push(formatTotals(passed, verdicts.length - passed, verdicts.length));
 
   return { verdicts, lines, failed };
 }
 
-/** v1 `apply_strict`: WARNING issues escalate to ERROR when --strict. */
+/** predecessor `apply_strict`: WARNING issues escalate to ERROR when --strict. */
 export function applyStrict<T extends { level: ValidationLevel }>(items: readonly T[]): T[] {
   return items.map((i) => (i.level === 'WARNING' ? { ...i, level: 'ERROR' as const } : i));
 }

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

@@ -1,6 +1,6 @@
 ---
 name: "llman-sdd-apply-cycle"
-description: "Single closed-loop for one change: gate→implement→test→validate→verify→archive→commit. Manual trigger only. Agent MUST NOT auto-invoke."
+description: "End-to-end closed loop for one change: implement→test→validate→verify→archive. Manual trigger only; agent must not auto-invoke."
 metadata:
   version: "{{ llman_version }}"
 disable-model-invocation: true
@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 # LLMAN SDD Apply Cycle
 
-End-to-end closed loop for one change (manual). Requires Branch binding and `readyToImplement=true`.
+End-to-end closed loop for one change (manual). Requires a bound branch and a green specs-landed gate (`specsLanded ∨ needsSpecsChange=false`); `readyToImplement=true` (the completion signal) closes the cycle.
 
 **Manual trigger only**: `/skill:llman-sdd-apply-cycle <change-id>`
 
@@ -16,60 +16,52 @@ End-to-end closed loop for one change (manual). Requires Branch binding and `rea
 
 ### 0) Gate + status
 ```bash
-llman-sdd show <change-id> --json --type change
+llman-sdd show <change-id> --output json --type change
 ```
-> Stage gate: decide from `stage` / `readyToImplement` in `llman-sdd show <id> --json --type change`; full decision table lives in llman-sdd-apply.
+> Stage decisions use the `stage` / `readyToImplement` fields; the full decision table lives in llman-sdd-apply.
 
 - Must be on the bound non-default branch.
-- If `readyToImplement` is not true → STOP (finish Specs landing or `needs_specs_change: false`); **do not** finalize yet.
-- Track progress via `tasks.md` checkboxes (or `llman-sdd list` task counts); still read `tasks.md`, proposal/design, and live `llmanspec/specs/**` on the bound branch (SSOT).
+- specs-landed gate failing → STOP (land specs or `needs_specs_change: false`). Green but `readyToImplement=false` → normal: tasks pending, keep implementing; **finalize only when `readyToImplement=true`**.
+- Track progress via `tasks.md` checkboxes (or `llman-sdd list` task counts); still read `tasks.md`, proposal/design, and `llmanspec/specs/**` on the bound branch (the single source of truth).
 
 ### 1) Loop: implement → test
 For each incomplete task:
-1. Implement per task + live specs (minimal diff)
-2. Run `tasks[].test` if present
+1. Implement per task + specs (minimal diff)
+2. Run the task's stated verification command when the task text names one
 3. On failure, fix and retry (same self-repair budget as `llman-sdd-apply`: cap 8 rounds)
 4. Check off `tasks.md` as `[x]`
 
 ### 2) Validate
 ```bash
-llman-sdd validate <change-id> --strict --no-interactive
+llman-sdd validate <change-id> --strict
 ```
-On failure, fix and retry (same self-repair budget as `llman-sdd-apply`: cap 8 rounds).
+On failure, fix and retry (cap 8 rounds).
 
 ### 3) Verify (recommended)
-Prefer `llman-sdd-verify` (or equivalent dual-axis self-check). CRITICAL → STOP; do not archive.
+Prefer `llman-sdd-verify` (or an equivalent dual-axis self-check). CRITICAL → STOP; do not archive.
 
-### 4) Archive
+### 4) Archive + commit
 ```bash
 llman-sdd change finalize <change-id>
 ```
-(dirty tree OK; auto merge (squash default) + docs rename + **auto commit** `archive(sdd): <change-id>` in one process. `--no-commit` skips the auto commit for manual/CI histories — then commit with `git add -A && git commit -m "archive(sdd): <change-id>"`.)
+Dirty tree OK; auto merge (squash default) + rename + **auto commit** `archive(sdd): <change-id>` in one process. `--no-commit` skips the auto commit (manual/CI histories) — then commit with `git add -A && git commit -m "archive(sdd): <change-id>"`. Plain `change archive` stays as a fallback.
 
-`change checkpoint` is removed; the plain `change archive` command stays as a fallback (no checkpointed field required).
-
-### 5) Commit (see step 4)
-Finalize already auto-committed unless `--no-commit` was passed.
-
-### 6) Optional cleanup
+### 5) Optional cleanup
 ```bash
 git branch -D <feature-branch>   # after squash the branch is no longer an ancestor of main; -d gets refused
 ```
-push / hosting PR only when the user explicitly asks.
+Push / PR only when the user explicitly asks.
 
 ## Hard constraints
 - **Never ask** "should I continue" unless blocked.
 - **Never switch** changes until this one is archived and committed.
-- **Retry cap**: self-repair follows `llman-sdd-apply`'s 8-round budget (including the diagnose escalation path).
-- **Do not** author `changes/<id>/specs/` or use `change delta`.
-- **No default push/PR**.
+- **Do not** author `changes/<id>/specs/`; **no default push/PR**.
 
 ## Ethics Governance
 - `ethics.risk_level`: medium
-- `ethics.prohibited_actions`: implement/archive without `readyToImplement`, switching changes early, writing `changes/<id>/specs/`, commit without validation, default push/PR
+- `ethics.prohibited_actions`: implementing without a bound branch / a green specs-landed gate, archiving without `readyToImplement=true`, switching changes early, writing `changes/<id>/specs/`, committing without validation, default push/PR
 - `ethics.required_evidence`: `readyToImplement=true`, validate --strict pass, all tasks checked, finalize/archive success
-- `ethics.refusal_contract`: after 3 gate/validation failures, report blocker; do not force-archive
-- `ethics.escalation_policy`: if changing SDD workflow specs/templates, pause for user confirm before archive
+- `ethics.refusal_contract`: after 8 self-repair rounds still failing, report a blocker; never force-archive
+- `ethics.escalation_policy`: if changing SDD workflow specs/templates, pause for user confirmation before archive
 
-> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
+{{ unit("skills/cli-footer") }}

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

@@ -1,125 +1,107 @@
 ---
 name: "llman-sdd-apply"
-description: "Implement tasks from an llman SDD change in a closed loop — write code, run tests, self-heal on failures until all gates pass. Use when a change is proposed and ready to implement. Updates tasks.md checkboxes and runs validation."
+description: "Implement a proposed change's tasks in a closed loop: code → test → self-heal → all gates green. Enter after propose, once specs are landed."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Apply
 
-Implement all tasks in `llmanspec/changes/<id>/tasks.md` **in one closed loop**:
-Implement code → Add tests/acceptance → Run gates → Self-heal on failures → Report results when all pass.
-Unless there is a clear blocker, **DO NOT stop halfway to ask "should I continue?"**
+Implement all tasks in `llmanspec/changes/<id>/tasks.md` **in one closed loop**: implement → add tests/acceptance → run gates → self-heal and re-run on failure → report when all pass. Unless there is a clear blocker, **do not stop halfway to ask "should I continue?"**
 
 ## Pipeline Position
 
 {{ unit("skills/git-native-flow-brief") }}
 
-### Skill navigation (not the lifecycle; shows current skill only)
-
 ```mermaid
 flowchart LR
-    propose["llman-sdd-propose<br/>Propose"] --> apply
-    apply["★ llman-sdd-apply ★<br/>Implement (readyToImplement)"]
-    apply --> verify["llman-sdd-verify<br/>Verify"]
-    verify --> archive["llman-sdd-archive<br/>Archive"]
+    propose["llman-sdd-propose"] --> apply["★ llman-sdd-apply"]
+    apply --> verify["llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style apply fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 You are at Git-native **H (apply)** in the full lifecycle diagram: Specs-landed (or `needs_specs_change: false`) and `readyToImplement=true` required first → next: `llman-sdd-verify`
+> 📍 Entry requires the specs-landed gate green (or `needs_specs_change: false`); `readyToImplement=true` (all gates green) is the completion signal that closes this loop → next `llman-sdd-verify`.
 
 ## Hard Constraints
 
-- **SSOT-driven**: `proposal.md` / `design.md` / `tasks.md` and live `llmanspec/specs/**` on the feature branch are the single source of truth; every MUST/SHALL in specs must be fulfilled.
-- **Scope-locked**: Only implement what's in the current change; don't fix "unrelated issues" on the side.
-- **Minimal changes**: Keep changes minimal and strictly scoped to current tasks.
-- **No guessing**: If requirements are unclear, or specs contradict reality, STOP and report — don't assume behavior.
-- **No legacy compatibility layers**: If a change requires new behavior, upgrade all call sites directly, unless tasks/proposal explicitly require compatibility.
-- **Don't ask "should I continue?"**: Execute to loop closure unless you hit an unresolvable blocker.
-- **Close-out**: this skill's closed loop ends by suggesting `llman-sdd-verify`; finalize/archive is handled by `llman-sdd-archive` (do not finalize inside the self-healing loop).
+- **Single-source-of-truth driven**: `proposal.md` / `design.md` / `tasks.md` and `llmanspec/specs/**` on the branch; every MUST/SHALL in specs must be fulfilled.
+- **Scope-locked**: only implement the current change's scope; never fix "unrelated issues" on the side; keep changes minimal.
+- **No guessing**: unclear requirements or specs contradicting reality → STOP and report; don't assume.
+- **No legacy compatibility layers**: if the change requires new behavior, upgrade all call sites directly, unless tasks/proposal explicitly require compatibility.
+- **Close-out**: this loop ends by suggesting `llman-sdd-verify`; finalize/archive belongs to `llman-sdd-archive` (do not finalize inside the self-healing loop).
 
 ## Commit Policy
 
-- **Commits on the change branch are free** (no mid-flight archive point; `change finalize` needs no clean tree): segment by task or milestone when it helps review, or keep the working tree dirty and let finalize make ONE close commit — both are first-class. `change checkpoint` no longer exists (calling it exits non-zero and points to finalize), so there is no mid-flight "archive point" to maintain; `change finalize` handles both shapes (it does NOT require a clean tree).
-- **Default close-out**: after all tasks pass gates and verify is green, `llman-sdd change finalize <id>` auto-commits `archive(sdd): <change-id>` (uncommitted impl diff + frontmatter + archive rename in one commit). Do not run finalize inside the apply loop. `--no-commit` skips the auto commit (manual/CI histories; pre-commit-hook conflicts).
-- **Blocker interrupt**: when you must STOP on a blocker, make ONE work-in-progress commit (e.g. `wip(sdd): <change-id> <summary>`) to preserve the state, then report.
+- **Commits on the change branch are free** (`change finalize` needs no clean tree): segment by task/milestone, or keep the tree dirty and let finalize make one close commit — both are first-class.
+- **Default close-out**: after all tasks pass gates and verify is green, `llman-sdd change finalize <id>` auto-commits `archive(sdd): <change-id>` (uncommitted diff + frontmatter + rename in one commit). Do not run finalize inside the apply loop. `--no-commit` skips the auto commit (manual/CI histories; pre-commit-hook conflicts).
+- **Blocker interrupt**: when you must STOP on a blocker, make ONE WIP commit (e.g. `wip(sdd): <change-id> <summary>`) to preserve the state, then report.
 
 ## Steps
 
 ### 0) Preflight (required)
-- Read and obey: `llmanspec/config.yaml`, `AGENTS.md` (if present).
-- `git status --porcelain`:
-  - If working tree is dirty and changes don't belong to the current change: `git stash push -u -m "llman-sdd-apply autopilot backup"`.
-- Run `llman-sdd validate --all --strict --no-interactive`:
-  - If it fails for reasons unrelated to the current change, stop and report (inconsistent artifacts prevent SSOT-driven implementation).
-- **Check spec valid_scope integrity**: use `llman-sdd list --specs --json` to list all specs, then for each spec verify every path in its `valid_scope` exists on disk. If any scope file/directory is missing, stop and suggest updating the spec (remove the deleted path from `valid_scope`).
-
-### 1) Select change id and check prerequisites
-- If a change id is provided, use it directly.
-- Otherwise infer from context; if ambiguous, run `llman-sdd list --json` and let user pick.
-- Always announce: "Using change: <id>" and how to override.
-- Confirm you are on the non-default feature branch bound via `llman-sdd change start <id>` or `change attach <id>` (`--force` only to rebind). Specs/features on the branch are SSOT — do not author under `changes/<id>/specs/`.
+- Read and obey `llmanspec/config.yaml`, `AGENTS.md` (if present).
+- `git status --porcelain`: if the tree is dirty with changes not belonging to this change → `git stash push -u -m "llman-sdd-apply autopilot backup"` first.
+- `llman-sdd validate --all --strict`: if it fails for reasons unrelated to this change → stop and report (inconsistent artifacts prevent source-of-truth-driven implementation).
+- **Check spec valid_scope integrity**: `llman-sdd list --specs --json` lists all specs; for each, verify every `valid_scope` path exists on disk. On missing paths → stop and suggest updating the spec (remove the deleted path).
+
+### 1) Select the change id and check prerequisites
+- If provided, use it; otherwise infer from context, and if ambiguous run `llman-sdd list --json` and let the user pick. Always announce "Using change: <id>" and how to override.
+- Confirm you are on the non-default branch bound via `llman-sdd change start <id>` or `change attach <id>` (`--force` only to rebind). Specs on the branch are the single source of truth — do not author under `changes/<id>/specs/`.
 {{ unit("skills/stage-guard") }}
 - Use `llman-sdd context --task "<goal from proposal>" --paths "<scope from specs>"` to get relevant specs.
-  - If context is unavailable, run `llman-sdd index rebuild` and retry.
+  - Context unavailable → run `llman-sdd index check` first: stale/missing → `llman-sdd index rebuild` and retry; still unavailable on a fresh index (`LLMAN_SDD_INDEX_CHAT_MODEL` unset) → fall back to `llman-sdd list --specs` + reading `.feature` files directly — do not loop on rebuild.
 
-### 2) Read SSOT artifacts
-You must read through:
-- `llmanspec/changes/<id>/proposal.md`
-- `llmanspec/changes/<id>/design.md` (if present)
-- `llmanspec/changes/<id>/tasks.md`
-- Live specs on the feature branch: `llmanspec/specs/**` (`<capability>.feature`) — this is SSOT
+### 2) Read the source-of-truth artifacts
+- `llmanspec/changes/<id>/proposal.md`, `design.md` (if present), `tasks.md`
+- `llmanspec/specs/**` (`<capability>.feature`) on the branch
 
-Extract hard constraints from proposal.md and design.md decisions. Convert tasks.md into a minimal executable step sequence (preserving original order).
+Distill proposal/design decisions into a list of inviolable hard constraints; convert tasks.md into a minimal executable step sequence (preserving original order).
 
 ### 3) Show status
-- Progress: "N/M tasks complete"
-- Next 1–3 unchecked tasks (brief overview)
+- Progress "N/M tasks complete" + a brief look at the next 1–3 unchecked tasks.
 
-### 4) Implement tasks one by one (closed-loop execution)
+### 4) Implement tasks one by one (closed loop)
 For each unchecked task:
-1. **Implement**: strictly per task description + specs requirements, keep changes minimal.
-2. **Update checkbox immediately** after completion: `- [ ]` → `- [x]`.
-3. If task is unclear, you hit a blocker, or specs/design don't match reality → STOP and report the blocker, don't assume.
-
-> 💡 Previous phase `llman-sdd-propose` (generated tasks); after this phase → `llman-sdd-verify` (verify)
-
-### 5) Verification and self-healing loop (run after each task or batch)
-Run project gate commands (adapt to the actual project):
-- Relevant test suite: `just test` or `cargo test --all`
-- Format/lint: `just check` or `just lint` + `just fmt`
-- Git-native: stay on the bound feature branch; edit live `llmanspec/specs/<capability>.feature` (flat, or directory `llmanspec/specs/<capability>/` main file; rules `@human`, acceptance `@executable`) as needed; run `llman-sdd validate --specs` after spec edits; commit on the branch freely (segmented or leave dirty for finalize). Do not use `change delta` / solidify / feature_delta; `change checkpoint` is removed.
-- SDD validation: `llman-sdd validate <id> --strict --no-interactive`
-
-**On failure → enter self-healing loop (don't ask "should I continue?"):**
-1. Parse failure cause (test failure / lint / format / validation error).
-2. **Decide if it's a hard-to-locate bug** (cause unclear / intermittent flake / regression not obvious at a glance):
-   - **Not hard-to-locate** (clear lint/format/compile/validation error): apply a minimum fix (don't expand scope); re-run the "minimum failure repro command" first, then re-run all gates.
-   - **Hard-to-locate bug → escalate to the diagnose sub-flow**:
+1. **Implement**: strictly per task description + specs, minimal changes.
+2. **Check the box immediately** after completion: `- [ ]` → `- [x]`. **Close-out is not a task**: `change finalize` / `change archive` are pipeline steps and MUST NOT appear in tasks.md — if one is listed (e.g. "close-out — finalize"), remove it (the close-out task gate requires every task checked).
+3. **Edit, then verify — serially**: verification MUST run after edits land on disk; MUST NOT put edits and tests/validation in the same parallel tool-call batch (the check may read stale files and report a false failure or a false pass).
+4. Task unclear, blocker hit, or specs/design contradict reality → STOP and report; don't assume.
+
+### 5) Verification and self-healing loop (after each task or batch)
+Run the project gates as appropriate:
+- Test suite: `just test` or `cargo test --all`; format/lint: `just check` or `just lint` + `just fmt`
+- 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`
+
+**Gate evidence**:
+- Close-out runs the configured `bdd.run_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.
+- 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.
+
+**On failure → self-heal (don't ask "should I continue?"):**
+1. Parse the failure cause (test / lint / format / validation).
+2. Decide if it's a hard-to-locate bug (cause unclear / intermittent flake / regression not obvious at a glance):
+   - **Not hard-to-locate** (clear lint/format/compile/validation error): apply a minimal fix (don't expand scope); re-run the minimum failure-repro command first, then all gates.
+   - **Hard-to-locate → escalate to the diagnose sub-flow**:
      1. **First build a command that reproduces the failure** (fast, deterministic, agent-runnable, and goes red on *this* bug) — one that drives the real bug path and asserts the user's exact symptom. **MUST NOT start hypothesizing before such a command exists** (staring at code and guessing is the failure this prevents).
      2. Run it, confirm red → minimize the repro (cut inputs/calls/config/data one at a time, keep only what's load-bearing).
      3. Generate **3–5 ranked hypotheses**, each falsifiable ("if X is the cause, changing Y makes the bug disappear").
      4. Verify one variable at a time; fix once the root cause is found.
-     5. If there's no correct seam for a regression test, note the architectural gap (hand off to `llman-sdd-arch-review`; when that skill is not enabled via `extra_skills`, write the gap into this change's `proposal.md` Further Notes section or `design.md`, and MUST NOT break the loop over it).
-3. Re-run the "minimum failure repro command" first, then re-run all gates.
-4. Log as one self-healing round: `Round N: failure → fix → re-run → pass/fail`.
-
-**Self-healing cap: 8 rounds**; exceeding this is a blocker: stop and output a blocker report (last failing command + output summary + what you tried).
+     5. If there's no correct seam for a regression test, note the architectural gap (hand off to `llman-sdd-arch-review`; when not enabled, write the gap into this change's `proposal.md` Further Notes section or `design.md`, and MUST NOT break the loop over it).
+3. Re-run the minimum failure-repro command first, then all gates.
+4. Log one self-healing round: `Round N: failure → fix → re-run → pass/fail`.
 
-**Human review checkpoint (after each task batch passes the gates)**: once a batch is green, before starting the next batch or producing the completion report, run `llman-sdd review`:
+**Self-healing cap: 8 rounds**; exceeding it is a blocker: stop and output a blocker report (last failing command + output summary + what you tried).
 
-- Exit code zero → continue.
-- Non-zero exit = CRITICAL findings: STOP, fix, re-run review; MUST NOT enter the next batch or emit the completion report with CRITICAL findings open.
+**Human review gate (after each task batch passes the gates)**: before starting the next batch or emitting the completion report, run `llman-sdd review`: exit code zero → continue; non-zero = CRITICAL findings → STOP, fix, re-run review; MUST NOT enter the next batch or emit the completion report with CRITICAL findings open.
 
 ### 6) Completion report
-After all tasks complete + all gates green, output a structured report (see Output Contract below).
-Then suggest running `llman-sdd-verify` for the verification phase.
-
-> 💡 Implementation done → next: `llman-sdd-verify` (verify)
+After all tasks complete + all gates green, output a structured report (see Output Contract), then suggest `llman-sdd-verify`.
 
-> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/validation-hints") }}
 

package/templates/en/skills/llman-sdd-arch-review.md

@@ -1,27 +1,21 @@
 ---
 name: "llman-sdd-arch-review"
-description: "Scan codebase for shallow modules (interface nearly equals implementation) and surface deepening candidates. Use when the user wants an architecture review, seeks module deepening opportunities, or wants to improve testability and AI-navigability."
+description: "Architecture review: scan for shallow modules (interface ≈ implementation) and surface deepening candidates to improve testability and AI-navigability."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Architecture Review
 
-Scan the codebase for architectural friction and surface **deepening opportunities** — refactors that turn shallow modules (interface nearly equals implementation) into deep ones (lots of behaviour behind a small interface). The aim is testability and AI-navigability.
-
-## Pipeline position
-
-Auxiliary tool, not part of the main pipeline (explore→propose→apply→verify→archive). Usable at any stage; commonly triggered during explore to surface improvement candidates.
-
-> 📍 Standalone optional skill; does not replace any pipeline stage.
+Scan the codebase for architectural friction and surface **deepening opportunities** — turning shallow modules (interface ≈ implementation) into deep ones (lots of behavior behind a small interface). The aim is testability and AI-navigability. Auxiliary tool, not part of the main pipeline; usable at any stage, commonly triggered during explore.
 
 ## Design vocabulary
 
-A set of words about module shape, used to articulate "where it's worth changing". MUST NOT substitute "component" / "service" / "API" / "boundary" (they are broader, less precise):
+Words about module shape; MUST NOT substitute "component" / "service" / "API" / "boundary" (broader, less precise):
 
 - **Module** — anything with an interface and an implementation (function/class/package/cross-layer slice).
 - **Interface** — everything a caller must know to use it correctly: type signature, plus invariants, ordering constraints, error modes, performance characteristics.
-- **Depth** — the amount of behaviour behind the interface. **Deep** = lots of behaviour behind a small interface; **shallow** = interface nearly as complex as the implementation (the caller saves nothing).
+- **Depth** — the amount of behavior behind the interface. **Deep** = lots of behavior behind a small interface; **shallow** = interface nearly as complex as the implementation (the caller saves nothing). This skill turns shallow into deep.
 - **Seam** — a place where you can swap the implementation without editing call sites (where the interface lives). In llman, seam = the public boundary driven by `*.feature` GWT steps.
 - **Leverage** — what callers get from depth: more capability per unit of interface learned.
 - **Locality** — what maintainers get from depth: changes/bugs/knowledge/verification concentrate in one place.
@@ -31,10 +25,10 @@ A set of words about module shape, used to articulate "where it's worth changing
 ### 1. Explore (scope first, YAGNI)
 - If the user named a direction (module/subsystem/pain point), accept it; skip inference.
 - Otherwise walk `git log --oneline` for hot spots (files/areas that keep coming up).
-- Prefer reading live `<capability>.feature` (single-track SSOT) and `design.md` (existing ADRs); MUST NOT create a `CONTEXT.md`.
+- Prefer reading `<capability>.feature` (the single source of truth) and `design.md` (existing ADRs); MUST NOT create a `CONTEXT.md`.
 - Use the Agent tool (`subagent_type=Explore`) to walk the codebase, noting friction:
   - Does understanding one concept require bouncing between many small modules?
-  - Where are modules **shallow** (interface nearly as complex as the implementation)?
+  - Where are modules **shallow** (interface ≈ implementation complexity, callers save nothing)?
   - Where are pure functions extracted only for testability, but real bugs hide in how they're called (no locality)?
   - Which parts are untested or hard to test through their current interface?
 
@@ -46,20 +40,19 @@ For each candidate:
 - **Benefits** — locality and leverage improvements; how tests get better.
 - **Recommendation strength** — `Strong` / `Worth exploring` / `Speculative`.
 
-**Deletion test**: for any suspected-shallow module, imagine deleting it — does complexity vanish (it's just a pass-through, no value) or reappear across N call sites (it's actually earning its keep)? "Reappears" is the signal you want.
+**Deletion test**: for any suspected-shallow module, imagine deleting it — does complexity vanish (it's just a pass-through) or reappear across N call sites (it's actually earning its keep)? "Reappears" is the signal you want.
 
 **ADR conflicts**: if a candidate contradicts an existing `design.md` decision, surface it only when the friction is real enough to warrant reopening, and mark it in the candidate.
 
-### 3. Grilling (after the user picks a candidate)
-Run `llman-sdd-explore`'s **grilling branch** (trigger "deep-dig") to walk the decision tree — constraints, dependencies, the deepened module's shape, what sits behind the seam, which tests survive.
+### 3. Deep-dive Q&A (after the user picks a candidate)
+Run `llman-sdd-explore`'s **deep-dive Q&A branch** (trigger "deep-dig") to walk the decision tree — constraints, dependencies, the deepened module's shape, what sits behind the seam, which tests survive.
 
-- A deepened module uses a concept not in the capability `.feature`? → update live `.feature` **only** if the change already has Branch binding and you are on the bound branch (Specs landing); otherwise STOP and route to `llman-sdd-propose` / `change start` — **never** edit live specs on the default branch.
+- The deepened module uses a concept not in the `.feature`? → update the `.feature` **only** if the change is branch-bound and you are on the bound branch; otherwise STOP and route to `llman-sdd-propose` / `change start` — **never** edit specs on the default branch.
 - User rejects the candidate with a load-bearing reason? → offer an ADR only when "hard to reverse + surprising without context + real trade-off" all hold; record in `design.md`.
 
 ## Output
-Candidate list (text; optional HTML report written to OS temp dir, not the repo) + the grilling decision record after the user picks one (write back to proposal; contract edits only via Specs landing into live `.feature`).
+Candidate list (text; optional HTML report written to the OS temp dir, not the repo) + the deep-dive decision record after the user picks one (write back to the proposal; contract edits only after landing on the bound branch into the `.feature`).
 
-> For command details run `llman-sdd <cmd> --help`; the CLI is the command reference — skills embed no command tables.
-> "Spec" here = a `.feature` file under this project's `llmanspec/specs/`; run `llman-sdd list --specs` or `llman-sdd show <capability>`.
+{{ unit("skills/cli-footer") }}
 
 {{ unit("skills/structured-protocol") }}