codexspec 0.7.9__tar.gz → 0.7.11__tar.gz

{codexspec-0.7.9 → codexspec-0.7.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.9
+Version: 0.7.11
 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
@@ -608,6 +608,7 @@ Implementation follows **conditional TDD workflow**:
 | --- | --- |
 | `/codexspec:distill` | Distill reusable cross-feature knowledge into `.codexspec/profile/` |
 | `/codexspec:evolve` | Compile profile knowledge into a command/skill and contribute upstream via a reviewed PR |
+| `/codexspec:onboard` | Cold-start the project profile by scanning an existing codebase (conventions + constraints) |
 
 #### Git Workflow Commands
 
@@ -615,6 +616,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.9 → codexspec-0.7.11}/README.md

@@ -563,6 +563,7 @@ Implementation follows **conditional TDD workflow**:
 | --- | --- |
 | `/codexspec:distill` | Distill reusable cross-feature knowledge into `.codexspec/profile/` |
 | `/codexspec:evolve` | Compile profile knowledge into a command/skill and contribute upstream via a reviewed PR |
+| `/codexspec:onboard` | Cold-start the project profile by scanning an existing codebase (conventions + constraints) |
 
 #### Git Workflow Commands
 
@@ -570,6 +571,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.9 → codexspec-0.7.11}/pyproject.toml

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

{codexspec-0.7.9 → codexspec-0.7.11}/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.9"
+__version__ = "0.7.11"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants

{codexspec-0.7.9 → codexspec-0.7.11}/src/codexspec/commands/installer.py

@@ -47,8 +47,8 @@ def get_commands_metadata() -> list[CommandMetadata]:
 
     Returns:
         List of CommandMetadata dictionaries sorted by category priority:
-        core (11) -> enhanced (7) -> git (2) -> review (1) -> utility (2)
-        Total: 23 commands
+        core (11) -> enhanced (8) -> git (3) -> review (1) -> utility (2)
+        Total: 25 commands
     """
     return [
         # Core Commands (11)
@@ -129,7 +129,7 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "core",
             "file_name": "implement-tasks.md",
         },
-        # Enhanced Commands (7)
+        # Enhanced Commands (8)
         {
             "name": "clarify",
             "display_name": "/codexspec:clarify",
@@ -172,6 +172,13 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "enhanced",
             "file_name": "evolve.md",
         },
+        {
+            "name": "onboard",
+            "display_name": "/codexspec:onboard",
+            "description": "扫描现有代码库冷启动项目 profile（提取 conventions 与 constraints）",
+            "category": "enhanced",
+            "file_name": "onboard.md",
+        },
         {
             "name": "debug",
             "display_name": "/codexspec:debug",
@@ -179,7 +186,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",
@@ -194,6 +201,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.9 → codexspec-0.7.11}/templates/commands/distill.md

@@ -54,17 +54,27 @@ Four **category directories**, each holding **one record per file** (`<id>.md`)
 Every record MUST separate the distilled claim from the evidence it rests on:
 
 - `id` — **type letter + full source-feature id + local sequence**, e.g. `P-2026-0812-14054p-1` or `Con-2026-0812-14054p-1`. It is **both** the record's `### <id>: <title>` heading **and its filename** (`pitfalls/P-2026-0812-14054p-1.md`). The **source-feature id** is the distilling feature's full spec-dir id `{YYYY-MMDD-HHMM}{rr}` (e.g. `2026-0812-14054p`); it is globally unique by the timestamp+random scheme spec directories use, so records distilled on parallel feature branches never collide on id **or filename** (they merge with no conflict). Keep the **full** id (not a short tail) so the record is self-describing: the date supports recency/staleness reading, and the feature id ties the record to its originating change for decision context and scope. When distilling with no feature context, generate a fresh `{YYYY-MMDD-HHMM}{rr}` id now (same convention as create-new-feature). **Never** use a bare sequential id such as `P-001` — those collide across parallel branches.
-- `claim` — one-sentence reusable statement.
+- `claim` — one-sentence reusable **summary** (a title line, not the actionable body — for a `pitfall` the usable content lives in the three body parts below, not in this sentence).
 - `type` — `convention` | `constraint` | `pitfall` | `decision` (`constraint` = highest priority).
 - `scope/when` — natural-language applicability condition (e.g. "when editing Python code"); omit for global. **No formal syntax.**
 - `evidence.facts` — the concrete observations behind it; **quote the user's original words, do not paraphrase**.
 - `evidence.state` — the context/validity when true (feature / commit / config; still valid?).
-- `provenance` — source feature/session, trigger, timestamp, `derivation = explicit | inferred`.
-- `status` — `vetted` **only** when `derivation = explicit` (the user's own words) AND the item was verified by an outcome (a test passed, a workaround worked); every `inferred` item stays `candidate`. Only `vetted` records are eligible for `evolve`.
+- `provenance` — source feature/session, trigger, timestamp, `derivation = explicit | inferred`, `confidence = high | medium | low`. `derivation` records only **how the claim was first obtained** (the user's own words vs inferred); it is **not** a gate on `status` (see below).
+- `status` — `candidate` | `vetted` | `conflict/needs-adjudication`. A record is `vetted` **only** when BOTH (a) it was **verified by an outcome** (a test passed, a workaround worked) AND (b) a **human endorsed it** — either it came from the user's own words (`derivation: explicit`) **or** the user approved it in `/distill review`. `derivation` is **not** itself a gate: an `inferred` record that is outcome-verified and human-approved becomes `vetted` and is eligible for `evolve`. Un-verified speculation MUST NOT be `vetted`. `conflict/needs-adjudication` marks a deferred conflict (see Conflict adjudication) and is not `evolve`-eligible. Only `vetted` records are eligible for `evolve`.
+
+**Pitfall records carry more than a claim.** A `pitfall` (or any trap-type record) MUST, beyond `claim` and `evidence`, spell out three body parts — a bare "here is the trap" record is a defect (the next person just re-hits it):
+
+- `root-cause` — *why* the trap happens (the underlying mechanism), not merely what it is.
+- `workaround` — the concrete way around it, with the code / paths / commands to apply.
+- `lesson` — the transferable takeaway that generalizes beyond this one instance.
+
+If you cannot state all three, the pitfall is not yet understood well enough to record. `convention` / `constraint` / `decision` records usually need only `claim` + `evidence`; this three-part body is required specifically for traps.
+
+> **onboard variant**: `/codexspec:onboard` writes to this same store and format, with one difference — its records are inferred from code, so `evidence.facts` holds a verbatim **code observation** (path + snippet) instead of a user quote, `provenance` marks the onboard scan, and `derivation` is always `inferred`. onboard therefore writes `status: candidate` **at write time** (it never writes `vetted` itself); such a record can still be promoted to `vetted` later once it is outcome-verified and approved in `/distill review` — its `inferred` origin is not a barrier (per the `status` rule above).
 
 This separation is what makes a later error locatable as **misread** (facts wrong) vs **overreach** (claim over-generalized) vs **stale** (state no longer holds).
 
-Example entry — file `conventions/Con-2026-0809-2219gg-1.md`:
+Example — a `convention` (claim + evidence is enough), file `conventions/Con-2026-0809-2219gg-1.md`:
 
 ```markdown
 ### Con-2026-0809-2219gg-1: Prefer absolute imports
@@ -73,10 +83,26 @@ Example entry — file `conventions/Con-2026-0809-2219gg-1.md`:
 - scope/when: Python modules under `src/`
 - evidence.facts: "Use absolute imports; relative ones broke the packaged wheel last time."
 - evidence.state: confirmed at feature 2026-0809-2219gg; commit a1b2c3d
-- provenance: distill @implement-tasks, 2026-08-09, derivation: explicit
+- provenance: distill @implement-tasks, 2026-08-09, derivation: explicit, confidence: high
 - status: vetted
 ```
 
+Example — a `pitfall` (note the required `root-cause` / `workaround` / `lesson` body), file `pitfalls/P-2026-0810-1330ab-1.md`:
+
+```markdown
+### P-2026-0810-1330ab-1: `re.sub` with a string replacement corrupts blocks containing backslashes
+- claim: Inject a rendered block with a function replacement in `re.sub`, never a string.
+- type: pitfall
+- scope/when: upserting a rendered block into a file via `re.sub` in `src/`
+- root-cause: a string replacement passed to `re.sub` interprets `\g<...>` and backslash escapes, so any such sequence inside the block silently corrupts the output.
+- workaround: pass a callable replacement — `pattern.sub(lambda _m: block, text)` — so the block is inserted verbatim.
+- lesson: whenever the replacement is data (not a pattern), use the callable form; the same trap applies in any language whose replace interprets `$1` / `\1`.
+- evidence.facts: the injected block contained `\g<0>` and rendered as garbage until switched to the lambda form.
+- evidence.state: confirmed at feature 2026-0810-1330ab; commit c0ffee1. Still valid.
+- provenance: distill @implement-tasks, 2026-08-10, derivation: inferred, confidence: high
+- status: candidate
+```
+
 ## Extraction
 
 Read the interaction segment and extract, per the dimensions above, only **verified** knowledge — prefer facts confirmed by outcomes over speculation; speculation MUST NOT become `vetted`.
@@ -106,6 +132,15 @@ git history is the audit ledger. Do **NOT** keep a retired file or a retired sec
 
 Auto-distill writes `candidate` records non-interactively and **never prompts**. Promote them through the **manual review mode** — `/distill review` (or `/distill` with no new segment to distill): list every pending `candidate` compactly (claim + evidence + provenance) and let the user approve inline — "vet all", "vet 1,3", "edit 2", "drop 4". Apply the choices by editing each record's `status` (a `replace`). **The user never hand-edits the profile files.**
 
+The user's approval here **is** the human endorsement half of the `vetted` gate: an approved `candidate` that is already outcome-verified becomes `vetted` **regardless of its original `derivation`** (an `inferred` record is not blocked from vetting). If a candidate has not yet been outcome-verified, approval keeps it `candidate` (or the user may attest the outcome to complete the gate). This is the path by which `inferred` knowledge — including everything `/codexspec:onboard` writes — reaches `vetted` and becomes `evolve`-eligible.
+
+## Self-check before finishing
+
+A lightweight judgment pass (not an engineered lint) over what you just wrote:
+
+- **Not hollow** — every `pitfall` states `root-cause` + `workaround` + `lesson`, not just a `claim`. If it collapses to one line, either flesh it out or drop it.
+- **Links resolve** — any `[[id]]` cross-link points to an existing record file under `.codexspec/profile/`, or is an intentional forward reference to one you are also writing now. Don't leave a link to a record that will never exist.
+
 ## Output
 
 Report concisely in the interaction language: which records were added / replaced / removed and in which file, any `conflict` records deferred, or "nothing to distill" on early-exit. distill **never** gates the caller.

codexspec-0.7.11/templates/commands/onboard.md

@@ -0,0 +1,89 @@
+---
+description: Cold-start the project profile by scanning an existing codebase for conventions and constraints
+argument-hint: "[path]"
+allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(ls/cat/find:*), Edit, Write
+---
+
+# Codebase Onboarding
+
+## Language Preference
+
+Read `.codexspec/config.yml`. Two independent language controls apply (each falls back to `language.output`, then English):
+
+- **Interaction language** (`language.interaction`): language for all conversation with the user — questions, explanations, status messages, and `codexspec` CLI terminal output.
+- **Document language** (`language.document`): language for generated artifact files (the profile records).
+
+Converse in the interaction language and author artifacts in the document language. Apply the project's translation standard to both: translate by meaning (not word-for-word), keep English for terms with no good native equivalent, and write as if originally in that language. **Exception**: `evidence.facts` records a verbatim code observation (path + snippet) and MUST NOT be translated.
+
+## User Input
+
+`$ARGUMENTS`
+
+## Role and Operating Model
+
+`onboard` is the **cold-start / bulk counterpart to `distill`**. Where `distill` writes the project profile incrementally from interaction, `onboard` scans an **existing codebase** once and batch-writes the reusable knowledge that is **implicit in the code and not already recorded accessibly** into the shared store `.codexspec/profile/`. It exists to bootstrap a brownfield project's profile so accumulated project knowledge is grounded immediately, instead of only after enough work has flowed through `distill`.
+
+`onboard` is **read-only on the codebase** and **write-only to `.codexspec/profile/`**: it never modifies source, tests, git state, or the constitution. It is a **standalone, user-invoked command** — not an SDD pipeline stage: it has **no auto-next successor** and **no automatic hook**, and it leaves no persistent document beyond the profile records (no map, no walkthrough — those, if ever wanted, belong to a separate `explain`).
+
+## Prerequisite & Scaffold
+
+Before scanning:
+
+- If `.codexspec/` is **absent**, the project is not codexspec-initialized. **Stop** and direct the user to run `codexspec init`. Do not scaffold a whole project.
+- If `.codexspec/` is present but the profile store is missing, **ensure the canonical scaffold** — the four category directories `.codexspec/profile/{constraints,conventions,pitfalls,decisions}/` (matching what `codexspec init` produces) — before writing.
+- git is **not required**. onboard runs on a plain directory.
+
+## Codebase Scan
+
+Scan strategy is **high-signal-first over the whole repository in a single pass**:
+
+- Respect `.gitignore`. When there is **no git / no `.gitignore`**, fall back to sensible defaults that skip vendored, build, and dependency directories (e.g. `node_modules`, `dist`, `build`, `.venv`, `target`), and say so in the summary.
+- **Deep-read high-value sources**: directory structure; build / dependency / lint / formatter / type-checker config; entry points; existing docs (README, CONTRIBUTING, ADRs); test layout; and the frequently-imported core modules. **Shallow-sample** the bulk of business code rather than reading every file.
+- **Stream findings to the store as you go** — write each convention as soon as it is confirmed — so the scan is **interruptible and resumable**. Do **not** block until the whole scan finishes before writing or interacting; a run interrupted mid-scan keeps what it already wrote and can be re-run to continue.
+- An optional `[path]` argument (from `$ARGUMENTS`) **narrows** the scan to a single subdirectory or module.
+- Never claim full coverage when you sampled — the summary distinguishes deep-read from sampled areas.
+
+## What onboard Extracts — and What It Must NOT
+
+Extraction uses your **flexible judgment over what the code actually shows** — not a fixed checklist of filenames or markers. onboard actively extracts **only two** of the four profile categories:
+
+- **`conventions`** (the primary yield) — the code's observable regularities: directory/module structure, naming schemes, import style, the tech stack and toolchain (read from manifests), lint/format/type configuration, test framework and layout, and patterns repeated across the codebase. **Observable architecture / tech-stack facts** are captured here as fact-plus-steering, not as ADR-style decisions.
+- **`constraints`** (narrow, high-risk) — **only** config-level **explicit hard prohibitions**: lint/type rules set to *error* that ban imports or APIs, `do not edit` / generated-file / managed-block markers, and CODEOWNERS / protected-path conventions. Every constraint candidate carries a **precise evidence anchor** (`file:line` or a config snippet). **Absent an explicit prohibition signal, propose no constraint** — silence, never a guess.
+
+onboard **never** extracts `decisions` or `pitfalls`. A documented decision or pitfall is already readable in the repo (redundant to copy); an undocumented one is unreliable to infer from a cold scan (pitfalls are experiential; decision rationale would be fabricated). Those two categories remain `distill`'s channels, where the rationale and lived experience are available.
+
+## Record Format
+
+onboard **reuses `distill`'s profile store and record format verbatim** — one record per file under a category directory (`conventions/<id>.md`, `constraints/<id>.md`), ids namespaced by the source-feature id, and `claim` physically separated from `evidence`. See `distill.md` for the canonical format. onboard writes with these **deltas**:
+
+- `provenance` marks the **onboard scan** as the source (distinct from `distill`), with `derivation: inferred` — always, because the knowledge is inferred from code, never quoted from the user.
+- An onboard record's `status` is always **`candidate`** at write time — onboard **never** writes `vetted` itself. Its `inferred` origin is **not** a permanent barrier: such a record can later be promoted to `vetted` via `/distill review` once it is outcome-verified and the user approves it (the `evolve` gate remains `vetted`). See the `status` rule in `distill.md`.
+- `evidence.facts` holds the **concrete code observation** — the file path plus the relevant snippet or config anchor — instead of a user quote.
+
+## Integration with the Existing Profile
+
+Before writing, **read the existing profile** and integrate:
+
+- **De-duplicate** — skip anything already covered by an existing record (by judgment, not an algorithm).
+- **Adjudicate conflicts** per `distill`'s order (recency → specificity → scenario-decoupling → defer); if genuinely unresolvable, write the record `status: conflict/needs-adjudication` and surface it — never block, never guess.
+- **Never clobber.** onboard MUST NOT overwrite or delete any existing `vetted`, hand-authored, or `distill`-written record. It only **adds** new files (namespaced ids merge with zero conflict) or edits **its own** candidate file. This makes re-running onboard (whole repo, or a narrowed `[path]`) safe and **idempotent** — it augments without destroying.
+
+## Safety Gate — quick review for high-risk, immediate effect for the rest
+
+`candidate` records take local effect immediately (weighted with caution); vetting only gates `evolve`, not local effect. Because onboard is high-volume cold inference, it gates the one high-risk category and lets the bulk flow:
+
+- **`conventions` → written immediately as `candidate`.** They take effect at once and are refined later, asynchronously and at your pace, via `/distill review`. No synchronous audit.
+- **`constraints` → held for a quick in-session review at the end of the scan.** Because a wrong, top-weighted constraint would otherwise take honored-first effect unreviewed, onboard accumulates constraint candidates and, at the end, presents them for a fast review. This is a **persist / do-not-persist** decision for *this scan's* constraints — **not** a promotion to `vetted`, and **not** an invocation of `/distill review`. For each candidate you may **persist**, **edit then persist**, or **drop**; only persisted ones are written (as `candidate`). If the scan found **no** constraint candidates, there is no synchronous step.
+
+The user reviews only the small high-risk set here; the ongoing, backlog-wide vetting of any `candidate` remains the separate asynchronous `/distill review` channel.
+
+## Output Summary
+
+Report concisely in the interaction language: the records added / updated per category and file, any `conflict` records deferred, and **which areas were deep-read versus sampled** (never imply full coverage when you sampled). On an empty or knowledge-free scan, write nothing and report "nothing to onboard".
+
+## Boundaries (recap)
+
+- Read-only on code; write-only to `.codexspec/profile/`; no source / test / git / constitution mutation.
+- Standalone: no auto-next, no automatic hook, and **no Automatic Distillation step** (onboard is not a wrap-up command).
+- Writes only `conventions` and `constraints`; never `decisions` or `pitfalls`.
+- Produces no persistent document beyond profile records.

codexspec-0.7.11/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.