codexspec 0.7.15__tar.gz → 0.7.16__tar.gz

{codexspec-0.7.15 → codexspec-0.7.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.15
+Version: 0.7.16
 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

{codexspec-0.7.15 → codexspec-0.7.16}/pyproject.toml

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

{codexspec-0.7.15 → codexspec-0.7.16}/src/codexspec/__init__.py

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

{codexspec-0.7.15 → codexspec-0.7.16}/templates/commands/distill.md

@@ -55,7 +55,7 @@ Apply this boundary test to every candidate: **"Would a single feature's `requir
 
 ## The profile store: `.codexspec/profile/`
 
-Six **category directories**, each holding **one record per file** (`<id>.md`) with **only current-effective** knowledge — dense, with no "retired" section (git history is the ledger). One-file-per-record is deliberate: parallel feature branches each add differently-named files, so distilled knowledge merges without conflict. Create the directory and record file on first write.
+Six **category directories**, each holding **one record per file** (`<id>.md`, or `<id>-<slug>.md` — see the `id` rule below) with **only current-effective** knowledge — dense, with no "retired" section (git history is the ledger). One-file-per-record is deliberate: parallel feature branches each add differently-named files, so distilled knowledge merges without conflict. Create the directory and record file on first write.
 
 - `constraints/` — negative constraints (`严禁 / 仅允许`). These carry the **highest** weight and MUST be honored first.
 - `conventions/` — positive cross-feature conventions / steering.
@@ -70,7 +70,7 @@ There is **no** `facts/` category — a bare fact with no "therefore do X" is ei
 
 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.
+- `id` — **type letter + full source-feature id + local sequence**, e.g. `P-2026-0812-14054p-1` or `Con-2026-0812-14054p-1`. The `### <id>: <title>` heading keeps the bare id; the **filename** is `<id>-<slug>.md`, where the **slug** is a semantic suffix derived from the record title: lowercase ASCII letters and digits with hyphens as separators (`^[a-z0-9]+(-[a-z0-9]+)*$`, no leading/trailing hyphen), at most 50 characters, rendered in English when the title is not ASCII. When no meaningful slug can be derived, write the legacy bare form `<id>.md` — both forms are valid store members. The slug never enters the id, the heading, or `[[id]]` links, and never participates in uniqueness. Locating a record from its id stays mechanical: the record's file is exactly the one named `<id>.md` or the one named `<id>-<slug>.md`; because the slug admits only `[a-z0-9-]`, no other filename can begin with `<id>` followed by `-` or `.`, so a lookup by id is unambiguous even when one sequence number is a digit-prefix of another. 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) — uniqueness is carried entirely by the id. 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 **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` | `strategy` | `runbook` (`constraint` = highest priority).
 - `scope/when` — natural-language applicability condition (e.g. "when editing Python code"); omit for global. **No formal syntax.**
@@ -105,7 +105,7 @@ If you cannot state these parts, the strategy or runbook is not yet worth record
 
 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 — a `convention` (claim + evidence is enough), file `conventions/Con-2026-0809-2219gg-1.md`:
+Example — a `convention` (claim + evidence is enough), file `conventions/Con-2026-0809-2219gg-1-prefer-absolute-imports.md`:
 
 ```markdown
 ### Con-2026-0809-2219gg-1: Prefer absolute imports
@@ -118,7 +118,7 @@ Example — a `convention` (claim + evidence is enough), file `conventions/Con-2
 - status: vetted
 ```
 
-Example — a `pitfall` (note the required `root-cause` / `workaround` / `lesson` body), file `pitfalls/P-2026-0810-1330ab-1.md`:
+Example — a `pitfall` (note the required `root-cause` / `workaround` / `lesson` body), file `pitfalls/P-2026-0810-1330ab-1-re-sub-string-replacement-corruption.md`:
 
 ```markdown
 ### P-2026-0810-1330ab-1: `re.sub` with a string replacement corrupts blocks containing backslashes
@@ -134,7 +134,7 @@ Example — a `pitfall` (note the required `root-cause` / `workaround` / `lesson
 - status: candidate
 ```
 
-Example — a `strategy` (note the `trigger` / `action` body), file `strategies/S-2026-0813-1606fz-1.md`:
+Example — a `strategy` (note the `trigger` / `action` body), file `strategies/S-2026-0813-1606fz-1-suspect-markdown-emphasis-first.md`:
 
 ```markdown
 ### S-2026-0813-1606fz-1: When a substring contract test fails, suspect markdown emphasis first
@@ -149,7 +149,7 @@ Example — a `strategy` (note the `trigger` / `action` body), file `strategies/
 - status: candidate
 ```
 
-Example — a `runbook` (note the ordered `steps` + `failure-recovery` body), file `runbooks/R-2026-0813-1143el-1.md`:
+Example — a `runbook` (note the ordered `steps` + `failure-recovery` body), file `runbooks/R-2026-0813-1143el-1-release-a-new-codexspec-version.md`:
 
 ```markdown
 ### R-2026-0813-1143el-1: Release a new CodexSpec version
@@ -191,7 +191,7 @@ When a new item conflicts with an existing rule, resolve in this order:
 
 Change the profile **only** through three conceptual operations (you edit the files directly — these are a discipline, **not** a tool API or matching algorithm):
 
-- `add` — create a new record file `<category>/<id>.md` for a verified item.
+- `add` — create a new record file `<category>/<id>-<slug>.md` (bare `<category>/<id>.md` when no meaningful slug applies) for a verified item.
 - `replace` — supersede an outdated/wrong item **in its own file** (keeps records dense).
 - `remove` — delete the record's file when a changed environment invalidates it.
 

{codexspec-0.7.15 → codexspec-0.7.16}/templates/commands/onboard.md

@@ -65,7 +65,7 @@ onboard **never** extracts `decisions`, `pitfalls`, `strategies`, or `runbooks`.
 
 ## 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**:
+onboard **reuses `distill`'s profile store and record format verbatim** — one record per file under a category directory (`conventions/<id>-<slug>.md`, `constraints/<id>-<slug>.md`; bare `<id>.md` when no meaningful slug applies), 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`.