codexspec 0.7.5__tar.gz → 0.7.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexspec
-Version: 0.7.5
+Version: 0.7.7
 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>
 
@@ -585,10 +586,17 @@ Implementation follows **conditional TDD workflow**:
 | ---------------------------- | --------------------------------------------------------------- |
 | `/codexspec:config`          | Manage project configuration (create/view/modify/reset)         |
 | `/codexspec:clarify`         | Scan spec for ambiguities (4 categories, max 5 questions)       |
-| `/codexspec:analyze`         | Cross-artifact consistency analysis (read-only, severity-based) |
+| `/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                                  |
 
+#### 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
 
 | Command                    | Description                                       |
@@ -617,7 +625,7 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 | Two-Phase Spec      | No                      | Yes (clarify + generate)                      |
 | Review Commands     | Optional                | 3 dedicated review commands + scoring         |
 | Clarify Command     | Yes                     | 4 focus categories, review integration        |
-| Analyze Command     | Yes                     | Read-only, severity-based, constitution-aware |
+| Analyze Command     | Yes                     | Auto-remediating, severity-based, constitution-aware |
 | TDD in Tasks        | Optional                | Conditional on requirements, risk, and policy |
 | Implementation      | Standard                | Conditional TDD (code vs docs/config)         |
 | Extension System    | Yes                     | Yes                                           |

{codexspec-0.7.5 → codexspec-0.7.7}/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>
 
@@ -540,10 +541,17 @@ Implementation follows **conditional TDD workflow**:
 | ---------------------------- | --------------------------------------------------------------- |
 | `/codexspec:config`          | Manage project configuration (create/view/modify/reset)         |
 | `/codexspec:clarify`         | Scan spec for ambiguities (4 categories, max 5 questions)       |
-| `/codexspec:analyze`         | Cross-artifact consistency analysis (read-only, severity-based) |
+| `/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                                  |
 
+#### 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
 
 | Command                    | Description                                       |
@@ -572,7 +580,7 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 | Two-Phase Spec      | No                      | Yes (clarify + generate)                      |
 | Review Commands     | Optional                | 3 dedicated review commands + scoring         |
 | Clarify Command     | Yes                     | 4 focus categories, review integration        |
-| Analyze Command     | Yes                     | Read-only, severity-based, constitution-aware |
+| Analyze Command     | Yes                     | Auto-remediating, severity-based, constitution-aware |
 | TDD in Tasks        | Optional                | Conditional on requirements, risk, and policy |
 | Implementation      | Standard                | Conditional TDD (code vs docs/config)         |
 | Extension System    | Yes                     | Yes                                           |

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

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

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

@@ -43,7 +43,7 @@ from .integrations import get_integrations
 from .translator import SUPPORTED_LANGUAGES, translate
 
 # Version info
-__version__ = "0.7.0"
+__version__ = "0.7.7"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants
@@ -181,6 +181,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 +226,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 +245,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 +287,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)
@@ -1042,6 +1074,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 +1566,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 +1593,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.5 → codexspec-0.7.7}/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 (6) -> git (2) -> review (1) -> utility (2)
+        Total: 20 commands
     """
     return [
         # Core Commands (9)
@@ -144,6 +144,20 @@ 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",
+        },
         # Git Workflow Commands (2)
         {
             "name": "commit-staged",

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

@@ -113,6 +113,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.7/templates/commands/analyze.md

@@ -0,0 +1,99 @@
+---
+description: Analyze end-to-end traceability and consistency across SDD artifacts
+argument-hint: "[feature directory]"
+---
+
+# Cross-Artifact Analyzer
+
+## 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`
+
+## Operating Model
+
+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.
+- 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.
+
+## Inputs
+
+Load:
+
+- `requirements.md`
+- `spec.md`
+- `plan.md`
+- `tasks.md`
+- Constitution
+
+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
+
+Build the chain:
+
+```text
+confirmed NEED/CON/DEC/OUT
+  -> REQ/NFR Sources
+  -> plan Covers
+  -> task Covers + Plan reference
+```
+
+Detect:
+
+- Confirmed requirements with no spec coverage
+- Spec requirements with missing or invalid sources
+- Spec requirements 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
+- Dependency or ordering conflicts that prevent execution
+
+## Remediation
+
+Resolve findings along two dimensions. `requirements.md` is never edited.
+
+- **Completeness** — every upstream authority (ultimately `requirements.md`) must be covered downstream. For an uncovered upstream item, auto-add the missing downstream coverage. A downstream entry that only adds derived or elaborated detail without upstream authority does **not** harm completeness and is preserved untouched — its mere existence is not a defect.
+- **Consistency** — act **only on conflicts**: a downstream entry that contradicts `requirements.md`/upstream truth or another entry. Resolve a conflict by conforming the unauthorized or lower-authority side with the **minimal change** needed to remove it. When there is no conflict, take no action.
+- **Determinism** — the fix direction is dictated by the authority hierarchy; never invent intent, and never rewrite `requirements.md`.
+- **Conflict tie-break** — when two conflicting entries share no adjudicating upstream, trace both to their nearest common upstream authority and conform to it. If genuinely no common upstream exists, leave both entries unchanged and report the unresolved conflict; analyze still completes and does not gate or escalate.
+
+Apply only deterministic, authority-directed remediations automatically. Keep optional Risk Advisories and Design Opportunities separate; never auto-apply those.
+
+## Finding Rules
+
+Use the same evidence requirements as the review commands:
+
+- Evidence
+- Location
+- Mismatch
+- Impact
+- Remediation
+
+Merge the same root cause. Separate optional Risk Advisories and Design Opportunities from verified defects.
+
+## Output
+
+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"
+- Verified defects by severity that were not auto-remediable (for example, a reported-only tie-break conflict)
+- Unmapped or unauthorized items
+- Risk Advisories
+- Design Opportunities
+- Coverage counts for each link in the chain
+
+`requirements.md` is never among the changed files. It is valid to report zero findings and zero remediations.

{codexspec-0.7.5 → codexspec-0.7.7}/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.5 → codexspec-0.7.7}/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.7/templates/commands/distill.md

@@ -0,0 +1,110 @@
+---
+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 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.
+
+- `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.
+
+### Record format — `claim` and `evidence` physically separated
+
+Every record MUST separate the distilled claim from the evidence it rests on:
+
+- `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:
+
+```markdown
+### C-003: 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** 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 markdown 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.
+
+git history is the audit ledger. Do **NOT** keep a retired section inside the files.
+
+## 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.7/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.5 → codexspec-0.7.7}/templates/commands/implement-tasks.md

@@ -212,6 +212,19 @@ non-PASS and cannot be declared successful by the implementer.
 If verification requires a new product or architecture decision, stop and
 request that decision. Do not invent intent or weaken the requirement.
 
+#### 7.3a Scenario Coverage Self-Check
+
+Independently of the reviewer — do not extend or rely on `review-code` for this —
+verify that every test scenario enumerated in `tasks.md` maps to at least one
+implemented test that genuinely exercises and asserts it. A scenario with no
+covering test, or covered only by a hollow or non-asserting test (the test must
+assert the scenario's expected outcome), is a blocking scenario-coverage gap.
+
+Treat each gap as a verified obligation and repair it via 7.4 (red-green: add the
+covering test, observe it fail for the missing behavior, then make it pass), then
+re-verify and re-review per 7.5. This check is owned by this implementer; it adds
+no command and does not modify `review-code`.
+
 #### 7.4 Apply Test-Safe Repairs
 
 Apply only verified repairs:
@@ -260,8 +273,8 @@ or cleared by an audit score.
 
 Success requires a final valid `PASS` envelope from a fresh complete-feature
 review, with complete requirements and verification, isolated required reviewer
-topology, zero P0-P3 counts, no blocking coverage gaps, and a still-green
-baseline.
+topology, zero P0-P3 counts, no blocking coverage gaps, no uncovered enumerated
+test scenario from `tasks.md` (per 7.3a), and a still-green baseline.
 
 Any `FAIL`, persistent `INCONCLUSIVE`, unresolved verified defect, repeated
 refuted finding, decision requirement, or no-progress guard is blocking. Preserve
@@ -279,3 +292,13 @@ 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.
+
+## 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.5 → codexspec-0.7.7}/templates/commands/plan-to-tasks.md

@@ -60,6 +60,9 @@ Stop instead of guessing when:
 - Mark `[P]` only when tasks can actually run concurrently after their declared dependencies. Missing `[P]` is not inherently a defect.
 - Require test-first ordering only when mandated by the constitution, specification, plan, or established repository workflow.
 - Otherwise include the appropriate verification task without imposing TDD as a universal method.
+- For every **testable** task, enumerate an explicit, individually identifiable **Test Scenarios** list: the happy path plus the boundary and error conditions the behavior implies. Non-testable tasks (docs, config, assets, infrastructure) keep their deterministic verification and do not carry test scenarios.
+- Derive test scenarios from the specification's acceptance criteria and the covered requirement's behavior, expanding them into concrete cases; never invent scenarios with no upstream basis. If upstream behavior is too underspecified to enumerate meaningful scenarios, stop per the Stop Conditions rather than guessing.
+- Keep each scenario individually identifiable and traceable so implementation and the `implement-tasks` self-check can map each scenario to a test one-to-one. Do not pad: enumerate only scenarios the behavior actually implies.
 - Do not add polish, monitoring, abstraction, documentation, or hardening tasks unless they are required by the approved plan, repository policy, or a verified implementation need.
 
 ## Required Output
@@ -71,7 +74,8 @@ Include:
 - Task groups derived from the plan
 - Task IDs, outcomes, paths, dependencies, and traceability
 - Verification steps and checkpoints appropriate to the change
-- A coverage table mapping plan components and requirements to tasks
+- An explicit **Test Scenarios** list for every testable task (happy path plus behavior-implied boundary/error cases), each scenario individually identifiable
+- A coverage table mapping plan components and requirements to tasks, including scenario-to-task mapping for testable tasks
 - Unmapped tasks, if any, with explicit justification
 
 ## Pre-Save Validation
@@ -81,6 +85,7 @@ Include:
 3. Dependencies are acyclic and ordered before dependents.
 4. Verification is sufficient for the actual risk and project policy.
 5. No task expands product scope or silently changes the plan.
+6. Every testable task enumerates sufficient, individually traceable test scenarios (happy path plus behavior-implied boundary/error), all derived from upstream behavior with none invented.
 
 ## Automatic Review Loop
 
@@ -97,9 +102,9 @@ Invoke `/codexspec:review-tasks <feature-dir>/tasks.md`.
 When the review loop above concludes in a passing state — the final `/codexspec:review-tasks` Overall Status is `PASS` or `PASS_WITH_WARNINGS` — invoke `/codexspec:analyze <feature-dir>` exactly once.
 
 - Do not invoke analyze when the review loop stopped at `NEEDS_REVISION` or `BLOCKED`, or stopped early per the conditions above; in those cases end here, handing control back to the user as the review loop already does.
-- analyze runs once and is read-only. Present its output as-is; do not auto-fix its findings and do not run a fix-and-reanalyze loop.
-- If `requirements.md` is absent, analyze still runs and discloses its legacy limitation (it starts at `spec.md` and cannot verify fidelity to the original discussion) per its own behavior.
-- analyze's results are informational only. They do not change whether tasks are ready for implementation and do not add a gate before `/codexspec:implement-tasks`.
+- analyze runs once. It auto-remediates deterministic, authority-directed inconsistencies (conforming `spec.md`/`plan.md`/`tasks.md` to `requirements.md`; it never edits `requirements.md`) and reports the result. Do not run a fix-and-reanalyze loop.
+- If `requirements.md` is absent, analyze still runs in legacy mode, reports findings only (no auto-modification), and discloses its legacy limitation (it starts at `spec.md` and cannot verify fidelity to the original discussion) per its own behavior.
+- analyze's deterministic conforming fixes need no re-review; its remediations and any residual findings do not add a gate before `/codexspec:implement-tasks`.
 - Do not modify the Output Summary for analyze, and do not save an additional analyze report file; analyze's own output is the report.
 
 ## Auto-Next Chain Advance
@@ -111,7 +116,7 @@ When `workflow.auto_next` is `true` AND the review loop above concluded in a pas
 1. Emit exactly one notice line, in the interaction language, e.g. `auto_next: review passed → invoking /codexspec:implement-tasks <feature-dir>`.
 2. Invoke `/codexspec:implement-tasks <feature-dir>` exactly once, with no confirmation prompt, then end this command.
 
-analyze's findings are informational only and do NOT block this advance (see the Automatic Cross-Artifact Analysis section above). Do not auto-advance when `workflow.auto_next` is disabled, or the review loop stopped at `NEEDS_REVISION` or `BLOCKED`, or stopped early; hand control back to the user as the review loop already does. This advances the chain and does not modify the Output Summary.
+analyze's deterministic auto-fixes and any residual findings do NOT block this advance (see the Automatic Cross-Artifact Analysis section above). Do not auto-advance when `workflow.auto_next` is disabled, or the review loop stopped at `NEEDS_REVISION` or `BLOCKED`, or stopped early; hand control back to the user as the review loop already does. This advances the chain and does not modify the Output Summary.
 
 ## Output Summary
 

{codexspec-0.7.5 → codexspec-0.7.7}/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.5/templates/commands/analyze.md

@@ -1,84 +0,0 @@
----
-description: Analyze end-to-end traceability and consistency across SDD artifacts
-argument-hint: "[feature directory]"
----
-
-# Cross-Artifact Analyzer
-
-## 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`
-
-## Operating Constraints
-
-This command is read-only. Do not modify artifacts.
-
-Resolve the feature by explicit path, then current branch. Ask the user if it is ambiguous; never select the latest feature silently.
-
-## Inputs
-
-Load:
-
-- `requirements.md`
-- `spec.md`
-- `plan.md`
-- `tasks.md`
-- Constitution
-
-Legacy compatibility: if `requirements.md` is missing, state that the analysis starts at `spec.md` and cannot validate fidelity to the original discussion.
-
-## End-to-End Traceability
-
-Build the chain:
-
-```text
-confirmed NEED/CON/DEC/OUT
-  -> REQ/NFR Sources
-  -> plan Covers
-  -> task Covers + Plan reference
-```
-
-Detect:
-
-- Confirmed requirements with no spec coverage
-- Spec requirements with missing or invalid sources
-- Spec requirements 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
-- Dependency or ordering conflicts that prevent execution
-
-## Finding Rules
-
-Use the same evidence requirements as the review commands:
-
-- Evidence
-- Location
-- Mismatch
-- Impact
-- Remediation
-
-Merge the same root cause. Separate optional Risk Advisories and Design Opportunities from verified defects.
-
-## Output
-
-Produce:
-
-- Authority mode
-- End-to-end coverage table
-- Verified defects by severity
-- Unmapped or unauthorized items
-- Risk Advisories
-- Design Opportunities
-- Coverage counts for each link in the chain
-
-It is valid to report zero defects.