@llman-sdd/core 0.3.0 → 0.5.0

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") }}

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") }}