claude-dev-env 8.36.4 → 8.37.1

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.4",
+    "version": "8.37.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/asd-ste100-language.md

@@ -1,40 +1,9 @@
-# ASD-STE100 Language Policy
+# ASD-STE100 language policy
 
-Use this rule as the sole general language authority for user-facing text in this repository.
-It defines ordinary word choice, sentence style, tone, punctuation, and prose form.
+**When:** Writing chat, tool narration, or repository prose.
 
-This text is an **ASD-STE100 Issue 9 conversational adaptation**. It applies the standard's
-clear-writing principles to assistant messages. The official standard remains the authority for
-definitions and dictionary decisions.
+Use the sole general language rule. Write short, complete sentences on one topic. Use active voice; lead with conditions; give one action per step. Use plain, precise words and stable terms. Expand abbreviations and contractions first; name unclear pronouns. Be inclusive; punctuate clearly. Preserve exact labels, identifiers, formulas, titles, and interface text. Send a result, blocker, or question. Mark injury or death `WARNING`, equipment damage `CAUTION`; state condition then result. Aim for 20 words per step, 25 per description. Treat checks as aids; have a human verify accuracy, terms, safety, confidentiality, and meaning.
 
-## Official sources
+**Enforcement:** none, the agent applies it.
 
-- [ASD-STE100 Simplified Technical English, Issue 9 (2025-01-15)](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf)
-- [ASD-STE100 FAQ](https://www.asd-ste100.org/STE_faq.html)
-- [ASD-STE100 About page](https://www.asd-ste100.org/about_STE.html)
-- [ASD-STE100 tools guidance](https://www.asd-ste100.org/STEsoftware.html)
-- [STEMG white paper on ASD-STE100 and artificial intelligence](https://www.asd-ste100.org/assets/files/WhitePaper-ASD-STE100_and_AI.pdf)
-
-## Writing policy
-
-- Write short, complete sentences. Keep one topic in each explanatory sentence.
-- Use active voice. Put the condition first when an instruction has a prerequisite.
-- Write imperative procedure steps. Give one action in each sentence.
-- Prefer familiar, precise words. Use one stable term for one item or action.
-- Write full words and explicit references. Expand abbreviations and contractions when they first appear.
-- Replace ambiguous pronouns with the noun they name.
-- Use inclusive, neutral language.
-- Use periods, commas, colons, and bullets to show structure.
-- Preserve exact quoted labels, identifiers, formulas, titles, and interface text.
-- Send the reader only a result, a blocker, or a question. Leave out a line that says nothing is needed from them, and leave out which agent, session, or coordinator did the work.
-- Use `WARNING` for a risk of injury or death. Use `CAUTION` for a risk of equipment, tool, or machine damage. State the command or condition first, then state the result.
-- Aim for 20 words or fewer in a procedure sentence when the technical content allows.
-- Aim for 25 words or fewer in a descriptive sentence when the technical content allows.
-
-Use this policy for chat, tool narration, questions, plans, documentation, code-adjacent prose,
-and durable repository text. Named contracts can add behavior-specific structure, evidence,
-question routing, current-state documentation, completion, docstring, or publication rules.
-Those contracts use this policy for their language.
-
-Treat automated output and language checks as drafting aids. A responsible human verifies
-technical accuracy, terminology, safety, confidentiality, and intended meaning.
+**Full text:** [`docs/rule-guides/asd-ste100-language.md`](../docs/rule-guides/asd-ste100-language.md). Read it for sources.

package/rules/cleanup-temp-files.md

@@ -1,33 +1,9 @@
-# Clean Up Temporary Files
+# Clean up temporary files
 
-**When this applies:** After tasks that created scratch files, debug dumps, or one-off scripts the user did not ask to keep.
+**When:** Creating scratch files, debug dumps, or one-off helpers during a task.
 
-Source: [Anthropic — Reduce file creation in agentic coding](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#reduce-file-creation-in-agentic-coding)
+Prefer memory to scratch files and track any temporary files you create. At completion, remove those files and leave user-requested files in place. Files under the OS temporary root or `$CLAUDE_JOB_DIR` need no explicit removal; a parent handles child-agent scratch. Use the permitted removal form.
 
-## During a task
+**Enforcement:** none, the agent applies it.
 
-- Prefer working in memory over creating scratchpad files. Use variables and tool results instead of writing intermediate data to disk.
-- When a temporary file is needed (e.g., a helper script, a test fixture, a debug output), track it mentally for cleanup.
-
-## When a task is complete
-
-- Remove every temporary file, script, or helper file you created during the task.
-- Leave the working directory cleaner than you found it.
-- If a file was created at the user's explicit request (not as a byproduct of your process), leave it in place.
-
-## Exceptions to the removal duty
-
-Three kinds of file are already ephemeral and need no explicit removal:
-
-- A file under the OS temporary root.
-- A file under `$CLAUDE_JOB_DIR`, which the harness clears with the job.
-- A child agent's scratch file, which the parent removes at teardown.
-
-Use an allowed removal form for everything else: [`destructive-commands.md`](destructive-commands.md) names them.
-
-## What counts as temporary
-
-- Scripts written to test a hypothesis or run a one-off check
-- Debug output files, log dumps, or intermediate data exports
-- Helper files created to work around tool limitations
-- Any file the user did not ask for and would not expect to find after the task
+**Full text:** [`docs/rule-guides/cleanup-temp-files.md`](../docs/rule-guides/cleanup-temp-files.md). Read it to classify a file or choose cleanup.

package/rules/correction-lens.md

@@ -1,110 +1,21 @@
-# Correction Lens
+# Correction lens
 
-**Standing rule. This file is never archived and never removed.** The permanence
-clause at the end of this document states what that binds.
+**When:** A user corrects you.
 
-**When this applies:** Every correction the user gives. A "no, do it this way", a
-"stop writing that word", a repeated review comment, a fix the user makes by hand
-after an agent hands work back. Each one is evidence that a control is missing,
-and the correction is handled by building that control.
+Open a control in the guarded repository, in the same run, at the highest capable layer. State the layer, why higher layers fail, and the change opened. Pair layers when both help. Move repeated corrections up a layer. Memory records the decision.
 
-## Rule
-
-A correction runs through five layers, in this order, and the lesson lands at the
-highest layer that can hold it. The change opens in the same run as the
-correction.
-
-| Priority | Layer | What holds the lesson | The lesson lands as |
-|---|---|---|---|
-| 1 | Codebase | The mistake is impossible by how the code is written | A type, a signature, a data structure, an API shape, a deleted branch |
-| 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.md` row, a `.cursor/BUGBOT.md` pointer, a Graphite or BugBot rule |
-| 4 | Skill | An agent follows a procedure | A skill under the agents home |
-| 5 | Style guide | Word choice and prose shape | A row in a `rules/*.md` file or a style document |
-
-Layer 1 is the goal every time. A lesson encoded there needs no reader, no run,
-and no agent to remember it. The wrong call has nowhere to live.
-
-## Choosing the layer
-
-Three sentences close every correction:
-
-1. The layer chosen.
-2. Why each higher layer cannot hold this lesson.
-3. The change opened at the chosen layer, by pull request.
-
-A layer holds a lesson when its own test passes:
-
-- **Layer 1 holds it** when a type, a signature, or a data structure can make the
-  wrong call fail to compile, fail to construct, or fail to exist.
-- **Layer 2 holds it** when a program reading the tree can separate right from
-  wrong with no judgment call.
-- **Layer 3 holds it** when a reader needs the criterion in front of them and a
-  program cannot decide it.
-- **Layer 4 holds it** when the lesson is a procedure with steps an agent runs.
-- **Layer 5 holds it** when the lesson is word choice or the shape of prose.
-
-Effort rules out no layer. A layer is ruled out when it lacks the capability to
-hold the lesson, and the sentence that rules it out says which capability is
-missing. "A lint for this would take a day" leaves layer 2 in play.
-
-Two layers often hold one correction. Take both: the shape at layer 1 and the
-check at layer 2 cost one run together and each covers what the other misses.
-
-## A repeated correction moves up a layer
-
-The same correction arriving a second time is the measurement. The layer chosen
-the first time was too low. Move the lesson one layer up and say so in the same
-run.
-
-A review comment that repeats across pull requests reads the same way. Each
-repetition names the layer below the reviewer as the one that needs the control.
-Count the repetitions.
-
-## Where the control lands
-
-A control lands in the repository whose code, CI, or pipeline it guards. A
-control for one repository's workflows, review bots, pipelines, or agents lands
-in that repository. This package takes only repo-agnostic controls, the
-environment and development pieces any repository could use, so every session
-that loads this environment carries them. A control written into one project's
-instructions reaches that project alone, and a control written into a chat reply
-reaches that conversation alone.
-
-Memory holds the decision. The control holds the behavior. A correction that
-produced a memory file and nothing else has been recorded and never encoded, so
-the rule still binds. Open the control.
-
-## Trust grows as the controls catch the common mistakes
-
-Add agents after the controls catch what agents get wrong, and start from a
-workflow small enough to watch. Each repeated correction becomes a stronger
-control, and the number of agents rises behind it.
-[`docs/high-trust-agent-delivery.md`](../docs/high-trust-agent-delivery.md)
-carries the model this comes from, including the layered-controls picture and
-the inner and outer delivery loops.
+| Priority | Layer | Control |
+|---|---|---|
+| 1 | Codebase | Prevent the mistake. |
+| 2 | Static analysis | Programmatic check. |
+| 3 | Review tooling | Reviewer criterion. |
+| 4 | Skill | Agent procedure. |
+| 5 | Style guide | Wording rule. |
 
 ## Permanence
 
-This file stays in `rules/`. A prune pass, an archive sweep, a consolidation, or
-a rewrite that would move it into `rules-archived/` stops at this line. The
-"Never archived" section of
-[`packages/claude-dev-env/rules-archived/ARCHIVE-MANIFEST.md`](../rules-archived/ARCHIVE-MANIFEST.md)
-names it, and
-[`archiving-agent-config.md`](archiving-agent-config.md) names the same
-exemption from the archiving procedure's side.
-
-An edit that sharpens this rule is welcome. The file stays.
-
-## Codex copy
-
-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).
+Keep this file in `rules/`. A prune, archive, consolidation, or rewrite that would move it stops here. Edits that sharpen it are welcome.
 
-## Sibling rules
+**Enforcement:** none, the agent applies it.
 
-| Rule | Role |
-|---|---|
-| [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md) | A gate blocks on a breaking finding and records a smell |
-| [`code-standards.md`](code-standards.md) | The layer map of contract, pointer, enforcer, lint, session rules |
-| [`archiving-agent-config.md`](archiving-agent-config.md) | How a rule leaves service, and which files are exempt |
-| [`falsify-before-green.md`](falsify-before-green.md) | A new layer-2 check counts once it has run red on a named break |
+**Full text:** [`docs/rule-guides/correction-lens.md`](../docs/rule-guides/correction-lens.md). Read it when choosing a layer or locating a control.

package/rules/destructive-commands.md

@@ -1,47 +1,11 @@
-# Destructive Commands in Bash
+# Destructive commands in Bash
 
-No hook watches Bash commands for destructive patterns. What you face is the harness permission prompt. The harness raises it from the session permission mode and the permission rules in effect on your host. In a background or auto-mode run no human can answer that prompt, so the call stalls.
+**When:** Removing files or writing a destructive command string.
 
-Two consequences follow. Use an allowed removal form, and keep a destructive literal out of the command string even when it rides only as data.
-
-## Removal forms to prefer
-
-- **Scratch and probe files.** Use the PowerShell tool with `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`.
-- **Worktrees.** Use `git worktree remove --force <path>`.
-- **Tracked files.** Use `git rm <path>`, which records the deletion in the index.
-- **Bash `rm` when unavoidable.** Write one standalone `rm` with absolute literal paths, no chaining, and no globs. Keep every target inside the ephemeral namespace below.
-
-## The ephemeral namespace
-
-Keep a Bash `rm` to targets that resolve inside one of these:
-
-- The OS temporary root.
-- A path rooted at `/tmp` or `/temp`, drive-letter tolerant.
-- A path holding a `/worktrees/` or `/worktree/` segment, or a directory git reports inside a worktree admin directory.
-- `~/.claude`.
-
-Never pass a bare ephemeral root, such as `/tmp`, the OS temp root itself, or a bare directory named `worktrees` or `worktree`. A single stray argument then wipes the whole namespace.
-
-Write each target as a literal path. A variable, a `$(...)` or backtick expansion, or a brace glob hides what the command will delete from the reader and from the permission matcher.
-
-A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by the harness and needs no explicit removal. See the exception clause in [`cleanup-temp-files.md`](cleanup-temp-files.md).
-
-## Keep destructive literals out of the command string
-
-The permission matcher reads the raw command string. A destructive literal carried only as data still sits in that string, so it can push the command out of an allowed shape and into a prompt even though the shell never executes it. This covers a commit message, a PR or issue body, an echoed string, a `python -c` or `node -e` or `awk` argument, and a heredoc.
-
-- Bodies that describe destructive-command behavior go in a file passed by path, such as `git commit -F <file>` or `gh … --body-file <file>`. See [`gh-cli-conventions.md`](gh-cli-conventions.md). Never `git commit -m` or `gh … -b`.
-- To exercise or verify a hook, run the committed test suite with `python -m pytest <test_file>`, which passes the command strings as in-language data. Never an inline `python -c` harness.
-
-## Every subagent prompt carries the rule
-
-A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers, such as review lenses, fix agents, or verifiers, copies this line into every subagent prompt it issues. A grandchild cleaning up its own probe file then uses an allowed form:
+No hook watches Bash commands; a permission prompt can stall unattended work. Keep destructive literals out of command strings, including data. Use literal absolute targets; never target a bare temporary root. Use `git rm` for tracked files. Pass bodies by file and test hooks through the test suite. Copy this line into every subagent prompt:
 
 > Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
 
-Prefer that a child leaves its scratch files for the parent to remove at teardown.
-
-## Sibling rules
+**Enforcement:** none, the agent applies it; the harness may prompt.
 
-- [`cleanup-temp-files.md`](cleanup-temp-files.md) names which scratch files a task removes, and which it leaves.
-- [`windows-filesystem-safe.md`](windows-filesystem-safe.md) holds the safe `rmtree` and `force_rmtree` patterns for read-only Windows files.
+**Full text:** [`docs/rule-guides/destructive-commands.md`](../docs/rule-guides/destructive-commands.md). Read it before any removal.