claude-dev-env 7.7.1 → 8.1.0

package/.agents/agents/clean-coder.md

@@ -22,7 +22,7 @@ Before writing a single line — **task-local discovery only** (no project-wide
 1. **Load scoped repository instructions first.** Starting at the repository root, read every applicable `AGENTS.md` on the path to the task file. Then read the applicable `CLAUDE.md` files. Apply nearer instructions after broader ones; the closest file wins.
 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 inspect the target package's existing constants layout — such as `config/` or a sibling `*_constants` package. Keep this task-local constants search. Do **not** force a generic `config/` layout. 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.** Reuse first: exact value match → import the existing name. Semantic match → reuse it. Add a shared constant only when the value is shared policy or has multiple consumers. When no match exists, use the target package's existing constants layout; a one-use value follows `file-global-constants` rather than becoming a new shared constant.
+4. **Reuse constants from that local table.** Reuse first: exact value match → import the existing name. Semantic match → reuse it. Add a shared constant only when the value is shared policy or has multiple consumers. When no match exists, use the target package's existing constants layout, and keep a one-use value in the scope that reads it rather than making it a new shared constant.
 5. **Search callers.** When a symbol, name, or signature changes, search its full caller boundary and update every consumer. This search may be wider than the constants search.
 
 ## Generation mindset (9 laws)
@@ -50,17 +50,16 @@ Installed paths use the active managed root and agents home resolved above; sour
 | Write-time gates | `<managed-root>/hooks/blocking/code_rules_enforcer.py` (source fallback: `packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py`) |
 | Naming and abbreviations | `<managed-root>/docs/CODE_RULES.md#5-no-abbreviations` (source fallback: `packages/claude-dev-env/docs/CODE_RULES.md#5-no-abbreviations`) |
 | Policy surface map | `<managed-root>/rules/code-standards.md` (source fallback: `packages/claude-dev-env/rules/code-standards.md`) |
-| File-global constants | `<managed-root>/rules/file-global-constants.md` (source fallback: `packages/claude-dev-env/rules/file-global-constants.md`) |
 | Windows rmtree / mkdir | `<managed-root>/rules/windows-filesystem-safe.md` (source fallback: `packages/claude-dev-env/rules/windows-filesystem-safe.md`) |
 | `gh` body files | `<managed-root>/rules/gh-cli-conventions.md` (source fallback: `packages/claude-dev-env/rules/gh-cli-conventions.md`) |
 | Plain illustrative docstrings | `<managed-root>/rules/plain-illustrative-docstrings.md` (source fallback: `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`) |
 | Tests / TDD | `<managed-root>/rules/testing.md` (source fallback: `packages/claude-dev-env/rules/testing.md`), `<managed-root>/rules/paired-test-coverage.md` (source fallback: `packages/claude-dev-env/rules/paired-test-coverage.md`), `<managed-root>/rules/bdd.md` (source fallback: `packages/claude-dev-env/rules/bdd.md`) |
-| Questions / task tracking | `<managed-root>/rules/ask-user-question-required.md` (source fallback: `packages/claude-dev-env/rules/ask-user-question-required.md`), `<managed-root>/rules/verify-before-asking.md` (source fallback: `packages/claude-dev-env/rules/verify-before-asking.md`) |
+| Questions / task tracking | `<managed-root>/rules/verify-before-asking.md` (source fallback: `packages/claude-dev-env/rules/verify-before-asking.md`) |
 | Runtime evidence | `<managed-root>/rules/verify-runtime-state.md` (source fallback: `packages/claude-dev-env/rules/verify-runtime-state.md`) |
 | Documentation / durable artifacts | `<managed-root>/rules/doc-inventory-integrity.md` (source fallback: `packages/claude-dev-env/rules/doc-inventory-integrity.md`), `<managed-root>/rules/durable-post-artifacts.md` (source fallback: `packages/claude-dev-env/rules/durable-post-artifacts.md`) |
 | Batch / failure blast radius | `<managed-root>/rules/failure-blast-radius.md` (source fallback: `packages/claude-dev-env/rules/failure-blast-radius.md`) |
 | Git / GitHub | `<managed-root>/rules/git-workflow.md` (source fallback: `packages/claude-dev-env/rules/git-workflow.md`), `<managed-root>/rules/gh-cli-conventions.md` (source fallback: `packages/claude-dev-env/rules/gh-cli-conventions.md`), `<managed-root>/rules/re-stage-before-commit.md` (source fallback: `packages/claude-dev-env/rules/re-stage-before-commit.md`) |
-| Workers / completion | `<managed-root>/rules/agent-spawn-protocol.md` (source fallback: `packages/claude-dev-env/rules/agent-spawn-protocol.md`), `<managed-root>/rules/workers-done-before-complete.md` (source fallback: `packages/claude-dev-env/rules/workers-done-before-complete.md`) |
+| Workers / completion | `<managed-root>/rules/workers-done-before-complete.md` (source fallback: `packages/claude-dev-env/rules/workers-done-before-complete.md`) |
 | TDD / right-size | Review contract Tests + Design; `CODE_RULES.md` §7–§8 |
 
 ## Session policy map (canonical links)
@@ -70,13 +69,13 @@ Load only the group that matches the task. Keep session policy details in these
 | Group | Canonical refs |
 |---|---|
 | Tests | `<managed-root>/rules/testing.md` (source fallback: `packages/claude-dev-env/rules/testing.md`); `<managed-root>/rules/anti-corollary-tests.md` (source fallback: `packages/claude-dev-env/rules/anti-corollary-tests.md`) |
-| Questions | `<managed-root>/rules/ask-user-question-required.md` (source fallback: `packages/claude-dev-env/rules/ask-user-question-required.md`); `<managed-root>/rules/verify-before-asking.md` (source fallback: `packages/claude-dev-env/rules/verify-before-asking.md`) |
+| Questions | `<managed-root>/rules/verify-before-asking.md` (source fallback: `packages/claude-dev-env/rules/verify-before-asking.md`) |
 | Search and shell | `<managed-root>/rules/filesystem-search.md` (source fallback: `packages/claude-dev-env/rules/filesystem-search.md`); `<managed-root>/rules/shell-invocation.md` (source fallback: `packages/claude-dev-env/rules/shell-invocation.md`) |
 | Runtime checks | `<managed-root>/rules/verify-runtime-state.md` (source fallback: `packages/claude-dev-env/rules/verify-runtime-state.md`) |
 | Documentation | `<managed-root>/rules/doc-inventory-integrity.md` (source fallback: `packages/claude-dev-env/rules/doc-inventory-integrity.md`); `<managed-root>/rules/docstring-prose-matches-implementation.md` (source fallback: `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`) |
 | Batch failures | `<managed-root>/rules/failure-blast-radius.md` (source fallback: `packages/claude-dev-env/rules/failure-blast-radius.md`) |
 | Git | `<managed-root>/rules/git-workflow.md` (source fallback: `packages/claude-dev-env/rules/git-workflow.md`); `<managed-root>/rules/re-stage-before-commit.md` (source fallback: `packages/claude-dev-env/rules/re-stage-before-commit.md`) |
-| Worker coordination | `<managed-root>/rules/agent-spawn-protocol.md` (source fallback: `packages/claude-dev-env/rules/agent-spawn-protocol.md`); `<managed-root>/rules/workers-done-before-complete.md` (source fallback: `packages/claude-dev-env/rules/workers-done-before-complete.md`) |
+| Worker coordination | `<managed-root>/rules/workers-done-before-complete.md` (source fallback: `packages/claude-dev-env/rules/workers-done-before-complete.md`) |
 
 Material implementation questions must return to the caller for `AskUserQuestion` handling; do not ask in plain text or guess.
 

package/.agents/agents/issue-tracker.md

@@ -19,7 +19,7 @@ Keep the same warm `issue-tracker` agent for follow-up actions on the **same iss
 
 ## Voice
 
-Use the `plain-brief` output style (`output-styles/plain-brief.md`). Final message is issue number(s) and URL(s) only.
+Keep the final message to the issue number(s) and URL(s) only.
 
 ## On each turn
 

package/.agents/agents/pr-description-writer.md

@@ -1,6 +1,6 @@
 ---
 name: pr-description-writer
-description: "Writes factual pull request titles, descriptions, and comments in plain illustrative language from the current diff. The `pr_description_writer_gate` PreToolUse hook requires a spawn of this agent before `gh pr create`."
+description: "Writes factual pull request titles, descriptions, and comments in plain illustrative language from the current diff. Spawn it when a pull request needs a body written from the diff or rewritten in full."
 tools: Read,Grep,Glob,Bash
 ---
 

package/.agents/agents/skill-writer-agent.md

@@ -30,18 +30,7 @@ A caller may bundle three of these fields — `Composition plan`, `Description`,
 
 A refine packet instead carries: the current SKILL.md, what was observed, what to change, new gotchas to add, what to preserve, a description rewrite, a composition change, and a deterministic fix.
 
-**Direct request.** A looser prompt names the skill to build or the file to edit. Fill the packet yourself from the references below, and ask the caller for any field only they hold, such as domain context or constraints.
-
-## Read first
-
-At the start of every job, read the live references at `~/.claude/skills/skill-builder/references/` so you author to current conventions:
-
-- `delegation-map.md` — the handoff packet and the Produce contract.
-- `deterministic-elements.md` — the rule that deterministic work ships as code, artifacts, or session tasks.
-- `description-field.md` — the trigger-catalog description shape.
-- `skill-modularity.md` — hub layout and compose-by-name.
-
-Read them fresh each run; they carry the rules you author to.
+**Direct request.** A looser prompt names the skill to build or the file to edit. Fill the packet yourself from the standards below, and ask the caller for any field only they hold, such as domain context or constraints.
 
 ## Standards every file meets
 

package/.agents/agents/test_agent_frontmatter.py

@@ -13,14 +13,14 @@ model on every spawn, so no agent definition names one, concrete or
 `inherit`::
 
     ok:   <no model key at all>
-    flag: model: inherit    <- caller can no longer choose the model
+    flag: model: inherit    <- caller cannot choose the model
     flag: model: opus       <- pinned concrete model, caller can't override
 
 Every block must also load through `yaml.safe_load`. An unquoted colon inside
 a plain scalar reads as a mapping key and makes the whole block unloadable::
 
     ok:   description: ... constraints. Examples are below.
-    flag: description: ... constraints. Examples:   <- block no longer loads
+    flag: description: ... constraints. Examples:   <- block does not load
 
 Two parsers read these files, and a block that satisfies one can still be
 unreadable by the other. `scripts/codex_compat_materializer.py` loads the
@@ -445,10 +445,6 @@ EXPECTED_SOURCE_LINK_PAIRS = {
             "<managed-root>/rules/code-standards.md",
             "packages/claude-dev-env/rules/code-standards.md",
         ),
-        (
-            "<managed-root>/rules/file-global-constants.md",
-            "packages/claude-dev-env/rules/file-global-constants.md",
-        ),
         (
             "<managed-root>/rules/windows-filesystem-safe.md",
             "packages/claude-dev-env/rules/windows-filesystem-safe.md",
@@ -477,10 +473,6 @@ EXPECTED_SOURCE_LINK_PAIRS = {
             "<managed-root>/rules/bdd.md",
             "packages/claude-dev-env/rules/bdd.md",
         ),
-        (
-            "<managed-root>/rules/ask-user-question-required.md",
-            "packages/claude-dev-env/rules/ask-user-question-required.md",
-        ),
         (
             "<managed-root>/rules/verify-before-asking.md",
             "packages/claude-dev-env/rules/verify-before-asking.md",
@@ -521,10 +513,6 @@ EXPECTED_SOURCE_LINK_PAIRS = {
             "<managed-root>/rules/re-stage-before-commit.md",
             "packages/claude-dev-env/rules/re-stage-before-commit.md",
         ),
-        (
-            "<managed-root>/rules/agent-spawn-protocol.md",
-            "packages/claude-dev-env/rules/agent-spawn-protocol.md",
-        ),
         (
             "<managed-root>/rules/workers-done-before-complete.md",
             "packages/claude-dev-env/rules/workers-done-before-complete.md",
@@ -797,7 +785,6 @@ def test_clean_coder_links_canonical_policy_areas() -> None:
     required_links = (
         "<managed-root>/docs/CODE_RULES.md#5-no-abbreviations",
         "<managed-root>/rules/testing.md",
-        "<managed-root>/rules/ask-user-question-required.md",
         "<managed-root>/rules/verify-runtime-state.md",
         "<managed-root>/rules/doc-inventory-integrity.md",
         "<managed-root>/rules/failure-blast-radius.md",
@@ -992,7 +979,6 @@ def test_clean_coder_follows_target_package_constant_layouts() -> None:
     assert "Reuse first" in body
     assert "shared policy" in body
     assert "multiple consumers" in body
-    assert "file-global-constants" in body
     assert "add the constant to the appropriate config file" not in body
 
 
@@ -1029,7 +1015,6 @@ def test_clean_coder_groups_session_policy_references() -> None:
         "Worker coordination",
     ):
         assert each_policy_group in body
-    assert "ask-user-question-required.md" in body
     assert "workers-done-before-complete.md" in body
     assert "verify-runtime-state.md" in body
     assert "Material implementation questions must return to the caller" in body
@@ -1039,7 +1024,6 @@ def test_clean_coder_groups_session_policy_references() -> None:
     expected_session_policy_files = (
         "testing.md",
         "anti-corollary-tests.md",
-        "ask-user-question-required.md",
         "verify-before-asking.md",
         "filesystem-search.md",
         "shell-invocation.md",
@@ -1049,7 +1033,6 @@ def test_clean_coder_groups_session_policy_references() -> None:
         "failure-blast-radius.md",
         "git-workflow.md",
         "re-stage-before-commit.md",
-        "agent-spawn-protocol.md",
         "workers-done-before-complete.md",
     )
     session_policy_map = body[body.index("## Session policy map") :]

package/.agents/skills/issue-tracker/SKILL.md

@@ -21,7 +21,7 @@ Prefer the **same warm** `issue-tracker` agent for follow-ups on the same issue
 
 ## Voice
 
-Use the `plain-brief` output style (`output-styles/plain-brief.md`). End with the issue number(s) and URL(s) the caller must keep.
+End with the issue number(s) and URL(s) the caller must keep, and nothing else.
 
 ## Gotchas
 

package/.agents/skills/orchestrator/SKILL.md

@@ -36,9 +36,8 @@ verification reads.
 ## status_gate (deterministic — not optional)
 
 **Prose does not keep the loop alive.** Re-arm and terminate are gated by
-`scripts/status_gate.py` (and, on Claude, the PreToolUse hook
-`orchestrator_refresh_reschedule_gate`). The gate is host-agnostic: a
-single pending re-arm latch in the status file, not host product names.
+`scripts/status_gate.py`. The gate is host-agnostic: a single pending re-arm
+latch in the status file, not host product names.
 
 ```
 python scripts/status_gate.py set --status active|done [--run-slug SLUG] [--status-file PATH]
@@ -158,8 +157,8 @@ in the repo the run works on (working files, not committed):
 - **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.
+  and every ticket for that task reuses it, so each spawn starts from
+  the same named files, constraints, and acceptance check.
 - **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.

package/.agents/skills/pull-request/SKILL.md

@@ -73,7 +73,7 @@ current process environment.
 
 | Skill | When | Produces | If missing |
 |---|---|---|---|
-| `pr-description-writer` | Before create or a full body rewrite | A reviewed title and body file | Stop the create or rewrite and report that authoring is required |
+| `pr-description-writer` | Create or a full body rewrite, when you want the body drafted for you | A reviewed title and body file | Write the title and body yourself |
 | `privacy-hygiene` | Before any durable GitHub post | A clean body and repository privacy sweep | Stop before publication and report the missing gate |
 | `issue-tracker` | Issue create, edit, or comment requests | Issue state and issue URLs | Route the request there. |
 | `e-code-review` | Review or review/fix loop requests | Structured findings or a clean review result | Route the request there. |
@@ -97,10 +97,10 @@ request target. Create actions publish drafts. Record the target before any writ
 
 ### 2. Author the title and body
 
-For create and full body rewrite, invoke the installed
-`pr-description-writer`. Require its title and body file as the authoring
-output. A comment or review may use a supplied body file when it does not
-rewrite the pull request description.
+For create and full body rewrite, write the title and a body file, or invoke
+the installed `pr-description-writer` to draft them from the diff. A comment or
+review may use a supplied body file when it does not rewrite the pull request
+description.
 
 ### 3. Run the local linter
 
@@ -122,8 +122,9 @@ permanent URLs. Rerun the linter after changing the body.
 
 ### 5. Resolve the process-local author
 
-Run `.agents/skills/pull-request/scripts/pull_request.py` with one structured
-action and the selected author. The command runs the linter again, resolves
+Run `~/.agents/skills/pull-request/scripts/pull_request.py` (under the agents
+home, not the repository; a worktree holds no `.agents/` copy) with one
+structured action and the selected author. The command runs the linter again, resolves
 the author value, and passes it only to the child `gh` process. It never
 changes the parent environment or calls `gh auth switch`.
 

package/.agents/skills/pull-request/reference/publication-tasks.md

@@ -6,7 +6,7 @@ reason when the task is conditional. This file is a task seed catalog, not a
 markdown progress board.
 
 1. Resolve one repository, action, and selected author. For create, resolve the source branch, base, and head. For other actions, resolve one existing pull request target. Create actions publish drafts.
-2. Invoke the required `pr-description-writer` for create or full body rewrite, then record its title and body file. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
+2. Record the title and body file for create or full body rewrite, written by you or drafted by `pr-description-writer`. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
 3. Validate every title, body, artifact, and local path input. Reject inline body input.
 4. Resolve the active managed root and run `<managed-root>/scripts/durable_post_lint.py` for the matching action. Record exit code `0` before credential lookup or network work.
 5. Run `privacy-hygiene` before the GitHub post and record its clean result.

package/.agents/skills/team-advisor/SKILL.md

@@ -26,9 +26,8 @@ One warm advisor at the strongest tier this session can reach. This session is t
 1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
 2. Claude: Fable first in-session at `ADVISOR_EFFORT` (default low). When Fable is out of usage, bind Astra at the same effort. Codex: Astra in-session. Third-party: headless Fable then Astra. When the host's walk fails, fail closed.
 3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); a native Astra subagent on Codex; one CLI `session_id` on a third-party host via the protocol Claude-chain or Astra helper.
-4. A Fable-tier spawn or re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt (protocol warm-up; `fable_spawn_gate` requires it).
-5. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
-6. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
+4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
+5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
 **GOTCHA (Cursor / ThirdParty + Astra):** when the walk reaches Astra or the user asks for Astra, first tool call is `python ~/.claude/_shared/advisor/scripts/codex_astra_advisor.py --bind --enable-astra --cwd <repo-root>` with the charter on stdin. Do not use Agent or Task. Do not search for a probe path. Details: [`third-party-bind.md`](../../_shared/advisor/reference/third-party-bind.md) GOTCHA and [`astra-rung.md`](../../_shared/advisor/reference/astra-rung.md).
 

package/_shared/advisor/advisor-protocol.md

@@ -104,7 +104,6 @@ The validator checks ladder shape only; host policy sits on top.
 ## Warm-up (once per session)
 
 On a **Claude host**, spawn `session-advisor` at the Fable alias with the charter as its prompt. When Fable is out of usage and the Astra rung is open, bind Astra through the Codex helper instead.
-A **Fable**-tier try carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt. `hooks/blocking/fable_spawn_gate.py` denies a Fable-tier spawn without it.
 Full spawn fields and the charter template: [`reference/warm-up.md`](reference/warm-up.md).
 
 On a **Codex host**, spawn a native in-session Astra subagent with the same charter. Bind fields: [`reference/identity.md`](reference/identity.md) and [`reference/warm-up.md`](reference/warm-up.md).

package/_shared/advisor/reference/lifecycle.md

@@ -10,7 +10,6 @@ Every other consumer (executors, or any other consulting session) reaches it by
 One shared advisor exists per orchestrated session, owned by the session that spawned it.
 
 **Re-spawn on drift.** If a reply shows the agent working from a stale picture, or the session pivots to an unrelated task, the owning session ends that agent and spawns a fresh one with a new charter.
-A **Fable**-tier re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in that fresh prompt, as a Fable-tier warm-up try does.
 
 ## Codex host
 

package/_shared/advisor/reference/warm-up.md

@@ -11,14 +11,13 @@ The consuming skill's session tries Fable first. Spawn with:
 - `model`: the short alias via `resolve_cli_model_id("Fable")` (alias table: [`cli-chain.md`](cli-chain.md)): `fable`. When Fable is out of usage and the Astra rung is open, continue with the Codex helper in [`astra-rung.md`](astra-rung.md) as the Astra fallback.
 - `name`: a name the session and every consumer will use to reach it (e.g. `team-advisor-agent`).
 - `run_in_background: true`.
-- `prompt`: the charter below. A **Fable**-tier try carries the exact token `FABLE-SPAWN-AUTHORIZED` in that prompt. `hooks/blocking/fable_spawn_gate.py` denies every `Agent` or `Task` spawn at `model: fable` whose prompt lacks that token. A try at any other tier needs no token.
+- `prompt`: the charter below.
 
 Stop at the first successful bind. That try's tier is `selected_tier`; the warm advisor lives at that tier for the rest of the session.
 
 ## Charter (the spawn prompt)
 
 The charter states the agent's role, the repo path, and the session's current goal in two or three sentences. The agent is a standing reviewer. It answers only via SendMessage. File edits and commands are out of its scope.
-On a Fable-tier try, include the exact token `FABLE-SPAWN-AUTHORIZED` as plain text in this prompt (substring match; the gate reads the token alone, wherever it came from).
 State plainly:
 
 - Every consult carries: who is asking (name and assignment), what changed since their last consult, the live decision or question, and any load-bearing paths or excerpts.

package/audit-rubrics/audit-categories.json

@@ -389,10 +389,6 @@
           "id": "J3",
           "axis_name": "Constants location"
         },
-        {
-          "id": "J4",
-          "axis_name": "File-global use-count"
-        },
         {
           "id": "J5",
           "axis_name": "Abbreviations"

package/audit-rubrics/category_rubrics/category-e-dead-code.md

@@ -26,7 +26,7 @@
 | E6 | Removed-but-not-deleted symbol references | Symbols renamed/removed elsewhere with stale import or call sites left behind. |
 | E7 | Test fixtures / helpers defined but never used | Pytest fixtures, test data builders, mock factories with no callers. |
 | E8 | Stub / placeholder code without tracking | Judge `pass`, `...`, and `raise NotImplementedError` directly; track follow-up work outside source code. |
-| E9 | Constants-module exports with no importer | A module-level `UPPER_SNAKE` constant added to a `*_constants.py` / `config/` module that no module in the repo imports and that the constants file itself never references. The file-global use-count gate exempts a constants module because every name it exports legitimately carries zero in-file references, so a genuinely dead export slips past the write-time gate. Distinguish dead from live by grepping the whole repo for each constant name: a sibling such as `MEDIUM_TERMINAL` imported by a consumer module is live; a `MEDIUM_TEXT` that no `from ... import` line and no in-file reference names is dead (CODE_RULES 9.8). Remove the dead export. |
+| E9 | Constants-module exports with no importer | A module-level `UPPER_SNAKE` constant added to a `*_constants.py` / `config/` module that no module in the repo imports and that the constants file itself never references. No write-time check reads a constants module, and every name such a module exports carries zero in-file references by design, so a dead export reaches the audit untouched. Distinguish dead from live by grepping the whole repo for each constant name: a sibling such as `MEDIUM_TERMINAL` imported by a consumer module is live; a `MEDIUM_TEXT` that no `from ... import` line and no in-file reference names is dead (CODE_RULES 9.8). Remove the dead export. |
 
 ---
 

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -5,7 +5,7 @@
 **Examples of Category J findings:**
 - A literal `60` appears in a production function body (magic value rule).
 - A new `MAX_RETRIES = 3` declared at module scope outside `config/`.
-- A parameter named `ctx` instead of `context` (abbreviation rule).
+- A parameter named `ctx` where the name `context` belongs (abbreviation rule).
 - A function that returns a value with no return-type annotation.
 - A new `# explains the loop logic` comment added to production code.
 
@@ -20,7 +20,6 @@
 | J1 | Magic values in production function bodies | Literals other than `0`, `1`, `-1` inside production function bodies. Test files exempt. |
 | J2 | String-template magic | f-strings whose structural literal text (paths, URLs, patterns) belongs in `config/`. |
 | J3 | Constants location | Module-level `UPPER_SNAKE = ...` outside `config/` in production code. Exempt path families: `config/*`, `/migrations/`, `/workflow/`, `_tab.py`, `/states.py`, `/modules.py`, test files. |
-| J4 | File-global use-count | A file-global constant referenced by fewer than two methods/functions/classes in the same file. |
 | J5 | Abbreviations | `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. (Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.) |
 | J6 | Vague names | `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague prefixes: `handle`, `process`, `manage`, `do`. |
 | J7 | Type hints | Missing type annotation on a parameter or return; presence of `Any` or `# type: ignore`. |

package/audit-rubrics/prompts/category-e-dead-code.md

@@ -26,7 +26,7 @@ Inline the artifact under this section using the section types defined in the ch
 
 **E2. Functions / methods defined but never called**
 - For every function, method, or callable defined or modified by the artifact, enumerate call sites: direct calls, callback registrations (`onerror=`, `key=`, signal handlers), decorator applications, `__main__` guards, framework-driven discovery (pytest collection, Django URL resolution, FastAPI route decorators, Click groups), and string-form references resolved at runtime (`getattr`, dispatch tables).
-- Leading-underscore names: a single internal call site is sufficient; explicitly verify nothing outside the file imports the underscore-prefixed name.
+- Leading-underscore names: a single internal call site is enough; explicitly verify nothing outside the file imports the underscore-prefixed name.
 - Public names: confirm at least one call site inside or outside the file, or confirm the function is part of a documented public API.
 - Framework-discovered callables (test functions, route handlers, CLI commands): state which collector picks them up and confirm the artifact's path matches that collector's pattern.
 
@@ -59,7 +59,7 @@ Inline the artifact under this section using the section types defined in the ch
 
 **E7. Test fixtures / helpers defined but never used**
 - For every test file in scope, enumerate `@pytest.fixture`, `@pytest.fixture(scope=...)`, `setUp` / `tearDown` methods, factory helpers, mock builders, and module-level test constants. Verify each has at least one consumer test.
-- Module-level constants in test files: each must satisfy the file-global-constants use-count rule (≥2 references) OR be referenced by exactly one test plus one helper that the tests call.
+- Module-level constants in test files: each must be referenced by at least two callers, OR by exactly one test plus one helper that the tests call.
 - Helpers defined inside a single test body that are never called within that body are dead.
 - Adversarial probes for proof-of-absence: (a) any test that defines a local helper (e.g., `def make_dir(...):`) and never calls it? (b) any imported test name from the production module that no test exercises? (c) any module-level constant whose call graph collapses to zero references after the diff?
 
@@ -71,7 +71,7 @@ Inline the artifact under this section using the section types defined in the ch
 
 **E9. Constants-module exports with no importer**
 - For every module-level `UPPER_SNAKE` constant the artifact adds to a `*_constants.py` or `config/` module, grep the whole repo for the constant name and locate at least one importer (`from <module> import <NAME>`) or in-file reference.
-- The file-global use-count gate exempts a constants module because every name it exports carries zero in-file references by design, so a genuinely dead export slips past the write-time gate; this sub-bucket is the audit-time backstop for that exemption.
+- Every name a constants module exports carries zero in-file references by design and no write-time check reads such a module, so a dead export reaches the audit untouched; this sub-bucket is the audit-time backstop.
 - A sibling that a consumer module imports is live; a constant that no `from ... import` line and no in-file reference names anywhere in the repo is dead and must be removed (CODE_RULES 9.8).
 - Constants reached only by string-form lookup (`getattr(config, name)`, settings registries) are live; name the dynamic consumer when you mark such a constant referenced.
 - Adversarial probes for proof-of-absence: (a) does the artifact add any constant to a `*_constants.py` / `config/` module whose name returns zero hits outside its own definition line? (b) is any newly added constant shadowed by a same-named constant in a sibling module so the importer resolves the other one? (c) does any constant exist only as an `__all__` re-export with no downstream importer of that re-export?
@@ -156,7 +156,7 @@ ID prefix: `find`.
 **E7. Test fixtures / helpers defined but never used**
 - `test_sweep_empty_dirs.py` defines no `@pytest.fixture` decorators. Nothing to flag under "fixture with no consumers".
 - `_set_creation_time_windows` is the only test helper; it has three call sites (E2 above). Used.
-- `_SCRIPTS_DIR` (line 12) is a module-level constant used at line 13 (`if str(_SCRIPTS_DIR) not in sys.path:`) and line 14 (`sys.path.insert(0, str(_SCRIPTS_DIR))`). Two references; satisfies the file-global-constants use-count rule.
+- `_SCRIPTS_DIR` (line 12) is a module-level constant used at line 13 (`if str(_SCRIPTS_DIR) not in sys.path:`) and line 14 (`sys.path.insert(0, str(_SCRIPTS_DIR))`). Two references; the constant earns its module scope.
 - No test data builders or mock factories are defined in this PR.
 - Adversarial probes for proof-of-absence: (a) does any of the five tests define a local helper inside its body that is then never called? (e.g., a `def make_dir(...):` defined but unused) — scan each test body. (b) does any test import a name from `sweep_empty_dirs` that it never uses? — only `sweep` is imported, and every test calls it. (c) does the `_SCRIPTS_DIR` block survive if pytest is invoked with `sweep_empty_dirs.py` already on `sys.path`? — yes, the membership-test guards the insert, so the constant is still meaningfully consumed even on the second run.
 
@@ -178,7 +178,7 @@ ID prefix: `find`.
 
 Q1: Are there imports unused locally but consumed by a re-export pattern in another file? Cite the cross-file pair if found. (Hypothesis: none — neither `sweep_empty_dirs.py` nor `test_sweep_empty_dirs.py` defines `__all__`, so re-export is not in play. `config/sweep_config.py` declares two constants that ARE consumed by `sweep_empty_dirs.py` lines 10-11; this is normal cross-file consumption, not a re-export.)
 Q2: What's the worst unused-code hazard introduced by this PR? Cite `<file>:<line>`. Candidates to evaluate: `arguments.interval` is parsed but unreachable on the `--once` path (line 57 short-circuits before the watch loop at line 67); the scheduled task always uses `--once`, so the `--interval` argparse declaration at line 45 is dead code on the only invocation path the installer creates. Decide: P2 (style) because the manual watch-mode path still uses it, vs P1 if you treat "the only installer path never exercises this branch" as functionally dead.
-Q3: Which symbol most likely will *become* dead code after a near-future refactor? Candidates: `_log_walk_error` (sole call site is the `os.walk(..., onerror=...)` kwarg — if a future refactor switches to `pathlib.Path.rglob` for walking, this helper has no other consumer and silently becomes orphaned); `DEFAULT_POLL_INTERVAL` (sole consumer is `_build_parser`'s `--interval` default — if Q2's hazard is resolved by removing `--interval` from the `--once`-only installer flow, this constant has zero consumers in the script and the file-global-constants use-count rule is broken).
+Q3: Which symbol most likely will *become* dead code after a near-future refactor? Candidates: `_log_walk_error` (sole call site is the `os.walk(..., onerror=...)` kwarg — if a future refactor switches to `pathlib.Path.rglob` for walking, this helper has no other consumer and silently becomes orphaned); `DEFAULT_POLL_INTERVAL` (sole consumer is `_build_parser`'s `--interval` default — if Q2's hazard is resolved by removing `--interval` from the `--once`-only installer flow, this constant has zero consumers in the script).
 
 ## Output
 

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -50,11 +50,6 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 - Distinguish *imports* (`from config.X import FOO`) from *declarations* — imports are not J3-scope.
 - Adversarial probes: (a) does any module-level constant masquerade as an "import" via a re-export pattern? (b) is there a `_PRIVATE_UPPER` declaration that escapes the visual UPPER_SNAKE filter but is still module-level? (c) does any test file declare a constant that *would* be flagged if it were in production, indicating the constant probably belongs in `config/` even if test-exempt?
 
-**J4. File-global use-count**
-- For every file-global constant outside `config/`, count references in the same file. Single ref → move to `config/`. Zero refs → delete.
-- The rule applies to *constants*, not functions, classes, or imports.
-- Adversarial probes: (a) is any imported constant referenced only once in the importing file (suggesting the import itself is gratuitous)? (b) is any helper function defined in a production file but never called from inside the same file (separate dead-code concern, surfaced here for completeness)? (c) does any constant in `config/` get imported from zero call sites across the repo?
-
 **J5. Abbreviations**
 - Walk every parameter, local, and attribute name across production, test, and JavaScript changed lines. Flag: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.
 - This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
@@ -101,7 +96,7 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 
 ## Cross-bucket questions to answer at the end
 
-Q1: Are there literals or names that span two sub-buckets (e.g., a magic value in J1 that also appears inside an f-string scrutinized by J2; an UPPER_SNAKE in J3 that also fails the use-count test in J4)? Cite the literal/name and both sub-bucket IDs.
+Q1: Are there literals or names that span two sub-buckets (e.g., a magic value in J1 that also appears inside an f-string scrutinized by J2; an UPPER_SNAKE in J3 that is also an abbreviation under J5)? Cite the literal/name and both sub-bucket IDs.
 
 Q2: What is the worst CODE_RULES drift introduced by this artifact? Cite `<file>:<line>`. (Common candidates: cross-language duplicates, stale help text mirroring a config constant, abbreviations in a public API surface, bare `Any` annotations, hardcoded user paths in installer scripts.)
 
@@ -149,13 +144,6 @@ ID prefix: `find`.
 - `Install-SweepEmptyDirs.ps1` line 245 — `$TaskName = "SweepEmptyDirs"` is a PowerShell variable; J3 enforces Python module-level UPPER_SNAKE outside `config/`. PowerShell out of scope for J3.
 - Adversarial probes: (a) does any module-level constant in `sweep_empty_dirs.py` masquerade as an "import"? (b) is there any `_PRIVATE_UPPER` declaration that escapes the visual UPPER_SNAKE filter? (c) does the test file accidentally declare a constant that *would* be flagged if it were in production?
 
-**J4. File-global use-count**
-- For every file-global constant outside `config/`, count references in the same file. Single ref → move to `config/`. Zero refs → delete.
-- `sweep_empty_dirs.py` — no file-global constants declared (`DEFAULT_AGE_SECONDS` and `DEFAULT_POLL_INTERVAL` are imports). Imports follow standard import-usage rules, not the file-global use-count rule.
-- `config/sweep_config.py:142-143` — `DEFAULT_AGE_SECONDS` and `DEFAULT_POLL_INTERVAL` live in `config/`, exempt by location.
-- Test file `_SCRIPTS_DIR` — test files exempt.
-- Adversarial probes: (a) is any imported constant in `sweep_empty_dirs.py` referenced only once (line 104 for `DEFAULT_AGE_SECONDS`, line 108 for `DEFAULT_POLL_INTERVAL`) — wait, `DEFAULT_AGE_SECONDS` is referenced TWICE on line 104 (`default=DEFAULT_AGE_SECONDS`) and line 105 (`f"...default: {DEFAULT_AGE_SECONDS} = 2 minutes"`); `DEFAULT_POLL_INTERVAL` is referenced TWICE on line 108 and line 109. Both meet the ≥2-references threshold (note: file-global use-count technically applies to declarations, not imports — listed here for completeness). (b) is any helper function in `sweep_empty_dirs.py` defined but never called from inside the file? `_log_walk_error` (line 73) is referenced once at line 84; `_build_parser` (line 101) is referenced once at line 114. The use-count rule applies to *constants*, not functions, so neither is flagged. (c) does any constant in `config/sweep_config.py` get imported from zero call sites?
-
 **J5. Abbreviations**
 - Walk every parameter, local, and attribute name in `sweep_empty_dirs.py`.
 - `_log_walk_error(os_error: OSError)` — `os_error` is full word, not `e` (exception loop var allowed but not required). Verified clean.
@@ -247,11 +235,9 @@ import time
 from config.sweep_config import DEFAULT_AGE_SECONDS
 from config.sweep_config import DEFAULT_POLL_INTERVAL
 
-
 def _log_walk_error(os_error: OSError) -> None:
     print(f"warning: cannot scan {os_error.filename} — {os_error.strerror}", file=sys.stderr)
 
-
 def sweep(root: str, min_age_seconds: int) -> list[str]:
     """Remove empty directories under *root* older than *min_age_seconds*."""
 
@@ -275,7 +261,6 @@ def sweep(root: str, min_age_seconds: int) -> list[str]:
 
     return removed
 
-
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Delete empty directories older than a given age.")
     parser.add_argument("root", help="Root directory to scan")
@@ -287,7 +272,6 @@ def _build_parser() -> argparse.ArgumentParser:
                         help=f"Poll interval in seconds when looping (default: {DEFAULT_POLL_INTERVAL})")
     return parser
 
-
 def main() -> None:
     parser = _build_parser()
     arguments = parser.parse_args()
@@ -309,7 +293,6 @@ def main() -> None:
         print("
 stopped.")
 
-
 if __name__ == "__main__":
     main()
 ```
@@ -342,7 +325,6 @@ if str(_SCRIPTS_DIR) not in sys.path:
 
 from sweep_empty_dirs import sweep  # noqa: E402
 
-
 def _set_creation_time_windows(path: str, timestamp: float) -> None:
     dt = datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
     date_str = dt.strftime("%Y-%m-%d %H:%M:%S")
@@ -352,7 +334,6 @@ def _set_creation_time_windows(path: str, timestamp: float) -> None:
         check=True, capture_output=True,
     )
 
-
 def test_deletes_empty_dir_older_than_threshold() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         empty_dir = os.path.join(tmp, "old_empty")
@@ -362,7 +343,6 @@ def test_deletes_empty_dir_older_than_threshold() -> None:
         assert empty_dir in removed
         assert not os.path.isdir(empty_dir)
 
-
 def test_skips_empty_dir_newer_than_threshold() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         fresh_dir = os.path.join(tmp, "fresh_empty")
@@ -371,7 +351,6 @@ def test_skips_empty_dir_newer_than_threshold() -> None:
         assert fresh_dir not in removed
         assert os.path.isdir(fresh_dir)
 
-
 def test_deletes_nested_empty_dirs() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         leaf = os.path.join(tmp, "parent", "child", "leaf")
@@ -384,13 +363,11 @@ def test_deletes_nested_empty_dirs() -> None:
         assert os.path.join(tmp, "parent", "child") in removed
         assert os.path.join(tmp, "parent") in removed
 
-
 def test_empty_root_does_not_crash() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         _set_creation_time_windows(tmp, time.time() - 300)
         sweep(tmp, min_age_seconds=120)
 
-
 def test_skips_nonempty_dir() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         nonempty_dir = os.path.join(tmp, "has_stuff")

package/bin/install-constants.mjs

@@ -55,12 +55,7 @@ export const RUN_BACKUP_DIRECTORY_NAME_PATTERN =
  */
 export const PACKAGE_AGENTS_HOME_DIRECTORY_NAME = '.agents';
 
-export const PSTACK_MODEL_RULE_FILE_NAME = 'pstack-models.mdc';
 export const SUBAGENT_MODEL_POLICY_FILE_NAME = 'subagent-model-policy.json';
-export const PSTACK_SEEDED_MODEL_PREFERENCES_FILE_NAMES = Object.freeze([
-    'pstack-model-preferences.claude.json',
-    'pstack-model-preferences.codex.json',
-]);
 
 /**
  * The directory name skill directories carry in a package source and under