codexspec 0.7.7__tar.gz → 0.7.8__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.7
+Version: 0.7.8
 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
@@ -589,6 +589,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.8}/README.md

@@ -544,6 +544,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.8}/pyproject.toml

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

{codexspec-0.7.7 → codexspec-0.7.8}/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.8"
 __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.8}/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 (9) -> enhanced (6) -> git (2) -> review (1) -> utility (2)
-        Total: 20 commands
+        core (9) -> enhanced (7) -> git (2) -> review (1) -> utility (2)
+        Total: 21 commands
     """
     return [
         # Core Commands (9)
@@ -115,7 +115,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 +158,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.8}/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)

codexspec-0.7.8/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.8/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.8}/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)
 

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

@@ -90,6 +90,7 @@ For **each task**, determine the workflow based on task type:
 3. **Verify - Run Tests**
    - Execute all relevant tests
    - Ensure new tests pass and no existing tests break
+   - If a test stays red across several green attempts, a fix reddens a previously-passing test, or you catch yourself guessing: stop patching and follow **Systematic Debugging Escalation** (below)
 
 4. **Review & Refactor**
    - Check for bugs, edge cases, security issues
@@ -231,7 +232,9 @@ Apply only verified repairs:
 
 - For a functional defect, first add a reproducing regression test and observe
   the expected failure. Then use red-green-refactor until the defect is fixed
-  while existing behavior remains green.
+  while existing behavior remains green. When such a repair is non-trivial — the
+  cause is not a mechanical local edit but must be traced across call chains,
+  state, or data flow — follow **Systematic Debugging Escalation** (below).
 - For documentation and non-code configuration defects, use the applicable
   deterministic checks before and after the repair. Do not manufacture a code
   test when the binding contract is non-code.
@@ -293,6 +296,25 @@ or a commit.
   a commit, create it only after the applicable checks are green; a commit must
   never alter, replace, or imply the review verdict.
 
+## Systematic Debugging Escalation
+
+When a fix is not converging, escalate into the systematic root-cause discipline instead of continuing to patch. This is a reference, not a duplicate: the discipline lives once in `/codexspec:debug`.
+
+**Trip conditions** (either one):
+
+- **(a) During the TDD Verify/green loop (§3)**: the same test stays red after several green attempts, a fix reddens a previously-passing test, or you notice guess-and-check behavior.
+- **(b) During a test-safe repair (§7.4)**: you are fixing a **functional/correctness (or robustness) defect** whose fix is **non-trivial** — it requires tracing across call chains, state, or data flow, not a mechanical local edit. This trip does NOT apply to idiomatic-clarity, architecture, constitution-alignment, style, or trivial mechanical fixes.
+
+**Escalation**:
+
+```text
+Invoke /codexspec:debug
+```
+
+Apply its root-cause discipline to the failing test (trip a) or the defect under repair (trip b). The escalation is **non-gating and low-ceremony**: it produces no PASS/FAIL, emits no mandatory notice line, and does not interrupt the user.
+
+**Resume**: once `debug` has reached the root cause and applied a verified fix, **return here and continue** the task or repair exactly where you left off — re-establish the green baseline and proceed. There is no runtime stack; resuming is your responsibility, not the engine's.
+
 ## Automatic Distillation
 
 Read `workflow.auto_distill` from `.codexspec/config.yml` (**default `true`** — enabled unless explicitly set to the literal `false`; absent or any non-`false` value means enabled).

{codexspec-0.7.7 → codexspec-0.7.8}/templates/commands/specify.md

@@ -50,6 +50,15 @@ When the argument identifies an existing feature:
 4. Load the existing `requirements.md`.
 5. Legacy feature: if only `spec.md` exists, extract candidate entries from it, mark them `open`, and require user confirmation before they become authoritative.
 
+## Consult Project Profile
+
+Before discussing and finalizing requirements, read the project profile under `.codexspec/profile/` when it exists so the confirmed `requirements.md` is a synthesis that already accounts for accumulated project knowledge. Each category is a directory holding one record per file:
+
+- `constraints/` first — the project's hard prohibitions (highest weight); requirements MUST NOT contradict them.
+- `pitfalls/`, `conventions/`, `decisions/` — read the records relevant to this feature's area, to avoid re-hitting known traps, to follow established conventions, and to reuse past cross-feature/architectural decisions rather than re-litigating them.
+
+Each record carries a `status` (`candidate` or `vetted`); weight `candidate` entries with appropriate caution. Fold what is relevant into the discussion and the resulting entries; cite a profile record as evidence when it materially shapes a decision. This is the single point where the profile enters the SDD pipeline — downstream stages keep `requirements.md` as authority and do not re-read the profile. Degrade silently when the profile is absent or empty (nothing to apply); never block on it.
+
 ## Discussion Rules
 
 - Ask one material question at a time.