claude-dev-env 8.9.0 → 8.11.0

package/hooks/lifecycle/test_nested_project_hooks.py

@@ -0,0 +1,251 @@
+"""Behavior tests for the nested project hooks forwarder.
+
+Each case builds a session directory that holds child checkouts, runs the hook
+script the way Claude Code does (payload on stdin, ``CLAUDE_PROJECT_DIR`` set
+to the session directory), and reads the exit code and output it produces.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+HOOK_SCRIPT_PATH = pathlib.Path(__file__).parent / "nested_project_hooks.py"
+BLOCKING_EXIT_CODE = 2
+
+
+def _make_checkout(
+    session_directory: pathlib.Path,
+    checkout_name: str,
+    all_hook_groups_by_event: dict[str, list[dict[str, object]]],
+) -> pathlib.Path:
+    checkout_directory = session_directory / checkout_name
+    (checkout_directory / ".git").mkdir(parents=True)
+    settings_directory = checkout_directory / ".claude"
+    settings_directory.mkdir()
+    (settings_directory / "settings.json").write_text(
+        json.dumps({"hooks": all_hook_groups_by_event}), encoding="utf-8"
+    )
+    return checkout_directory
+
+
+def _command_group(matcher: str, command: str) -> dict[str, object]:
+    return {"matcher": matcher, "hooks": [{"type": "command", "command": command}]}
+
+
+def _run_hook(
+    session_directory: pathlib.Path, payload: dict[str, object]
+) -> subprocess.CompletedProcess[str]:
+    hook_environment = dict(os.environ)
+    hook_environment["CLAUDE_PROJECT_DIR"] = str(session_directory)
+    return subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT_PATH)],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        env=hook_environment,
+        check=False,
+        timeout=60,
+    )
+
+
+def _pre_tool_use_payload(tool_name: str) -> dict[str, object]:
+    return {"hook_event_name": "PreToolUse", "tool_name": tool_name, "tool_input": {}}
+
+
+def _session_start_payload() -> dict[str, object]:
+    return {"hook_event_name": "SessionStart", "source": "startup"}
+
+
+def test_should_run_a_child_session_start_hook_inside_that_child(
+    tmp_path: pathlib.Path,
+) -> None:
+    record_path = tmp_path / "record.txt"
+    checkout_directory = _make_checkout(
+        tmp_path / "session",
+        "alpha",
+        {
+            "SessionStart": [
+                _command_group(
+                    "",
+                    f'echo "$CLAUDE_PROJECT_DIR|$(pwd)" > "{record_path}"',
+                )
+            ]
+        },
+    )
+
+    completed_process = _run_hook(tmp_path / "session", _session_start_payload())
+
+    assert completed_process.returncode == 0
+    resolved_checkout = str(checkout_directory.resolve())
+    project_directory, working_directory = (
+        record_path.read_text(encoding="utf-8").strip().split("|")
+    )
+    assert str(pathlib.Path(project_directory).resolve()) == resolved_checkout
+    assert str(pathlib.Path(working_directory).resolve()) == resolved_checkout
+
+
+def test_should_carry_child_session_start_output_as_additional_context(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"SessionStart": [_command_group("", "echo alpha is ready")]},
+    )
+    _make_checkout(
+        tmp_path,
+        "beta",
+        {"SessionStart": [_command_group("", "echo beta is ready")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _session_start_payload())
+
+    assert completed_process.returncode == 0
+    hook_output = json.loads(completed_process.stdout)
+    additional_context = hook_output["hookSpecificOutput"]["additionalContext"]
+    assert hook_output["hookSpecificOutput"]["hookEventName"] == "SessionStart"
+    assert "alpha is ready" in additional_context
+    assert "beta is ready" in additional_context
+    assert additional_context.index("alpha") < additional_context.index("beta")
+
+
+def test_should_block_a_tool_call_when_a_child_hook_exits_two(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("Bash", "echo the gate refused this >&2; exit 2")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == BLOCKING_EXIT_CODE
+    assert "the gate refused this" in completed_process.stderr
+
+
+def test_should_pass_a_child_deny_decision_through(tmp_path: pathlib.Path) -> None:
+    deny_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": "no receipt for this commit",
+        }
+    }
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {
+            "PreToolUse": [
+                _command_group(
+                    "Bash|mcp__github__merge_pull_request",
+                    f"echo '{json.dumps(deny_output)}'",
+                )
+            ]
+        },
+    )
+
+    completed_process = _run_hook(
+        tmp_path, _pre_tool_use_payload("mcp__github__merge_pull_request")
+    )
+
+    assert completed_process.returncode == 0
+    assert json.loads(completed_process.stdout) == deny_output
+
+
+def test_should_not_forward_a_child_allow_decision(tmp_path: pathlib.Path) -> None:
+    allow_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+        }
+    }
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", f"echo '{json.dumps(allow_output)}'")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout.strip() == ""
+
+
+def test_should_skip_a_child_hook_whose_matcher_names_another_tool(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("Write|Edit", "exit 2")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+
+
+def test_should_do_nothing_when_the_session_directory_is_a_checkout(
+    tmp_path: pathlib.Path,
+) -> None:
+    (tmp_path / ".git").mkdir()
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", "exit 2")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout.strip() == ""
+
+
+def test_should_skip_a_child_directory_that_is_not_a_checkout(
+    tmp_path: pathlib.Path,
+) -> None:
+    checkout_directory = _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", "exit 2")]},
+    )
+    (checkout_directory / ".git").rmdir()
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+
+
+def test_should_let_the_call_through_when_a_child_hook_fails_to_start(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", "a-command-that-does-not-exist")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+
+
+@pytest.mark.parametrize("unreadable_settings", ["{not json", "[]", '{"hooks": []}'])
+def test_should_skip_a_child_whose_settings_cannot_be_read(
+    tmp_path: pathlib.Path, unreadable_settings: str
+) -> None:
+    checkout_directory = _make_checkout(tmp_path, "alpha", {})
+    (checkout_directory / ".claude" / "settings.json").write_text(
+        unreadable_settings, encoding="utf-8"
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0

package/hooks/session/skill_loaded_reminder.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
-"""PreToolUse, SessionStart and UserPromptSubmit hook. Keeps poteto-mode loaded in every context.
+"""Hook that keeps poteto-mode loaded in every session, subagent and workflow helper.
 
 ::
 
-    Agent tool call, prompt lacks the skill      -> prompt opens with "invoke pstack:poteto-mode"
+    Agent or Codex spawn_agent, skill not named -> prompt opens with "invoke pstack:poteto-mode"
+    Workflow script helper starts               -> "invoke pstack:poteto-mode now"
     context compacted mid-run                    -> "invoke pstack:poteto-mode again"
     user turn, skill not loaded since compacting -> "invoke pstack:poteto-mode now"
     user turn, skill already loaded              -> nothing
@@ -25,7 +26,6 @@ if _hooks_dir not in sys.path:
 
 from hooks_constants.skill_loaded_reminder_constants import (
     ALL_SELF_LOADING_SUBAGENT_TYPES,
-    ALL_SUBAGENT_TOOL_NAMES,
     ASSISTANT_ENTRY_TYPE,
     COMPACT_BOUNDARY_SUBTYPE,
     COMPACTION_REMINDER,
@@ -37,10 +37,12 @@ from hooks_constants.skill_loaded_reminder_constants import (
     SESSION_START_EVENT_NAME,
     SKILL_TOOL_NAME,
     SLASH_COMMAND_MARKER,
-    SUBAGENT_PROMPT_PREFIX,
+    SUBAGENT_START_EVENT_NAME,
+    ALL_SPAWN_PROMPT_FIELDS_AND_PREFIXES_BY_TOOL_NAME,
     TOOL_USE_BLOCK_TYPE,
     USER_ENTRY_TYPE,
     USER_PROMPT_SUBMIT_EVENT_NAME,
+    WORKFLOW_SUBAGENT_TYPE,
 )
 from hooks_constants.pre_tool_use_allow_output import write_pre_tool_use_allow_to_stdout
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
@@ -48,25 +50,32 @@ from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY,
 
 
 def subagent_input_with_poteto_mode(
+    tool_name: str,
     all_tool_input_fields: dict[str, object],
 ) -> dict[str, object] | None:
-    """Return the Agent tool input with the poteto-mode instruction first, or None to leave it.
+    """Return the spawn input with the poteto-mode invocation first, or None to leave it.
 
     ::
 
-        {"prompt": "Reply leaf."}                          -> {"prompt": "Before any ...\\n\\nReply leaf."}
-        {"prompt": "Invoke pstack:poteto-mode, then ..."}  -> None
-        {"subagent_type": "pstack:poteto-agent", ...}      -> None, that agent loads the skill itself
+        Agent        {"prompt": "Reply leaf."}   -> {"prompt": "Before any ...\\n\\nReply leaf."}
+        spawn_agent  {"message": "Fix it."}      -> {"message": "$pstack:poteto-mode\\n\\nFix it."}
+        Agent        {"prompt": "Invoke pstack:poteto-mode, then ..."}  -> None
+        Agent        {"subagent_type": "pstack:poteto-agent", ...}      -> None, it loads the skill
+
+    Claude Code spawns through Agent or Task and Codex through spawn_agent, so
+    each tool name carries its own prompt field and invocation text.
 
     Args:
-        all_tool_input_fields: The Agent tool input the session is about to send.
+        tool_name: The spawn tool the session called.
+        all_tool_input_fields: The spawn input the session is about to send.
     """
-    prompt = all_tool_input_fields.get("prompt")
+    field_name, invocation_prefix = ALL_SPAWN_PROMPT_FIELDS_AND_PREFIXES_BY_TOOL_NAME[tool_name]
+    prompt = all_tool_input_fields.get(field_name)
     if not isinstance(prompt, str) or POTETO_MODE_SKILL_NAME in prompt:
         return None
     if all_tool_input_fields.get("subagent_type") in ALL_SELF_LOADING_SUBAGENT_TYPES:
         return None
-    return {**all_tool_input_fields, "prompt": SUBAGENT_PROMPT_PREFIX + PROMPT_SEPARATOR + prompt}
+    return {**all_tool_input_fields, field_name: invocation_prefix + PROMPT_SEPARATOR + prompt}
 
 
 def _invokes_poteto_mode(all_entry_fields: dict[str, object]) -> bool:
@@ -149,6 +158,7 @@ def reminder_for(all_hook_fields: dict[str, object]) -> str | None:
     ::
 
         SessionStart, source compact                     -> COMPACTION_REMINDER
+        SubagentStart, workflow-subagent                 -> NOT_LOADED_REMINDER
         UserPromptSubmit, transcript lacks the skill     -> NOT_LOADED_REMINDER
         UserPromptSubmit, transcript loaded the skill    -> None
 
@@ -158,6 +168,9 @@ def reminder_for(all_hook_fields: dict[str, object]) -> str | None:
     event_name = all_hook_fields.get("hook_event_name")
     if event_name == SESSION_START_EVENT_NAME:
         return COMPACTION_REMINDER if all_hook_fields.get("source") == COMPACTION_SOURCE else None
+    if event_name == SUBAGENT_START_EVENT_NAME:
+        is_workflow_helper = all_hook_fields.get("agent_type") == WORKFLOW_SUBAGENT_TYPE
+        return NOT_LOADED_REMINDER if is_workflow_helper else None
     if event_name != USER_PROMPT_SUBMIT_EVENT_NAME:
         return None
     if _is_loaded_in_transcript(all_hook_fields.get("transcript_path")):
@@ -168,7 +181,7 @@ def reminder_for(all_hook_fields: dict[str, object]) -> str | None:
 def _is_subagent_spawn(all_hook_fields: dict[str, object]) -> bool:
     return (
         all_hook_fields.get("hook_event_name") == PRE_TOOL_USE_EVENT_NAME
-        and all_hook_fields.get("tool_name") in ALL_SUBAGENT_TOOL_NAMES
+        and all_hook_fields.get("tool_name") in ALL_SPAWN_PROMPT_FIELDS_AND_PREFIXES_BY_TOOL_NAME
         and isinstance(all_hook_fields.get("tool_input"), dict)
     )
 
@@ -179,7 +192,9 @@ def main() -> None:
     if hook_payload is None:
         return
     if _is_subagent_spawn(hook_payload):
-        rewritten_input = subagent_input_with_poteto_mode(hook_payload["tool_input"])
+        rewritten_input = subagent_input_with_poteto_mode(
+            hook_payload["tool_name"], hook_payload["tool_input"]
+        )
         if rewritten_input is not None:
             write_pre_tool_use_allow_to_stdout(rewritten_input)
         return

package/hooks/session/test_skill_loaded_reminder.py

@@ -132,14 +132,46 @@ class TestSubagentSpawn:
 class TestSubagentInputWithPotetoMode:
     def test_every_other_input_field_is_kept(self) -> None:
         rewritten_input = reminder.subagent_input_with_poteto_mode(
-            {"prompt": "Go.", "model": "sonnet", "run_in_background": True}
+            "Agent", {"prompt": "Go.", "model": "sonnet", "run_in_background": True}
         )
         assert rewritten_input is not None
         assert rewritten_input["model"] == "sonnet"
         assert rewritten_input["run_in_background"] is True
 
     def test_an_input_with_no_prompt_is_left_alone(self) -> None:
-        assert reminder.subagent_input_with_poteto_mode({"description": "Go"}) is None
+        assert reminder.subagent_input_with_poteto_mode("Agent", {"description": "Go"}) is None
+
+    def test_a_codex_spawn_input_with_only_items_is_left_alone(self) -> None:
+        assert (
+            reminder.subagent_input_with_poteto_mode(
+                "spawn_agent", {"items": [{"type": "text", "text": "Go."}]}
+            )
+            is None
+        )
+
+
+class TestCodexSpawn:
+    def test_a_codex_spawn_message_opens_with_the_skill_mention(self) -> None:
+        emitted = json.loads(
+            _run_main(
+                _agent_call(
+                    {"message": "Fix the failing test.", "model": "gpt-6-luna"},
+                    tool_name="spawn_agent",
+                )
+            )
+        )
+        rewritten_input = emitted["hookSpecificOutput"]["updatedInput"]
+        assert rewritten_input["message"] == "$pstack:poteto-mode\n\nFix the failing test."
+        assert rewritten_input["model"] == "gpt-6-luna"
+        assert "prompt" not in rewritten_input
+
+    def test_a_codex_spawn_message_that_already_mentions_the_skill_is_left_alone(self) -> None:
+        assert (
+            _run_main(
+                _agent_call({"message": "$pstack:poteto-mode\n\nFix it."}, tool_name="spawn_agent")
+            )
+            == ""
+        )
 
 
 class TestIsPotetoModeLoaded:
@@ -202,5 +234,20 @@ class TestReminderFor:
     def test_a_resumed_session_keeps_its_context_and_prints_nothing(self) -> None:
         assert _run_main({"hook_event_name": "SessionStart", "source": "resume"}) == ""
 
+    def test_a_workflow_helper_starting_is_told_to_invoke_the_skill(self) -> None:
+        emitted = json.loads(
+            _run_main({"hook_event_name": "SubagentStart", "agent_type": "workflow-subagent"})
+        )
+        hook_output = emitted["hookSpecificOutput"]
+        assert hook_output["hookEventName"] == "SubagentStart"
+        assert hook_output["additionalContext"] == NOT_LOADED_REMINDER
+
+    def test_an_agent_tool_helper_starting_prints_nothing_since_its_prompt_carries_the_line(
+        self,
+    ) -> None:
+        assert (
+            _run_main({"hook_event_name": "SubagentStart", "agent_type": "general-purpose"}) == ""
+        )
+
     def test_a_payload_that_is_not_json_prints_nothing(self) -> None:
         assert _run_main("not json") == ""

package/hooks/test_followup_ledger.py

@@ -1,6 +1,7 @@
 """Behavior tests for the non-breaking-finding follow-up ledger."""
 
 import json
+import subprocess
 import sys
 from pathlib import Path
 
@@ -82,6 +83,23 @@ def test_record_followup_finding_writes_one_json_object_per_line(tmp_path: Path)
     assert json.loads(all_lines[0])["rule_id"] == "instruction-mode"
 
 
+def test_a_recorded_ledger_stays_out_of_git_status(tmp_path: Path) -> None:
+    subprocess.run(["git", "init", "--quiet", str(tmp_path)], check=True)
+
+    record_followup_finding(
+        tmp_path, FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+    )
+
+    status_result = subprocess.run(
+        ["git", "-C", str(tmp_path), "status", "--porcelain", "--untracked-files=all"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    assert followup_ledger_path(tmp_path).is_file()
+    assert status_result.stdout == ""
+
+
 def test_record_followup_finding_swallows_a_write_failure(tmp_path: Path) -> None:
     blocking_file = tmp_path / ".claude"
     blocking_file.write_text("not a directory", encoding="utf-8")

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.9.0",
+    "version": "8.11.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -27,6 +27,7 @@
         "_shared/",
         "audit-rubrics/",
         "codex-rules/",
+        "pstack-codex-models.md",
         "AGENTS.md",
         ".claude/CLAUDE.md",
         "!**/__pycache__/**",

package/pstack-codex-models.md

@@ -0,0 +1,37 @@
+# pstack model configuration
+
+feature, refactoring: gpt-6-sol
+bug-fix: gpt-6-astra
+perf-issue: gpt-6-sol
+hillclimb: gpt-6-sol
+judgment and prose: gpt-6-astra
+strongest judgment: gpt-6-astra
+how explorer: gpt-6-luna
+how explainer: gpt-6-luna
+why investigators: gpt-6-luna
+why synthesizer: gpt-6-luna
+reflect tooling: gpt-6-sol
+reflect judgment, divergent, synthesizer: gpt-6-astra
+arena runners: gpt-6-astra, gpt-6-sol, gpt-6-luna
+arena cross-judge pool: gpt-6-astra, gpt-6-sol, gpt-6-luna
+swarm workers: gpt-6-luna
+architect runners: gpt-6-astra, gpt-6-sol, gpt-6-luna
+interrogate reviewers: gpt-6-astra, gpt-6-sol, gpt-6-luna
+
+## Reasoning effort
+
+Single-model Luna roles use max. Astra roles use low. Sol roles use medium.
+Panel entries use low, max, xhigh in the listed order.
+Keep duplicate panel entries. Each entry specifies one candidate.
+The cross-judge pool retains the effort paired with each entry.
+
+Apply these substitutions once to incoming model requests:
+- Sol medium through Luna max requests use gpt-6-luna with max effort.
+- Sol high or higher requests use gpt-6-astra with low effort.
+- Terra requests use gpt-6-luna with xhigh effort.
+- Existing Luna requests use gpt-6-luna with high effort.
+
+Explicit role and panel settings above take precedence over substitutions.
+Do not apply substitutions again to their output.
+
+session hook: on

package/rules/bdd.md

@@ -13,7 +13,7 @@
 1. **Deliberate Discovery** — Reduce uncertainty before code; surface what you do not know (Smart & Molak §5.4).
 2. **Illustrate** — Explore goals, constraints, and concrete examples in chat; "given … when … then …" style outcomes.
 3. **Formulate** — Express behavior as narrow **"should …"** specifications the user can approve.
-4. **Automate** — Build each formulated behavior through the TDD inner loop: CODE_RULES §8, red-green-refactor, canonical as stated in [`code-standards.md`](code-standards.md).
+4. **Automate** — Build each formulated behavior with tests. Red-green-refactor is the default loop, and the TDD skill (`pstack:tdd`) carries it: CODE_RULES §8, as stated in [`code-standards.md`](code-standards.md). A prototype may run ahead of its tests and adds them before the pull request goes ready.
 
 Conversation is the essential practice: if discovery is skipped, structured formats do not rescue the workflow (Minimal BDD).
 

package/rules/build-needs-a-user.md

@@ -0,0 +1,53 @@
+# Build Needs a User
+
+**When this applies:** Before you build a new tool, script, hook, gate, skill,
+command, or workflow step. That includes a hook or check built to answer a
+correction.
+
+## Rule
+
+Answer three questions before the first line of the build:
+
+1. **Who calls it?** Name the hook entry, workflow step, skill, command, or
+   module that will run it in this same change.
+2. **When does it first run?** Name the date or the event of first use.
+3. **When was this job last done by hand?** Name the last time, and how often it
+   comes up.
+
+Build when all three have a concrete answer. When the only answer is "it might
+help" or "we could use it later", stop and send the owner one line: what the
+build is for and which question has no answer. Keep the rest of the task moving
+while that line waits.
+
+Search first, per [`prefer-existing-tools.md`](prefer-existing-tools.md). A
+tool that already exists answers the need, and the build is the glue.
+
+## Size the first build to the first use
+
+Build the smallest version that serves the first caller. A correction starts
+as a row in a rule file. It becomes a hook or a lint only when the same
+correction arrives a second time, per
+[`correction-lens.md`](correction-lens.md).
+
+## Where it is enforced
+
+The staged policy lint's `uncalled-new-file` rule reads each code file a change
+adds under `scripts/`, `hooks/`, or `bin/`. It reports the file when its name
+appears only in its own tests, `CHANGELOG.md`, `README.md`, and
+`bin/ever-shipped-skills.mjs`. CI runs that lint against the merge base, so a
+file with no caller turns the pull request red.
+
+## Why
+
+The history of this package holds files that lived weeks and ran never. The
+Codex compatibility watcher shipped 502 lines and 599 lines of tests in July,
+and PR 1488 deleted it in September. Its own test was the only file that named
+it.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`prefer-existing-tools.md`](prefer-existing-tools.md) | Search before you build |
+| [`correction-lens.md`](correction-lens.md) | A repeated correction moves up a layer |
+| [`archiving-agent-config.md`](archiving-agent-config.md) | How an unused capability leaves service |

package/rules/code-standards.md

@@ -18,7 +18,7 @@ Load `CODE_RULES.md` when reviewing a PR, resolving a policy conflict, or genera
 
 Two standards live in `CODE_RULES.md` in full:
 
-- **TDD** — CODE_RULES §8 / AGENTS Tests: red, green, refactor; no production code before a failing test.
+- **TDD** — CODE_RULES §8: red, green, refactor is the default loop for a bug fix and for new behavior, and the TDD skill (`pstack:tdd`) carries the procedure. A prototype may run ahead of its tests and adds them before the pull request goes ready. A bug fix ships with a test that reproduces the bug.
 - **Right-sized engineering** — CODE_RULES §7 / AGENTS Design: functions over classes; concrete over abstract; add an abstraction at the commit that introduces its second concrete implementation. That count is a house call, one occurrence earlier than the rule of three Fowler credits to Don Roberts. The direction comes from the literature; the number does not, so read it as this package's setting rather than as a cited standard.
 
 BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers and formulates the behavior a feature needs, then each formulated behavior is built through the TDD cycle.

package/rules/flag-non-breaking-findings.md

@@ -108,6 +108,13 @@ naming a file that does not exist, an env-var row naming a file that never
 reads the variable, a test outside the testpaths allowlist, and a tracked
 secret.
 
+`scripts/cde_lint.py` splits the policy-lint findings the same way.
+`SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py`
+carries one row per smell, and a check id with no row reads as breaking. Three
+checks are smells there: `test-pairing` and the two paired-test coverage
+checks. The lint prints each as a warning, records it in the ledger, and exits
+zero when no error remains.
+
 ## Sibling rules
 
 | Rule | Role |

package/rules/paired-test-coverage.md

@@ -20,6 +20,8 @@ When you add a public function to a module whose test suite already exercises th
 
 Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so CI is where they report, against the merge base. The two checks cover the two write orders.
 
+Both checks record smells, per [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md). `SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py` declares `code-rules/paired-test-missing-function` and `code-rules/paired-test-omitted-function` as smells. The lint prints each finding as a warning, records it in `.claude/followups/smells.jsonl`, and exits zero when every finding is a warning. A later pull request adds the missing tests.
+
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 
 1. The target is production code — not a test module, hook infrastructure, config module, migration, workflow registry, or `__init__.py`.
@@ -33,8 +35,8 @@ A public function counts as covered when its name appears — imported, called,
 
 ## Relationship to the file-level TDD order
 
-`tdd_enforcer.py` once required a fresh test file to exist before a production module was written, judging coverage one file at a time. Nothing runs it now, and the staged policy lint carries no replacement, so the test-first order is yours to hold. This check judges coverage one function at a time for a module that already carries such a test file. Write the test file first, and the lint then reports any public function that file leaves uncovered.
+No hook or lint checks the order in which a test and its module are written. Red-green-refactor is the default loop, and the TDD skill (`pstack:tdd`) carries it; a prototype may run ahead of its tests and adds them before the pull request goes ready. This check judges coverage one function at a time for a module that already carries a stem-matched test file, and reports any public function that file leaves uncovered.
 
 ## Why this check is mechanical
 
-A public function with no test reads as covered when the module's test file sits right beside it and exercises its siblings. The gap survives review because the suite looks complete. Running the lint on every staged change keeps the module's public surface and its test suite in step.
+A public function with no test reads as covered when the module's test file sits right beside it and exercises its siblings. The gap survives review because the suite looks complete. Running the lint on every staged change records each gap in the follow-up ledger, where `cde followup list` names it until a pull request closes it.

package/rules/testing.md

@@ -25,4 +25,8 @@ Tests exercise production behavior, production data, and production code paths.
 
 ## No Gate Holds the Test-First Order
 
-`tdd_enforcer.py` once required a fresh, failing test before a production module was written. Nothing runs it now, and the staged policy lint carries no replacement. Hold the red-green-refactor order yourself, and let review check it on the diff.
+Red, green, refactor is the default loop for a bug fix and for new behavior. The TDD skill (`pstack:tdd`) carries the procedure, and no hook or lint checks the order. A prototype may run ahead of its tests and adds them before the pull request goes ready. A bug fix ships with a test that reproduces the bug. Review reads the tests on the diff.
+
+## A Fix Carries Its Proof Test
+
+The `Fix test proof` job in `.github/workflows/pr-check.yml` runs `_shared/pr-loop/scripts/fix_pr_test_proof.py` on every pull request whose title starts with `fix`. A fix that changes production code must change at least one Python test that fails on the base and passes on the head. A fix that changes only docs or CI config passes. Version one reads Python tests only, so a fix proven by a JavaScript or PowerShell test needs a Python test beside it.