claude-dev-env 8.36.3 → 8.37.0

package/hooks/routing/test_spawn_readiness_hook.py

@@ -0,0 +1,278 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import spawn_readiness_hook
+from hooks_constants.spawn_readiness_hook_constants import (
+    MISSING_INTERVIEW_REASON,
+    MISSING_INVESTIGATION_REASON,
+)
+
+HOOK_SCRIPT = Path(__file__).resolve().parent / "spawn_readiness_hook.py"
+THREAD_SPAWN_TOOL_NAME = "mcp__hearthbot__start_thread_session"
+SETTLED_LINE = "Scope settled: the request names the file, the fix, and the test."
+
+
+def _user(text: str) -> dict[str, object]:
+    return {"type": "user", "message": {"role": "user", "content": text}}
+
+
+def _tool_use(
+    name: str, tool_input: dict[str, object], block_id: str = "toolu_x"
+) -> dict[str, object]:
+    return {
+        "type": "assistant",
+        "message": {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "id": block_id, "name": name, "input": tool_input}],
+        },
+    }
+
+
+def _tool_result(tool_use_id: str, is_error: bool = False) -> dict[str, object]:
+    return {
+        "type": "user",
+        "message": {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": tool_use_id,
+                    "content": "ok",
+                    "is_error": is_error,
+                }
+            ],
+        },
+    }
+
+
+def _queued(prompt: str) -> dict[str, object]:
+    return {"type": "attachment", "attachment": {"type": "queued_command", "prompt": prompt}}
+
+
+READ_STEP = _tool_use("Bash", {"command": "cat README.md"})
+QUESTION_STEP = _tool_use("mcp__hearthbot__ask_decision", {"question": "Which repo should this land in?"})
+REPLY_STEP = _user("The public one.")
+INTERVIEWED_TRANSCRIPT = [_user("Build the hook."), READ_STEP, QUESTION_STEP, REPLY_STEP]
+
+
+def _spawn_input(tool_name: str, brief: str = "Do the task.") -> dict[str, object]:
+    if tool_name == THREAD_SPAWN_TOOL_NAME:
+        return {"title": "Task", "instructions": brief}
+    return {"description": "Task", "prompt": brief}
+
+
+def _write_transcript(tmp_path: Path, all_entries: list[dict[str, object]]) -> Path:
+    transcript_path = tmp_path / "transcript.jsonl"
+    transcript_path.write_text(
+        "".join(json.dumps(each_entry) + "\n" for each_entry in all_entries), encoding="utf-8"
+    )
+    return transcript_path
+
+
+def _run_hook(tmp_path: Path, hook_payload: dict[str, object]) -> str:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps(
+            {"hook_event_name": "PreToolUse", "tool_use_id": "toolu_spawn", **hook_payload}
+        ),
+        capture_output=True,
+        text=True,
+        env={**os.environ, "HOME": str(tmp_path)},
+        check=True,
+    )
+    return completed.stdout
+
+
+def _spawn(
+    tmp_path: Path,
+    all_entries: list[dict[str, object]],
+    tool_name: str = "Agent",
+    brief: str = "Do the task.",
+) -> str:
+    return _run_hook(
+        tmp_path,
+        {
+            "tool_name": tool_name,
+            "tool_input": _spawn_input(tool_name, brief),
+            "transcript_path": str(_write_transcript(tmp_path, all_entries)),
+        },
+    )
+
+
+def _deny_reason(stdout: str) -> str:
+    decision = json.loads(stdout)["hookSpecificOutput"]
+    assert decision["hookEventName"] == "PreToolUse"
+    assert decision["permissionDecision"] == "deny"
+    return decision["permissionDecisionReason"]
+
+
+def _decision_log(tmp_path: Path) -> list[dict[str, object]]:
+    log_path = tmp_path / ".claude" / "logs" / "spawn-readiness.jsonl"
+    return [
+        json.loads(each_line) for each_line in log_path.read_text(encoding="utf-8").splitlines()
+    ]
+
+
+@pytest.mark.parametrize("tool_name", ["Agent", "Task", THREAD_SPAWN_TOOL_NAME])
+def test_should_let_the_spawn_run_after_a_read_a_question_and_a_reply(
+    tmp_path: Path, tool_name: str
+) -> None:
+    assert _spawn(tmp_path, INTERVIEWED_TRANSCRIPT, tool_name) == ""
+
+
+def test_should_deny_a_spawn_with_no_read_since_the_request(tmp_path: Path) -> None:
+    transcript = [_user("Build the hook."), QUESTION_STEP, REPLY_STEP]
+    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INVESTIGATION_REASON
+
+
+def test_should_deny_a_spawn_with_no_question_to_the_user(tmp_path: Path) -> None:
+    transcript = [_user("Build the hook."), READ_STEP]
+    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+
+
+def test_should_deny_a_spawn_whose_question_has_no_reply_yet(tmp_path: Path) -> None:
+    transcript = [_user("Build the hook."), READ_STEP, QUESTION_STEP]
+    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+
+
+def test_should_name_both_gaps_when_the_session_did_neither(tmp_path: Path) -> None:
+    reason = _deny_reason(_spawn(tmp_path, [_user("Build the hook.")]))
+    assert reason == f"{MISSING_INVESTIGATION_REASON} {MISSING_INTERVIEW_REASON}"
+
+
+def test_should_count_a_plain_chat_question_as_no_interview(
+    tmp_path: Path,
+) -> None:
+    statement = _tool_use("mcp__hearthbot__post_message", {"text": "Which repo should this land in?"})
+    transcript = [_user("Build the hook."), READ_STEP, statement, REPLY_STEP, READ_STEP]
+    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+
+
+def test_should_count_an_answered_ask_user_question_as_the_interview(tmp_path: Path) -> None:
+    transcript = [
+        _user("Build the hook."),
+        _tool_use("Read", {"file_path": "README.md"}),
+        _tool_use("AskUserQuestion", {"questions": []}, block_id="toolu_ask"),
+        _tool_result("toolu_ask"),
+    ]
+    assert _spawn(tmp_path, transcript) == ""
+
+
+def test_should_count_an_answered_widget_as_the_interview(tmp_path: Path) -> None:
+    widget = _tool_use("mcp__hearthbot__post_widget", {"family": "visualize", "input": {}})
+    transcript = [_user("Build the hook."), READ_STEP, widget, _user("The left layout.")]
+    assert _spawn(tmp_path, transcript) == ""
+
+
+def test_should_count_an_answered_decision_card_as_the_interview(tmp_path: Path) -> None:
+    transcript = [
+        _user("Build the hook."),
+        _tool_use("mcp__hearthbot__fetch_thread", {"thread_id": "t"}),
+        _tool_use("mcp__hearthbot__ask_decision", {"question": "Pick one"}),
+        _queued('<wake reason="mention"><message from="human">Option one.</message></wake>'),
+    ]
+    assert _spawn(tmp_path, transcript, THREAD_SPAWN_TOOL_NAME) == ""
+
+
+def test_should_skip_an_agent_relay_as_the_reply(tmp_path: Path) -> None:
+    relay = _queued('<relay from="coordinator"><note>Keep going.</note></relay>')
+    transcript = [_user("Build the hook."), READ_STEP, QUESTION_STEP, relay]
+    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+
+
+def test_should_require_a_new_interview_for_a_follow_up_request(tmp_path: Path) -> None:
+    earlier_spawn = _tool_use("Agent", {"prompt": "Build the hook."})
+    transcript = [*INTERVIEWED_TRANSCRIPT, earlier_spawn, _user("Now add a second hook."), READ_STEP]
+    assert _deny_reason(_spawn(tmp_path, transcript)) == MISSING_INTERVIEW_REASON
+
+
+def test_should_treat_two_messages_in_a_row_after_a_question_as_one_reply(
+    tmp_path: Path,
+) -> None:
+    transcript = [*INTERVIEWED_TRANSCRIPT, _user("Also keep it short.")]
+    assert _spawn(tmp_path, transcript) == ""
+
+
+def test_should_pass_the_interview_on_a_scope_settled_line_and_log_it(tmp_path: Path) -> None:
+    transcript = [_user("Fix the typo in README.md line 3."), READ_STEP]
+    brief = f"Fix the typo.\n{SETTLED_LINE}"
+    assert _spawn(tmp_path, transcript, THREAD_SPAWN_TOOL_NAME, brief) == ""
+    [log_record] = _decision_log(tmp_path)
+    assert log_record["outcome"] == "scope_settled"
+    assert log_record["tool_name"] == THREAD_SPAWN_TOOL_NAME
+    assert log_record["scope_settled_line"] == SETTLED_LINE
+
+
+def test_should_still_require_the_read_with_a_scope_settled_line(tmp_path: Path) -> None:
+    brief = f"Fix the typo.\n{SETTLED_LINE}"
+    reason = _deny_reason(_spawn(tmp_path, [_user("Fix the typo.")], brief=brief))
+    assert reason == MISSING_INVESTIGATION_REASON
+
+
+def test_should_deny_a_scope_settled_line_with_no_reason(tmp_path: Path) -> None:
+    transcript = [_user("Fix the typo."), READ_STEP]
+    reason = _deny_reason(_spawn(tmp_path, transcript, brief="Fix it.\nScope settled:"))
+    assert reason == MISSING_INTERVIEW_REASON
+
+
+def test_should_let_a_read_only_subagent_run_without_checks(tmp_path: Path) -> None:
+    stdout = _run_hook(
+        tmp_path,
+        {
+            "tool_name": "Agent",
+            "tool_input": {"subagent_type": "Explore", "prompt": "Find the hooks."},
+            "transcript_path": str(_write_transcript(tmp_path, [_user("Build the hook.")])),
+        },
+    )
+    assert stdout == ""
+
+
+def test_should_count_a_read_only_subagent_as_the_investigation(tmp_path: Path) -> None:
+    explore = _tool_use("Agent", {"subagent_type": "Explore", "prompt": "Find it."})
+    transcript = [_user("Build the hook."), explore, QUESTION_STEP, REPLY_STEP]
+    assert _spawn(tmp_path, transcript) == ""
+
+
+def test_should_let_a_spawn_from_inside_a_subagent_run(tmp_path: Path) -> None:
+    stdout = _run_hook(
+        tmp_path,
+        {
+            "tool_name": "Agent",
+            "agent_id": "agent_1",
+            "tool_input": _spawn_input("Agent"),
+            "transcript_path": str(_write_transcript(tmp_path, [_user("Build the hook.")])),
+        },
+    )
+    assert stdout == ""
+
+
+def test_should_let_the_spawn_run_and_log_when_the_transcript_is_unreadable(
+    tmp_path: Path,
+) -> None:
+    stdout = _run_hook(
+        tmp_path,
+        {
+            "tool_name": "Agent",
+            "tool_input": _spawn_input("Agent"),
+            "transcript_path": str(tmp_path / "absent.jsonl"),
+        },
+    )
+    assert stdout == ""
+    [log_record] = _decision_log(tmp_path)
+    assert log_record["outcome"] == "transcript_unreadable"
+
+
+def test_should_return_the_scope_settled_line_from_the_brief() -> None:
+    tool_input = {"instructions": f"Do X.\n  {SETTLED_LINE}"}
+    assert (
+        spawn_readiness_hook.scope_settled_line(THREAD_SPAWN_TOOL_NAME, tool_input) == SETTLED_LINE
+    )
+
+
+def test_should_ignore_a_tool_it_does_not_check() -> None:
+    assert spawn_readiness_hook.decide_hook_output({"tool_name": "Read", "tool_input": {}}) is None

package/hooks/routing/test_spawn_readiness_steps.py

@@ -0,0 +1,87 @@
+import json
+
+from spawn_readiness_steps import SessionStep, readiness_gaps, session_steps
+
+
+def _user(text: str) -> dict[str, object]:
+    return {"type": "user", "message": {"role": "user", "content": text}}
+
+
+def _tool_use(name: str, tool_input: dict[str, object], block_id: str = "toolu_x") -> dict[str, object]:
+    return {
+        "type": "assistant",
+        "message": {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "id": block_id, "name": name, "input": tool_input}],
+        },
+    }
+
+
+def _tool_result(tool_use_id: str) -> dict[str, object]:
+    return {
+        "type": "user",
+        "message": {
+            "role": "user",
+            "content": [{"type": "tool_result", "tool_use_id": tool_use_id, "content": "ok"}],
+        },
+    }
+
+
+READ_STEP = _tool_use("Bash", {"command": "cat README.md"})
+
+
+def test_should_skip_meta_entries_and_tool_results_as_user_messages() -> None:
+    all_lines = [
+        json.dumps(_user("Build the hook.")),
+        json.dumps({**_user("Base directory for this skill"), "isMeta": True}),
+        json.dumps(READ_STEP),
+        json.dumps(_tool_result("toolu_x")),
+    ]
+    assert session_steps(all_lines) == [
+        SessionStep.USER_MESSAGE,
+        SessionStep.READ,
+    ]
+
+
+def test_should_leave_the_spawn_under_check_out_of_the_steps() -> None:
+    explore = _tool_use(
+        "Agent", {"subagent_type": "Explore", "prompt": "Find it."}, block_id="toolu_spawn"
+    )
+    all_lines = [json.dumps(_user("Build the hook.")), json.dumps(explore)]
+    assert session_steps(all_lines, "toolu_spawn") == [
+        SessionStep.USER_MESSAGE
+    ]
+
+
+def test_should_report_no_gaps_for_a_reply_after_a_question() -> None:
+    all_steps = [
+        SessionStep.USER_MESSAGE,
+        SessionStep.READ,
+        SessionStep.QUESTION,
+        SessionStep.USER_MESSAGE,
+    ]
+    assert readiness_gaps(all_steps) == []
+
+
+def test_should_read_a_github_get_call_as_a_read_and_a_chat_question_as_another_call() -> None:
+    all_lines = [
+        json.dumps(_tool_use("mcp__github__get_file_contents", {"path": "a"})),
+        json.dumps(_tool_use("mcp__hearthbot__reply", {"text": "Which one?"})),
+        json.dumps(_tool_use("mcp__hearthbot__ask_decision", {"question": "Which one?"})),
+    ]
+    assert session_steps(all_lines) == [SessionStep.READ, SessionStep.OTHER_TOOL_CALL, SessionStep.QUESTION]
+
+
+def test_should_start_the_span_at_the_request_before_an_answered_question() -> None:
+    all_steps = [
+        SessionStep.USER_MESSAGE,
+        SessionStep.READ,
+        SessionStep.OTHER_TOOL_CALL,
+        SessionStep.USER_MESSAGE,
+        SessionStep.QUESTION,
+        SessionStep.USER_MESSAGE,
+    ]
+    assert readiness_gaps(all_steps) == [
+        "Investigate the request before this spawn. Read the files, threads, or sources it names, "
+        "so the brief and the agent count fit the task. Run the reads in a message before the spawn."
+    ]

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.36.3",
+    "version": "8.37.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/bdd.md

@@ -9,27 +9,6 @@ paths:
 
 # BDD (discovery-driven development)
 
-**Canonical detail:** `~/.claude/system-prompts/software-engineer.xml` → `<behavior_protocol>`.
+For every non-trivial feature, discover what you do not know, illustrate it with concrete examples in chat, formulate each behavior as a narrow "should ..." specification, then build each one through the TDD loop (CODE_RULES §8). Name developer-facing specs and tests as should sentences.
 
-**Optional long-form references (load when needed):**
-
-- `@~/.claude/docs/BDD_SCENARIO_QUALITY.md` — seven scenario quality patterns (§7.6-style)
-- `@~/.claude/docs/BDD_DISCOVERY_PROTOCOL.md` — Example Mapping algorithm for chat
-- `@~/.claude/docs/BDD_TEST_LAYOUT.md` — describe/when/should layout and soap-opera personas
-
-## What you do for every non-trivial feature
-
-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 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).
-
-## Solo developer
-
-You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). See the optional long-form references above for the full algorithm and anti-pattern list.
-
-## Naming
-
-Developer-facing specs and tests use **should** sentences so intent stays visible (Dan North, "Introducing BDD", 2006).
+**Full text:** [`docs/rule-guides/bdd.md`](../docs/rule-guides/bdd.md), with the long-form BDD references.

package/rules/code-standards.md

@@ -10,37 +10,8 @@ paths:
 
 # Code Standards
 
-> **Canonical review contract:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — the human and AI review contract for code quality, loaded on demand.
-> **Checked-in pointer:** [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md) — the file Cursor BugBot reads; it points at `CODE_RULES.md`.
-> **Production enforcement.** The staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file. No write-time hook runs it. CI runs that lint against the merge base. Each mechanical rule carries a synchronization test.
+[`CODE_RULES.md`](../docs/CODE_RULES.md) is the review contract for code quality. Load it when you review a pull request, resolve a policy conflict, or generate code. Red, green, refactor is the default loop (CODE_RULES §8). Keep engineering right-sized (CODE_RULES §7).
 
-## Policy surface map
+**Enforcement:** the staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file, and CI runs it against the merge base.
 
-| Layer | Path | Role |
-|---|---|---|
-| Contract | `docs/CODE_RULES.md` | Full review criteria for PR agents, loaded on demand |
-| Pointer | `.cursor/BUGBOT.md` | Checked-in file Cursor BugBot reads; points at `CODE_RULES.md` |
-| Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained checks the staged policy lint runs; not generated from the docs |
-| Lint | `scripts/cde_lint.py` | Runs the enforcer and the other policy rules over staged or changed files, grading each against the file's prior text; see [`ci-owns-the-gate.md`](ci-owns-the-gate.md) for what each selection flag reports |
-| Session rules | `rules/*.md` | Runtime session policy (questions, tasks, shell) |
-
-Load `CODE_RULES.md` when reviewing a PR, resolving a policy conflict, or generating code. Prefer linking this ref over restating rules.
-
-Two standards live in `CODE_RULES.md` in full:
-
-- **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.
-
-## Session policies (ref docs, not restated here)
-
-| Concern | Rule file |
-|---|---|
-| Handling a correction from the user | [`correction-lens.md`](correction-lens.md) |
-| Task tracking / worker completion | [`workers-done-before-complete.md`](workers-done-before-complete.md) |
-| Multi-step task list | skill `task-build` (see agents catalog) |
-
-## Validation
-
-Mechanical enforcer coverage is checked by the existing `hooks/blocking/test_code_rules_enforcer*.py` suite.
+**Full text:** [`docs/rule-guides/code-standards.md`](../docs/rule-guides/code-standards.md), with the policy surface map.

package/rules/correction-lens.md

@@ -96,37 +96,9 @@ exemption from the archiving procedure's side.
 
 An edit that sharpens this rule is welcome. The file stays.
 
-## Excerpt for repository-instruction sessions
+## Codex copy
 
-Codex reads its repository `AGENTS.md`; this excerpt supplies the standalone
-contract.
-
-```
-Correction handling for this run, from rules/correction-lens.md.
-
-Every correction the user gives becomes a control. Run it through five layers
-and land it at the highest one that can hold it:
-
-1. Codebase. The mistake is impossible by how the code is written: a type, a
-   signature, a data structure, an API shape.
-2. Static analysis. A program reads the tree and decides: a lint rule, an
-   enforcer check, a paired test, a CI gate.
-3. Review tooling. A reviewer or a review bot reads the criterion: a code-rules
-   row, a BUGBOT pointer, a Graphite rule.
-4. Skill. An agent follows a procedure.
-5. Style guide. Word choice and prose shape.
-
-Close the correction with three sentences: the layer chosen, why each higher
-layer cannot hold the lesson, and the change opened at that layer in this run.
-Effort rules out no layer; a missing capability does, and you name which one.
-
-The same correction arriving twice means the layer was too low. Move it up one
-layer and say so.
-
-Land the control in the repository whose code, CI, or pipeline it guards. The
-shared environment package takes only repo-agnostic controls that any
-repository could use. A memory file records the decision and encodes nothing.
-```
+Codex reads its repository `AGENTS.md`. The standalone excerpt it receives lives in [`docs/rule-guides/correction-lens-excerpt.md`](../docs/rule-guides/correction-lens-excerpt.md).
 
 ## Sibling rules
 

package/rules/doc-inventory-integrity.md

@@ -11,38 +11,12 @@ paths:
 
 # Documentation Inventory Integrity
 
-A doc that inventories code is a contract: a reader trusts the listing to map the directory, trusts a shown command to run, and trusts a table row to name the file that reads the variable. Three repository checks hold the three inventory shapes in step with the code. No write-time hook runs them. Run `python packages/claude-dev-env/scripts/repository_policy.py` before you commit, and CI runs the same command.
+A doc that inventories code stays in step with the code, in the same change:
 
-## 1. A per-directory `CLAUDE.md` names files that exist
+1. Every bare filename a per-directory `CLAUDE.md` names in a table cell or a fenced run command exists in its subtree.
+2. A package `README.md` Layout table, `CLAUDE.md` "Key files" list, or skill `SKILL.md` Layout table names each new production file and says what it does. Broaden the purpose sentence and the file's description when its responsibility grows.
+3. An env-var table row names a code file that reads the variable.
 
-Every bare filename a per-directory `CLAUDE.md` names points at a file in the subtree that `CLAUDE.md` describes — both the filenames its table cells list and the scripts its fenced run commands invoke (`python script.py`). Add the row and the run command in the change that adds the file; drop both in the change that removes it.
+**Enforcement:** `repository_checks/claude_md.py`, `repository_checks/package_inventory.py`, and `repository_checks/env_var_documentation.py`. Run `python packages/claude-dev-env/scripts/repository_policy.py` before you commit. CI runs the same command.
 
-`repository_checks/claude_md.py` scans every tracked `CLAUDE.md` in the committed tree and reports each orphan it holds, loading its detection logic from `claude_md_orphan_file_blocker.py`. It reads committed files rather than a pending write, so it reports a pre-existing orphan alongside a new one.
-
-It collects two kinds of reference:
-
-- **Table cells** — the first column of each markdown table row **outside** a fenced code block, keeping cells that name a bare filename in backticks, with no path separator, not a slash-command, ending in a known extension (`.py`, `.md`, `.json`, `.mjs`, `.js`, `.ts`, `.ps1`, `.cmd`, `.ahk`, `.yml`, `.yaml`, `.sh`, `.txt`, `.cfg`, `.toml`, `.ini`).
-- **Run commands** — each line **inside** a fenced code block that invokes an interpreter (`python`, `python.exe`, `python3`, `node`, `pwsh`, `powershell`, `bash`, `sh`, `ruby`, `perl`) on a script, taking that script's basename when it ends in `.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`, `.rb`, or `.pl`.
-
-A fenced *table row* is an example and contributes nothing; a fenced *run command* is a contract the reader runs and is checked. The write is blocked when a collected filename exists nowhere under the scan root — the `CLAUDE.md` directory's parent, covering the directory, its subdirectories, and its siblings. A filesystem error that halts the subtree walk fails open.
-
-The check stays quiet for a target that is not a `CLAUDE.md`, for a cell holding a path, a subdirectory ending in `/`, or a slash-command, for a table row inside a fence, for an inline `python x.py` mention outside a fence, and for a table naming an explicit relative-path source (a `../` token), which documents files outside the subtree by design.
-
-## 2. A package inventory names each new production file
-
-A package directory that documents its own files in a `README.md` Layout table, a `CLAUDE.md` "Key files" list, or a skill `SKILL.md` Layout table keeps that inventory in step with the directory. A new production file in such a directory gets its entry — a table row or a list bullet naming the file in backticks and saying what it does — in the same change.
-
-`repository_checks/package_inventory.py` scans the committed tree and reports a production file whose basename appears in no present inventory, loading its detection logic from `package_inventory_stale_blocker.py`. It names the fix. A skill `SKILL.md` Layout table that maps `scripts/` counts as the inventory for files in that subdirectory.
-
-Two free-prose slices stay with judgment and belong in the same change:
-
-1. **Purpose / scope sentence.** When the new module adds a responsibility the package `## Purpose` (or the parent inventory's one-line summary of the subdirectory) omits, broaden that sentence to name it. A hook cannot derive a module's responsibility from its filename.
-2. **Per-file description clause.** When a file gains a responsibility the inventory's em-dash description omits — a new public function, a new module-level constant — broaden the clause to name it. The gate checks only that the basename appears once and never reads the description. Constants modules (`*_constants.py`, or any `.py` directly inside `config/`) are the common shape: the clause that lands in the module docstring lands in the inventory description in the same change. The gate fires on Write of a new file and skips files directly inside `config/`, so an Edit adding a constant to an existing config module matches neither path.
-
-This is the `category-o-docstring-vs-impl-drift` (O8) orphaned-doc-claim shape applied to a package inventory.
-
-## 3. An env-var table row names a file that reads the variable
-
-Every row in an env-var summary table pairs an UPPER_SNAKE variable with a code-file path that reads it — written as `` | `GOOGLE_APPLICATION_CREDENTIALS` | `auth/google_auth.py` | … | ``. When a code change removes the last read of a variable from a file, the same change drops or corrects the row naming that file.
-
-`repository_checks/env_var_documentation.py` scans tracked `.md` files and reports a row whose named code file exists yet never references the variable, loading its detection logic from `env_var_table_code_drift_blocker.py`. It names the fix. A row whose code file resolves nowhere stays quiet, since the check cannot prove the drift.
+**Full text:** [`docs/rule-guides/doc-inventory-integrity.md`](../docs/rule-guides/doc-inventory-integrity.md).

package/rules/docstring-prose-matches-implementation.md

@@ -6,48 +6,10 @@ paths:
 
 # Docstring Prose Matches Implementation
 
-**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
+**When this applies:** Writing or editing a docstring, or a skill's companion `SKILL.md`, whose prose lists the inputs, matches, skips, or step order a body applies.
 
-## Rule
+The list covers every behavior the body applies, and the body accepts only what the list names. When the body changes the set, update the prose in the same edit. A hook's docstring and `CORRECTIVE_MESSAGE` claim exactly the shapes its detector flags.
 
-When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
+**Enforcement:** `code_rules_docstrings.py` and the JS slices in `code_rules_imports_logging.py`, which the staged policy lint runs through `code_rules_enforcer.py`, plus its `hook-prose-consistency` rule. CI runs it against the merge base.
 
-When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
-
-## Write-time checks
-
-Read the body and the docstring side by side. Apply each check that matches the prose:
-
-- **Unions / match sources** — every member of a "what counts" union appears in the prose.
-- **Suppressors / skip lists** — every early-return suppressor appears in the prose.
-- **Step order** — named order matches call order; branch-guarded corrective steps are named too.
-- **Shared fallbacks** — every condition that reaches a fallback call is named.
-- **Predicate breadth** — the body accepts only the inputs the prose names.
-- **Exclusion axis** — an exclusion clause keys on the same axis the body classifies on.
-- **Companion docs** — a `SKILL.md` (or sibling) order/content claim matches the producer body.
-- **Gate-outcome status flags** — an outcome routed to a blocker (`blocker = ...; break`) reads as blocked everywhere, never as a bypass.
-- **Returns / Raises / Note claims** — each free-form claim matches the body.
-
-Many deterministic shapes of this drift are checked in `code_rules_docstrings.py` (and the JS and `.mjs` slices in `code_rules_imports_logging.py`). The staged policy lint reaches both through `code_rules_enforcer.py`, and CI runs it against the merge base. Free-form rest is judgment.
-
-## Hook prose matches its detector
-
-A hook module is the sharpest case of the same rule: its docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags, and claim no broader trigger surface than the regex enforces.
-
-The staged policy lint carries this as its `hook-prose-consistency` rule, covering hook modules and their `*_constants.py` companions. It reports prose that claims a trigger the detector never fires on, and names the fix. No write-time hook runs it, so CI is where it reports.
-
-After writing a hook, ask: would a token matching every word of this message trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches. The path-shape case is the common overstatement — a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.
-
-## Full standard
-
-The full Category O judgment standard — sub-buckets O1–O9, the complete write-time gate inventory, free-form checklists, and worked examples — lives in:
-
-`~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
-
-## Division of labor
-
-| Surface | Role |
-|---|---|
-| **This rule** | Always-on write-time policy and the compact checklist above. |
-| Category O rubric | Single thick source for the full standard (on demand). |
-| Category O prompt | Audit template; points at the rubric for judgment. |
+**Full text:** [`docs/rule-guides/docstring-prose-matches-implementation.md`](../docs/rule-guides/docstring-prose-matches-implementation.md), with the write-time checklist. The Category O audit rubric carries the full standard.