@llman-sdd/core 0.3.1 → 0.5.1

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

@@ -1,125 +1,107 @@
 ---
 name: "llman-sdd-apply"
-description: "Implement tasks from an llman SDD change in a closed loop — write code, run tests, self-heal on failures until all gates pass. Use when a change is proposed and ready to implement. Updates tasks.md checkboxes and runs validation."
+description: "Implement a proposed change's tasks in a closed loop: code → test → self-heal → all gates green. Enter after propose, once specs are landed."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Apply
 
-Implement all tasks in `llmanspec/changes/<id>/tasks.md` **in one closed loop**:
-Implement code → Add tests/acceptance → Run gates → Self-heal on failures → Report results when all pass.
-Unless there is a clear blocker, **DO NOT stop halfway to ask "should I continue?"**
+Implement all tasks in `llmanspec/changes/<id>/tasks.md` **in one closed loop**: implement → add tests/acceptance → run gates → self-heal and re-run on failure → report when all pass. Unless there is a clear blocker, **do not stop halfway to ask "should I continue?"**
 
 ## Pipeline Position
 
 {{ unit("skills/git-native-flow-brief") }}
 
-### Skill navigation (not the lifecycle; shows current skill only)
-
 ```mermaid
 flowchart LR
-    propose["llman-sdd-propose<br/>Propose"] --> apply
-    apply["★ llman-sdd-apply ★<br/>Implement (readyToImplement)"]
-    apply --> verify["llman-sdd-verify<br/>Verify"]
-    verify --> archive["llman-sdd-archive<br/>Archive"]
+    propose["llman-sdd-propose"] --> apply["★ llman-sdd-apply"]
+    apply --> verify["llman-sdd-verify"]
+    verify --> archive["llman-sdd-archive"]
 
     style apply fill:#fff3cd,stroke:#ffc107,stroke-width:3px
 ```
 
-> 📍 You are at Git-native **H (apply)** in the full lifecycle diagram: Specs-landed (or `needs_specs_change: false`) and `readyToImplement=true` required first → next: `llman-sdd-verify`
+> 📍 Entry requires the specs-landed gate green (or `needs_specs_change: false`); `readyToImplement=true` (all gates green) is the completion signal that closes this loop → next `llman-sdd-verify`.
 
 ## Hard Constraints
 
-- **SSOT-driven**: `proposal.md` / `design.md` / `tasks.md` and live `llmanspec/specs/**` on the feature branch are the single source of truth; every MUST/SHALL in specs must be fulfilled.
-- **Scope-locked**: Only implement what's in the current change; don't fix "unrelated issues" on the side.
-- **Minimal changes**: Keep changes minimal and strictly scoped to current tasks.
-- **No guessing**: If requirements are unclear, or specs contradict reality, STOP and report — don't assume behavior.
-- **No legacy compatibility layers**: If a change requires new behavior, upgrade all call sites directly, unless tasks/proposal explicitly require compatibility.
-- **Don't ask "should I continue?"**: Execute to loop closure unless you hit an unresolvable blocker.
-- **Close-out**: this skill's closed loop ends by suggesting `llman-sdd-verify`; finalize/archive is handled by `llman-sdd-archive` (do not finalize inside the self-healing loop).
+- **Single-source-of-truth driven**: `proposal.md` / `design.md` / `tasks.md` and `llmanspec/specs/**` on the branch; every MUST/SHALL in specs must be fulfilled.
+- **Scope-locked**: only implement the current change's scope; never fix "unrelated issues" on the side; keep changes minimal.
+- **No guessing**: unclear requirements or specs contradicting reality → STOP and report; don't assume.
+- **No legacy compatibility layers**: if the change requires new behavior, upgrade all call sites directly, unless tasks/proposal explicitly require compatibility.
+- **Close-out**: this loop ends by suggesting `llman-sdd-verify`; finalize/archive belongs to `llman-sdd-archive` (do not finalize inside the self-healing loop).
 
 ## Commit Policy
 
-- **Commits on the change branch are free** (no mid-flight archive point; `change finalize` needs no clean tree): segment by task or milestone when it helps review, or keep the working tree dirty and let finalize make ONE close commit — both are first-class. `change checkpoint` no longer exists (calling it exits non-zero and points to finalize), so there is no mid-flight "archive point" to maintain; `change finalize` handles both shapes (it does NOT require a clean tree).
-- **Default close-out**: after all tasks pass gates and verify is green, `llman-sdd change finalize <id>` auto-commits `archive(sdd): <change-id>` (uncommitted impl diff + frontmatter + archive rename in one commit). Do not run finalize inside the apply loop. `--no-commit` skips the auto commit (manual/CI histories; pre-commit-hook conflicts).
-- **Blocker interrupt**: when you must STOP on a blocker, make ONE work-in-progress commit (e.g. `wip(sdd): <change-id> <summary>`) to preserve the state, then report.
+- **Commits on the change branch are free** (`change finalize` needs no clean tree): segment by task/milestone, or keep the tree dirty and let finalize make one close commit — both are first-class.
+- **Default close-out**: after all tasks pass gates and verify is green, `llman-sdd change finalize <id>` auto-commits `archive(sdd): <change-id>` (uncommitted diff + frontmatter + rename in one commit). Do not run finalize inside the apply loop. `--no-commit` skips the auto commit (manual/CI histories; pre-commit-hook conflicts).
+- **Blocker interrupt**: when you must STOP on a blocker, make ONE WIP commit (e.g. `wip(sdd): <change-id> <summary>`) to preserve the state, then report.
 
 ## Steps
 
 ### 0) Preflight (required)
-- Read and obey: `llmanspec/config.yaml`, `AGENTS.md` (if present).
-- `git status --porcelain`:
-  - If working tree is dirty and changes don't belong to the current change: `git stash push -u -m "llman-sdd-apply autopilot backup"`.
-- Run `llman-sdd validate --all --strict --no-interactive`:
-  - If it fails for reasons unrelated to the current change, stop and report (inconsistent artifacts prevent SSOT-driven implementation).
-- **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) Select change id and check prerequisites
-- If a change id is provided, use it directly.
-- Otherwise infer from context; if ambiguous, run `llman-sdd list --json` and let user pick.
-- Always announce: "Using change: <id>" and how to override.
-- Confirm you are on the non-default feature branch bound via `llman-sdd change start <id>` or `change attach <id>` (`--force` only to rebind). Specs/features on the branch are SSOT — do not author under `changes/<id>/specs/`.
+- Read and obey `llmanspec/config.yaml`, `AGENTS.md` (if present).
+- `git status --porcelain`: if the tree is dirty with changes not belonging to this change → `git stash push -u -m "llman-sdd-apply autopilot backup"` first.
+- `llman-sdd validate --all --strict`: if it fails for reasons unrelated to this change → stop and report (inconsistent artifacts prevent source-of-truth-driven implementation).
+- **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) Select the change id and check prerequisites
+- If provided, use it; otherwise infer from context, and if ambiguous run `llman-sdd list --json` and let the user pick. Always announce "Using change: <id>" and how to override.
+- Confirm you are on the non-default branch bound via `llman-sdd change start <id>` or `change attach <id>` (`--force` only to rebind). Specs on the branch are the single source of truth — do not author under `changes/<id>/specs/`.
 {{ unit("skills/stage-guard") }}
 - Use `llman-sdd context --task "<goal from proposal>" --paths "<scope from specs>"` to get relevant specs.
-  - If context is unavailable, run `llman-sdd index rebuild` and retry.
+  - Context unavailable → run `llman-sdd index check` first: stale/missing → `llman-sdd index rebuild` 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) Read SSOT artifacts
-You must read through:
-- `llmanspec/changes/<id>/proposal.md`
-- `llmanspec/changes/<id>/design.md` (if present)
-- `llmanspec/changes/<id>/tasks.md`
-- Live specs on the feature branch: `llmanspec/specs/**` (`<capability>.feature`) — this is SSOT
+### 2) Read the source-of-truth artifacts
+- `llmanspec/changes/<id>/proposal.md`, `design.md` (if present), `tasks.md`
+- `llmanspec/specs/**` (`<capability>.feature`) on the branch
 
-Extract hard constraints from proposal.md and design.md decisions. Convert tasks.md into a minimal executable step sequence (preserving original order).
+Distill proposal/design decisions into a list of inviolable hard constraints; convert tasks.md into a minimal executable step sequence (preserving original order).
 
 ### 3) Show status
-- Progress: "N/M tasks complete"
-- Next 1–3 unchecked tasks (brief overview)
+- Progress "N/M tasks complete" + a brief look at the next 1–3 unchecked tasks.
 
-### 4) Implement tasks one by one (closed-loop execution)
+### 4) Implement tasks one by one (closed loop)
 For each unchecked task:
-1. **Implement**: strictly per task description + specs requirements, keep changes minimal.
-2. **Update checkbox immediately** after completion: `- [ ]` → `- [x]`.
-3. If task is unclear, you hit a blocker, or specs/design don't match reality → STOP and report the blocker, don't assume.
-
-> 💡 Previous phase `llman-sdd-propose` (generated tasks); after this phase → `llman-sdd-verify` (verify)
-
-### 5) Verification and self-healing loop (run after each task or batch)
-Run project gate commands (adapt to the actual project):
-- Relevant test suite: `just test` or `cargo test --all`
-- Format/lint: `just check` or `just lint` + `just fmt`
-- Git-native: stay on the bound feature branch; edit live `llmanspec/specs/<capability>.feature` (flat, or directory `llmanspec/specs/<capability>/` main file; rules `@human`, acceptance `@executable`) as needed; run `llman-sdd validate --specs` after spec edits; commit on the branch freely (segmented or leave dirty for finalize). Do not use `change delta` / solidify / feature_delta; `change checkpoint` is removed.
-- SDD validation: `llman-sdd validate <id> --strict --no-interactive`
-
-**On failure → enter self-healing loop (don't ask "should I continue?"):**
-1. Parse failure cause (test failure / lint / format / validation error).
-2. **Decide if it's a hard-to-locate bug** (cause unclear / intermittent flake / regression not obvious at a glance):
-   - **Not hard-to-locate** (clear lint/format/compile/validation error): apply a minimum fix (don't expand scope); re-run the "minimum failure repro command" first, then re-run all gates.
-   - **Hard-to-locate bug → escalate to the diagnose sub-flow**:
+1. **Implement**: strictly per task description + specs, minimal changes.
+2. **Check the box immediately** after completion: `- [ ]` → `- [x]`. **Close-out is not a task**: `change finalize` / `change archive` are pipeline steps and MUST NOT appear in tasks.md — if one is listed (e.g. "close-out — finalize"), remove it (the close-out task gate requires every task checked).
+3. **Edit, then verify — serially**: verification MUST run after edits land on disk; MUST NOT put edits and tests/validation in the same parallel tool-call batch (the check may read stale files and report a false failure or a false pass).
+4. Task unclear, blocker hit, or specs/design contradict reality → STOP and report; don't assume.
+
+### 5) Verification and self-healing loop (after each task or batch)
+Run the project gates as appropriate:
+- Test suite: `just test` or `cargo test --all`; format/lint: `just check` or `just lint` + `just fmt`
+- Edit `llmanspec/specs/<capability>.feature` on the branch as needed (flat or directory main file; canonical native layout: `@req:<id>` on the `规则:` block header, nested `场景:` as executable examples); run `llman-sdd validate --specs` after spec edits; commit on the branch freely.
+- SDD validation: `llman-sdd validate <id> --strict`
+
+**Gate evidence**:
+- 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.
+- Gate verdicts MUST come from the real harness: MUST NOT obtain a "pass" via `--no-check`; on harness failure, find the root cause first (leaked env vars, nested-invocation guards, wrong cwd …) — MUST NOT label it an "inherent/self-referential property" and bypass it.
+- Before/after criteria (counts, baselines) 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.
+- Refactors and bulk replacements: MUST compare the test count before and after; all-green gates with fewer tests is a failure.
+
+**On failure → self-heal (don't ask "should I continue?"):**
+1. Parse the failure cause (test / lint / format / validation).
+2. Decide if it's a hard-to-locate bug (cause unclear / intermittent flake / regression not obvious at a glance):
+   - **Not hard-to-locate** (clear lint/format/compile/validation error): apply a minimal fix (don't expand scope); re-run the minimum failure-repro command first, then all gates.
+   - **Hard-to-locate → escalate to the diagnose sub-flow**:
      1. **First build a command that reproduces the failure** (fast, deterministic, agent-runnable, and goes red on *this* bug) — one that drives the real bug path and asserts the user's exact symptom. **MUST NOT start hypothesizing before such a command exists** (staring at code and guessing is the failure this prevents).
      2. Run it, confirm red → minimize the repro (cut inputs/calls/config/data one at a time, keep only what's load-bearing).
      3. Generate **3–5 ranked hypotheses**, each falsifiable ("if X is the cause, changing Y makes the bug disappear").
      4. Verify one variable at a time; fix once the root cause is found.
-     5. If there's no correct seam for a regression test, note the architectural gap (hand off to `llman-sdd-arch-review`; when that skill is not enabled via `extra_skills`, write the gap into this change's `proposal.md` Further Notes section or `design.md`, and MUST NOT break the loop over it).
-3. Re-run the "minimum failure repro command" first, then re-run all gates.
-4. Log as one self-healing round: `Round N: failure → fix → re-run → pass/fail`.
-
-**Self-healing cap: 8 rounds**; exceeding this is a blocker: stop and output a blocker report (last failing command + output summary + what you tried).
+     5. If there's no correct seam for a regression test, note the architectural gap (hand off to `llman-sdd-arch-review`; when not enabled, write the gap into this change's `proposal.md` Further Notes section or `design.md`, and MUST NOT break the loop over it).
+3. Re-run the minimum failure-repro command first, then all gates.
+4. Log one self-healing round: `Round N: failure → fix → re-run → pass/fail`.
 
-**Human review checkpoint (after each task batch passes the gates)**: once a batch is green, before starting the next batch or producing the completion report, run `llman-sdd review`:
+**Self-healing cap: 8 rounds**; exceeding it is a blocker: stop and output a blocker report (last failing command + output summary + what you tried).
 
-- Exit code zero → continue.
-- Non-zero exit = CRITICAL findings: STOP, fix, re-run review; MUST NOT enter the next batch or emit the completion report with CRITICAL findings open.
+**Human review gate (after each task batch passes the gates)**: before starting the next batch or emitting the completion report, run `llman-sdd review`: exit code zero → continue; non-zero = CRITICAL findings → STOP, fix, re-run review; MUST NOT enter the next batch or emit the completion report with CRITICAL findings open.
 
 ### 6) Completion report
-After all tasks complete + all gates green, output a structured report (see Output Contract below).
-Then suggest running `llman-sdd-verify` for the verification phase.
-
-> 💡 Implementation done → next: `llman-sdd-verify` (verify)
+After all tasks complete + all gates green, output a structured report (see Output Contract), then suggest `llman-sdd-verify`.
 
-> 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-arch-review.md

@@ -1,27 +1,21 @@
 ---
 name: "llman-sdd-arch-review"
-description: "Scan codebase for shallow modules (interface nearly equals implementation) and surface deepening candidates. Use when the user wants an architecture review, seeks module deepening opportunities, or wants to improve testability and AI-navigability."
+description: "Architecture review: scan for shallow modules (interface ≈ implementation) and surface deepening candidates to improve testability and AI-navigability."
 metadata:
   version: "{{ llman_version }}"
 ---
 
 # LLMAN SDD Architecture Review
 
-Scan the codebase for architectural friction and surface **deepening opportunities** — refactors that turn shallow modules (interface nearly equals implementation) into deep ones (lots of behaviour behind a small interface). The aim is testability and AI-navigability.
-
-## Pipeline position
-
-Auxiliary tool, not part of the main pipeline (explore→propose→apply→verify→archive). Usable at any stage; commonly triggered during explore to surface improvement candidates.
-
-> 📍 Standalone optional skill; does not replace any pipeline stage.
+Scan the codebase for architectural friction and surface **deepening opportunities** — turning shallow modules (interface ≈ implementation) into deep ones (lots of behavior behind a small interface). The aim is testability and AI-navigability. Auxiliary tool, not part of the main pipeline; usable at any stage, commonly triggered during explore.
 
 ## Design vocabulary
 
-A set of words about module shape, used to articulate "where it's worth changing". MUST NOT substitute "component" / "service" / "API" / "boundary" (they are broader, less precise):
+Words about module shape; MUST NOT substitute "component" / "service" / "API" / "boundary" (broader, less precise):
 
 - **Module** — anything with an interface and an implementation (function/class/package/cross-layer slice).
 - **Interface** — everything a caller must know to use it correctly: type signature, plus invariants, ordering constraints, error modes, performance characteristics.
-- **Depth** — the amount of behaviour behind the interface. **Deep** = lots of behaviour behind a small interface; **shallow** = interface nearly as complex as the implementation (the caller saves nothing).
+- **Depth** — the amount of behavior behind the interface. **Deep** = lots of behavior behind a small interface; **shallow** = interface nearly as complex as the implementation (the caller saves nothing). This skill turns shallow into deep.
 - **Seam** — a place where you can swap the implementation without editing call sites (where the interface lives). In llman, seam = the public boundary driven by `*.feature` GWT steps.
 - **Leverage** — what callers get from depth: more capability per unit of interface learned.
 - **Locality** — what maintainers get from depth: changes/bugs/knowledge/verification concentrate in one place.
@@ -31,10 +25,10 @@ A set of words about module shape, used to articulate "where it's worth changing
 ### 1. Explore (scope first, YAGNI)
 - If the user named a direction (module/subsystem/pain point), accept it; skip inference.
 - Otherwise walk `git log --oneline` for hot spots (files/areas that keep coming up).
-- Prefer reading live `<capability>.feature` (single-track SSOT) and `design.md` (existing ADRs); MUST NOT create a `CONTEXT.md`.
+- Prefer reading `<capability>.feature` (the single source of truth) and `design.md` (existing ADRs); MUST NOT create a `CONTEXT.md`.
 - Use the Agent tool (`subagent_type=Explore`) to walk the codebase, noting friction:
   - Does understanding one concept require bouncing between many small modules?
-  - Where are modules **shallow** (interface nearly as complex as the implementation)?
+  - Where are modules **shallow** (interface ≈ implementation complexity, callers save nothing)?
   - Where are pure functions extracted only for testability, but real bugs hide in how they're called (no locality)?
   - Which parts are untested or hard to test through their current interface?
 
@@ -46,20 +40,19 @@ For each candidate:
 - **Benefits** — locality and leverage improvements; how tests get better.
 - **Recommendation strength** — `Strong` / `Worth exploring` / `Speculative`.
 
-**Deletion test**: for any suspected-shallow module, imagine deleting it — does complexity vanish (it's just a pass-through, no value) or reappear across N call sites (it's actually earning its keep)? "Reappears" is the signal you want.
+**Deletion test**: for any suspected-shallow module, imagine deleting it — does complexity vanish (it's just a pass-through) or reappear across N call sites (it's actually earning its keep)? "Reappears" is the signal you want.
 
 **ADR conflicts**: if a candidate contradicts an existing `design.md` decision, surface it only when the friction is real enough to warrant reopening, and mark it in the candidate.
 
-### 3. Grilling (after the user picks a candidate)
-Run `llman-sdd-explore`'s **grilling branch** (trigger "deep-dig") to walk the decision tree — constraints, dependencies, the deepened module's shape, what sits behind the seam, which tests survive.
+### 3. Deep-dive Q&A (after the user picks a candidate)
+Run `llman-sdd-explore`'s **deep-dive Q&A branch** (trigger "deep-dig") to walk the decision tree — constraints, dependencies, the deepened module's shape, what sits behind the seam, which tests survive.
 
-- A deepened module uses a concept not in the capability `.feature`? → update live `.feature` **only** if the change already has Branch binding and you are on the bound branch (Specs landing); otherwise STOP and route to `llman-sdd-propose` / `change start` — **never** edit live specs on the default branch.
+- The deepened module uses a concept not in the `.feature`? → update the `.feature` **only** if the change is branch-bound and you are on the bound branch; otherwise STOP and route to `llman-sdd-propose` / `change start` — **never** edit specs on the default branch.
 - User rejects the candidate with a load-bearing reason? → offer an ADR only when "hard to reverse + surprising without context + real trade-off" all hold; record in `design.md`.
 
 ## Output
-Candidate list (text; optional HTML report written to OS temp dir, not the repo) + the grilling decision record after the user picks one (write back to proposal; contract edits only via Specs landing into live `.feature`).
+Candidate list (text; optional HTML report written to the OS temp dir, not the repo) + the deep-dive decision record after the user picks one (write back to the proposal; contract edits only after landing on the bound branch into the `.feature`).
 
-> 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-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") }}