@erclx/aitk 3.11.0 → 3.11.1

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

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

package/claude/skills/claude-address-review/SKILL.md

@@ -194,3 +194,13 @@ Rebased PR #<number> onto origin/main. <N> files resolved by hand, <N> rebuilt b
 ```
 
 Do not merge. Hand back to the orchestrator for re-review.
+
+## Post-review findings
+
+Not everything worth reaching the reviewing session surfaces inside the numbered flow above. A worker that settled a risk, filed a follow-up, or found something else worth reporting after Step 7 already closed the review posts it directly rather than waiting on a review pass that has nothing left to trigger it. Write the body the way Step 6 writes a reply: load `write-human` for voice, follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` for the banned words, and run the `${CLAUDE_SKILL_DIR}/../../standards/publish.md` scan before posting.
+
+Open with `## Post-review findings` rather than `## Review response`, since nothing on the thread is being answered. `claude-pr-review` states the full heading set this belongs to and routes it the same as a response: `claude-orchestrate`'s poll picks it up and sends the reviewing session back for a pass. Close the body with `🤖 Addressed by Claude Code` on its own line, matching the reply's footer.
+
+```bash
+gh pr comment <number> --body-file .claude/.tmp/address-review/reply-<number>.md
+```

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

@@ -36,6 +36,7 @@ Poll GitHub for pull request movement by running <POLL_SCRIPT>, then act on what
 - 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 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.
@@ -51,7 +52,9 @@ The script exits non-zero and classifies nothing when the open pull request list
 
 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 three jq filters in the script to match, or every pull request reads as never reviewed.
+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.
 

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

@@ -32,16 +32,19 @@ if [ -z "$BASE_REF" ]; then
 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
+# 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 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.
+# 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")
@@ -55,13 +58,37 @@ JQ_LAST_REVIEWED_HEAD='
 JQ_REPLY_STATE='
   [ .comments[]
     | select((.body // "") | split("\n")[0] | rtrimstr("\r")
-             | . == "## Review response" or . == "## Rebase")
+             | . == "## 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
@@ -176,6 +203,11 @@ snapshot() {
     # 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
@@ -194,7 +226,7 @@ snapshot() {
       merges=conflict
     fi
 
-    echo "$n $head ${prior:-none} $resp $merges $review_state $reply_at"
+    echo "$n $head ${prior:-none} $resp $merges $review_state $reply_at $unmatched_count $unmatched_heading"
   done
 }
 
@@ -211,7 +243,7 @@ CHANGED=0
 # 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; do
+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)
@@ -229,7 +261,7 @@ while read -r n head prior resp merges heading age pass_at reply_at; do
       echo "OPENED    #$n at ${head:0:7}, $merges against $BASE_BRANCH"
     fi
     CHANGED=1
-    FINAL+="$n $head $prior $resp $merges $state $age"$'\n'
+    FINAL+="$n $head $prior $resp $merges $state $unmatched_count"$'\n'
     continue
   fi
   old_head=$(echo "$old" | cut -d' ' -f2)
@@ -240,6 +272,7 @@ while read -r n head prior resp merges heading age pass_at reply_at; do
   # 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.
@@ -248,6 +281,19 @@ while read -r n head prior resp merges heading age pass_at reply_at; do
     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"
@@ -312,7 +358,7 @@ while read -r n head prior resp merges heading age pass_at reply_at; do
     # re-enters next run and STALLED oscillates instead of reporting once.
     state=reported
   fi
-  FINAL+="$n $head $prior $resp $merges $state"$'\n'
+  FINAL+="$n $head $prior $resp $merges $state $unmatched_count"$'\n'
 done <<<"$NEW"
 
 while read -r n _rest; do

package/claude/skills/claude-pr-review/SKILL.md

@@ -170,7 +170,9 @@ A minor the dispatched worker declines is what needs a surface that survives the
 
 Read the state off the most recent review comment rather than off the presence of a closed one. A close-out does not close the pull request, so a commit pushed after it gets its own pass, and that pass reopens the review under `## Review` when it raises a finding of any grade.
 
-Both of this skill's headings anchor as a section distinct from human threads. Do not invent one beyond those two and the `## Review response` a sibling owns, and do not append the PR number, which GitHub already renders above the comment.
+Both of this skill's headings anchor as a section distinct from human threads, and neither invents beyond what the whole set already states. That set is five headings across two families, stated here once so `claude-orchestrate`'s poll and every reply-posting skill cite it rather than carry a copy. The review family, `## Review` and `## Review closed`, belongs to this skill alone, and the reply family, `## Review response`, `## Rebase`, and `## Post-review findings`, belongs to `claude-address-review`.
+
+The first reply heading answers a finding this skill posted, the second reports a stale branch resolved without one, and the third carries a finding a worker produces after a close-out rather than in answer to one already on the thread, since a finding produced late is still a finding. A comment posted under a heading outside these five reaches the poll as unclassified rather than as silence, so an invented sixth heading is a gap the next run reports instead of one it repeats. Do not append the PR number, which GitHub already renders above the comment.
 
 Name the scope in every summary line after the first pass, since a reader cannot otherwise tell a narrow read from a full one. When the fallback in Step 2 fired, replace the commit count with `Re-reviewed the full change, the prior pass's commit is no longer on the branch`.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.11.0",
+  "version": "3.11.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {