docs(ci): say why the skip-actors line must survive a re-pin

[kyle-sexton]

No linked issue — this closes nothing. #1767 stays open deliberately: its residual gap is
structural (runner-policy cannot require an input), and a comment guards against a careful
reviewer, not an inattentive one. Closing it on a documentation change would record the gap as
fixed when it is not.

What

Seventeen lines of comment above skip-actors in
.github/workflows/claude-security-review.yml. No value changes; the actor list stays at the
ratified four.

Why

The existing comment says the list is stated explicitly rather than inherited, and records how
#1766 widened it. It does not say why deleting the line is unsafe when its value matches the
upstream default of the moment — which is the only state in which a reviewer is tempted to delete
it, and precisely the state #1766 was in.

Two things the re-pin reviewer needs and the comment did not carry:

• Deleting is not a no-op at parity. The four actors are ADR 0002's 2026-08-04 ratified
  baseline. Inheriting re-delegates that ratification to whatever ci-workflows ships next, and
  every actor in an inherited default satisfies this repo's REQUIRED
  security-review / security-review check with no review run, on security-sensitive paths.

• The failure directions are asymmetric, which is what makes explicit correct here without
  contradicting the fleet's inheritance-over-explicit-list default elsewhere. A stale explicit list
  fails CLOSED and LOUD — for an actor the reusable's allowed_bots does not permit, the action
  throws and the fail-closed mapping turns that into a red required check no push can fix. A stale
  inherited default fails OPEN and SILENT — an actor this repo never deliberated skips review with
  CI green. Loud-and-blocking is the direction to fail in; silent-and-permissive is not.

  The first draft of this comment described the closed direction as "an actor gets a review it may
  not have needed — visible, cheap." That was wrong, and review caught it: ADR 0002's
  skip-actors-vs-allowed_bots section records that removing an actor from skip-actors alone
  does not restore review of its PRs — it blocks the merge. Corrected in the second commit, which
  also notes that un-skipping an actor for real requires widening allowed_bots upstream, so
  removing a name here is never a one-line change.

The comment also names standards#308 at the point of use: runner-policy rejects inputs outside the
reviewed contract but cannot require one, so dropping this line re-widens the exception with CI
green and nothing said.

Provenance

Salvaged from PR #1845, which I closed as superseded. That branch re-narrowed the exception to two
actors on 2026-07-31; the 2026-08-04 addendum records an explicit operator decision ratifying four
and names four as the baseline future additions are measured against, having weighed the two-actor
case on its merits. The narrowing is therefore correctly dead — but the branch's comment block was
the better explanation of an invariant that survives the ruling either way, so it is ported here
with the actor list left alone.

Verification

• actionlint clean on the changed file.
• The skip-actors value is byte-identical before and after — confirmed by reading the parsed line
  back, not by eye.
• Comment-only diff: 17 insertions, 0 deletions.

Related

• Re-deliberate ADR 0002: skip-actors inheritance widens the security-review exception to claude[bot] and melodic-ai[bot] #1767 — the re-deliberation issue this comment serves; left open, since the residual
  requiredInputs gap is not closed by a comment.
• fix(ci): re-narrow the security lane's skip-actor exception to two actors #1845 — the superseded branch this is salvaged from.
• ci: re-pin claude lane callers to v0.9.1, adopt paths-file, serialize the review lane #1766 — the re-pin that dropped the line and silently widened the exception.
• docs/adr/0002-default-on-ai-review-advisory-with-earned-promotion.md — the 2026-08-04 addendum
  that ratified four actors.
• feat(runner-policy): a requiredInputs contract field, so a dropped caller input cannot pass silently standards#308 — the requiredInputs-style contract field that would make this
  structurally enforced rather than comment-enforced.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 73b7b4b709

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 56s —— View job

---

Review complete ✅

• Gather context (read diff, changed file, referenced docs)
• Understand the request (code-review lane trigger on PR open)
• Review the comment-only diff for correctness and alignment with CLAUDE.md / REVIEW.md
• Post findings

Summary

This PR adds 17 comment lines above skip-actors in
.github/workflows/claude-security-review.yml.
Verified locally:

• git diff origin/main...HEAD for this file contains zero removed lines — the change is
  purely additive, confirming the PR's "comment-only, 17 insertions / 0 deletions" claim.
• The skip-actors value on line 61 is unchanged: dependabot[bot],claude[bot],melodic-ai[bot],melodic-standards-sync[bot].
• Every factual claim in the new comment checks out against
  docs/adr/0002-default-on-ai-review-advisory-with-earned-promotion.md: the four-actor set matches the 2026-08-04 addendum's ratified baseline (line 269), the "silence would have ratified four, operator instead made an explicit pick" framing matches the addendum text (lines 262–264), and the runner-policy rejects-but-cannot-require-inputs characterization matches the ADR's own description (lines 104, 142–144).
• The required check name security-review / security-review matches existing usage elsewhere in the ADR and PLAN.md.
• New comment lines stay ≤ 80 chars, consistent with the file's existing wrapped-comment style (checked with grep -n '.\{81,\}').
• No actionlint binary is available in this sandbox, so the PR's "actionlint clean" claim is author-claimed and unverified by me — I did not independently confirm it.
• This is a comment-only change to a repository CI workflow (not a plugin manifest, marketplace schema, hook contract, or plugin-component contract surface), so CLAUDE.md's fresh-docs mandate does not apply here.
• Per REVIEW.md, this repo runs a dedicated security lane (claude-security-review.yml exists), so this code-review lane correctly excludes security findings — moot anyway, since there's no security-relevant change here (no state writes, no auth/authz path, nothing for the atomicity or audit-log checks to apply to).

No correctness, design, or maintainability issues found. The new comment is accurate, non-duplicative of the existing header comment (lines 38–43 explain why explicit; the new lines explain why deletion-at-parity is unsafe and the asymmetric failure-direction rationale — genuinely new information), and consistent with the file's dense ADR-referencing comment style already established at lines 3–16.

I have no inline findings to raise — the diff is comment-only and every claim within it is traceable and correct.

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 1m 58s —— View job

---

Code Review

• Gather context (PR diff, files, CLAUDE.md/REVIEW.md)
• Understand request (code-review lane: correctness, design, conventions, error handling, observability, docs — security findings excluded per REVIEW.md, since claude-security-review.yml exists and owns that scope)
• Review changed file (.github/workflows/claude-security-review.yml)
• Check whether Codex's prior finding is already addressed
• Post findings

Scope note: this PR is a pure comment addition to a GitHub Actions workflow file — no skip-actors value change, no plugin manifest/marketplace/hook contract touched, so the fresh-docs mandate's plugin-contract scope doesn't apply here. My lane's checks (observability audit-log completeness, multi-write atomicity) don't apply to a comment-only diff either.

Codex's finding (P2, "Correct the stale-list failure mode") is already resolved. It was raised against commit 73b7b4b, which described the closed-list failure as "an actor gets a review it may not have needed — visible, cheap." The second commit, 16b0a81, rewrites that passage to say a stale explicit list "fails CLOSED and LOUD" and turns the required check red — matching ADR 0002's addendum (docs/adr/0002-default-on-ai-review-advisory-with-earned-promotion.md lines 168–173, verified by reading the file) that removing an actor from skip-actors alone does not restore review, it blocks the merge. Confirmed by diffing the two commits directly (git diff 73b7b4b 16b0a81) — the only substantive change between them is exactly this correction. No further action needed on that thread.

Independent verification performed:

• git diff origin/main...HEAD -- .github/workflows/claude-security-review.yml: 23 insertions, 0 deletions, matching the PR's stated diff shape.
• Diffed the base commit against HEAD with the #-comment lines filtered out — zero non-comment diff, confirming the skip-actors: value line itself is untouched (the PR's "byte-identical value" claim, independently confirmed rather than taken on the author's word).
• CI's ci job (which runs actionlint, per .github/workflows/ci.yml) passed on this HEAD — independent confirmation of the PR's actionlint claim, not a restatement of it.
• Cross-checked the comment's claims about the 2026-08-04 ratified four-actor baseline and the skip-actors/allowed_bots asymmetry against docs/adr/0002-...md directly; both check out.

No new findings. The added comment is accurate against the ADR, consistent with the actual commit history (#1766, #1845, #1766's re-pin), and stays within a comment-only diff with no behavior change. One very minor, sub-nit-level observation not worth a blocking comment: .github/workflows/claude-security-review.yml:57 cites (ADR 0002, "skip-actors and the action's allowed_bots are different levers") in quotes as if it were a section heading, but that phrase is a paraphrase of a sentence in the ADR body (permalink) — the ADR has no heading by that name. Doesn't affect correctness since the underlying claim is accurate; flagging only in case the author wants the citation style to read as a paraphrase rather than a quoted heading.