@llman-sdd/core 0.3.1 → 0.5.0

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

@@ -1,84 +1,69 @@
 ---
 name: "llman-sdd-archive"
-description: "Archive completed llman SDD changes. Auto-merge back into the fork-point branch (squash by default), then rename change docs to archive/. Use after verify reports all-clear."
+description: "Archive a completed change: merge back (squash default), rename docs into archive/, auto-commit the close-out. Run after verify is green."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Archive
 
-Use this skill to archive completed changes. Prerequisites: verify all-green, and the change already has Branch binding plus Specs landing (or `needs_specs_change: false`; live specs are on the bound branch). `change finalize` **auto-merges** into the fork-point branch (target: `--into` > binding `base_branch` > default branch; method: `--method` > config `sdd.merge_method`, squash by default — feature diff + rename collapse into ONE close-out commit on the target), **renames** change docs to `changes/archive/`, then **auto-commits** `archive(sdd): <change-id>` (impl diff + rename in one commit; `--no-commit` skips). `change checkpoint` is removed (no mid-flight archive point; `change finalize` does not require a clean tree). `git push` / hosting PR are optional.
+Archive completed changes. Prerequisites: verify all-green, and the change is branch-bound with specs landed (or `needs_specs_change: false`). `change finalize` **auto-merges** into the base branch (target: `--into` > binding `base_branch` > default branch; method: `--method` > config `sdd.merge_method`, squash by default — feature diff + rename collapse into ONE commit on the target), **renames** change docs into `changes/archive/`, then **auto-commits** `archive(sdd): <change-id>` (`--no-commit` skips). `git push` / PR are optional.
 
 ## Pipeline Position
 
 ```mermaid
 flowchart LR
-    verify["llman-sdd-verify<br/>Verify"] --> archive
-    archive["★ llman-sdd-archive ★<br/>Archive (you are here)"]
+    verify["llman-sdd-verify"] --> archive["★ llman-sdd-archive"]
 
     style archive fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 You are in the archive phase: the last stop in the Git-native lifecycle.
-> 📎 If specs get too large, run `llman-sdd-specs-compact` to compress.
+> 📍 You are in archive: the last stop of the branch lifecycle. If specs grow too large, run `llman-sdd-specs-compact`.
 
 ## Hard Constraints
 
-- **Must pass verify phase all-green first**: don't archive changes that haven't passed verification.
-- **Must already have Branch binding**: `change start` / `attach` done; otherwise STOP.
-- **SSOT validation**: every change must pass `llman-sdd validate <id> --strict --no-interactive` before archiving.
+- **Verify must be all-green first**; **the change must be branch-bound** (`change start` / `attach`) — otherwise STOP.
+- Every change must pass `llman-sdd validate <id> --strict` before archiving.
 - **Don't ask "should I continue?"**: execute the full batch to completion unless you hit an unresolvable error.
-- **Close-out MUST NOT default to PR/push**: finalize performs a local merge (squash by default) + rename + one close-out commit (`archive(sdd): <id>`). `git push` / hosting PR are optional — only when the user or project explicitly requires remote review. **Agent MUST NOT** push or open a PR by default on this skill's account.
+- **Close-out MUST NOT default to PR/push**: the CLI merges locally (squash default) + one close-out commit. Push / PR only when the user or project explicitly requires remote review — **Agent MUST NOT** push or open a PR by default.
 
 ## Steps
 
 ### 0) Preflight
-- `git status --porcelain`: confirm working tree changes belong to completed changes.
-- If unexpected changes exist, handle them (stash or report).
+- `git status --porcelain`: confirm working-tree changes belong to completed changes; handle unexpected ones first (stash or report).
 
-### 1) Confirm target changes
-- Determine target IDs: single or batch (from user input or `llman-sdd list --json`).
-- Always announce: "Archiving IDs: <id1>, <id2>, ...".
-- Confirm each change has passed verify phase all-green.
+### 1) Confirm targets
+- Determine IDs (single or batch, from user input or `llman-sdd list --json`); always announce "Archiving IDs: <id1>, <id2>, ..." and confirm each change is verify all-green.
 
 ### 2) Archive one by one
-- **Human review checkpoint (before each id is archived, including batches)**: run `llman-sdd review --capability <id>`. Exit code zero → continue; non-zero = CRITICAL findings: STOP, fix, re-run; MUST NOT archive with CRITICAL findings open.
-- Validate each first: `llman-sdd validate <id> --strict --no-interactive`.
-- Validation failure → STOP and report; don't skip validation and force archive.
+- **Human review gate (before each id, including batches)**: run `llman-sdd review` (plain; `--capability` takes a spec id only). Exit code zero → continue; non-zero = CRITICAL → STOP, fix, re-run; MUST NOT archive with CRITICAL findings open.
+- Validate first: `llman-sdd validate <id> --strict`; failure → STOP and report, never force-archive.
 - Optional preview: `llman-sdd change archive <id> --dry-run`.
-- Execute archive:
-  - default: `llman-sdd change archive <id>`
-  - tooling-only: `llman-sdd change archive <id> --skip-specs`
-  - **stop immediately on first failure**, report remaining unprocessed IDs.
-- **Git-native close-out**:
-  - Prerequisites: Branch binding done (`change start` / `attach`); still on the bound branch (or the target branch after the auto merge).
-  - `change archive` / `change finalize` run the **auto merge** (target `--into` > binding `base_branch` > default branch; method squash by default or `ff`; if the target is held by another worktree the merge is skipped with an explicit manual command), **then** rename change docs into `changes/archive/` — rename is never rolled back on merge failure and degradation is reported explicitly.
-  - Legacy `*.feature.delta.toon` or `spec.toon` under specs is a migration blocker — run `llman-sdd project migrate --kind toon2features`.
-  - **Default: `change finalize` (one-command close)** — gates → auto merge → docs rename → **auto commit** `archive(sdd): <change-id>` (squash default: impl diff + rename collapse into ONE commit on the target; no manual `git commit` needed; locked-rule edits are a report-only WARNING — warn, never block):
+- Execute: `llman-sdd change archive <id>`; **stop immediately on first failure** and report the remaining IDs.
+- **Branch close-out**:
+  - Prerequisites: branch bound; still on the bound branch (or on the target branch after the auto merge).
+  - `change archive` / `change finalize` run the **auto merge** (target `--into` > `base_branch` > default branch; method squash by default or `ff`; when the target is held by another worktree the merge and commit run in place inside it, with `executed in target worktree <path>` in the output; a dirty holding worktree aborts with disposal options and zero writes), **then** rename into `changes/archive/` — the rename is never rolled back on merge failure and degradation is reported explicitly.
+  - **Default: `change finalize` (one-command close)** — gates → merge → rename → **auto commit** `archive(sdd): <change-id>` (no manual `git commit` needed; locked-rule edits are a report-only WARNING — warn, never block):
     ```text
-    1. Implement live specs + code (working tree may stay dirty; commits on the branch are free — segmented or none)
+    1. Implement specs + code (working tree may stay dirty; commits on the branch are free)
     2. llman-sdd change finalize <id>    # gates + merge (squash default) + rename + auto commit
-    3. optional: git commit --amend    # adjust the message; git branch -D <feature>  # after squash the branch is no longer an ancestor; -d gets refused
+    3. optional: git commit --amend to adjust the message; git branch -D <feature>  # after squash the branch is no longer an ancestor; -d gets refused
     ```
-    `--no-commit` skips the auto commit (CI / pre-commit-hook conflicts): finalize then leaves the tree dirty and prints the manual `git commit` command. Idempotent retry: a rerun after a failed auto commit detects the already-archived rename and finishes the commit.
-  - **Fallback: plain `change archive <id>`** — same merge + rename, no auto commit; requires a clean tree. `checkpointed`/`checkpoint_sha` fields went away with checkpoint (no mid-flight archive point; `change finalize` needs no clean tree) — nothing to write beforehand, and nothing to review for the snapshot (use `change diff` instead).
+    `--no-commit` skips the auto commit (CI / pre-commit-hook conflicts): finalize leaves the tree dirty and prints the manual commit command. Idempotent retry: a rerun after a failed auto commit detects the already-archived rename and finishes the commit.
+  - **Fallback: plain `change archive <id>`** — same auto merge + rename + close-out commit as finalize (no `--no-commit` here); gates: tasks all checked + clean tree + on the bound non-default branch (`--force` skips the gates). Snapshot review: `change diff`.
 
 ### 3) Full validation
-- After all archives complete: `llman-sdd validate --all --strict --no-interactive`.
-- Confirm post-archive spec artifacts are consistent.
+- After all archives: `llman-sdd validate --all --strict`; confirm spec artifacts are consistent.
 
 ### 4) Commit guidance
-- Finalize auto-committed (`archive(sdd): <id>`); with `--no-commit`, commit manually: `git add -A && git commit -m "archive(sdd): <id1>, <id2>"` (or the archive skill's suggested format).
-- Optional: `git branch -D <feature>` after the merge (squash leaves the branch outside main's ancestry). push / hosting PR only when the user or project explicitly requires remote review.
-- **Breaking contract changes** (removed/renamed frontmatter field, command, tag, or stage value) MUST ship an upgrade path under `migrations/v<from>-v<to>/` (README prompt + one-shot script, shipped in-repo) — verify it exists before closing the change.
-- **Archived `depends_on`**: archive renames the change dir to `archive/YYYY-MM-DD-<id>`, but validate recognizes `depends_on` pointing to archived/frozen ids as INFO (not ERROR), so you do **not** need to manually update other changes' `depends_on` frontmatter after archive.
-
-> 💡 Previous phase `llman-sdd-verify` (passed verification) → this phase completes the loop. If specs grow too large, run `llman-sdd-specs-compact`.
+- Finalize already auto-committed; with `--no-commit`, commit manually: `git add -A && git commit -m "archive(sdd): <id1>, <id2>"`.
+- Optional: `git branch -D <feature>` after the merge. Push / PR only when explicitly required.
+- **Breaking contract changes** (removed/renamed frontmatter field, command, tag, or stage value) MUST ship an upgrade path under `migrations/v<from>-v<to>/` (README + one-shot script, shipped in-repo) — verify it exists before closing.
+- **Archived `depends_on`**: archive renames the change dir to `archive/YYYY-MM-DD-<id>`; validate treats `depends_on` pointing to archived/frozen ids as INFO (not ERROR), so you do **not** need to update other changes' frontmatter after archive.
 
 {{ unit("workflow/archive-freeze-guidance") }}
 
-> 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-continue.md

@@ -1,41 +1,34 @@
 ---
 name: "llman-sdd-continue"
-description: "Continue an existing llman SDD change by creating the next artifact."
+description: "Continue an existing change: create the next missing artifact."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Continue
 
-Use this skill to continue an existing change and create the next missing artifact.
+Continue an existing change and create the next missing artifact.
 
 ## Steps
-1. Identify the change id:
-   - If provided by the user, use it.
-   - Otherwise run `llman-sdd list --json` and ask which change to continue.
-   - Always announce: "Using change: <id>".
-2. Read the change directory: `llmanspec/changes/<id>/`.
-> Stage gate: decide from `stage` / `readyToImplement` in `llman-sdd show <id> --json --type change`; full decision table lives in llman-sdd-apply.
-3. Determine the next artifact to create (in order):
+1. Identify the change id: use it if provided; otherwise run `llman-sdd list --json` and ask which change to continue. Always announce "Using change: <id>".
+2. Read `llmanspec/changes/<id>/`.
+> Stage decisions use `stage` / `readyToImplement` from `llman-sdd show <id> --output json --type change`; the full decision table lives in llman-sdd-apply.
+3. Determine the next missing artifact, in order:
    1) `proposal.md`
-   2) `design.md` (only if design tradeoffs matter)
+   2) `design.md` (only when design tradeoffs matter)
    3) `tasks.md`
-   4) `llman-sdd change start <id>` (or `change attach <id>` if the branch already exists) — Branch binding
-   5) Edit live `llmanspec/specs/<capability>.feature` (flat, or directory main file) on the **bound branch** and commit — Specs landing (or set `needs_specs_change: false` when there is no contract edit)
-4. Create exactly ONE missing artifact (or one live spec/feature edit on the bound branch).
-   - Do NOT implement application code in continue mode.
-   - Do NOT create `*.feature.delta.toon`, `spec.toon`, or files under `changes/<id>/specs/`.
-   - Do NOT edit shared `llmanspec/specs/**` before start/attach.
-5. If all artifacts already exist, suggest next actions from `llman-sdd show <id> --json`:
-   - `readyToImplement=false` → finish Specs landing (or `needs_specs_change: false`); do **not** suggest apply yet
-   - `readyToImplement=true` → Implement: `llman-sdd-apply`
-   - After verify → Archive: `llman-sdd-archive`
-   - Validate: `llman-sdd validate <id> --strict --no-interactive`
-   - Review: `llman-sdd change diff <id>` (read-only)
+   4) `llman-sdd change start <id>` (or `change attach <id>` if the branch exists) — bind the branch
+   5) Edit `llmanspec/specs/<capability>.feature` (flat, or directory main file) on the **bound branch** and commit — land specs (or set `needs_specs_change: false` when there is no contract edit)
+4. Create exactly ONE missing artifact (or one spec edit on the bound branch).
+   - Do NOT write application code; do NOT create `changes/<id>/specs/`; do NOT edit `llmanspec/specs/**` before start/attach.
+5. If all artifacts exist, suggest next steps from `llman-sdd show <id> --output json`:
+   - specs-landed gate failing → land specs first (or `needs_specs_change: false`); do **not** suggest apply yet
+   - specs-landed gate green (even mid-implementation with `readyToImplement=false` while tasks remain) → `llman-sdd-apply`
+   - After verify → `llman-sdd-archive`
+   - Validate: `llman-sdd validate <id> --strict`; review: `llman-sdd change diff <id>` (read-only)
 
 {{ unit("skills/git-native-flow") }}
-> 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-draft.md

@@ -1,64 +1,53 @@
 ---
 name: "llman-sdd-draft"
-description: "Quickly capture a change idea as a draft proposal (proposal.md only, via `change new --from`). No tasks/design/specs/attach. Use to jot down ideas or future requirements; promote to full propose when ready."
+description: "Capture a change idea as a draft (proposal.md only, no id asked). For jotting ideas/future needs; formalize with propose when ready."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Draft
 
-Capture a change idea as a **draft proposal** (a `proposal.md` skeleton only). This is the lightweight entry point for "just record this idea / future need" — no triage, no tasks, no live specs, no attach. Promote to a formal change with `llman-sdd-propose` when the idea is ready to act on.
+Capture a change idea as a **draft** (a `proposal.md` skeleton only) — the lightweight "just record it" entry: no scale assessment, no tasks, no specs edits, no attach. Formalize with `llman-sdd-propose` when ready to act.
 
 ## Pipeline Position
 
 ```mermaid
 flowchart LR
-    draft["★ llman-sdd-draft ★<br/>Draft (you are here)"] -.->|"promote"| propose["llman-sdd-propose<br/>Propose"]
-    propose --> apply["llman-sdd-apply<br/>Implement"]
-    apply --> verify["llman-sdd-verify<br/>Verify"]
-    verify --> archive["llman-sdd-archive<br/>Archive"]
+    draft["★ llman-sdd-draft"] -.->|"formalize"| propose["llman-sdd-propose"]
+    propose --> apply["llman-sdd-apply"] --> verify["llman-sdd-verify"] --> archive["llman-sdd-archive"]
 
     style draft fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 You are at the draft stage → next: flesh out `proposal.md`, then run `llman-sdd-propose` to formalize
-> 📎 This skill creates a **draft** change (proposal.md only). Full propose follows Git-native: tasks → Branch binding → Specs landing (see propose lifecycle diagram)
-> 🗺️ Skill navigation ≠ Git-native lifecycle; Branch binding / Specs landing are not separate skills
+> 📍 Draft stage → next: flesh out `proposal.md`, then `llman-sdd-propose` to formalize.
 
 ## Hard Constraints
 
 - **MUST NOT ask the user for a change id**: derive it from the description via `change new --from` and announce it.
-- **MUST NOT create tasks/design/specs/attach**: this skill creates only the `proposal.md` draft shell. Full planning artifacts belong to `llman-sdd-propose`.
-- **MUST NOT run triage or assess change scale**: that is propose's job. If the user wants to start implementing, suggest `llman-sdd-propose`.
-- **Scope boundary**: if the description clearly involves MUST/SHALL behavioral contract changes or multi-file impact, suggest `llman-sdd-propose` instead of stopping at a draft — but still create the draft shell first so the idea isn't lost.
-- **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 it via `llman-sdd show`/`list`, never store it in frontmatter. Do not re-declare frontmatter fields in the prose body (no `## Status` block); the body H1 is a human-readable title, not a repeat of the change id.
+- **MUST NOT create tasks/design/specs/attach**: only the `proposal.md` draft; full planning belongs to `llman-sdd-propose`.
+- **MUST NOT assess change scale**: that is propose's job. If the user wants to start implementing → suggest `llman-sdd-propose`.
+- **Scope boundary**: if the description clearly involves MUST/SHALL contract changes or multi-file impact, suggest `llman-sdd-propose` — but still create the draft first so the idea isn't lost.
+- **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 (no `## Status` block); the H1 is a human-readable title, not a repeat of the change id.
 
 ## Steps
 
 ### 0) Preflight
-- Read `llmanspec/config.yaml` for project context, rules, locale.
-- `llmanspec/` must exist; if missing, tell the user to run `llman-sdd init`, then STOP.
+- Read `llmanspec/config.yaml`; if `llmanspec/` is missing, tell the user to run `llman-sdd init`, then STOP.
 
 ### 1) Capture the description
-- Take the user's description as-is (e.g. "draft: add a export-to-json command", "note down: we should support worktrees for sdd changes").
-- **MUST NOT ask for a change id.** Derive it from the description.
+- Take the user's description as-is (e.g. "draft: add an export-to-json command", "note: sdd changes should support worktrees"). **MUST NOT ask for a change id.**
 
-### 2) Create the draft shell
+### 2) Create the draft
 ```bash
 llman-sdd change new --from "<user description>"
 ```
-- The CLI generates a legal kebab-case id (sanitized + validated), creates `llmanspec/changes/<derived id>/proposal.md` (a skeleton with `## Why` / `## What Changes` TODO sections), and prints the final id + path.
-- If the derived id collides with an existing change, the CLI fails non-zero; suggest rephrasing the description or using `--force` to overwrite (rare for drafts).
+- The CLI generates a legal kebab-case id, creates `llmanspec/changes/<id>/proposal.md` (a skeleton with `## Why` / `## What Changes` TODO sections), and prints the id + path.
+- On id collision the CLI fails non-zero; suggest rephrasing or `--force` to overwrite (rare for drafts).
 
 ### 3) Announce and hand off
-- **MUST tell the user the derived id** (e.g. "Created draft change `<id>` at `llmanspec/changes/<id>/proposal.md`").
-- Suggest next steps:
-  - Flesh out `proposal.md` (Why / What Changes / Capabilities / Impact) now or later.
-  - When ready to act on it, run `llman-sdd-propose` to formalize (triage + tasks → `change start`/`attach` → Specs landing).
+- **MUST tell the user the derived id** ("Created draft change `<id>` at `llmanspec/changes/<id>/proposal.md`").
+- Suggest next steps: flesh out `proposal.md` (Why / What Changes / Capabilities / Impact); formalize with `llman-sdd-propose` when ready.
 
-> 💡 Draft captured → next: edit `proposal.md`, then `llman-sdd-propose` to formalize.
-
-> 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-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") }}