claude-dev-env 2.7.1 → 2.9.0

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/code-quality-agent.md

@@ -8,7 +8,7 @@ color: red
 
 You audit a pull request diff for bugs and CODE_RULES.md compliance issues. You return findings; the orchestrator handles fixes.
 
-**Announce at start:** "Using code-quality-agent — auditing diff against A–P categories with CODE_RULES.md awareness."
+**Announce at start:** "Using code-quality-agent — auditing diff against A–Q categories with CODE_RULES.md awareness."
 
 ## Scope
 
@@ -18,7 +18,7 @@ Audit only added or modified lines in the diff. Pre-existing code on untouched l
 
 This agent runs in one of two modes depending on the calling prompt:
 
-- **Unscoped (default):** the prompt names no categories. Walk all of A through P and produce Shape A/B for every category.
+- **Unscoped (default):** the prompt names no categories. Walk all of A through Q and produce Shape A/B for every category.
 - **Category-restricted:** the prompt names a subset of categories ("audit only category F" or "investigate only H, I, and K"). Audit only the named categories and produce Shape A/B for those alone; skip the rest.
 
 Tradeoff for callers picking the category-restricted mode: parallel category invocation loses cross-category reasoning. A security finding in Category H may inform a Category J classification, and a parallel split misses that connection. When categories need to inform each other, prefer the unscoped mode.
@@ -31,9 +31,9 @@ Preserve every existing comment. Findings on production code report only on new
 
 Report findings only. Author zero edits. Author zero diffs. Run zero commits or pushes. The orchestrator (and the calling skill) handles fix application, commit creation, and PR posting based on your finding list.
 
-## Bug Categories A–P
+## Bug Categories A–Q
 
-Every audit pass walks all sixteen categories. Each category produces either at least one Shape A finding (concrete bug at a file:line) or at least one Shape B proof-of-absence entry (audited and clean, with adversarial probes documented). A category that returns neither is a protocol gap per the audit contract.
+Every audit pass walks all seventeen categories. Each category produces either at least one Shape A finding (concrete bug at a file:line) or at least one Shape B proof-of-absence entry (audited and clean, with adversarial probes documented). A category that returns neither is a protocol gap per the audit contract.
 
 For each category's full description, examples, sub-bucket decomposition, and concrete checks, read the matching rubric in `../audit-rubrics/category_rubrics/`:
 
@@ -55,6 +55,7 @@ For each category's full description, examples, sub-bucket decomposition, and co
 | N | Test-name scenario verifier | `../audit-rubrics/category_rubrics/category-n-test-name-scenario-verifier.md` |
 | O | Docstring / fixture-prose vs implementation drift | `../audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` |
 | P | Name / regex / word-list vs behavior-contract precision | `../audit-rubrics/category_rubrics/category-p-name-vs-behavior-contract.md` |
+| Q | Cross-surface claim consistency (terminology, PR-description claims, message-vs-guard) | `../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.
 
@@ -114,7 +115,7 @@ A bare verified-clean label is inadequate: every Shape B entry lists the files o
 
 ## Per-Category Expectation
 
-Every category A through P is investigated. The output for each category is one of:
+Every category A through Q is investigated. The output for each category is one of:
 - one or more Shape A findings, or
 - one Shape B proof-of-absence entry with concrete files, quoted lines, and adversarial probes.
 

package/agents/deep-research.md

@@ -1,25 +1,6 @@
 ---
 name: deep-research
-description: Use this agent for iterative, multi-source deep research that produces comprehensive Obsidian reports with full citations. Official-docs-first methodology with anti-hallucination constraints. Examples:
-
-  <example>
-  Context: User wants thorough research on a technical topic
-  user: "Research the current state of WebSocket authentication best practices"
-  assistant: "I'll use the deep-research agent to conduct iterative multi-source research and produce a cited report."
-  <commentary>
-  Multi-source research requiring iteration and synthesis — exactly what deep-research handles.
-  </commentary>
-  </example>
-
-  <example>
-  Context: User needs a landscape survey with citations
-  user: "Compare the major vector database options for production RAG systems in 2026"
-  assistant: "I'll launch the deep-research agent to survey the landscape across multiple sources."
-  <commentary>
-  Broad survey requiring many sources, comparison, and synthesis — deep-research with exhaustive depth.
-  </commentary>
-  </example>
-
+description: "Use this agent for iterative, multi-source deep research that produces comprehensive Obsidian reports with full citations. Official-docs-first methodology with anti-hallucination constraints. Examples:\n\n  <example>\n  Context: User wants thorough research on a technical topic\n  user: \"Research the current state of WebSocket authentication best practices\"\n  assistant: \"I'll use the deep-research agent to conduct iterative multi-source research and produce a cited report.\"\n  <commentary>\n  Multi-source research requiring iteration and synthesis — exactly what deep-research handles.\n  </commentary>\n  </example>\n\n  <example>\n  Context: User needs a landscape survey with citations\n  user: \"Compare the major vector database options for production RAG systems in 2026\"\n  assistant: \"I'll launch the deep-research agent to survey the landscape across multiple sources.\"\n  <commentary>\n  Broad survey requiring many sources, comparison, and synthesis — deep-research with exhaustive depth.\n  </commentary>\n  </example>"
 color: cyan
 ---
 
@@ -31,10 +12,9 @@ You receive a `<research_brief>` from the orchestrating skill. Your job is to ex
 
 On receiving the research brief, write the state file:
 
-`.deep-research-state.md`:
+`.deep-research-state.md` opens with a YAML frontmatter block — a three-hyphen fence line, these fields, then a closing three-hyphen fence line:
 
-```markdown
----
+```yaml
 topic: "[from brief]"
 brief: "[one-line summary from brief]"
 iteration: 0
@@ -42,8 +22,11 @@ max_iterations: [from brief]
 status: researching
 source_count: 0
 official_docs_found: false
----
+```
+
+The rest of the file holds the tracking sections:
 
+```markdown
 ## Sources Found
 
 (none yet)

package/agents/docs-agent.md

@@ -1,32 +1,6 @@
 ---
 name: docs-agent
-description: Use this agent for all documentation tasks — managing/consolidating project docs, analyzing existing documentation to prevent code duplication, and writing user-facing guides for non-technical audiences. Trigger with requests like 'update our docs', 'check if we already have this documented', 'write a user guide', or 'consolidate documentation'.
-
-Examples:
-- <example>
-  Context: User wants comprehensive documentation management
-  user: "call the doc manager"
-  assistant: "I'll use the docs-agent to analyze and update the documentation"
-  <commentary>
-  Documentation management request — use docs-agent in orchestration mode.
-  </commentary>
-</example>
-- <example>
-  Context: User is implementing a new feature and wants to avoid duplicating existing functionality
-  user: "I need to add a function that validates user input"
-  assistant: "Let me consult the docs-agent to check if we already have validation methods documented"
-  <commentary>
-  Before implementing new functionality, use docs-agent in analysis mode to check for existing documented methods.
-  </commentary>
-</example>
-- <example>
-  Context: User needs documentation for non-technical staff
-  user: "Write documentation for the new export feature so our office staff can use it"
-  assistant: "I'll use the docs-agent to create clear, step-by-step documentation that anyone can follow"
-  <commentary>
-  Non-technical audience — use docs-agent in user-docs writing mode.
-  </commentary>
-</example>
+description: "Use this agent for all documentation tasks — managing/consolidating project docs, analyzing existing documentation to prevent code duplication, and writing user-facing guides for non-technical audiences. Trigger with requests like 'update our docs', 'check if we already have this documented', 'write a user guide', or 'consolidate documentation'.\n\nExamples:\n- <example>\n  Context: User wants comprehensive documentation management\n  user: \"call the doc manager\"\n  assistant: \"I'll use the docs-agent to analyze and update the documentation\"\n  <commentary>\n  Documentation management request — use docs-agent in orchestration mode.\n  </commentary>\n</example>\n- <example>\n  Context: User is implementing a new feature and wants to avoid duplicating existing functionality\n  user: \"I need to add a function that validates user input\"\n  assistant: \"Let me consult the docs-agent to check if we already have validation methods documented\"\n  <commentary>\n  Before implementing new functionality, use docs-agent in analysis mode to check for existing documented methods.\n  </commentary>\n</example>\n- <example>\n  Context: User needs documentation for non-technical staff\n  user: \"Write documentation for the new export feature so our office staff can use it\"\n  assistant: \"I'll use the docs-agent to create clear, step-by-step documentation that anyone can follow\"\n  <commentary>\n  Non-technical audience — use docs-agent in user-docs writing mode.\n  </commentary>\n</example>"
 color: cyan
 ---
 

package/agents/issue-tracker.md

@@ -1,12 +1,6 @@
 ---
 name: issue-tracker
-description: >-
-  Primary handler for one GitHub issue action per spawn on a work-stream:
-  open an epic, file a sub-issue, update status in place, refresh the epic
-  checklist, or close a sub-issue. Spawn with one action plus the issue-candidate
-  or issue number it needs; loads the issue-tracker skill; returns affected
-  issue numbers and URLs. Prefer the same warm agent for follow-ups on the same
-  issue or the same epic work-stream.
+description: "Primary handler for one GitHub issue action per spawn on a work-stream: open an epic, file a sub-issue, update status in place, refresh the epic checklist, or close a sub-issue. Spawn with one action plus the issue-candidate or issue number it needs; loads the issue-tracker skill; returns affected issue numbers and URLs. Prefer the same warm agent for follow-ups on the same issue or the same epic work-stream."
 tools: Read, Bash, Skill, mcp__github__search_issues, mcp__github__issue_read, mcp__github__issue_write, mcp__github__sub_issue_write, mcp__github__add_issue_comment
 color: green
 ---

package/agents/skill-writer-agent.md

@@ -1,7 +1,6 @@
 ---
 name: skill-writer-agent
-description: >-
-  Authors a skill package — SKILL.md plus companion files — to skill-builder conventions: hub layout, trigger-catalog description, deterministic work shipped as scripts and task-seed lists. Triggers: author a skill, write a SKILL.md, skill-writer-agent, delegate skill file authoring, produce skill package files.
+description: "Authors a skill package — SKILL.md plus companion files — to skill-builder conventions: hub layout, trigger-catalog description, deterministic work shipped as scripts and task-seed lists. Triggers: author a skill, write a SKILL.md, skill-writer-agent, delegate skill file authoring, produce skill package files."
 tools: Read, Write, Edit, Grep, Glob
 color: green
 ---

package/agents/test_agent_frontmatter.py

@@ -16,6 +16,53 @@ model on every spawn, so no agent definition names one, concrete or
     flag: model: inherit    <- caller can no longer 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
+
+Two parsers read these files, and a block that satisfies one can still be
+unreadable by the other. `scripts/codex_compat_materializer.py` reads the
+block line by line, so every field fits on the line that names it::
+
+    ok:   description: "Use this agent ... Examples:\\n\\n  <example> ..."
+    flag: description: |        <- the line scan cannot follow the block scalar
+
+That reader also counts fence lines across the whole file, so a bare `---`
+anywhere in the body reads as a second frontmatter fence::
+
+    ok:   ```yaml ... ``` example blocks in the body
+    flag: a `---` line inside a body example  <- counted as a fence
+
+That reader also cannot express an empty `tools: []` list, which is a defect
+in the reader rather than in the one definition that declares it, so that
+definition is named in `_codex_materializable_paths` and covered by every
+other check here.
+
+Each definition also has to carry a `name` and a `description` bound to a
+non-empty string, and a `name` equal to its file stem — a mapping that loads
+but binds `description` to nothing, or names an agent the file does not,
+registers a subagent the caller cannot spawn::
+
+    ok:   docs-agent.md  -> name: docs-agent
+    flag: docs-agent.md  -> name: doc-manager   <- wrong spawn id
+    flag: description:                          <- loads as None, loader needs text
+
+Every check above is parametrized over the definitions that yield a
+frontmatter block, so a file that yields none would drop out of all of them
+and leave the suite green while unreadable. The block is what the fence lines
+delimit, so the file that opens no fence or never closes one is exactly the
+broken file these checks exist to catch::
+
+    ok:   docs-agent.md  -> ---  name/description  ---   <- block found
+    flag: docs-agent.md  -> ---  name/description        <- no closing fence,
+                                                            silently uncovered
+
+`test_every_agent_definition_yields_a_frontmatter_block` holds that floor: it
+walks the same directory the parametrized checks draw from and fails on any
+definition missing from them.
+
 Frontmatter parsing is self-contained here (stdlib only): the block is the
 text between the file's opening and closing `---` fence lines, and top-level
 keys are read with a line scan so an agent whose `description` embeds
@@ -24,18 +71,27 @@ informal `<example>` prose is not mistaken for one carrying extra keys.
 
 from __future__ import annotations
 
+import importlib.util
 import re
+import sys
 from functools import cache
 from pathlib import Path
+from types import ModuleType
 
 import pytest
 import yaml
 
 ACCEPTED_FRONTMATTER_KEYS = frozenset({"name", "description", "tools", "color"})
-CODE_VERIFIER_AGENT_NAME = "code-verifier"
+EMPTY_TOOLS_LIST_FILENAME = "code-advisor.md"
 EXEMPT_MARKDOWN_FILENAME = "CLAUDE.md"
 FRONTMATTER_FENCE_LINE = "---"
+MATERIALIZER_MODULE_NAME = "codex_compat_materializer"
+MATERIALIZER_MODULE_PATH = (
+    Path(__file__).resolve().parent.parent / "scripts" / f"{MATERIALIZER_MODULE_NAME}.py"
+)
 MODEL_KEY_NAME = "model"
+RENAMED_AGENT_NAME = "an-agent-name-no-file-carries"
+REQUIRED_FRONTMATTER_FIELDS = ("name", "description")
 TOP_LEVEL_KEY_PATTERN = re.compile(r"^([a-z][a-z0-9_]*):", re.MULTILINE)
 
 
@@ -60,14 +116,30 @@ def _extract_frontmatter_block(markdown_text: str) -> str | None:
 
 
 @cache
-def _agent_definition_paths() -> tuple[Path, ...]:
+def _agent_definition_candidate_paths() -> tuple[Path, ...]:
+    """Return every markdown file in this directory that must be a definition.
+
+    This is the floor the parametrized checks are measured against: each of
+    these files is expected to yield a frontmatter block, so one that does not
+    is a broken definition rather than a file to pass over.
+
+    Returns:
+        Every `*.md` path in this directory except the exempt one, sorted.
+    """
     agents_directory = Path(__file__).parent
-    all_markdown_files = sorted(agents_directory.glob("*.md"))
     return tuple(
         each_markdown_file
-        for each_markdown_file in all_markdown_files
+        for each_markdown_file in sorted(agents_directory.glob("*.md"))
         if each_markdown_file.name != EXEMPT_MARKDOWN_FILENAME
-        and _extract_frontmatter_block(each_markdown_file.read_text(encoding="utf-8"))
+    )
+
+
+@cache
+def _agent_definition_paths() -> tuple[Path, ...]:
+    return tuple(
+        each_markdown_file
+        for each_markdown_file in _agent_definition_candidate_paths()
+        if _extract_frontmatter_block(each_markdown_file.read_text(encoding="utf-8"))
         is not None
     )
 
@@ -84,6 +156,124 @@ def _top_level_keys(frontmatter_block: str) -> set[str]:
     return set(TOP_LEVEL_KEY_PATTERN.findall(frontmatter_block))
 
 
+@cache
+def _codex_materializable_paths() -> tuple[Path, ...]:
+    """Return the definitions the Codex materializer is expected to read.
+
+    `code-advisor.md` declares `tools: []`, and its body states the agent has
+    zero tools, so the empty list is the field saying what the author meant.
+    The materializer's list parser raises on an empty list, so it cannot
+    express a correct declaration::
+
+        tools: Read, Bash  -> ok:   parsed
+        tools: []          -> flag: MaterializerError, though the file is right
+
+    The gap belongs to that parser, so the definition stays as written and only
+    this one check steps around it. The YAML-load, required-field, accepted-key,
+    model-ban, and name checks all still cover the file.
+
+    Returns:
+        Every agent definition path except the one whose correct frontmatter
+        the materializer's list parser cannot express.
+    """
+    return tuple(
+        each_path
+        for each_path in _agent_definition_paths()
+        if each_path.name != EMPTY_TOOLS_LIST_FILENAME
+    )
+
+
+@cache
+def _codex_materializer_module() -> ModuleType:
+    """Load the package's own line-oriented frontmatter parser from disk.
+
+    Returns:
+        The imported `codex_compat_materializer` module.
+    """
+    module_specification = importlib.util.spec_from_file_location(
+        MATERIALIZER_MODULE_NAME, MATERIALIZER_MODULE_PATH
+    )
+    assert module_specification is not None, (
+        f"no import specification for {MATERIALIZER_MODULE_PATH}"
+    )
+    assert module_specification.loader is not None, (
+        f"no import loader for {MATERIALIZER_MODULE_PATH}"
+    )
+    materializer_module = importlib.util.module_from_spec(module_specification)
+    sys.modules.setdefault(MATERIALIZER_MODULE_NAME, materializer_module)
+    module_specification.loader.exec_module(materializer_module)
+    return materializer_module
+
+
+def _required_field_problem(parsed_frontmatter: object) -> str | None:
+    """Describe what stops the loader using this frontmatter, or None.
+
+    The loader needs text for every required field, so a field that loads as
+    nothing or as a nested mapping is a problem even though the block itself
+    is valid YAML::
+
+        description: Use this agent ...  -> ok:   None
+        description:                     -> flag: bound to NoneType
+        description:                     -> flag: bound to dict
+          nested: value
+
+    Args:
+        parsed_frontmatter: Value `yaml.safe_load` produced for the block.
+
+    Returns:
+        A sentence naming the problem, or None when every required field is a
+        non-empty string.
+    """
+    if not isinstance(parsed_frontmatter, dict):
+        return (
+            f"frontmatter loads as {type(parsed_frontmatter).__name__} rather "
+            "than a key/value mapping"
+        )
+    for each_field in REQUIRED_FRONTMATTER_FIELDS:
+        if each_field not in parsed_frontmatter:
+            return f"frontmatter carries no {each_field} field"
+        field_value = parsed_frontmatter[each_field]
+        if not isinstance(field_value, str):
+            return (
+                f"frontmatter binds {each_field} to "
+                f"{type(field_value).__name__} rather than a string"
+            )
+        if not field_value.strip():
+            return f"frontmatter binds {each_field} to an empty string"
+    return None
+
+
+def _agent_name_problem(parsed_frontmatter: object, expected_name: str) -> str | None:
+    """Describe a name that disagrees with the file stem, or None.
+
+    A subagent registers under the name in its frontmatter, so a name that is
+    not the file stem is spawned by an id no caller uses::
+
+        docs-agent.md -> name: docs-agent   -> ok:   None
+        docs-agent.md -> name: doc-manager  -> flag: wrong spawn id
+
+    Args:
+        parsed_frontmatter: Value `yaml.safe_load` produced for the block.
+        expected_name: The definition file's stem.
+
+    Returns:
+        A sentence naming the problem, or None when the name matches the stem.
+    """
+    if not isinstance(parsed_frontmatter, dict):
+        return (
+            f"frontmatter loads as {type(parsed_frontmatter).__name__} rather "
+            "than a key/value mapping"
+        )
+    declared_name = parsed_frontmatter.get("name")
+    if declared_name == expected_name:
+        return None
+    return (
+        f"frontmatter declares name {declared_name!r} rather than "
+        f"{expected_name!r}, so the agent registers under a spawn id that does "
+        "not match its file"
+    )
+
+
 @pytest.mark.parametrize(
     "agent_definition_path",
     _agent_definition_paths(),
@@ -100,14 +290,121 @@ def test_agent_frontmatter_uses_only_accepted_keys(
     )
 
 
-def test_code_verifier_frontmatter_parses_and_names_the_agent() -> None:
-    agents_directory = Path(__file__).parent
-    code_verifier_block = _frontmatter_block(
-        agents_directory / f"{CODE_VERIFIER_AGENT_NAME}.md"
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_loads_as_a_yaml_mapping(
+    agent_definition_path: Path,
+) -> None:
+    frontmatter_block = _frontmatter_block(agent_definition_path)
+    try:
+        parsed_frontmatter = yaml.safe_load(frontmatter_block)
+    except yaml.YAMLError as yaml_error:
+        pytest.fail(
+            f"{agent_definition_path.name} frontmatter is not loadable YAML, so "
+            f"the subagent loader cannot read the definition: {yaml_error}"
+        )
+    assert isinstance(parsed_frontmatter, dict), (
+        f"{agent_definition_path.name} frontmatter loads as "
+        f"{type(parsed_frontmatter).__name__} rather than a key/value mapping"
+    )
+    unaccepted_keys = set(parsed_frontmatter) - ACCEPTED_FRONTMATTER_KEYS
+    assert not unaccepted_keys, (
+        f"{agent_definition_path.name} loads frontmatter keys the subagent "
+        f"loader does not accept: {sorted(unaccepted_keys)}"
+    )
+
+
+def test_every_agent_definition_yields_a_frontmatter_block() -> None:
+    covered_names = {each_path.name for each_path in _agent_definition_paths()}
+    uncovered_names = sorted(
+        each_path.name
+        for each_path in _agent_definition_candidate_paths()
+        if each_path.name not in covered_names
+    )
+    assert not uncovered_names, (
+        f"{', '.join(uncovered_names)} yield no frontmatter block, so every "
+        "parametrized check in this module passes over them and the suite "
+        "stays green while the definitions are unreadable"
     )
-    parsed_frontmatter = yaml.safe_load(code_verifier_block)
-    assert parsed_frontmatter["name"] == CODE_VERIFIER_AGENT_NAME
-    assert set(parsed_frontmatter) <= ACCEPTED_FRONTMATTER_KEYS
+
+
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _codex_materializable_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_parses_with_the_codex_materializer(
+    agent_definition_path: Path,
+) -> None:
+    materializer_module = _codex_materializer_module()
+    try:
+        materializer_module.parse_frontmatter(
+            agent_definition_path,
+            agent_definition_path.read_text(encoding="utf-8"),
+            agent_definition_path.name,
+        )
+    except materializer_module.MaterializerError as materializer_error:
+        pytest.fail(
+            f"{agent_definition_path.name} frontmatter is unreadable by "
+            f"{MATERIALIZER_MODULE_NAME}, so the agent cannot be materialized "
+            f"for Codex: {materializer_error}"
+        )
+
+
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_binds_required_fields_to_non_empty_strings(
+    agent_definition_path: Path,
+) -> None:
+    parsed_frontmatter = yaml.safe_load(_frontmatter_block(agent_definition_path))
+    field_problem = _required_field_problem(parsed_frontmatter)
+    assert field_problem is None, f"{agent_definition_path.name} {field_problem}"
+
+
+def test_required_field_check_rejects_a_description_bound_to_nothing() -> None:
+    parsed_frontmatter = yaml.safe_load("name: docs-agent\ndescription:\n")
+    assert _required_field_problem(parsed_frontmatter) == (
+        "frontmatter binds description to NoneType rather than a string"
+    )
+
+
+def test_required_field_check_rejects_a_description_bound_to_a_mapping() -> None:
+    parsed_frontmatter = yaml.safe_load(
+        "name: docs-agent\ndescription:\n  nested: value\n"
+    )
+    assert _required_field_problem(parsed_frontmatter) == (
+        "frontmatter binds description to dict rather than a string"
+    )
+
+
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_names_the_agent_after_its_file(
+    agent_definition_path: Path,
+) -> None:
+    parsed_frontmatter = yaml.safe_load(_frontmatter_block(agent_definition_path))
+    name_problem = _agent_name_problem(parsed_frontmatter, agent_definition_path.stem)
+    assert name_problem is None, f"{agent_definition_path.name} {name_problem}"
+
+
+def test_name_check_rejects_an_agent_renamed_away_from_its_file_stem() -> None:
+    agent_definition_path = _agent_definition_paths()[0]
+    renamed_block = _frontmatter_block(agent_definition_path).replace(
+        f"name: {agent_definition_path.stem}", f"name: {RENAMED_AGENT_NAME}", 1
+    )
+    name_problem = _agent_name_problem(
+        yaml.safe_load(renamed_block), agent_definition_path.stem
+    )
+    assert name_problem is not None and RENAMED_AGENT_NAME in name_problem
 
 
 @pytest.mark.parametrize(
@@ -125,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