ci: take review instructions from the default branch, and gate self-approval (#132)

* ci: take review instructions from the default branch, and gate self-approval

Moves the review prompt out of claude-code-review.yml into
.github/review-prompt.md, materialized from the default branch at review time.
Prompt edits then neither trip claude-code-action's anti-tamper gate nor
influence the review of the PR making them. PR #131 is what prompted this: 38
files of ADR migration were blocked from review by a four-line prompt edit.

A security review of the first draft found the naive materialization was itself
exploitable, and that is fixed here rather than shipped:

- git show "origin/$DEFAULT_BRANCH:..." takes an UNQUALIFIED refname, and
  gitrevisions(7) resolves refs/tags/<name> before refs/remotes/<name>. With
  fetch-depth: 0 fetching all tags, a tag named "origin/main" would supply the
  review instructions for every PR, exiting 0 with only a stderr warning.
  Reproduced end to end. Now resolves refs/remotes/origin/<default> to a SHA,
  logs it, and reads by SHA.
- CLAUDE.md is materialized from the default branch too. The prompt judges
  against its Key Conventions list, so reading it from the PR checkout let a PR
  edit the list to permit its own violation.
- A PR touching review-prompt.md, .github/workflows/ or CLAUDE.md now has any
  claude[bot] APPROVED dismissed via the API and the check failed. Prose alone
  cannot protect the root of trust.
- The sentinel is grepped in the materialize step rather than only asserted by
  the model it protects.
- Fork PRs are skipped, not failed. A required check permanently red on outside
  contributions trains the operator to override red checks.

Also drops track_progress and gh pr comment so the review body and inline
comments are the only channel, and adds actions: read plus gh pr checks / gh run
view so the reviewer can verify build and test claims against CI's own result.
It deliberately gets no build or test tools: those execute PR-authored code in a
job that can approve the PR.

ADR 0025 records the decision.

* ci: fix three defects found in second-opinion review

- Job-level 'actions: read' was missing. An explicit permissions block sets
  every unlisted permission to none, so additional_permissions: actions: read
  on the action alone granted nothing and the reviewer could not have read the
  check runs it was just told to verify claims against. Athena has both; only
  the action-level half was copied.

- The governance detector checked review-prompt.md, .github/workflows/ and
  CLAUDE.md, while review-prompt.md told the reviewer DECISIONS.md and
  docs/decisions/ were mechanically covered too. A PR adding an ADR could
  escape the guard it was promised to be under. Detector now covers both, which
  means every ADR PR needs operator approval — that is the intended reading of
  ADR 0023, since the reviewer defers to ADRs as precedent.

- The formal-review check counted ANY historical claude[bot] review, so a
  re-run after a new push went green on a verdict about the previous commit.
  Now scoped to the head SHA. Pre-existing, fixed here because the file was
  already open.

Adds a fork-notice job. A skipped job reports its required check as PASSING, so
skipping the review on fork PRs made them green with nothing reviewed and no
trace of why; the notice puts it in the run summary.

Prompt: pending checks are a race, so say unverified rather than reporting a
queued check as a failure; and defer-to-operator maps to --comment, not
--request-changes.

* ci: withhold approval on review-governing PRs, not the review itself

Operator ruling: Claude should still review the protected files and report what
it finds; only the power to approve is reserved.

The gate failed the check unconditionally whenever a PR touched a governance
path, even when the reviewer had correctly submitted COMMENTED. That discarded a
review that was wanted, and made a red check the normal outcome for a whole
class of PR — training exactly the merge-past-red habit the fork-notice change
exists to avoid.

Now: a COMMENTED deferral passes, with a notice saying the check is green
because the reviewer behaved, not because the PR is approved. Merge still waits
for the operator, since COMMENTED does not satisfy branch protection. The step
fails only when claude[bot] actually approved — that approval is dismissed and
the red check records the disobedience.

ADRs stay in the protected set, per the same ruling.

* ci: close a green-with-live-approval hole and widen the governance detector

Third security pass. The two that mattered:

- Both review queries were unpaginated. GitHub returns 30 reviews oldest-first,
  so an approval submitted now sits on page 2 of any PR that already has 30
  review objects — the withhold step would find nothing, print 'reviewer
  behaved correctly' and exit 0 green while the approval stood and satisfied
  branch protection. Reachable without an attacker: every inline comment
  creates a review object. Both queries now --paginate.

- The detector covered CLAUDE.md but not .claude/, .mcp.json, AGENTS.md, or
  nested CLAUDE.md. .claude/settings.json is tracked and .gitignore had no
  claude entry, so a PR could add .claude/settings.local.json - which outranks
  settings.json - carrying env (redirect model traffic) or hooks (arbitrary
  shell in the job holding the approval token). Those are read by the runtime
  before the model starts, so no prompt-level rule can defend against them.
  Added to the detector and to .gitignore.

Also: dismissal now matches .user.type == 'Bot' rather than the claude[bot]
login literal, so an approval from another App is not invisible; the test
fixtures, psd1 and CHANGELOG join the detector, since the prompt already
reserved release tagging to the operator and did not enforce it; a failed
dismissal says so loudly instead of aborting silently under bash -e and
claiming success; the pre-review notice no longer promises a red check on the
path that goes green; show-ref --verify replaces rev-parse, which still DWIMs
on a ref that does not exist; and a concurrency group stops two runs
interleaving dismissals.

Dropped the '@claude re-review' suggestion from the fail-closed message: it
pointed at an ungated workflow on exactly the PRs where approval is reserved.

ADR 0025 now states the premise the whole design rests on - that code-owner
review is off, deliberately, because enabling it would end bot merging - and
records claude.yml as an open second path to a binding approval.

* ci: narrow CODEOWNERS so code-owner review becomes usable

Operator's suggestion, and it is better than what ADR 0025 previously recorded.

CODEOWNERS was '* @goodolclint'. At that breadth 'Require review from Code
Owners' is unusable — it would demand the operator on every PR and end the
verdict-gated merge loop — which is why the setting is off and why the
self-approval guard had to live in the workflow.

Narrowed to the governance and release paths only, matching the detector. An
ordinary PR has no code owner and an automated approval still merges it; a PR
touching what governs review or what gets published requires the operator.

That makes the setting safe to enable, and GitHub then enforces the property
better than the workflow step can: not one-shot, no pagination limit, no bot
identity to match, no dismissal permission needed, and it covers an approval
from any source — including claude.yml, the ungated second path the dismissal
step cannot see.

Enabling the setting is the operator's action, not this commit's. Until then
the workflow gate remains load-bearing, and it stays either way as
defence-in-depth. Both files carry a keep-in-sync note; drift is silent in the
direction that matters.

ADR 0025 records the edge case: GitHub does not let an author approve their own
PR, so an operator-authored governance PR would need admin enforcement toggled
or to go through the bot.

* ci: stop the green-path notice claiming more than it checked

Third-party re-review: the empty-id branch announced 'It reviewed and deferred,
as intended', but an empty list only means no automated APPROVED was found. It
cannot distinguish a deferral from CHANGES_REQUESTED, from no verdict, or from
no review at all — that a formal review exists at this head SHA is established
by the verify step, not this one. The notice now says what was actually
checked, and says plainly that green does not mean approved or adequately
reviewed.

ADR 0025 said a prompt edit 'gets a red check', contradicting its own statement
two paragraphs earlier that a deferral passes. Corrected, and it now records
the one governance path that genuinely gets no review: this workflow itself,
where the action's anti-tamper gate means there is no verdict to observe.

---------

Co-authored-by: goodolclint-claude[bot] <323206664+goodolclint-claude[bot]@users.noreply.github.com>

docs/decisions/0025-review-instructions-come-from-the-default-branch-and-review-governing-prs-cannot-self-approve.md

@@ -0,0 +1,82 @@
+# ADR 0025 — Review instructions come from the default branch, and review-governing PRs cannot self-approve
+
+- **Status:** Accepted
+- **Date:** 2026-09-02
+- **Deciders:** operator + agent
+- **Context source:** PR #131 blocked by the anti-tamper gate; security review of the fix, 2026-09-02
+
+## Context
+
+`claude-code-action` submits a binding review verdict, and on this repository a `claude[bot]` **APPROVED** satisfies branch protection. An approval merges code, which makes the reviewer a high-value target.
+
+The action carries an anti-tamper gate: it self-skips when the PR's copy of `.github/workflows/claude-code-review.yml` differs from the default branch, and the fail-closed step turns that into a red check. That is correct, but it made the review prompt effectively uneditable — PR #131 had 38 files of ADR migration blocked from review by a four-line prompt change.
+
+Moving the prompt into `.github/review-prompt.md` and materializing it from the default branch fixes that. A security review of the first draft found the naive form of that materialization was itself exploitable, and that the guarantee's scope was narrower than its comments claimed.
+
+## Decision
+
+**Instructions come from the default branch, addressed by SHA.** The materialize step resolves `refs/remotes/origin/<default>` to a commit and reads both `.github/review-prompt.md` and `CLAUDE.md` from it.
+
+The ref is fully qualified deliberately. `git show "origin/main:<path>"` is an **unqualified** refname, and `gitrevisions(7)` resolves `refs/tags/<name>` *before* `refs/remotes/<name>`. `actions/checkout` with `fetch-depth: 0` fetches all tags, so a tag literally named `origin/main` supplies the review instructions for every subsequent PR — exiting 0 with only a stderr warning, so it does not fail closed. Reproduced end to end on 2026-09-02.
+
+**`CLAUDE.md` is materialized too.** The prompt judges convention compliance against the "Key Conventions" list. Read from the PR checkout, a PR could edit that list to permit its own violation, so the reviewer is pointed at the default branch's copy.
+
+**A PR that governs review cannot auto-approve itself.** A step diffs against the default branch for `.github/review-prompt.md`, `.github/workflows/**`, `CLAUDE.md`, `DECISIONS.md` and `docs/decisions/**`. On a match, the review still runs and its findings are still wanted — the only thing withheld is the power to approve.
+
+The expected verdict on such a PR is `COMMENTED`, which the prompt asks for and which does not satisfy branch protection, so merge waits for the operator regardless. The gate **passes** in that case: the reviewer behaved correctly. It fails only when `claude[bot]` actually submitted `APPROVED`, which means either a successful injection or plain non-compliance — that approval is dismissed through the API so it cannot satisfy branch protection, and the red check records that it happened.
+
+Operator ruling 2026-09-02: withhold approval, not review. An earlier draft failed the check unconditionally on these PRs, which threw away a review that was wanted and made red the normal outcome for a whole class of PR — training the merge-past-red habit that the fork-notice change exists to avoid.
+
+`docs/decisions/` is in that list deliberately, and it has a cost: **every ADR now needs operator approval.** That follows from what the ADRs became in [ADR 0023](0023-decisions-live-in-docs-decisions-in-house-adr-format.md) — the reviewer is told to defer to them as recorded precedent, so a PR that adds an ADR and then leans on it is the fabricated-precedent attack. The prompt separately instructs the reviewer to treat an ADR added by the PR under review as a claim rather than settled precedent; the dismissal makes that mechanical instead of advisory. `CHANGES_REQUESTED` and `COMMENTED` are left standing — they do not unblock a merge, and their content is still useful.
+
+**The sentinel is checked mechanically.** `grep -qx PSPROXMOXVE-REVIEW-V1` runs in the materialize step, before Claude starts, rather than only being asserted by the model the sentinel exists to protect.
+
+**No build or test tools.** The reviewer verifies build and test claims by reading the check runs for the same SHA (`gh pr checks`, `gh run view`, with `actions: read`), never by running the suite.
+
+## Rejected alternatives
+
+**`pull_request_target`.** It runs the workflow from the base branch, which would satisfy "always use main" directly. Rejected: it hands a write-scoped token and secrets to a context where PR-authored code is checked out, and the action can run Bash. It is the single most catastrophic misconfiguration in this class.
+
+**Granting `dotnet build`, `dotnet test` and `pwsh -Command Invoke-Pester`,** which the reviewer asked for on PR #131 so it could verify the test counts itself. Rejected: `dotnet test` executes test code from the branch under review and `dotnet build` runs MSBuild targets that can `Exec` arbitrary commands, in a job holding a token that can approve the PR. That converts probabilistic prompt-injection influence into deterministic control. CI already ran those suites on the same SHA; reading the result is both safer and better evidence.
+
+**Prose alone for the governance rule.** The first draft relied on a "defer to the operator" instruction in the prompt. A soft control cannot protect the root of trust: one successful injection, or plain non-compliance, would convert into persistent control of every future review.
+
+**Leaving the prompt inline in the workflow.** Maximally tamper-proof — the anti-tamper gate covers it — but it blocks unrelated work, which is what prompted this.
+
+## Consequences
+
+Prompt edits no longer trip the anti-tamper gate, but they do trip the governance gate: a PR changing `review-prompt.md` is reviewed, cannot be auto-approved, and needs the operator's approval to merge. Its check goes **green** when the reviewer defers correctly — the red is reserved for an automated approval that had to be dismissed. That is the intended trade: routine work is unblocked, changes to the reviewer are not.
+
+One member of the governance set behaves differently, and it is this workflow itself. A PR editing `.github/workflows/claude-code-review.yml` trips `claude-code-action`'s own anti-tamper gate, so no review runs at all and the fail-closed step reds the check. "The review still runs" above is true of every governance path except that one.
+
+**Bootstrap:** the PR introducing this fails its own materialize step, because `review-prompt.md` is not yet on the default branch. It is red regardless, since it also edits the workflow. Confirm the next PR after merge goes green.
+
+Fork PRs are skipped rather than failed. Previously they would have gone red with a message blaming the anti-tamper gate, and a required check that is always red on outside contributions trains the operator to override red checks — the habit the governance gate depends on not existing.
+
+The trade is that GitHub reports a skipped required check as **passing**, so a fork PR shows green `claude-review` with nothing reviewed. A `fork-notice` job runs in its place and puts that in the run summary, but the green check is real and misleading on its own. Fork PRs are operator-reviewed by policy.
+
+**`CODEOWNERS` is narrowed so that code-owner review becomes usable.**
+
+The security review observed that branch protection's "Require review from Code Owners" would make every bypass in this area inert, because `claude[bot]` is not a code owner and its approval could never satisfy protection. It also observed that the setting is **off** — verified on PR #100, where `mergeable_state` reached `clean` on the bot's approval alone.
+
+The reason it was off is that `CODEOWNERS` was `* @goodolclint`. At that breadth the setting is unusable: it would require the operator on *every* pull request and end the verdict-gated merge loop, so the guard had to be built in the workflow instead.
+
+Operator ruling 2026-09-02: narrow the ownership rather than accept the weakness. `CODEOWNERS` now names only the governance and release paths — the same set the detector checks. Ordinary PRs have no code owner and an automated approval still merges them; a PR touching what governs review or what gets published requires the operator.
+
+This inverts the design. With the setting enabled, GitHub enforces the property, and it enforces it far better than the workflow step can: it is not a one-shot check, it has no pagination limit, it does not depend on matching the right bot identity, it needs no dismissal permission, and it applies to an approval from **any** source — including `.github/workflows/claude.yml`, the ungated second path noted below, which the dismissal step cannot see.
+
+The workflow gate stays, as defence-in-depth and as the only control while the setting is off. **Enabling the setting is the operator's action and is not done by this decision.** Until it is, the dismissal step is still load-bearing and should be read that way.
+
+The two lists must be kept in sync; both files say so. Drift is the failure mode, and it is silent in the direction that matters — a path in the detector but not in `CODEOWNERS` is protected only by the weaker mechanism.
+
+One edge case is worth knowing before enabling the setting: **GitHub does not let an author approve their own pull request.** An operator-authored PR touching a governance path would have no eligible code-owner reviewer, and with admin enforcement on there is no bypass. In practice every recent PR is authored by `goodolclint-claude[bot]`, so the operator is free to approve; but an operator-authored governance change would need admin enforcement toggled, or to go through the bot.
+
+Three limits remain, and are not closed by this decision:
+
+- **`.github/workflows/claude.yml` is a second, ungated path to a binding approval.** It runs the same action on any `@claude` mention with `contents: write` and no `allowedTools` restriction, no materialized prompt, and no governance detection — so its standing instructions are the repository `CLAUDE.md` *from the PR's checkout*, the exact file this workflow materializes from the default branch to avoid. An approval produced there is never dismissed, because the gate here is a one-shot check inside this job and `pull_request` does not fire on review submission. Filed separately; not fixed here.
+
+- `Bash(gh api:*)` is broad enough to reach endpoints the narrower `gh pr *` grants exclude, so the tool allowlist is a guardrail for a cooperating agent, not a sandbox for a hijacked one. The real bound is the Claude App installation's permissions.
+- `docs/decisions/` is still read from the PR checkout rather than materialized. The prompt instructs the reviewer to treat an ADR added or edited by the PR under review as a claim, not as settled precedent, and the dismissal gate above backs that mechanically.
+- The formal-review check is scoped to the head SHA, so a re-run cannot pass on a verdict about an earlier commit. It had counted any historical `claude[bot]` review; that predates this decision and was fixed alongside it.
+
+The same unqualified-ref defect exists in `~/Source/Athena/.github/workflows/claude-code-review.yml`, which this workflow was adapted from.