codexspec 0.7.6__tar.gz → 0.7.8__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codexspec
-Version: 0.7.6
+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
@@ -555,6 +555,7 @@ Implementation follows **conditional TDD workflow**:
 | `--set-commit-lang`, `-c` | Set the commit-message language |
 | `--list-langs`            | List all supported languages |
 | `--auto-next`            | Toggle/set `workflow.auto_next` (bare toggles; or on/off) |
+| `--auto-distill`         | Toggle/set `workflow.auto_distill` (default on; bare toggles; or on/off) |
 
 </details>
 
@@ -588,6 +589,14 @@ 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
+
+| Command | Description |
+| --- | --- |
+| `/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 |
 
 #### Git Workflow Commands
 

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

@@ -510,6 +510,7 @@ Implementation follows **conditional TDD workflow**:
 | `--set-commit-lang`, `-c` | Set the commit-message language |
 | `--list-langs`            | List all supported languages |
 | `--auto-next`            | Toggle/set `workflow.auto_next` (bare toggles; or on/off) |
+| `--auto-distill`         | Toggle/set `workflow.auto_distill` (default on; bare toggles; or on/off) |
 
 </details>
 
@@ -543,6 +544,14 @@ 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
+
+| Command | Description |
+| --- | --- |
+| `/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 |
 
 #### Git Workflow Commands
 

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

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

{codexspec-0.7.6 → 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.0"
+__version__ = "0.7.8"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants
@@ -181,6 +182,11 @@ _AUTO_NEXT_FALSE = {"off", "false", "0", "no"}
 _AUTO_NEXT_SENTINEL = "__toggle__"
 _AUTO_NEXT_ACCEPTED = "on/off, true/false, 1/0, yes/no"
 
+# workflow.auto_distill toggle. Unlike auto_next, auto_distill defaults to ON
+# (opt-out): only the literal ``false`` disables it. Reuses the auto_next token
+# sets for parsing; a distinct sentinel keeps the bare-toggle rewrites separate.
+_AUTO_DISTILL_SENTINEL = "__toggle_distill__"
+
 
 @app.command()
 def config(
@@ -221,6 +227,13 @@ def config(
         "--auto-next",
         help="Toggle workflow.auto_next (bare), or set it (on/off|true/false|1/0|yes/no).",
     ),
+    # ``--auto-distill`` mirrors ``--auto-next``; the bare toggle is rewritten to
+    # ``--auto-distill=<sentinel>`` by ``_normalize_auto_distill_argv`` in ``main()``.
+    auto_distill: Optional[str] = typer.Option(
+        None,
+        "--auto-distill",
+        help="Toggle workflow.auto_distill (bare), or set it (on/off|true/false|1/0|yes/no).",
+    ),
 ) -> None:
     """
     View or modify CodexSpec project configuration.
@@ -233,6 +246,7 @@ def config(
         codexspec config --set-lang zh-CN      # Set language to Chinese
         codexspec config --set-commit-lang en  # Set commit messages to English
         codexspec config --auto-next           # Toggle workflow.auto_next
+        codexspec config --auto-distill off    # Disable workflow.auto_distill (default on)
         codexspec config --list-langs          # List supported languages
     """
     # Handle list languages
@@ -274,6 +288,25 @@ def config(
             raise typer.Exit(1)
         return
 
+    # Handle auto-distill toggle/set
+    if auto_distill is not None:
+        if auto_distill == _AUTO_DISTILL_SENTINEL:
+            target = not _read_auto_distill(config_file)
+        else:
+            try:
+                target = parse_auto_distill_value(auto_distill)
+            except ValueError:
+                console.print(f"[red]Invalid --auto-distill value:[/red] {auto_distill!r}")
+                console.print(f"Accepted values: {_AUTO_NEXT_ACCEPTED} (or pass --auto-distill bare to toggle).")
+                raise typer.Exit(1)
+        if _write_auto_distill(config_file, target):
+            state = "enabled" if target else "disabled"
+            console.print(f"[green]auto_distill {state}[/green] (workflow.auto_distill = {str(target).lower()})")
+        else:
+            console.print("[red]Failed to update workflow.auto_distill[/red]")
+            raise typer.Exit(1)
+        return
+
     # Handle set language
     if set_lang:
         normalized = normalize_locale(set_lang)
@@ -674,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():
@@ -852,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:
@@ -1042,6 +1084,101 @@ def _dump_lines(path: Path, lines: list[str]) -> bool:
     return True
 
 
+# --- workflow.auto_distill toggle helpers ----------------------------------
+
+
+def parse_auto_distill_value(raw: str) -> bool:
+    """Parse an explicit ``--auto-distill`` value into a boolean.
+
+    Accepts the same tokens as ``--auto-next`` (``on/off``, ``true/false``,
+    ``1/0``, ``yes/no``; case-insensitive, surrounding whitespace ignored).
+    Raises ``ValueError`` for any other token.
+    """
+    token = (raw or "").strip().lower()
+    if token in _AUTO_NEXT_TRUE:
+        return True
+    if token in _AUTO_NEXT_FALSE:
+        return False
+    raise ValueError(f"invalid --auto-distill value: {raw!r}")
+
+
+def _read_auto_distill(config_file: Path) -> bool:
+    """Return True unless ``workflow.auto_distill`` is the literal ``false``.
+
+    ``auto_distill`` defaults to enabled (opt-out): an absent key/section, an
+    explicit ``true``, or any non-``false`` value enables it; only the literal
+    ``false`` disables it. A missing file also reads as enabled.
+    """
+    try:
+        content = config_file.read_text(encoding="utf-8")
+    except OSError:
+        return True
+    in_workflow = False
+    for line in content.splitlines():
+        if not line.strip():
+            continue
+        if not line[0].isspace():  # top-level key (or comment)
+            key = line.split("#", 1)[0].strip()
+            in_workflow = key == "workflow:"
+            continue
+        if in_workflow:
+            match = re.match(r"^\s*auto_distill:\s*(\S+?)\s*(?:#.*)?$", line)
+            if match:
+                return match.group(1) != "false"
+    return True
+
+
+def _write_auto_distill(config_file: Path, value: bool) -> bool:
+    """Set ``workflow.auto_distill`` to an unquoted boolean.
+
+    Mirrors ``_write_auto_next``: (1) update the value in place when the key
+    exists under ``workflow:``; (2) insert it as the section's first child when
+    the section exists but the key is absent; (3) append a ``workflow:`` section
+    when absent. Preserves all other lines/comments. Returns ``False`` on I/O
+    error.
+    """
+    try:
+        content = config_file.read_text(encoding="utf-8")
+    except OSError:
+        return False
+
+    token = "true" if value else "false"
+    lines = content.split("\n")
+
+    workflow_idx: Optional[int] = None
+    in_workflow = False
+    for i, line in enumerate(lines):
+        if not line.strip():
+            continue
+        if not line[0].isspace():
+            key = line.split("#", 1)[0].strip()
+            in_workflow = key == "workflow:"
+            if in_workflow:
+                workflow_idx = i
+            continue
+        if in_workflow and re.match(r"^\s*auto_distill:\s*\S+", line):
+            indent = line[: len(line) - len(line.lstrip())]
+            lines[i] = f"{indent}auto_distill: {token}"
+            return _dump_lines(config_file, lines)
+
+    if workflow_idx is not None:
+        lines.insert(workflow_idx + 1, f"  auto_distill: {token}")
+        return _dump_lines(config_file, lines)
+
+    section = f"workflow:\n  auto_distill: {token}"
+    if not content:
+        new_content = section + "\n"
+    elif content.endswith("\n"):
+        new_content = content + "\n" + section + "\n"
+    else:
+        new_content = content + "\n\n" + section + "\n"
+    try:
+        config_file.write_text(new_content, encoding="utf-8")
+    except OSError:
+        return False
+    return True
+
+
 def _next_step_start(integration_keys: set[str], language: str) -> str:
     """Return a target-aware start instruction."""
     if integration_keys == {"codex"}:
@@ -1439,24 +1576,23 @@ The following slash commands are available in this project:
 """
 
 
-def _normalize_auto_next_argv(argv: list[str]) -> list[str]:
-    """Rewrite a bare ``--auto-next`` into ``--auto-next=<sentinel>``.
+def _normalize_optional_value_argv(argv: list[str], flag: str, sentinel: str) -> list[str]:
+    """Rewrite a bare ``flag`` into ``flag=<sentinel>``.
 
     Click 8.3 no longer honors ``flag_value`` for a bare optional-value option
-    (it errors "requires an argument"). To preserve ``codexspec config
-    --auto-next`` (bare) as a toggle, a standalone ``--auto-next`` token — one
-    that is not already in ``--auto-next=...`` form and is not followed by a
-    value token — is rewritten to ``--auto-next=<sentinel>``, which the
-    ``config`` handler interprets as a toggle.
+    (it errors "requires an argument"). A standalone ``flag`` token — one that is
+    not already in ``flag=...`` form and is not followed by a value token — is
+    rewritten to ``flag=<sentinel>``, which the ``config`` handler reads as a
+    toggle.
     """
     out: list[str] = []
     i = 0
     while i < len(argv):
         tok = argv[i]
-        if tok == "--auto-next":
+        if tok == flag:
             nxt = argv[i + 1] if i + 1 < len(argv) else None
             if nxt is None or nxt.startswith("-"):
-                out.append(f"--auto-next={_AUTO_NEXT_SENTINEL}")
+                out.append(f"{flag}={sentinel}")
             else:
                 out.append(tok)
                 out.append(nxt)
@@ -1467,10 +1603,24 @@ def _normalize_auto_next_argv(argv: list[str]) -> list[str]:
     return out
 
 
+def _normalize_auto_next_argv(argv: list[str]) -> list[str]:
+    """Rewrite a bare ``--auto-next`` into ``--auto-next=<sentinel>`` (see
+    ``_normalize_optional_value_argv``)."""
+    return _normalize_optional_value_argv(argv, "--auto-next", _AUTO_NEXT_SENTINEL)
+
+
+def _normalize_auto_distill_argv(argv: list[str]) -> list[str]:
+    """Rewrite a bare ``--auto-distill`` into ``--auto-distill=<sentinel>`` (see
+    ``_normalize_optional_value_argv``)."""
+    return _normalize_optional_value_argv(argv, "--auto-distill", _AUTO_DISTILL_SENTINEL)
+
+
 def main() -> None:
     """Main entry point for the CLI."""
     if "--auto-next" in sys.argv:
         sys.argv = _normalize_auto_next_argv(sys.argv)
+    if "--auto-distill" in sys.argv:
+        sys.argv = _normalize_auto_distill_argv(sys.argv)
     app()
 
 

{codexspec-0.7.6 → 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 (4) -> git (2) -> review (2) -> utility (2)
-        Total: 19 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",
@@ -144,6 +144,27 @@ def get_commands_metadata() -> list[CommandMetadata]:
             "category": "enhanced",
             "file_name": "tasks-to-issues.md",
         },
+        {
+            "name": "distill",
+            "display_name": "/codexspec:distill",
+            "description": "从交互中萃取可复用的跨特性知识到 .codexspec/profile/",
+            "category": "enhanced",
+            "file_name": "distill.md",
+        },
+        {
+            "name": "evolve",
+            "display_name": "/codexspec:evolve",
+            "description": "将 profile 沉淀编译为命令/技能并通过评审 PR 贡献回上游",
+            "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.6 → 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)
@@ -113,6 +118,8 @@ Use these Codex skills when working on CodexSpec workflows:
 - `$codexspec:spec-to-plan` to produce `plan.md`.
 - `$codexspec:plan-to-tasks` to produce `tasks.md`.
 - `$codexspec:implement-tasks` to implement approved tasks.
+- `$codexspec:distill` to capture reusable cross-feature knowledge into `.codexspec/profile/`.
+- `$codexspec:evolve` to contribute vetted profile knowledge back upstream via a reviewed PR.
 
 Before making workflow decisions, read `.codexspec/memory/constitution.md`.
 {CODEXSPEC_CONTEXT_END}

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.6 → codexspec-0.7.8}/templates/commands/commit-staged.md

@@ -157,3 +157,13 @@ If `git commit` fails due to a pre-commit hook modifying files:
 - Report the error message to the user
 - DO NOT attempt to "fix" the situation
 - The user should investigate and resolve manually
+
+## 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).
+
+When `workflow.auto_distill` is enabled (not the literal `false`) AND a commit was created successfully, invoke `/codexspec:distill` exactly once on this session's interaction, then end.
+
+- distill is non-blocking and non-interactive: it never prompts and never alters the commit or its message; it early-exits when there is nothing reusable to capture.
+- distill only writes records to `.codexspec/profile/`; it never touches tracked project files or the git state.
+- Do not invoke distill when `auto_distill` is disabled or when no commit was created (for example, an ABORT above).

{codexspec-0.7.6 → codexspec-0.7.8}/templates/commands/config.md

@@ -107,6 +107,7 @@ Display the configuration as in Step 2, then exit.
       {"label": "Output language (legacy)", "description": "Fallback language used when interaction/document are not set (currently: {current value})"},
       {"label": "Commit language", "description": "Language for commit messages (currently: {current value})"},
       {"label": "Auto-next chain", "description": "Auto-advance the SDD pipeline once a stage passes (workflow.auto_next) (currently: {current value})"},
+      {"label": "Auto-distill", "description": "Run /codexspec:distill on completion of wrap-up commands to capture reusable knowledge (workflow.auto_distill) (currently: {current value})"},
       {"label": "Back", "description": "Return to main menu"}
     ]
   }]
@@ -153,6 +154,29 @@ Display the configuration as in Step 2, then exit.
    a `workflow:` section with `auto_next: <bool>`), preserving every other
    line and comment.
 
+3b. For "Auto-distill", ask whether to enable or disable:
+
+```json
+{
+  "questions": [{
+    "question": "Set workflow.auto_distill:",
+    "header": "Auto-distill",
+    "options": [
+      {"label": "Enable", "description": "Run /codexspec:distill on completion of wrap-up commands"},
+      {"label": "Disable", "description": "Do not auto-distill; run /codexspec:distill manually"},
+      {"label": "Back", "description": "Return without changing"}
+    ]
+  }]
+}
+```
+
+   Then read `.codexspec/config.yml`. `auto_distill` is enabled by default; the
+   current value is disabled only when `workflow.auto_distill` is the literal
+   `false` (an absent key/section, `true`, or any other value is enabled). Write
+   `workflow.auto_distill` as an unquoted `true`/`false` (update the value in place
+   when the key exists; otherwise add `auto_distill: <bool>` under the `workflow:`
+   section, creating that section if absent), preserving every other line and comment.
+
 4. Update the configuration file with the new value
 5. Display the updated configuration
 6. Exit

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.8/templates/commands/distill.md

@@ -0,0 +1,111 @@
+---
+description: Distill reusable, cross-feature knowledge from an interaction into the project profile
+argument-hint: "[interaction segment or context to distill]"
+---
+
+# Distill
+
+## 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` quotes the user's original words verbatim and MUST NOT be translated.
+
+## User Input
+
+`$ARGUMENTS`
+
+## Operating Model
+
+`distill` extracts the reusable, cross-feature knowledge produced during work and persists it to the project-level store `.codexspec/profile/`. It runs two ways:
+
+- **Auto (primary)**: embedded in wrap-up commands (`implement-tasks` on completion, `commit-staged`, `pr`), gated by `workflow.auto_distill` in `.codexspec/config.yml` (**default enabled**; disabled only when explicitly set to the literal `false`).
+- **Manual (fallback)**: invoked directly on the supplied or most-recent interaction segment.
+
+distill is **non-blocking and non-interactive**: it never prompts, never gates another command, and **early-exits without writing** when the delta contains nothing reusable.
+
+**Input contract**: distill operates on "a segment of interaction to distill." It MUST NOT assume it is live in the conversation, so the same routine works whether embedded (fed live context) or invoked manually on a supplied segment.
+
+## What distill captures — and what it must NOT
+
+Capture **only** knowledge that is reusable **across features** and that the per-feature SDD artifacts structurally cannot accumulate.
+
+Apply this boundary test to every candidate: **"Would a single feature's `requirements.md` / `spec.md` / `plan.md` record this?"**
+
+- **Yes** → it is feature-scoped; leave it in that artifact. **Do NOT** copy it into the profile. (Requirement rationale already lives in `requirements.md`; approach rationale in plan/design.)
+- **No / it spans features** → it may enter the profile.
+
+**Never** create a feature-local store. The profile is project-level only; a feature's memory is its existing spec directory.
+
+## The profile store: `.codexspec/profile/`
+
+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/` — 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.**
+- `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`.
+
+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`:
+
+```markdown
+### Con-2026-0809-2219gg-1: Prefer absolute imports
+- claim: Always use absolute imports in `src/`.
+- type: convention
+- 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
+- status: vetted
+```
+
+## 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`.
+
+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
+
+When a new item conflicts with an existing rule, resolve in this order:
+
+1. **Recency** — newer corrections win (usually a `replace`).
+2. **Specificity** — a specific instruction overrides the general one **only within its scope**.
+3. **Scenario-decoupling** — if neither wins, keep **both** under a `scope/when` condition rather than forcing a winner.
+4. **Defer, don't guess** — if genuinely unresolvable, write the record with `status: conflict/needs-adjudication` and surface it at the next interactive point or at evolve time. **Never block, never guess.**
+
+## Mutation discipline
+
+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.
+- `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 file or a retired section.
+
+## Vetting candidates (manual, interactive)
+
+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.**
+
+## 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.8/templates/commands/evolve.md

@@ -0,0 +1,74 @@
+---
+description: Compile vetted project-profile knowledge into a reusable command/skill and contribute it upstream via a reviewed PR
+argument-hint: "[what to evolve, or a profile area]"
+---
+
+# Evolve
+
+## 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.
+
+Converse in the interaction language. **The compiled command/skill draft is a distributed template and MUST be authored in English** (project i18n convention), regardless of `language.document`. PR title/body follow `language.commit`.
+
+## User Input
+
+`$ARGUMENTS`
+
+## Operating Model
+
+`evolve` turns **vetted** sediment in `.codexspec/profile/` into a reusable capability and contributes it back to CodexSpec through a **human-reviewed PR**. It **never merges unattended** and **never** edits install artifacts.
+
+## Selecting what to promote
+
+Promote only records that are **both**:
+
+1. `status: vetted` (never `candidate` or `conflict`), and
+2. **general enough for the toolkit** — the generality extension of distill's boundary test: *"Is this useful to every CodexSpec user, or only to this project?"*
+
+Project-specific knowledge **stays** in the profile. Only generally-useful capability is promoted upstream. When nothing qualifies, stop and report — do not force a promotion.
+
+## Compiling the draft
+
+Compile the selected sediment into a SKILL.md / command-template draft that conforms to both:
+
+- **Anthropic Agent Skills** (SKILL.md + progressive disclosure), and
+- **existing CodexSpec command-template conventions** (YAML frontmatter + sections + `## Language Preference`, English).
+
+Apply these compile rules:
+
+- **Priority order** — core needs first, **negative constraints immediately after (highest weight)**, then the rest.
+- **Logic-clean** — `replace`/`remove` any superseded rule first; the output MUST carry **no** contradictory rules.
+- **Imperative wording** — use **必须 / 始终 / 严禁 / 仅允许** in place of 可以考虑 / 尽量 / 最好不要 / 或许. Match the project's explicit **Prefer / Avoid** rule style; do not use decorative markers.
+
+## Where output goes (self-bootstrap)
+
+Write **only** under `templates/` — a new `templates/commands/*.md` or a standalone skill package. **NEVER** edit `.claude/commands/codexspec/`: it is a regenerated install artifact, and any edit there is silently overwritten on the next reinstall and never reaches users. Changes reach users via `publish` → `init`.
+
+## Contribution mechanics
+
+**Before any `git push` or PR creation, present the compiled draft file(s) and the value statement to the user and obtain explicit approval. Proceed only on approval; NEVER push or open a PR unattended.** (Writing a local draft under `templates/` is git-reversible; the outward action is what is gated.)
+
+On approval, open a PR for human review. **Auto-detect** the git path — this is a mechanics difference only, never a permission tier:
+
+- Upstream **write access** → push a branch in-repo and open the PR.
+- **No write access** → fork, push to the fork, open a cross-repo PR.
+
+Both take the **identical** review path.
+
+## Value gate and PR summary
+
+Produce a one-sentence **value statement** as the PR summary:
+
+> Resolves `<pain>`, by `<added/revised constraint>`, achieving `<quality/efficiency gain>`.
+
+If no crisp value statement can be written, **open NO PR** — the batch is not worth promoting (this is the lightweight substitute for a metric/eval gate).
+
+For review, keep each promoted `claim` paired with its `evidence` so a reviewer can check **claim ⇐ evidence**. A promoted change that later proves worse MUST be rolled back via `remove`/`replace` (git-traceable), not a manual file edit.
+
+## Output
+
+Report in the interaction language: what was selected, the draft file(s) written under `templates/`, and the PR (branch or fork) with its value statement — or **"nothing promoted"** with the reason (value gate / nothing vetted / nothing general enough).

{codexspec-0.7.6 → 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.
@@ -292,3 +295,32 @@ or a commit.
 - Commits remain outside verdict logic. If the surrounding workflow calls for
   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).
+
+When `workflow.auto_distill` is enabled (not the literal `false`) AND this command reported success (§7.6), invoke `/codexspec:distill` exactly once on this session's interaction, then end.
+
+- distill is non-blocking and non-interactive: it never prompts, never changes this command's verdict or report, and early-exits when there is nothing reusable to capture.
+- distill only writes `candidate`/`vetted` records to `.codexspec/profile/`; it MUST NOT modify `requirements.md`, `spec.md`, `plan.md`, or `tasks.md`.
+- Do not invoke distill when `auto_distill` is disabled or when this command did not report success.

{codexspec-0.7.6 → codexspec-0.7.8}/templates/commands/pr.md

@@ -622,3 +622,13 @@ When saving to a file, output the raw markdown content directly (without code bl
 - Include enough detail for reviewers to understand the changes
 - Do not include any AI attribution in the PR description
 - Focus on clarity and usefulness for code reviewers
+
+## 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).
+
+When `workflow.auto_distill` is enabled (not the literal `false`) AND a PR/MR description was generated successfully, invoke `/codexspec:distill` exactly once on this session's interaction, then end.
+
+- distill is non-blocking and non-interactive: it never prompts and never alters the generated description; it early-exits when there is nothing reusable to capture.
+- distill only writes records to `.codexspec/profile/`.
+- Do not invoke distill when `auto_distill` is disabled or when no description was produced.

{codexspec-0.7.6 → 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.