[calvin-archastro]

Review on ArchCode

Problem and intent

ArchDev CLI 0.54.7 to 0.55.4 ships the commands a coding agent needs to repair its own PR from CI and review events (events watch, events claim|renew|release, events dispatch). The archdev skill does not mention them. firstlanding's session-start contract already tells every session to run archdev events watch --pr <num> --json "(skill references/pr-events.md)", and that file does not exist here.

Without the reference an agent either skips PR events or invents the procedure, and nothing stops two agents (or an agent and the ArchDev daemon) from pushing to the same PR head. The claim table is the only fence: events claim exits 3 when the head is owned, and the agent must then change nothing.

Intent: document exactly what has shipped, in the order an agent must run it, and prove with a real harness that the installed skill produces that behavior.

What changed

1. archdev/references/pr-events.md (new): command table; how to run the watch per harness (Claude Code: Monitor tool; Codex, Grok and others: detached process or --once, never a foreground watch); the JSONL event fields (action_hint, claimed_by, gap, untrusted details); per-event procedure: verify head, events claim (exit 3 means stop, no edit, commit, push or release), fix, commit, push when authorized, extract run pr.review-annotations for the new head, events release with the claimed head and token, follow-through.
2. archdev/references/pr-orchestrator.md (new): events watch --mine plus events dispatch --event - for a session that coordinates repairs and does not edit code; exit 3 means skip; the dispatcher owns claim, renew and release.
3. archdev/SKILL.md: new section 4 "PR events" linking both references, a pointer from step 4 of the Pull Requests list, and a trigger phrase in the description (983 of 1024 characters).
4. archdev/references/bootstrap.md: "PR events minimum version" gate. PR events need 0.55.4 or newer (claim 0.54.7, watch 0.51.0, dispatch 0.55.4). Check --version and events claim --help; if either fails, skip PR events and offer the upgrade. The bootstrap scripts keep the 0.49.6 floor so unrelated workflows are not forced to upgrade.
5. plugins/*: regenerated with tools/plugin-gen (npm run build); npm run check, typecheck and test pass.

Not documented on purpose: events watch --inbox (hook-delivered inbox notes). It is in firstlanding main but not in any release (0.55.6 rejects the flag). Document it when it ships.

Unchanged: the 0.49.6 bootstrap floor, hook installation rules, and the rule that PR reporting does not require annotations. Annotations in this flow are repair evidence for reviewers, not a gate.

Scope

Skill docs and generated plugin copies only. No CLI, installer or hook change.

Risk

Low. Text only, and it applies only when the agent is handling PR events. The one risk is wrong commands: every command and flag was checked against the live 0.55.6 binary (--help) and the Rust source (events/claims.rs, watch.rs, dispatch.rs), and the executed eval below runs them.

User impact

Agents with a CLI at 0.55.4+ handle ci_failed, review_submitted and rebase events on their PRs, and back off when another agent or the daemon owns the head. Older CLIs see no change.

Testing

Canonical end-to-end proof: evals/skill-bench/pr_events_live.py run in firstlanding (companion change, not in this PR). It installs plugins/codex/skills/archdev from this branch into a hermetic CODEX_HOME, runs real Codex (gpt-6-astra) with the real 0.55.6 archdev CLI and its SQLite claim table, a bare-repo origin, a fake gh serving PR #42 and a fake Platform that stores annotation rows. archdev and git run through a tracing shim. Three turns, graded without an LLM judge from the trace, origin, claim DB and stored rows:

phase	event line	result
1	archdev.pr.ci_failed for the PR head	PASS: claim exit 0, commit, push (head moved to a descendant, node --test passes), extract run pr.review-annotations 42 stored a row for the new head, events release exit 0 with the claimed head and token, no claim left, in that order
2	archdev.pr.review_submitted for the pushed head	PASS: same sequence; average([]) is 0 and a regression test covers it
3	archdev.pr.ci_failed for a head another agent already claimed	PASS: events claim exit 3, no mutating git call, origin and checkout unchanged, no annotations, other claim still held and not released

Run live-6: all 38 checks passed (exit 0). The first turn read references/pr-events.md from the installed skill.

What the earlier live runs changed in this PR: run 5 passed every behavioral check but the agent then tried to start a second events watch after the harness had already handed it an event, and called that BLOCKED. The reference now says not to start a second watch when one is running (section 1).

Controls without a model: a scripted agent that follows the procedure passes; one that never claims fails the claim, release, order and before-claim checks; one that keeps going after exit 3 fails the no-mutation checks.

Fidelity: real Codex, real archdev CLI, real git and SQLite. Faked: GitHub (gh stub), Platform (loopback), the watch itself (the lines are seeded into the prompt, as a Monitor or background watch would deliver them), inspect metadata results (empty). Codex runs with --dangerously-bypass-approvals-and-sandbox in a throwaway home.

Not proven here: the Claude Code Monitor path and Grok (only Codex was run); events watch against a real subscription (needs a live Platform); events dispatch and the orchestrator reference (the CLI's own contract tests cover dispatch, and an operator-run Codex synthetic exists; this PR's eval does not exercise it); cross-machine ownership (claims are per HOME). The eval is a manual run (model calls); its grader is covered by offline tests in firstlanding's //evals/skill-bench:test-ci. This PR's own CI (plugins.yml, skill-bootstrap-checks.yml) covers only generation and bootstrap behavior.

Follow-ups

1. firstlanding: land evals/skill-bench/pr_events_live.py, its fixture and the updated evals/coding/tasks/skill-pr-events.yaml (uncommitted there; Task tsk_73yYr1DkTVUNai6Mowi5m7).
2. Document events watch --inbox after the release that contains it.
3. Run the eval with Claude Code (Monitor) and Grok.

🤖 Generated with Claude Code