codexspec 0.7.7__tar.gz → 0.7.9__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.7
+Version: 0.7.9
 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) |
 
@@ -589,6 +600,7 @@ Implementation follows **conditional TDD workflow**:
 | `/codexspec:analyze`         | Cross-artifact consistency analysis (auto-remediating, severity-based) |
 | `/codexspec:checklist`       | Generate requirements quality checklist                         |
 | `/codexspec:tasks-to-issues` | Convert tasks to GitHub Issues                                  |
+| `/codexspec:debug`           | Systematic root-cause debugging (4 phases; standalone or escalated from implement-tasks) |
 
 #### Self-Evolution Commands
 

{codexspec-0.7.7 → codexspec-0.7.9}/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) |
 
@@ -544,6 +555,7 @@ Implementation follows **conditional TDD workflow**:
 | `/codexspec:analyze`         | Cross-artifact consistency analysis (auto-remediating, severity-based) |
 | `/codexspec:checklist`       | Generate requirements quality checklist                         |
 | `/codexspec:tasks-to-issues` | Convert tasks to GitHub Issues                                  |
+| `/codexspec:debug`           | Systematic root-cause debugging (4 phases; standalone or escalated from implement-tasks) |
 
 #### Self-Evolution Commands
 

{codexspec-0.7.7 → codexspec-0.7.9}/pyproject.toml

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

{codexspec-0.7.7 → codexspec-0.7.9}/src/codexspec/__init__.py

@@ -40,10 +40,11 @@ from .i18n import (
     update_language_field,
 )
 from .integrations import get_integrations
+from .profile import ensure_profile_scaffold, inject_profile_block
 from .translator import SUPPORTED_LANGUAGES, translate
 
 # Version info
-__version__ = "0.7.7"
+__version__ = "0.7.9"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants
@@ -706,6 +707,11 @@ def init(
     (codexspec_dir / "templates" / "docs").mkdir(exist_ok=True)
     (codexspec_dir / "scripts").mkdir(exist_ok=True)
 
+    # Ensure the profile scaffold unconditionally (independent of integrations),
+    # so knowledge distilled later is effective immediately with no re-init and
+    # no dangling reference. Non-destructive: existing profile files are kept.
+    ensure_profile_scaffold(target_dir)
+
     # Copy helper scripts based on platform
     scripts_source_dir = get_scripts_dir()
     if scripts_source_dir.exists():
@@ -884,6 +890,10 @@ def init(
                     prepend_compliance_section(claude_md)
                     console.print(f"[green]{translate('cli.init.compliance_added', normalized_lang)}[/green]")
 
+        # Inject the profile block AFTER creation/compliance so it never clobbers
+        # the compliance @import or the user's body (bounded, idempotent).
+        inject_profile_block(claude_md)
+
     # Initialize git if requested
     if not no_git and not (target_dir / ".git").exists():
         try:

{codexspec-0.7.7 → codexspec-0.7.9}/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 (6) -> git (2) -> review (1) -> utility (2)
-        Total: 20 commands
+        core (11) -> enhanced (7) -> git (2) -> review (1) -> utility (2)
+        Total: 23 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",
@@ -115,7 +129,7 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "core",
             "file_name": "implement-tasks.md",
         },
-        # Enhanced Commands (4)
+        # Enhanced Commands (7)
         {
             "name": "clarify",
             "display_name": "/codexspec:clarify",
@@ -158,6 +172,13 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "enhanced",
             "file_name": "evolve.md",
         },
+        {
+            "name": "debug",
+            "display_name": "/codexspec:debug",
+            "description": "系统化根因排查（四阶段：复现→定位根因→单一修复），可独立调用或由 implement-tasks 升级进入",
+            "category": "enhanced",
+            "file_name": "debug.md",
+        },
         # Git Workflow Commands (2)
         {
             "name": "commit-staged",

{codexspec-0.7.7 → codexspec-0.7.9}/src/codexspec/integrations/codex.py

@@ -10,6 +10,7 @@ from typing import Any
 import yaml
 
 from codexspec.commands.installer import get_commands_metadata
+from codexspec.profile import inject_profile_block
 from codexspec.translator import load_translation_cache, translate_template_frontmatter
 
 CODEXSPEC_CONTEXT_START = "<!-- CODEXSPEC START -->"
@@ -90,6 +91,10 @@ class CodexIntegration:
 
         context_path.write_text(updated, encoding="utf-8")
 
+        # Inject the profile block (pointers only, no @import) alongside the
+        # skills section, as its own bounded, idempotent managed block.
+        inject_profile_block(context_path)
+
     def render_skill(self, command_name: str, content: str, fallback_description: str = "") -> str:
         """Render one command template into a Codex SKILL.md."""
         frontmatter, body = _split_frontmatter(content)
@@ -110,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.9/src/codexspec/profile.py

@@ -0,0 +1,112 @@
+"""Project-profile consumption.
+
+Wires a user project's ``.codexspec/profile/`` into the AI context files so that
+knowledge distilled by ``/codexspec:distill`` is consulted in later work.
+
+Store layout: **one record per file** under a per-category directory
+(``constraints/`` ``conventions/`` ``pitfalls/`` ``decisions/``). Because parallel
+feature branches each add differently-named record files, their distilled
+knowledge merges without conflict.
+
+Two concerns live here:
+
+- ``ensure_profile_scaffold`` — create the four category directories (each kept
+  by a ``.gitkeep``) so every injected reference resolves, independent of whether
+  any knowledge has been distilled yet.
+- ``render_profile_block`` / ``inject_profile_block`` — render a bounded,
+  channel-neutral managed block (pointers only, no ``@import``) and inject it
+  idempotently into a context file (CLAUDE.md or AGENTS.md) without disturbing any
+  other content.
+
+See the feature record under
+``.codexspec/specs/2026-0812-14054p-profile-consumption/``.
+"""
+
+import re
+from pathlib import Path
+
+# Ordered: constraints first (highest weight, honored first). Each is a directory
+# holding one record per file.
+PROFILE_CATEGORIES = ("constraints", "conventions", "pitfalls", "decisions")
+
+PROFILE_BLOCK_START = "<!-- CODEXSPEC PROFILE START -->"
+PROFILE_BLOCK_END = "<!-- CODEXSPEC PROFILE END -->"
+
+# Channel-neutral: identical for CLAUDE.md and AGENTS.md. Constraints are a strong
+# mandatory pointer (no @import), so the block depends on no tool-specific import
+# mechanism and the store can be one-file-per-record directories. Assembled from
+# short literals to keep each source line within the line-length limit.
+_PROFILE_BLOCK = "".join(
+    [
+        f"{PROFILE_BLOCK_START}\n",
+        "## CodexSpec Project Profile\n\n",
+        "**Project constraints (highest priority — read these FIRST):** before any non-trivial work you MUST ",
+        "read every record under `.codexspec/profile/constraints/` — the project's hard prohibitions ",
+        "(严禁 / 仅允许). Honor them before anything else.\n\n",
+        "**Project profile — consult on demand when relevant to the task** ",
+        "(each directory holds one record per file):\n\n",
+        "- `.codexspec/profile/conventions/` — cross-feature conventions / steering; ",
+        "read before adopting a pattern, structure, or naming choice.\n",
+        "- `.codexspec/profile/pitfalls/` — known traps and their workarounds; ",
+        "read before implementing or debugging in an area that may have bitten before.\n",
+        "- `.codexspec/profile/decisions/` — past cross-feature / architectural decisions; ",
+        "read before deciding in the same area, to reuse prior rationale rather than re-litigate it.\n\n",
+        "Read the full record — each carries a `status` of `candidate` or `vetted`; ",
+        "weight `candidate` items with appropriate caution. A directory may be empty ",
+        "until `/codexspec:distill` has captured knowledge.\n",
+        f"{PROFILE_BLOCK_END}\n",
+    ]
+)
+
+
+def ensure_profile_scaffold(target_dir: Path) -> Path:
+    """Create ``.codexspec/profile/`` and its four category directories if absent.
+
+    Each category is a directory of one-record-per-file entries; a ``.gitkeep``
+    keeps an empty category tracked so every pointer resolves. Idempotent and
+    non-destructive: existing records and directories are never overwritten.
+    """
+    profile_dir = target_dir / ".codexspec" / "profile"
+    for category in PROFILE_CATEGORIES:
+        category_dir = profile_dir / category
+        category_dir.mkdir(parents=True, exist_ok=True)
+        keep = category_dir / ".gitkeep"
+        if not keep.exists():
+            keep.write_text("", encoding="utf-8")
+    return profile_dir
+
+
+def render_profile_block() -> str:
+    """Render the bounded managed profile block.
+
+    Identical for CLAUDE.md and AGENTS.md: constraints and the three on-demand
+    categories are all delivered as pointers to their directories — no ``@import``
+    anywhere — so the block is channel-neutral and the store can be
+    one-file-per-record directories that merge without conflict.
+    """
+    return _PROFILE_BLOCK
+
+
+def inject_profile_block(context_path: Path) -> None:
+    """Idempotently inject/update the profile block in ``context_path``.
+
+    Only the bounded ``<!-- CODEXSPEC PROFILE START/END -->`` region is written;
+    any other content in the file is preserved verbatim. Creates the file if it
+    does not exist.
+    """
+    block = render_profile_block().rstrip("\n")
+    existing = context_path.read_text(encoding="utf-8") if context_path.exists() else ""
+
+    pattern = re.compile(
+        re.escape(PROFILE_BLOCK_START) + r".*?" + re.escape(PROFILE_BLOCK_END),
+        re.DOTALL,
+    )
+    if pattern.search(existing):
+        # Function replacement avoids backslash/group interpretation in `block`.
+        updated = pattern.sub(lambda _match: block, existing)
+    elif existing.strip():
+        updated = existing.rstrip() + "\n\n" + block + "\n"
+    else:
+        updated = block + "\n"
+
+    context_path.write_text(updated, encoding="utf-8")

{codexspec-0.7.7 → codexspec-0.7.9}/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.9/templates/commands/debug.md

@@ -0,0 +1,80 @@
+---
+description: Debug a failure to its root cause before proposing any fix
+argument-hint: "[error text | failing test | file:line | plain-language symptom]"
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write
+---
+
+# Systematic Debugger
+
+## 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 (requirements/spec/plan/tasks).
+
+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.
+
+## User Input
+
+`$ARGUMENTS`
+
+## Role and Iron Law
+
+You debug a reported symptom to its **root cause** and apply exactly one verified fix.
+
+**Iron Law: NO FIX BEFORE ROOT CAUSE.** You MUST NOT propose, apply, or even sketch a fix until Phase 1 has established what is actually wrong and why. Symptom patches — wrapping the error, silencing a failing assertion, retrying blindly — are failures, not fixes.
+
+Red flags that mean STOP and return to Phase 1: "let me just try changing X", "add a try/except here", "it's probably the Y" — any edit attempted before the failure is reproduced and understood.
+
+You leave **no persistent artifact**: no report file, no debug journal. Your output is the fix plus a concise root-cause explanation in the conversation. (Reusable, cross-feature lessons are captured separately by `/codexspec:distill`, never written here.)
+
+## Symptom Intake
+
+Take the symptom from `$ARGUMENTS` when provided — an error or stack trace, a failing-test id, a `file:line`, or a plain-language description — otherwise from error output already visible in this session.
+
+When the symptom is too thin to act on, **reproduce-or-ask** before doing anything else:
+
+- First attempt to reproduce it yourself: run the failing test, exercise the path, read the log or stack trace.
+- If you still cannot reproduce it reliably, ask the user for exactly what is missing — reproduction steps, the precise input that triggers it, expected-vs-actual behavior, the verbatim error, and when it started.
+- Do NOT propose a fix for an unreproduced symptom.
+
+## Investigation Protocol
+
+Work the phases in order. Phase 1 is a hard gate.
+
+### Phase 1 — Root-Cause Investigation (hard gate)
+
+- Read the error/failure carefully and completely; do not skim.
+- Reproduce it consistently. A flaky or order-dependent failure must be made reliably reproducible before you continue.
+- Check what changed recently — the diff, recent commits, configuration.
+- Trace the data and control flow **backward** from the symptom to where the wrong state originates. Inspect enough callers, callees, and inputs to locate the true origin; it is often not where the error surfaces.
+- **Exit criterion**: you can state, in one sentence, WHAT is wrong and WHY. Until then, no fix.
+
+### Phase 2 — Pattern Analysis
+
+- Find a working reference: a passing sibling test, an analogous code path, or an earlier good state.
+- Compare the failing case against it and enumerate every material difference.
+- Identify which difference actually explains the root cause.
+
+### Phase 3 — Hypothesis & Verification
+
+- Write down a single, specific hypothesis about the root cause.
+- Test it minimally — change one variable at a time, and predict the outcome before observing it.
+- Confirm or reject. If rejected, reformulate; do not stack untested guesses.
+
+### Phase 4 — Fix
+
+- Write a failing test first that captures the defect (a reproducing regression test) and observe it fail for the right reason. For a symptom with no natural unit test — a documentation or configuration defect, a production-log incident — construct the closest reproducing check instead.
+- Apply a single, minimal fix that targets the root cause — not the symptom, and no "while I'm here" changes.
+- Verify: the new test passes and no previously-passing test breaks.
+
+### Architecture Gate (≥3 failed fixes)
+
+If three fixes for the same problem have failed, STOP. Do not attempt a fourth blind fix. Repeated failure is evidence that the model of the problem — or the architecture — is wrong. Surface it: state what was tried, why each attempt failed, and what architectural question must be answered before continuing.
+
+## Completion
+
+- Report the root cause (one or two sentences), the fix applied, and the verification that shows it green.
+- **When you were entered from another command** (for example, `implement-tasks` escalated into this discipline), do not end the session: hand control back and **resume that command** exactly where it left off, now with the defect resolved.
+- If you could not reach a root cause, or you hit the Architecture Gate, say so plainly with the evidence. Never paper over it with a speculative fix.

{codexspec-0.7.7 → codexspec-0.7.9}/templates/commands/distill.md

@@ -42,17 +42,18 @@ Apply this boundary test to every candidate: **"Would a single feature's `requir
 
 ## The profile store: `.codexspec/profile/`
 
-Four markdown files, each holding **only current-effective** knowledge — dense, with no "retired" section (git history is the ledger). Create the directory and file on first write.
+Four **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.
 
-- `constraints.md` — negative constraints (`严禁 / 仅允许`). These carry the **highest** weight and MUST be honored first.
-- `conventions.md` — positive cross-feature conventions / steering.
-- `pitfalls.md` — cross-feature traps and their workarounds.
-- `decisions.md` — cross-feature / architectural decisions only (ADR-lite). **Never** single-feature requirement rationale.
+- `constraints/` — negative constraints (`严禁 / 仅允许`). These carry the **highest** weight and MUST be honored first.
+- `conventions/` — positive cross-feature conventions / steering.
+- `pitfalls/` — cross-feature traps and their workarounds.
+- `decisions/` — cross-feature / architectural decisions only (ADR-lite). **Never** single-feature requirement rationale.
 
 ### Record format — `claim` and `evidence` physically separated
 
 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.
 - `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.**
@@ -63,10 +64,10 @@ Every record MUST separate the distilled claim from the evidence it rests on:
 
 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:
+Example entry — file `conventions/Con-2026-0809-2219gg-1.md`:
 
 ```markdown
-### C-003: Prefer absolute imports
+### Con-2026-0809-2219gg-1: Prefer absolute imports
 - claim: Always use absolute imports in `src/`.
 - type: convention
 - scope/when: Python modules under `src/`
@@ -80,7 +81,7 @@ Example entry:
 
 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`.
 
-Before writing, **read the current profile** and skip anything already covered; update anything changed via `replace`. **This is how deduplication is done — by judgment, not an algorithm.**
+Before writing, **read the current profile** (the record files under each category directory) and skip anything already covered; update anything changed via `replace`. **This is how deduplication is done — by judgment, not an algorithm.**
 
 ## Conflict adjudication
 
@@ -93,13 +94,13 @@ When a new item conflicts with an existing rule, resolve in this order:
 
 ## Mutation discipline
 
-Change the profile **only** through three conceptual operations (you edit the markdown directly — these are a discipline, **not** a tool API or matching algorithm):
+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` — append a new verified item.
-- `replace` — supersede an outdated/wrong item in place (keeps files dense).
-- `remove` — delete an item invalidated by a changed environment.
+- `add` — create a new record file `<category>/<id>.md` 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.
 
-git history is the audit ledger. Do **NOT** keep a retired section inside the files.
+git history is the audit ledger. Do **NOT** keep a retired file or a retired section.
 
 ## Vetting candidates (manual, interactive)