@erclx/aitk 0.60.0 → 0.61.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/SKILL.md

@@ -37,6 +37,8 @@ The roadmap is optional and this skill does not require it. It carries why a seq
 
 A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do. On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It writes `.claude/tasks/session.md` with the state of play, the decisions taken under delegated authority, the mistakes worth not repeating, and the standing cautions. On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
 
+The review trigger takes the same shape. `references/orchestrator-poll.md` holds the loop prompt and the condition under which the poll runs, and `scripts/poll.sh` is what the prompt invokes. Nothing starts or stops that loop on its own, so the condition holds only while a session applies it.
+
 That routing lives in this body and this skill is user-invoked, so a session that has dropped the body routes nothing and the request lands as ordinary conversation. Approaching a compaction is when a long session is likeliest to have dropped it, which is the same moment the handoff exists for. Re-invoke `/aitk:claude-orchestrate` first whenever the session has run long or the ask goes unanswered. The two runbooks sit at `references/orchestrator-handoff.md` and `references/orchestrator-resume.md` inside this skill's own folder, so a person who knows their plugin root opens either one directly and follows it without this skill loaded at all.
 
 ## Output
@@ -96,7 +98,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 3. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
 4. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
 5. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
-6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
+6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate. Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. It routes a moved or answered pull request straight to a re-review and reports an opened one without acting, which keeps every first pass a batched judgment this session triggers.
 7. Close the loop. After the worker runs `claude-address-review`, re-review if needed, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
 
 ## Boundaries

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

@@ -0,0 +1,44 @@
+---
+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. It reads only, and it never starts a first-pass review.
+
+`${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 a dispatch and stop it when the last pull request merges with nothing else out. An open pull request or a dispatched worker is the condition, and both resolve from the board plus `gh pr list` without asking the operator. A release pull request alone does not qualify, since its sweep carries no findings.
+
+Nothing enforces this. No hook starts the poll and no check stops it, so the condition holds only while a session applies it. Left always-on it fires into an empty board through every gap between a dispatch and its push, which leaves stopping it to the operator.
+
+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 prompt
+
+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 `/loop` turn, which arrives as a standalone prompt, so a block carrying the variable reaches the session as a literal string and the run improvises a substitute.
+
+```plaintext
+/loop 3m Poll GitHub for pull request movement by running <POLL_SCRIPT>, then act on what it reports.
+
+- MOVED or RESPONSE on a pull request I have already reviewed: run the aitk: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: report it and stop. First passes wait for the operator, because reading several together is what surfaces cross-PR findings.
+- 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.
+- CONFLICT: report it and stop. The branch owner rebases, not this session.
+- GONE: report it, then sweep the board by invoking the aitk: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.
+
+Never start a first-pass review on your own.
+```
+
+## 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 four review headings the script matches are written by `claude-pr-review` and `claude-address-review`. A project that posts its reviews under different headings edits the two jq filters in the script to match, or every pull request reads as never reviewed.

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

@@ -0,0 +1,202 @@
+#!/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 four strings are owned elsewhere and pinned here. `claude-pr-review`
+# writes `## Review` and `## Review closed`, and `claude-address-review` writes
+# `## Review response` and `## Rebase`. 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 two tests stay symmetric.
+# The reply family carries `## Rebase` because a run sent straight to the rebase
+# step posts under a heading deliberately kept outside the `## Review` family.
+# Widening one family without the other is what left the reply test narrow, so
+# a fifth heading is added here beside its sibling.
+JQ_LAST_REVIEWED_HEAD='
+  [ .reviews[]
+    | select((.body // "") | split("\n")[0] | rtrimstr("\r")
+             | . == "## Review" or . == "## Review closed")
+  ] | last | .commit.oid // empty
+'
+JQ_REPLY_COUNT='
+  [ .comments[]
+    | select((.body // "") | split("\n")[0] | rtrimstr("\r")
+             | . == "## Review response" or . == "## Rebase")
+  ] | length
+'
+
+# 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
+    echo "$old"
+    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
+  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")
+    resp=$(jq -r "$JQ_REPLY_COUNT" <<<"$payload")
+
+    # `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"
+  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
+
+while read -r n head prior resp merges; do
+  [ -z "$n" ] && continue
+  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
+    continue
+  fi
+  old_head=$(echo "$old" | cut -d' ' -f2)
+  old_resp=$(echo "$old" | cut -d' ' -f4)
+  old_merges=$(echo "$old" | cut -d' ' -f5)
+
+  # 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
+
+  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" ]; then
+    echo "RESPONSE  #$n answered with no new commit"
+    CHANGED=1
+  fi
+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."
+echo "$NEW" >"$STATE"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -27,9 +27,9 @@
   },
   "scripts": {
     "check:spell": "cspell '**' '.*/**' '.*' --no-progress --color --show-context",
-    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/",
-    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/",
-    "check:shell": "find scripts tooling .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} +",
+    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/ claude/",
+    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/ claude/",
+    "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} +",
     "check:types": "tsc --noEmit",
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",