@llman-sdd/core 0.3.0 → 0.5.0

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

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

package/templates/en/units/skills/cli-footer.md

@@ -0,0 +1,2 @@
+> 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/units/skills/git-native-flow-brief.md

@@ -1,9 +1,10 @@
-## Git-native lifecycle (brief)
+## Branch lifecycle (brief)
 
-Do not conflate **skill navigation** with the **Git-native lifecycle**. Full diagram: root `AGENTS.md` or the diagram inside `llman-sdd-propose`.
+**Skill navigation** ≠ **branch lifecycle**. Full diagram: root `AGENTS.md` or the one inside `llman-sdd-propose`.
 
 Hard rules:
-1. **First** Branch binding (`change start` / `attach`) → Full; **then** Specs landing (edit and commit `llmanspec/specs/**` on the bound branch).
-2. No live contract edits → `needs_specs_change: false`. Apply requires `readyToImplement=true`.
-3. Close-out: `change finalize` (auto commit `archive(sdd): <id>`; `--no-commit` to skip). `change checkpoint` is removed (calling it exits non-zero and points to finalize).
-4. **Do not** commit live specs on the default branch; if already attached, do not re-run `start`.
+1. **First** bind the branch (`change start` / `attach`) → full; **then** land specs (edit and commit `llmanspec/specs/**` on the bound branch).
+2. No contract edits → `needs_specs_change: false`. Enter apply when `stage=full` and the specs-landed gate passes; `readyToImplement=true` (all gates green) is the completion signal gating verify/finalize.
+3. Close-out: `change finalize` (auto commit `archive(sdd): <id>`; `--no-commit` to skip).
+4. **Do not** commit specs on the default branch; if already attached, do not re-run `start`.
+5. Worktree (optional): `change start --worktree` creates the branch in a dedicated worktree without hijacking the current checkout (`--base <branch>` records a non-default fork source); finalize runs in place when the target is held by another worktree (location annotated in output).

package/templates/en/units/skills/git-native-flow.md

@@ -1,6 +1,6 @@
-## Git-native lifecycle (full diagram)
+## Branch lifecycle (full diagram)
 
-Do not conflate two layers: the **Git-native lifecycle** (Branch binding → Specs landing → `readyToImplement`) vs **skill navigation** (explore→propose→apply→verify→archive). Specs landing is **not** a separate skill.
+Two layers, don't conflate them: the **branch lifecycle** (bind branch → land specs → `readyToImplement`) vs **skill navigation** (explore→propose→apply→verify→archive). Landing specs is **not** a separate skill.
 
 ```mermaid
 flowchart TB
@@ -10,21 +10,21 @@ flowchart TB
     B2["add tasks.md → planned"]
   end
 
-  subgraph gate_start["Branch binding"]
+  subgraph bind["Bind branch"]
     C{"Clean tree<br/>and on default branch?"}
     D["change start<br/>create sdd/&lt;id&gt; + write branch/base_branch/base_sha"]
     E["or manual checkout -b<br/>then change attach"]
   end
 
   subgraph specs_only["Only on this change branch"]
-    F["Edit live llmanspec/specs/** (.feature)"]
-    G["commit → Specs landing<br/>live merge-base...HEAD includes specs paths"]
+    F["Edit llmanspec/specs/** (.feature)"]
+    G["commit → land specs<br/>live merge-base...HEAD includes specs paths"]
   end
 
-  subgraph implement["Implement"]
+  subgraph implement["Implement & close"]
     H["apply: code per tasks<br/>may keep editing specs"]
     I["verify"]
-    J["finalize<br/>merge (squash default) → rename → auto commit archive(sdd): &lt;id&gt;<br/>specs first hit default branch"]
+    J["finalize: merge (squash default) → rename → auto commit archive(sdd): &lt;id&gt;<br/>specs first hit the target branch"]
   end
 
   A --> B1 --> B2 --> C
@@ -34,7 +34,17 @@ flowchart TB
 ```
 
 Hard rules:
-1. **First** `change start` / `attach` (Branch binding) to enter Full; **then** edit `llmanspec/specs/**` on the bound non-default branch and commit (Specs landing).
-2. For changes with no live contract edits, set frontmatter `needs_specs_change: false`. Enter apply only when `llman-sdd show <id> --json` has `readyToImplement=true` — `Full ∧` every `gateChecks` item passes (specs-landed = `specsLanded ∨ needs_specs_change=false`; ranges are live merge-bases, stored `base_sha` is audit-only).
-3. `change checkpoint` is removed (no mid-flight archive point; `change finalize` does not require a clean tree). Close-out is `llman-sdd change finalize <id>`: it auto-commits `archive(sdd): <id>` (impl diff + rename in one commit); `--no-commit` skips the auto commit for manual/CI histories. Commits on the change branch are free (segmented or finalize single-shot).
-4. **Do not** commit live specs to the default branch just to satisfy the clean-tree gate; if already attached, do not re-run `start`.
+1. **First** `change start` / `attach` to bind the branch (enter full); **then** edit `llmanspec/specs/**` on the bound non-default branch and commit (land specs).
+2. No contract edits → set frontmatter `needs_specs_change: false`. Enter apply when `stage=full` and the specs-landed gate passes (specsLanded ∨ needs_specs_change=false); `readyToImplement=true` (every gateChecks item green, incl. tasks-done) is the completion signal gating verify/finalize. Diff ranges are always live merge-bases; the stored `base_sha` is audit-only.
+3. Close-out is `llman-sdd change finalize <id>`: it auto-commits `archive(sdd): <id>` (impl diff + rename in one commit); `--no-commit` skips the auto commit. Commits on the change branch are free (segmented or finalize single-shot).
+4. **Do not** commit specs to the default branch just to satisfy the clean-tree gate; if already attached, do not re-run `start`.
+
+Worktree decision table:
+
+| Working style | Command | Criteria |
+|---|---|---|
+| Single checkout | `llman-sdd change start <id>` | On the default branch with a clean tree; switches this checkout to the new branch |
+| Keep current checkout / parallel changes | `llman-sdd change start <id> --worktree` | Branch lives in a dedicated worktree (`sdd.worktree_root` / `sdd.worktree_naming` config; default sibling of the repo root), current checkout untouched, output includes the worktree path; pair with `--base <branch>` for a non-default fork source |
+| Already on a feature branch (incl. manual wt/git-worktree) | `llman-sdd change attach <id>` | Branch already exists; `--base <branch>` records the fork source explicitly |
+
+finalize target location: when the target branch is held by another worktree, `llman-sdd change finalize <id>` / `llman-sdd change archive <id>` run the merge, rename and commit inside that worktree (output includes `executed in target worktree <path>`); a dirty holding worktree aborts with disposal options and zero writes.

package/templates/en/units/skills/human-readable-summary.md

@@ -1,10 +1,9 @@
 # Human-Readable Summary (mandatory)
 
-Every report, handoff, or gate output you produce in this workflow MUST open
-with a short human-readable summary block before any machine detail:
+Every report, handoff, or gate output MUST open with a short human-readable summary before any machine detail:
 
 - **Verdict** — one line (e.g. "all gates green" / "2 CRITICAL found").
 - **Risks** — up to three bullets, highest impact first.
 - **Decisions needed** — explicit asks, or "none".
 
-Keep it under ten lines; details belong below the fold.
+Under ten lines; details below the fold.

package/templates/en/units/skills/stage-guard.md

@@ -1,17 +1,17 @@
 ## Stage guard (`stage` / `readyToImplement`)
 
-Decide from authoritative JSON (never from vague "complete artifacts" wording):
+Decide from authoritative JSON (never from "artifacts look complete"):
 
 ```bash
-llman-sdd show <id> --json --type change
+llman-sdd show <id> --output json --type change
 ```
 
 Read: `stage`, `specsLanded`, `needsSpecsChange`, `readyToImplement`, `gateChecks` (per-item `pass` + one-line `hint` when failing).
 
 | Condition | Action |
 |-----------|--------|
-| `stage=draft` (proposal.md only) | STOP. Grow to Designed (add design.md) → Planned (add tasks.md) → Branch binding → Specs landing. Draft cannot apply/verify. If proposal+design+tasks exist but stage is still `draft`: tasks-without-design — add design.md first. **Do not** create `changes/<id>/specs/`; **do not** edit live specs on the default branch first. |
-| `stage=designed` (proposal + design) | Next: add tasks.md → `planned`. Run `change start` / `attach` (Branch binding) only after planning artifacts are complete. |
-| `stage=planned` (proposal + design + tasks) | STOP until binding: run `change start` / `attach` (Branch binding) → `full`. |
-| `stage=full` and `readyToImplement=false` | STOP. Finish Specs landing on the **bound branch** (edit `llmanspec/specs/**` and commit), or set `needs_specs_change: false`. **Do not** re-run `change start`. If specs on the bound branch were lost → checkout/recreate + `attach --force` if needed. |
-| `readyToImplement=true` | Pass apply/verify prerequisites. `changes/<id>/specs/` is expected to be **absent** — do not treat as missing. |
+| `stage=draft` (proposal.md only) | STOP. Grow: add design.md → designed, add tasks.md → planned, then bind the branch and land specs. Draft cannot apply/verify. If proposal+tasks exist but stage is still `draft` (tasks-without-design — design.md gates the stage): add design.md first. **Do not** create `changes/<id>/specs/`; **do not** edit specs on the default branch first. |
+| `stage=designed` (proposal + design) | Next: add tasks.md → `planned`. Bind (`change start` / `attach`) only after planning docs are complete. |
+| `stage=planned` (proposal + design + tasks) | STOP until bound: `change start` / `attach` → `full`. |
+| `stage=full` and `readyToImplement=false` | Read the failing `gateChecks` items. specs-landed gate failing → land specs on the **bound branch** (edit `llmanspec/specs/**` and commit), or set `needs_specs_change: false`; **do not** re-run `change start` (lost bound-branch specs → checkout/recreate + `attach --force` if needed). specs-landed gate green but tasks-done/validate/clean-tree failing → normal mid-implementation state: proceed with apply (check off tasks); do not treat it as a landing failure. |
+| `readyToImplement=true` | Completion signal: every gateChecks item green (tasks done + validate passed) — verify/finalize prerequisites met. `changes/<id>/specs/` is expected to be **absent** — do not treat as missing. |

package/templates/en/units/skills/structured-protocol.md

@@ -1,23 +1,20 @@
 ## Context
-- Check state before acting: change/spec status comes from `llman-sdd show/list/validate` output.
-- Locate relevant specs with `llman-sdd context --task --paths` before reading spec files.
+- Check state before acting: change/spec status comes from `llman-sdd show/list/validate`; locate relevant specs with `llman-sdd context --task --paths` before reading spec files.
 
 ## Goal
-- Reach one verifiable outcome for this command; report result paths and validation state.
+- Reach one verifiable outcome; report result paths and validation state.
 
 ## Constraints
-- Follow the hard rules in the skill body (not repeated here). Triage first: behavior-contract changes take the full SDD path, implementation-only changes take quick; when unsure choose full SDD.
-- Keep changes minimal; never force past a known validation failure.
+- Follow the skill body's hard rules (not repeated here). Classify first: behavior-contract changes take the full SDD path, implementation-only changes take quick; when unsure choose full SDD. Keep changes minimal; never force past a known validation failure.
 
 ## Workflow
-- Treat `llman-sdd` command output as the source of truth at every step; run `llman-sdd validate` after touching artifacts.
-- Command details: the generated command reference below, or `llman-sdd <cmd> --help`.
+- Treat `llman-sdd` command output as the source of truth at every step; run `llman-sdd validate` after touching artifacts. Command details: `llman-sdd <cmd> --help`.
 
 ## Decision Policy
 - Clarify high-impact ambiguity before proceeding; verify facts yourself, ask the user only for decisions.
 
 ## Output Contract
-- Human-readable summary first (conclusion / risks / decisions needed), machine detail after.
+- Human-readable summary first (verdict / risks / decisions needed), machine detail after.
 
 ## Ethics Governance
 - `ethics.risk_level`: low — reads/writes this repo and `llmanspec/` only, no outward-facing actions; a skill body may override.

package/templates/en/units/skills/validation-hints.md

@@ -1,7 +1,6 @@
 Validation fixes (single-track feature-as-spec):
 
-1) Missing header comments (`missing `# capability:`` header comment`):
-Every capability `.feature` (`llmanspec/specs/<capability>.feature` or `llmanspec/specs/<capability>/<capability>.feature`) MUST start with:
+1) Missing header comments (`missing # capability: header comment`): every capability `.feature` (`llmanspec/specs/<capability>.feature` or the same-named main file in a directory) MUST start with:
 ```
 # language: zh-CN
 # capability: <capability>
@@ -9,16 +8,13 @@ Every capability `.feature` (`llmanspec/specs/<capability>.feature` or `llmanspe
 # scope: src/
 ```
 
-2) Tag grammar (`@human constraint scenario must carry an @req:<req_id> tag` / `orphan acceptance scenario`):
-- Rules: `@req:<id> @human` — statement in the scenario description (MUST/SHALL required).
-- Acceptance: `@executable` + at least one `@req:<id>` linking a rule.
-Never combine `@human` with `@executable`. (`@manual` was removed in 0.3.0 — drop it; `@human` already carries the human-judgement semantics.)
+2) Native layout (`rule must carry an @req:<req_id> tag on the rule header`):
+- One canonical style: `@req:<id>` on the `规则:` block header, nested `场景:` (Given/When/Then) as executable examples — the default preferred shape.
+- Only keep a `规则:` block with no nested scenario (bare rule) for requirements that cannot be expressed programmatically or are not yet converted: free-text description, no MUST/SHALL enforcement; validate reports an aggregate count, the review `pending` signal measures it, specs-compact keeps reducing it.
+- Legacy tags `@executable`/`@rule`/`@human`/`@manual` are gone and parse inert; when old files hit structural problems run `llman-sdd spec migrate-native`.
+- Top-level `场景:` outside any `规则:` are plain feature-level examples: no rule handle, no warning, not part of rule accounting (native Gherkin).
 
-3) Legacy `spec.toon` present (`legacy spec.toon found ... run ... toon2features`):
-Run `llman-sdd project migrate --kind toon2features --yes`, review the diff, commit.
-
-Git-native guardrail:
-- **Branch binding** → **Specs landing**: first `change start` / `attach`, then edit live `.feature` files on the bound non-default branch and commit.
-- Locked rules (report-only): editing/removing an existing `@human` scenario yields a WARNING and never blocks validate / change finalize / change diff; the report names the edited rule by `@req:<id>`. Control points: git branch diff plus `llman-sdd review` / `change diff` output. Legacy lock-ack metadata (frontmatter `rules_touched` / `agent_acked`, the `@agent` tag, the `--yes` ack semantics) is fully removed — no aliases, no compat layer (locked rules are report-only: a warning, never a block).
-- Apply requires `readyToImplement=true` (or `needs_specs_change: false`). Close-out prefers `change finalize`.
-- Do not use `change delta` / solidify / `*.feature.delta.toon`.
+Branch guardrail:
+- First `change start` / `attach` to bind the branch, then edit `.feature` on the bound non-default branch and commit (land specs).
+- Locked rules (report-only): editing/removing an existing `规则:` block yields a WARNING and never blocks validate / finalize / `change diff`; the report names the rule by `@req:<id>`. Control points: git branch diff plus `llman-sdd review` / `change diff`. Legacy lock-ack metadata (frontmatter `rules_touched` / `agent_acked`, the `@agent` tag, the `--yes` ack semantics) is fully removed — no aliases, no compat layer.
+- Enter apply when `stage=full` and the specs-landed gate passes (specsLanded ∨ `needs_specs_change: false`); verify/finalize require `readyToImplement=true` (completion signal). Close-out prefers `change finalize`.

package/templates/en/units/spec/feature-contract.md

@@ -1,7 +1,8 @@
-## Canonical Single-Track Feature Contract
+## Canonical Single-Track Feature Contract (native Gherkin layout)
 
-Each capability is ONE Gherkin file: flat `llmanspec/specs/<capability>.feature` (default) or directory `llmanspec/specs/<capability>/` with a same-named main file — pick one layout, both at once is a conflict.
-It is the only spec artifact — there is no `spec.toon`.
+Each capability is ONE Gherkin file: flat `llmanspec/specs/<capability>.feature` (default) or directory `llmanspec/specs/<capability>/` with a same-named main file — pick one layout; both at once is a conflict. It is the only spec artifact (there is no `spec.toon`).
+
+The format is the **native Gherkin hierarchy**: `功能:` → `规则:` (the requirement: title + free-form description + `@req:<id>` handle) → nested `场景:` (executable GWT examples). This is the only canonical style; legacy tags (`@executable`/`@rule`/`@human`/`@manual`) are gone — migrate old files with `spec migrate-native`.
 
 ```gherkin
 # language: zh-CN
@@ -11,19 +12,29 @@ It is the only spec artifact — there is no `spec.toon`.
 
 功能: sample
 
-  @req:r1 @human
-  场景: Rule title
-    System MUST do something.
+  @req:r1
+  规则: A requirement point
+    Free-text requirement (no MUST/SHALL enforcement); wrap long text across
+    lines for human/agent readability. A description line must not begin with
+    a step keyword (would be parsed as a step).
+
+    场景: An executable example
+      假如 a precondition
+      当 a trigger happens
+      那么 the outcome is observed
 
-  @req:r1 @executable
-  场景: happy
-    假如 a precondition
-    当 a trigger happens
-    那么 the outcome is observed
+  @req:r2
+  规则: Not-yet-converted requirement (bare rule — counted by the aggregate nudges)
+    This description is the only carrier of the requirement today. Rules with
+    no nested scenario are counted as bare; specs-compact keeps driving them
+    down or converting them.
 ```
 
-- Header comments (`# capability:` / `# purpose:` / `# scope:`) are REQUIRED; `scope` drives staleness.
-- `@human` scenarios are human-owned constraints; their description carries the normative statement verbatim. Editing/removing them yields a WARNING only (report-only, never blocks a gate) — compare via git branch diff; the legacy lock-ack metadata `rules_touched` / `agent_acked` / `@agent` is removed with no aliases and no compat layer (locked rules are report-only: a warning, never a block).
-- `@executable` scenarios are runner-bound acceptance; they link rules via `@req:<req_id>`.
-- Coverage tiers: enforced (has acceptance) / pending. `list --specs` reports both.
-- Scenarios MUST stay top-level: `Rule:` blocks are rejected (the runner skips them silently).
+- Header comments (`# capability:` / `# purpose:` / `# scope:`) are REQUIRED; `scope` drives staleness checks.
+- **Executable scenarios preferred**: express behavior as nested `场景:` (`Given/When/Then`) bound to BDD step code and executed by the runner — the default. Only use a `规则:` block without executable scenarios for requirements that cannot be expressed programmatically (abstract goals, architecture decisions, governance/human judgment) or are not yet converted; record the rationale in proposal/design.
+- `@req:<id>` lives on the `规则:` block header: the global unique requirement handle (shared by resolve-req/next-req-id/citation). Missing or duplicate ids are validate ERRORs.
+- Rule description is free text: no MUST/SHALL enforcement; wrap long text across lines for reviewability, with no `- ` list marker (it would enter the description verbatim).
+- Top-level `场景:` outside any `规则:` are plain feature-level examples (native Gherkin allows them; no rule handle, no warning, not part of rule accounting); rules with no nested scenario are bare rules (aggregate INFO via `--include-info`; the review `pending` signal measures them).
+- Editing/removing an existing `规则:` block yields a WARNING only (report-only, never blocks a gate) — compare via git branch diff; the legacy lock-ack metadata `rules_touched` / `agent_acked` / `@agent` is removed with no aliases and no compat layer.
+- Coverage tiers: enforced (has nested scenarios) / pending (bare) — `list --specs` reports both.
+- `规则:` blocks are containers: nested `场景:` are executed by the runner; two-space indent tiers (`规则:` 2, nested `场景:` 4, steps 6).

package/templates/en/units/workflow/archive-freeze-guidance.md

@@ -1,6 +1,9 @@
 ## Archive Cold Backup Guidance
-- If archived directories are growing too large, use cold backup maintenance:
+- When archived directories grow too large, use cold backup maintenance (freeze moves bodies into the 7z cold backup and replaces the dir with a flat `<YYYY-MM-DD>-<id>.yaml` index card carrying only `title` and `depends_on`):
   - Preview freeze candidates: `llman-sdd archive freeze --dry-run`
   - Freeze old archives: `llman-sdd archive freeze --before <YYYY-MM-DD> --keep-recent <N>`
-  - Restore when needed: `llman-sdd archive thaw --change <YYYY-MM-DD-id>`
-- Apply freeze/thaw only to dated archive directories (`YYYY-MM-DD-*`) and keep a small recent window unfrozen when possible.
+  - List frozen entries: `llman-sdd archive freeze --list`
+  - Restore when needed: `llman-sdd archive thaw --change <YYYY-MM-DD-id>` (extracts bodies back and removes the card)
+- Apply freeze/thaw only to dated archive directories (`YYYY-MM-DD-*`); keep a small recent window unfrozen.
+- The flat index card stays on disk: `title` (from the proposal H1) and `depends_on` (seed for graph dependency edges) are grep-able and traceable; the id and date are implied by the file name — the purpose and dependencies of a frozen change are inspectable without thawing, while bodies live in the 7z cold backup and are fetched on demand.
+- Running outside the main checkout (a worktree not holding the default branch) prints a warning (never blocks) — continue there only intentionally.

package/templates/zh-Hans/skills/llman-sdd-apply-cycle.md

@@ -1,6 +1,6 @@
 ---
 name: "llman-sdd-apply-cycle"
-description: "单个变更的闭环：门禁检查→实施→测试→校验→verify 建议→归档→提交。仅手动触发。Agent MUST NOT 自动调用。"
+description: "单 change 端到端闭环：实施→测试→校验→verify→归档提交。仅手动触发，agent 禁止自动调用。"
 metadata:
   version: "{{ llman_version }}"
 disable-model-invocation: true
@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 # LLMAN SDD Apply Cycle
 
-单个变更端到端闭环（手动）。须已 Branch binding 且 `readyToImplement=true`。
+单 change 端到端闭环（手动）。须已绑定分支且 specs-landed 门通过（`specsLanded ∨ needsSpecsChange=false`）；`readyToImplement=true`（完成信号）收拢闭环。
 
 **仅手动触发**：`/skill:llman-sdd-apply-cycle <change-id>`
 
@@ -16,60 +16,52 @@ disable-model-invocation: true
 
 ### 0) 门禁 + 状态
 ```bash
-llman-sdd show <change-id> --json --type change
+llman-sdd show <change-id> --output json --type change
 ```
-> 阶段判定：用 `llman-sdd show <id> --json --type change` 的 `stage` / `readyToImplement` 字段；完整判定表见 llman-sdd-apply。
+> 阶段判定用 `stage` / `readyToImplement` 字段；完整判定表见 llman-sdd-apply。
 
 - 须在绑定的非默认分支上。
-- `readyToImplement` 不为 true → STOP（先 Specs landing 或 `needs_specs_change: false`）；**不要**直接 finalize。
-- 进度以 `tasks.md` checkbox 为准（或 `llman-sdd list` 的任务计数）；实现时仍须阅读 `tasks.md`、proposal/design 与绑定分支上的 live `llmanspec/specs/**`（SSOT）。
+- specs-landed 门未过 → STOP（先落地 specs 或 `needs_specs_change: false`）。已绿但 `readyToImplement=false` → 正常：tasks 待完成，继续实施；**仅当 `readyToImplement=true` 才 finalize**。
+- 进度以 `tasks.md` checkbox 为准（或 `llman-sdd list` 任务计数）；实现时仍须读 `tasks.md`、proposal/design 与绑定分支上的 `llmanspec/specs/**`（唯一事实来源）。
 
 ### 1) 循环：实施 → 测试
 对每个未完成 task：
-1. 按 task + live specs 实现（最小改动）
-2. 运行 `tasks[].test`（若有）
-3. 失败则修复重试（自修复预算与 `llman-sdd-apply` 一致：上限 8 轮）
+1. 按 task + specs 实现（最小改动）
+2. task 文本写明验证命令时运行之
+3. 失败修复重试（自修复预算同 `llman-sdd-apply`：上限 8 轮）
 4. 勾选 `tasks.md` 为 `[x]`
 
 ### 2) 校验
 ```bash
-llman-sdd validate <change-id> --strict --no-interactive
+llman-sdd validate <change-id> --strict
 ```
-失败则修复重试（自修复预算与 `llman-sdd-apply` 一致：上限 8 轮）。
+失败修复重试（上限 8 轮）。
 
 ### 3) Verify（推荐）
 优先跑 `llman-sdd-verify`（或等效双轴自检）。有 CRITICAL → STOP，勿归档。
 
-### 4) 归档
+### 4) 归档 + 提交
 ```bash
 llman-sdd change finalize <change-id>
 ```
-（工作区可脏；自动合并（squash 缺省）+ 文档改名 + **自动提交** `archive(sdd): <change-id>` 单进程完成。`--no-commit` 跳过自动提交用于手动/CI 历史——此时自行 `git add -A && git commit -m "archive(sdd): <change-id>"`。）
+工作区可脏；自动合并（默认 squash）+ 改名 + **自动提交** `archive(sdd): <change-id>` 单进程完成。`--no-commit` 跳过自动提交（手动/CI 历史）——此时自行 `git add -A && git commit -m "archive(sdd): <change-id>"`。普通 `change archive` 保留为 fallback。
 
-`change checkpoint` 已移除；普通 `change archive` 命令保留为 fallback（不再要求任何 checkpointed 字段）。
-
-### 5) 提交（见步骤 4）
-finalize 已自动提交，除非传了 `--no-commit`。
-
-### 6) 可选清理
+### 5) 可选清理
 ```bash
-git branch -D <feature-branch>   # squash 后分支不再是 main 祖先，-d 会被拒绝
+git branch -D <feature-branch>   # squash 后分支不再是 main 祖先，-d 会被拒
 ```
-push / Hosting PR 仅当用户明确要求。
+push / PR 仅当用户明确要求。
 
 ## 硬约束
-- **禁止询问**「要不要继续」——除非 blocker，否则一路到底。
-- **禁止切换**其他 change，直到本 change 已归档并提交。
-- **重试上限**：自修复遵循 `llman-sdd-apply` 的 8 轮预算（含 diagnose 升级路径）。
-- **禁止**写 `changes/<id>/specs/` 或 `change delta`。
-- **禁止默认 push/PR**。
+- **禁止问**「要不要继续」——除非 blocker，一路到底。
+- **禁止切换**其他 change，直到本 change 归档并提交。
+- **禁止**写 `changes/<id>/specs/`；**禁止默认 push/PR**。
 
 ## Ethics Governance
 - `ethics.risk_level`: medium
-- `ethics.prohibited_actions`: 未 `readyToImplement` 就实施/归档、切换其他 change、写 `changes/<id>/specs/`、未校验就提交、默认 push/PR
+- `ethics.prohibited_actions`: 未绑定分支 / specs-landed 门未过就实施、未 `readyToImplement=true` 就归档、中途切换 change、写 `changes/<id>/specs/`、未校验就提交、默认 push/PR
 - `ethics.required_evidence`: `readyToImplement=true`、validate --strict 通过、tasks 全勾、finalize/archive 成功
-- `ethics.refusal_contract`: 门禁或校验自修复 8 轮仍失败 → 报告 blocker，禁止强行归档
-- `ethics.escalation_policy`: 若改动 SDD 工作流 spec/模板，归档前暂停请用户确认
+- `ethics.refusal_contract`: 自修复 8 轮仍失败 → 报告 blocker，禁止强行归档
+- `ethics.escalation_policy`: 改动 SDD 工作流 spec/模板时，归档前暂停请用户确认
 
-> 命令细节用 `llman-sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
-> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman-sdd list --specs` / `llman-sdd show <capability>` 查全文。
+{{ unit("skills/cli-footer") }}