claude-dev-env 2.7.1 → 2.9.0

package/hooks/hooks_constants/test_prose_metrics_parity.py

@@ -0,0 +1,124 @@
+"""Parity checks across the duplicated prose-metric copies.
+
+``plain_language_blocker_constants`` and ``eli11_reply_enforcer_constants``
+each carry their own copy of the metrics that read a reply's prose, so a
+tuning landed in one copy alone drifts the two gates apart. These checks fail
+loud on that drift::
+
+    COUNTABLE_WORD_PATTERN      ok:   byte-equal across both copies
+    table-row pattern           ok:   byte-equal across both copies
+    "- Run the migration"       ok:   both copies read a list marker
+    "1.5% of hosts still fail." ok:   neither copy reads a list marker
+    "**1.** Run the migration"  flag: the eli11 copy alone reads a marker
+
+The list-marker copies hold two different shapes — one combined regex against
+a bullet/numbered split — so they are pinned by the lines they agree on plus
+the one line they read differently.
+
+Row 2 of ``~/.claude/orchestrator-runs/falsify-first/parked-items.md`` carries
+the shared home that retires these copies.
+"""
+
+import pathlib
+import re
+import sys
+
+_HOOKS_ROOT = pathlib.Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants.eli11_reply_enforcer_constants import (
+    BULLET_LINE_PATTERN,
+    NUMBERED_STEP_PATTERN,
+    TABLE_ROW_PATTERN,
+)
+from hooks_constants.eli11_reply_enforcer_constants import (
+    COUNTABLE_WORD_PATTERN as ELI11_COUNTABLE_WORD_PATTERN,
+)
+from hooks_constants.plain_language_blocker_constants import ALL_CHAT_DETAIL_MARKERS
+from hooks_constants.plain_language_blocker_constants import (
+    COUNTABLE_WORD_PATTERN as PLAIN_LANGUAGE_COUNTABLE_WORD_PATTERN,
+)
+
+_TABLE_ROW_MARKER_LABEL = "a table row"
+_LIST_MARKER_LABEL = "a bullet or numbered list marker"
+_BOLD_NUMBERED_STEP_LINE = "**1.** Run the migration"
+
+_ALL_SHARED_LIST_MARKER_LINES = (
+    "- Run the migration",
+    "* Run the migration",
+    "+ Run the migration",
+    "1. Run the migration",
+    "2) Run the migration",
+    "   - Run the migration",
+    "  1. Run the migration",
+)
+
+_ALL_NON_LIST_MARKER_LINES = (
+    "Run the migration",
+    "1.5% of hosts still fail.",
+    "|table|row|",
+    "-no space after the dash",
+)
+
+
+def _chat_detail_marker_named(marker_label: str) -> re.Pattern[str]:
+    """Return the plain-language chat-detail pattern carrying one label.
+
+    Args:
+        marker_label: The label the chat-detail marker table gives a pattern.
+
+    Returns:
+        The compiled pattern registered under that label.
+    """
+    for each_pattern, each_label in ALL_CHAT_DETAIL_MARKERS:
+        if each_label == marker_label:
+            return each_pattern
+    raise AssertionError(f"no chat-detail marker labeled {marker_label!r}")
+
+
+def _eli11_copy_reads_a_list_marker(reply_line: str) -> bool:
+    """Report whether the eli11 bullet/numbered split reads a list marker.
+
+    Args:
+        reply_line: One line of reply text.
+
+    Returns:
+        True when either half of the split matches the line.
+    """
+    if BULLET_LINE_PATTERN.search(reply_line):
+        return True
+    return bool(NUMBERED_STEP_PATTERN.search(reply_line))
+
+
+def test_countable_word_pattern_copies_stay_byte_equal() -> None:
+    assert (
+        PLAIN_LANGUAGE_COUNTABLE_WORD_PATTERN.pattern
+        == ELI11_COUNTABLE_WORD_PATTERN.pattern
+    )
+    assert (
+        PLAIN_LANGUAGE_COUNTABLE_WORD_PATTERN.flags
+        == ELI11_COUNTABLE_WORD_PATTERN.flags
+    )
+
+
+def test_table_row_pattern_copies_stay_byte_equal() -> None:
+    plain_language_table_row = _chat_detail_marker_named(_TABLE_ROW_MARKER_LABEL)
+    assert plain_language_table_row.pattern == TABLE_ROW_PATTERN.pattern
+    assert plain_language_table_row.flags == TABLE_ROW_PATTERN.flags
+
+
+def test_list_marker_copies_agree_on_every_shared_line() -> None:
+    combined_marker = _chat_detail_marker_named(_LIST_MARKER_LABEL)
+    for each_line in _ALL_SHARED_LIST_MARKER_LINES:
+        assert combined_marker.search(each_line)
+        assert _eli11_copy_reads_a_list_marker(each_line)
+    for each_line in _ALL_NON_LIST_MARKER_LINES:
+        assert not combined_marker.search(each_line)
+        assert not _eli11_copy_reads_a_list_marker(each_line)
+
+
+def test_bold_numbered_step_reads_as_a_list_marker_in_the_eli11_copy_alone() -> None:
+    combined_marker = _chat_detail_marker_named(_LIST_MARKER_LABEL)
+    assert not combined_marker.search(_BOLD_NUMBERED_STEP_LINE)
+    assert _eli11_copy_reads_a_list_marker(_BOLD_NUMBERED_STEP_LINE)

package/output-styles/CLAUDE.md

@@ -0,0 +1,17 @@
+# output-styles
+
+Output-style instruction files installed into `~/.claude/output-styles/` by `bin/install.mjs`. Each file instructs an agent or session to respond in a specific voice or format.
+
+## Files
+
+| File | Style | Effect |
+|---|---|---|
+| `caveman-agent.md` | Caveman Agent | Terse fragments, lead with answer, smallest artifact that solves the stated problem, question premise before building |
+
+## Format
+
+Each file uses YAML frontmatter (`name`, `description`, optional `keep-coding-instructions`) followed by Markdown instructions. The `keep-coding-instructions: true` flag tells Claude Code to keep the session's coding rules even when this style is active.
+
+## Adding a style
+
+Create a `.md` file with frontmatter and behavioral instructions, then run `bin/install.mjs` to copy it to `~/.claude/output-styles/`.

package/output-styles/caveman-agent.md

@@ -0,0 +1,37 @@
+---
+name: Caveman Agent
+description: Caveman voice + caveman work. Terse replies, minimum viable artifacts, pushback before build.
+keep-coding-instructions: true
+---
+
+Caveman voice. Caveman work.
+
+## Voice
+
+Lead with answer. Drop articles, filler, hedging, preamble, recap.
+Fragments OK. Pattern: `[thing] [action] [reason]. [next step].`
+Keep code, paths, commands, errors, JSON unchanged.
+Bullets/tables only when scan beats prose.
+
+## Work ethos
+
+Smallest artifact that solves stated problem. Nothing more.
+One file beats three. Functions beat classes. Concrete beats abstract.
+No planning docs, no speculative tests, no future-proof params, no README unless asked.
+Question premise before building — if existing tool covers it, say so and stop.
+
+## Pushback rule
+
+Before any new file, ask:
+- Does existing tool already do this? If yes → say so, stop.
+- Is the scaffolding earning its keep right now? If no → drop it.
+- One file or many? → one, unless many is forced.
+
+## Escape hatch
+
+Normal language and normal care for:
+- Safety, destructive ops, irreversible actions
+- Money, credentials, production systems
+- Genuine confusion risk
+
+Caveman voice is for speed, not for hazards.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.7.1",
+    "version": "2.9.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -16,6 +16,7 @@
         "docs/",
         "commands/",
         "agents/",
+        "output-styles/",
         "skills/",
         "hooks/",
         "system-prompts/",

package/rules/CLAUDE.md

@@ -15,6 +15,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
+| `claims-as-quotes.md` | On agent reports, hand-offs, review verdicts, and PR or commit prose, a design-gating claim travels with its quoted lines and `path:line` reference; chat keeps research-mode compact citations; a claim without its quote is a lead to check |
 | `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
 | `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth, including §8 (TDD) and §7 (right-sizing); BDD is the outer process and TDD the inner loop |
 | `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |

package/rules/ask-user-question-required.md

@@ -3,3 +3,29 @@
 Route every user-directed question through the `AskUserQuestion` tool — never a plain-text question in a response's final paragraph. Structure: concise `question`, `header` of 12 chars or fewer, 2-4 options (the UI adds the "Other" fallback), `multiSelect` only when choices genuinely combine.
 
 The `question_to_user_enforcer` Stop hook blocks a response whose final paragraph (after stripping code fences, inline code, and blockquotes) ends in a question mark or contains ask-phrases ("would you like", "should I", "let me know if", ...). Rhetorical questions answered in the same paragraph, and questions inside code or blockquotes, pass. `verify-before-asking` gates whether the question belongs to the user at all.
+
+## The question block stays lean
+
+`AskUserQuestion` renders as one plain unformatted text block. Detail — plans, counts, tradeoffs, background — goes in chat text before the call. The block itself carries a lean question and short choices. When a choice needs formatting, an inline visualizer tool carries it.
+
+The `plain_language_blocker` PreToolUse hook denies an `AskUserQuestion` call whose `question` text or whose `description` under any of the `options` carries chat detail:
+
+| What the block carries | Cap |
+|---|---|
+| Fenced code block | none |
+| Heading | none |
+| Table row | none |
+| Bullet or numbered list marker | none |
+| Paragraphs | 1 — a blank line splits the block in two |
+| `question` sentences | 2 |
+| `question` words | 40 |
+| `description` sentences | 1 |
+| `description` words | 15 |
+
+Two fields are counted, and each one gets the same treatment: the `question` text, and the `description` under every entry of `options`. The four structure markers apply to both. The paragraph cap applies to both. The sentence and word caps differ by field, as the table shows.
+
+Structure is read at block level on the raw text: a marker counts when it opens a line, so a fence written on a single line still reads as a fence. Line endings fold to one spelling first, so a blank line counts whichever way it is written.
+
+An inline code span — a path, a flag, a command the reader needs verbatim — weighs one word against either word cap on both fields, so a question naming `--dry-run` and a choice naming `C:\dev\gate.py` both pass. A span sits inside a line, so it never opens one with a marker.
+
+A sentence closes on `.`, `!`, or `?` followed by a capitalized word or by the end of the text. A word is any whitespace-separated token carrying a letter or a digit. The denial names each cap the block broke and sends the detail back to chat text.

package/rules/claims-as-quotes.md

@@ -0,0 +1,65 @@
+# Claims as Quotes
+
+**When this applies:** Agent reports, hand-off artifacts, review verdicts, and PR or commit prose that state what existing code does. Always-on like `research-mode.md` for those durable surfaces — a commit message and a `gh` PR body have no shared path match. Chat replies use research-mode's compact citation only; the three-piece shape does not bind chat.
+
+## Rule
+
+Under `research-mode.md`, a factual claim carries its source. This rule sets the shape a claim takes when it decides a design or gates an action: the `path:line` reference, the quoted lines, and the claim sentence travel together. The consumer reads those lines before acting on the claim.
+
+In a chat reply, research-mode's compact citation stands — a linked source name or a `file:line` reference. The three-piece shape binds only agent reports, hand-off artifacts, review verdicts, and PR or commit prose.
+
+Claims of this shape:
+
+- "the helper already normalizes this"
+- "the gate covers that path"
+- "this caller handles the new shape"
+
+On the surfaces the three-piece shape binds, each one settles a design question for whoever reads it and carries its quote; a claim without its quote decides nothing: it is a lead to check, not a fact to build on.
+
+## The failure shape
+
+A paraphrase of code behavior, accepted without the source lines, ships a design premise nobody checked. The error surfaces when the built code meets the real behavior, with the design that rests on the premise already written.
+
+## What a claim carries
+
+| Piece | Shape |
+|---|---|
+| Reference | `payments/refund.py:88-90` — the path with the line span |
+| Quote | The lines word for word, in a fenced block |
+| Claim | One sentence naming what those lines settle |
+
+## Examples
+
+**A lead:** "`build_refund` already clamps the refund to the order total, so the new path needs no bound check."
+
+**A fact:** the reference, the lines, and the claim together.
+
+`payments/refund.py:88-90`
+
+```python
+def build_refund(order, requested_amount):
+    refund_amount = min(requested_amount, order.total)
+    return Refund(order_id=order.id, amount=refund_amount)
+```
+
+`build_refund` clamps to `order.total` on its one path, so a caller downstream of it needs no bound check.
+
+## What the consumer does
+
+- Read the quoted lines before the sentence that summarizes them.
+- On the surfaces the three-piece shape binds, treat a claim that arrives without its quote as a lead: pull the lines yourself, or ask the sender for them, before any design rests on it.
+- When the quoted lines say something other than the claim, the lines win.
+
+## Enforcement
+
+This rule binds as prose discipline: a reviewer applies it to the claims a report, a verdict, or a PR body makes about existing code. No hook backs it, because telling a design-deciding claim from background prose needs meaning a regex cannot read.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| `research-mode.md` | Names what counts as a citation and grounds a factual claim in word-for-word quotes |
+| `hedging-claims.md` | Catches a hedge word standing in for evidence on a claim; this rule catches a claim missing its quote |
+| `verify-runtime-state.md` | A verdict about what runs rests on a live probe from this session |
+| `falsify-before-green.md` | A check's green counts once the check has been shown red |
+| `measurement-denominators.md` | Every count names what it scanned |

package/rules/code-standards.md

@@ -1,13 +1,39 @@
 # Code Standards
 
-> **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
-> This is the single source of truth for code standards. Non-negotiable.
+> **Canonical policy:** repository-root [`AGENTS.md`](../../../AGENTS.md) — the human and AI review contract for code quality.
+> **Compact projection:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — validated summary for generation load.
+> **Production enforcement:** `hooks/blocking/code_rules_enforcer.py` — hand-maintained Write/Edit gates; each mechanical rule carries a synchronization test.
 
-`CODE_RULES.md` (`~/.claude/docs/CODE_RULES.md`) is the compact reference for every standard: self-documenting names, centralized configuration, constant reuse, no magic literals, full words, complete type hints, required-vs-optional parameters, construction logic in the model, temporary-code `TODO:` markers, behavior-first component names, and TDD.
+## Policy surface map
 
-Two standards live there in full and nowhere else:
+| Layer | Path | Role |
+|---|---|---|
+| Canonical | `AGENTS.md` (repo root) | Full review criteria for PR agents; BugBot sync source |
+| Projection | `docs/CODE_RULES.md` | Compact always-load reference; must not diverge from AGENTS |
+| Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained blockers; not generated from the docs |
+| Session rules | `rules/*.md` | Runtime session policy (questions, tasks, shell) |
 
-- **TDD** — CODE_RULES §8 is canonical: red, green, refactor, with no production code before a failing test.
-- **Right-sized engineering** — CODE_RULES §7 is canonical: functions over classes, concrete over abstract, an abstraction added at the commit that introduces its second concrete implementation.
+Load `AGENTS.md` when reviewing a PR or resolving a policy conflict. Load `CODE_RULES.md` when generating code under the compact checklist. Prefer linking these refs over restating rules.
 
-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 CODE_RULES §8 red-green-refactor cycle.
+Two standards live in the canonical policy in full (and in the projection by name):
+
+- **TDD** — CODE_RULES §8 / AGENTS Tests: red, green, refactor; no production code before a failing test.
+- **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.
+
+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 |
+|---|---|
+| Question routing | [`ask-user-question-required.md`](ask-user-question-required.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) |
+
+## Synchronization
+
+Mechanical enforcer coverage is checked by `tests/test_agents_policy_parity.py` and the existing `hooks/blocking/test_code_rules_enforcer*.py` suite. BugBot projection drift is checked with:
+
+```
+python .github/scripts/sync_ai_rules.py --check
+```

package/rules/eli11-replies.md

@@ -20,7 +20,7 @@
 
 ## 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-policy.md) stays in charge of the agent's own Bash-tool calls, which run pwsh-only.
+- **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.

package/scripts/CLAUDE.md

@@ -6,13 +6,13 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 
 | File | Purpose |
 |---|---|
-| `claude_chain_runner.py` | Runs a `claude` invocation through a usage-ranked fallback chain (`~/.claude/claude-chain.json`): probes weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, tries the highest-remaining account first, and falls over to the next ranked binary only on a usage-limit failure; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
+| `claude_chain_runner.py` | Runs a `claude` invocation through a fallback chain (`~/.claude/claude-chain.json`) with `--routing-mode usage_ranked` (default: probe weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, highest remaining first) or `ordered_account` (config list order; non-usage failures stop as `advisor_blocked`); falls over only on a usage-limit failure; returns `terminal_status` / optional `session_id` on the outcome; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
 | `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try order |
 | `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
 | `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv with no turn cap (the timeout is the only bound), mints a unique leader socket, captures streams, refuses a timeout that is missing, below `MIN_WORKER_TIMEOUT_SECONDS`, or above the `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) ceiling, kills the whole process tree on timeout with grace and retries the kill-and-drain round once, classifies ok/usage_limit/auth_failure/timeout/kill_failed/error; exports `require_timeout_within_bounds` so a dispatcher can apply the same bounds without launching; imported by `spawn_grok_batch.py` and `resolve_worker_spawn.py` |
 | `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
-| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
+| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, optionally binds a unique worker advisor per role via the lead-supplied `advisor.launcher` (placeholder default in constants), injects `advisor_session_id`, requires the same session ENDORSE or bounded CORRECTION/PLAN then ENDORSE, classifies bind/verdict/timeout/missing-launcher failures as `advisor_blocked`, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
 | `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |
 | `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); applies `require_timeout_within_bounds` before the preflight, so an out-of-bounds `--timeout-seconds` prints a `timeout_out_of_bounds` outcome and exits 3 on every tier; protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
@@ -33,7 +33,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 
 | Entry | Description |
 |---|---|
-| `dev_env_scripts_constants/` | Named constants (`timing.py`) for scripts in this directory |
+| `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
 | `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
 | `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
 

package/scripts/_code_review_test_support.py

@@ -27,6 +27,10 @@ if _SCRIPTS_DIRECTORY not in sys.path:
 import claude_chain_runner as chain_runner  # noqa: E402
 import invoke_code_review as invoker  # noqa: E402
 from claude_chain_runner import ChainAttempt, ChainInvocationOutcome  # noqa: E402
+from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
+    TERMINAL_STATUS_CHAIN_EXHAUSTED,
+    TERMINAL_STATUS_SERVED,
+)
 from dev_env_scripts_constants.code_review_constants import (  # noqa: E402
     CLI_SESSION_MODEL_FLAG,
     CODE_REVIEW_MODEL_ALIAS,
@@ -128,6 +132,7 @@ def claude_served(
         stdout=stdout,
         stderr="",
         attempts=(ChainAttempt(command=FIXTURE_SERVED_COMMAND, status="served"),),
+        terminal_status=TERMINAL_STATUS_SERVED,
     )
 
 
@@ -140,6 +145,7 @@ def claude_failed() -> ChainInvocationOutcome:
         attempts=(
             ChainAttempt(command=FIXTURE_SERVED_COMMAND, status="usage_limited"),
         ),
+        terminal_status=TERMINAL_STATUS_CHAIN_EXHAUSTED,
     )
 
 

package/scripts/check.ps1

@@ -1,8 +1,8 @@
 #!/usr/bin/env pwsh
 <#
 .SYNOPSIS
-    One-shot quality gate — runs ruff, hooks mypy, pr-loop mypy, and the
-    blocking pytest suite from a single entry point.
+    One-shot quality gate — runs ruff, hooks mypy, pr-loop mypy,
+    process-tree mypy, and the blocking pytest suite from a single entry point.
 
 .DESCRIPTION
     Resolves paths relative to $PSScriptRoot so the script works from any CWD
@@ -10,7 +10,8 @@
     and the installed runtime (~/.claude/scripts/check.ps1, after install.mjs
     propagates this file). Tools: ruff over hooks/, mypy over hooks blocking
     and validators, mypy-pr-loop over _shared/pr-loop/scripts production
-    modules, and optional pytest over the blocking enforcer suite. Each tool
+    modules, mypy-process-tree over the shared process-tree kill helper and
+    its constants, and optional pytest over the blocking enforcer suite. Each tool
     runs sequentially; the first non-zero exit code is preserved as the
     script's exit code so CI/pre-commit can short-circuit on the first failure.
 
@@ -19,7 +20,7 @@
     static-analysis gates.
 
 .PARAMETER SkipMypy
-    Skip both mypy runs (hooks mypy and mypy-pr-loop).
+    Skip every mypy run (hooks mypy, mypy-pr-loop, and mypy-process-tree).
 
 .PARAMETER SkipRuff
     Skip the ruff run.
@@ -27,7 +28,7 @@
 .OUTPUTS
     Per-tool status lines on stdout. Final summary line:
         CHECK: OK
-        CHECK: FAILED tools=ruff,mypy,mypy-pr-loop,pytest
+        CHECK: FAILED tools=ruff,mypy,mypy-pr-loop,mypy-process-tree,pytest
 #>
 [CmdletBinding()]
 param(
@@ -41,6 +42,7 @@ $ErrorActionPreference = 'Stop'
 $hooksRoot = Resolve-Path (Join-Path $PSScriptRoot '..' 'hooks')
 $blockingRoot = Join-Path $hooksRoot 'blocking'
 $prLoopScriptsRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '_shared' 'pr-loop' 'scripts')
+$processTreeScriptsRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '_shared' 'process-tree' 'scripts')
 
 $failedTools = @()
 $firstNonZeroExitCode = 0
@@ -108,6 +110,17 @@ if (-not $SkipMypy) {
             Pop-Location
         }
     }
+
+    Invoke-Tool -Label 'mypy-process-tree' -Action {
+        Push-Location $processTreeScriptsRoot
+        try {
+            mypy --config-file (Join-Path $processTreeScriptsRoot 'pyproject.toml') `
+                process_tree_kill.py `
+                config/process_tree_scripts_constants
+        } finally {
+            Pop-Location
+        }
+    }
 }
 
 if (-not $SkipTests) {