codexspec 0.7.6__tar.gz → 0.7.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexspec
-Version: 0.7.6
+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>
 
@@ -589,6 +590,13 @@ Implementation follows **conditional TDD workflow**:
 | `/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                                       |

{codexspec-0.7.6 → 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>
 
@@ -544,6 +545,13 @@ Implementation follows **conditional TDD workflow**:
 | `/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                                       |

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

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

{codexspec-0.7.6 → 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.6 → 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.6 → 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.6 → 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.6 → 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.6 → codexspec-0.7.7}/templates/commands/implement-tasks.md

@@ -292,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.6 → 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.