@llman-sdd/core 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {
@@ -9,7 +9,8 @@
     "directory": "packages/core"
   },
   "files": [
-    "src"
+    "src",
+    "templates"
   ],
   "type": "module",
   "exports": {
@@ -23,6 +24,10 @@
     "typecheck": "bun run --cwd ../.. typecheck"
   },
   "dependencies": {
+    "7z-wasm": "^1.2.0",
+    "@cucumber/gherkin": "^42.0.1",
+    "@cucumber/messages": "^34.2.1",
+    "nunjucks": "^3.2.4",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   },

package/templates/en/agents-root-stub.md

@@ -0,0 +1,9 @@
+# LLMAN Spec-Driven Development
+
+This project uses llman SDD. Read `llmanspec/config.yaml` for SDD command behavior configuration, and `llmanspec/AGENTS.md` for additional project-specific rules.
+
+## SDD Pipeline
+
+Use `/llman-sdd-explore` to get started, then follow the pipeline: `/llman-sdd-propose` → `/llman-sdd-apply` → `/llman-sdd-verify` → `/llman-sdd-archive`.
+
+Keep this managed block so `llman sdd init --update` can refresh it.

package/templates/en/llmanspec-agents-stub.md

@@ -0,0 +1,6 @@
+# llmanspec AGENTS.md
+
+This file is referenced by the root `AGENTS.md` managed block. Use it to add
+project-specific rules, context, or conventions that you want AI agents to follow.
+
+<!-- Add your rules below this line -->

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

@@ -0,0 +1,75 @@
+---
+name: "llman-sdd-apply-cycle"
+description: "Single closed-loop for one change: gate→implement→test→validate→verify→archive→commit. Manual trigger only. Agent MUST NOT auto-invoke."
+metadata:
+  version: "{{ llman_version }}"
+disable-model-invocation: true
+---
+
+# LLMAN SDD Apply Cycle
+
+End-to-end closed loop for one change (manual). Requires Branch binding and `readyToImplement=true`.
+
+**Manual trigger only**: `/skill:llman-sdd-apply-cycle <change-id>`
+
+## Workflow
+
+### 0) Gate + status
+```bash
+llman sdd show <change-id> --json --type change
+```
+> Stage gate: decide from `stage` / `readyToImplement` in `llman sdd show <id> --json --type change`; full decision table lives in llman-sdd-apply.
+
+- Must be on the bound non-default branch.
+- If `readyToImplement` is not true → STOP (finish Specs landing or `needs_specs_change: false`); **do not** finalize yet.
+- Track progress via `tasks.md` checkboxes (or `llman sdd list` task counts); still read `tasks.md`, proposal/design, and live `llmanspec/specs/**` on the bound branch (SSOT).
+
+### 1) Loop: implement → test
+For each incomplete task:
+1. Implement per task + live specs (minimal diff)
+2. Run `tasks[].test` if present
+3. On failure, fix and retry (same self-repair budget as `llman-sdd-apply`: cap 8 rounds)
+4. Check off `tasks.md` as `[x]`
+
+### 2) Validate
+```bash
+llman sdd validate <change-id> --strict --no-interactive
+```
+On failure, fix and retry (same self-repair budget as `llman-sdd-apply`: cap 8 rounds).
+
+### 3) Verify (recommended)
+Prefer `llman-sdd-verify` (or equivalent dual-axis self-check). CRITICAL → STOP; do not archive.
+
+### 4) Archive
+```bash
+llman sdd change finalize <change-id>
+```
+(dirty tree OK; auto merge (squash default) + docs rename + **auto commit** `archive(sdd): <change-id>` in one process. `--no-commit` skips the auto commit for manual/CI histories — then commit with `git add -A && git commit -m "archive(sdd): <change-id>"`.)
+
+`change checkpoint` is removed; the plain `change archive` command stays as a fallback (no checkpointed field required).
+
+### 5) Commit (see step 4)
+Finalize already auto-committed unless `--no-commit` was passed.
+
+### 6) Optional cleanup
+```bash
+git branch -D <feature-branch>   # after squash the branch is no longer an ancestor of main; -d gets refused
+```
+push / hosting PR only when the user explicitly asks.
+
+## Hard constraints
+- **Never ask** "should I continue" unless blocked.
+- **Never switch** changes until this one is archived and committed.
+- **Retry cap**: self-repair follows `llman-sdd-apply`'s 8-round budget (including the diagnose escalation path).
+- **Do not** author `changes/<id>/specs/` or use `change delta`.
+- **No default push/PR**.
+
+## Ethics Governance
+- `ethics.risk_level`: medium
+- `ethics.prohibited_actions`: implement/archive without `readyToImplement`, switching changes early, writing `changes/<id>/specs/`, commit without validation, default push/PR
+- `ethics.required_evidence`: `readyToImplement=true`, validate --strict pass, all tasks checked, finalize/archive success
+- `ethics.refusal_contract`: after 3 gate/validation failures, report blocker; do not force-archive
+- `ethics.escalation_policy`: if changing SDD workflow specs/templates, pause for user confirm before 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>`.

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

@@ -0,0 +1,126 @@
+---
+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."
+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?"**
+
+## 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"]
+
+    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`
+
+## 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).
+
+## 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.
+
+## 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/`.
+{{ 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.
+
+### 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
+
+Extract hard constraints from proposal.md and design.md decisions. 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)
+
+### 4) Implement tasks one by one (closed-loop execution)
+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. **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).
+
+**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`:
+
+- 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.
+
+### 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)
+
+> 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-arch-review.md

@@ -0,0 +1,65 @@
+---
+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."
+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.
+
+## 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):
+
+- **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).
+- **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.
+
+## Steps
+
+### 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`.
+- 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 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?
+
+### 2. Present candidates
+For each candidate:
+- **Files** — which files/modules are involved.
+- **Problem** — why the current architecture causes friction (use depth/leverage/locality).
+- **Solution** — plain-English description of what would change.
+- **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.
+
+**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.
+
+- 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.
+- 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`).
+
+> 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-archive.md

@@ -0,0 +1,85 @@
+---
+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."
+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.
+
+## Pipeline Position
+
+```mermaid
+flowchart LR
+    verify["llman-sdd-verify<br/>Verify"] --> archive
+    archive["★ llman-sdd-archive ★<br/>Archive (you are here)"]
+
+    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.
+
+## 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.
+- **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.
+
+## Steps
+
+### 0) Preflight
+- `git status --porcelain`: confirm working tree changes belong to completed changes.
+- If unexpected changes exist, handle them (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.
+
+### 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.
+- 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):
+    ```text
+    1. Implement live specs + code (working tree may stay dirty; commits on the branch are free — segmented or none)
+    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
+    ```
+    `--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).
+
+### 3) Full validation
+- After all archives complete: `llman sdd validate --all --strict --no-interactive`.
+- Confirm post-archive 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`.
+
+{{ 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/validation-hints") }}
+
+{{ unit("skills/structured-protocol") }}

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

@@ -0,0 +1,41 @@
+---
+name: "llman-sdd-continue"
+description: "Continue an existing llman SDD change by creating the next artifact."
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Continue
+
+Use this skill to 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) `proposal.md`
+   2) `design.md` (only if 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)
+
+{{ 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/validation-hints") }}
+
+{{ unit("skills/structured-protocol") }}

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

@@ -0,0 +1,64 @@
+---
+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."
+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.
+
+## 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"]
+
+    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
+
+## 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.
+
+## 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.
+
+### 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.
+
+### 2) Create the draft shell
+```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).
+
+### 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).
+
+> 💡 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/ethics-governance") }}

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

@@ -0,0 +1,78 @@
+---
+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."
+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.
+
+**IMPORTANT: 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.
+
+## 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"]
+
+    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
+
+## Stance
+- Curious, not prescriptive
+- Grounded in the actual codebase
+- Visual when helpful (ASCII diagrams)
+- Willing to 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.
+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.
+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.
+5. Explore options and tradeoffs (2–3 options).
+6. Assess change scale (triage) 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.
+
+## 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)
+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/structured-protocol") }}

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

@@ -0,0 +1,38 @@
+---
+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/."
+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.
+
+## 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`.
+
+## Steps
+
+1. Ask the user for a short description, change id (or derive), impacted capability, and confirm the final id.
+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).
+
+{{ 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/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}