claude-dev-env 2.4.0 → 2.7.0

package/_shared/pr-loop/scripts/tests/test_stale_worktree_rule_sweep_constants.py

@@ -1,85 +1,85 @@
-"""Behavioral tests for stale_worktree_rule_sweep_constants.
-
-Confirms get_claude_worktrees_root resolves the worktrees directory under
-the user's ~/.claude home, and that the rule-parsing constants carry the
-literal shapes the sweep relies on.
-"""
-
-from __future__ import annotations
-
-import importlib.util
-import sys
-from pathlib import Path
-from types import ModuleType
-
-import pytest
-
-
-def _load_constants_module() -> ModuleType:
-    scripts_directory = Path(__file__).parent.parent
-    parent_directory = str(scripts_directory.resolve())
-    if parent_directory not in sys.path:
-        sys.path.insert(0, parent_directory)
-    module_path = (
-        scripts_directory
-        / "pr_loop_shared_constants"
-        / "stale_worktree_rule_sweep_constants.py"
-    )
-    specification = importlib.util.spec_from_file_location(
-        "pr_loop_shared_constants.stale_worktree_rule_sweep_constants", module_path
-    )
-    assert specification is not None
-    assert specification.loader is not None
-    module = importlib.util.module_from_spec(specification)
-    specification.loader.exec_module(module)
-    return module
-
-
-def test_worktrees_root_resolves_under_the_user_claude_home(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-) -> None:
-    constants_module = _load_constants_module()
-    monkeypatch.setenv("HOME", str(tmp_path))
-    monkeypatch.setenv("USERPROFILE", str(tmp_path))
-    resolved_worktrees_root = constants_module.get_claude_worktrees_root()
-    assert resolved_worktrees_root == tmp_path / ".claude" / "worktrees"
-
-
-def test_extract_rule_target_path_reads_the_delimited_path() -> None:
-    constants_module = _load_constants_module()
-    extracted_path = constants_module.extract_rule_target_path(
-        "Edit(/repo/wt/.claude/**)"
-    )
-    assert extracted_path == "/repo/wt/.claude/**"
-
-
-def test_extract_rule_target_path_returns_none_for_a_non_rule() -> None:
-    constants_module = _load_constants_module()
-    assert constants_module.extract_rule_target_path("not a rule") is None
-
-
-def test_worktree_directory_for_rule_keeps_nested_segments_below_the_root() -> None:
-    constants_module = _load_constants_module()
-    worktrees_root = Path("/home/dev/.claude/worktrees")
-    resolved_directory = constants_module.worktree_directory_for_rule(
-        "Edit(/home/dev/.claude/worktrees/repo/feature/.claude/**)", worktrees_root
-    )
-    assert resolved_directory == worktrees_root / "repo" / "feature"
-
-
-def test_worktree_directory_for_rule_keeps_one_segment_flat_layout() -> None:
-    constants_module = _load_constants_module()
-    worktrees_root = Path("/home/dev/.claude/worktrees")
-    resolved_directory = constants_module.worktree_directory_for_rule(
-        "Edit(/home/dev/.claude/worktrees/flat-worktree/.claude/**)", worktrees_root
-    )
-    assert resolved_directory == worktrees_root / "flat-worktree"
-
-
-def test_worktree_directory_for_rule_returns_none_outside_the_root() -> None:
-    constants_module = _load_constants_module()
-    worktrees_root = Path("/home/dev/.claude/worktrees")
-    resolved_directory = constants_module.worktree_directory_for_rule(
-        "Edit(/home/dev/project/.claude/**)", worktrees_root
-    )
-    assert resolved_directory is None
+"""Behavioral tests for stale_worktree_rule_sweep_constants.
+
+Confirms get_claude_worktrees_root resolves the worktrees directory under
+the user's ~/.claude home, and that the rule-parsing constants carry the
+literal shapes the sweep relies on.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_constants_module() -> ModuleType:
+    scripts_directory = Path(__file__).parent.parent
+    parent_directory = str(scripts_directory.resolve())
+    if parent_directory not in sys.path:
+        sys.path.insert(0, parent_directory)
+    module_path = (
+        scripts_directory
+        / "pr_loop_shared_constants"
+        / "stale_worktree_rule_sweep_constants.py"
+    )
+    specification = importlib.util.spec_from_file_location(
+        "pr_loop_shared_constants.stale_worktree_rule_sweep_constants", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+def test_worktrees_root_resolves_under_the_user_claude_home(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    constants_module = _load_constants_module()
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    resolved_worktrees_root = constants_module.get_claude_worktrees_root()
+    assert resolved_worktrees_root == tmp_path / ".claude" / "worktrees"
+
+
+def test_extract_rule_target_path_reads_the_delimited_path() -> None:
+    constants_module = _load_constants_module()
+    extracted_path = constants_module.extract_rule_target_path(
+        "Edit(/repo/wt/.claude/**)"
+    )
+    assert extracted_path == "/repo/wt/.claude/**"
+
+
+def test_extract_rule_target_path_returns_none_for_a_non_rule() -> None:
+    constants_module = _load_constants_module()
+    assert constants_module.extract_rule_target_path("not a rule") is None
+
+
+def test_worktree_directory_for_rule_keeps_nested_segments_below_the_root() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/.claude/worktrees/repo/feature/.claude/**)", worktrees_root
+    )
+    assert resolved_directory == worktrees_root / "repo" / "feature"
+
+
+def test_worktree_directory_for_rule_keeps_one_segment_flat_layout() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/.claude/worktrees/flat-worktree/.claude/**)", worktrees_root
+    )
+    assert resolved_directory == worktrees_root / "flat-worktree"
+
+
+def test_worktree_directory_for_rule_returns_none_outside_the_root() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/project/.claude/**)", worktrees_root
+    )
+    assert resolved_directory is None

package/_shared/pr-loop/worker-spawn.md

@@ -146,7 +146,7 @@ Mode decision:
 | `ThirdParty` | any | `chain` | Headless spawn through `claude_chain_runner` |
 
 The review always runs at effort **high** on model **opus**. Chain mode builds
-a single-turn prompt `/code-review xhigh --fix`, pins `--model opus`, sets
+a single-turn prompt `/code-review ultra --fix`, pins `--model opus`, sets
 subprocess `cwd` to the PR working tree, and reads stdin from the empty stream
 so the spawn does not wait for input.
 

package/agents/CLAUDE.md

@@ -11,10 +11,11 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 | `clean-coder.md` | Clean Coder | Primary code-writing agent; internalizes CODE_RULES.md and targets zero `/check` findings |
 | `code-advisor.md` | Code Advisor | Single-executor mid-run advisor (PLAN/CORRECTION/STOP as final text); distinct from session-advisor |
 | `code-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
-| `code-verifier.md` | Code Verifier | Post-hoc verification after coder agents finish; read-only, fresh context, puts the draft verdict through one strongest-tier validation subagent, ends with a fenced verdict |
+| `code-verifier.md` | Code Verifier | Post-hoc verification after coder agents finish; never edits files in the verified tree, with one exception, a deliberate break at an off-tree break site outside it, defined in the agent body; fresh context, puts the draft verdict through one strongest-tier validation subagent, ends with a fenced verdict; `all_pass` true needs a complete shown-red table as well as clean layers |
 | `deep-research.md` | Deep Research | Citation-grounded research with web search |
 | `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
 | `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
+| `issue-tracker.md` | Issue Tracker | Primary handler for one GitHub issue action per spawn; loads the issue-tracker skill (plain-brief); returns issue numbers and URLs |
 | `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
 | `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes that pass the `pr_description_enforcer` hook's body audit |
 | `session-advisor.md` | Session Advisor | Standing multi-consumer reviewer; SendMessage only; returns endorse/correction/plan/stop |
@@ -22,7 +23,7 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 
 ## Format
 
-Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker.
+Each file uses YAML frontmatter (`name`, `description`, `tools`, optional `color`) followed by a Markdown body with the agent's behavioral instructions. The `description` field appears in the Claude Code agent picker. An agent definition carries no `model` key — the caller supplies the model on each spawn.
 
 ## Adding an agent
 

package/agents/caveman.md

@@ -1,7 +1,6 @@
 ---
 name: caveman
 description: Trims noise from an artifact the main caller has already authored. Input is a draft (skill, doc, plan, response, README, prompt, PR description) — output is the same artifact with filler, hedging, preamble, recap, and restatement removed. Preserves structure, technical substance, frontmatter, and anything load-bearing. Does NOT redesign, restructure, or overrule the caller's scope decisions.
-model: inherit
 color: red
 ---
 

package/agents/clasp-deployment-orchestrator.md

@@ -1,7 +1,6 @@
 ---
 name: clasp-deployment-orchestrator
 description: Use PROACTIVELY when creating or deploying Google Apps Script projects with multiple files, complex configuration, or batch operations. Invokes the clasp-deployment skill for command execution.
-model: inherit
 tools: Task, Read, Write, Glob, Grep
 color: green
 ---

package/agents/clean-coder.md

@@ -1,7 +1,6 @@
 ---
 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."
-model: opus
 tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill, SendMessage
 color: green
 ---

package/agents/code-advisor.md

@@ -2,7 +2,6 @@
 name: code-advisor
 description: Single-executor mid-run advisor. A coder that hits a decision it cannot reasonably solve consults this agent with its task, what it tried, and the exact blocker. Returns PLAN, CORRECTION, or STOP as final reply text (not SendMessage). Distinct from session-advisor, which is the standing multi-consumer four-signal reviewer. Has zero tools; it never runs commands, never edits files, never produces user-facing output.
 tools: []
-model: inherit
 color: purple
 ---
 

package/agents/code-quality-agent.md

@@ -1,7 +1,6 @@
 ---
 name: code-quality-agent
 description: Use this agent for comprehensive code quality reviews across multiple files.
-model: opus
 color: red
 ---
 
@@ -175,7 +174,7 @@ Followed by the Shape A finding list, the Shape B proof-of-absence list, and the
 
 ## Caller Context
 
-Callers /bugteam, /qbug, and /findbugs invoke this agent at different models per call (opus for /bugteam, sonnet primary for /findbugs, haiku secondary for both /qbug and /findbugs). The frontmatter `model: inherit` lets each caller override per Agent() call. Persistence files such as `loop-N-audit.json` and `loop-N-diagnostics.json` are the calling skill's responsibility — your output is the structured finding list defined above.
+Callers /bugteam, /qbug, and /findbugs invoke this agent at different models per call (opus for /bugteam, sonnet primary for /findbugs, haiku secondary for both /qbug and /findbugs). The frontmatter carries no `model:` key, so each caller's `Agent()` model applies. Persistence files such as `loop-N-audit.json` and `loop-N-diagnostics.json` are the calling skill's responsibility — your output is the structured finding list defined above.
 
 ## Examples
 

package/agents/code-verifier.md

@@ -1,8 +1,7 @@
 ---
 name: code-verifier
-description: Post-hoc verification agent for the three-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
+description: Post-hoc verification agent for the three-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Never edits files in the tree under review — its one exception is a deliberate break at an off-tree break site outside that tree, defined in its body.
 tools: Read, Grep, Glob, Bash, Task
-model: sonnet
 color: orange
 ---
 
@@ -18,9 +17,10 @@ Run all three layers, in this order:
 
 Findings discipline:
 
-- A finding must cite a failing command (with its output) or a named task item. No citation, no finding.
+- A finding must cite a failing command (with its output) or a named task item. No citation, no finding. `findings` carries code defects alone.
 - Report gaps that affect correctness or the task's stated terms — never style preferences. Sound work produces zero findings; do not invent gaps to look thorough.
-- Never edit a file. You verify; repair agents repair.
+- Never edit a file in the work tree you verify — you verify; repair agents repair. The one exception is a deliberate break for the shown-red table, which goes at one of the off-tree break sites the shown-red section below lists.
+- Never run `git stash`. `refs/stash` belongs to the repository, not to a work tree, so every worktree shares one stash list: a `pop` can apply another verifier's entry into your tree and hand you a surface that is not your assignment. To read the base, add a throwaway detached worktree at the base commit (`git worktree add --detach <temp-path> <base-sha>`), read it there, and drop it with `git worktree remove --force <temp-path>`. You only ever need to read a base tree, and stash moves the very tree you were asked to verify.
 - Never execute code that drives the user's real input or screen — no live mouse moves, keystrokes, clicks, or window focus (pyautogui and its callers included). Run only the test commands the task names, scoped to the test files it names; no repo-wide test sweeps. Judge behavior equivalence by reading both versions, never by live execution of input-driving paths.
 
 Before you write the verdict, learn the surface hash of the work tree you verified. Use the branch mode — it resolves the work tree that holds the branch automatically, so it is immune to your own cwd:
@@ -33,14 +33,42 @@ On Windows the same file sits at %USERPROFILE%\.claude\hooks\blocking\verificati
 
 The printed hash commits to every changed and untracked file's content in the verified work tree, so it names that surface no matter which directory you or the committer run from. If the CLI prints an empty-surface or wrong-work-tree error and no hash, you are pointed at a work tree with no changes versus origin/main — re-run with the branch mode to locate the correct work tree.
 
-As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, and your two-way diff-to-task mapping — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. This pass is always a cold `Explore` spawn, not a message to the session's warm advisor: the refutation needs a grader with no accumulated session context or prior positions, and the verifier runs in sessions that have no advisor bound. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
+As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. A tier denied by policy counts as unreachable, so the walk continues down the ladder to the next tier rather than skipping the validation pass. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, your two-way diff-to-task mapping, and the shown-red table with every deliberate-red run labeled as shown-red evidence so the validator reads it as a staged break rather than a genuine failure — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. This pass is always a cold `Explore` spawn, not a message to the session's warm advisor: the refutation needs a grader with no accumulated session context or prior positions, and the verifier runs in sessions that have no advisor bound. Run that spawn synchronously — set the Task `run_in_background` field to `false` — so the validator's reply lands inside this turn. A background spawn returns straight away and its completion notification arrives after your turn is over, so the reply you are waiting for never reaches you and the verdict fence never gets written. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
 
-This validation pass is terminal: the `Explore` type gives the validation subagent no way to spawn a further agent or edit a file, so it answers with prose only. When it refutes any part, re-check that part yourself against the commands and the diff, and correct the verdict before you emit it. When it refutes nothing, the draft verdict stands. Then emit the fenced verdict block below — it stays the last thing in your message so the verifier_verdict_minter hook reads it.
+Ending your turn without the verdict fence throws the whole run away: every gate you ran and every mapping you built reaches the caller as prose it cannot mint, and the commit gate stays shut on work you already checked. So the fence is unconditional. A validator that returns nothing usable, a tier that never binds, a refutation you accept and fold in — each of those ends the same way, with the fence. When you find yourself about to close on a promise to finish once something reports back, run the refutation pass yourself and emit the verdict.
 
-End your final message with exactly one fenced verdict block — the verifier_verdict_minter hook parses it, binds it to that hash, and the verified_commit_gate hook unlocks `git commit`/`git push` for any work tree whose live surface matches it:
+This validation pass is terminal: the `Explore` type gives the validation subagent no way to spawn a further agent or edit a file, so it answers with prose only. When it refutes any part, re-check that part yourself against the commands and the diff, and correct the verdict before you emit it. When it refutes nothing, the draft verdict stands. Then write your final message.
+
+Your final message runs in one order: the shown-red table, then — only when the verdict is incomplete — the named unshown check, then every `no break available` row named, then the verdict fence last, so the verifier_verdict_minter hook reads it. Every runnable check the verdict rests on gets one row — a runnable check is a layer 1 runnable gate you can execute against the surface. Breakability is not part of that definition: no check leaves the runnable set by being called unbreakable.
+
+| Check | Deliberate break | Red | Green |
+|---|---|---|---|
+| `<command you ran>` | `<break you applied>`, or `no break available — <why no input, no environment, and no scratch-copy mutation can make this check fail>`, or `n/a — check not run` | `<exit code or the deciding line>`, or `no red` | `<exit code or the deciding line>` |
+
+The Deliberate break cell holds exactly one of those three values: the break you applied, `no break available` with its one-line reason, or `n/a — check not run`. Only the first of the three produced a red, so only the first carries a red result in the Red cell. A `no break available` row and an `n/a — check not run` row each carry the literal `no red` there — never an empty cell, never the Green value repeated, and never an exit code, which would make a row that showed no red scan like one that did.
+
+Keep each cell to one line — an exit code, a failing test id, an assert line, or a hook's block message. The Green cell may cite the check's first clean run when you kept that output; a clean result already in hand needs no third run. Longer excerpts go below the table in a plain fenced block carrying no info string.
+
+The reading layers, 2 and 3 above, take no rows. Name in prose what you read and what that reading would catch. A runnable check keeps its row whatever you conclude by reading it, and whatever you conclude about breaking it.
+
+Break the check at an off-tree break site — a site where the break cannot reach the tree you verify: a failing input or environment fed to the check, or a mutated copy in a scratch directory outside that tree.
+
+At either off-tree break site, a check that exercises the changed behavior fails because of the break rather than for an unrelated reason.
+
+Break off-tree so the work tree under verification stays as the coders left it; an in-place break moves the surface `manifest_sha256` names and is forbidden. The green is that same check run against the verified tree.
+
+Every runnable check the verdict rests on gets a row, with no exclusion path: a rested-on runnable check with no row makes the verdict incomplete, and a check you judge unbreakable still owes its row. Where no runnable check the verdict depends on exists, the surface rests on the reading layers alone and carries an empty table, complete. The empty table is for a surface where nothing runnable exists at all, never for one where a runnable check exists and you skipped it. A row carrying `n/a — check not run` is a runnable check you relied on and never showed red, and it makes the verdict incomplete too; its Red cell carries `no red`.
+
+`no break available` is a different claim from `n/a — check not run`: the check ran, and no break exists for it, so its Red cell carries `no red` as well. That row counts complete when it carries the one-line reason naming why no input, no environment, and no scratch-copy mutation can make that check fail, so `all_pass` true stays reachable for a genuinely unbreakable gate. A `no break available` row without that reason is an incomplete row and makes the verdict incomplete exactly as a missing row does.
+
+An incomplete verdict names the unshown check directly above the fence and sets `all_pass` to false. Naming a `no break available` row is a separate matter from that incomplete-check naming: a verdict carrying any `no break available` row names each of those rows directly above the fence because the row carries no red, whether the verdict is otherwise complete or incomplete, and naming one never by itself makes the verdict incomplete or sets `all_pass` false. `findings` goes on carrying every code defect the run found, and is empty only when the run found none.
+
+Write the table as plain markdown; the fence holds JSON alone.
+
+Exactly one fenced verdict block — the verifier_verdict_minter hook parses it, binds it to that hash, and the verified_commit_gate hook unlocks `git commit`/`git push` for any work tree whose live surface matches it:
 
 ```verdict
 {"all_pass": false, "findings": [{"check": "<gate or task item>", "detail": "<command + output, or the named task item and what is missing>"}], "manifest_sha256": "<hash the CLI printed>"}
 ```
 
-Set `all_pass` to true with an empty `findings` list only when every layer came back clean. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Commit-committability gates (CODE_RULES / merge conflicts) must already be green before you are spawned; you are the last semantic check before commit. Any file change after you finish moves that hash and invalidates the verdict.
+Set `all_pass` to true with an empty `findings` list only when every layer came back clean and the shown-red table is complete. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Commit-committability gates (CODE_RULES / merge conflicts) must already be green before you are spawned; you are the last semantic check before commit. Any file change after you finish moves that hash and invalidates the verdict.

package/agents/deep-research.md

@@ -20,7 +20,6 @@ description: Use this agent for iterative, multi-source deep research that produ
   </commentary>
   </example>
 
-model: opus
 color: cyan
 ---
 

package/agents/docs-agent.md

@@ -27,7 +27,6 @@ Examples:
   Non-technical audience — use docs-agent in user-docs writing mode.
   </commentary>
 </example>
-model: inherit
 color: cyan
 ---
 

package/agents/git-commit-crafter.md

@@ -1,7 +1,6 @@
 ---
 name: git-commit-crafter
 description: Use this agent when you need to create git commits, stage changes, or organize multiple file changes into atomic commits. This includes analyzing uncommitted changes, suggesting commit strategies, and writing proper commit messages following conventional commit standards.
-model: inherit
 color: yellow
 ---
 

package/agents/issue-tracker.md

@@ -0,0 +1,42 @@
+---
+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.
+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
+---
+
+# Issue tracker agent
+
+**Caller wants one issue action. You run that action and hand back numbers + URLs.**
+
+**dedup -> one action -> markers only -> numbers + URLs**
+
+You are the primary handler for one action per turn. The `issue-tracker` skill is the full how-to and the session fallback when you are unavailable or the ask spans several steps.
+
+## Warm reuse (callers)
+
+Keep the same warm `issue-tracker` agent for follow-up actions on the **same issue** or a **related issue on the same epic**. Message that agent again with the next action. Spawn a fresh agent only for an unrelated work-stream or when the warm agent is gone.
+
+## Voice
+
+Use the `plain-brief` output style (`output-styles/plain-brief.md`). Final message is issue number(s) and URL(s) only.
+
+## On each turn
+
+1. **Load the skill** if this is the first turn of this agent. Use the Skill tool to load `issue-tracker`. Follow it for markers, dedup, tools, handoff schema, PR auto-close, and gotchas. Do not invent a second path.
+2. **Run the named action.** The ticket names one action: file a sub-issue from an issue-candidate, open an epic, update status in place, refresh the epic checklist, or close a sub-issue. Run that action end to end (every step *that* action needs: labels, attach, checklist refresh when the action creates or closes a child). Do not start a second, unrelated action in this turn.
+3. **Return numbers and URLs.** Affected issue number(s) and URL(s) only, no narration after that payload, so the caller can send the next action to this same agent or spawn another when the work-stream changes.
+
+## Hold these lines
+
+- Dedup open **and** closed before create.
+- Edit only between marker pairs; comments are cross-links only.
+- Attach with REST `.id` and `gh -F`, never display `#N` or `-f`.
+- Prefer GitHub MCP; fall back to `gh` per the skill matrix.
+- When a fix ships: **PR body first** for auto-close. On the PR that merges into the **default branch**, put `Closes #N` for each finished sub-issue (`Closes #12` and `Closes #13`, not `Closes #12, #13`). Prefer the same line on the first commit. Stacked PRs that are not default-branch merges use plain `#N` only. A related UI link without a closing keyword does not close the issue. You own picking the correct `#N`.

package/agents/plan-packet-validator.md

@@ -2,7 +2,6 @@
 name: plan-packet-validator
 description: Fresh-context validator for workflow-generated plan packets. Use after a plan packet is written under docs/plans/<slug>/ to verify source accuracy, completeness, TDD readiness, scope control, handoff quality, and no invented repo behavior. Read-only; never edits files.
 tools: Read, Grep, Glob, Bash
-model: inherit
 color: purple
 ---
 

package/agents/pr-description-writer.md

@@ -2,7 +2,6 @@
 name: pr-description-writer
 description: "Optional agent for PR descriptions and PR comments. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`, and pass the `pr_description_enforcer` PreToolUse hook's body audit on `gh pr create`, `gh pr edit`, and `gh pr comment`."
 tools: Read,Grep,Glob,Bash
-model: haiku
 ---
 
 # PR Description Writer

package/agents/test_agent_frontmatter.py

@@ -5,47 +5,79 @@ Code subagent loader reads. The loader accepts a fixed key set; an unrecognized
 top-level key breaks the spawn — the subagent starts with a broken definition,
 idles, and dies without a report::
 
-    ok:   name / description / tools / model / color
+    ok:   name / description / tools / color
     flag: effort            <- unrecognized, subagent dies delivering nothing
 
-The accepted set is the one `agents/CLAUDE.md` documents (name, description,
-tools, color) plus the `model` pin the working agents carry (clean-coder pins
-opus, pr-description-writer pins haiku). Top-level keys are read with a line
-scan so an agent whose `description` embeds informal `<example>` prose is not
-mistaken for one carrying extra keys.
+An agent definition carries no `model` key at all — the caller supplies the
+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: opus       <- pinned concrete model, caller can't override
+
+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
+informal `<example>` prose is not mistaken for one carrying extra keys.
 """
 
 from __future__ import annotations
 
 import re
+from functools import cache
 from pathlib import Path
 
 import pytest
 import yaml
 
-ACCEPTED_FRONTMATTER_KEYS = frozenset(
-    {"name", "description", "tools", "model", "color"}
-)
-FRONTMATTER_FENCE = "---"
-FRONTMATTER_SEGMENT_COUNT = 3
+ACCEPTED_FRONTMATTER_KEYS = frozenset({"name", "description", "tools", "color"})
 CODE_VERIFIER_AGENT_NAME = "code-verifier"
+EXEMPT_MARKDOWN_FILENAME = "CLAUDE.md"
+FRONTMATTER_FENCE_LINE = "---"
+MODEL_KEY_NAME = "model"
 TOP_LEVEL_KEY_PATTERN = re.compile(r"^([a-z][a-z0-9_]*):", re.MULTILINE)
 
 
-def _agent_definition_paths() -> list[Path]:
+def _extract_frontmatter_block(markdown_text: str) -> str | None:
+    """Return the YAML text between the file's opening and closing --- fences.
+
+    Args:
+        markdown_text: The full text of an agent definition markdown file.
+
+    Returns:
+        The frontmatter text (the lines strictly between the two fence
+        lines), or None when the file does not open with a --- fence line or
+        never closes one.
+    """
+    all_lines = markdown_text.splitlines()
+    if not all_lines or all_lines[0].strip() != FRONTMATTER_FENCE_LINE:
+        return None
+    for each_line_index in range(1, len(all_lines)):
+        if all_lines[each_line_index].strip() == FRONTMATTER_FENCE_LINE:
+            return "\n".join(all_lines[1:each_line_index])
+    return None
+
+
+@cache
+def _agent_definition_paths() -> tuple[Path, ...]:
     agents_directory = Path(__file__).parent
     all_markdown_files = sorted(agents_directory.glob("*.md"))
-    return [
+    return tuple(
         each_markdown_file
         for each_markdown_file in all_markdown_files
-        if each_markdown_file.read_text(encoding="utf-8").startswith(FRONTMATTER_FENCE)
-    ]
+        if each_markdown_file.name != EXEMPT_MARKDOWN_FILENAME
+        and _extract_frontmatter_block(each_markdown_file.read_text(encoding="utf-8"))
+        is not None
+    )
 
 
 def _frontmatter_block(agent_definition_path: Path) -> str:
-    agent_text = agent_definition_path.read_text(encoding="utf-8")
-    fence_segments = agent_text.split(FRONTMATTER_FENCE, FRONTMATTER_SEGMENT_COUNT - 1)
-    return fence_segments[1]
+    frontmatter_block = _extract_frontmatter_block(
+        agent_definition_path.read_text(encoding="utf-8")
+    )
+    assert frontmatter_block is not None
+    return frontmatter_block
 
 
 def _top_level_keys(frontmatter_block: str) -> set[str]:
@@ -76,3 +108,20 @@ def test_code_verifier_frontmatter_parses_and_names_the_agent() -> None:
     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",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_carries_no_model_key(
+    agent_definition_path: Path,
+) -> None:
+    frontmatter_block = _frontmatter_block(agent_definition_path)
+    declared_keys = _top_level_keys(frontmatter_block)
+    assert MODEL_KEY_NAME not in declared_keys, (
+        f"{agent_definition_path.name} carries a model: key in frontmatter; "
+        "the caller supplies the model on every spawn, so agent definitions "
+        "carry no model key at all, not even model: inherit"
+    )