@llman-sdd/core 0.3.1 → 0.5.1

package/templates/en/skills/llman-sdd-specs-compact.md

@@ -1,65 +1,40 @@
 ---
 name: "llman-sdd-specs-compact"
-description: "Human-triggered maintenance tool. Compacts and deduplicates llman SDD specs after many archived changes — merges redundant requirements and scenarios while preserving all normative behavior. NOT part of the regular pipeline: only run when the user explicitly asks to compact specs."
+description: "Compact and dedupe specs: merge redundant requirements/scenarios without changing normative behavior. Manual run only, when the user explicitly asks."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Specs Compact
 
-Use this skill to compact specs without changing normative behavior.
-
-## Pipeline Position
-
-```mermaid
-flowchart LR
-    archive["llman-sdd-archive<br/>After archiving"] --> compact
-    compact["📎 llman-sdd-specs-compact<br/>Compact specs (maintenance)"]
-
-    style compact fill:#e8f4e8,stroke:#28a745,stroke-width:2px
-```
-
-> 📎 Maintenance tool, typically run after accumulating many archives. For daily development → `llman-sdd-propose` (Branch binding + Specs landing) / `llman-sdd-apply` (requires `readyToImplement`).
+Compact specs without changing normative behavior. Maintenance tool, not part of the daily pipeline; typically run after many archived changes.
 
 ## Context
-- Specs grow bloated with duplicate requirements/scenarios as changes accumulate.
-- Compaction must remain verifiable and regressible.
-- When archive history is too large, it interferes with compaction review and navigation.
+- Specs bloat with duplicate requirements/scenarios as changes accumulate; compaction must stay verifiable and regressible.
+- An oversized archive history interferes with compaction review and navigation.
 
 ## Goal
-- Identify and merge redundant requirements/scenarios.
-- Form a more compact and maintainable spec structure.
+- Merge redundant requirements/scenarios into a more compact, maintainable spec structure.
 
 ## Constraints
-- Don't delete normative behavior without explicit replacement.
-- Try to keep requirement titles stable.
-- Each retained requirement must have at least one valid scenario.
-- **Editing live `llmanspec/specs/**` requires a change**: Branch binding first (`change start` / `attach`), then commit on the bound branch (Specs landing style); **never** compact-rewrite live specs on the default branch.
+- Don't delete normative behavior without explicit replacement; keep requirement titles stable where possible; every retained requirement keeps at least one valid scenario.
+- **Editing `llmanspec/specs/**` requires a change**: bind the branch first (`change start` / `attach`), then edit and commit on the bound branch; **never** compact-rewrite specs on the default branch.
 
 ## Workflow
-1. Inventory current specs (`llman-sdd list --specs`).
-2. If archived history is large, run archive freeze first:
-   - Preview: `llman-sdd archive freeze --dry-run`
-   - Execute: `llman-sdd archive freeze --before <YYYY-MM-DD> --keep-recent <N>`
-3. Identify overlapping items across capabilities.
+1. Inventory specs (`llman-sdd list --specs`).
+2. If archived history is large, freeze first: preview `llman-sdd archive freeze --dry-run`; execute `llman-sdd archive freeze --before <YYYY-MM-DD> --keep-recent <N>`.
+3. Identify cross-capability overlap (duplicate req ids across specs: `llman-sdd project dedupe-req-ids --dry-run` reports the remap plan).
 4. Produce a compaction plan (canonical requirements + keep/merge/remove decisions + migration notes).
-5. Execute and validate (`llman-sdd validate --specs --strict --no-interactive`).
+5. Execute and validate (`llman-sdd validate --specs --strict`).
 
 ## Decision Policy
-- Prefer merging when two requirements are semantically equivalent.
-- Only extract shared spec text when reference relationships are clear.
-- When archive directory is noisy, suggest freezing first before compacting.
+- Prefer merging semantically equivalent requirements; extract shared text only when references are clear; freeze first when the archive is noisy.
 - If compaction would change external behavior, pause and ask the user first.
 
 ## Output Contract
-- Output compaction plan grouped by capability.
-- Include: keep/merge/remove decisions with rationale.
-- Include validation commands and expected results.
-
-> 💡 After maintenance, new work goes through the normal pipeline: `llman-sdd-propose` (Branch binding + Specs landing) → `llman-sdd-apply` (requires `readyToImplement`) → `llman-sdd-verify` → `llman-sdd-archive`.
+- Compaction plan grouped by capability: keep/merge/remove decisions with rationale + validation commands and expected results.
 
-> 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-validate.md

@@ -1,31 +1,27 @@
 ---
 name: "llman-sdd-validate"
-description: "Validate llmanspec changes and specs with actionable fixes."
+description: "Validate changes and specs; suggest actionable fixes."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Validate
 
-Use this skill to validate change/spec format and staleness.
+Validate change/spec format and staleness.
 
 ## Steps
-1. Validate one item: `llman-sdd validate <id>`.
-2. Validate all: `llman-sdd validate --all` (or `--changes` / `--specs`).
-3. Use `--strict` and `--no-interactive` for CI-like checks.
-4. If validation fails, summarize the errors and propose minimal, concrete fixes.
+1. Single item: `llman-sdd validate <id>`; batch: `llman-sdd validate --all` (or `--changes` / `--specs`); use `--strict` in CI/automation.
+2. On failure, summarize the errors and propose minimal, concrete fixes.
 {% if bdd_enabled %}
-5. **BDD checks (Git-native Partitioned SSOT)**:
-   - Validate live `.feature` Gherkin and `@req` / dual-write gates on the **bound branch** (Branch binding required).
-   - `.feature` is the harness authority — executable GWT lives only in live `.feature` (no solidify; no `feature_delta` / `change delta`).
-   - Change lifecycle gates: `change start` / `attach` (Branch binding), `finalize` (close-out; auto commit `archive(sdd): <id>`, `--no-commit` to skip) / `diff` (read-only). `change checkpoint` is removed (no mid-flight archive point; `change finalize` does not require a clean tree).
-   - `llman-sdd validate --specs` runs `bdd.run_command` by default.
-   - Use `list --specs --json` for `morphology` (includes `dualWriteCount`).
-   - Change JSON status fields: `stage` (draft/designed/planned/full) / `specsLanded` / `needsSpecsChange` / `readyToImplement` (`show --json`).
+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 `bdd.run_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.
+   - `list --specs --json` shows `morphology` (ruleCount / ruleEnforcedCount / rulePendingCount / acceptanceCount / featureScenarioCount).
+   - Change JSON status fields: `stage` (draft/designed/planned/full) / `specsLanded` / `needsSpecsChange` / `readyToImplement` (`show --output json`).
 {% endif %}
 
-> 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-verify.md

@@ -1,56 +1,44 @@
 ---
 name: "llman-sdd-verify"
-description: "Verify that an implemented llman SDD change matches its specs, design, and tasks. Produces a report (CRITICAL / WARNING / SUGGESTION) comparing code to artifacts. Run after apply completes. If clean, the change is ready to archive."
+description: "Verify an implemented change against its specs/design/tasks; report CRITICAL/WARNING/SUGGESTION. Run after apply; if clean, ready to archive."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Verify
 
-Use this skill to verify that the implementation matches the change's artifacts.
+Verify that the implementation matches the change's artifacts.
 
 ## Pipeline Position
 
-### Skill navigation (not the lifecycle; shows current skill only)
-
 ```mermaid
 flowchart LR
-    apply["llman-sdd-apply<br/>Implement"] --> verify
-    verify["★ llman-sdd-verify ★<br/>Verify (you are here)"]
-    verify --> archive["llman-sdd-archive<br/>Archive"]
+    apply["llman-sdd-apply"] --> verify["★ llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style verify fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 You are in the verify phase → if pass: next `llman-sdd-archive` (archive); if fail: go back to `llman-sdd-apply` (fix). This is Git-native **I (verify)**; the change should already be Specs-landed (`readyToImplement=true`).
-> 🗺️ Skill navigation ≠ Git-native lifecycle; see brief lifecycle unit at the bottom.
+> 📍 You are in verify → pass leads to `llman-sdd-archive`, failure goes back to `llman-sdd-apply`. The change should already have landed specs with `readyToImplement=true` (all gates green — the completion signal).
 
 ## Hard Constraints
 
-- **Must pass apply phase all-green first**: don't skip to verify on changes that haven't been implemented.
-- **CRITICAL issues must be fixed**: CRITICAL problems must be resolved before archive.
-- **Don't ask "should I continue?"**: run the full verification flow, output a complete report.
+- **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 `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.
+- **Don't ask "should I continue?"**: run the full verification flow and output a complete report.
 
 {{ unit("skills/stage-guard") }}
 
 ## Steps
 1. Select the change id (or ask the user to pick from `llman-sdd list --json`).
-2. Run a fast validation gate:
-   - `llman-sdd validate <id> --strict --no-interactive`
-   - **When diagnosing structural issues (Gherkin parse / `@req` linkage / dual-write / global req_id uniqueness), prefer adding `--no-check`** (skips the potentially slow `bdd.run_command` under BDD-on); run the full `--check` (full mode) only after structural gates are green. Each `FAIL <item_type>/<id>` line lists a failing item (above the Totals line).
-3. Read:
-   - Live specs on the feature branch: `llmanspec/specs/**` (`<capability>.feature`) — SSOT
-   - `proposal.md` and `design.md` if present
-   - `tasks.md` to understand what was implemented
-   - `llmanspec/changes/<id>/specs/` only if residual old docs exist — ignore; SSOT is live specs
-4. **Dual-axis review (Standards + Spec, 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) on two axes:
-   - **Spec axis**: does the implementation satisfy the `@human` rule MUST/SHALL and the `@executable` GWT?
-     - Missing/partial behaviors, wrong implementations, and scope creep in the diff not asked for by the spec.
-     - Suggest minimal fixes or artifact updates.
-   - **Standards axis**: does the code follow `AGENTS.md` coding style + the Fowler smell baseline?
-     - **Authority priority**: `AGENTS.md` documented standard > smell baseline (repo overrides); skip anything tooling already enforces.
-     - Smells are **judgement heuristics** ("possible Feature Envy"), not hard violations.
-     - Smell baseline (each "what → fix"):
+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 `bdd.run_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).
+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.
+   - **Standards axis**: does the code follow `AGENTS.md` + the smell baseline? Authority priority: `AGENTS.md` > smell baseline; skip anything tooling already enforces. Smells are **judgement heuristics** ("possible Feature Envy"), not hard violations:
 
      | Smell | Fix |
      |-------|-----|
@@ -67,29 +55,20 @@ flowchart LR
      | Middle Man (just delegates) | cut it, call direct |
      | Refused Bequest (subclass rejects most inheritance) | use composition |
    - 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-on verification (Git-native Partitioned SSOT)** — only when `config.yaml` has a `bdd:` block:
-   - Confirm the change is attached and you are on that feature branch.
-   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; runs `bdd.run_command` by default (`--no-check` to skip).
-   - Optional read-only review: `llman-sdd change diff <id>` (or `--export-patch <path>`). Diff is review/export only — never treat it as an apply step.
-   - Check: legacy `spec.toon` / `*.feature.delta.toon` absent; if present, run toon2features first (do not invent a solidify / repair hunt).
+5. **BDD verification** — only when `config.yaml` has a `bdd:` block:
+   - Confirm the change is branch-bound and you are on that branch.
+   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; when `bdd.run_command` is configured the harness runs by default (`--no-check` skips it) 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 bdd_verify_prompt %}
    - Extra requirement: {{ bdd_verify_prompt }}
 {% endif %}
-6. Produce a short report:
-   - **CRITICAL** (must fix before archive)
-   - **WARNING** (should fix)
-   - **SUGGESTION** (nice to have)
-7. **Human review checkpoint**: once the report has no CRITICAL findings and before suggesting archive, run `llman-sdd review`:
-   - Exit code zero → suggest `llman-sdd-archive` for finalize/archive.
-   - Non-zero exit = CRITICAL findings: fix via `llman-sdd-apply`, then re-run review; MUST NOT enter finalize/archive with CRITICAL findings open.
-
-> 💡 Verify pass → next: `llman-sdd-archive` (archive); CRITICAL issues → go back to `llman-sdd-apply` (fix)
+6. Produce a short report: **CRITICAL** (must fix before archive) / **WARNING** (should fix) / **SUGGESTION** (nice to have).
+7. **Human review gate**: once the report has no CRITICAL findings and before suggesting archive, run `llman-sdd review`: exit code zero → suggest `llman-sdd-archive`; non-zero = CRITICAL → fix via `llman-sdd-apply`, then re-run review; MUST NOT enter finalize/archive with CRITICAL findings open.
 
 {{ unit("skills/git-native-flow-brief") }}
 {{ unit("skills/human-readable-summary") }}
-> 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-wayfinder.md

@@ -1,27 +1,24 @@
 ---
 name: "llman-sdd-wayfinder"
-description: "Plan a huge, foggy chunk of work (more than one agent session can hold) as a shared map of decision tickets, resolving them one at a time until the way is clear. Manual trigger only; the agent must not auto-invoke."
+description: "Break huge, foggy work (beyond one agent session) into a decision map, resolving decisions one at a time. Manual trigger only."
 metadata:
   version: "{{ llman_version }}"
+disable-model-invocation: true
 ---
 
 # LLMAN SDD Wayfinder
 
-A loose, large idea has arrived — too big for a single agent session, wrapped in fog: the way from here to the **destination** isn't visible yet. This skill finds that way rather than charging at the destination.
-
-It charts the path as an llman SDD **change dependency graph** (`llman-sdd graph`): each sub-work (ticket) resolves a **decision** rather than delivering a slice, worked one at a time until the way is clear.
+A loose, large idea has arrived — too big for a single agent session, and the way from here to the **destination** isn't visible yet. This skill finds that way rather than charging ahead: it charts the path as a change dependency graph (`llman-sdd graph`), where each sub-work item (ticket) resolves a **decision** rather than delivering code, worked one at a time until the way is clear.
 
 ## Pipeline position
 
-Auxiliary tool, for **pre-planning large work** before the main pipeline. When the map clears, merge onto the main flow at `llman-sdd-propose`.
-
-> 📍 Standalone optional skill; when the map clears → `llman-sdd-propose` (collapse decisions into a buildable plan).
+Auxiliary tool for **pre-planning large work** before the main pipeline. When the map clears → `llman-sdd-propose` to collapse decisions into an implementable plan.
 
 ## Core principles
 
 - **Plan, don't do**: each ticket resolves a decision; the map is done when "the way is clear, no decisions left". The urge to just do the work is usually the signal you've reached the map's edge and should hand off.
-- **Refer by name**: in all human-readable narration, refer to a ticket by its title; MUST NOT use bare ids/numbers.
-- **One session, one ticket**: each session resolves only one ticket (research tickets excepted).
+- **Refer by name**: in human-readable narration, refer to a ticket by its title; MUST NOT use bare ids/numbers.
+- **One session, one ticket** (research tickets excepted).
 
 ## Map structure
 
@@ -34,7 +31,7 @@ The map's `proposal.md` structure:
 <what reaching the end looks like — spec/decision/change. One or two lines.>
 
 ## Notes
-<domain; skills each session should consult; standing preferences for this effort>
+<domain; skills each session should consult; standing preferences>
 
 ## Decisions so far
 <!-- index: one line per closed ticket, gist + link -->
@@ -52,36 +49,35 @@ Each ticket is a child change carrying a `wayfinder:<type>` tag (in the proposal
 
 - **Research (agent-driven)**: read docs/APIs/local resources to surface a fact a decision waits on. Delegate to `llman-sdd-research` in the background.
 - **Prototype (human-in-the-loop)**: raise fidelity with a cheap, rough runnable (throwaway terminal app or UI variant).
-- **Grilling (human-in-the-loop)**: via `llman-sdd-explore`'s grilling branch, one question at a time. **Default type**.
+- **Deep-dive Q&A (human-in-the-loop)**: via `llman-sdd-explore`'s deep-dive branch, one question at a time. **Default type**.
 - **Task (human or agent)**: manual work that must happen before a decision can be made (sign up for a service, move data so its shape is visible).
 
 ## Fog of war
 
 The map is **deliberately** incomplete. The test for ticket-vs-fog: **can you state the question precisely now** (not whether you can answer it).
 - Can state precisely → ticket (even if blocked).
-- Cannot yet state precisely → **Not yet specified** (coarser than a ticket; one fog patch may graduate into several tickets or none).
+- Cannot yet → **Not yet specified** (coarser than a ticket; one fog patch may graduate into several tickets or none).
 
 ## Steps
 
 ### Chart the map
-1. **Name the destination**: use `llman-sdd-explore`'s grilling branch to pin down what this map is finding its way to.
-2. **Breadth-first scan**: grill again, fanning out rather than deep-diving, surfacing open decisions and the first takeable steps. If **no fog surfaces** — the way is already clear, the whole effort fits one session — you don't need a map; stop and ask the user how to proceed.
+1. **Name the destination**: use the deep-dive Q&A branch to pin down what this map is finding its way to.
+2. **Breadth-first scan**: deep-dive again, fanning out rather than drilling one thread, surfacing open decisions and the first takeable steps. If **no fog surfaces** — the way is already clear, the whole effort fits one session — you don't need a map; stop and ask the user how to proceed.
 3. **Create the map** (overview change): `llman-sdd change new <map-id>`, fill Destination/Notes, leave Decisions-so-far empty, write fog into Not yet specified.
-4. **Create the tickets you can specify now** as child changes, then wire blocking edges with `llman-sdd graph` (second pass: ids needed before cross-referencing).
+4. **Create the tickets you can specify now** as child changes, then wire blocking edges with `llman-sdd graph` (ids needed before cross-referencing).
 5. Spin up `llman-sdd-research` background subagents for each research ticket.
 6. Stop — charting is one session's work; resolve nothing by hand.
 
 ### Work through the map
-1. Load the map (low-resolution view).
-2. Pick a ticket (user-named or first frontier item); claim it with Branch binding (`change start`, or `change attach` if the branch already exists). The map/ticket **planning shell** may briefly live on the default branch; if the ticket must edit live specs, do Specs landing on the bound branch.
-3. Resolve it — zoom as needed (read related ticket bodies, invoke skills the Notes block names). In doubt, use `llman-sdd-explore`'s grilling. **Do not** edit `llmanspec/specs/**` before Branch binding.
+1. Load the map (low-resolution view; don't read every ticket in full).
+2. Pick a ticket (user-named or first frontier item); claim it by binding the branch (`change start`, or `change attach` if the branch exists). Planning docs may briefly live on the default branch; if the ticket must edit specs, land them on the bound branch.
+3. Resolve it — zoom as needed (read related ticket bodies, invoke the skills the Notes block names). In doubt, use the deep-dive Q&A. **Do not** edit `llmanspec/specs/**` before binding.
 4. Record the resolution: write the answer into the ticket's proposal, close it, append a one-line gist + pointer to the map's Decisions-so-far.
-5. Add newly-surfaced tickets (create-then-wire); graduate fog that the answer has made specifiable, clearing it from Not yet specified. If the answer reveals a ticket sits beyond the destination, rule it out of scope rather than resolving it on the route.
+5. Add newly-surfaced tickets (create-then-wire); graduate fog the answer made specifiable out of Not yet specified; if the answer reveals a ticket sits beyond the destination, rule it out of scope rather than resolving it on the route.
 
 ## Output
-Map change + child decision changes' dependency graph (`llman-sdd graph`). When the way is clear, proceed to `llman-sdd-propose` (Branch binding → Specs landing through `readyToImplement=true`) to collapse decisions into an implementable plan.
+Map change + child decision changes' dependency graph (`llman-sdd graph`). When the way is clear, proceed to `llman-sdd-propose` to collapse decisions into an implementable plan.
 
-> 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") }}

package/templates/en/units/skills/cli-footer.md

@@ -0,0 +1,2 @@
+> 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>`.

package/templates/en/units/skills/git-native-flow-brief.md

@@ -1,9 +1,10 @@
-## Git-native lifecycle (brief)
+## Branch lifecycle (brief)
 
-Do not conflate **skill navigation** with the **Git-native lifecycle**. Full diagram: root `AGENTS.md` or the diagram inside `llman-sdd-propose`.
+**Skill navigation** ≠ **branch lifecycle**. Full diagram: root `AGENTS.md` or the one inside `llman-sdd-propose`.
 
 Hard rules:
-1. **First** Branch binding (`change start` / `attach`) → Full; **then** Specs landing (edit and commit `llmanspec/specs/**` on the bound branch).
-2. No live contract edits → `needs_specs_change: false`. Apply requires `readyToImplement=true`.
-3. Close-out: `change finalize` (auto commit `archive(sdd): <id>`; `--no-commit` to skip). `change checkpoint` is removed (calling it exits non-zero and points to finalize).
-4. **Do not** commit live specs on the default branch; if already attached, do not re-run `start`.
+1. **First** bind the branch (`change start` / `attach`) → full; **then** land specs (edit and commit `llmanspec/specs/**` on the bound branch).
+2. No contract edits → `needs_specs_change: false`. Enter apply when `stage=full` and the specs-landed gate passes; `readyToImplement=true` (all gates green) is the completion signal gating verify/finalize.
+3. Close-out: `change finalize` (auto commit `archive(sdd): <id>`; `--no-commit` to skip).
+4. **Do not** commit specs on the default branch; if already attached, do not re-run `start`.
+5. Worktree (optional): `change start --worktree` creates the branch in a dedicated worktree without hijacking the current checkout (`--base <branch>` records a non-default fork source); finalize runs in place when the target is held by another worktree (location annotated in output).

package/templates/en/units/skills/git-native-flow.md

@@ -1,6 +1,6 @@
-## Git-native lifecycle (full diagram)
+## Branch lifecycle (full diagram)
 
-Do not conflate two layers: the **Git-native lifecycle** (Branch binding → Specs landing → `readyToImplement`) vs **skill navigation** (explore→propose→apply→verify→archive). Specs landing is **not** a separate skill.
+Two layers, don't conflate them: the **branch lifecycle** (bind branch → land specs → `readyToImplement`) vs **skill navigation** (explore→propose→apply→verify→archive). Landing specs is **not** a separate skill.
 
 ```mermaid
 flowchart TB
@@ -10,21 +10,21 @@ flowchart TB
     B2["add tasks.md → planned"]
   end
 
-  subgraph gate_start["Branch binding"]
+  subgraph bind["Bind branch"]
     C{"Clean tree<br/>and on default branch?"}
     D["change start<br/>create sdd/&lt;id&gt; + write branch/base_branch/base_sha"]
     E["or manual checkout -b<br/>then change attach"]
   end
 
   subgraph specs_only["Only on this change branch"]
-    F["Edit live llmanspec/specs/** (.feature)"]
-    G["commit → Specs landing<br/>live merge-base...HEAD includes specs paths"]
+    F["Edit llmanspec/specs/** (.feature)"]
+    G["commit → land specs<br/>live merge-base...HEAD includes specs paths"]
   end
 
-  subgraph implement["Implement"]
+  subgraph implement["Implement & close"]
     H["apply: code per tasks<br/>may keep editing specs"]
     I["verify"]
-    J["finalize<br/>merge (squash default) → rename → auto commit archive(sdd): &lt;id&gt;<br/>specs first hit default branch"]
+    J["finalize: merge (squash default) → rename → auto commit archive(sdd): &lt;id&gt;<br/>specs first hit the target branch"]
   end
 
   A --> B1 --> B2 --> C
@@ -34,7 +34,17 @@ flowchart TB
 ```
 
 Hard rules:
-1. **First** `change start` / `attach` (Branch binding) to enter Full; **then** edit `llmanspec/specs/**` on the bound non-default branch and commit (Specs landing).
-2. For changes with no live contract edits, set frontmatter `needs_specs_change: false`. Enter apply only when `llman-sdd show <id> --json` has `readyToImplement=true` — `Full ∧` every `gateChecks` item passes (specs-landed = `specsLanded ∨ needs_specs_change=false`; ranges are live merge-bases, stored `base_sha` is audit-only).
-3. `change checkpoint` is removed (no mid-flight archive point; `change finalize` does not require a clean tree). Close-out is `llman-sdd change finalize <id>`: it auto-commits `archive(sdd): <id>` (impl diff + rename in one commit); `--no-commit` skips the auto commit for manual/CI histories. Commits on the change branch are free (segmented or finalize single-shot).
-4. **Do not** commit live specs to the default branch just to satisfy the clean-tree gate; if already attached, do not re-run `start`.
+1. **First** `change start` / `attach` to bind the branch (enter full); **then** edit `llmanspec/specs/**` on the bound non-default branch and commit (land specs).
+2. No contract edits → set frontmatter `needs_specs_change: false`. Enter apply when `stage=full` and the specs-landed gate passes (specsLanded ∨ needs_specs_change=false); `readyToImplement=true` (every gateChecks item green, incl. tasks-done) is the completion signal gating verify/finalize. Diff ranges are always live merge-bases; the stored `base_sha` is audit-only.
+3. Close-out is `llman-sdd change finalize <id>`: it auto-commits `archive(sdd): <id>` (impl diff + rename in one commit); `--no-commit` skips the auto commit. Commits on the change branch are free (segmented or finalize single-shot).
+4. **Do not** commit specs to the default branch just to satisfy the clean-tree gate; if already attached, do not re-run `start`.
+
+Worktree decision table:
+
+| Working style | Command | Criteria |
+|---|---|---|
+| Single checkout | `llman-sdd change start <id>` | On the default branch with a clean tree; switches this checkout to the new branch |
+| Keep current checkout / parallel changes | `llman-sdd change start <id> --worktree` | Branch lives in a dedicated worktree (`sdd.worktree_root` / `sdd.worktree_naming` config; default sibling of the repo root), current checkout untouched, output includes the worktree path; pair with `--base <branch>` for a non-default fork source |
+| Already on a feature branch (incl. manual wt/git-worktree) | `llman-sdd change attach <id>` | Branch already exists; `--base <branch>` records the fork source explicitly |
+
+finalize target location: when the target branch is held by another worktree, `llman-sdd change finalize <id>` / `llman-sdd change archive <id>` run the merge, rename and commit inside that worktree (output includes `executed in target worktree <path>`); a dirty holding worktree aborts with disposal options and zero writes.

package/templates/en/units/skills/human-readable-summary.md

@@ -1,10 +1,9 @@
 # Human-Readable Summary (mandatory)
 
-Every report, handoff, or gate output you produce in this workflow MUST open
-with a short human-readable summary block before any machine detail:
+Every report, handoff, or gate output MUST open with a short human-readable summary before any machine detail:
 
 - **Verdict** — one line (e.g. "all gates green" / "2 CRITICAL found").
 - **Risks** — up to three bullets, highest impact first.
 - **Decisions needed** — explicit asks, or "none".
 
-Keep it under ten lines; details belong below the fold.
+Under ten lines; details below the fold.

package/templates/en/units/skills/stage-guard.md

@@ -1,17 +1,17 @@
 ## Stage guard (`stage` / `readyToImplement`)
 
-Decide from authoritative JSON (never from vague "complete artifacts" wording):
+Decide from authoritative JSON (never from "artifacts look complete"):
 
 ```bash
-llman-sdd show <id> --json --type change
+llman-sdd show <id> --output json --type change
 ```
 
 Read: `stage`, `specsLanded`, `needsSpecsChange`, `readyToImplement`, `gateChecks` (per-item `pass` + one-line `hint` when failing).
 
 | Condition | Action |
 |-----------|--------|
-| `stage=draft` (proposal.md only) | STOP. Grow to Designed (add design.md) → Planned (add tasks.md) → Branch binding → Specs landing. Draft cannot apply/verify. If proposal+design+tasks exist but stage is still `draft`: tasks-without-design — add design.md first. **Do not** create `changes/<id>/specs/`; **do not** edit live specs on the default branch first. |
-| `stage=designed` (proposal + design) | Next: add tasks.md → `planned`. Run `change start` / `attach` (Branch binding) only after planning artifacts are complete. |
-| `stage=planned` (proposal + design + tasks) | STOP until binding: run `change start` / `attach` (Branch binding) → `full`. |
-| `stage=full` and `readyToImplement=false` | STOP. Finish Specs landing on the **bound branch** (edit `llmanspec/specs/**` and commit), or set `needs_specs_change: false`. **Do not** re-run `change start`. If specs on the bound branch were lost → checkout/recreate + `attach --force` if needed. |
-| `readyToImplement=true` | Pass apply/verify prerequisites. `changes/<id>/specs/` is expected to be **absent** — do not treat as missing. |
+| `stage=draft` (proposal.md only) | STOP. Grow: add design.md → designed, add tasks.md → planned, then bind the branch and land specs. Draft cannot apply/verify. If proposal+tasks exist but stage is still `draft` (tasks-without-design — design.md gates the stage): add design.md first. **Do not** create `changes/<id>/specs/`; **do not** edit specs on the default branch first. |
+| `stage=designed` (proposal + design) | Next: add tasks.md → `planned`. Bind (`change start` / `attach`) only after planning docs are complete. |
+| `stage=planned` (proposal + design + tasks) | STOP until bound: `change start` / `attach` → `full`. |
+| `stage=full` and `readyToImplement=false` | Read the failing `gateChecks` items. specs-landed gate failing → land specs on the **bound branch** (edit `llmanspec/specs/**` and commit), or set `needs_specs_change: false`; **do not** re-run `change start` (lost bound-branch specs → checkout/recreate + `attach --force` if needed). specs-landed gate green but tasks-done/validate/clean-tree failing → normal mid-implementation state: proceed with apply (check off tasks); do not treat it as a landing failure. |
+| `readyToImplement=true` | Completion signal: every gateChecks item green (tasks done + validate passed) — verify/finalize prerequisites met. `changes/<id>/specs/` is expected to be **absent** — do not treat as missing. |

package/templates/en/units/skills/structured-protocol.md

@@ -1,23 +1,20 @@
 ## Context
-- Check state before acting: change/spec status comes from `llman-sdd show/list/validate` output.
-- Locate relevant specs with `llman-sdd context --task --paths` before reading spec files.
+- Check state before acting: change/spec status comes from `llman-sdd show/list/validate`; locate relevant specs with `llman-sdd context --task --paths` before reading spec files.
 
 ## Goal
-- Reach one verifiable outcome for this command; report result paths and validation state.
+- Reach one verifiable outcome; report result paths and validation state.
 
 ## Constraints
-- Follow the hard rules in the skill body (not repeated here). Triage first: behavior-contract changes take the full SDD path, implementation-only changes take quick; when unsure choose full SDD.
-- Keep changes minimal; never force past a known validation failure.
+- Follow the skill body's hard rules (not repeated here). Classify first: behavior-contract changes take the full SDD path, implementation-only changes take quick; when unsure choose full SDD. Keep changes minimal; never force past a known validation failure.
 
 ## Workflow
-- Treat `llman-sdd` command output as the source of truth at every step; run `llman-sdd validate` after touching artifacts.
-- Command details: the generated command reference below, or `llman-sdd <cmd> --help`.
+- Treat `llman-sdd` command output as the source of truth at every step; run `llman-sdd validate` after touching artifacts. Command details: `llman-sdd <cmd> --help`.
 
 ## Decision Policy
 - Clarify high-impact ambiguity before proceeding; verify facts yourself, ask the user only for decisions.
 
 ## Output Contract
-- Human-readable summary first (conclusion / risks / decisions needed), machine detail after.
+- Human-readable summary first (verdict / risks / decisions needed), machine detail after.
 
 ## Ethics Governance
 - `ethics.risk_level`: low — reads/writes this repo and `llmanspec/` only, no outward-facing actions; a skill body may override.

package/templates/en/units/skills/validation-hints.md

@@ -1,7 +1,6 @@
 Validation fixes (single-track feature-as-spec):
 
-1) Missing header comments (`missing `# capability:`` header comment`):
-Every capability `.feature` (`llmanspec/specs/<capability>.feature` or `llmanspec/specs/<capability>/<capability>.feature`) MUST start with:
+1) Missing header comments (`missing # capability: header comment`): every capability `.feature` (`llmanspec/specs/<capability>.feature` or the same-named main file in a directory) MUST start with:
 ```
 # language: zh-CN
 # capability: <capability>
@@ -9,16 +8,13 @@ Every capability `.feature` (`llmanspec/specs/<capability>.feature` or `llmanspe
 # scope: src/
 ```
 
-2) Tag grammar (`@human constraint scenario must carry an @req:<req_id> tag` / `orphan acceptance scenario`):
-- Rules: `@req:<id> @human` — statement in the scenario description (MUST/SHALL required).
-- Acceptance: `@executable` + at least one `@req:<id>` linking a rule.
-Never combine `@human` with `@executable`. (`@manual` was removed in 0.3.0 — drop it; `@human` already carries the human-judgement semantics.)
+2) Native layout (`rule must carry an @req:<req_id> tag on the rule header`):
+- One canonical style: `@req:<id>` on the `规则:` block header, nested `场景:` (Given/When/Then) as executable examples — the default preferred shape.
+- Only keep a `规则:` block with no nested scenario (bare rule) for requirements that cannot be expressed programmatically or are not yet converted: free-text description, no MUST/SHALL enforcement; validate reports an aggregate count, the review `pending` signal measures it, specs-compact keeps reducing it.
+- Legacy tags `@executable`/`@rule`/`@human`/`@manual` are gone and parse inert; when old files hit structural problems run `llman-sdd spec migrate-native`.
+- Top-level `场景:` outside any `规则:` are plain feature-level examples: no rule handle, no warning, not part of rule accounting (native Gherkin).
 
-3) Legacy `spec.toon` present (`legacy spec.toon found ... run ... toon2features`):
-Run `llman-sdd project migrate --kind toon2features --yes`, review the diff, commit.
-
-Git-native guardrail:
-- **Branch binding** → **Specs landing**: first `change start` / `attach`, then edit live `.feature` files on the bound non-default branch and commit.
-- Locked rules (report-only): editing/removing an existing `@human` scenario yields a WARNING and never blocks validate / change finalize / change diff; the report names the edited rule by `@req:<id>`. Control points: git branch diff plus `llman-sdd review` / `change diff` output. Legacy lock-ack metadata (frontmatter `rules_touched` / `agent_acked`, the `@agent` tag, the `--yes` ack semantics) is fully removed — no aliases, no compat layer (locked rules are report-only: a warning, never a block).
-- Apply requires `readyToImplement=true` (or `needs_specs_change: false`). Close-out prefers `change finalize`.
-- Do not use `change delta` / solidify / `*.feature.delta.toon`.
+Branch guardrail:
+- First `change start` / `attach` to bind the branch, then edit `.feature` on the bound non-default branch and commit (land specs).
+- Locked rules (report-only): editing/removing an existing `规则:` block yields a WARNING and never blocks validate / finalize / `change diff`; the report names the rule by `@req:<id>`. Control points: git branch diff plus `llman-sdd review` / `change diff`. Legacy lock-ack metadata (frontmatter `rules_touched` / `agent_acked`, the `@agent` tag, the `--yes` ack semantics) is fully removed — no aliases, no compat layer.
+- Enter apply when `stage=full` and the specs-landed gate passes (specsLanded ∨ `needs_specs_change: false`); verify/finalize require `readyToImplement=true` (completion signal). Close-out prefers `change finalize`.

package/templates/en/units/spec/feature-contract.md

@@ -1,7 +1,8 @@
-## Canonical Single-Track Feature Contract
+## Canonical Single-Track Feature Contract (native Gherkin layout)
 
-Each capability is ONE Gherkin file: flat `llmanspec/specs/<capability>.feature` (default) or directory `llmanspec/specs/<capability>/` with a same-named main file — pick one layout, both at once is a conflict.
-It is the only spec artifact — there is no `spec.toon`.
+Each capability is ONE Gherkin file: flat `llmanspec/specs/<capability>.feature` (default) or directory `llmanspec/specs/<capability>/` with a same-named main file — pick one layout; both at once is a conflict. It is the only spec artifact (there is no `spec.toon`).
+
+The format is the **native Gherkin hierarchy**: `功能:` → `规则:` (the requirement: title + free-form description + `@req:<id>` handle) → nested `场景:` (executable GWT examples). This is the only canonical style; legacy tags (`@executable`/`@rule`/`@human`/`@manual`) are gone — migrate old files with `spec migrate-native`.
 
 ```gherkin
 # language: zh-CN
@@ -11,19 +12,29 @@ It is the only spec artifact — there is no `spec.toon`.
 
 功能: sample
 
-  @req:r1 @human
-  场景: Rule title
-    System MUST do something.
+  @req:r1
+  规则: A requirement point
+    Free-text requirement (no MUST/SHALL enforcement); wrap long text across
+    lines for human/agent readability. A description line must not begin with
+    a step keyword (would be parsed as a step).
+
+    场景: An executable example
+      假如 a precondition
+      当 a trigger happens
+      那么 the outcome is observed
 
-  @req:r1 @executable
-  场景: happy
-    假如 a precondition
-    当 a trigger happens
-    那么 the outcome is observed
+  @req:r2
+  规则: Not-yet-converted requirement (bare rule — counted by the aggregate nudges)
+    This description is the only carrier of the requirement today. Rules with
+    no nested scenario are counted as bare; specs-compact keeps driving them
+    down or converting them.
 ```
 
-- Header comments (`# capability:` / `# purpose:` / `# scope:`) are REQUIRED; `scope` drives staleness.
-- `@human` scenarios are human-owned constraints; their description carries the normative statement verbatim. Editing/removing them yields a WARNING only (report-only, never blocks a gate) — compare via git branch diff; the legacy lock-ack metadata `rules_touched` / `agent_acked` / `@agent` is removed with no aliases and no compat layer (locked rules are report-only: a warning, never a block).
-- `@executable` scenarios are runner-bound acceptance; they link rules via `@req:<req_id>`.
-- Coverage tiers: enforced (has acceptance) / pending. `list --specs` reports both.
-- Scenarios MUST stay top-level: `Rule:` blocks are rejected (the runner skips them silently).
+- Header comments (`# capability:` / `# purpose:` / `# scope:`) are REQUIRED; `scope` drives staleness checks.
+- **Executable scenarios preferred**: express behavior as nested `场景:` (`Given/When/Then`) bound to BDD step code and executed by the runner — the default. Only use a `规则:` block without executable scenarios for requirements that cannot be expressed programmatically (abstract goals, architecture decisions, governance/human judgment) or are not yet converted; record the rationale in proposal/design.
+- `@req:<id>` lives on the `规则:` block header: the global unique requirement handle (shared by resolve-req/next-req-id/citation). Missing or duplicate ids are validate ERRORs.
+- Rule description is free text: no MUST/SHALL enforcement; wrap long text across lines for reviewability, with no `- ` list marker (it would enter the description verbatim).
+- Top-level `场景:` outside any `规则:` are plain feature-level examples (native Gherkin allows them; no rule handle, no warning, not part of rule accounting); rules with no nested scenario are bare rules (aggregate INFO via `--include-info`; the review `pending` signal measures them).
+- Editing/removing an existing `规则:` block yields a WARNING only (report-only, never blocks a gate) — compare via git branch diff; the legacy lock-ack metadata `rules_touched` / `agent_acked` / `@agent` is removed with no aliases and no compat layer.
+- Coverage tiers: enforced (has nested scenarios) / pending (bare) — `list --specs` reports both.
+- `规则:` blocks are containers: nested `场景:` are executed by the runner; two-space indent tiers (`规则:` 2, nested `场景:` 4, steps 6).