codexspec 0.7.8__tar.gz → 0.7.10__tar.gz

{codexspec-0.7.8 → codexspec-0.7.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.8
+Version: 0.7.10
 Summary: CodexSpec - A Requirements-First SDD toolkit for Claude Code
 Project-URL: Homepage, https://github.com/Zts0hg/codexspec
 Project-URL: Repository, https://github.com/Zts0hg/codexspec
@@ -166,9 +166,12 @@ CodexSpec is built on the belief that **effective AI-assisted development requir
 CodexSpec structures development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
-                                                   │                         │                            │
-                                              Review spec               Review plan                  Review tasks
+Idea → /specify           → requirements.md
+     → /generate-spec      → spec.md      → review-spec
+     → /spec-to-design     → design.md    → review-design
+     → /spec-to-plan       → plan.md      → review-plan
+     → /plan-to-tasks      → tasks.md     → review-tasks
+     → /implement-tasks    → code
 ```
 
 Confirmed requirements are the highest-priority feature authority. Derived artifacts carry explicit source links so conflicts can be traced back instead of silently propagated.
@@ -176,6 +179,7 @@ Confirmed requirements are the highest-priority feature authority. Derived artif
 **Every generated artifact has a corresponding review command:**
 
 - `spec.md` → `/codexspec:review-spec`
+- `design.md` → `/codexspec:review-design`
 - `plan.md` → `/codexspec:review-plan`
 - `tasks.md` → `/codexspec:review-tasks`
 - All artifacts → `/codexspec:analyze`
@@ -207,6 +211,7 @@ claude
 > /codexspec:constitution Create principles focused on code quality and testing
 > /codexspec:specify I want to build a todo application
 > /codexspec:generate-spec
+> /codexspec:spec-to-design
 > /codexspec:spec-to-plan
 > /codexspec:plan-to-tasks
 > /codexspec:implement-tasks
@@ -355,9 +360,12 @@ The config command will guide you through:
 CodexSpec breaks development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
-                                                   │                         │                            │
-                                              Review spec               Review plan                  Review tasks
+Idea → /specify           → requirements.md
+     → /generate-spec      → spec.md      → review-spec
+     → /spec-to-design     → design.md    → review-design
+     → /spec-to-plan       → plan.md      → review-plan
+     → /plan-to-tasks      → tasks.md     → review-tasks
+     → /implement-tasks    → code
 ```
 
 ### Workflow Steps
@@ -367,10 +375,11 @@ Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-t
 | 1. Project Principles        | `/codexspec:constitution`    | `constitution.md`           | ✅           |
 | 2. Requirement Clarification | `/codexspec:specify`         | `requirements.md`           | ✅           |
 | 3. Generate Spec             | `/codexspec:generate-spec`   | `spec.md` + auto-review     | ✅           |
-| 4. Technical Planning        | `/codexspec:spec-to-plan`    | `plan.md` + auto-review     | ✅           |
-| 5. Task Breakdown            | `/codexspec:plan-to-tasks`   | `tasks.md` + auto-review    | ✅           |
-| 6. Cross-Artifact Analysis   | `/codexspec:analyze`         | Analysis report             | ✅           |
-| 7. Implementation            | `/codexspec:implement-tasks` | Code                        | -           |
+| 4. System Design             | `/codexspec:spec-to-design`  | `design.md` + auto-review   | ✅           |
+| 5. Technical Planning        | `/codexspec:spec-to-plan`    | `plan.md` + auto-review     | ✅           |
+| 6. Task Breakdown            | `/codexspec:plan-to-tasks`   | `tasks.md` + auto-review    | ✅           |
+| 7. Cross-Artifact Analysis   | `/codexspec:analyze`         | Analysis report             | ✅           |
+| 8. Implementation            | `/codexspec:implement-tasks` | Code                        | -           |
 
 ### specify vs clarify: When to Use Which?
 
@@ -568,7 +577,8 @@ Implementation follows **conditional TDD workflow**:
 | `/codexspec:constitution`    | Create/update project constitution with cross-artifact validation |
 | `/codexspec:specify`         | Clarify, confirm, and persist requirements in `requirements.md`    |
 | `/codexspec:generate-spec`   | Generate `spec.md` document ★ Auto-review                         |
-| `/codexspec:spec-to-plan`    | Convert spec to technical plan ★ Auto-review                      |
+| `/codexspec:spec-to-design`  | Produce `design.md` (architecture/components/decisions) ★ Auto-review |
+| `/codexspec:spec-to-plan`    | Convert design to implementation plan ★ Auto-review              |
 | `/codexspec:plan-to-tasks`   | Break down plan into traceable, verifiable tasks ★ Auto-review    |
 | `/codexspec:implement-tasks` | Execute tasks (conditional TDD)                                   |
 
@@ -577,6 +587,7 @@ Implementation follows **conditional TDD workflow**:
 | Command                   | Description                            |
 | ------------------------- | -------------------------------------- |
 | `/codexspec:review-spec`  | Review specification (auto or manual)  |
+| `/codexspec:review-design` | Review design (auto or manual)        |
 | `/codexspec:review-plan`  | Review technical plan (auto or manual) |
 | `/codexspec:review-tasks` | Review task breakdown (auto or manual) |
 
@@ -604,6 +615,7 @@ Implementation follows **conditional TDD workflow**:
 | -------------------------- | ------------------------------------------------- |
 | `/codexspec:commit-staged` | Generate commit message from staged changes       |
 | `/codexspec:pr`            | Generate PR/MR description (auto-detect platform) |
+| `/codexspec:release-notes` | Generate release notes from git history (maintain CHANGELOG.md + release body)|
 
 #### Code Review Commands
 

{codexspec-0.7.8 → codexspec-0.7.10}/README.md

@@ -121,9 +121,12 @@ CodexSpec is built on the belief that **effective AI-assisted development requir
 CodexSpec structures development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
-                                                   │                         │                            │
-                                              Review spec               Review plan                  Review tasks
+Idea → /specify           → requirements.md
+     → /generate-spec      → spec.md      → review-spec
+     → /spec-to-design     → design.md    → review-design
+     → /spec-to-plan       → plan.md      → review-plan
+     → /plan-to-tasks      → tasks.md     → review-tasks
+     → /implement-tasks    → code
 ```
 
 Confirmed requirements are the highest-priority feature authority. Derived artifacts carry explicit source links so conflicts can be traced back instead of silently propagated.
@@ -131,6 +134,7 @@ Confirmed requirements are the highest-priority feature authority. Derived artif
 **Every generated artifact has a corresponding review command:**
 
 - `spec.md` → `/codexspec:review-spec`
+- `design.md` → `/codexspec:review-design`
 - `plan.md` → `/codexspec:review-plan`
 - `tasks.md` → `/codexspec:review-tasks`
 - All artifacts → `/codexspec:analyze`
@@ -162,6 +166,7 @@ claude
 > /codexspec:constitution Create principles focused on code quality and testing
 > /codexspec:specify I want to build a todo application
 > /codexspec:generate-spec
+> /codexspec:spec-to-design
 > /codexspec:spec-to-plan
 > /codexspec:plan-to-tasks
 > /codexspec:implement-tasks
@@ -310,9 +315,12 @@ The config command will guide you through:
 CodexSpec breaks development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
-                                                   │                         │                            │
-                                              Review spec               Review plan                  Review tasks
+Idea → /specify           → requirements.md
+     → /generate-spec      → spec.md      → review-spec
+     → /spec-to-design     → design.md    → review-design
+     → /spec-to-plan       → plan.md      → review-plan
+     → /plan-to-tasks      → tasks.md     → review-tasks
+     → /implement-tasks    → code
 ```
 
 ### Workflow Steps
@@ -322,10 +330,11 @@ Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-t
 | 1. Project Principles        | `/codexspec:constitution`    | `constitution.md`           | ✅           |
 | 2. Requirement Clarification | `/codexspec:specify`         | `requirements.md`           | ✅           |
 | 3. Generate Spec             | `/codexspec:generate-spec`   | `spec.md` + auto-review     | ✅           |
-| 4. Technical Planning        | `/codexspec:spec-to-plan`    | `plan.md` + auto-review     | ✅           |
-| 5. Task Breakdown            | `/codexspec:plan-to-tasks`   | `tasks.md` + auto-review    | ✅           |
-| 6. Cross-Artifact Analysis   | `/codexspec:analyze`         | Analysis report             | ✅           |
-| 7. Implementation            | `/codexspec:implement-tasks` | Code                        | -           |
+| 4. System Design             | `/codexspec:spec-to-design`  | `design.md` + auto-review   | ✅           |
+| 5. Technical Planning        | `/codexspec:spec-to-plan`    | `plan.md` + auto-review     | ✅           |
+| 6. Task Breakdown            | `/codexspec:plan-to-tasks`   | `tasks.md` + auto-review    | ✅           |
+| 7. Cross-Artifact Analysis   | `/codexspec:analyze`         | Analysis report             | ✅           |
+| 8. Implementation            | `/codexspec:implement-tasks` | Code                        | -           |
 
 ### specify vs clarify: When to Use Which?
 
@@ -523,7 +532,8 @@ Implementation follows **conditional TDD workflow**:
 | `/codexspec:constitution`    | Create/update project constitution with cross-artifact validation |
 | `/codexspec:specify`         | Clarify, confirm, and persist requirements in `requirements.md`    |
 | `/codexspec:generate-spec`   | Generate `spec.md` document ★ Auto-review                         |
-| `/codexspec:spec-to-plan`    | Convert spec to technical plan ★ Auto-review                      |
+| `/codexspec:spec-to-design`  | Produce `design.md` (architecture/components/decisions) ★ Auto-review |
+| `/codexspec:spec-to-plan`    | Convert design to implementation plan ★ Auto-review              |
 | `/codexspec:plan-to-tasks`   | Break down plan into traceable, verifiable tasks ★ Auto-review    |
 | `/codexspec:implement-tasks` | Execute tasks (conditional TDD)                                   |
 
@@ -532,6 +542,7 @@ Implementation follows **conditional TDD workflow**:
 | Command                   | Description                            |
 | ------------------------- | -------------------------------------- |
 | `/codexspec:review-spec`  | Review specification (auto or manual)  |
+| `/codexspec:review-design` | Review design (auto or manual)        |
 | `/codexspec:review-plan`  | Review technical plan (auto or manual) |
 | `/codexspec:review-tasks` | Review task breakdown (auto or manual) |
 
@@ -559,6 +570,7 @@ Implementation follows **conditional TDD workflow**:
 | -------------------------- | ------------------------------------------------- |
 | `/codexspec:commit-staged` | Generate commit message from staged changes       |
 | `/codexspec:pr`            | Generate PR/MR description (auto-detect platform) |
+| `/codexspec:release-notes` | Generate release notes from git history (maintain CHANGELOG.md + release body)|
 
 #### Code Review Commands
 

{codexspec-0.7.8 → codexspec-0.7.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.7.8"
+version = "0.7.10"
 description = "CodexSpec - A Requirements-First SDD toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"

{codexspec-0.7.8 → codexspec-0.7.10}/src/codexspec/__init__.py

@@ -44,7 +44,7 @@ from .profile import ensure_profile_scaffold, inject_profile_block
 from .translator import SUPPORTED_LANGUAGES, translate
 
 # Version info
-__version__ = "0.7.8"
+__version__ = "0.7.10"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants

{codexspec-0.7.8 → codexspec-0.7.10}/src/codexspec/commands/installer.py

@@ -47,11 +47,11 @@ def get_commands_metadata() -> list[CommandMetadata]:
 
     Returns:
         List of CommandMetadata dictionaries sorted by category priority:
-        core (9) -> enhanced (7) -> git (2) -> review (1) -> utility (2)
-        Total: 21 commands
+        core (11) -> enhanced (7) -> git (3) -> review (1) -> utility (2)
+        Total: 24 commands
     """
     return [
-        # Core Commands (9)
+        # Core Commands (11)
         {
             "name": "constitution",
             "display_name": "/codexspec:constitution",
@@ -73,10 +73,17 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "core",
             "file_name": "generate-spec.md",
         },
+        {
+            "name": "spec-to-design",
+            "display_name": "/codexspec:spec-to-design",
+            "description": "将已确认的规格转换为可追溯的设计文档（架构/组件/关键设计决策）",
+            "category": "core",
+            "file_name": "spec-to-design.md",
+        },
         {
             "name": "spec-to-plan",
             "display_name": "/codexspec:spec-to-plan",
-            "description": "将已确认的规格转换为可追溯的技术计划",
+            "description": "将已确认的设计转换为可追溯的实现计划",
             "category": "core",
             "file_name": "spec-to-plan.md",
         },
@@ -94,6 +101,13 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "core",
             "file_name": "review-spec.md",
         },
+        {
+            "name": "review-design",
+            "display_name": "/codexspec:review-design",
+            "description": "审查设计的忠实度、可行性与规划就绪度",
+            "category": "core",
+            "file_name": "review-design.md",
+        },
         {
             "name": "review-plan",
             "display_name": "/codexspec:review-plan",
@@ -165,7 +179,7 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "enhanced",
             "file_name": "debug.md",
         },
-        # Git Workflow Commands (2)
+        # Git Workflow Commands (3)
         {
             "name": "commit-staged",
             "display_name": "/codexspec:commit-staged",
@@ -180,6 +194,13 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "git",
             "file_name": "pr.md",
         },
+        {
+            "name": "release-notes",
+            "display_name": "/codexspec:release-notes",
+            "description": "从 git 历史生成发布说明：更新 CHANGELOG.md + 用户向发布正文（不决定版本）",
+            "category": "git",
+            "file_name": "release-notes.md",
+        },
         # Code Review Commands (1)
         {
             "name": "review-code",

{codexspec-0.7.8 → codexspec-0.7.10}/src/codexspec/integrations/codex.py

@@ -115,6 +115,7 @@ Use these Codex skills when working on CodexSpec workflows:
 - `$codexspec:constitution` to create or update project principles.
 - `$codexspec:specify` to capture confirmed requirements.
 - `$codexspec:generate-spec` to produce `spec.md`.
+- `$codexspec:spec-to-design` to produce `design.md`.
 - `$codexspec:spec-to-plan` to produce `plan.md`.
 - `$codexspec:plan-to-tasks` to produce `tasks.md`.
 - `$codexspec:implement-tasks` to implement approved tasks.

{codexspec-0.7.8 → codexspec-0.7.10}/templates/commands/analyze.md

@@ -22,7 +22,7 @@ Converse in the interaction language and author artifacts in the document langua
 
 This command detects cross-artifact inconsistencies **and auto-remediates them**. It is not read-only.
 
-- `requirements.md` is the single source of truth. analyze **never modifies `requirements.md`**. Every fix conforms the downstream artifacts (`spec.md`, `plan.md`, `tasks.md`) to `requirements.md`; the fix direction is uniquely determined by the authority hierarchy (requirements > spec > plan > tasks) and never requires inventing intent.
+- `requirements.md` is the single source of truth. analyze **never modifies `requirements.md`**. Every fix conforms the downstream artifacts (`spec.md`, `design.md`, `plan.md`, `tasks.md`) to `requirements.md`; the fix direction is uniquely determined by the authority hierarchy (requirements > spec > design > plan > tasks) and never requires inventing intent.
 - Auto-apply deterministic, authority-directed fixes **by default** — both when invoked manually and when invoked inside the `auto_next` chain — with no confirmation prompt and no human-escalation path.
 
 Resolve the feature by explicit path, then current branch. Ask the user if it is ambiguous; never select the latest feature silently.
@@ -33,10 +33,13 @@ Load:
 
 - `requirements.md`
 - `spec.md`
+- `design.md`
 - `plan.md`
 - `tasks.md`
 - Constitution
 
+A legacy feature may have no `design.md`; when it is absent, analyze the chain without the design link and proceed.
+
 Legacy compatibility: if `requirements.md` is missing, state that the analysis starts at `spec.md` and cannot validate fidelity to the original discussion. In legacy mode there is no source of truth to conform to, so do not auto-modify artifacts; report findings only.
 
 ## End-to-End Traceability
@@ -46,7 +49,8 @@ Build the chain:
 ```text
 confirmed NEED/CON/DEC/OUT
   -> REQ/NFR Sources
-  -> plan Covers
+  -> design Covers
+  -> plan Covers (Covers: REQ; Design: <component>)
   -> task Covers + Plan reference
 ```
 
@@ -54,7 +58,8 @@ Detect:
 
 - Confirmed requirements with no spec coverage
 - Spec requirements with missing or invalid sources
-- Spec requirements with no plan coverage
+- Spec requirements with no design coverage
+- Design components with no plan coverage
 - Plan deliverables with no task coverage
 - Tasks with no upstream authority or implementation-support justification
 - Semantic drift, scope expansion, contradictions, and use of superseded/open entries
@@ -89,7 +94,7 @@ Produce:
 
 - Authority mode
 - End-to-end coverage table
-- Applied remediations: the exact downstream edits made to `spec.md`/`plan.md`/`tasks.md` and why, or "none"
+- Applied remediations: the exact downstream edits made to `spec.md`/`design.md`/`plan.md`/`tasks.md` and why, or "none"
 - Verified defects by severity that were not auto-remediable (for example, a reported-only tie-break conflict)
 - Unmapped or unauthorized items
 - Risk Advisories

{codexspec-0.7.8 → codexspec-0.7.10}/templates/commands/generate-spec.md

@@ -101,8 +101,8 @@ Read `workflow.auto_next` from `.codexspec/config.yml` (default `false`; only th
 
 When `workflow.auto_next` is `true` AND the Automatic Review Loop above concluded in a passing state — the final Overall Status is `PASS` or `PASS_WITH_WARNINGS` — advance the chain automatically:
 
-1. Emit exactly one notice line, in the interaction language, e.g. `auto_next: review passed → invoking /codexspec:spec-to-plan <feature-dir>`.
-2. Invoke `/codexspec:spec-to-plan <feature-dir>` exactly once, then end this command.
+1. Emit exactly one notice line, in the interaction language, e.g. `auto_next: review passed → invoking /codexspec:spec-to-design <feature-dir>`.
+2. Invoke `/codexspec:spec-to-design <feature-dir>` exactly once, then end this command.
 
 Do not auto-advance when `workflow.auto_next` is disabled, or the review loop stopped at `NEEDS_REVISION` or `BLOCKED`, or stopped early per the conditions above; in those cases hand control back to the user exactly as the review loop already does. This advances the chain and does not modify the Output Summary.
 

{codexspec-0.7.8 → codexspec-0.7.10}/templates/commands/implement-tasks.md

@@ -37,6 +37,7 @@ Read:
 
 - `requirements.md`
 - `spec.md`
+- `design.md`
 - `plan.md`
 - `tasks.md`
 - `.codexspec/memory/constitution.md` when present
@@ -46,8 +47,11 @@ Authority order:
 1. Confirmed entries in `requirements.md`
 2. `spec.md`
 3. Constitution and verified repository facts
-4. Approved `plan.md`
-5. `tasks.md`
+4. `design.md`
+5. Approved `plan.md`
+6. `tasks.md`
+
+A legacy feature may have no `design.md`; when it is absent, proceed with `plan.md` as the design-and-plan authority.
 
 When `requirements.md` is absent, use legacy spec-only mode. Treat `spec.md` as
 the temporary highest feature authority and state that fidelity to the original

{codexspec-0.7.8 → codexspec-0.7.10}/templates/commands/plan-to-tasks.md

@@ -33,9 +33,12 @@ Read:
 
 - `requirements.md`
 - `spec.md`
+- `design.md`
 - `plan.md`
 - Constitution and relevant repository conventions
 
+`design.md` (the confirmed design) sits between `spec.md` and `plan.md` in authority; read it as context so tasks trace to the design the plan implements. A legacy feature may have no `design.md`; proceed from `plan.md` in that case.
+
 Legacy compatibility: when `requirements.md` is absent, use `spec.md` as the temporary highest authority and state the limitation.
 
 ## Stop Conditions

codexspec-0.7.10/templates/commands/release-notes.md

@@ -0,0 +1,212 @@
+---
+description: Generate release notes from git history — maintain a Keep a Changelog CHANGELOG.md entry and emit a user-facing release body, without deciding versions or mutating git state
+allowed-tools: Bash(git branch:*), Bash(git tag:*), Bash(git describe:*), Bash(git log:*), Bash(git diff:*), Bash(git rev-parse:*), Bash(git remote:*), Bash(ls:*), Bash(cat:*), Read, Edit, Write
+---
+
+## Constitution Compliance (MANDATORY)
+
+**Before generating release notes:**
+
+1. **Check for Constitution File**: Look for `.codexspec/memory/constitution.md`
+2. **If Constitution Exists**:
+   - Load and read relevant principles (especially documentation and versioning standards)
+   - Ensure the generated notes align with constitutional guidelines
+3. **If No Constitution Exists**: Proceed with the defaults below
+
+## Language Preference
+
+**IMPORTANT**: Before generating output, read the project's language configuration from `.codexspec/config.yml`.
+
+**Generated-content language priority**:
+
+1. If `language.commit` is set, use that language for the CHANGELOG entry and release body
+2. Otherwise, use `language.output` as fallback
+3. If neither is configured, default to English
+
+**Note**:
+
+- Section headings that are format keywords (`Added`, `Changed`, `Fixed`, etc.) and technical terms
+  (API, JWT, OAuth) may remain in English when appropriate.
+- The `## [Unreleased]` / `## [X.Y.Z]` version markers and ISO dates are format, not prose — keep them
+  as-is.
+
+## User Input
+
+```
+$ARGUMENTS
+```
+
+## Role
+
+You generate **release notes** from git history for **this project**, whatever its release process.
+You make **no assumption** about how the project releases: there may be no `publish.sh`, no CI, no
+particular hosting platform, and no particular versioning scheme (semver, CalVer, and date tags are
+all possible). Every behavior below degrades gracefully when such an assumption does not hold.
+
+You produce two layered outputs from the same analysis:
+
+1. A developer **CHANGELOG.md** entry in Keep a Changelog format.
+2. A user-facing **release body** derived from it.
+
+You **own no versioning** and **mutate no git state** (see Forbidden Operations).
+
+## Forbidden Operations (CRITICAL)
+
+This command is a **generator**, sharing the safety discipline of `commit-staged` and `pr`.
+
+**UNDER NO CIRCUMSTANCES**:
+
+- `git add` / `git commit` / `git reset` / `git checkout` / `git restore` / `git stash` / `git rm` —
+  the command MUST NEVER modify the git staging area and MUST NEVER create a commit.
+- Overwrite `CHANGELOG.md` wholesale with `Write`, or rewrite / reorder / delete any existing
+  CHANGELOG entry.
+- Decide or "own" a version bump; tag; publish; or create a GitHub/GitLab release.
+- Include any AI attribution in generated content — no `Co-Authored-By`, "Generated with", robot
+  emoji, or references to AI tools/agents.
+
+The **only** permitted file writes are: the safe additive `CHANGELOG.md` insertion described in
+**CHANGELOG.md Maintenance**, and — only when `--output <file>` is given — writing the release body to
+that user-directed path.
+
+## Parameters
+
+Parse `$ARGUMENTS` for the following optional parameters:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--version <X.Y.Z>` | (none) | Stamp this version on the new section; short-circuits all version inference/suggestion |
+| `--from <ref>` | (resolved) | Explicit range start (overrides Range Resolution) |
+| `--to <ref>` | `HEAD` | Explicit range end |
+| `--output <file>` | (terminal) | Write the release body to a file instead of stdout |
+| `--spec <feature>` | (none) | Enrich the "why" from that feature's `spec.md` / `tasks.md` |
+
+- If `--version` is present, **validate** it is a well-formed version string. If it is malformed,
+  **reject** with a clear validation message and do **not** write a malformed section.
+- If `--spec` is present but does not resolve to an existing feature/path, **degrade gracefully**:
+  proceed from git alone and report the unresolved path. Do not fail.
+
+## Range Resolution
+
+Determine the commit range `<from>..<to>` (default `<to>` is `HEAD`):
+
+1. **Explicit override**: if `--from` (and optionally `--to`) is given, use it directly.
+2. **Latest tag**: otherwise, the default range is `latest tag..HEAD` — resolve the latest tag via
+   `git describe --tags --abbrev=0`.
+3. **No reachable tag → CHANGELOG fallback**: if the repository has no reachable tag, fall back to
+   "after the last version recorded in `CHANGELOG.md`" (anchor on the most recent versioned section).
+4. **No tag and no CHANGELOG (or no anchorable version) → full history**: if neither a tag nor an
+   anchorable CHANGELOG version exists (for example the only prior section is `Unreleased`, which has
+   no commit anchor), summarize the **full history**.
+
+Always apply `--no-merges` so merge commits are excluded. Route the Edge Cases below before analysis.
+
+## Git Context Collection
+
+Over the resolved range, collect:
+
+1. **Commits**: `git log --no-merges --pretty=format:"%H %s" <from>..<to>`
+2. **Full diff**: `git diff <from>..<to>` (to understand what each commit actually changed)
+3. When `--spec` resolves: read that feature's `spec.md` / `tasks.md` for intent ("why").
+
+## Change Categorization
+
+Group the changes into **Keep a Changelog** categories, including only those that apply:
+
+- `### Added` — new features
+- `### Changed` — changes to existing functionality
+- `### Deprecated` — soon-to-be-removed features
+- `### Removed` — removed features
+- `### Fixed` — bug fixes
+- `### Security` — security fixes
+
+**Conventional commits are used when present but are NOT required.** When commits do not follow the
+convention, **infer** the category and wording from the **diff and commit subjects** (the "diff is the
+source of truth" approach of `commit-staged` / `pr`).
+
+**User-facing vs contributor split**: the user-facing lists lead with user-visible changes
+(`feat` / `fix` / `perf`, and anything a user would notice). Internal / contributor-only changes
+(`chore` / `refactor` / `test` / `ci` / `build`, internal docs) go **only** under a separate
+`### For contributors` subsection. When commit types are absent, infer visibility from the diff.
+
+## Completeness Cross-Check
+
+After drafting, **cross-check** the entry against the commit list: **every non-merge commit in the
+selected range must map to at least one bullet.** If any commit is unrepresented, add it. Do not pad
+with bullets that correspond to no commit.
+
+## Version Handling
+
+Choose the new section's label:
+
+- **Default**: `## [Unreleased]` — with **no date** (the Keep a Changelog convention for accumulating
+  changes before a version is assigned).
+- **`--version X.Y.Z` given**: stamp `## [X.Y.Z] - <YYYY-MM-DD>` (today's ISO date) and **skip all
+  version inference and suggestion**.
+
+**Guarded advisory** (only when `--version` is absent): print a console-only suggested next version
+**only when** the project is detected to use **semver AND conventional commits** — i.e. existing
+tags/versions are semver-shaped *and* the range's commits carry conventional-commit prefixes. In that
+case print the suggested next version, the reasoning (e.g. counts of `feat` / `fix` / breaking), and
+an explicit "override with `--version`" note. **Otherwise stay silent** on version suggestions.
+
+The command MUST **never write a version number into the file on its own** — the file section is only
+ever `## [Unreleased]` or a user-provided `--version`.
+
+## CHANGELOG.md Maintenance
+
+Maintain `CHANGELOG.md` at the repository root with a **safe, additive** edit:
+
+1. **Create if absent**: if `CHANGELOG.md` does not exist, create it with the **standard Keep a
+   Changelog header**:
+
+   ```markdown
+   # Changelog
+
+   All notable changes to this project will be documented in this file.
+
+   The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+   and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+   ```
+
+2. **Insert additively**: read the entire existing `CHANGELOG.md` first. Insert the new section at a
+   single insertion point — into an existing `## [Unreleased]` section when one is present (merge the
+   new bullets in rather than duplicating the section), else immediately above the most recent
+   versioned section, else directly after the header. **Never rewrite, reorder, or delete any
+   existing entry.**
+3. **Edit, never overwrite**: perform the insertion with a precise `Edit` (exact `old_string` match)
+   — **never** use `Write` to overwrite the whole `CHANGELOG.md`.
+
+This is the command's only mutation of `CHANGELOG.md`, and it never touches git state.
+
+## Release Body Generation
+
+Derive the user-facing **release body** from the same categorized model:
+
+- Lead with what the user **can now do** — "You can now…", plain language, not implementation detail.
+- Keep internal/contributor changes under a `### For contributors` subsection, out of the main list.
+- Flag breaking changes visibly (`**Breaking change:**`).
+- The body is **generic markdown**, platform-agnostic — the user pastes it into GitHub / GitLab / any
+  release page. The command does **not** publish it.
+
+## Output Modes
+
+- **Terminal (default)**: print the release body to the terminal wrapped in a markdown code block so
+  the raw markdown can be copied.
+- **`--output <file>`**: write the raw release body to that file (the one user-directed file write
+  permitted besides the CHANGELOG insertion).
+
+The `CHANGELOG.md` entry is written in both modes.
+
+## Edge Cases
+
+- **Not a git repository**: report "Not a git repository." and take no action.
+- **Empty range** (no commits since the resolved start): report "No changes to release." — do not
+  fabricate entries and do not error.
+- **Detached HEAD**: report that the branch cannot be determined and stop, rather than guessing.
+- **Unresolved `--spec`**: proceed from git alone and report the unresolved path (see Parameters).
+- **Malformed `--version`**: reject with a clear validation message; write no malformed section.
+
+## Automatic Distillation
+
+This command has **no** Automatic Distillation step. It is a generator, not an interaction that
+produces reusable cross-feature knowledge.