@llman-sdd/core 0.1.0 → 0.1.2

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

@@ -0,0 +1,74 @@
+---
+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."
+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`.
+
+## Usage
+
+**Focus view (seed mode):** Show a specific change and its relationship neighborhood.
+
+```bash
+llman sdd graph <change-id>              # the change + direct relationships (depth 1)
+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.
+
+**Global view (scope mode):** Show all changes by scope.
+
+```bash
+llman sdd graph                          # all active changes (default)
+llman sdd graph --scope archived         # all archived (completed) changes
+llman sdd graph --scope all              # everything
+```
+
+## Output
+
+- Output is a 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".
+
+## Proposal frontmatter format
+
+```yaml
+---
+depends_on:
+  - other-change-id
+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/ethics-governance") }}

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

@@ -0,0 +1,34 @@
+---
+name: "llman-sdd-onboard"
+description: "Onboard to the llman SDD workflow in a repository."
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Onboard
+
+Use this skill to onboard to llman SDD in a repository.
+
+## Steps
+1. Read `llmanspec/config.yaml` for project context, conventions, and rules.
+2. Use `llman sdd list --specs --json` to see all specs at a glance.
+   - Or use `llman sdd context --task "<task description>" --paths "<files>"` to find task-relevant specs.
+   - If context returns `quality: "unavailable"`, run `llman sdd index rebuild` first (default backend is `pageindex`; it needs `LLMAN_SDD_INDEX_CHAT_MODEL` for retrieval but not for rebuilding).
+3. Read only the `direct` spec files from context output.
+4. Assess change scale (see triage rules): behavioural contract change → full SDD; implementation change → quick path.
+5. Advance by path:
+   - **Full path**: planning shell (draft → designed [+design.md] → planned [+tasks.md]) → Branch binding → Specs landing (or `needs_specs_change: false`) → `readyToImplement=true` → apply → verify → finalize/archive (skill navigation: propose → apply → verify → archive).
+   - **Quick path**: no MUST/SHALL change; edit code and commit (live specs only on a bound branch — see `llman-sdd-quick`).
+6. Use `llman sdd graph` to visualize change dependencies.
+
+> 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>`.
+
+## Notes
+- `llmanspec/config.yaml` holds project context, rules, locale, and skills paths.
+- Locale affects templates/skills only; CLI stays English.
+- Refresh skills with `llman sdd init --update`.
+
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

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

@@ -0,0 +1,120 @@
+---
+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."
+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.
+
+## 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"]
+
+    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)
+
+## 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.
+- **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.
+{% 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]`).
+{% 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.
+
+## 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.
+
+## 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`).
+
+### 1) Assess change scale (triage)
+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
+   - 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>`)
+
+### 2) Ensure 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).
+{% if extra_skill_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`).
+{% 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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)
+
+> 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/validation-hints") }}
+
+{{ unit("skills/structured-protocol") }}

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

@@ -0,0 +1,56 @@
+---
+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."
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Quick Path
+
+Use this path for small changes that don't modify behavioral contracts.
+
+## Pipeline Position
+
+```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["..."]
+
+    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)
+
+## 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)
+
+## 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.
+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.
+
+## 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`
+
+> 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/ethics-governance") }}

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

@@ -0,0 +1,46 @@
+---
+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."
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Research
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+## Pipeline position
+
+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.
+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).
+
+## 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`).
+   - 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.
+
+## 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/structured-protocol") }}

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

@@ -0,0 +1,24 @@
+---
+name: "llman-sdd-show"
+description: "Inspect llmanspec changes and specs quickly."
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Show
+
+Use this skill to inspect changes, specs, and JSON output.
+
+## Steps
+1. List items: `llman sdd list` or `llman sdd list --specs`.
+2. If the id is unknown or ambiguous, show the list and ask the user to pick.
+3. Show details: `llman sdd show <id>`.
+4. Disambiguate with `--type change|spec` when needed.
+5. For changes, use `--json`: status SSOT fields are `stage` / `specsLanded` / `needsSpecsChange` / `readyToImplement` (never decide apply-readiness from vague "complete artifacts" wording).
+
+> 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/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

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

@@ -0,0 +1,66 @@
+---
+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."
+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`).
+
+## 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.
+
+## Goal
+- Identify and merge redundant requirements/scenarios.
+- Form a more compact and 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.
+
+## 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.
+4. Produce a compaction plan (canonical requirements + keep/merge/remove decisions + migration notes).
+5. Execute and validate (`llman sdd validate --specs --strict --no-interactive`).
+
+## 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.
+- 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`.
+
+> 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/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

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

@@ -0,0 +1,32 @@
+---
+name: "llman-sdd-validate"
+description: "Validate llmanspec changes and specs with actionable fixes."
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Validate
+
+Use this skill to 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.
+{% 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`).
+{% 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/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

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

@@ -0,0 +1,96 @@
+---
+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."
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Verify
+
+Use this skill to 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"]
+
+    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.
+
+## 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.
+
+{{ 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"):
+
+     | Smell | Fix |
+     |-------|-----|
+     | Mysterious Name (name hides intent) | rename it |
+     | Duplicated Code (same logic shape) | extract the shared part |
+     | Feature Envy (method uses another's data more) | move the method over |
+     | Data Clumps (same fields travel together) | bundle into a type |
+     | Primitive Obsession (primitive stands in for a domain concept) | give it a dedicated type |
+     | Repeated Switches (same switch recurs) | polymorphism or a shared map |
+     | Shotgun Surgery (one change scatters edits) | gather into one module |
+     | Divergent Change (one file changes for unrelated reasons) | split it |
+     | Speculative Generality (abstraction for unseen needs) | delete it |
+     | Message Chains (long a.b().c()) | hide the chain behind one method |
+     | 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).
+   - 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)
+
+{{ 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/validation-hints") }}
+
+{{ unit("skills/structured-protocol") }}

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

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