claude-dev-env 2.0.0 → 2.0.2

package/skills/everything-search/SKILL.md

@@ -13,7 +13,13 @@ Search files instantly on Windows using the Everything command-line interface (e
 
 ## Hard limits
 
-Scope and fallback policy: `packages/claude-dev-env/rules/es-exe-file-search.md`.
+Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds — narrow the search to what you need.
+
+When `es.exe` fails or returns nothing, self-heal first: fall back to the `Glob` tool (name and path patterns) or `Grep` (file contents), and report the outage so the reader knows the index was unavailable. When self-healing also fails, ask the user through `AskUserQuestion` with a short analysis and next-step options.
+
+## Registry tokens
+
+The `es_exe_path_rewriter` hook resolves scope tokens before the command runs. A `{project-name}` placeholder or a bare registry key from `~/.claude/project-paths.json` becomes its quoted absolute path in the command. The hook allows and rewrites — it never blocks — so a search scoped to a registered project names the project token and lets the hook fill in the path.
 
 ## Instructions
 

package/skills/orchestrator/SKILL.md

@@ -21,115 +21,118 @@ delegating to Sonnet-5 workers came out cheaper and faster
 than a solo frontier agent held to the same verification rigor, with
 84-98% of the team's input tokens billed at the worker rate.
 
-Claude Code has no `multiagent` coordinator field or Managed-Agents-style
-`create_agent`/`send_to_agent` primitives; this skill reaches the same
-shape with the tools Claude Code already has. Under this skill the session
-is the orchestrator. In Claude Code the user always talks to the session and never to a
-subagent, so the session is the user's sole interface: all user-facing
-communication flows through it. It spawns and resumes executor subagents
-— `clean-coder` and the like — and those executors do every bit of the
-execution: the code edits, the build runs, the test runs. The orchestrating
-session drives the plan and routes hard decisions to the shared advisor
-(Claude: warm `session-advisor`; a third-party host: Claude CLI advisor via the chain runner).
-
-## Gotchas
-
-- **Double invocation duplicates the reminder loop.** A second `/orchestrator`
-  in the same session schedules a second refresh loop. Check whether the loop
-  is already running before you schedule one (see the invocation guard in
-  Process step 1).
-- **The orchestrating session never executes.** The moment it edits a file or
-  runs the tests itself, the pairing breaks and the executor's warm context is
-  wasted. Hand every code edit and every build or test run to an executor; keep
-  the orchestrating session's own tool use to orchestration and light
-  verification reads. Hard decisions go to the shared advisor (Claude:
-  `session-advisor` via SendMessage; a third-party host: Claude CLI advisor via the chain).
-- **Flat ad hoc spawns bypass routing.** Every execution task goes through a
-  workflow-backed spawn or workflow resume so the required agent type, model,
-  prompt packet, and sidecar metadata stay attached to the work.
-- **Wrong agent or model is an enforcement failure.** If a task category maps
-  to `clean-coder` on `opus`, a `general-purpose` Sonnet spawn is not a cost
-  optimization; it is the wrong executor for the contract.
-- **Resuming an unnamed background agent needs its agentId.** A background
-  spawn returns an `agentId` (format `a...-...`); keep it so `SendMessage` can
-  reach that agent later. A named agent is reachable by name.
-- **Only the orchestrating session owns the shared advisor's lifecycle.** An
-  executor that finds the advisor unreachable (Claude warm agent, or Claude
-  CLI bind on a third-party host) reports that upward; it never spawns a replacement itself.
+Under this skill the session is the orchestrator. It spawns and resumes
+executor subagents — `clean-coder` and the like — and those executors do
+every bit of the execution: the code edits, the build runs, the test
+runs. The orchestrating session drives the plan, keeps the run artifacts
+and the ledger current, and routes hard decisions to the shared advisor.
+The moment it edits a file or runs a test itself, the pairing breaks —
+its own tool use stays orchestration, run-artifact writes, and light
+verification reads.
+
+## Design rule — thin prompts, thick artifacts, thin skill
+
+Three faces of one rule (reading pinned by the audit spec on
+jl-cmd/claude-dev-env#174: thin means high-signal, not short; thick
+context lives outside the window, reachable by pointers):
+
+- **Thin prompts.** A spawn prompt is a dispatch ticket: one task,
+  pointers to the artifacts that hold the context, one done-check, a thin
+  return contract. The prompt can be thin because the context is thick
+  elsewhere.
+- **Thick artifacts.** Durable run state lives in files — the run
+  charter, one assignment file per task, result records — written once,
+  read by every agent that needs them, and still there when any one
+  agent's context is gone.
+- **Thin skill.** This file holds only what changes decisions at
+  orchestration time. Standing policy lives where it loads once:
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
+  for everything advisor, the agent definitions for executor discipline.
 
 ## Process
 
-1. **Check whether the refresh loop is already running this
-   session.** If it is, do not schedule a second loop. Reuse any live
-   shared advisor bind (Claude warm `session-advisor`, or a third-party host's
-   Claude CLI bind — run step 3 only when none exists yet), then skip straight to step 4.
-
-2. **Register the discipline reminder.** By default, schedule it with
-   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/orchestrator-refresh`,
-   where each refresh re-schedules the next one — a 1200-second wakeup costs
-   one prompt-cache miss per firing and nothing more (see Gotchas). The loop
-   mechanism (`/loop 20m /orchestrator-refresh`) is the escape hatch when
-   `ScheduleWakeup` is not available. Either way the reminder is the
-   enforcement surface: each firing re-asserts the discipline while the run is
-   in flight.
-
-3. **Bind the shared advisor before any executor.** Detect the host profile
-   first (see Host profiles in
-   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)).
-   On a **Claude host**, follow the Warm-up procedure in that doc (Agent spawn
-   of `session-advisor`). Compute the model floor as the max of the
-   orchestrating session's own tier and the highest model in the Workflow Agent
-   Routing table below (for example, max(Sonnet, Opus) = Opus when those are
-   the tiers in play). That floor is a lower bound only — the Claude spawn walk
-   tries top-down from Fable down to that floor per
-   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md);
-   it is not a "spawn only at the floor" rule. Paste the **Claude host**
-   Advisor block from that doc, with the resolved agent name filled in, into
-   every executor's spawn prompt. On a **third-party host**, skip the Agent spawn —
-   bind a max-tier Claude advisor through the protocol's CLI Claude-chain path
-   (Fable high, then Opus max; `claude_chain_runner.py` for account usage
-   failover). Paste the **Third-party host** Advisor block from that doc into every
-   executor's spawn prompt — never the Claude SendMessage block. Every row in
-   the routing table is a consumer of the shared advisor, not just this
-   session. The orchestrating session owns the shared advisor's lifecycle end
-   to end (Agent spawn or CLI bind, drift handling per the shared doc,
-   shutdown at task end); executors only ever SendMessage the warm agent
-   (Claude) or report to this session so it can consult the CLI advisor
-   (a third-party host). When the CLI chain cannot bind, fail closed and report
-   to the user — do not answer the four signals as this third-party session.
-
-4. **Orchestrate the task.** Hold the plan and the user conversation. Execute
-   workflow-backed spawns or resumes using the routing table below, and keep
-   driving while they work. Every executor spawn includes the host-matched
-   Advisor block from step 3. Your own tool use stays orchestration and light
-   verification reads. Keep your task list updated religiously.
-
-5. **Consult the shared advisor at hard decisions.** Every consumer — each
-   executor and this session — consults when one of these holds (same list as
-   the protocol and Advisor block):
-   - A nontrivial plan is about to be locked in and acted on.
-   - The consumer believes its assigned work is finished.
-   - A commit, push, or other hard-to-reverse action is about to run.
-   - The same failure has come back more than once, or progress has stalled.
-   - The chosen approach is being reconsidered.
-
-   **Claude host:** consult the shared `session-advisor` via `SendMessage`.
-   **Third-party host:** executors report to this orchestrating session; this session
-   consults the bound Claude CLI advisor (`claude_chain_runner.py` +
-   `--resume`) and relays the four-signal reply (no Agent-tool
-   `session-advisor`, no SendMessage to one). Every consult gets back one of
-   four signals (ENDORSE, CORRECTION, PLAN, or STOP). When the CLI advisor is
-   unreachable, fail closed and surface that to the user — do not invent a
-   signal as this session. See `agents/session-advisor.md` for what each
-   signal means and
+1. **Invocation guard.** One `/orchestrator` per session. When the
+   refresh loop is already running, do not schedule a second one; reuse
+   the live advisor bind and go to step 4.
+2. **Register the discipline reminder.** Schedule it with
+   `ScheduleWakeup` at `delaySeconds: 1800`, prompt
+   `/orchestrator-refresh`, where each refresh re-schedules the next one.
+3. **Bind the shared advisor before any executor.** Follow
    [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
-   for the consult format.
+   end to end: detect the host profile, compute the floor from the
+   orchestrator consumer set — this session plus every tier in the
+   routing table (its Model floor section) — walk the ladder top-down,
+   and fail closed when nothing binds. This session owns the advisor's
+   whole lifecycle (its Lifecycle ownership section); executors only ever
+   message the warm agent or report here, and an executor that finds the
+   advisor unreachable reports that upward — it never spawns a
+   replacement itself.
+4. **Write the run artifacts** (next section) before the first spawn.
+5. **Orchestrate.** Hold the plan and the user conversation. Spawn each
+   task with a ticket (Spawn ticket section), keep driving while
+   executors work, and keep the ledger reconciled (Task ledger
+   discipline).
+6. **Consult the advisor at hard decisions.** The trigger list, consult
+   format, and reply handling live in the protocol's "Consulting the
+   warm agent" section; both this session and every executor are
+   consumers. Replies open with one of ENDORSE, CORRECTION, PLAN, or
+   STOP — `agents/session-advisor.md` defines each signal.
+
+## Run state lives in artifacts
+
+Write these before the first spawn, default home `docs/plans/<run-slug>/`
+in the repo the run works on (working files, not committed):
+
+- **Run charter** — the goal, the repo root, the advisor name and host
+  profile. One file every ticket points at.
+- **One assignment file per task** — scope, file list, constraints, the
+  acceptance check, baseline command output. The thick context goes
+  here. `/prompt-generator` authors the assignment once at plan time,
+  and every ticket for that task reuses it — that reuse is what
+  satisfies the agent-spawn-protocol context check at each spawn.
+- **Results merge into run state.** An executor's product is its
+  artifact — the branch diff, the test output, the report its agent type
+  may write — and its reply is thin: status, artifact paths, blockers.
+  The orchestrating session records each result into the run's result
+  files as it reconciles the ledger.
+
+Correctness never rides on any agent's private context: when an executor
+dies or hangs, point a fresh spawn at the same assignment file plus its
+partial results and the run continues.
+
+## Spawn ticket — the whole prompt
+
+Every executor spawn prompt is this shape:
+
+```
+Task: <one sentence, one deliverable>
+Read first: <assignment file path>; <run charter path>
+Touch only: <files or globs>
+Done when: <one mechanical check — a command, a test, a diff scope>
+Return: status, artifact paths, blockers — nothing else.
+
+<host-matched Advisor block from advisor-protocol.md, advisor name filled in>
+```
+
+- **Size the task by its done-check.** The right task is the largest
+  unit that fits one sentence plus pointers, has one mechanical
+  done-check, and needs no mid-run clarification. A task that does not
+  fit gets split in the plan — never padded into a longer prompt.
+  Explore fan-outs run tiny; a `clean-coder` assignment can carry a
+  whole scoped feature.
+- **Do not restate what the agent definition carries.** The routing
+  table picks the definition, and `clean-coder` already holds the code
+  discipline. The ticket adds the task, the pointers, and the Advisor
+  block only.
+- **The Advisor block is the one pasted paragraph.** It is host-matched
+  at bind time and written to be self-contained (the protocol's Advisor
+  block section) — paste it; do not point at it.
 
 ## Workflow Agent Routing
 
-Every delegated task runs through a workflow-backed agent invocation. Do not
-spawn a flat subagent directly when a workflow invocation or workflow resume is
-available.
+Every delegated task runs through a workflow-backed agent invocation. Do
+not spawn a flat subagent directly when a workflow invocation or
+workflow resume is available.
 
 | Work | Agent type | Model |
 |---|---|---|
@@ -141,58 +144,78 @@ available.
 
 Routing rules:
 
-- Use a workflow invocation or resume for each row above. The workflow prompt
-  must name the selected agent type, model, work category, task scope, and
-  expected output.
-- Resume a warm workflow agent before creating a new workflow run when the warm
-  agent holds the relevant context.
-- `clean-coder` owns code edits. `code-verifier` owns verification. The same
-  workflow agent never grades work it wrote.
-- PR-description workflows include the actual changed-file list in the prompt
-  and verify the final body against that file list before posting or returning
-  it.
-- Exploration workflows return file paths, line numbers, and direct evidence;
-  they do not write code or mutate repo state.
+- Each row spawns workflow-backed with a ticket; the routing row and the
+  ticket together carry the agent type, model, task, and return
+  contract. A task category that maps to `clean-coder` on `opus` is not
+  served by a `general-purpose` Sonnet spawn — the table is the
+  contract, not a cost suggestion.
+- Resume a warm workflow agent before creating a new workflow run when
+  the warm agent holds the relevant context.
+- `clean-coder` owns code edits. `code-verifier` owns verification. The
+  same workflow agent never grades work it wrote.
+- PR-description workflows include the actual changed-file list in the
+  prompt and verify the final body against that file list before posting
+  or returning it.
+- Exploration workflows return file paths, line numbers, and direct
+  evidence; they do not write code or mutate repo state.
 - Fan-out worker fleets use the **grok-spawn** skill when that skill is
-  installed and grok is usable (`grok_worker_preflight.py` soft gate). The
-  Claude Code Agent tool remains the Claude-host alternative for in-process
-  workers.
-
-## Agent reuse (non-negotiable)
-
-- **Resume before you spawn, always.** A warm agent carries its context and
-  cached tokens; a fresh spawn starts cold and pays to rebuild both.
-  Resume the existing workflow agent by name or `agentId` when it holds
-  relevant context. Prefer that path every time an existing workflow agent
-  matches the routing table.
-- **Spawn a fresh agent only when** no existing agent holds relevant context,
-  or a genuine task switch needs a clean context.
-- **Name the agent to resume.** When a PLAN from the shared advisor fits a warm
-  agent, name which agent to resume and where.
+  installed and grok is usable (`grok_worker_preflight.py` soft gate).
+  The Claude Code Agent tool remains the Claude-host alternative for
+  in-process workers.
+
+## Agent reuse
+
+- **Resume before you spawn.** A warm agent (active within the past 59
+  minutes) carries its context and cached tokens; a fresh spawn pays to
+  rebuild both. Resume by name, or by `agentId` for an unnamed
+  background spawn — keep the `agentId` (format `a...-...`) from the
+  spawn result so `SendMessage` can reach that agent later.
+- **Spawn a fresh agent only when** no existing agent holds relevant
+  context, or a genuine task switch needs a clean context.
+- **Reuse is a cost rule, not a correctness dependency.** The run
+  artifacts keep every executor replaceable (Run state section).
+- **Name the agent to resume.** When a PLAN from the shared advisor fits
+  a warm agent, name which agent to resume and where.
+
+## Task ledger discipline
+
+The task list is the run's ledger, and it must be reconcilable against
+the live agents at any moment. Four invariants hold at all times:
+
+1. **No untracked work.** Every unit of delegated work has a task BEFORE
+   its executor spawns — TaskCreate first, then Agent.
+2. **Ownership is live.** At spawn, set the task `in_progress` with
+   `owner` = the executor's agent name. One task, one owner.
+3. **Completion follows evidence.** A task turns `completed` only when
+   the executor's result is back AND merged into run state — the run's
+   result files and the task record — never on dispatch, never on a
+   self-report alone (see `workers-done-before-complete`).
+4. **Dependencies mirror the plan.** Phase order is encoded as
+   `blockedBy` links, updated the moment the plan changes.
+
+Reconcile on every state change (spawn, completion notification, plan
+change) and on every `/orchestrator-refresh` firing.
 
 ## Constraints
 
 - One `/orchestrator` per session; the invocation guard blocks a second
   reminder loop.
-- The orchestrating session orchestrates and routes hard decisions to the
-  shared advisor (host-matched path in step 5), but never edits code or runs a
-  build or test itself — executors do that.
-- Delegated execution uses workflow-backed agent invocations and follows the
-  Workflow Agent Routing table exactly.
-- One shared advisor per orchestrated session, owned by the orchestrating
-  session (see
-  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md))
-  — on Claude, executors consult a warm `session-advisor` via SendMessage; on
-  a third-party host, executors report here and this session relays the Claude CLI advisor.
-  Executors never spawn or respawn the advisor.
-- Reuse a warm agent over a cold spawn whenever one holds relevant context.
+- The orchestrating session never edits code or runs a build or test
+  itself — executors do that. Its own tool use stays orchestration,
+  run-artifact writes, and light verification reads.
+- Every delegated task carries a ledger entry, an assignment artifact,
+  and a workflow-backed spawn with a ticket, routed by the table.
+- One shared advisor per orchestrated session, owned by this session per
+  the protocol; executors never spawn, respawn, or shut it down.
 
 ## File Index
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Orchestrator strategy, workflow routing contract, shared-advisor consult protocol, reuse rules, and constraints. |
+| `SKILL.md` | Orchestrator strategy: design rule, process, run artifacts, spawn ticket, routing table, reuse rules, ledger invariants, constraints. |
 
 ## Folder Map
 
-- `SKILL.md` — complete orchestrator workflow instructions.
+- `SKILL.md` — complete orchestrator workflow instructions. Advisor
+  policy lives in
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).

package/skills/orchestrator-refresh/SKILL.md

@@ -15,10 +15,18 @@ Detect the host profile first (see Host profiles in
 Re-assert the discipline for that host only — do not invent an Agent-tool
 Claude `session-advisor` spawn on a third-party host.
 
-1. **You are the orchestrator.** Orchestrate and hold the user conversation;
+1. **Reconcile the task ledger first.** Call `TaskList` before anything else
+   this firing. The ledger is stale when any of these holds: a running or
+   finished executor has no `in_progress` task naming it as owner; a finished
+   executor's task is still open (or was closed without its result merged);
+   the next phase you will dispatch has no pending task; a `blockedBy` link
+   contradicts the actual run order. Fix every mismatch with TaskCreate /
+   TaskUpdate in this same firing — never defer reconciliation to "when the
+   agent reports".
+2. **You are the orchestrator.** Orchestrate and hold the user conversation;
    spawn executor subagents to do all the work — every code edit and build or
    test run.
-2. **Hard decisions go to the shared advisor.**
+3. **Hard decisions go to the shared advisor.**
    - **Claude host:** executors consult the warm `session-advisor` via
      `SendMessage` and receive one of four signals — ENDORSE, CORRECTION, PLAN,
      or STOP. The orchestrating session routes its own hard decisions the same
@@ -30,11 +38,11 @@ Claude `session-advisor` spawn on a third-party host.
      session; consult the Claude CLI advisor and relay ENDORSE / CORRECTION /
      PLAN / STOP. When the CLI bind is unreachable, fail closed and report to
      the user — do not answer the four signals as this third-party session.
-3. **Resume before you spawn.** `SendMessage` an existing *executor* agent by
+4. **Resume before you spawn.** `SendMessage` an existing *executor* agent by
    name or `agentId` to reuse its warm context; prefer that over a cold spawn.
    (On a third-party host this is executor reuse only — advisor re-bind stays on the CLI
    chain path in the shared protocol.)
-4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
+5. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
    subagent's context, so a clean context comes from a fresh spawn — never tell
    an agent to compact.
 5. **Re-schedule the next refresh** (about 1200 seconds out) when the loop

package/system-prompts/CLAUDE.md

@@ -1,16 +1,16 @@
 # system-prompts
 
-System prompt files installed into `~/.claude/system-prompts/` by `bin/install.mjs`. Claude Code loads these as the base persona and behavioral protocol for a session.
+System-prompt reference files installed into `~/.claude/system-prompts/` by `bin/install.mjs`. Rules and skills pull a file (or one of its sections) into context on demand by citing its installed path.
 
 ## Files
 
 | File | Purpose |
 |---|---|
-| `software-engineer.xml` | Primary system prompt: defines the software engineering role, task-scope rules, output style, and the BDD `<behavior_protocol>` that rules in `rules/bdd.md` reference |
+| `software-engineer.xml` | Software-engineering reference: defines the engineering role, task-scope rules, output style, and the BDD `<behavior_protocol>` that `rules/bdd.md` cites on demand |
 
 ## Format
 
-Files use XML with named sections (`<role>`, `<task_scope>`, `<output_style>`, `<behavior_protocol>`, etc.). Claude Code injects the full file into the system prompt slot at session start.
+Files use XML with named sections (`<role>`, `<task_scope>`, `<output_style>`, `<behavior_protocol>`, etc.). A rule or skill cites a file, or one of its sections, to pull it into context when the task needs it.
 
 ## Adding a prompt
 

package/docs/agents-md-alignment-plan.md

@@ -1,123 +0,0 @@
-# AGENTS.md Alignment Plan
-
-This document captures the alignment between `AGENTS.md` (the canonical code-rules instruction set consumed by Cursor BugBot, Copilot, Claude, and other code-review/authoring agents) and the local enforcement layer (`code_rules_enforcer.py` and companion blocking hooks).
-
-## Goal
-
-Two-way alignment:
-
-1. Every rule the hooks enforce at write time is documented in `AGENTS.md` so review tools without hook access (Cursor BugBot, Copilot, external reviewers) flag the same violations from the diff alone.
-2. Every rule `AGENTS.md` requires is either (a) enforced by a hook at write time, (b) explicitly listed as bugbot-only judgment because it requires diff-semantic reasoning, or (c) a candidate for a future hook.
-
-This file is the single source of truth for the alignment status.
-
-## Methodology
-
-- Read every `check_*` function in `packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py` (28 functions, lines 108–2236) plus the `validate_content` dispatch (line 2239).
-- Read every Write/Edit hook registered in `packages/claude-dev-env/hooks/hooks.json`.
-- Read `packages/claude-dev-env/hooks/blocking/sensitive_file_protector.py` for file-level blocks.
-- Read every rule file in `~/.claude/rules/*.md` and the canonical CODE_RULES.md files in this repo.
-- Walked `AGENTS.md` bullet by bullet against the above.
-
-## What this PR changes
-
-### Added to `AGENTS.md`
-
-- Intro pointer to the new **Hook enforcement** appendix.
-- **Magic values & configuration**: explicit config-domain table (`config/timing.py` for timing values, `config/constants.py` for ports/URLs/thresholds, `config/selectors.py` for DOM locators) and a flag rule for new constants whose value or semantic name already exists in `config/`.
-- **Design**: tightened the YAGNI bullet to specify "every existing call site passes the same value → required (or inline)".
-- **Tests**: five new bullets — delete-no-value tests, fail-not-skip rule, pragmatic-infra five-point checklist, public-API-only assertions, React query priority and `userEvent`/API-boundary mocking.
-- **Platform and tooling**: the unsafe-`rmtree`-on-Windows pattern is blocked (with the canonical `force_rmtree` helper inlined), Node `mkdirSync` requires `{ recursive: true }` on possibly-existing paths, and all `gh` commands with markdown body content must use `--body-file`.
-- **Repo hygiene**: never-commit list (`docs/plans/*.md`, `*.plan.md`, `SESSION_STATE.md`, `*.audit.json`, `*.audit.md`, image extensions) and a scratch-file pattern enumeration.
-- **Hook enforcement** appendix mapping each hook-enforced rule to its enforcing hook file.
-
-### Deliberately excluded
-
-PR draft lifecycle bullets and one-commit-per-review-stage rules were proposed and then removed. Cursor BugBot reviews diffs and PR descriptions; it cannot toggle PR ready/draft state or enforce commit-stage discipline. Those rules belong in human-facing workflow documentation, not in `AGENTS.md`.
-
-## Open items
-
-The following are documented gaps. None are addressed in this PR.
-
-### Category A — enforced locally, not yet in AGENTS.md
-
-Each closure is concrete and additive — recommended for a follow-up PR titled `docs(agents): close remaining hook-vs-rule gaps`.
-
-| ID | Hook check (file:line) | Gap |
-|---|---|---|
-| A1 | `code_rules_enforcer.py:404` `check_windows_api_none` | `win32gui.X(.., None)` — use `0` for unused int params |
-| A2 | `code_rules_enforcer.py:603` `check_e2e_test_naming` | `online`/`offline` in `test()`/`it()`/`describe()` titles in `*.spec.*` files |
-| A3 | `code_rules_enforcer.py:713` `check_type_escape_hatches` | `# type: ignore` requires trailing `# <reason>` of ≥5 chars |
-| A4 | `code_rules_enforcer.py:2126` `check_inline_literal_collections` | inline `[...]` / `{...}` of constants in production function bodies |
-| A5 | `code_rules_enforcer.py:2085` `check_string_literal_magic` | bare string literals (not just f-string fragments) matching path / URL / regex shape |
-| A6 | `code_rules_enforcer.py:843` `check_constants_outside_config_advisory` | function-local `UPPER_SNAKE = ...` advisory |
-| A7 | `code_rules_enforcer.py:2003` `check_library_print` | `print()` outside CLI markers (`/scripts/`, `_cli.py`, `/cli.py`) |
-| A8 | `sensitive_file_protector.py` | edits to `package-lock.json`, `yarn.lock`, `Pipfile.lock`, `poetry.lock`, `pnpm-lock.yaml`, `composer.lock` |
-| A9 | `sensitive_file_protector.py` | edits to `.env*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `credentials.json`, `secrets.json`, `id_rsa`, `id_ed25519` |
-| A10 | `code_rules_enforcer.py:1175` `check_existence_check_tests` | `x is not None` as sole-assertion form (currently `AGENTS.md` lists only `callable` and `hasattr`) |
-| A11 | `code_rules_enforcer.py:1839` `check_unused_optional_parameters` | the exact trigger: optional param where every call site passes the same value |
-| A12 | `mypy_validator.py` | mypy-clean is required at write time |
-| A13 | `auto_formatter.py` | auto-formatter runs on Write/Edit |
-| A14 | `code_rules_enforcer.py:1072` `check_skip_decorators_in_tests` | the broader rule is "any decorator named `skip*`", not just `@skip_if_missing_dependency` |
-| A15 | `code_rules_enforcer.py:1786` `check_duplicated_format_patterns` | identical format-string patterns at multiple call sites |
-
-### Category B — required by AGENTS.md, no local hook (bugbot-only judgment)
-
-These are reviewable from a diff but not amenable to AST/regex enforcement; they remain bugbot's judgment.
-
-- **Naming**: `ctx`/`cfg`/`msg`/`btn`/`idx`/`cnt`/`elem`/`val`/`tmp` abbreviation expansion (B1); `X_by_Y` map naming (B2); preposition parameter prefixes (B3); banned function-name prefixes `handle_`/`process_`/`manage_`/`do_` (B4); component naming for what they ARE (B5).
-- **Structure**: function length ≤ 30 lines (B6); two blank lines between Python top-level functions (B7).
-- **Types**: concrete type captures actual shape, even when bare `object` would compile (B8).
-- **Architecture**: functions vs classes vs ABCs (B9); SOLID S/O/L/I/D (B10); construction logic in models/services (B11); self-contained components (B12); `TODO:` on scaffolding (B14).
-- **Data flow**: reuse data already in scope (B13); reuse-before-create semantic duplication (B23).
-- **Tests**: pragmatic-infra five-point checklist (B15); test through public API (B16); React query priority and mocking strategy (B17).
-- **Platform**: Node `mkdirSync({recursive: true})` (B18) — Python `shutil.rmtree` is hooked, Node equivalent is not.
-- **Hygiene**: planning/image file globs (B19); scratch-file patterns (B20); PR-description references for kept files (B21).
-- **Config**: domain placement within `config/` (B22); 0-reference dead-code constants (B24).
-
-### Category C — JS/TS asymmetry
-
-`code_rules_enforcer.py` `validate_content` (line 2239) dispatches on file extension. For `.js`/`.ts`/`.tsx`/`.jsx`, only three checks run:
-
-- `check_comment_changes` — added inline / removed existing comments.
-- `check_e2e_test_naming` — online/offline in spec test titles.
-- `advise_file_line_count` — advisory.
-
-Every other rule (magic values, constants location, banned identifiers, type annotations, boolean naming, loop variable naming, parameter annotations, return annotations, library print, optional-param-unused, `Any` detection) runs on Python files only. For JS/TS code, `AGENTS.md` is the only enforcement layer — bugbot review is the gate.
-
-Whether each Python check has a JS/TS equivalent that ports cleanly: not investigated. Out of scope for this PR.
-
-## Recommended hook additions
-
-Not part of this PR — proposed as separate small PRs (one new check + tests per PR, following the existing `test_code_rules_enforcer_*.py` pattern). Each is AST/regex-tractable.
-
-| Item | Suggested check | Note |
-|---|---|---|
-| B1 | extend `BANNED_IDENTIFIERS` | add `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp` |
-| B2 | dict-target naming rule | flag dict assignments whose target name lacks `_by_` |
-| B3 | parameter-name prefix rule | flag direction parameters lacking `from_`/`to_`/`into_` |
-| B4 | banned function-name prefixes | flag `def handle_*`, `def process_*`, `def manage_*`, `def do_*` |
-| B6 | function-length advisory | per-function line count, advisory above 30 |
-| B19 | extend `sensitive_file_protector.py` | block edits to `*.plan.md`, `SESSION_STATE.md`, `docs/plans/*.md`, `*.audit.{json,md}`, image extensions |
-| B20 | scratch-file name patterns | block edits to `scratch_*.py`, `debug_*.py`, `try_*.py`, `repro_*.py` |
-| B22 | config-domain placement | flag a constant added to `config/constants.py` whose name suggests `timing.py` or `selectors.py` |
-| B24 | 0-reference dead-code constants | extend `check_file_global_constants_use_count` to also flag 0 callers |
-
-## Files in this PR
-
-- `AGENTS.md` (modified) — adds the rules and sections listed above.
-- `packages/claude-dev-env/docs/agents-md-alignment-plan.md` (new) — this document.
-
-## Verification
-
-- Read updated `AGENTS.md` end-to-end and confirm each new bullet lives under the correct section heading.
-- Confirm no rule mentioned in the **Hook enforcement** appendix is missing its source check in `code_rules_enforcer.py` or sibling hook file.
-- Confirm the canonical `force_rmtree` helper code block in **Platform and tooling** describes the rule without containing the exact match-string the `windows_rmtree_blocker.py` hook scans for. Otherwise the hook will block any future edit to the file.
-- No code changes — the `AGENTS.md` and plan doc are documentation only.
-
-## Out of scope
-
-- Closing the Category A gaps in `AGENTS.md` (tracked above; recommended follow-up PR).
-- Implementing any of the Category B hook additions (each is its own small PR).
-- Investigating JS/TS hook coverage parity (Category C).
-- Changes to `code_rules_enforcer.py` or any other hook source file.