claude-dev-env 2.8.0 → 2.9.0

package/CLAUDE.md

@@ -12,7 +12,13 @@ A runtime value that is itself private — a host, an SSH user or port, an owner
 
 ## Advisors
 
-When the `advisor()` tool is available, read `~/.claude/docs/references/advisor-tool.md`. For complex tasks use the `/team-advisor` skill.
+| Path | Holds |
+|---|---|
+| `~/.claude/docs/references/advisor-tool.md` | When to call a stronger reviewer, hard rule before first write, how to treat advice |
+| `/team-advisor` skill | Standing warm advisor bind (map: `docs/references/team-advisor-skill.md`) |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, lifecycle |
+
+When `advisor()` is available, use it under the rules in `advisor-tool.md`. When `advisor()` is unavailable, use `/team-advisor`.
 
 ## Files and workspaces
 

package/agents/clean-coder.md

@@ -1,34 +1,24 @@
 ---
 name: clean-coder
-description: "Use PROACTIVELY for ALL code generation — feature development, bug fixes, refactoring, hook creation, automation scripts, and any task that produces code. Internalizes CODE_RULES.md and the 8-dimension readability standard so thoroughly that /check finds zero issues. The definitive code-writing agent."
+description: "Use PROACTIVELY for ALL code generation — feature development, bug fixes, refactoring, hook creation, automation scripts, and any task that produces code. Internalizes AGENTS.md (canonical) via the CODE_RULES.md projection and the 8-dimension readability standard so thoroughly that /check finds zero issues. The definitive code-writing agent."
 tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill, SendMessage
 color: green
 ---
 
 # Clean Coder — Zero-Defect Code Generation
 
-You are the definitive code-writing agent. You produce code so clean that reviewers find nothing. Every rule from CODE_RULES.md and every dimension from the readability rubric is internalized into your generation process. The goal: `/check` returns CLEAN on every file you touch.
+You are the definitive code-writing agent. You produce code so clean that reviewers find nothing. Canonical policy is repository-root `AGENTS.md`; `CODE_RULES.md` is its compact projection. Every dimension from the readability rubric is internalized into your generation process. The goal: `/check` returns CLEAN on every file you touch.
 
-**Announce at start:** "Using clean-coder agent — CODE_RULES.md internalized, targeting 160/160 readability."
+**Announce at start:** "Using clean-coder agent — AGENTS.md / CODE_RULES projection internalized, targeting 160/160 readability."
 
 ## First Action (MANDATORY)
 
-Before writing a single line:
+Before writing a single line — **task-local discovery only** (no project-wide preload):
 
 1. **Read project CLAUDE.md** (when one exists) — load project-specific rules, naming overrides, and any extended ruleset.
-2. **Glob for existing config files** using these patterns from the project root. Issue all seven Glob calls in parallel (single message, multiple tool calls — they have no dependencies on each other):
-   - `**/config/constants.py`
-   - `**/config/timing.py`
-   - `**/config/selectors.py`
-   - `**/config.py`
-   - `**/settings.py`
-   - `**/.env`
-   - `**/.env.*`
-3. **Read every config file the globs return.** Extract every `UPPER_SNAKE_CASE` binding into a local name → value table. Before writing any constant in the new code:
-   - Exact value match in the table → import the existing name.
-   - Semantic match → reuse the existing name.
-   - No match → add the constant to the appropriate `config/` file.
-4. **Read the file you are about to edit** (when editing existing code). Note every existing comment so you can leave each one untouched on lines that remain otherwise unchanged.
+2. **Read the file you are about to edit** (when editing existing code). Note every existing comment so you can leave each one untouched on lines that remain otherwise unchanged.
+3. **Discover config only next to the task files.** From each file you will write or edit, walk up to the nearest package or repo root and open only the config modules that package already uses for constants — typically `config/constants.py`, `config/timing.py`, `config/selectors.py`, or a sibling `*_constants` package. Do **not** glob the whole tree for every config file. Do **not** glob or open `.env`, `.env.*`, or other secret files.
+4. **Reuse constants from that local table.** Exact value match → import the existing name. Semantic match → reuse it. No match → add the constant to the appropriate `config/` file for that package.
 
 ## The 8 Generation Laws
 
@@ -171,7 +161,7 @@ Hooks under `~/.claude/hooks/` are standalone scripts; module-level `UPPER_SNAKE
 
 ### Reuse before create
 
-Search first. Import second. Create last. Before writing a constant, scan the name → value table built in First Action step 3.
+Search first. Import second. Create last. Before writing a constant, scan the name → value table built in First Action step 4.
 
 ### File-global constants use-count rule
 
@@ -422,7 +412,7 @@ When reading transcripts under the user projects directory, pass explicit file p
 
 Decision tree before writing any constant:
 
-1. Search the existing `config/` directory (using the table from First Action step 3).
+1. Search the existing `config/` directory (using the table from First Action step 4).
 2. Found exact value → **import it**.
 3. Found semantic match → **reuse the existing name**.
 4. Config file exists for this category → **add to the existing file**.

package/agents/test_agent_frontmatter.py

@@ -422,3 +422,29 @@ def test_agent_frontmatter_carries_no_model_key(
         "the caller supplies the model on every spawn, so agent definitions "
         "carry no model key at all, not even model: inherit"
     )
+
+
+def _clean_coder_body() -> str:
+    return (Path(__file__).parent / "clean-coder.md").read_text(encoding="utf-8")
+
+
+def test_clean_coder_never_globs_or_reads_dotenv_files() -> None:
+    body = _clean_coder_body()
+    assert "`**/.env`" not in body
+    assert "`**/.env.*`" not in body
+    assert "Never open `.env`" in body or "Do **not** glob or open `.env`" in body
+    assert re.search(r"(?i)glob.*\.env|\.env.*glob", body) is None or "Do **not** glob or open `.env`" in body
+
+
+def test_clean_coder_uses_task_local_config_discovery() -> None:
+    body = _clean_coder_body()
+    assert "task-local" in body.lower()
+    assert "project-wide preload" in body.lower() or "Do **not** glob the whole tree" in body
+    assert "Issue all five Glob calls" not in body
+    assert "Issue all seven Glob calls" not in body
+
+
+def test_clean_coder_examples_import_constants_from_config() -> None:
+    body = _clean_coder_body()
+    assert "from config.timing import MAXIMUM_RETRIES" in body
+    assert re.search(r"(?m)^MAXIMUM_RETRIES\s*=\s*\d+", body) is None

package/docs/CODE_RULES.md

@@ -1,6 +1,8 @@
 # Code Rules Reference
 
-Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.py` — the hook blocks the Write/Edit and returns the corrective detail at violation time, so this document lists those rules by name only.
+Compact **projection** of the repository-root canonical policy [`AGENTS.md`](../../../AGENTS.md). When this file and `AGENTS.md` disagree, **`AGENTS.md` wins** — update this projection in the same change.
+
+⚡ marks rules enforced by hand-maintained `code_rules_enforcer.py` — the hook blocks the Write/Edit and returns the corrective detail at violation time, so this document lists those rules by name only. Session policy (question routing, task tracking) lives in `rules/*.md`; see [`code-standards.md`](../rules/code-standards.md).
 
 ---
 
@@ -46,7 +48,7 @@ Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` fo
 
 ## 6. COMPLETE TYPE HINTS
 
-ALL parameters typed, ALL returns typed. No `Any`, no `# type: ignore` (also enforced by the mypy_validator.py hook).
+ALL parameters typed, ALL returns typed. No `Any`. A `# type: ignore` is allowed only with a second trailing `#` justification of at least five characters (e.g. `# type: ignore[misc]  # stubs missing in foo library`); bare ignores are blocked by `code_rules_enforcer.py`. Prefer fixing the type over an ignore when a real annotation is available.
 
 ## 6.5 FILE LENGTH GUIDANCE
 

package/docs/references/CLAUDE.md

@@ -8,8 +8,8 @@ Pointer documents to external sources, standard terminology, and internal tool o
 |---|---|
 | `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
 | `code-review-enforcement.md` | How the code-review gates work: the two required efforts (push at low, PR creation at xhigh), the stamp bound to the branch-surface hash, the single sanctioned minter, the two-layer stamp-directory guard, and the bypass surfaces the gates leave open |
-| `advisor-tool.md` | The `advisor()` tool: a no-parameter review call that forwards the full conversation history to a stronger reviewer model, and when to call it |
-| `team-advisor-skill.md` | The `/team-advisor` skill: spawning a standing review agent at the strongest reachable tier, and how it relates to the `advisor()` tool |
+| `advisor-tool.md` | Canonical consult bones for any stronger reviewer: when to call, hard rule before first write, how to treat advice; maps to the Anthropic advisor tool |
+| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and how it pairs with `advisor()` |
 
 ## Role
 

package/docs/references/advisor-tool.md

@@ -1,13 +1,51 @@
 # Advisor Tool
 
-`advisor()` is a review tool backed by a stronger reviewer model. It takes no parameters — calling it forwards the entire conversation history automatically, so the reviewer sees the task, every tool call made, and every result seen so far.
+Canonical consult timing and weight for any stronger-reviewer path: the native `advisor()` tool, `/team-advisor`, and the shared warm advisor.
 
-## When to call it
+Source bones: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) (Suggested system prompt for coding tasks). API shape, model pairs, cost, and caching live there. This file carries only the call rules a session needs every time.
 
-Call `advisor()` before substantive work: before writing, before committing to an interpretation, before building on an assumption. Orientation work — finding files, fetching a source, seeing what exists — comes first; call `advisor()` once that orientation is done and before the substantive step begins.
+## What it is
 
-Treat the advisor as more experienced than the calling agent. Consult it whenever a path forward is uncertain.
+`advisor()` is a no-parameter review call. The platform forwards the full conversation (task, tool calls, results) to a stronger model. The executor continues with that guidance.
 
-## Availability
+When `advisor()` is absent, use `/team-advisor` (see `team-advisor-skill.md`).
 
-`advisor()` is present only in environments where it has been configured as a tool. Check the available tools before relying on it; when it is absent, fall back to `/team-advisor` (see `team-advisor-skill.md` in this directory).
+## When to call
+
+Call **before substantive work** — before writing, before locking an interpretation, before building on an assumption.
+
+If the task needs orientation first (find files, fetch a source, see what exists), do that, then call. Orientation is not substantive work. Writing, editing, and declaring an answer are.
+
+Also call:
+
+- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not.
+- **When stuck** — errors recur, approach does not converge, results do not fit.
+- **When considering a change of approach.**
+
+On tasks longer than a few steps, call at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you do not need repeated calls — most value is on the first call, before the approach hardens.
+
+Call for design, architecture, and risk questions where you will not touch a file. If the response would be analysis or a recommendation with no other tool calls, call first. That judgment is where a second opinion is highest value. Simple factual lookups and arithmetic do not need a call.
+
+## Hard rule
+
+Your first write, edit, or state-changing shell call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation (`ls`, `cat`, `grep`, `find`, and harness equivalents) is not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.
+
+## How to treat advice
+
+Give the advice serious weight. If a step fails empirically, or primary-source evidence contradicts a claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it is evidence the test does not check what the advice is checking.
+
+If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" A reconcile call is cheaper than the wrong branch.
+
+## Brevity cue
+
+When the consult path supports a free-text brief, append:
+
+`(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)`
+
+## Related
+
+| Doc | Holds |
+|---|---|
+| [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | API shape, model pairs, cost, caching, full best practices |
+| `team-advisor-skill.md` | Standing warm advisor when `advisor()` is missing |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle, executor paste blocks |

package/docs/references/team-advisor-skill.md

@@ -1,14 +1,20 @@
-# Team-Advisor Skill Invocation
+# Team-Advisor Skill
 
-`/team-advisor` spawns a standing review agent for the session at the strongest reachable model tier, run at the highest reasoning effort. Use it to get a second opinion from a distinct model line than the one driving the session. For example:
+`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. Use it when `advisor()` is absent, or when you want a standing four-signal reviewer across many decision points.
 
-- Claude session -> consult Fable xhigh
-- Codex session -> consult Sol xhigh
+## Refs
 
-## When to use it
+| Doc | Holds |
+|---|---|
+| `skills/team-advisor/SKILL.md` | Sole-consumer bind wiring and constraints |
+| `advisor-tool.md` | Consult timing, hard rule, how to treat advice |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor, lifecycle |
+| `agents/session-advisor.md` | ENDORSE / CORRECTION / PLAN / STOP |
 
-Consult the spawned advisor before big decisions, before declaring work complete, before any commit, when a failure repeats, or when reconsidering a chosen approach.
+## When to use
 
-## Relationship to the advisor tool
+Follow the call rules in `advisor-tool.md` (orientation first, then consult before substantive work; durable deliverable before the completion consult; stuck or reapproach; long tasks twice).
 
-`/team-advisor` works standalone; it needs no `advisor()` tool present. When both are available (see `advisor-tool.md` in this directory), use `advisor()` for a fast, history-forwarding check before substantive work, and `/team-advisor` for a standing reviewer consulted at decision points.
+## Relation to `advisor()`
+
+`/team-advisor` works with no `advisor()` tool. When both exist: `advisor()` for a fast history-forwarded check; `/team-advisor` for a standing named reviewer consulted at the same cadence.

package/hooks/hooks_constants/code_rules_path_utils_constants.py

@@ -24,6 +24,7 @@ ALL_CONFIG_DIRECTORY_NAMES = frozenset(
         "usage_pause_constants",
         "prototype_scripts_constants",
         "codex_review_scripts_constants",
+        "e_code_review_scripts_constants",
         "dev_env_scripts_constants",
         "fresh_branch_scripts_constants",
     }

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.8.0",
+    "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/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

@@ -12,7 +12,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `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/dev_env_scripts_constants/CLAUDE.md

@@ -10,7 +10,7 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 | `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
 | `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, routing-mode tokens (`usage_ranked` / `ordered_account`), outcome `terminal_status` values (`served` / `advisor_blocked` / `chain_exhausted` / `timeout`), the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes (including advisor-blocked); `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
 | `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
-| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
+| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, worker-advisor placeholder launcher/model/effort tokens, four verdict signals, MAXIMUM_WORKER_ADVISOR_CORRECTIONS, advisor_blocked classification, and advisor_session_id report keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
 | `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers; finding severity tokens (`blocker` / `high` / `medium` / `low` / `nit`), verification verdict tokens, loop terminal tokens (`clean` / `nits_fixed` / `advisor_blocked`), and pure helpers for retained-finding checks, head recording, terminal resolution, and terminal encoding |
 | `__init__.py` | Empty package marker |
 

package/scripts/dev_env_scripts_constants/grok_run_ledger_constants.py

@@ -0,0 +1,50 @@
+"""Named constants for the host-neutral Grok run ledger and patch artifacts."""
+
+from __future__ import annotations
+
+LEDGER_SCHEMA_VERSION: str = "1.0.0"
+"""Schema version stamped on every ledger document and task record."""
+
+LEDGER_FILENAME: str = "grok-run-ledger.json"
+"""Default ledger filename under a run-state directory."""
+
+PATCH_MANIFEST_FILENAME: str = "patch-manifest.json"
+"""Default patch-manifest filename under a run-state directory."""
+
+TASK_STATUS_PENDING: str = "pending"
+"""Task is recorded and waiting for dispatch."""
+
+TASK_STATUS_IN_PROGRESS: str = "in_progress"
+"""Task has exactly one live owner and is being worked."""
+
+TASK_STATUS_COMPLETED: str = "completed"
+"""Task reached a successful terminal state."""
+
+TASK_STATUS_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Task stopped because the advisor bind or verdict failed closed."""
+
+TASK_STATUS_PENDING_REVIEW: str = "pending_review"
+"""Task was invalidated by snapshot drift and needs re-review."""
+
+ALL_LEGAL_TASK_STATUSES: frozenset[str] = frozenset(
+    {
+        TASK_STATUS_PENDING,
+        TASK_STATUS_IN_PROGRESS,
+        TASK_STATUS_COMPLETED,
+        TASK_STATUS_ADVISOR_BLOCKED,
+        TASK_STATUS_PENDING_REVIEW,
+    }
+)
+"""Every legal task status the ledger accepts."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for ledger and patch-manifest files."""
+
+JSON_INDENT: int = 2
+"""Indent width for pretty-printed ledger and patch-manifest JSON."""
+
+TEMPORARY_LEDGER_PREFIX: str = ".ledger-"
+"""Prefix for atomic ledger temp files before replace."""
+
+TEMPORARY_LEDGER_SUFFIX: str = ".tmp"
+"""Suffix for atomic ledger temp files before replace."""

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -503,3 +503,107 @@ CLI_ENABLE_CLAUDE_TIER_FLAG: str = "--enable-claude-tier"
 
 EMPTY_OUTPUT: str = ""
 """Empty captured output when no tier produced stdout."""
+
+BATCH_SPEC_ADVISOR_KEY: str = "advisor"
+"""JSON key for the optional batch-level worker-advisor block."""
+
+ADVISOR_SPEC_LAUNCHER_KEY: str = "launcher"
+"""JSON key for the lead-supplied advisor launcher executable name."""
+
+ADVISOR_SPEC_MODEL_KEY: str = "model"
+"""JSON key for the advisor model name."""
+
+ADVISOR_SPEC_EFFORT_KEY: str = "effort"
+"""JSON key for the advisor effort level."""
+
+DEFAULT_ADVISOR_LAUNCHER_PLACEHOLDER: str = "ADVISOR_LAUNCHER_PLACEHOLDER"
+"""Committed placeholder; real launcher arrives only from the lead's batch spec."""
+
+DEFAULT_ADVISOR_MODEL: str = "opus"
+"""Default advisor model when the batch advisor block omits model."""
+
+DEFAULT_ADVISOR_EFFORT: str = "high"
+"""Default advisor effort when the batch advisor block omits effort."""
+
+MAXIMUM_WORKER_ADVISOR_CORRECTIONS: int = 3
+"""Maximum CORRECTION/PLAN re-consults per worker before advisor_blocked."""
+
+MAXIMUM_ADVISOR_TIMEOUT_SECONDS: int = 600
+"""Timeout for one advisor launcher subprocess call, in seconds."""
+
+ADVISOR_SIGNAL_ENDORSE: str = "ENDORSE"
+"""Opening signal that accepts a worker report."""
+
+ADVISOR_SIGNAL_CORRECTION: str = "CORRECTION"
+"""Opening signal that requires a re-consult up to the correction cap."""
+
+ADVISOR_SIGNAL_PLAN: str = "PLAN"
+"""Opening signal treated like CORRECTION for re-consult counting."""
+
+ADVISOR_SIGNAL_STOP: str = "STOP"
+"""Opening signal that ends the worker as advisor_blocked immediately."""
+
+ALL_KNOWN_ADVISOR_SIGNALS: frozenset[str] = frozenset(
+    {
+        ADVISOR_SIGNAL_ENDORSE,
+        ADVISOR_SIGNAL_CORRECTION,
+        ADVISOR_SIGNAL_PLAN,
+        ADVISOR_SIGNAL_STOP,
+    }
+)
+"""The four allowed first tokens of an advisor reply."""
+
+CLASSIFICATION_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Worker classification when advisor bind, resume, or verdict fails closed."""
+
+PENDING_BIND_SENTINEL: str = "PENDING_BIND"
+"""Unbound advisor session or signal sentinel; must fail closed before launch."""
+
+ADVISOR_PROMPT_HEADER_TEMPLATE: str = (
+    "Worker advisor session: {session_id}\n"
+    "Advisor model: {model}\n"
+    "Advisor effort: {effort}\n"
+    "Report only after the same session endorses or corrections are applied.\n\n"
+)
+"""Prefix injected into each worker prompt after a successful pre-dispatch bind."""
+
+SUMMARY_ADVISOR_SESSION_ID_KEY: str = "advisor_session_id"
+"""Per-worker report JSON key for the unique advisor session id."""
+
+SUMMARY_ADVISOR_SIGNAL_KEY: str = "advisor_completion_signal"
+"""Per-worker report JSON key for the final advisor opening signal."""
+
+SUMMARY_ADVISOR_LAUNCHER_KEY: str = "advisor_launcher"
+"""Per-worker report JSON key for the spec-supplied launcher (runtime only)."""
+
+ADVISOR_CLI_PRINT_FLAG: str = "-p"
+"""Print/non-interactive flag passed to the advisor launcher."""
+
+ADVISOR_CLI_MODEL_FLAG: str = "--model"
+"""Model flag passed to the advisor launcher."""
+
+ADVISOR_CLI_EFFORT_FLAG: str = "--effort"
+"""Effort flag passed to the advisor launcher."""
+
+ADVISOR_CLI_OUTPUT_FORMAT_FLAG: str = "--output-format"
+"""Output-format flag passed to the advisor launcher."""
+
+ADVISOR_CLI_OUTPUT_FORMAT_JSON: str = "json"
+"""JSON output format value for advisor launcher calls."""
+
+ADVISOR_CLI_RESUME_FLAG: str = "--resume"
+"""Resume flag for post-report advisor consults."""
+
+ADVISOR_BIND_PROMPT_TEMPLATE: str = (
+    "You are the unique worker advisor for role {role_name}. "
+    "Answer only. Open with exactly one of: ENDORSE | CORRECTION | PLAN | STOP. "
+    "Pre-dispatch: ENDORSE this worker assignment if safe, else CORRECTION."
+)
+"""Prompt body used for the pre-dispatch advisor bind."""
+
+ADVISOR_VERDICT_PROMPT_TEMPLATE: str = (
+    "You are the unique worker advisor for role {role_name}, session {session_id}. "
+    "Answer only. Open with exactly one of: ENDORSE | CORRECTION | PLAN | STOP. "
+    "Post-report review of the worker report follows.\n\n{report_text}"
+)
+"""Prompt body used for the post-report advisor verdict."""