claude-dev-env 2.32.0 → 2.33.0

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

@@ -38,7 +38,6 @@ These shape how you think while writing. Mechanical rules live in the canonical
 7. **One meaning per variable** — new names for each transformation stage.
 8. **Visual rhythm** — paragraph breaks; walls become named helpers.
 
-9. **Complexity budget** — state the budget before implementation. Keep the change to 1–2 files and ~50–300 lines. Keep each function to about 40 executable lines and a nesting level of 2. Split the work or record why the budget does not fit.
 
 ## Canonical policy map (do not restate)
 
@@ -81,7 +80,7 @@ Load only the group that matches the task. Keep session policy details in these
 
 Material implementation questions must return to the caller for `AskUserQuestion` handling; do not ask in plain text or guess.
 
-Type-ignore rule (AGENTS Types): a `# type: ignore` needs a second trailing `#` justification of at least five characters. Prefer a real type when available.
+Type-ignore rule (AGENTS Types): avoid `# type: ignore`; remove it and use a typed boundary or real type.
 
 Constants (AGENTS Magic values): use named constants from the target layout. Search its constants module first. Do not force a generic `config/` layout. Example:
 
@@ -134,11 +133,13 @@ Consult the advisor the spawn ticket names. When the ticket names the orchestrat
 ```
 [1] Local config searched and reused?
 [2] Full words; correct naming prefixes?
-[3] Parameters and returns typed; no bare Any / bare type: ignore?
-[4] No new production inline comments; existing comments preserved?
-[5] Magic values and UPPER_SNAKE live in config/ where required?
-[6] Function short; one job; guards over else-chains?
-[7] Pre-check --check clean for the real destination path?
+[3] Parameters and returns typed; no Any / no type-ignore directives?
+[4] Do not add code comments. Preserve existing comments. Docstrings remain allowed.
+[5] When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+[6] Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
+[7] Magic values and UPPER_SNAKE live in config/ where required?
+[8] Function short; one job; guards over else-chains?
+[9] Pre-check --check clean for the real destination path?
 ```
 
 ## Scope, TDD, and outcomes

package/.agents/agents/code-quality-agent.md

@@ -61,7 +61,9 @@ Tradeoff for category-restricted mode: parallel category invocation loses cross-
 
 ## Comment Preservation
 
-Preserve every existing comment. Findings on production code report only on new code added by the diff; existing comments on lines that remain otherwise unchanged stay outside the audit's scope. New inline comments added by this PR's diff are themselves a category J finding (production code self-documents through naming).
+Leave comments tied to untouched code unchanged. Findings on production and test code report only on new code added by the diff; comments on lines that remain otherwise unchanged stay outside the audit's scope. New inline comments added by this PR's diff are themselves a category J finding (code self-documents through naming).
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
 
 ## Read-Only Stance
 
@@ -93,7 +95,7 @@ For each category's full description, examples, sub-bucket decomposition, and co
 | P | Name / regex / word-list vs behavior-contract precision | `<managed-root>/audit-rubrics/category_rubrics/category-p-name-vs-behavior-contract.md` (source fallback: `packages/claude-dev-env/audit-rubrics/category_rubrics/category-p-name-vs-behavior-contract.md`) |
 | Q | Cross-surface claim consistency (terminology, PR-description claims, message-vs-guard) | `<managed-root>/audit-rubrics/category_rubrics/category-q-cross-surface-claims.md` (source fallback: `packages/claude-dev-env/audit-rubrics/category_rubrics/category-q-cross-surface-claims.md`) |
 
-Test files (`test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, and any path under `/tests/`) are exempt from category J. The exempt path families documented in the J reference also opt out of the constants-location sub-item.
+Test files use the same no-new-comment policy. The exempt path families documented in the J reference still opt out of the constants-location sub-item.
 
 Category K Shape A findings always cite TWO line locations: the changed line and the unchanged-but-should-have-changed parallel line. The `failure_mode` field describes the contradiction between the two states. K is narrow but recurrent — linters and unit tests rarely catch these findings.
 

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

@@ -16,16 +16,21 @@ Explain the change so a smart reader who knows nothing about the code can pictur
 - Prefer a tiny Before / After story when the change is about how something is found, asked for, checked, saved, retried, or stopped.
 - Use small words and picture words.
 - Replace jargon with the action it represents. When one technical term matters, explain it immediately in plain words.
-- Keep the main behavior in `What this adds`, the reason in `Why`, and proof in `Verification`.
 - Keep titles concrete. Say what someone gives it, what happens, or what comes back.
 
+## Full-diff behavior standard
+
+Before drafting, inventory every independently observable behavior in the full diff. A behavior is independent when a user, caller, operator, automation, output, error, exit status, fallback, or side effect can observe it separately. Lead with the central behavior for readability, then give every other behavior its own short paragraph or bullet.
+
+For each behavior, state the trigger or observer, the Before -> After result, the affected surface/caller when shared, and focused proof. Include important preserved behavior and fallback paths when they help a coder rule a regression in or out. Describe outcomes, not line-by-line implementation, and do not hide multiple behaviors under vague umbrella wording.
+
 For a concrete voice sample only when needed, read `reference/pr-description-illustrative-voice.md` beside this agent. For a concrete verification sample only when needed, read `reference/pr-description-verification.md`. These samples guide the shape and voice; they are not content to copy into unrelated pull requests.
 
 ## Draft the body
 
 1. Inspect the cumulative diff, the current pull request body, and the validation results.
-2. Find the main behavior a user, caller, operator, or reviewer can see.
-3. Write that behavior first in plain illustrative language.
+2. Build the full-diff inventory and name every independently observable behavior.
+3. Write the central behavior first, then give each other behavior its own short paragraph or bullet.
 4. Preserve accurate issue links and curated sections from the current body when they remain useful.
 5. Use headings when they help a reviewer scan the change.
 6. In `Verification`, lead with what a person can open, see, click, compare, or try for themselves. Put test results in one short supporting line when useful.

package/.agents/agents/reference/pr-description-illustrative-voice.md

@@ -12,6 +12,12 @@ After: show the new action in a tiny scene.
 
 Keep machine words out when a plain action works. If one technical term matters, explain it in the same breath with a simple picture.
 
+## Full-diff behavior standard
+
+Before writing, inventory every independently observable behavior in the full diff. A behavior is independent when a user, caller, operator, automation, output, error, exit status, fallback, or side effect can observe it separately. Lead with the central behavior for readability, then give every other behavior its own short paragraph or bullet.
+
+For each behavior, state the trigger or observer, the Before -> After result, the affected surface/caller when shared, and focused proof. Include important preserved behavior and fallback paths when they help a coder rule a regression in or out. Describe outcomes, not line-by-line implementation, and do not hide multiple behaviors under vague umbrella wording.
+
 ## Sample 1 — call the right helper directly
 
 The theme package has a phone icon somewhere. We need to find it.
@@ -39,7 +45,6 @@ The person running the loop asked for a full look, so every pass gets a full loo
 - Prefer Before / After when the change is about how something is asked, found, checked, saved, retried, or stopped.
 - Use picture words: hand it, open it, find it, check it, save it, skip it, stop, call by name.
 - Prefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”
-- Keep the main behavior in `What this adds`.
 - Keep `Why` short and concrete.
 - Put proof only in `Verification`.
 - Explain jargon immediately or replace it.

package/.agents/agents/test_agent_frontmatter.py

@@ -934,15 +934,6 @@ def test_code_quality_agent_contract_forbids_mutating_commands() -> None:
     assert "run no commands that write files or create PRs." in body
 
 
-def test_clean_coder_sets_a_small_complexity_budget() -> None:
-    body = _clean_coder_body()
-    assert "Complexity budget" in body
-    assert "1–2 files" in body
-    assert "~50–300 lines" in body
-    assert "about 40 executable lines" in body
-    assert "nesting level of 2" in body
-
-
 def test_clean_coder_defines_a_liveness_boundary_for_dead_code_cleanup() -> None:
     body = _clean_coder_body()
     assert "orphaned or dead code" in body.lower()

package/.agents/agents/test_pr_description_writer_style.py

@@ -29,7 +29,6 @@ def test_voice_reference_keeps_the_plain_illustrative_shape() -> None:
         "found it",
         "missing",
         "duplicated",
-        "What this adds",
         "Why",
         "Verification",
     ):
@@ -45,3 +44,27 @@ def test_verification_leads_with_a_human_visible_check() -> None:
         assert visible_action in reference_text
     assert "Tests: focused checks pass." in reference_text
     assert "Machine checks can support the claim." in reference_text
+
+
+def test_full_diff_behavior_standard_is_explicit_in_writer_sources() -> None:
+    all_writer_source_texts = [
+        (AGENT_DIRECTORY.parent / "skills" / "pr-title-description" / "SKILL.md").read_text(
+            encoding="utf-8"
+        ),
+        AGENT_PATH.read_text(encoding="utf-8"),
+        VOICE_REFERENCE_PATH.read_text(encoding="utf-8"),
+    ]
+
+    for each_required_text in (
+        "independently observable behavior",
+        "Before -> After result",
+        "affected surface/caller when shared",
+        "focused proof",
+        "preserved behavior and fallback paths",
+        "outcomes, not line-by-line implementation",
+        "vague umbrella wording",
+    ):
+        assert all(
+            each_required_text in each_source_text
+            for each_source_text in all_writer_source_texts
+        )

package/.agents/skills/e-simplify/SKILL.md

@@ -40,23 +40,9 @@ include the working-tree changes in scope — the review often runs before the
 commit. If a PR number, branch name, or file path was passed as an argument,
 review that target instead. Treat this diff as the review scope.
 
-**Diff-size cap.** Run `git diff --shortstat` on the same range Phase 0 used
-to get the diff, and add its insertions and deletions for the changed-line
-count. Default ceiling: 400 changed lines for one run — a tunable default the
-user may adjust. Above the ceiling, narrow the target first — a subdirectory,
-a package, or one file path — and review that narrowed target. Do not launch
-Phase 1 over a diff above the ceiling.
-
 ### Phase 1 — Review (up to 4 cleanup agents in parallel)
 
-**Lens cap.** Four lenses is the ceiling, not the floor. Default split — also
-tunable — by the `git diff --shortstat` changed-line count from Phase 0:
-under 100 changed lines, run 2 lenses (reuse and simplification); at 100
-changed lines or above, and under the diff-size cap, run all 4 lenses.
-
-Launch the review agents for the lenses in scope for this run — 2 or 4 by the
-cap above — via the Agent tool, all in a single message so they run
-concurrently. Pass each agent the diff and one of the angles below. Each
+Launch all four review agents via the Agent tool in one message so they run concurrently. Pass each agent the diff and one angle below. Each
 returns its findings with `file`, `line`, a one-line `summary`, and the
 concrete cost (what is duplicated, wasted, or harder to maintain).
 

package/.agents/skills/grok-spawn/reference/worker-briefs.md

@@ -61,6 +61,10 @@ session owns every git and GitHub step.
 You edit code and run tests for one closed task. You never commit, push, or call
 `gh`. The lead session stages, verifies, commits, pushes, and posts.
 
+Do not add code comments. Preserve existing comments. Docstrings remain allowed.
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
+
 ## Scope
 
 - Working directory: [absolute path]

package/.agents/skills/pr-refinement/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pr-refinement
-description: Coordinate shared-extraction and capability-naming audits, then update an existing pull request or publish a required focused GitHub pull-request stack. Use when a user asks to turn a PR architecture audit into extracted shared code and small pull requests.
+description: Coordinate shared-extraction and capability-naming audits, then update an existing pull request or publish a focused GitHub pull-request stack. Use when a user asks to turn a PR architecture audit into extracted shared code and small pull requests.
 ---
 
 # PR Refinement
 
-Turn audit findings into a focused existing pull-request update or a required dependency-ordered GitHub pull-request stack.
+Turn audit findings into a focused existing pull-request update or a dependency-ordered GitHub pull-request stack.
 
 ## Peer skills
 

package/.agents/skills/pr-shared-extraction/SKILL.md

@@ -42,7 +42,7 @@ Shared extraction audit:
 - [ ] 3. Grep for offense patterns (see reference/offense-taxonomy.md)
 - [ ] 4. Write prioritized findings (P0–P3)
 - [ ] 5. Apply **Mode routing** after the report
-- [ ] 6. Extract in small CLs (~100 lines) + move/adjust tests
+- [ ] 6. Extract in small CLs + move/adjust tests
 - [ ] 7. Run scoped pytest, then follow the selected mode's mutation boundary
 - [ ] 8. When the mode is `preflight-proposal`, record proposal evidence from the [shared preflight proposal contract](../_shared/pr-loop/preflight-proposal.md) and require downstream owner selection before reapplication
 ```
@@ -115,7 +115,7 @@ Use [reference/offense-taxonomy.md](reference/offense-taxonomy.md). Assign prior
 3. **Retarget every caller, then delete the old module** — grep the old import path; remove re-export facades
 4. **Constants:** one source; workflow CLI keeps only workflow-specific names (`LEDGER_FILENAME`, exit codes)
 5. **Tests move with behavior** — shared module gets shared tests; orchestration keeps integration tests only
-6. **Small CLs** — one concern per commit (~100 lines); run scoped pytest after each
+6. **Small CLs** — one concern per commit; run scoped pytest after each
 
 ### Canonical target map (this repo)
 

package/.agents/skills/pr-title-description/SKILL.md

@@ -12,7 +12,12 @@ Review this pull request: <PR link>
 
 Read the PR and its full diff. Do not use the branch name, commit message, labels, current title, or a shallow summary.
 
-Find the main thing this adds for a user, caller, or operator.
+## Full-diff behavior standard
+
+Before writing, inventory every independently observable behavior in the full diff. A behavior is independent when a user, caller, operator, automation, output, error, exit status, fallback, or side effect can observe it separately. Lead with the central behavior for readability, then give every other behavior its own short paragraph or bullet.
+
+For each behavior, state the trigger or observer, the Before -> After result, the affected surface/caller when shared, and focused proof. Include important preserved behavior and fallback paths when they help a coder rule a regression in or out. Describe outcomes, not line-by-line implementation, and do not hide multiple behaviors under vague umbrella wording.
+
 
 Write like the reader is smart but knows nothing about this code. Pretend they asked you to explain it like they are five and feel stupid. If a word needs another sentence to explain it, replace the word — or turn it into a tiny story.
 
@@ -68,7 +73,6 @@ Then write a short, paste-ready PR description.
 Use this structure:
 
 What this adds
-1–2 short paragraphs in that illustrative voice. Lead with a scene when you can (“The theme package has a phone icon somewhere…”). If the change is a new way to ask, use Before / After. Say what you give it, what it does with its hands, and what you get back. If an abstract machine-word must appear, gloss it immediately (“That’s all X is — …”). Describe the job people can see. Do not describe inner machinery. Mention a check only if it is central to the feature. If there are many changes, keep the main one. Mention others only if they explain the main one.
 
 Why
 One short paragraph. Same plain level. Say who needs this and what goes wrong without it (the “yell and wait for a hand” problem). If this is needed to decode the feature, rewrite “What this adds.”

package/.agents/skills/review-tier/SKILL.md

@@ -29,7 +29,7 @@ Use for `/review-tier` and automatic review classification. Refuse execution req
 
 ## Examples
 
-Input `{"files": 0, "lines": 0}` produces `T1`. Input `{"hard_triggers": ["migration"]}` produces `T3`. Input `{"files": 0}` with override `T2` produces calculated `T1` and effective `T2`.
+Input `{"packages": 0, "risk": 0}` produces `T1`. Input `{"hard_triggers": ["migration"]}` produces `T3`. An empty input with override `T2` produces calculated `T1` and effective `T2`.
 
 ## Dependencies
 

package/.agents/skills/review-tier/reference/tier-policy.json

@@ -3,7 +3,7 @@
   "tiers": ["T1", "T2", "T3"],
   "thresholds": {"T1": 0, "T2": 2, "T3": 5},
   "hard_triggers": ["security", "migration", "public-api", "release"],
-  "axes": ["files", "lines", "packages", "risk", "public_api", "dependencies"],
-  "axis_weights": {"files": 1, "lines": 1, "packages": 2, "risk": 2, "public_api": 2, "dependencies": 1},
+  "axes": ["packages", "risk", "public_api", "dependencies"],
+  "axis_weights": {"packages": 2, "risk": 2, "public_api": 2, "dependencies": 1},
   "approved_downgrades": ["T1", "T2"]
 }

package/.agents/skills/review-tier/scripts/review_tier.py

@@ -6,10 +6,38 @@ import hashlib
 import json
 import os
 import subprocess
+from collections.abc import Mapping, Sequence
 from pathlib import Path
-from typing import Mapping, Sequence
 
-from review_tier_constants.config.constants import ALL_DEPENDENCY_MARKERS, ALL_HARD_TRIGGER_MARKERS, ALL_PACKAGE_ROOT_NAMES, ALL_PUBLIC_API_MARKERS, ALL_SOURCE_SUFFIXES, ALL_STATUS_ARGUMENTS, ALL_STATUS_DOMAINS, ALL_TIER_ORDER, ALL_UNTRACKED_ARGUMENTS, AMBIGUOUS_BASE_REF, DEFAULT_BRANCH_FALLBACK, GIT_COMMAND_FAILED, GIT_HEAD_REF, INVALID_BASE_REF, JSON_INDENT, MALFORMED_TIER_POLICY, MAX_AXIS_VALUE, MIN_NONEMPTY_RISK, PATH_SEPARATOR, PLUGIN_DATA_ENVIRONMENT, REMOTE_HEAD_REF, ROOT_PACKAGE, ROUTING_STATE_ROOT_TRACKED, STATUS_CODE_LENGTH, STATUS_PREFIX_LENGTH, UNAPPROVED_TIER_DOWNGRADE, UNKNOWN_TIER
+from review_tier_constants.config.constants import (
+    ALL_DEPENDENCY_MARKERS,
+    ALL_HARD_TRIGGER_MARKERS,
+    ALL_PACKAGE_ROOT_NAMES,
+    ALL_PUBLIC_API_MARKERS,
+    ALL_SOURCE_SUFFIXES,
+    ALL_STATUS_ARGUMENTS,
+    ALL_STATUS_DOMAINS,
+    ALL_TIER_ORDER,
+    ALL_UNTRACKED_ARGUMENTS,
+    AMBIGUOUS_BASE_REF,
+    DEFAULT_BRANCH_FALLBACK,
+    GIT_COMMAND_FAILED,
+    GIT_HEAD_REF,
+    INVALID_BASE_REF,
+    JSON_INDENT,
+    MALFORMED_TIER_POLICY,
+    MAX_AXIS_VALUE,
+    MIN_NONEMPTY_RISK,
+    PATH_SEPARATOR,
+    PLUGIN_DATA_ENVIRONMENT,
+    REMOTE_HEAD_REF,
+    ROOT_PACKAGE,
+    ROUTING_STATE_ROOT_TRACKED,
+    STATUS_CODE_LENGTH,
+    STATUS_PREFIX_LENGTH,
+    UNAPPROVED_TIER_DOWNGRADE,
+    UNKNOWN_TIER,
+)
 
 
 def router_state_root(repo_root: str | Path, all_environment: Mapping[str, str] | None = None) -> Path:
@@ -197,9 +225,8 @@ def inventory_generation(repo_root: str | Path, base_ref: str | None = None, sta
     untracked_identities = [{"path": each_path, "sha256": record["content_sha256"]} for each_path, record in ((record["path"], record) for record in records) if "untracked" in record["domains"]]
     base_source = "explicit" if base_ref else ("remote_default" if requested_base == REMOTE_HEAD_REF else "configured_fallback")
     canonical = json.dumps({"base_ref": requested_base, "base_source": base_source, "base_sha": base, "merge_base_sha": merge_base, "head_sha": head, "domains": {each_domain: sorted(all_paths) for each_domain, all_paths in domains.items()}, "files": records, "untracked_identities": sorted(untracked_identities, key=lambda record: record["path"])}, sort_keys=True, separators=(",", ":")).encode() + patch_bytes
-    lines = sum(int(record["added"]) + int(record["deleted"]) for record in records)
     digest = hashlib.sha256(canonical).hexdigest()
-    return {"paths": [record["path"] for record in records], "files_by_domain": records, "committed": sorted(committed), "staged": sorted(domains["staged"]), "unstaged": sorted(domains["unstaged"]), "untracked": sorted(domains["untracked"]), "base_ref": requested_base, "base_source": base_source, "base_sha": base, "merge_base_sha": merge_base, "head_sha": head, "merge_base": merge_base, "HEAD": head, "inventory_hash": digest, "diff_hash": digest, "files": len(records), "lines": lines, "packages": len(packages), "risk": MIN_NONEMPTY_RISK if records else 0, "public_api": public_api, "dependencies": dependencies, "hard_triggers": triggers}
+    return {"paths": [record["path"] for record in records], "files_by_domain": records, "committed": sorted(committed), "staged": sorted(domains["staged"]), "unstaged": sorted(domains["unstaged"]), "untracked": sorted(domains["untracked"]), "base_ref": requested_base, "base_source": base_source, "base_sha": base, "merge_base_sha": merge_base, "head_sha": head, "merge_base": merge_base, "HEAD": head, "inventory_hash": digest, "diff_hash": digest, "packages": len(packages), "risk": MIN_NONEMPTY_RISK if records else 0, "public_api": public_api, "dependencies": dependencies, "hard_triggers": triggers}
 
 
 def _package_key(path: str) -> str:

package/.agents/skills/review-tier/scripts/test_generation.py

@@ -2,8 +2,13 @@ import subprocess
 from pathlib import Path
 
 import pytest
-
-from review_tier import build_generation, inventory_generation, router_state_directory, router_state_root, router_state_root_id
+from review_tier import (
+    build_generation,
+    inventory_generation,
+    router_state_directory,
+    router_state_root,
+    router_state_root_id,
+)
 
 
 def test_generation_uses_live_git_surface(tmp_path: Path) -> None:
@@ -94,23 +99,6 @@ def test_diff_hash_changes_when_same_path_content_changes(tmp_path: Path) -> Non
     assert inventory_generation(tmp_path)["diff_hash"] != first_hash
 
 
-def test_effective_lines_include_committed_staged_unstaged_and_untracked(tmp_path: Path) -> None:
-    _git_repository(tmp_path)
-    committed_path = tmp_path / "committed.txt"
-    committed_path.write_text("one\ntwo\n", encoding="utf-8")
-    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
-    subprocess.run(["git", "commit", "-qm", "committed"], cwd=tmp_path, check=True)
-    staged_path = tmp_path / "staged.txt"
-    staged_path.write_text("one\ntwo\n", encoding="utf-8")
-    subprocess.run(["git", "add", str(staged_path)], cwd=tmp_path, check=True)
-    staged_path.write_text("one\ntwo\nthree\n", encoding="utf-8")
-    unstaged_path = tmp_path / "seed.txt"
-    unstaged_path.write_text("seed\nchanged\n", encoding="utf-8")
-    (tmp_path / "untracked.txt").write_text("one\ntwo\n", encoding="utf-8")
-    inventory = inventory_generation(tmp_path)
-    assert inventory["lines"] >= 6
-
-
 def test_inventory_preserves_rename_prior_path_and_operations(tmp_path: Path) -> None:
     _git_repository(tmp_path)
     old_path = tmp_path / "old name.txt"

package/.agents/skills/review-tier/scripts/test_review_tier.py

@@ -1,4 +1,11 @@
-from review_tier import build_decision, calculate_tier, canonical_json_hash, effective_tier, load_policy, policy_hash
+from review_tier import (
+    build_decision,
+    calculate_tier,
+    canonical_json_hash,
+    effective_tier,
+    load_policy,
+    policy_hash,
+)
 
 
 def test_public_policy_functions_return_behavior() -> None:
@@ -10,24 +17,17 @@ def test_public_policy_functions_return_behavior() -> None:
 
 
 def test_tier_boundaries_and_hard_trigger() -> None:
-    assert calculate_tier({"files": 0, "lines": 0, "packages": 0, "risk": 0}) == "T1"
-    assert calculate_tier({"files": 2}) == "T2"
-    assert calculate_tier({"files": 5}) == "T2"
+    assert calculate_tier({"packages": 0, "risk": 0}) == "T1"
     assert calculate_tier({"hard_triggers": ["security"]}) == "T3"
 
 
-def test_all_six_axes_accept_zero_one_two_boundaries() -> None:
-    axes = ("files", "lines", "packages", "risk", "public_api", "dependencies")
+def test_all_axes_accept_zero_one_two_boundaries() -> None:
+    axes = ("packages", "risk", "public_api", "dependencies")
     assert calculate_tier({axis: 0 for axis in axes}) == "T1"
     assert calculate_tier({axis: 1 for axis in axes}) == "T3"
     assert calculate_tier({axis: 2 for axis in axes}) == "T3"
 
 
-def test_score_boundaries_keep_small_changes_below_t3() -> None:
-    assert calculate_tier({"files": 1, "lines": 1}) == "T2"
-    assert calculate_tier({"files": 2, "packages": 1, "risk": 1}) == "T3"
-
-
 def test_upward_and_approved_downward_override() -> None:
     assert effective_tier("T1", "T3") == "T3"
     assert effective_tier("T3", "T1") == "T1"

package/AGENTS.md

@@ -1,3 +1,7 @@
+Do not add code comments. Preserve existing comments. Docstrings remain allowed.
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
+
 Use positive, present-focused prose.
 
 State what should be done, what something does, what was done, or what needs to be done.
@@ -5,3 +9,82 @@ State what should be done, what something does, what was done, or what needs to
 Include only information directly relevant to the immediate task or remaining work.
 
 Use direct outcome-focused wording. Omit filler, failed attempts, alternatives considered, and process narration.
+
+Cut AI tells from any writing. Must always apply.
+
+Edit text to remove AI patterns and add human voice.
+
+Process
+Scan for the patterns below.
+Rewrite. Preserve meaning, match intended tone.
+Add soul (see next section).
+Self-audit: "What makes this obviously AI generated?" Fix remaining tells.
+
+
+Adding soul
+
+Removing patterns is half the job. Sterile, voiceless writing is just as obvious.
+Have opinions. React to facts instead of neutrally listing pros and cons.
+Vary rhythm. Short sentences. Then longer ones that take their time. Mix it up.
+Acknowledge complexity. "Impressive but also kind of unsettling" beats "impressive."
+Use "I" when it fits. First person isn't unprofessional.
+Let some mess in. Perfect structure looks machine-made.
+Be specific. Not "this is concerning" but "there's something unsettling about agents churning away at 3am."
+Patterns to detect and fix
+
+
+Content
+
+Puffery. "pivotal moment", "testament to", "evolving landscape", "setting the stage for", "indelible mark", "deeply rooted". Cut puffery, state what happened.
+Name-dropping. Listing media outlets without context. Pick one, say what was said.
+Superficial -ing phrases. "highlighting...", "ensuring...", "reflecting...", "showcasing...", "fostering...". Delete or expand with real sources.
+Promotional language. "nestled", "vibrant", "breathtaking", "groundbreaking", "renowned", "stunning", "must-visit". Use neutral descriptions.
+Vague attributions. "Experts believe", "Industry reports suggest", "Some critics argue". Name the source or delete.
+Formulaic challenges. "Despite challenges... continues to thrive." Replace with specific facts.
+
+
+Language
+
+AI vocabulary. Additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore, vibrant. Replace with plain words.
+Fancy ways to say "is". "serves as", "stands as", "boasts", "features". Just say "is" or "has".
+"Not just X, but Y." State the point directly instead.
+Rule of three. Forcing ideas into groups of three. Use the natural number.
+Synonym cycling. Protagonist, main character, central figure, hero all in one paragraph. Pick one, repeat it.
+False ranges. "from X to Y" where X and Y aren't on a meaningful scale. List topics directly.
+
+
+Style
+
+Em dash overuse. Avoid em dashes entirely. Use periods or commas only (no parentheses, no en dashes, no hyphen-as-dash substitutes). Em dashes are an AI tell, and reaching for parentheses instead just trades one tell for another. If a thought needs separation, end the sentence or use a comma.
+Colon overuse. Colons are fine before a list or example. Not as mid-sentence connectors. "If you're coming from traditional automation: instead of registering event handlers, you describe conditions" adds nothing with the colon. Rewrite to let the point stand on its own without comparison framing. "Describing when the scheduler should fire works best as plain English." Same meaning, no crutch punctuation.
+Boldface overuse. Don't bold every proper noun or acronym.
+Inline-header lists. The tell is a bold label and colon that restates the line: "Performance: Performance improved...". Convert those to prose. A bold lead-in that ends in a period, names the item, and is followed by genuinely new detail ("Schema in TypeScript. Tables live in one file.") is fine, not a tell.
+Title case headings. Use sentence case.
+Decorative emojis. Remove from headings and bullets.
+Curly quotes. Replace with straight quotes.
+
+
+Communication artifacts
+
+Chatbot phrases. "I hope this helps!", "Let me know if...", "Of course!", "Certainly!", "Found the smoking gun!" Remove.
+Cutoff disclaimers. "While specific details are limited..." Find sources or remove.
+Sycophantic tone. "Great question! You're absolutely right!" Respond directly.
+
+
+Filler
+Filler phrases. "In order to" becomes "To". "Due to the fact that" becomes "Because". "It is important to note that" gets deleted.
+Excessive hedging. "could potentially possibly be argued that it might" becomes "may".
+Generic conclusions. "The future looks bright." State specific plans or facts.
+
+
+Jargon
+Abstract metaphor nouns. Substrate, wedge, vector, locus, vantage, nexus, primitive (as noun), harness (as metaphor), surface (as in "API surface"), bedrock, scaffolding (as metaphor), modality, paradigm, gold-plating, ratchet (as metaphor), evacuate (for moving code), endgame, north star, flywheel. These read as technical but usually have a plainer concrete word. "Substrate" becomes "base". "Wedge in" becomes "add". "Vector" becomes "way" or "method". "Gold-plating" becomes "more than the job needs". "Ratchet" becomes the mechanism's real name or "a limit that only tightens". "Evacuate" becomes "move out". "Endgame" becomes "the last phase". Pick the concrete word.
+
+
+Plain speech
+
+Say what it does, not how it feels. "the database stays close at hand", "SQL you can read", "types that follow your schema" name a feeling. The fix names the mechanism or a number: ".toSQL() returns the exact string sent to the database", "a column rename fails the build". Ask what the sentence tells the reader to do or know, then write that. If you can't restate it as a concrete instruction, fact, or number, cut it. One more check: if the sentence could appear unchanged in another project's docs, it says nothing about this one. Cut it.
+Shorten or split dense sentences. If the reader has to backtrack to parse a sentence, break it in two or drop clauses. One idea per sentence.
+Active voice. Prefer it. Catch "is/are/was/were + past participle" and name the actor: "queries are validated" becomes "the compiler validates queries", "the file is parsed by the loader" becomes "the loader parses the file". Passive is fine only when the actor is unknown or genuinely doesn't matter.
+Cut adverbs, or use a stronger verb. "runs quickly" becomes "is fast" or the number. "significantly improves" becomes the measured delta. An adverb propping up a weak verb means the verb is wrong.
+Prefer the plain word. "utilize" becomes "use", "leverage" becomes "use", "facilitate" becomes "help", "numerous" becomes "many", "in the event that" becomes "if". The fancier synonym is rarely clearer.

package/_shared/pr-loop/code-rules-gate.md

@@ -44,13 +44,16 @@ python "<gate_script>" --base origin/<base_branch> --only-under <prefix> [--only
 - File-global UPPER_SNAKE constants (must live in `config/` outside exempt path families)
 - Magic values in production function bodies (literals other than 0, 1, -1)
 - Imports outside top of module
-- New comments in production code (existing comments preserved untouched)
+- New code comments anywhere; comments tied to touched code are removed and comments tied to untouched code remain unchanged
 - File-global constants used by fewer than 2 functions/methods
 - Logging format-arg violations
 - Database column-name string magic (snake_case strings as first element of 2-tuples in function bodies)
 - Public-wrapper-drops-optional-kwargs of same-file delegates
 
-Test files (`test_*.py`, `*_test.py`, `*.spec.*`, `conftest.py`, paths under `/tests/`) are exempt from comment, magic-value, and constants-location rules.
+Test files use the same no-new-comment policy; their magic-value and constants-location exemptions remain.
+
+When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
+Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
 
 ## Halt-fix-rerun protocol
 

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -2,7 +2,8 @@
 
 ::
 
-    default mode: git diff since merge-base, joined with untracked files
+    default mode: git diff since merge-base, joined with untracked files;
+    --comment-policy: opt into changed-comment findings
     --staged:     validate the staged index; --paths: validate explicit files
     --immediate:  validate staged rules and terminology at commit time
     every mode ends by naming how many files it inspected
@@ -13,6 +14,7 @@ and re-exports their surface for the test suite.
 
 import argparse
 import sys
+from functools import partial
 from pathlib import Path
 
 
@@ -44,7 +46,6 @@ try:
         ALL_WINDOWS_VENV_PYTHON_RELATIVE_PATH_SEGMENTS,
         EMPTY_FILE_SET_EXIT_CODE,
         EMPTY_FILE_SET_MESSAGE,
-        IMMEDIATE_SCOPE_ARGUMENT,
         INSPECTED_COUNT_MESSAGE,
         MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS,
         MINIMUM_STAGED_PYTEST_PYTHON_MAJOR,
@@ -357,7 +358,10 @@ def main(all_arguments: list[str]) -> int:
     repository_root = (
         arguments.repo_root.resolve() if arguments.repo_root is not None else Path.cwd().resolve()
     )
-    validate_content = load_validate_content_for_full_gate()
+    validate_content = partial(
+        load_validate_content_for_full_gate(),
+        include_comment_policy=arguments.comment_policy,
+    )
     if arguments.paths:
         return _run_explicit_paths_mode(validate_content, arguments, repository_root)
     if arguments.immediate:

package/_shared/pr-loop/scripts/code_rules_gate_parts/gate_arguments.py

@@ -9,6 +9,16 @@ from pr_loop_shared_constants.code_rules_gate_constants import (
 )
 
 
+def _add_comment_policy_argument(parser: argparse.ArgumentParser) -> None:
+    """Add the opt-in diff-aware comment-policy switch."""
+    parser.add_argument(
+        "--comment-policy",
+        action="store_true",
+        default=False,
+        help="Include the opt-in diff-aware comment-policy checks.",
+    )
+
+
 def _add_source_arguments(parser: argparse.ArgumentParser) -> None:
     """Add the repo-root, base-ref, and staged-scope arguments to *parser*."""
     parser.add_argument(
@@ -22,6 +32,7 @@ def _add_source_arguments(parser: argparse.ArgumentParser) -> None:
         default="origin/main",
         help="Merge-base ref for git diff (default: origin/main).",
     )
+    _add_comment_policy_argument(parser)
     staged_scope_group = parser.add_mutually_exclusive_group()
     staged_scope_group.add_argument(
         "--staged",
@@ -77,6 +88,7 @@ def parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
 
     Returns:
         The parsed namespace with ``repo_root``, ``base``, ``staged``,
-        ``immediate``, ``only_under``, and ``paths`` attributes.
+        ``immediate``, ``comment_policy``, ``only_under``, and ``paths``
+        attributes.
     """
     return _build_argument_parser().parse_args(all_arguments)

package/_shared/pr-loop/scripts/code_rules_gate_parts/tests/test_gate_arguments.py

@@ -25,5 +25,12 @@ def test_parse_arguments_collects_only_under_and_paths() -> None:
 def test_parse_arguments_defaults_base_to_origin_main() -> None:
     arguments = gate_arguments.parse_arguments([])
     assert arguments.base == "origin/main"
+    assert arguments.comment_policy is False
     assert arguments.staged is False
     assert arguments.only_under == []
+
+
+def test_parse_arguments_accepts_opt_in_comment_policy() -> None:
+    arguments = gate_arguments.parse_arguments(["--comment-policy"])
+
+    assert arguments.comment_policy is True