docs(scripts): correct check-agent-model-declared's model-resolution header to four steps

[os-project-manager]

Fixes #6879

What

scripts/check-agent-model-declared.mjs's WHY-THIS-EXISTS header described Claude Code's subagent model resolution as three steps (model argument → frontmatter → inherit) and never mentioned CLAUDE_CODE_SUBAGENT_MODEL, the environment variable that outranks all three.

This PR corrects the header to the real four-step order:

1. the CLAUDE_CODE_SUBAGENT_MODEL environment variable, when set
2. the per-invocation model parameter on the Agent call
3. the agent definition's model: frontmatter
4. the main conversation's model

and adds the neighbouring, smaller note: a value blocked by the organization's availableModels allowlist falls back to the inherited model, not to the frontmatter pin.

The wording is kept consistent with the four-step order already written into .claude/agents/os-dev.md by PR #6871 (that file is out of this PR's surface — a separate card, #7055, owns it).

Why (from the issue)

The gate's whole thesis is that a role's tier is a property of the role, not of whoever dispatched it. CLAUDE_CODE_SUBAGENT_MODEL defeats that thesis silently — the gate still reports green because the frontmatter is still declared — and the header is the first document an investigator reads if that variable ever stops being unset. Observation-class finding; no user hits it today (verified at filing time: the variable is unset in the dispatch container and referenced nowhere under .claude/).

Scope

Comment-only. No behaviour change. The gate deliberately asserts only that the model: slot is non-empty (#6803 put "which tier is correct" out of its scope); this PR does not add any assertion about the environment variable or about tier correctness — doing so would be exactly the scope creep the issue calls out.

git diff confirms every changed line is a // comment line; no code, no self-test case, no CI wiring touched.

Verification

• pnpm check:agent-model-declared (self-test + real run against .claude/agents/) — green, unchanged from before the edit.
• node scripts/check-nul-bytes.mjs — green.
• Manual self-scan (grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' scripts/check-agent-model-declared.mjs) — no hits.

Changeset

None. This is a scripts/-only comment change that releases no package (repo precedent: #7048, #7008, #7104, #7106). skip-changeset label applied.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 1:18am

[os-project-manager]

HELD — not accepted yet. Staying draft until the two gates that carry the check:* family are accounted for.

The substance is fine and already independently verified by the PM, so this is not a rework request:

• Comment-only claim confirmed from the branch, not from the report: 23 changed lines on origin/claude/issue-6879-model-resolution-header, every one a // line, zero non-comment changes. ✅
• Four-step order, the allowlist-fallback note, wording aligned with .claude/agents/os-dev.md, skip-changeset applied and read back. ✅
• Honest reporting: in_progress reported as in_progress, and the local checks that were not run were named rather than papered over. That is the behaviour the loop wants.

⚠️ The hold is a gate-accounting problem, and it is a false-green shape I had not hit before. Querying the workflow runs on head ccd14e87d returns 7 runs, all success or skipped, zero non-green — which reads as "green" if you count non-green entries. But Lint & Type Check is not in the list at all:

ADR Merge Approval, CI, Check Links, Console Pin Freshness,
Duplicate Fix Guard, PR Automation        ← no "Lint & Type Check"

That workflow is the one carrying ESLint and TypeScript Type Check, i.e. the whole check:* family, and the implementer's own last read had both as in_progress. The three PRs merged ahead of this one (#7104, #7106, #7108) all had Lint & Type Check present in their run lists, so its absence here is anomalous rather than normal for this repo — most likely API lag between the check runs the implementer could see and the workflow-run records I read.

An absent required gate is not a passing gate. "Zero non-green" answers a different question from "every required gate reported". Accepting on the first reading would arm auto-merge on a PR whose type-check and lint state is simply unknown.

This is the third distinct false-green shape this seat has hit today, and they fail in different directions:

1. pull_request_read → get_status returns only the legacy commit-status API — on these PRs a single Vercel entry, total_count: 1, no check runs at all.
2. in_progress counted as not-a-failure.
3. This one — a required workflow missing from the run list entirely, so a non-green count of zero is satisfied vacuously.

Next check re-reads the runs for this head and looks for Lint & Type Check by name; ready + auto-merge follow only once it reports a conclusion. No action needed from the implementer — it has stood down correctly.

---

Generated by Claude Code

[os-project-manager]

Hold released — ACCEPT. Flipping ready and arming auto-merge.

Lint & Type Check now reports on head ccd14e87d:

REQUIRED "Lint & Type Check": completed/success
REQUIRED "CI":               completed/success

So the hold was API lag between the check runs the implementer could see (in_progress) and the workflow-run records the PM reads — not a missing or failing gate. The hold was still the right call: at the moment I read it, the run was absent, and an absent required gate and a passing one are not the same fact. Waiting cost about four minutes; accepting on "zero non-green" would have armed auto-merge on a PR whose lint and type-check state was genuinely unknown to me.

Full accounting on this head, gates named rather than counted: Lint & Type Check success, CI success, ADR Merge Approval success, Console Pin Freshness success, Check Links success, Duplicate Fix Guard success, PR Automation skipped. Zero non-green, and — the part that matters — nothing required is missing.

Substance was already verified independently before the hold: 23 changed lines, every one a // comment, zero non-comment changes, which was this card's hard constraint.

Worth noting for the record, since it is the behaviour the dispatch loop wants: after being told to stop polling, the implementer returned a report that named ESLint and TypeScript Type Check as in_progress rather than rounding them up, and explicitly listed what it had not run locally (pnpm install, full-repo ESLint, typecheck) with the reason — scripts/ sits outside every package's tsconfig, so a package-scoped typecheck would not have covered this file anyway. An honest in_progress plus a named gap is more useful than a green obtained an hour later.

---

Generated by Claude Code