@erclx/canon 4.0.0

package/claude/skills/claude-orchestrate/references/orchestrator-parked.md

@@ -0,0 +1,72 @@
+---
+title: Orchestrator parked row runbook
+description: Re-testing every parked blocker against the current tree, the two triggers that start the pass, and the two ways a re-test goes wrong
+---
+
+Re-test every parked row as orchestrator. A blocker cell is a measurement taken the day the row was parked and nothing re-takes it, so a row can wait on a condition that stopped holding weeks earlier with no surface reporting the gap.
+
+Two triggers start this pass. `orchestrator-sweep.md` ends by sending the rows `canon tasks validate` listed as untested here, because a merge changes the tree under every parked row at once rather than under the rows naming it. The other is an idle session: nothing merged, workers are building, no pull request is waiting on a first pass, and the board is not moving.
+
+The two differ in scope rather than in procedure. A merge sends the untested rows, since the validator already re-took the two kinds it can settle. An idle session walks every parked row, because no event narrowed which of them to look at.
+
+Neither trigger is a scheduler. `orchestrator-poll.md` owns the one recurring trigger this skill has, and a second loop firing into a static board is the always-on failure that file already warns about.
+
+The sweep's own question stays distinct from this one. It asks which parked row to promote next, taking the blocker cell as read, and this pass asks whether that cell is still true. A session collapsing them runs whichever it remembers and re-tests nothing.
+
+## Scope
+
+Every row under `## Up next` and `## Needs a plan` in `.claude/tasks/priority.md`. A `## Run now` row carries no blocker by definition, so the pass skips it. Resolve the board and each task file at the main worktree root, per Worktrees in `CLAUDE.md`.
+
+Take the rows in board order and finish one before opening the next. Clearing a row changes what the next row collides with, so a pass that measures every row first and writes afterwards writes against a board it has already invalidated.
+
+## Re-testing a row
+
+The blocker cell states what the row waits on, and each kind is tested differently. `canon tasks validate` already re-takes the first two and reports the rest as untested, so run it first and re-take by hand only what it names.
+
+- Collision with a track in flight: the validator tests the file the cell cites against the Touches column of every `## Run now` row. A track that merged since the row was parked is no longer in flight, whatever the sets still share. A cell naming the file in prose rather than in backticks cites nothing, so write the collision the way the board format spells it and the check picks the row up on the next run.
+- A dependency on another task: the validator opens the task a link in the cell names. One whose outcomes are all `[x]`, or one already archived, holds nothing. A cell naming the task in prose resolves to no file, so open it by hand and rewrite the cell as a link.
+- A condition about the tree, such as a count of some shape or the presence of a construct: measure it again, per Two ways a re-test goes wrong below.
+- Waiting on a plan: nothing external holds the row, so the pass writes the plan rather than testing anything. See The plan half below.
+- Waiting on an operator action, such as a run that happens from a shell: record it as untestable this pass and name what the operator has to do. A session cannot clear it, and re-measuring it every pass is waste.
+
+Write the result into the row. A re-test reported in chat is lost at the next compaction and the next pass measures the same thing again. Rewrite a blocker cell whose test no longer holds, move the row to the group its new state puts it in, and record the measurement in that task's `## Findings` with the date it was taken. `### Writing the board` in `claude-orchestrate` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report.
+
+## Two ways a re-test goes wrong
+
+Both return a confident wrong answer rather than an error, which is why each gets a step of its own.
+
+The first is reading the condition looser than the code defines it. A row parked on a count of some shape names a shape its consumer defines precisely, and a count taken by eye or by a pattern that approximates it lands somewhere else. The row that motivated this runbook counted 19 instances of a shape whose real count under the consumer's definition was zero.
+
+Find the code that consumes the shape, read the definition off it, and measure with that. A count taken any other way is not evidence about the blocker.
+
+The second is measuring against the wrong tree. A command that ships to targets is at risk in corpora this repository never formats, so a condition measured here reads as unreachable while it stays live where the command runs. Ask which tree the condition is about before asking what the count is. A local formatter removing the shape on contact says nothing about a target running no such formatter.
+
+## The plan half
+
+Plan what the pass clears, and plan any `## Needs a plan` row whose only blocker is the missing plan. The window is the argument: this pass runs while workers build and the session is otherwise idle, which is when planning costs the critical path nothing, and a row cleared with no plan is a row the next pass looks at again.
+
+Run `claude-feature` for each, carrying the constraint per in-flight track that `## The loop` in `claude-orchestrate` requires. Verify each plan against the tree the way that step does, since a plan written now is written against a tree several branches are already changing.
+
+Stop where `## Parallelism` stops rather than planning every row the pass cleared. A plan whose file set collides with every track in flight is one nobody can dispatch.
+
+Do not restate the refill procedure. `claude-orchestrate` owns it under `## Refilling the ready queue` and `orchestrator-sweep.md` wraps it for a batch of merges, so this pass promotes through that method rather than a second one.
+
+## Two results that are not a re-test
+
+Age is not evidence. A row untouched for weeks invites promotion, and the waiting is not an argument for it. `claude-orchestrate` refuses to promote a task to fill the queue and this pass inherits that refusal, so a row whose blocker still holds stays where it is. Reporting it as still parked, against a measurement taken this pass, is a result.
+
+A scoping defect can wear a blocker. A task whose file set collides with every other task by construction is oversized rather than blocked, and planning it again produces the same plan nobody can dispatch. Split it into tasks with disjoint file sets, so the board stops carrying a row that re-measures the same way every pass.
+
+## Output
+
+```plaintext
+Re-tested: <row>, <blocker> → <what the measurement showed>
+Cleared: <row>, now <group>, plan at <path>
+Still parked: <row>, <blocker> re-confirmed against <what was measured>
+Untestable: <row>, waits on <operator action>
+Split: <task> into <tasks>, file set collided with everything by construction
+```
+
+Omit any row with nothing in it. Name what was measured rather than the verdict alone, since a re-test the reader cannot check is the same claim the row already carried.
+
+Lead the reply with the three slots under `### Every later turn` in `claude-orchestrate`, so the human reads what they own before the evidence for it.

package/claude/skills/claude-orchestrate/references/orchestrator-poll.md

@@ -0,0 +1,87 @@
+---
+title: Orchestrator poll runbook
+description: The review trigger, the condition under which it runs, and how to read what it reports
+---
+
+Run the orchestrator's review trigger. The poll reports pull request movement and the session acts on what it reports. The script reads and never writes, and the routing block below decides which report earns a review, which earns a dispatch, and which earns neither.
+
+`${CLAUDE_SKILL_DIR}/scripts/poll.sh` is the script. It needs `gh` authenticated against the remote and `jq` on the path, and it reads the base branch from `origin/HEAD` rather than assuming a name.
+
+## When to run it
+
+Start the poll on an open pull request and stop it when the last one merges with nothing else out. That is the whole condition and it resolves from `gh pr list` without asking the operator. A release pull request alone does not qualify, since its sweep carries no findings.
+
+A dispatch no longer starts it. The script reads pull requests and a building worker has none, so every interval between the launch and the push is a fixed cost returning nothing, measured as five consecutive runs reporting no movement across roughly fifteen minutes while one worker built. What replaces it is the worker announcing its own pull request the moment it opens one, per the `claude-worker` skill that session loads, which covers exactly the transition the poll cannot observe.
+
+The dispatched-worker condition survives as a fallback rather than as a trigger. Start the poll against any dispatch still out after thirty minutes with no announcement, which is past the upper end of the ten to thirty minutes a row here takes. The announcement is newer than the narrowing it justifies, so a silent failure would otherwise leave a finished worker unnoticed the way one already sat idle for eighteen minutes, and the fallback keeps the cover a straight narrowing would have removed. `${CLAUDE_SKILL_DIR}/scripts/watch.sh` covers the same window at a lower cost, since it reads the roster alongside the pull request list and reports a worker that vanished as well as one that finished.
+
+A session holding a recurring-prompt scheduler starts the loop itself on that condition and cancels it on the same test, without waiting for the operator. Both halves belong to whoever holds the loop, since a session that can start one can stop one, and a runbook stating only the start leaves the always-on failure unaddressed on the side that causes it.
+
+Nothing enforces this. No hook starts the poll and no check stops it, so the condition holds only while whoever holds the loop applies it. Left always-on it fires into an empty board through every gap between a dispatch and its push.
+
+The poll is session-scoped and dies with the session that started it. Restart it after a compaction, and take the prompt from this file rather than from a transcript, since a running loop holds whatever wording it was started with and a correction here does not reach it.
+
+The reverse direction is the one that goes unnoticed. A scheduled prompt cannot be edited, so every routing fix is a cancel and a re-create, and three made inside one session each reached the running loop and none reached this file. Edit the block here first and re-create the loop from what this file then says. Rewriting the block from memory drops what the shipped one covered, which is how a `SEEN` report once fell through to no rule at all.
+
+## The prompt
+
+The requirement is a recurring prompt at roughly three minutes carrying the block below. `/loop 3m <the block>` is the mechanism this repository uses and one example among the schedulers a client may hold, so a client without that command reaches the same requirement through whatever recurring prompt it can schedule. Naming one vendor's command as the only path dates a file that ships to every target holding the plugin.
+
+The interval belongs to the schedule rather than to the script. One run is a single snapshot returning in about six seconds, so a session that reads `3m` as the script's runtime and relaunches on completion fires every few seconds and never settles, which happened once for 35 minutes.
+
+Resolve `${CLAUDE_SKILL_DIR}/scripts/poll.sh` to an absolute path and paste that in place of `<POLL_SCRIPT>` below. The variable expands while this runbook renders and not in a standalone loop turn, so a block carrying the variable reaches the session as a literal string and the run improvises a substitute.
+
+```plaintext
+Poll GitHub for pull request movement by running <POLL_SCRIPT>, then act on what it reports.
+
+- A release pull request, whatever state follows it: report it and stop. Its sweep carries no findings, so no pass is owed. Test this before any rule below, since a release pull request is reported OPENED like any other and would otherwise match that rule first.
+- MOVED or RESPONSE on a pull request I have already reviewed: run the canon:claude-pr-review skill on it immediately, narrow pass. Re-reviews read prior..head and gain nothing from waiting.
+- OPENED, or a pull request with no prior review pass: run the canon:claude-pr-review skill on it. A draft counts, since every pull request here opens as one and skipping drafts skips everything.
+- SEEN: report it and stop. A pass already covers that head, whether it arrived out of band or before the poll first saw the pull request, so no review follows.
+- STALLED: read the last pass and report what it carried. The pass has sat open for hours with nothing following it, so a worker mid-task is already ruled out and the dispatch either never went out or the session holding it is gone. Confirm and re-send it under the dispatch rule below, whatever grades the pass carried. Do not re-run a review to correct the heading, since a pass on an unchanged head with no response behind it stops by design.
+- CONFLICT: report it and stop. The branch owner rebases, not this session.
+- UNMATCHED: report it and stop. A comment posted under a heading outside the known set reaches nobody automatically, so a person decides whether to answer it by hand or the set needs a sixth heading.
+- GONE: report it, then sweep the board by invoking the canon:claude-orchestrate skill and following its queue-refill sweep.
+- A line starting `poll:`: report it verbatim and treat that pull request as unread this run. It is a failed query, not a state.
+- Nothing changed: say exactly "No movement." and nothing else.
+
+After any pass that posts a finding, at any severity, tell the session holding that branch to run the canon:claude-address-review skill. Resolve the target by running `canon sessions list --branch <branch> --json` at that moment, which scopes the match to this repository, then route on how many sessions it returned. Zero: report the invocation for me and dispatch nobody. Exactly one, with the confidence field reading "confirmed": address that name directly. Any other count, any other confidence, or a command that is missing or refuses: fall back to picking from a session listing, open by naming the worktree and branch you believe the reader holds, and ask to be corrected. Two sessions can hold one branch, so read the count rather than the first row. The threshold is stated once in the canon:claude-pr-review skill and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send.
+```
+
+## Reading the output
+
+Every classification line names a pull request and a state. A line starting `poll:` is not a classification. It means a query failed and the script declined to guess, so that pull request keeps its last known state and is neither reported as moved nor swept as merged. Treat it as unread and let the next run classify it.
+
+The script exits non-zero and classifies nothing when the open pull request list itself fails to load. That case would otherwise report every tracked pull request as merged, so the baseline is left untouched and the run says so.
+
+The baseline lives at `.claude/.tmp/pr-poll/baseline.txt` under the main worktree root and is per-machine. A first run against a board already in flight reports each open pull request once before it settles.
+
+The five review headings the script matches are written by `claude-pr-review` and `claude-address-review`, and the whole set is stated once in the first. A project that posts its reviews under different headings edits the jq filters in the script to match, or every pull request reads as never reviewed.
+
+`UNMATCHED` is what a heading outside the five reaches, carried the same way `RESPONSE` is: a rising count against the baseline is what is new to this script, and the message names the heading so a person can tell whether to answer it by hand or add it to the set. It fires on a tracked pull request only, since a first sighting reports `SEEN` or `OPENED` and takes whatever count already sits on the thread as its starting baseline rather than flagging history the poll never watched.
+
+`RESPONSE` is qualified by recency as well as by count, so it means a reply the last pass has not already answered rather than one this script has not seen before. A worker answers a finding and the reviewing session posts its close-out seconds later, which is the ordinary handback rather than a race, so a count on its own reported the answered thread on the next run and the re-review it routed to stopped at its own guard. The state now fires when the newest reply is stamped later than the last pass, and on a pull request carrying no pass at all, which is a worker talking to nobody and worth the turn. A reply landing inside the same second as the pass is dropped, matching the comparison `claude-pr-review` makes on the same two fields.
+
+`STALLED` is the one state the script derives from a heading rather than from a commit or a count, since `claude-pr-review` posts the open heading exactly when a dispatch is owed, per the threshold that skill states. The heading alone cannot carry it, because an open pass means a dispatch was owed and made, so the ordinary healthy thread is a worker still working. The age of that pass is the third test: the state fires when the open pass covers the head, nothing has followed it, and it is older than the `STALE_AFTER` seconds set at the top of the script. It reports once per entry and fires again after any commit or reply resets the thread. A project whose workers run longer than the default two hours raises that number.
+
+The state reaches every stalled dispatch, since one threshold governs the heading and the dispatch alike and a pass carrying anything posts the open heading. A minors-only pass therefore reports here on the same terms as a blocking one, which widens the state from what it caught while the two were split. It stays a heading test rather than a count test, so nothing here pins the summary line, which is a second string this script does not own.
+
+## The watch beside it
+
+`${CLAUDE_SKILL_DIR}/scripts/watch.sh` is a long-running loop rather than a scheduled prompt. It reads the open pull request list and the session roster together every sixty seconds and prints one line per new pull request, per worker whose status changed, and per worker that dropped out of the roster. Start it in the background and read what it emits. It writes nothing.
+
+Coverage is what it buys over the poll. A worker that finishes goes idle and a worker that crashes disappears, so a trigger reading pull requests alone stays silent through the second, and the roster read is the half `poll.sh` cannot make. It ran a full afternoon over four concurrent workers and caught every transition, while the three-minute poll it replaced reported no movement five times in a row.
+
+It classifies nothing and routes nothing. A line it prints says a pull request opened or a worker moved, and the routing block above is still what decides whether a review follows, so the two compose rather than replace each other.
+
+Every session in the repository holding a branch other than the base one counts as a worker, whoever launched it. The prototype matched the `orchestrator-` prefix instead, which reads a dispatched worker and misses every hand-launched one. A failed read of either source reports itself on a `watch:` line and leaves the baseline untouched, since reading an empty result as current state would report every worker gone on the pass after.
+
+## The stall alarm
+
+`watch.sh` prints `WORKER-STOPPED <name> <branch> <dwell>s` once a `waiting` row crosses `STALL_THRESHOLD_S`, and `WORKER-UNMEASURABLE <name> <branch>` for one whose record carries neither timestamp the dwell falls back to. Both are prints, not alerts, so the operator learns of one only when a session already reading the loop's output relays it further. The toolkit ships no notification verb, since the surface a stall reaches the operator through is a session tool rather than a command a shell loop can call.
+
+The two lines carry different confidence and the push has to say so rather than treat them as one signal. `WORKER-STOPPED` fires only once the dwell has already crossed the threshold, so it reports a wait already confirmed long. `WORKER-UNMEASURABLE` has no dwell to threshold on, so it fires on the first pass that meets a `waiting` row carrying neither stamp, whether that row has sat five seconds or fifty minutes.
+
+On meeting either line, push a notification to the operator through whatever notification surface the client offers, `PushNotification` in this repository's client and one example among the surfaces a different client exposes. Name the worker, the branch, which of the two lines fired, and the dwell where `WORKER-STOPPED` carries one, and send it once per stall the same way `watch.sh` prints it once, rather than repeating it on every interval the row stays stopped.
+
+The bound stays open. The alarm reaches the operator only through the controller's own read, so a controller mid-turn does not see the line for as long as the turn runs, and a controller that is itself stopped never does. Neither case closes here, since the watch loop and the notification surface both live inside the same session that has to be free to act on either.

package/claude/skills/claude-orchestrate/references/orchestrator-resume.md

@@ -0,0 +1,30 @@
+---
+title: Orchestrator resume runbook
+description: What to read back after a compaction, and how to treat a groundwork folder's three shelf lives
+---
+
+Resume as orchestrator after a compaction. Read the board and the groundwork behind the live work before answering anything, because a compaction summary keeps conclusions and drops the reasoning that produced them.
+
+1. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Every path below resolves against it.
+2. Read `.claude/tasks/priority.md` for the ordering and what each task waits on. Read the newest `.claude/tasks/session-*.md` when one exists, per `${CLAUDE_SKILL_DIR}/../../standards/session.md`, and treat it as the previous session's scratch rather than a source.
+3. Read the task file for every entry under `## Run now`, plus any entry a live pull request names.
+4. Read the groundwork folder each of those tasks cites. Read `README.md` for the file map, then `06-decision.md` when the track is closed, or `07-next-session.md` and the numbered topic files when it is open. A task's Findings section is a lossy summary of its track, so planning against the summary re-derives what the folder already settled.
+5. Run `gh pr list --state open` and `git log --oneline -5` to see what shipped since the folder was written.
+6. Report in this shape and stop:
+
+```plaintext
+Read: <task files>, <groundwork folders>
+Shipped since: <commits or PRs>
+Stale in the groundwork: <lean or number the shipped work overturned>
+Next: <the one or two tasks ready to hand a worker>
+```
+
+Treat a groundwork folder as three kinds of content with different shelf lives. Trust the reasoning and the method, which stay correct. Re-measure every count, size, and cost, because they were true when written. Check every `Leaning:` against what has shipped, because work spawned by a track routinely overturns the lean that spawned it and nothing writes back.
+
+A plan a live task cites goes stale the same way, and `claude-orchestrate` states the check that catches it.
+
+After each merge, place every finding the work produced before starting anything else. A finding that changes a standard goes to the standard, one that changes another task goes to that task's Findings, and one that overturns a groundwork lean gets marked answered in that folder. Findings recorded in a pull request thread and nowhere else are lost at merge.
+
+Cite a file and line for any claim taken from a groundwork folder, so a later reader can tell a read from a recall.
+
+Do not read every groundwork folder. Read the ones the live tasks cite. A speculative sweep of the whole folder is the cost this rule exists to bound.

package/claude/skills/claude-orchestrate/references/orchestrator-sweep.md

@@ -0,0 +1,21 @@
+---
+title: Orchestrator sweep runbook
+description: The once-per-batch board sweep, plan re-verification, and where each merged finding goes
+---
+
+Sweep the board as orchestrator after merging. Run this once per batch of merges, before answering what to do next, because the surfaces that record what shipped are the ones nothing updates on its own.
+
+1. Pull into the main worktree rather than fetching. A fetch leaves the local branch behind, so `git log` reports a state that has not arrived. A repository that adds a post-merge hook to name archive candidates gets it on a pull and never on a fetch.
+2. Follow `## Refilling the ready queue` in `claude-orchestrate`, every step in order. It owns the procedure. Do not restate it here and do not run it from memory.
+3. Re-verify every plan already written, not only the ones this sweep writes. A queued plan goes stale from whatever merged while it waited, and the loop's verify step fires at handoff rather than after a merge, so nothing else catches it. Grep each construct the plan names and count the sites against its claim, then open each file rather than trusting its account.
+4. Re-check any precondition a plan states about live state outside the repository. A remote branch, an open issue, or an installed version was true when the plan was written and is not a fact about the tree.
+
+Run `canon worktrees list` after the pull, which is the first point at which the merges this sweep followed are readable. It owns the reclaim rule and it removes nothing, so read its rows and act on the ones you mean to. Never substitute a git ancestry check for it.
+
+Run `canon tasks validate` once the board is rewritten and before reporting it. It resolves every plan pointer, accounts every task file against the board and the backlog both, tests the `## Run now` file sets for overlap, and re-takes the two blocker kinds a command can settle. It reports and never writes, so fix each row it names and run it again. A finding it reports is a board defect rather than a task finding, so it goes nowhere but the board.
+
+Then run `orchestrator-parked.md` over the rows the validator listed as untested. Those carry the three blocker kinds no command settles, and the merge this sweep followed changed the tree under every one of them at once while the refill above re-read none. Take the untested rows alone rather than the whole board, since the validator already answered the rest.
+
+Place every finding the merged work produced before promoting anything. A finding that changes a rule goes to the standard or the rule that states it, one that changes another task goes to that task's Findings, and one that overturns a groundwork lean gets marked answered in that folder. A pull request body counts as nowhere, since the thread stops being read the moment it merges.
+
+Report what closed, what moved, and what is ready to hand a worker. Name the file set each ready task touches, so the reader can check the disjointness claim rather than take it.

package/claude/skills/claude-orchestrate/scripts/poll.sh

@@ -0,0 +1,373 @@
+#!/usr/bin/env bash
+# Reports pull request movement since the last run. Reads only.
+#
+# The shebang is load-bearing. An earlier version ran under the operator's zsh,
+# where an unquoted parameter expansion does not word-split, so `set -- $line`
+# left every field but the first empty and every head compared unequal. The
+# poll reported movement that had not happened, which is the one failure that
+# makes a detection tool worth less than no tool.
+set -e
+set -o pipefail
+
+# The baseline is per-machine mutable state, so it stays in gitignored scratch
+# even though the script is tracked. Resolving the main worktree root rather
+# than this file's own folder keeps a poll started from a linked worktree
+# reading the baseline a poll started from main wrote.
+MAIN_ROOT="$(git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}')"
+if [ -z "$MAIN_ROOT" ]; then
+  echo "poll: not a git repository, so nothing is classified" >&2
+  exit 1
+fi
+STATE_DIR="$MAIN_ROOT/.claude/.tmp/pr-poll"
+mkdir -p "$STATE_DIR"
+STATE="$STATE_DIR/baseline.txt"
+touch "$STATE"
+
+# The base branch is read rather than assumed, since this ships to projects that
+# do not all call it `main`. A wrong base is not a visible failure: merge-tree
+# reports every pull request as conflicted against a ref that does not resolve.
+BASE_REF="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+if [ -z "$BASE_REF" ]; then
+  BASE_REF="origin/$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null || echo main)"
+fi
+BASE_BRANCH="${BASE_REF#origin/}"
+
+# These five strings are owned elsewhere and pinned here. `claude-pr-review`
+# writes `## Review` and `## Review closed`, and states the full five-heading
+# set once, beside the threshold it already states once. `claude-address-review`
+# writes `## Review response`, `## Rebase`, and `## Post-review findings`, the
+# last for a finding a worker produces after a close-out rather than in answer
+# to one already on the thread. All three surfaces ship separately, so a
+# heading added in either skill breaks a test here that no check reaches across.
+#
+# Both families match on the first line alone so the tests stay symmetric. The
+# reply family carries `## Rebase` and `## Post-review findings` beside
+# `## Review response` because neither answers a comment already on the thread,
+# which is why both were kept outside the `## Review` family rather than folded
+# into it.
+JQ_LAST_REVIEWED_HEAD='
+  [ .reviews[]
+    | select((.body // "") | split("\n")[0] | rtrimstr("\r")
+             | . == "## Review" or . == "## Review closed")
+  ] | last | .commit.oid // empty
+'
+# The count alone answers whether a reply is new to this script, which is not
+# the same question as whether it is newer than the pass it answers. The stamp
+# of the newest reply comes out of the same selection so the recency test costs
+# no second filter, and it is the one this file compares against `submittedAt`.
+JQ_REPLY_STATE='
+  [ .comments[]
+    | select((.body // "") | split("\n")[0] | rtrimstr("\r")
+             | . == "## Review response" or . == "## Rebase"
+             or . == "## Post-review findings")
+  ] as $replies
+  | ($replies | length | tostring)
+    + " "
+    + ([ $replies[] | .createdAt // empty | fromdateiso8601 | floor ]
+       | max // 0 | tostring)
+'
+# A comment matching neither family above is the gap this filter exists to
+# surface rather than absorb: a worker inventing a sixth heading used to reach
+# this script as silence, indistinguishable from no comment at all. The count
+# is read the same way the reply count is, a rising value against the baseline
+# being new to this script, and the newest heading's text rides along for the
+# report. It carries its spaces intact rather than encoded, since it is the
+# last field on both sides of the pipe: `${unmatched_state#* }` below strips
+# only the first space, and `read -r` further down hands its last named
+# variable the rest of the line whole. Neither reads a heading's own spaces
+# as a field separator, so a heading round-trips verbatim into the report a
+# person reads when deciding whether to answer it by hand.
+JQ_UNMATCHED_STATE='
+  [ .comments[]
+    | (.body // "") | split("\n")[0] | rtrimstr("\r")
+    | select(startswith("## "))
+    | select(. != "## Review" and . != "## Review closed"
+              and . != "## Review response" and . != "## Rebase"
+              and . != "## Post-review findings")
+  ] as $unclassified
+  | ($unclassified | length | tostring)
+    + " "
+    + (($unclassified | last) // "none")
+'
+
+# `claude-pr-review` states the threshold and posts `## Review` exactly when a
+# pass carries a finding, so the heading of the last review is what says whether
+# any work is owed on it. Taking it as well as the commit is what separates a
+# thread waiting on a worker from one nothing is owed on. A project editing the
+# two filters above for its own headings edits this one with them.
+#
+# The age of that review comes out of the same selection, because the heading
+# alone cannot separate the two. Under the rule above an open heading means a
+# dispatch was owed and made, so the ordinary healthy thread is a worker still
+# working and every one of them would be reported minutes after the pass posted.
+# jq computes the elapsed seconds itself, since `date -d` is GNU-only and this
+# script runs wherever the plugin is installed. A review carrying no stamp reads
+# as age zero and classifies nothing, which is the same answer the carry-forward
+# path gives a pull request this run could not read.
+#
+# The stamp itself is emitted as a third field beside the age it was derived
+# from, because the reply test below compares against the instant rather than
+# against the elapsed seconds. A missing stamp reads as zero there too, where it
+# sends a reply to be reported rather than suppressed. The two readers therefore
+# fail in opposite directions on the same absent field, since zero silences the
+# age test above and zero is the value the reply test reports on.
+JQ_LAST_REVIEW_STATE='
+  [ .reviews[]
+    | select((.body // "") | split("\n")[0] | rtrimstr("\r")
+             | . == "## Review" or . == "## Review closed")
+  ] | last
+  | if . == null then "none 0 0"
+    else (if .submittedAt == null then 0
+          else (.submittedAt | fromdateiso8601 | floor)
+          end) as $at
+      | ((.body | split("\n")[0] | rtrimstr("\r")
+          | if . == "## Review" then "open" else "closed" end)
+         + " "
+         + (if $at == 0 then "0" else (((now | floor) - $at) | tostring) end)
+         + " "
+         + ($at | tostring))
+    end
+'
+
+# An open pass this old has nobody on it. The cycle it has to clear is a review
+# landing and a worker pushing a follow-up, measured between ten and thirty
+# minutes across a day of runs on 2026-08-14, so two hours sits about four times
+# past the slowest observed and still well inside a working session. Shorter
+# starts catching the slow healthy case this threshold exists to exclude, and
+# longer lets a dead dispatch sit past the point a person would have noticed.
+# A project whose workers run longer than that raises it here.
+STALE_AFTER=7200
+
+# A pull request this run could not read keeps the line it had, so the GONE
+# sweep below does not read the gap as a merge and the baseline does not lose
+# the head it already knew. Saying so on stderr is the point: a silent skip is
+# how the failure this script was fixed for went unnoticed for a session.
+carry_forward() {
+  local n=$1 reason=$2 old
+  old=$(grep "^$n " "$STATE" || true)
+  if [ -n "$old" ]; then
+    # Every other classification compares a field against itself on a carried
+    # line, so it fires nothing. That is also what keeps the two stamps unread
+    # here: the baseline never held them, so both arrive empty, and the count
+    # test in front of them fails before either reaches a numeric comparison.
+    # STALLED reads a heading that is carried too, so
+    # the field is blanked to a value no branch matches. Echoing it intact would
+    # classify a pull request this run never reached while stderr below says the
+    # opposite, and one successful read restores it a run later. An already
+    # reported thread keeps its marker, or an unreadable run would let the same
+    # thread be reported a second time.
+    echo "$old" | awk '{ if ($6 != "reported") $6 = "carried"; print }'
+    echo "poll: #$n $reason, so it keeps its last known state and goes unclassified" >&2
+  else
+    echo "poll: #$n $reason, and it has no last known state, so it goes unclassified" >&2
+  fi
+}
+
+snapshot() {
+  local numbers n payload head prior resp merges review_state
+  git fetch -q origin "$BASE_BRANCH" 2>/dev/null || true
+
+  # A failed list reaches the caller as no open pull requests, and that reports
+  # every tracked one as GONE. It is a louder wrong answer than the one this
+  # script was fixed for, so the run aborts rather than classify on it.
+  if ! numbers=$(gh pr list --state open --json number --jq '.[].number' 2>/dev/null); then
+    echo "poll: the open pull request list could not be read" >&2
+    return 1
+  fi
+
+  for n in $numbers; do
+    # A query that failed and a pull request with genuinely no reviews both
+    # arrive as an empty result. Reading the first as the second reported a
+    # reviewed pull request as never reviewed, which routes the re-review to
+    # the first-pass branch, where it reports and stops, so the movement sits
+    # unreviewed until a person notices. One query per pull request gives that
+    # failure a single place to surface.
+    if ! payload=$(gh pr view "$n" --json headRefOid,reviews,comments 2>/dev/null); then
+      carry_forward "$n" "could not be read"
+      continue
+    fi
+
+    head=$(jq -r '.headRefOid // empty' <<<"$payload")
+    if [ -z "$head" ]; then
+      carry_forward "$n" "returned no head"
+      continue
+    fi
+
+    prior=$(jq -r "$JQ_LAST_REVIEWED_HEAD" <<<"$payload")
+    # Split here rather than carried whole, because the count keeps the fourth
+    # column every baseline written so far already reads, and the stamp goes to
+    # the end of the line beside the pass stamp it is compared against.
+    reply_state=$(jq -r "$JQ_REPLY_STATE" <<<"$payload")
+    resp=${reply_state%% *}
+    reply_at=${reply_state##* }
+    # Three space-separated fields, so the line below carries them as its own
+    # sixth, seventh, and eighth rather than needing a split.
+    review_state=$(jq -r "$JQ_LAST_REVIEW_STATE" <<<"$payload")
+    # Split the same way as the reply state, carried as the line's tenth and
+    # eleventh fields.
+    unmatched_state=$(jq -r "$JQ_UNMATCHED_STATE" <<<"$payload")
+    unmatched_count=${unmatched_state%% *}
+    unmatched_heading=${unmatched_state#* }
+
+    # `gh pr view --json mergeable` reports UNKNOWN until GitHub finishes
+    # computing it, which is exactly when a poll asks. merge-tree answers
+    # locally against the base this machine has, so it never returns UNKNOWN.
+    git fetch -q origin "pull/$n/head" 2>/dev/null || true
+    if ! git cat-file -e "${head}^{commit}" 2>/dev/null ||
+      ! git rev-parse --verify -q "$BASE_REF" >/dev/null; then
+      # merge-tree exits non-zero on a ref it cannot resolve as well as on a
+      # real conflict, and the two are indistinguishable from its status. Both
+      # sides are checked, because an unresolvable base reports every pull
+      # request as conflicted rather than one, which is the louder half.
+      merges=unknown
+    elif git merge-tree --write-tree "$BASE_REF" "$head" >/dev/null 2>&1; then
+      merges=clean
+    else
+      merges=conflict
+    fi
+
+    echo "$n $head ${prior:-none} $resp $merges $review_state $reply_at $unmatched_count $unmatched_heading"
+  done
+}
+
+# The reason is printed by whichever branch failed, since this one cannot tell
+# a list query from a parse and naming either would misattribute the other.
+if ! NEW=$(snapshot); then
+  echo "poll: nothing is classified this run and the baseline is unchanged" >&2
+  exit 1
+fi
+CHANGED=0
+# The baseline is written from here rather than from the snapshot, because the
+# heading field is the one column a classification rewrites. STALLED reports a
+# standing condition rather than a transition, so without a written marker it
+# would fire on every later run and the board would never read "No movement."
+FINAL=""
+
+while read -r n head prior resp merges heading age pass_at reply_at unmatched_count unmatched_heading; do
+  [ -z "$n" ] && continue
+  state=$heading
+  old=$(grep "^$n " "$STATE" || true)
+  if [ -z "$old" ]; then
+    # A pull request first seen here may already carry a pass, when it opened
+    # and was reviewed between two runs. Reporting it as new invites a first
+    # pass the thread already has.
+    if [ "$prior" = "$head" ]; then
+      echo "SEEN      #$n at ${head:0:7}, first sighting, already covered by a pass"
+    elif [ "$merges" = unknown ]; then
+      # `unknown` means no merge was attempted, so it is left off the line
+      # rather than printed where a verdict belongs.
+      echo "OPENED    #$n at ${head:0:7}"
+    else
+      echo "OPENED    #$n at ${head:0:7}, $merges against $BASE_BRANCH"
+    fi
+    CHANGED=1
+    FINAL+="$n $head $prior $resp $merges $state $unmatched_count"$'\n'
+    continue
+  fi
+  old_head=$(echo "$old" | cut -d' ' -f2)
+  old_resp=$(echo "$old" | cut -d' ' -f4)
+  old_merges=$(echo "$old" | cut -d' ' -f5)
+  # Only the marker is read off this field, so a baseline written before it
+  # existed yields empty and reads as not yet reported, which is what it is. The
+  # age decides the rest, so the first run after an upgrade needs no history and
+  # classifies a thread already past the threshold rather than waiting a run.
+  old_heading=$(echo "$old" | cut -d' ' -f6)
+  old_unmatched=$(echo "$old" | cut -d' ' -f7)
+
+  # A conflict arrives from the base moving, not from the branch, so it is
+  # reported on the transition rather than only when the head changes.
+  if [ "$merges" = conflict ] && [ "$old_merges" != conflict ]; then
+    echo "CONFLICT  #$n no longer merges into $BASE_BRANCH"
+    CHANGED=1
+  fi
+
+  # A rising count is what is new to this script, the same test RESPONSE
+  # below runs against the reply family. It fires on a tracked pull request
+  # only: a first sighting reports SEEN or OPENED and takes whatever count
+  # already sits on the thread as its starting baseline rather than flagging
+  # history retroactively. A carried line supplies neither, since
+  # carry_forward re-echoes the shorter baseline shape rather than a full
+  # snapshot line, so both sides default to zero the way old_unmatched
+  # already does.
+  if [ "${unmatched_count:-0}" -gt "${old_unmatched:-0}" ]; then
+    echo "UNMATCHED #$n posted under '$unmatched_heading'"
+    CHANGED=1
+  fi
+
+  if [ "$head" != "$old_head" ]; then
+    if [ "$prior" = "none" ]; then
+      echo "MOVED     #$n -> ${head:0:7}, never reviewed"
+    elif [ "$prior" = "$head" ]; then
+      # An out-of-band pass reviewed this head before the poll saw it move, so
+      # the range is empty because it is covered rather than because it broke.
+      # Without this the force-push branch below claims a rewrite that never
+      # happened, which is the class of false report the shebang note names.
+      echo "SEEN      #$n -> ${head:0:7}, already covered by the last pass"
+    else
+      # The range needs both commits local, and a force-push leaves the prior
+      # one unreachable. Count what resolves and say nothing when it does not,
+      # rather than reporting a zero that reads as no new work.
+      git fetch -q origin "pull/$n/head" 2>/dev/null || true
+      since=$(git log --oneline "${prior}..${head}" 2>/dev/null | wc -l | tr -d ' ' || true)
+      if [ -n "$since" ] && [ "$since" != "0" ]; then
+        echo "MOVED     #$n -> ${head:0:7}, $since commit(s) since your last pass"
+      else
+        echo "MOVED     #$n -> ${head:0:7}, range unresolved, likely force-pushed"
+      fi
+    fi
+    CHANGED=1
+  elif [ "$resp" -gt "$old_resp" ] &&
+    { [ "$pass_at" = 0 ] || [ "$reply_at" -gt "$pass_at" ]; }; then
+    # The count says the reply is new to this script and the stamp says it is
+    # newer than the pass, and both are needed. A worker answers a finding and
+    # the reviewing session closes out seconds later, so the count alone reports
+    # an answered thread on the next run and the session spends a turn learning
+    # `claude-pr-review` will refuse it. The gaps observed were 96, 24, and 35
+    # seconds, which is a reviewing session reading a reply and posting, so this
+    # is the ordinary handback rather than a race.
+    #
+    # A pull request carrying no pass at all reads as stamp zero and reports,
+    # which is the case the count was the right test for: a reply with nothing
+    # behind it is a worker talking to nobody and worth the turn. The test is
+    # strictly greater to match the guard `claude-pr-review` states on the same
+    # two fields, which drops a reply landing inside the same second as the
+    # pass, a narrower failure than the one it removes.
+    #
+    # The gate sits in the condition rather than in the body so a suppressed
+    # reply falls through to STALLED below, which is a thread this run should
+    # still be able to reach.
+    echo "RESPONSE  #$n answered with no new commit"
+    CHANGED=1
+  elif [ "$heading" = open ] && [ "$old_heading" != reported ] &&
+    [ "$prior" = "$head" ] && [ "$age" -ge "$STALE_AFTER" ]; then
+    # Three things at once: the last pass is open, it covers the head so no
+    # commit followed it, and the two branches above found no reply either. The
+    # open heading is posted exactly when a dispatch is owed, per the threshold
+    # `claude-pr-review` states, so a pass owing one left it here at any grade
+    # it carried. Any two of these describe an ordinary review waiting on a
+    # worker, which is why the age carries the third: without it every
+    # dispatched worker is reported minutes into the work it was sent to do,
+    # and a signal firing on the healthy path is one an operator learns to
+    # skip. The report still asks for a confirmation rather than asserting.
+    echo "STALLED   #$n open at ${head:0:7}, no commit or reply in $((age / 3600))h"
+    state=reported
+    CHANGED=1
+  elif [ "$heading" = open ] && [ "$old_heading" = reported ]; then
+    # Nothing above fired, so the thread has not moved since it was reported.
+    # Carry the marker rather than the freshly derived heading, or the state
+    # re-enters next run and STALLED oscillates instead of reporting once.
+    state=reported
+  fi
+  FINAL+="$n $head $prior $resp $merges $state $unmatched_count"$'\n'
+done <<<"$NEW"
+
+while read -r n _rest; do
+  [ -z "$n" ] && continue
+  echo "$NEW" | grep -q "^$n " || {
+    echo "GONE      #$n merged or closed"
+    CHANGED=1
+  }
+done <"$STATE"
+
+[ "$CHANGED" -eq 0 ] && echo "No movement."
+printf '%s' "$FINAL" >"$STATE"