@llman-sdd/core 0.3.1 → 0.5.1

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

@@ -1,78 +1,64 @@
 ---
 name: "llman-sdd-explore"
-description: "Enter llman SDD explore mode when the user wants to investigate, understand requirements, or think through a problem before implementing. Prohibits code writing. Use this when intent is unclear or the user wants analysis before action."
+description: "Explore mode: investigate, clarify requirements, think through problems before acting. No code writing. Use when intent is unclear or analysis comes first."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Explore
 
-Use this skill when the user wants to think through ideas, investigate problems, or clarify requirements **before** starting implementation.
+Use this skill to think through ideas, investigate problems, or clarify requirements **before** implementation.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.**
+**Explore mode is for thinking, not implementing:**
 - You MAY read files, search code, and investigate the codebase.
-- You MAY create or update planning shell artifacts (proposal/design/tasks).
-- Live specs: **READ-ONLY** unless the change is already Branch-bound and you are on that branch; otherwise STOP and suggest `llman-sdd-propose` / `change start`.
-- You MUST NOT write application code or implement features in explore mode.
+- You MAY create or update planning docs (proposal/design/tasks).
+- `llmanspec/specs/**` is **READ-ONLY** — unless the change is already bound to a branch and you are on it; otherwise STOP and suggest `llman-sdd-propose` / `change start`.
+- You MUST NOT write application code.
 
 ## Pipeline Position
 
 {{ unit("skills/git-native-flow-brief") }}
 
-### Skill navigation (not the lifecycle; shows current skill only)
-
 ```mermaid
 flowchart LR
-    explore["★ llman-sdd-explore ★<br/>Explore (you are here)"]
-    explore --> propose["llman-sdd-propose<br/>Propose (Branch binding + Specs landing)"]
-    propose --> apply["llman-sdd-apply<br/>Implement"]
-    apply --> verify["llman-sdd-verify<br/>Verify"]
-    verify --> archive["llman-sdd-archive<br/>Archive"]
+    explore["★ llman-sdd-explore"] --> propose["llman-sdd-propose"]
+    propose --> apply["llman-sdd-apply"]
+    apply --> verify["llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style explore fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 You are in the explore phase (thinking only) → standard path next: `llman-sdd-propose` (propose)
-> 📎 For small changes (no behavioral contract changes), go directly to `llman-sdd-quick` (quick path)
-> 🗺️ Skill navigation ≠ Git-native lifecycle
+> 📍 You are in explore → next is usually `llman-sdd-propose`; small changes (no contract edits) go via `llman-sdd-quick`.
 
 ## Stance
-- Curious, not prescriptive
-- Grounded in the actual codebase
-- Visual when helpful (ASCII diagrams)
-- Willing to hold multiple options and tradeoffs
+- Curious, not prescriptive; grounded in the actual codebase.
+- Visual when helpful (ASCII diagrams); hold multiple options and tradeoffs.
 
 ## Suggested moves
-1. Use `llman-sdd context --task "<task>" --paths "<files>"` to quickly locate relevant specs.
-   - Read the `direct` spec files (these are the contracts you must understand).
-   - If context is unavailable, rebuild with `llman-sdd index rebuild` (default `pageindex`, no model needed) and retry.
+1. Use `llman-sdd context --task "<task>" --paths "<files>"` to locate relevant specs; read the full text of the specs in its `direct` list (these are the contracts you must understand).
+   - Context unavailable → run `llman-sdd index check` first: stale/missing → `llman-sdd index rebuild` (default `pageindex`, no model needed) 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. Clarify the goal and constraints (ask 1–3 questions).
-3. **Grilling branch (optional, only when the user explicitly triggers)**: triggers on "deep-dig" / "grill" / "one at a time" / "nail it down". Walks the decision tree one question at a time:
-   - **Ask one question at a time**, with your recommended answer, waiting for feedback before the next.
-   - **Facts vs decisions**: look up anything verifiable by reading the capability `.feature`/code/running commands yourself — **don't ask** the user; only **decisions** (tradeoffs, preferences, scope boundaries) go to the user.
-   - **Terminology sharpening**: when a term conflicts or is fuzzy, call it out immediately ("your spec defines 'X' as A, but you just said B — which is it?"); on resolution: if the change already has Branch binding and you are on the bound branch, update live `.feature` (Specs landing); otherwise record only in `proposal.md` — **never** edit live specs on the default branch. MUST NOT create a `CONTEXT.md` glossary as a second authority.
-   - **Write decisions back**: resolved decisions go into the change's `proposal.md` "Open Questions" section (planning shell; OK briefly on the default branch).
-   - **Completion criterion**: every pending decision is resolved or explicitly deferred. When not triggered, the default (ask 1–3 questions) behavior is unchanged.
+3. **Deep-dive Q&A branch (optional, only on explicit user trigger)**: triggers on "deep-dig" / "grill" / "one at a time" / "nail it down". Walk the decision tree one question at a time:
+   - Ask one question at a time, with your recommended answer; wait for feedback before the next.
+   - Facts vs decisions: verify anything checkable by reading the `.feature`/code/running commands yourself — **don't ask** the user; only decisions (tradeoffs, preferences, scope boundaries) go to the user.
+   - Terminology sharpening: when a term conflicts or is fuzzy, call it out immediately ("your spec defines 'X' as A, but you just said B — which is it?"); on resolution: if the change is branch-bound and you are on the bound branch, update the `.feature`; otherwise record only in `proposal.md` — never edit specs on the default branch. MUST NOT create a `CONTEXT.md` glossary as a second authority.
+   - 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, prefer `llman-sdd validate <spec> --strict --no-check` (fast mode, skips the potentially slow `bdd.run_command`); resolve structural gates first (Gherkin / `@req` linkage / dual-write / req_id uniqueness), then run full mode (`--check` or `cargo test --features bdd`). The `FAIL <item_type>/<id>` lines in the output pin down each failing item.
+   - When diagnosing validation errors, run `llman-sdd validate <spec> --strict` first for the structural gates (Gherkin / `@req` linkage / dual-write / req_id uniqueness); when `bdd.run_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.
 5. Explore options and tradeoffs (2–3 options).
-6. Assess change scale (triage) to determine if full SDD is needed.
+6. Assess change scale to determine if full SDD is needed.
 7. When something crystallizes, offer to capture it (don't auto-write):
-   - Scope / design / work items → planning shell (`proposal.md` / `design.md` / `tasks.md`)
-   - Constraints / executable harness → **suggest** live `llmanspec/specs/**` (one `.feature` per capability); actual edits require Branch binding then Specs landing. If not bound yet in explore, record only in proposal — do not edit live specs.
-
-> Git-native: first `change start`/`attach` (Branch binding) to enter Full, then edit live `.feature` on the bound branch (Specs landing); no `change delta` / solidify / feature_delta.
+   - Scope / design / work items → planning docs (`proposal.md` / `design.md` / `tasks.md`)
+   - Constraints / executable harness → **suggest** `llmanspec/specs/**`; actual edits require a bound branch. If not bound yet, record only in proposal.
 
 ## Exiting explore mode
-When the user is ready to implement, choose based on change scale:
-- Behavioral contract change → `llman-sdd-propose` (create proposal artifacts)
-- Small change / no contract change → `llman-sdd-quick` (quick path)
-- `readyToImplement=true` → `llman-sdd-apply` (implement tasks)
+- Behavioral contract change → `llman-sdd-propose`
+- Small change / no contract change → `llman-sdd-quick`
+- change already landed specs (`stage=full`, specs-landed gate green) → `llman-sdd-apply`
 If the user asks you to implement while in explore mode, STOP and remind them to exit explore mode first.
 
-> 💡 Explore done → next: `llman-sdd-propose` (propose) or `llman-sdd-quick` (quick path)
-
-> 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/skills/llman-sdd-ff.md

@@ -1,38 +1,33 @@
 ---
 name: "llman-sdd-ff"
-description: "Fast-forward: create the planning shell then Branch binding + Specs landing in one pass. Never author under changes/<id>/specs/."
+description: "Fast-forward the propose path in one pass: planning docs → bind branch → land specs."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Fast-Forward (FF)
 
-Run the propose-equivalent path quickly: planning shell → Branch binding → Specs landing (through `readyToImplement=true`). This is **not** the old `changes/<id>/specs/` delta model.
+Run the propose-equivalent path quickly: planning docs → bind branch → land specs (through the specs-landed gate). This is **not** the old `changes/<id>/specs/` delta model.
 
 ## Hard constraints
 
-- **Planning shell** only under `llmanspec/changes/<id>/` (proposal/design/tasks).
-- Live contracts only under bound-branch `llmanspec/specs/**` (Specs landing).
-- **Do not** create `llmanspec/changes/<id>/specs/` or `*.feature.delta.toon`.
-- Enter apply only when `readyToImplement=true`.
+- Planning docs only under `llmanspec/changes/<id>/` (proposal/design/tasks); specs only under bound-branch `llmanspec/specs/**`.
+- **Do not** create `llmanspec/changes/<id>/specs/`.
+- Enter apply when `stage=full` and the specs-landed gate passes (or `needs_specs_change: false`); verify/finalize require `readyToImplement=true`.
 
 ## Steps
 
-1. Ask the user for a short description, change id (or derive), impacted capability, and confirm the final id.
+1. Take a one-line description; derive the change id when not supplied and announce it (non-blocking, same rule as propose); identify the impacted capability.
 2. Ensure `llman-sdd init` has been run (`llmanspec/` exists).
 3. If `llmanspec/changes/<id>/` exists: ask fill-missing vs new id; do not overwrite without confirmation.
-4. Create the **planning shell** (OK briefly on the default branch):
-   - `llman-sdd change new <id>` (or hand-write) → flesh out `proposal.md`
-   - `design.md` (if needed)
-   - `tasks.md`
-5. **Branch binding**: `llman-sdd change start <id>` (clean tree on default branch) or create a branch then `change attach <id>`.
-6. **Specs landing**: on the bound branch, edit live `llmanspec/specs/<capability>.feature` (flat, or directory main file) and commit; or set `needs_specs_change: false` when there is no contract edit.
-7. Validate: `llman-sdd validate <id> --strict --no-interactive`.
-8. Confirm `readyToImplement=true` via `llman-sdd show <id> --json`, then suggest `llman-sdd-apply` (do not suggest apply before ready).
+4. Create the planning docs (OK briefly on the default branch): `llman-sdd change new <id>` (or hand-write) → flesh out `proposal.md` → `design.md` (if needed) → `tasks.md`.
+5. **Bind the branch**: `llman-sdd change start <id>` (clean tree on the default branch) or create a branch then `change attach <id>`.
+6. **Land specs**: on the bound branch, edit `llmanspec/specs/<capability>.feature` (flat, or directory main file) and commit; or set `needs_specs_change: false` when there is no contract edit.
+7. Validate: `llman-sdd validate <id> --strict`.
+8. Confirm the specs-landed gate is green via `llman-sdd show <id> --output json` (`specsLanded` / `needsSpecsChange`), then suggest `llman-sdd-apply` (do not suggest apply before landing).
 
 {{ unit("skills/git-native-flow-brief") }}
-> 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") }}
 
 {{ unit("skills/ethics-governance") }}

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

@@ -1,30 +1,17 @@
 ---
 name: "llman-sdd-graph"
-description: "Visualize llman SDD change dependency relationships as a mermaid graph. Use to understand blocking and depends_on relationships for planning or inspection. Auxiliary tool — not part of the main implementation pipeline."
+description: "Visualize change dependencies (depends_on/blocks) as a mermaid graph. Auxiliary tool, usable at any stage."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Dependency Graph
 
-Use this skill to visualize dependencies between changes.
-
-## Pipeline Position
-
-```mermaid
-flowchart LR
-    pipeline["Main pipeline:<br/>propose → apply → verify → archive"]
-    graph["📎 llman-sdd-graph<br/>Dependency visualization (utility)"]
-    graph -.->|available at any stage| pipeline
-
-    style graph fill:#e8f4e8,stroke:#28a745,stroke-width:2px
-```
-
-> 📎 Utility tool, available at any pipeline stage. To propose → `llman-sdd-propose`. To implement → `llman-sdd-apply` only when `readyToImplement=true`.
+Visualize dependencies between changes. Auxiliary tool, not part of the main pipeline (propose → apply → verify → archive); usable at any stage.
 
 ## Usage
 
-**Focus view (seed mode):** Show a specific change and its relationship neighborhood.
+**Focus view (seed mode)** — a specific change and its neighborhood:
 
 ```bash
 llman-sdd graph <change-id>              # the change + direct relationships (depth 1)
@@ -32,27 +19,28 @@ llman-sdd graph <change-id> --depth 3    # recurse 3 levels
 llman-sdd graph <change-id> --depth 0    # just the change itself
 ```
 
-Seed mode traverses three directions: upstream (depends_on), downstream (depended by), and blocks, automatically discovering active and archived changes.
+Traverses three directions: upstream (depends_on), downstream (depended by), and blocks; auto-discovers active and archived changes.
 
-**Global view (scope mode):** Show all changes by scope.
+**Global view (scope mode)** — scope nodes are roots expanded one level along `depends_on` (depth 1, default; avoids unbounded dependency chains); `--depth` constrains this mode too:
 
 ```bash
-llman-sdd graph                          # all active changes (default)
-llman-sdd graph --scope archived         # all archived (completed) changes
-llman-sdd graph --scope all              # everything
+llman-sdd graph                          # active changes + direct deps (depth 1 default)
+llman-sdd graph --scope archived         # archived + direct deps
+llman-sdd graph --scope all              # everything + direct deps
+llman-sdd graph --depth 0                # scope nodes only (no dependency targets)
+llman-sdd graph --depth 3                # recurse 3 levels along dependency chains
 ```
 
 ## Output
 
-- Output is a mermaid flowchart to stdout, pipeable to a file or renderer:
+- Mermaid flowchart to stdout, pipeable to a file or renderer:
   ```
   llman-sdd graph c50 > deps.mmd
   llman-sdd graph c50 --depth 2 | mmdc -i - -o deps.png
   ```
-- Archived (completed) changes are shown with "✓ done" suffix and green highlight.
-- When the graph contains disconnected groups, each group renders as an independent subgraph labeled "Active", "Done", or "Mixed".
+- Archived changes show a "✓ done" suffix and green highlight; disconnected groups render as independent subgraphs labeled "Active" / "Done" / "Mixed".
 
-## Proposal frontmatter format
+## Declaring dependencies (proposal frontmatter)
 
 ```yaml
 ---
@@ -61,14 +49,8 @@ depends_on:
 blocks:
   - blocked-change-id
 ---
-
-## Why
-...
 ```
 
-> 💡 This is just a utility — main flow: `llman-sdd-propose` (Branch binding + Specs landing) → `llman-sdd-apply` (requires `readyToImplement`) → `llman-sdd-verify` → `llman-sdd-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") }}
 
 {{ unit("skills/ethics-governance") }}

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

@@ -1,120 +1,105 @@
 ---
 name: "llman-sdd-propose"
-description: "Create an llman SDD change proposal with planning artifacts (proposal/tasks; `change start`/`attach` first, then edit live specs/features on the bound branch). Use for MUST/SHALL behavioral contract changes."
+description: "Create a proposal for MUST/SHALL behavioral contract changes (proposal/tasks → bind branch → land specs). Small changes → quick; ideas → draft."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Propose
 
-Create a new change with planning artifacts (proposal + tasks; design optional), **first** `change start` (or `attach`) for Branch binding, **then** edit live `llmanspec/specs/<capability>.feature` (flat, or directory main file) on the bound branch (Specs landing), validate, and suggest next actions.
+Create a new change with planning docs (proposal + tasks; design optional): **first** `change start` (or `attach`) to bind the branch, **then** edit `llmanspec/specs/<capability>.feature` (flat, or directory main file) on the bound branch to land specs, validate, and suggest next steps.
 
 ## Pipeline Position
 
 {{ unit("skills/git-native-flow") }}
 {{ unit("skills/human-readable-summary") }}
 
-### Skill navigation (not the lifecycle; shows current skill only)
-
 ```mermaid
 flowchart LR
-    explore["llman-sdd-explore<br/>Explore"] --> propose
-    propose["★ llman-sdd-propose ★<br/>Propose (Branch binding + Specs landing)"]
-    propose --> apply["llman-sdd-apply<br/>Implement"]
-    apply --> verify["llman-sdd-verify<br/>Verify"]
-    verify --> archive["llman-sdd-archive<br/>Archive"]
+    explore["llman-sdd-explore"] --> propose["★ llman-sdd-propose"]
+    propose --> apply["llman-sdd-apply"]
+    apply --> verify["llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style propose fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 You are in propose: the Git-native path above is **planning shell (draft → designed → planned) → Branch binding → Specs landing** (until `readyToImplement=true`) → next: `llman-sdd-apply`
-> 📎 For small changes (no behavioral contract changes), use `llman-sdd-quick` (quick path)
+> 📍 You are in propose: planning docs (draft → designed → planned) → bind branch → land specs (through the specs-landed gate) → next `llman-sdd-apply`. Small changes go via `llman-sdd-quick`.
 
 ## Hard Constraints
 
-- **Non-blocking change id**: if the user supplied an id, use it; otherwise derive a valid kebab-case id from the task description (verb prefix, passes the CLI id check, follows the naming convention declared in `llmanspec/AGENTS.md`), announce the chosen id and how to override, and continue — MUST NOT wait for confirmation (ids are cheap to change before Branch binding). Only route to `llman-sdd-draft` when the user wants to capture an idea (draft, no id).
-- **Live specs are SSOT**: edit `llmanspec/specs/**` only **after** Branch binding, on the **bound non-default branch** (Specs landing). **Do not** edit live specs on the default branch; **do not** author under `changes/<id>/specs/` or use `change delta` (removed). The planning shell may briefly live on the default branch.
+- **Non-blocking change id**: if the user supplied an id, use it; otherwise derive a valid kebab-case id from the task description (verb prefix, passes the CLI id check, follows the naming convention in `llmanspec/AGENTS.md`), announce the chosen id and how to override, and continue — MUST NOT wait for confirmation (ids are cheap to change before binding). Route to `llman-sdd-draft` only when the user wants to capture an idea (no id).
+- **Specs are the single source of truth**: edit `llmanspec/specs/**` only **after** binding, on the **bound non-default branch**. **Do not** edit specs on the default branch. Planning docs may briefly live on the default branch.
 - **Don't ask "should I continue?"**: execute the full propose phase in one pass, generate artifacts and validate.
 {% if extra_skill_continue %}
-- **If change already exists**: STOP. If `readyToImplement=true`, suggest `llman-sdd-apply`; otherwise use `llman-sdd-continue` to finish Branch binding / Specs landing, or fill the planning shell.
+- **If the change already exists**: STOP. If the specs-landed gate is green, suggest `llman-sdd-apply`; otherwise use `llman-sdd-continue` to finish binding / landing specs or the planning docs.
 {% else %}
-- **If change already exists**: STOP. If `readyToImplement=true`, suggest `llman-sdd-apply`; otherwise finish the planning shell / Branch binding / Specs landing (edit `llmanspec/changes/<id>/`, or enable `extra_skills: [llman-sdd-continue]`).
+- **If the change already exists**: STOP. If the specs-landed gate is green, suggest `llman-sdd-apply`; otherwise finish the planning docs / binding / landing specs (edit `llmanspec/changes/<id>/`, or enable `extra_skills: [llman-sdd-continue]`).
 {% endif %}
-- **Frontmatter has a fixed schema**: when fleshing out `proposal.md`, only the allowed fields in `llmanspec/AGENTS.md` "Change Proposal Frontmatter SSOT" are accepted (including `depends_on`, `blocks`, `branch`, `base_sha`, `needs_specs_change`). `status`/`title`/`priority`/`author` etc. are rejected by `llman-sdd validate` as ERROR; lifecycle stage is inferred (query via `llman-sdd show`/`list`), never stored in frontmatter. Do not re-declare frontmatter fields in the prose body; the body H1 is a human-readable title, not a repeat of the change id.
+- **Frontmatter has a fixed schema**: `proposal.md` accepts only the allowed fields in `llmanspec/AGENTS.md` "Change Proposal Frontmatter SSOT" (`depends_on`, `blocks`, `branch`, `base_sha`, `needs_specs_change`, etc.); `status`/`title`/`priority`/`author` are rejected by `llman-sdd validate` as ERROR. Lifecycle stage is inferred (query via `llman-sdd show`/`list`), never stored in frontmatter. Do not re-declare frontmatter fields in the prose body; the H1 is a human-readable title, not a repeat of the change id.
 
 ## Quick-capture routing
 
-If the user just wants to **capture an idea** (e.g. "draft a proposal", "note down X", "remember to do Y later") without full planning, route them to the `llman-sdd-draft` skill — it creates a `proposal.md`-only draft shell via `change new --from` (no id asked, no tasks/specs/attach). Full propose (triage + tasks → `change start`/`attach` → Specs landing) starts here.
+If the user just wants to **capture an idea** ("draft a proposal", "note down X", "remember Y later") → `llman-sdd-draft`: it creates a `proposal.md`-only draft via `change new --from` (no id asked, no tasks/specs/attach). Full propose starts here.
 
 ## Steps
 
 ### 0) Preflight
 - Read `llmanspec/config.yaml` for project context, rules, locale.
-- `llman-sdd validate --all --strict --no-interactive`: ensure current artifacts are clean.
-  - If pre-existing errors, stop and report (stacking new changes on dirty artifacts causes cascading errors).
-- **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`).
+- `llman-sdd validate --all --strict` to ensure current artifacts are clean; on pre-existing errors, STOP and report (stacking a new change on dirty artifacts causes cascading errors).
+- **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) Assess change scale (triage)
+### 1) Assess change scale
 1. Classify:
-   - **Behavioral contract change** (modify MUST/SHALL, change external behavior) → full SDD workflow
-   - **Implementation change** (refactor, typo, perf) → quick path via `llman-sdd-quick`
-   - **Meta-spec change** (SDD templates/process) → full SDD workflow
+   - **Behavioral contract change** (modify MUST/SHALL, change external behavior) → full SDD
+   - **Implementation change** (refactor, typo, perf) → `llman-sdd-quick`
+   - **Meta-spec change** (SDD templates/process) → full SDD
    - When uncertain, choose full SDD (conservative).
 2. Use `llman-sdd context --task "<goal>" --paths "<scope>"` to find relevant specs.
-   - If context unavailable, rebuild with `llman-sdd index rebuild` (default `pageindex`, no model needed) and continue.
-3. Gather input:
-   - A short description of the change
-   - A change id (user-supplied if given; otherwise derive it with the non-blocking rule above and announce it)
-   - The impacted capability/capabilities (to name `specs/<capability>`)
+   - Context unavailable → run `llman-sdd index check` first: stale/missing → `llman-sdd index rebuild` (default `pageindex`, no model needed) 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.
+3. Gather input: a short change description; a change id (user-supplied, else derive per the non-blocking rule and announce); the impacted capability (to name `specs/<capability>`).
 
-### 2) Ensure project is initialized
-   - `llmanspec/` must exist; if missing, tell the user to run `llman-sdd init`, then STOP.
+### 2) Ensure the project is initialized
+- `llmanspec/` must exist; if missing, tell the user to run `llman-sdd init`, then STOP.
 
-### 3) Create change directory and artifacts
-   - Prefer `llman-sdd change new <change-id>` for the draft `proposal.md` shell (or create `llmanspec/changes/<change-id>/` manually).
+### 3) Create the change directory and artifacts
+- Prefer `llman-sdd change new <change-id>` for the `proposal.md` draft shell (or create `llmanspec/changes/<change-id>/` manually).
 {% if extra_skill_continue %}
-   - If the change already exists, STOP and suggest `llman-sdd-continue`.
+- If the change already exists, STOP and suggest `llman-sdd-continue`.
 {% else %}
-   - If the change already exists, STOP and suggest filling missing artifacts or `llman-sdd-apply` (optionally enable continue via `extra_skills`).
+- If the change already exists, STOP and suggest filling missing artifacts or `llman-sdd-apply` (optionally enable continue via `extra_skills`).
 {% endif %}
-   - Flesh out `proposal.md` (Why / What Changes / Capabilities / Impact)
-   - `design.md` only when tradeoffs/migrations matter
-   - **Confirm seams before writing tasks.md**: list the seams to be tested and confirm with the user. A seam = the public boundary driven by `*.feature` GWT steps (CLI subprocess or public interface) — MUST reuse existing harness seams, MUST NOT invent seams detached from `.feature`. Without `.feature`, seam = the CLI subcommand or public function boundary under test.
-   - `tasks.md`: split into **vertical slices** (each task cuts a narrow but complete path through schema→API→UI→tests, independently verifiable), with `[blocked-by: <task-id>]` dependency markers. **Wide-refactor exception** (one mechanical change sweeping the codebase, single edit breaks many call sites): sequence as expand-contract (add new beside old → migrate call sites in batches → delete old), don't force into a vertical slice.
-   - **First** `llman-sdd change start <change-id>` (recommended; clean tree on the default branch) or manually create a branch then `change attach <change-id>` to reach Full (bound).
-   - **Then** edit live `llmanspec/specs/<capability>.feature` (flat, or directory `llmanspec/specs/<capability>/` main file) on the bound non-default branch and commit (Specs landing). **Do not** edit live specs before start; **do not** commit live specs to the default branch just to satisfy the clean-tree gate. If already attached, do not re-run `start` (recover lost specs by checkout/recreate + `attach --force` if needed).
-   - 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`.
-   - **Breaking contract changes** (removed/renamed fields, commands, tags, or stage values) MUST plan the upgrade path: `migrations/v<from>-v<to>/` with README prompt + one-shot script (ship the upgrade dir + one-shot script in the same repo) — include it in the proposal's What Changes.
+- Flesh out `proposal.md` (Why / What Changes / Capabilities / Impact); write `design.md` only when tradeoffs/migrations matter.
+- **Confirm seams before writing tasks.md**: list the seams to be tested and confirm with the user. A seam = the public boundary driven by `*.feature` GWT steps (CLI subprocess or public interface) — MUST reuse existing harness seams, MUST NOT invent seams detached from `.feature`; without `.feature`, the seam is the CLI subcommand or public function boundary under test.
+- `tasks.md`: split into **vertical slices** (each task cuts a narrow but complete path through schema→API→UI→tests, independently verifiable), with `[blocked-by: <task-id>]` dependency markers. **Wide-refactor exception** (one mechanical change sweeping the codebase, a single edit breaking many call sites): sequence as expand-contract (add new beside old → migrate call sites in batches → delete old); don't force vertical slices. **tasks.md lists implementation and verification tasks only**: close-out (`change finalize` / `change archive`) is a pipeline step and MUST NOT be listed as a task — its task gate requires every task checked, so a close-out task is self-contradictory (checking it lies, leaving it blocks close-out, and `validate --strict` stays red during implementation). Before/after completion criteria (counts, baselines) MUST state they are measured on the change branch (against merge-base) — a value taken on the default branch is usually trivially the baseline.
+- **First** `llman-sdd change start <change-id>` (recommended; clean tree on the default branch; `--worktree` to keep the current checkout, `--base <branch>` for a non-default fork source) or manually create a branch then `change attach <change-id>`.
+- **Then** edit `llmanspec/specs/<capability>.feature` (flat, or directory `llmanspec/specs/<capability>/` main file) on the bound non-default branch and commit (land specs). **Do not** edit specs before start; **do not** commit specs to the default branch just to satisfy the clean-tree gate. If already attached, do not re-run `start` (recover lost specs by checkout/recreate + `attach --force`).
+- For changes with no contract edits, set frontmatter `needs_specs_change: false`. Enter apply when `llman-sdd show <id> --output json` shows `stage=full` with the specs-landed gate green; `readyToImplement=true` (all gates) is the completion signal gating verify/finalize.
+- **Breaking contract changes** (removed/renamed fields, commands, tags, or stage values) MUST plan the upgrade path: write a `migrations/v<from>-v<to>/README` (upgrade guidance; a one-shot script SHALL ship with the repo when feasible) — include it in the proposal's What Changes.
 
 ### 4) Validate
-   ```bash
-   llman-sdd validate <change-id> --strict --no-interactive
-   ```
-   This MUST pass before proceeding. If TOON parse errors appear, fix quoting:
-   values containing commas/colons/brackets must be double-quoted in tabular rows.
+```bash
+llman-sdd validate <change-id> --strict
+```
+This MUST pass before proceeding; failing items are listed one by one in the validate output's `items[].issues[]` — fix each and re-run.
 
 ### 4a) Optional BDD runner (`bdd:` block)
 - Read `llmanspec/config.yaml`. Is there a `bdd:` block?
-  - **Yes**: `validate --check` runs the harness; 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**: "This change looks like it has executable behavior. Enable a `bdd:` runner block so scenarios can be validated as `.feature` files? (adds a `bdd:` block to `config.yaml` — runner only, does not change the lifecycle.)"
-    - If **yes**: show the exact `bdd:` block to add (pick a `run_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 it, write it to `config.yaml`, then proceed with 4b rules.
-    - If **no**: features still validate structurally; only runner execution is skipped.
-- **Do NOT silently add the `bdd:` block** — always ask first. Adding it changes how `validate --check` behaves project-wide.
+  - **Yes**: `bdd.run_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.
+  - **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 `bdd:` runner block (adds a `bdd:` block to `config.yaml` — runner only, does not change the lifecycle). If **yes**: show the exact `bdd:` block to add (pick a `run_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 `bdd:` block** — always ask first. Adding it declares the project-wide BDD execution entry.
 
 ### 4b) Single-track feature authoring
-- Planning shell (proposal/design/tasks) may briefly live on the default branch; **do not** edit live `llmanspec/specs/**` on the default branch. After Branch binding, Specs landing and implementation happen on the bound branch.
-- **Single-track**: each capability is ONE `<capability>.feature`. Constraint rules are `@req:<id> @human` scenarios (statement verbatim in the description); executable acceptance scenarios carry `@executable` and link back via `@req:<req_id>`. Never nest scenarios in `Rule:` blocks (the runner skips them).
-- Change shell: `llman-sdd change new <change-id>` → fill proposal/design/tasks → `llman-sdd change start <change-id>` (or `change attach`) → **then** edit live specs on the bound branch and commit (Specs landing).
-- Do **not** use `change delta` / solidify / `*.feature.delta.toon`; if an active `*.feature.delta.toon` or a legacy `spec.toon` exists, run `llman-sdd project migrate --kind toon2features` first.
+- Planning docs may briefly live on the default branch; **do not** edit `llmanspec/specs/**` on the default branch. After binding, landing specs and implementation happen on the bound branch.
+- **Single-track**: each capability is ONE `<capability>.feature`. The canonical style is the native Gherkin hierarchy: `@req:<id>` on the `规则:` block header, nested `场景:` (`Given/When/Then` steps bound to runner step code and executed — **the default, preferred shape**); only when a requirement cannot be expressed programmatically (abstract goals, architecture decisions, governance/human judgment) or is not yet converted, leave a `规则:` block with no nested scenario (bare rule, free-text description) and record the rationale in proposal/design. Legacy tags (@executable/@rule/@human/@manual) are gone.
+- **Description readability**: split long `规则:` descriptions across multiple lines for reviewability (the official parser preserves lines); description lines must not carry a `- ` list marker (it becomes part of the description) and must not begin with a step keyword (`假如/当/那么/而且` / `Given/When/Then/And/But` — Gherkin would parse it as a step).
+- **Structured adds preferred**: to append rules/scenarios to an existing capability, prefer `llman-sdd spec next-req-id` (global rN allocation) + `spec add-req` (appends a `规则:` block) + `spec add-scenario` (inserts a nested `场景:` under the rule). New capability → `spec skeleton <capability>`; id lookup → `spec resolve-req <rN>`. Legacy tag-based files: run `spec migrate-native` first. Hand-editing the `.feature` stays the escape hatch (best for editing existing clauses).
+- **Executable-scenario-first triage** (decide before writing any new clause): any behavior expressible as GWT (Given/When/Then) and bound to step code MUST land as a nested `场景:` — prose-only rules guard nothing. Examples: programmatically decidable behavior (e.g. "when validate runs then stdout is TOON and exit code is 0") → nested `场景:`; abstract goals/architecture decisions not decidable by program → a bare `规则:` block (no nested scenario; aggregate count nudges it; specs-compact reduces it), recording the rationale in proposal/design.
 
 ### 5) Summarize and suggest next step
-   - Enter implementation phase: `llman-sdd-apply`.
-   - If you need to think more: `llman-sdd-explore`.
-
-> 💡 Proposal done → next: `llman-sdd-apply` (implement)
+- Enter implementation: `llman-sdd-apply`. Need more thinking: `llman-sdd-explore`.
 
-> 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") }}
 
 {{ unit("skills/structured-protocol") }}

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

@@ -1,6 +1,6 @@
 ---
 name: "llman-sdd-quick"
-description: "Handle small code changes that do NOT modify behavioral contracts — no MUST/SHALL changes, no spec modifications. Use for refactors, typo fixes, or perf tweaks. Switch to propose for anything affecting externally observable behavior."
+description: "Quick path for small changes that don't touch behavioral contracts (refactor/typo/perf). If a MUST/SHALL change emerges, stop and switch to propose."
 metadata:
   version: "{{ llman_version }}"
 ---
@@ -13,44 +13,29 @@ Use this path for small changes that don't modify behavioral contracts.
 
 ```mermaid
 flowchart LR
-    explore["llman-sdd-explore<br/>Explore"] --> quick
-
-    quick["★ llman-sdd-quick ★<br/>Quick path (you are here)"]
-    quick --> commit["git commit<br/>Done"]
-
-    explore --> propose["Full path:<br/>propose (Branch binding + Specs landing) → apply → verify → archive"]
-    propose --> apply["..."]
-    apply --> verify["..."]
-    verify --> archive["..."]
+    quick["★ llman-sdd-quick"] --> commit["git commit"]
+    explore["llman-sdd-explore"] --> propose["Full path: propose → apply → verify → archive"]
 
     style quick fill:#d4edda,stroke:#28a745,stroke-width:3px
 ```
 
-> 📍 Quick path: no behavioral contract changes, modify code and commit directly. If you find you need to change a contract → STOP, switch to full path `llman-sdd-propose`
-> 🗺️ Full path includes Git-native Branch binding + Specs landing (Specs landing is not a separate skill)
+> 📍 Quick path: edit code and commit directly. If you find a contract change is needed → STOP, switch to `llman-sdd-propose`.
 
 ## Conditions (all must hold)
 - Does not change any MUST/SHALL-defined externally observable behavior
-- Does not cross capability boundaries
-- Does not involve migration or compatibility concerns
-- Is not a meta-spec change (SDD templates/process)
+- Does not cross capability boundaries; no migration/compatibility concerns; not an SDD meta-spec change
 
 ## Steps
-1. Use `llman-sdd context --task "..." --paths "..."` to confirm no spec changes needed.
-   - If context returns `quality: "unavailable"`, rebuild with `llman-sdd index rebuild` (default `pageindex`, no model needed).
-   - Use `llman-sdd list --specs --json` for keyword-level spec metadata.
+1. Use `llman-sdd context --task "..." --paths "..."` to confirm no spec changes are needed.
+   - If context returns `quality: "unavailable"` → run `llman-sdd index check` first: stale/missing → `llman-sdd index rebuild` (default `pageindex`, no model needed) 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. Modify the code directly.
-3. If you need to touch `llmanspec/specs/**`, STOP unless you are on a bound non-default change branch (mini change: `change start`/`attach` → edit → commit). Never commit live specs on the default branch — not even for typo or scope-only fixes. Prefer routing live-spec maintenance to `llman-sdd-propose`, or require an existing bound branch.
-4. git commit (message must explain why).
-5. No change directory, no archive needed.
+3. If you need to touch `llmanspec/specs/**`, STOP — unless you are on a bound non-default change branch (mini change: `change start`/`attach` → edit → commit). Never commit specs on the default branch, not even for typo or scope-only fixes. Prefer routing specs maintenance to `llman-sdd-propose`.
+4. git commit (message explains why). No change directory, no archive.
 
 ## Boundary handling
-- If during modification you find a behavioral contract change → STOP, switch to `llman-sdd-propose` (full path).
-- If multiple files are involved and scope is unclear → verify with `llman-sdd context` first.
-
-> 💡 Quick path done → git commit. If you need the full path → `llman-sdd-propose` → `llman-sdd-apply` → `llman-sdd-verify` → `llman-sdd-archive`
+- A behavioral contract change emerges mid-edit → STOP, switch to `llman-sdd-propose`.
+- Multiple files involved and scope unclear → confirm with `llman-sdd context` first.
 
-> 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/ethics-governance") }}

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

@@ -1,46 +1,35 @@
 ---
 name: "llman-sdd-research"
-description: "Delegate external research to a background agent. Use when the user needs official docs/API/source facts gathered, or wants the reading legwork delegated so they can keep working."
+description: "Delegate fact-finding to a background agent: primary sources only (official docs/API/source), cited findings."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Research
 
-Spin up a **background agent** to do the research, so you keep working while it reads.
+Spin up a **background agent** to do the research while you keep working. Auxiliary tool, usable at any stage (common in explore/wayfinder); output is written back to the change's proposal "Further Notes" section.
 
-## Pipeline position
+## The background agent's job
 
-Auxiliary tool, usable at any stage. Common in explore/wayfinder to provide factual input for decisions. Output is written back to the change's proposal "Further Notes" section for later stages to consume.
-
-> 📍 Standalone optional skill; research output feeds the main flow's explore/propose.
-
-## Responsibilities
-
-The background agent's job:
-
-1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not secondary write-ups. Follow every claim back to the source that owns it.
+1. Investigate against **primary sources** — official docs, source code, specs, first-party APIs, not secondary write-ups; trace every claim back to the source that owns it.
 2. Write findings to a single Markdown file, citing each claim's source.
-3. Save location (follow the repo's own convention if it has one): **default** to `llmanspec/changes/<current-change>/research/<topic>.md` (change docs, **not** live specs). Write to `docs/research/` only when the topic spans multiple changes and will still be referenced after archiving; **never** put single-change decisions or decaying deep-dives into `docs/research/`.
-4. **MUST NOT** edit `llmanspec/specs/**` in this skill. If research shows MUST/SHALL must change → suggest `llman-sdd-propose` (Branch binding → Specs landing).
+3. Save location (repo convention wins if it has one): **default** `llmanspec/changes/<current-change>/research/<topic>.md` (change docs, **not** specs). Write to `docs/research/` only when the topic spans multiple changes and will still be referenced after archiving; **never** put single-change decisions or decaying deep-dives into `docs/research/`.
+4. **MUST NOT** edit `llmanspec/specs/**` in this skill. If research shows MUST/SHALL must change → suggest `llman-sdd-propose` (bind branch → land specs).
 
 ## Steps
 
-1. Clarify the research question (confirm with the user; if fuzzy, sharpen to a falsifiable one).
-2. Use the Agent tool `subagent_type=general-purpose` + `run_in_background: true` to launch the background research, with a prompt containing:
-   - The question statement.
-   - A requirement to cite only primary sources, with source URL/path per claim.
-   - The output file path (default `llmanspec/changes/<id>/research/<topic>.md`).
+1. Clarify the research question (confirm with the user; sharpen a fuzzy one into a falsifiable one).
+2. Launch via the Agent tool with `subagent_type=general-purpose` + `run_in_background: true`, prompt containing:
+   - The question statement; a requirement to cite only primary sources, with source URL/path per claim;
+   - The output file path (default `llmanspec/changes/<id>/research/<topic>.md`);
    - A word limit (suggested: focus on facts, prose narrative < 1500 words).
-3. Continue main-flow work while it runs in the background; receive a notification when done.
-4. Read the output, summarize key conclusions back into the current change's `proposal.md` "Further Notes" section (with a file pointer).
-5. If the research reveals a decision is needed, suggest entering `llman-sdd-explore`'s grilling branch.
+3. Continue main-flow work while it runs; when done, read the output and summarize key conclusions into the current change's `proposal.md` "Further Notes" section (with a file pointer).
+4. If the research reveals a decision is needed, suggest entering `llman-sdd-explore`'s deep-dive Q&A branch.
 
 ## Cooperation with wayfinder
 
 `llman-sdd-wayfinder`'s research tickets delegate to this skill for background resolution; on completion, write back to the ticket proposal and record a one-line gist in the map's Decisions-so-far.
 
-> 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") }}