claude-dev-env 2.15.1 → 2.17.0

package/hooks/hooks_constants/plain_language_blocker_constants.py

@@ -1,366 +0,0 @@
-"""Configuration constants for the plain_language_blocker PreToolUse hook.
-
-::
-
-    ALL_CHAT_DETAIL_MARKERS
-        ok:   "Which gate should run first?"
-        flag: "Which gate should run first?\\n- write\\n- commit"
-    INLINE_CODE_SPAN_PATTERN
-        ok:   "Should we pass `--dry-run` here?" -> one word toward the caps
-    ALL_LINE_ENDING_REPLACEMENTS
-        flag: a blank line spelled "\\r\\n\\r\\n" reads as a paragraph break
-    MAXIMUM_OPTION_DESCRIPTION_WORD_COUNT
-        ok:   "Runs on every write."
-        flag: a 30-word paragraph of tradeoffs
-
-Holds the heavy words and their everyday replacements, the prose-region
-strippers the word scan runs first, and the lean-question-block tunables: the
-block-level chat-detail markers that belong in chat text, the line-ending
-spellings normalized before those markers run, the inline-code span the length
-counts collapse to one word, and the sentence and word caps a question and an
-option description each answer to. The pure analyzer in
-``ask_user_question_shape`` reads the same lean-block tunables so shape grading
-and the runtime hook share one contract.
-"""
-
-from __future__ import annotations
-
-import re
-
-REPLACEMENT_BY_TERM: dict[str, str] = {
-    "addressees are requested": "(omit), please",
-    "under the provisions of": "under",
-    "interpose no objection": "don't object",
-    "afford an opportunity": "allow, let",
-    "has a requirement for": "needs",
-    "is in consonance with": "agrees with, follows",
-    "not later than 10 may": "by 10 May, before 11 May",
-    "provides guidance for": "guides",
-    "successfully complete": "complete, pass",
-    "with the exception of": "except for",
-    "due to the fact that": "due to, since",
-    "effect modifications": "make changes",
-    "in view of the above": "so",
-    "adversely impact on": "hurt, set back",
-    "at the present time": "at present, now",
-    "not later than 1600": "by 1600",
-    "combat environment": "combat",
-    "in a timely manner": "on time, promptly",
-    "in accordance with": "by, following, per, under",
-    "in the near future": "shortly, soon",
-    "is responsible for": "(omit) handles",
-    "on a regular basis": "(omit)",
-    "until such time as": "until",
-    "during the period": "during",
-    "in the process of": "(omit)",
-    "with reference to": "about",
-    "as prescribed by": "in, under",
-    "in the amount of": "for",
-    "is applicable to": "applies to",
-    "is authorized to": "may",
-    "state-of-the-art": "latest",
-    "close proximity": "near",
-    "for a period of": "for",
-    "in an effort to": "to",
-    "in the event of": "if",
-    "it is essential": "must, need to",
-    "it is requested": "please, we request, I request",
-    "notwithstanding": "inspite of, still",
-    "the undersigned": "I",
-    "arrive onboard": "arrive",
-    "in relation to": "about, with, to",
-    "incumbent upon": "must",
-    "limited number": "limits",
-    "take action to": "(omit)",
-    "as a means of": "to",
-    "in order that": "for, so",
-    "pertaining to": "about, of, on",
-    "provided that": "if",
-    "this activity": "us, we",
-    "advantageous": "helpful",
-    "consequently": "so",
-    "in regard to": "about, concerning, on",
-    "remuneration": "pay, payment",
-    "set forth in": "in",
-    "subsequently": "after, later, then",
-    "the month of": "(omit)",
-    "a number of": "some",
-    "accordingly": "so",
-    "adjacent to": "next to",
-    "appreciable": "many",
-    "appropriate": "(omit), proper, right",
-    "approximate": "about",
-    "by means of": "by, with",
-    "comply with": "follow",
-    "consolidate": "combine, join, merge",
-    "constitutes": "is, forms, makes up",
-    "demonstrate": "prove, show",
-    "discontinue": "drop, stop",
-    "disseminate": "give, issue, pass, send",
-    "expeditious": "fast, quick",
-    "immediately": "at once",
-    "in addition": "also, besides, too",
-    "in order to": "to",
-    "inasmuch as": "since",
-    "methodology": "method",
-    "necessitate": "cause, need",
-    "participate": "take part",
-    "practicable": "practical",
-    "proficiency": "skill",
-    "pursuant to": "by, following, per, under",
-    "relative to": "about, on",
-    "requirement": "need",
-    "substantial": "large, much",
-    "time period": "(either one)",
-    "utilization": "use",
-    "your office": "you",
-    "a and/or b": "a or b or both",
-    "accomplish": "carry out, do",
-    "additional": "added, more, other",
-    "addressees": "you",
-    "anticipate": "expect",
-    "assistance": "aid, help",
-    "be advised": "(omit)",
-    "capability": "ability",
-    "concerning": "about, on",
-    "equipments": "equipment",
-    "expiration": "end",
-    "facilitate": "ease, help",
-    "frequently": "often",
-    "heretofore": "until now",
-    "in lieu of": "instead",
-    "in view of": "since",
-    "indication": "sign",
-    "inter alia": "(omit)",
-    "it appears": "seems",
-    "parameters": "limits",
-    "previously": "before",
-    "prioritize": "rank",
-    "promulgate": "issue, publish",
-    "represents": "is",
-    "similar to": "like",
-    "subsequent": "later, next",
-    "sufficient": "enough",
-    "the use of": "(omit)",
-    "accompany": "go with",
-    "ascertain": "find out, learn",
-    "component": "part",
-    "currently": "(omit), now",
-    "designate": "appoint, choose, name",
-    "determine": "decide, figure, find",
-    "eliminate": "cut, drop, end",
-    "encounter": "meet",
-    "enumerate": "count",
-    "equitable": "fair",
-    "establish": "set up, prove, show",
-    "evidenced": "showed",
-    "expertise": "ability",
-    "failed to": "didn't",
-    "identical": "same",
-    "implement": "carry out, start",
-    "inception": "start",
-    "interface": "meet, work with",
-    "magnitude": "size",
-    "objective": "aim, goal",
-    "regarding": "about, of, on",
-    "remainder": "rest",
-    "selection": "choice",
-    "terminate": "end, stop",
-    "there are": "(omit)",
-    "therefore": "so",
-    "witnessed": "saw",
-    "accorded": "given",
-    "accurate": "correct, exact, right",
-    "aircraft": "plane",
-    "allocate": "divide",
-    "apparent": "clear, plain",
-    "combined": "joint",
-    "commence": "begin, start",
-    "comprise": "form, include, make up",
-    "contains": "has",
-    "disclose": "show",
-    "endeavor": "try",
-    "expedite": "hasten, speed up",
-    "feasible": "can be done, workable",
-    "finalize": "complete, finish",
-    "function": "act, role, work",
-    "herewith": "below, here",
-    "identify": "find, name, show",
-    "impacted": "affected, changed",
-    "indicate": "show, write down",
-    "initiate": "start",
-    "maintain": "keep, support",
-    "minimize": "decrease, method",
-    "numerous": "many",
-    "obligate": "bind, compel",
-    "preclude": "prevent",
-    "previous": "earlier",
-    "prior to": "before",
-    "purchase": "buy",
-    "relocate": "move",
-    "there is": "(omit)",
-    "transmit": "send",
-    "validate": "confirm",
-    "address": "discuss",
-    "attempt": "try",
-    "benefit": "help",
-    "command": "us, we",
-    "convene": "meet",
-    "evident": "clear",
-    "exhibit": "show",
-    "females": "women",
-    "forfeit": "give up, lose",
-    "forward": "send",
-    "furnish": "give, send",
-    "however": "but",
-    "initial": "first",
-    "liaison": "discussion",
-    "maximum": "greatest, largest, most",
-    "minimum": "least, smallest",
-    "monitor": "check, watch",
-    "observe": "see",
-    "operate": "run, use, work",
-    "optimum": "best, greatest, most",
-    "perform": "do",
-    "portion": "part",
-    "possess": "have, own",
-    "proceed": "do, go ahead, try",
-    "procure": "(omit)",
-    "provide": "give, offer, say",
-    "reflect": "say, show",
-    "request": "ask",
-    "require": "must, need",
-    "solicit": "ask for, request",
-    "subject": "the, this, your",
-    "therein": "there",
-    "thereof": "its, their",
-    "utilize": "use",
-    "warrant": "call for, permit",
-    "whereas": "because, since",
-    "accrue": "add, gain",
-    "advise": "recommend, tell",
-    "assist": "aid, help",
-    "attain": "meet",
-    "caveat": "warning",
-    "delete": "cut, drop",
-    "depart": "leave",
-    "desire": "want, wish",
-    "employ": "use",
-    "ensure": "make sure",
-    "expend": "spend",
-    "herein": "here",
-    "modify": "change",
-    "notify": "let know, tell",
-    "option": "choice, way",
-    "permit": "let",
-    "remain": "stay",
-    "render": "give, make",
-    "reside": "live",
-    "retain": "keep",
-    "submit": "give, send",
-    "timely": "prompt",
-    "viable": "practical, workable",
-    "elect": "choose, pick",
-    "it is": "(omit)",
-    "deem": "believe, consider, think",
-    "said": "the, this, that",
-    "same": "the, this, that",
-    "such": "the, this, that",
-    "type": "(omit)",
-    "vice": "instead of, versus",
-}
-
-ALL_TERM_PATTERNS: list[tuple[re.Pattern[str], str]] = [
-    (re.compile(r"\b" + re.escape(each_term) + r"\b", re.IGNORECASE), each_replacement)
-    for each_term, each_replacement in REPLACEMENT_BY_TERM.items()
-]
-
-ALL_SOFTWARE_TERMS: frozenset[str] = frozenset(
-    {
-        "command",
-        "function",
-        "address",
-        "parameters",
-        "interface",
-        "component",
-        "monitor",
-        "request",
-        "validate",
-        "however",
-        "forward",
-        "subject",
-        "same",
-        "such",
-        "said",
-        "type",
-        "it is",
-        "there is",
-        "there are",
-    }
-)
-
-FENCED_CODE_BLOCK_PATTERN: re.Pattern[str] = re.compile(r"```[\s\S]*?```", re.MULTILINE)
-INLINE_CODE_PATTERN: re.Pattern[str] = re.compile(r"`[^`]+`")
-BLOCKQUOTE_LINE_PATTERN: re.Pattern[str] = re.compile(r"^\s*>.*$", re.MULTILINE)
-URL_PATTERN: re.Pattern[str] = re.compile(r"https?://\S+", re.IGNORECASE)
-FILE_PATH_PATTERN: re.Pattern[str] = re.compile(
-    r"(?<![\w/\\])(?:[A-Za-z]:[\\/]|~?[\\/]|\.{1,2}[\\/])(?:[\w.\-]+[\\/])*[\w.\-]+"
-    r"|(?:[\w.\-]+[\\/])+[\w.\-]+\.[A-Za-z0-9]+"
-)
-
-MARKDOWN_EXTENSION: str = ".md"
-ASK_USER_QUESTION_TOOL_NAME: str = "AskUserQuestion"
-ALL_WRITE_EDIT_TOOL_NAMES: frozenset[str] = frozenset({"Write", "Edit", "MultiEdit"})
-
-DOT_CLAUDE_DIRECTORY_NAME: str = ".claude"
-PROJECT_ALLOWLIST_FILENAME: str = "plain-language-allow.json"
-PROJECT_ROOT_WALK_LIMIT: int = 40
-REPOSITORY_MARKER_NAME: str = ".git"
-
-USER_FACING_PLAIN_LANGUAGE_NOTICE: str = (
-    "Plain-language check: replace each flagged formal word with the simpler "
-    "word named in the reason."
-)
-
-ALL_CHAT_DETAIL_MARKERS: tuple[tuple[re.Pattern[str], str], ...] = (
-    (re.compile(r"^[ \t]*```", re.MULTILINE), "a fenced code block"),
-    (re.compile(r"^[ \t]*#{1,6}[ \t]+\S", re.MULTILINE), "a heading"),
-    (re.compile(r"^[ \t]*\|.*\|[ \t]*$", re.MULTILINE), "a table row"),
-    (
-        re.compile(r"^[ \t]*(?:[-*+][ \t]+|\d{1,2}[.)][ \t]+)\S", re.MULTILINE),
-        "a bullet or numbered list marker",
-    ),
-    (re.compile(r"\n[ \t]*\n"), "more than one paragraph"),
-)
-
-INLINE_CODE_SPAN_PATTERN: re.Pattern[str] = re.compile(r"`[^`\n]+`")
-INLINE_CODE_PLACEHOLDER: str = "code"
-
-ALL_LINE_ENDING_REPLACEMENTS: tuple[tuple[str, str], ...] = (
-    ("\r\n", "\n"),
-    ("\r", "\n"),
-)
-
-SENTENCE_BOUNDARY_PATTERN: re.Pattern[str] = re.compile(r"[.!?]+(?=\s+[A-Z]|\s*$)")
-COUNTABLE_WORD_PATTERN: re.Pattern[str] = re.compile(r"\S*[A-Za-z0-9]\S*")
-
-MAXIMUM_QUESTION_SENTENCE_COUNT: int = 2
-MAXIMUM_QUESTION_WORD_COUNT: int = 40
-MAXIMUM_OPTION_DESCRIPTION_SENTENCE_COUNT: int = 1
-MAXIMUM_OPTION_DESCRIPTION_WORD_COUNT: int = 15
-
-QUESTION_SURFACE_NAME: str = "the question"
-OPTION_DESCRIPTION_SURFACE_NAME: str = "an option description"
-
-LEAN_QUESTION_BLOCK_PREFIX: str = "BLOCKED: [LEAN_QUESTION] Question block carries chat detail -- "
-LEAN_QUESTION_VIOLATION_SEPARATOR: str = "; "
-HEAVY_WORD_SWAP_LIST_SEPARATOR: str = ", "
-LEAN_QUESTION_BLOCK_GUIDANCE: str = (
-    "AskUserQuestion renders as one plain text block. Print the plan, the counts, "
-    "and the tradeoffs in chat text before the call, keep the question block to a "
-    "lean question and short options, and reach for an inline visualizer tool when "
-    "a choice needs formatting."
-)
-USER_FACING_LEAN_QUESTION_NOTICE: str = (
-    "Question-block check: move the detail into chat and ask a short question."
-)

package/hooks/hooks_constants/test_hook_log_extractor_constants.py

@@ -1,123 +0,0 @@
-"""Behavior tests for query-name pattern and exit-code routing contracts."""
-
-from __future__ import annotations
-
-import re
-import sys
-from pathlib import Path
-
-_HOOKS_ROOT = Path(__file__).resolve().parent.parent
-if str(_HOOKS_ROOT) not in sys.path:
-    sys.path.insert(0, str(_HOOKS_ROOT))
-
-from hooks_constants import hook_log_extractor_constants
-from hooks_constants.hook_log_extractor_constants import (
-    EXIT_CODE_ENVIRONMENT_MISSING,
-    EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING,
-    EXIT_CODE_SUCCESS,
-    EXIT_CODE_UNKNOWN_QUERY,
-    LOCK_MAXIMUM_RETRY_COUNT,
-    LOCK_RETRY_SLEEP_SECONDS,
-    QUERY_NAME_PATTERN,
-    SENTINEL_INSERT_FAILURE_MESSAGE,
-    SENTINEL_SELECT_FAILURE_MESSAGE,
-    STOP_WRAPPER_DEBOUNCE_SECONDS,
-    STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE,
-    WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG,
-    WINDOWS_CREATE_NO_WINDOW_FLAG,
-)
-
-
-def _matches_query_pattern(candidate_name: str) -> bool:
-    return re.fullmatch(QUERY_NAME_PATTERN, candidate_name) is not None
-
-
-def test_query_name_pattern_allows_canonical_pre_baked_query_name() -> None:
-    assert _matches_query_pattern("top_blockers_last_24_hours")
-
-
-def test_query_name_pattern_rejects_path_traversal() -> None:
-    assert not _matches_query_pattern("../etc/passwd")
-
-
-def test_query_name_pattern_rejects_uppercase() -> None:
-    assert not _matches_query_pattern("TopBlockers")
-
-
-def test_query_name_pattern_rejects_hyphens() -> None:
-    assert not _matches_query_pattern("top-blockers")
-
-
-def test_query_name_pattern_rejects_empty_string() -> None:
-    assert not _matches_query_pattern("")
-
-
-def test_unknown_query_exit_code_distinguishes_from_success() -> None:
-    assert EXIT_CODE_UNKNOWN_QUERY != EXIT_CODE_SUCCESS
-
-
-def test_unknown_query_exit_code_distinguishes_from_extractor_offline_fallback() -> None:
-    assert EXIT_CODE_UNKNOWN_QUERY != EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING
-
-
-def test_unknown_query_exit_code_distinguishes_from_init_environment_missing() -> None:
-    assert EXIT_CODE_UNKNOWN_QUERY != EXIT_CODE_ENVIRONMENT_MISSING
-
-
-def test_extractor_offline_fallback_matches_success_so_stop_hook_does_not_surface_failure() -> None:
-    assert EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING == EXIT_CODE_SUCCESS
-
-
-def test_sentinel_insert_failure_message_is_distinct_from_select_failure() -> None:
-    assert SENTINEL_INSERT_FAILURE_MESSAGE != SENTINEL_SELECT_FAILURE_MESSAGE
-    assert SENTINEL_INSERT_FAILURE_MESSAGE
-
-
-def test_resolver_falls_back_to_home_when_claude_home_is_empty(
-    monkeypatch,
-) -> None:
-    monkeypatch.setenv("CLAUDE_HOME", "")
-
-    assert (
-        hook_log_extractor_constants._resolve_claude_home_directory()
-        == Path.home() / ".claude"
-    )
-
-
-def test_resolver_falls_back_to_home_when_claude_home_is_whitespace(
-    monkeypatch,
-) -> None:
-    monkeypatch.setenv("CLAUDE_HOME", "   ")
-
-    assert (
-        hook_log_extractor_constants._resolve_claude_home_directory()
-        == Path.home() / ".claude"
-    )
-
-
-def test_lock_retry_constants_are_positive_and_bounded() -> None:
-    assert LOCK_MAXIMUM_RETRY_COUNT > 0
-    assert LOCK_RETRY_SLEEP_SECONDS > 0
-
-
-def test_stop_wrapper_debounce_seconds_is_positive() -> None:
-    assert STOP_WRAPPER_DEBOUNCE_SECONDS > 0
-
-
-def test_stop_wrapper_last_run_timestamp_file_is_under_claude_home() -> None:
-    expected_path = (
-        hook_log_extractor_constants._resolve_claude_home_directory()
-        / "logs"
-        / "hooks"
-        / ".state"
-        / "stop_wrapper_last_run.txt"
-    )
-    assert Path(STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE) == expected_path
-
-
-def test_windows_creation_flags_are_distinct_nonzero_bits() -> None:
-    assert WINDOWS_CREATE_NO_WINDOW_FLAG > 0
-    assert WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG > 0
-    assert (
-        WINDOWS_CREATE_NO_WINDOW_FLAG & WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG
-    ) == 0

package/rules/doc-prose-cuts.md

@@ -1,58 +0,0 @@
-# Documentation Prose Cuts
-
-Prose a reader acts on states settled facts, decisions, and behavior directly. Four sentence shapes carry no fact the reader can act on. Cut each on sight, in `.md` files, in code comments, and in docstrings alike.
-
-A detail earns its place by mattering now, or by being timeless enough to matter for future work. Everything else is noise.
-
-## The four cut shapes
-
-### 1. Exclusion claims — state the claim itself
-
-Establishing a claim by naming what it is not, or by walking rejected candidates to reach the answer. Replace with the claim and the evidence behind it.
-
-> This is not Option A from the original framing.
-
-Cut it. Write what the approach is.
-
-### 2. Justification sentences — state the fact, drop the payoff
-
-A sentence whose only job is to say why a stated choice is good, or to restate a gain the reader already works out from the behavior around it or from a rule enforced elsewhere.
-
-> The lenses point at this file and read it when they run; they do not carry its text in their spawn prompts, so the checklist stays out of the per-round token budget.
-
-Keep the first clause. Cut the tail — the reader reaches it alone.
-
-For each sentence, ask: **does it state a fact the reader can act on that they could not already work out from the behavior around it?** If no, cut it.
-
-A rule's one-line reason stated in present behavior stays — `--jq` runs per page, so cross-page sorts give wrong results — because that reason names a fact the reader needs to pick the right call. A tradeoff or constraint the reader weighs before choosing a path stays too.
-
-### 3. Conversation references — write for a reader who saw nothing
-
-Every document stands alone. A reader with zero prior context understands every statement without the conversation that produced it.
-
-| Shape | Example | Fix |
-|---|---|---|
-| Options discussed in chat | "This is not Option A from the original framing" | State the decision on its own terms |
-| "As discussed" / "as we decided" | "As discussed, we'll use embeddings" | "Sref matching uses sentence-transformer embeddings" |
-| Pronouns pointing at chat | "This addresses the concerns raised earlier" | Name the concerns inline, or cut |
-| Relative framing on unseen alternatives | "Instead of the three options considered" | State the chosen approach directly |
-| Session sequencing | "After Round 3 we decided…" | State the decision as a fact |
-
-Obsidian session logs are the exception — they are conversation-scoped on purpose.
-
-### 4. Time references — describe current state only
-
-Never reference removed implementations, old defaults, prior behaviors, or earlier contracts. A module or function docstring carries the same current-state-only contract as a `.md` file.
-
-Comparisons to alternatives that still exist stay allowed ("use `--paginate --slurp | jq`, not `--jq` alone"), as do references to external defects that still exist (gh CLI #10459).
-
-After writing, ask: read a year from now by someone who knew no earlier state, does every sentence still make sense? If a sentence only helps someone who knew an earlier state, cut it.
-
-## Enforcement
-
-- **Write-time.** `state_description_blocker` (PreToolUse on Write|Edit) blocks historical and comparative phrases in `.md` prose, code comments, and Python docstrings. A phrase wrapped in double quotes or backticks inside a docstring counts as a mention and is skipped. The denial names the matched phrases and shows a rewrite.
-- **AI review.** The claude-dev-env repository's `.cursor/BUGBOT.md` names the other three shapes as findings an agent applies to the `.md` lines a PR changes. Judgment-based review covers these shapes because a regex cannot read sentence meaning.
-
-## Sibling rule
-
-[`plain-language.md`](plain-language.md) governs word choice — heavy words swapped for everyday ones. This rule governs which sentences survive at all.

package/rules/eli11-replies.md

@@ -1,36 +0,0 @@
-# ELI11 Replies
-
-**Users read about 20% of your words, and 79% of them scan.** Write every reply so the bold words alone tell the whole story.
-
-## Four skim mechanics
-
-1. **Bold keyword first** — open every line and bullet with its load-bearing words in bold. Eyes land on the first words of a line, then fall down the left edge — the [F-pattern](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content-discovered/).
-2. **One idea per line** — a second idea in the same line is invisible to a skimmer.
-3. **Conclusion first** — the outcome goes in sentence one. Detail sits below it, or gets cut.
-4. **Half the words** — write it, halve it, halve it again. Stay brief by default; a requested full report may run long.
-
-**Measured gains** ([NN/g eyetracking](https://www.nngroup.com/articles/how-users-read-on-the-web/)): concise +58%, scannable layout +47%, both together +124%.
-
-## Reply shape
-
-1. **Action first** — when the user must act, open with "Do N things" and numbered click-by-click steps, one short line each.
-2. **Outcome first** — when nothing is needed, open with the outcome in one sentence.
-3. **Findings** — at most 3 short bullets.
-4. **Detail** — only when the user asks.
-
-## Rules
-
-- **One command per block** — a command the user runs goes in its own `bash`-tagged fenced block, so the Run button appears. That tag gives the user a Run button; [`shell-invocation-policy`](shell-invocation.md) stays in charge of the agent's own Bash-tool calls, which run pwsh-only.
-- **One line per status** — each background-work update gets a single line.
-- **Cut findings first** — when a reply runs long, drop findings and keep the action steps.
-- **Skim test** — reading only the bold words tells the whole story.
-
-## Progress and finals
-
-Mid-run and closing narration follow [`opus5-communication-contract.md`](opus5-communication-contract.md) (`opus5-communication-contract-v1`): first progress update is one sentence; later updates only for important discoveries or direction changes; the final starts with the outcome.
-
-## Relationship to other rules
-
-- **[`plain-language`](plain-language.md)** owns word choice; this rule owns reply length and shape.
-- **[`opus5-communication-contract`](opus5-communication-contract.md)** owns progress updates, outcome-first finals, and thinking-disabled tool narration.
-- **`AskUserQuestion`** carries every question to the user, in the same short style.

package/rules/opus5-communication-contract.md

@@ -1,45 +0,0 @@
-# Opus 5 communication contract
-
-**Marker:** `opus5-communication-contract-v1`
-
-Positive contract for visible replies. Complements [`eli11-replies.md`](eli11-replies.md) (shape) and [`plain-language.md`](plain-language.md) (word choice).
-
-## Visible output
-
-1. **Concise by default.** A simple answer stays brief. When the user asks for a full audit or deep dump, the reply may run long enough to cover the substance.
-2. **First progress update is one sentence.** After the first tool batch on a multi-step task, one short status line is enough.
-3. **Later updates only for important change.** Further mid-run narration marks only important discoveries or a direction change — not every tool call.
-4. **Final starts with the outcome.** The closing message leads with what happened; artifacts scale to their substance.
-5. **Material corrections only.** Narrate a correction only when it changes code, a conclusion, or a decision.
-
-## Thinking-disabled tool narration
-
-When thinking is disabled in the harness:
-
-1. Speak one brief natural-language sentence before a tool call that needs user-visible context.
-2. When no fitting tool exists, say so in plain language.
-3. Never put internal-system XML in visible output.
-
-## Positive examples
-
-### Short answer
-
-User: "What is the default branch?"  
-Reply: "**Default branch** is `main`."
-
-### Requested full audit
-
-User: "Audit every hook registration and list gaps."  
-Reply: Outcome first, then a structured audit long enough to cover each gap — ELI11 caps still guide skim shape, not a hard character ceiling when depth was asked.
-
-### First progress update
-
-After the first tool batch: "**Checked** `hooks.json` registration paths."
-
-### Important discovery mid-run
-
-"**Blocker:** the package suite shadows `config` — running as two sessions."
-
-### Outcome-first final
-
-"**Shipped** draft PR #123. CI green on head `abc1234`. Merge still needs your OK."

package/rules/plain-language.md

@@ -1,9 +0,0 @@
-# Plain Language
-
-All prose a person reads (chat, `AskUserQuestion`, docs, PR/issue bodies, commits): everyday words, short active sentences, lead with the answer, define jargon on first use, and give only the detail the reader needs to act (progressive disclosure). Aim for first-pass readability by a non-specialist. Exact identifiers, file paths, and API names stay exact; code is out of scope.
-
-The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) names an everyday swap for a heavy word when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off). That path is **allow with a systemMessage advisory** — it does not deny the write. AskUserQuestion lean-block structure stays always on and still denies chat detail. When the flag is off, heavy-word hits only emit privacy-safe advisory candidates (see [`docs/references/prose-style-enforcement.md`](../docs/references/prose-style-enforcement.md)). Code fences, inline code, blockquotes, URLs, and file paths are skipped.
-
-[`eli11-replies`](eli11-replies.md) governs reply length and shape; [`opus5-communication-contract`](opus5-communication-contract.md) governs progress and finals; this rule governs word choice.
-
-A project can keep its own domain words out of the check with a `.claude/plain-language-allow.json` file: a JSON array of terms. An exact, case-insensitive, whole-word match on any term passes. The hook reads this file only from inside the project tree, up to the repository root, so each project's allowlist stays with its own code.