feat(repo): make an /archon-pr-review run identifiable, and give it an unattended mode

[orioltf]

Fixes #357.

Why

An /archon-pr-review run left no trace that a machine ran it, and it could not run without a human.

Its two comments arrive under the maintainer's own gh credential, carry no HTML marker, and are told apart only by a heading. That heading identifies nothing: 120 of this repository's 135 pull-request comments open with one, in 24 distinct shapes, and # 🔍 Comprehensive PR Review spans 40 pull requests of which only five ever carried an archon-comprehensive-pr-review run. PR #307 carries it twice, from two different workflows. A check keyed on a heading anyone can type is a check a paste can satisfy — the shape docs/process/ai-development.md:51 names.

The workflow also posts no PR review, so nothing reading gh pr view --json reviews sees a run at all. And Step 3 always asked for a go-ahead, which is right for a workflow that force-pushes and commits fixes, but makes the command unusable by a caller with no human present.

Both halves block the night shift: #358's Gate 1 cannot be written until a run is identifiable, and the command cannot be called at all until it has a second mode.

What changed

One file: .claude/commands/archon-pr-review.md.

• A new "Two markers, written by two actors" section. The workflow is bundled in the Archon binary and cannot be edited here, so the command asks the run for <!-- comprehensive-review-report head=<sha> part=review|fixes --> and writes its own <!-- archon-pr-review-verification run=<id> head=<sha> -->. The two share no leading token, so a reader matching one never matches the other. The section records that the workflow posts comments and never a review, gives the query that lists how every comment opens, and names both markers as the strings to find in that output.
• Step 3 gains a second path. The human path is named as the default and the unattended path as the one exception, in the same place, so an editor cannot delete the first while adding the second. The exception belongs to an unattended run of the night-shift skill. A flag would record nothing — an agent can grant itself a flag — so the path asks the caller to state the authorisation covering this PR, and that statement is copied into the verification comment. A caller with no authorisation to state stops and dispatches nothing.
• Step 4's dispatch prompt carries the ask. Mark every comment; print dimensions-run: and dimensions-not-run: in the review comment, on a produced-an-artifact definition, in exactly five spellings — code-review, error-handling, test-coverage, comment-quality, docs-impact. Produced-an-artifact is the definition that separates three states a looser one merges: a clean dimension, a dimension whose agent died silently, and one that never ran. synthesize fires at trigger_rule: one_success, so the review comment's literal 5 specialised agents survives four agents dying — which is why the roll call is asked for rather than read off the count.
• Step 6 selects by marker and posts one verification comment. Five fixed strings cover what the marker fails to deliver, each naming a different failure, and unknown, 0 and none are barred from standing in for any of them. The comment carries facts and labelled claims in a fixed field format — name, colon, one space, value, with the source on its own line beneath — and states no overall verdict. ci: is the one exception, quoted from gh pr checks and labelled as CI's word.
• allowed-tools gains Write, which posting the comment by --body-file needs.

What this does not do

It ships an ask, not a proof. No run has ever been asked for a marker and none has printed one, so at 9da6b23 no comment on any of the five reviewed pull requests carries it. The proof is #359's supervised rehearsal, and #358's Gate 1 stays unarmed until #359 answers. Two maintainer actions on #358 and #359 are recorded in the issue body; this PR does not edit either ticket.

Verification

$ pnpm ci:check
Checked 282 files in 113ms. No fixes applied.
Found 5 infos.
Checking formatting...
All matched files use Prettier code style!
ci:check EXIT=0

The 5 infos are pre-existing and unrelated (unsafe-fix suggestions in apps/claude-code/unic-pr-review tests).

Repo-scoped documentation change: no plugin version bump, no CHANGELOG entry, no LICENSE file touched.

Every shell snippet added here is portable to cmd.exe — no single-quoted arguments, no $VAR, no external program reached through a shell pipe. One labelled exemption: the comment-listing filter holds the inner string literal "\n", because reaching a comment's first line takes split("\n") and jq offers no literal-free way to write it. The file carries the caveat that this quoting is not verified on cmd.exe.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the /archon-pr-review command documentation to make archon-comprehensive-pr-review runs identifiable on a PR and to support an unattended dispatch path (for night-shift) while preserving an auditable trail.

Changes:

• Adds a “two markers, two actors” scheme (run-requested markers + command-written verification marker) to make runs detectable in PR comments.
• Introduces a strictly-scoped unattended path that requires an explicit authorisation statement and carries it into the verification comment.
• Expands Step 6 to select run output by marker (not headings) and to post a single structured verification comment via --body-file.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[orioltf]

⚡ Self-Fix Report (Aggressive)

Status: COMPLETE
Pushed: ✅ Changes pushed to archon/task-feature-repo-357-mark-runs-add-unattended-mode (df9bf67)
Philosophy: Fix everything unless clearly a new concern

---

Fixes Applied (1 total)

Severity	Count
🔴 CRITICAL	0
🟠 HIGH	0
🟡 MEDIUM	0
🟢 LOW	1

View all fixes

• ✅ Marker length stated as one number, but the two markers differ by one character (.claude/commands/archon-pr-review.md:53) — named part=review as the longer of the two markers the 94-char count describes; part=fixes is one character shorter

---

Tests Added

(none — prose-only change, no code or tests touched)

---

Skipped (0)

(none — all findings addressed)

---

Suggested Follow-up Issues

(none)

---

Validation

✅ Lint/format (pnpm ci:check green, 5 pre-existing infos in an unrelated file) | N/A Type check | N/A Tests

---

Self-fix by Archon · aggressive mode · fixes pushed to archon/task-feature-repo-357-mark-runs-add-unattended-mode

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (6)

.claude/commands/archon-pr-review.md:163

• Same as above: this jq slice uses [0:100], which can truncate the verification marker when the 32-char run id and 40-char SHA are present. Use a wider slice so the marker (and its head=) is fully visible.

gh pr view <n> --repo unic/unic-agents-plugins --json comments --jq ".comments[] | (.body | split(\"\n\")[0])[0:100]"

.claude/commands/archon-pr-review.md:219

• Right after the template, clarify that on the human path the entire authorisation: line should be omitted (not left blank or left as a placeholder), so the field-format expectations remain unambiguous.

`<run-id>` is the 32-character ID Step 5 read from `archon workflow status`. `<post-review-sha>` is `headRefOid` read **after** the run left the active list. `authorisation:` appears on the unattended path only; every other field is always present, and where its source did not deliver it carries one of the five strings above.

.claude/commands/archon-pr-review.md:216

• The template shows an authorisation: field, but it’s only valid on the unattended path. As written, it’s easy to copy/paste the template on the human path and accidentally include placeholder/empty authorisation, which would violate the strict field-format rules below. Make the template line explicitly say to omit it on the human path.

authorisation: <the caller's statement from Step 3, copied verbatim>

.claude/commands/archon-pr-review.md:24

• The introductory description still says the workflow “posts a review comment to the PR”, but the updated write-surface below now documents that it posts two comments (review + auto-fix report). Updating the intro avoids readers missing the second comment when scanning the top of the file.

- **Posts a `gh pr comment`** with the synthesised review, and a second one with the auto-fix report.

.claude/commands/archon-pr-review.md:53

• The explanation for the 100-char slice width only considers the run’s comprehensive-review-report markers (94 chars), but the verification marker you add in Step 6 is longer (~121 chars with a 32-char run id + 40-char SHA). Update the explanation to match the wider slice so readers don’t assume 100 is sufficient for all markers.

This issue also appears in the following locations of the same file:

• line 216
• line 219

In that output, find `archon-pr-review-verification` for this command's own comment and `comprehensive-review-report` for the run's. The width is 100 because the longer of the run's two markers (`part=review`) is 94 characters and ` part=` opens at column 79 — an 80-character slice shows the marker and hides which half of the run wrote it.

.claude/commands/archon-pr-review.md:50

• This jq slice uses [0:100], which can truncate the verification marker when the 32-char run id and 40-char SHA are present (the line is ~121 chars). Use a wider slice so the full marker, including head=, is visible in the listing output.

This issue also appears on line 163 of the same file.

gh pr view <n> --repo unic/unic-agents-plugins --json comments --jq ".comments[] | (.body | split(\"\n\")[0])[0:100]"