@erclx/aitk 3.11.0 → 3.11.2

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.2",
   "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/REQUIREMENT.md

@@ -11,6 +11,8 @@ Without this skill, a pull request is reviewed only by the session that wrote it
 
 A finding also stops being true by argument rather than by a fix. A worker naming the plan question that already declined it, or a constraint the pass could not see, settles it in the exchange that carried the answer, and the pass that accepts the argument drops the finding from its next body. A reader then sees a finding raised once and never mentioned again, which is indistinguishable from one everyone forgot.
 
+A request written under `## For the reviewer` also reached no reader. The authoring standard names it as what the reviewing session should confirm, and nothing on this side read the section by that name, so a branch author's question sat in the body until this skill answered it.
+
 ## Must
 
 - Post until the review closes. A first pass opens against the whole change, and each later pass checks whether the prior findings landed.
@@ -22,6 +24,7 @@ A finding also stops being true by argument rather than by a fix. A worker namin
 - State a withdrawal or a regrade on the thread with the fact that settled it, since a finding dropped in silence reads the same as one nobody answered
 - Key the body file on the pull request number and the head commit, and on the response it answers once the head repeats, so no two passes overwrite each other
 - Scan the comment for banned characters and internal phase labels before posting, since a finding phrased against a phase label reaches a reader with no task board
+- Answer a `## For the reviewer` bullet in the body, bounded to the section itself rather than the Summary or the Technical Context around it, so the independent vantage stays clear of the author's framing
 
 ## Must not
 

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

@@ -15,7 +15,7 @@ review against the whole change, and every later pass reads only the commits
 added since. The heading reports state rather than pass number: a pass carrying
 anything owed takes `## Review`, and `## Review closed` covers a pass carrying
 none, so the most recent comment's heading reports whether any work is owed.
-Owed is a finding at any severity or a Testing question, defined once at Step 4. Every pass is this skill, and which one it is gets detected from
+Owed is a finding at any severity, a Testing question, or a reviewer request nobody has answered, defined once at Step 4. Every pass is this skill, and which one it is gets detected from
 the thread rather than named by the caller.
 
 ## Guards
@@ -89,6 +89,10 @@ Test every unchecked box against the testing discipline in `${CLAUDE_SKILL_DIR}/
 
 Ask rather than grade. Whether a human is genuinely required is a reading the branch author may hold a reason this session cannot see, so the question carries no severity and enters no count. What it does carry is the heading and the dispatch, on the rule Step 4 states, because a question the author never receives corrects nothing and the author is the only party who can answer it. Answering it closes it, and the answer may be that the requirement holds.
 
+Read `## For the reviewer` the same way, bounded to the bullets under that heading rather than the Summary or the Technical Context around it. Those two carry the author's argument for the change, and reading them while judging it is most of what an independent pass exists to avoid, so the read stops at the section itself.
+
+Answer each bullet in the body, on the same terms as a Testing question: no severity, no count. A request nobody can answer stays owed under the heading and dispatch Step 4 states, keeping the thread open exactly as an unanswered Testing box does. One the pass does answer carries no further weight, since the answer is discharged in the same comment that carries it.
+
 Apply the high-signal filter: flag only what will cause incorrect behavior, break a documented rule, or mislead a downstream feature. If uncertain, do not flag.
 
 A later pass applies the same axes to the delta, and adds one check the first pass cannot make: did each prior finding land, and did the fix regress anything it touched. Findings of its own are normal findings, stated at the same severity and counted the same way. That count is one of the two things Step 4 reads to pick the heading, so a pass raising a finding of its own is not a close-out at any severity.
@@ -160,7 +164,17 @@ A Testing box the Step 3 check raised goes in a `**Testing**` block placed after
 
 Keep it to the boxes the check raised. Restating a box whose stated requirement holds teaches the branch author to skip the block.
 
-The threshold is stated here and nowhere else, and every other surface acting on it cites this skill rather than restating the grades. One rule governs both the heading and the dispatch: a pass carrying anything owed takes `## Review` and owes a dispatch to the session holding the branch, and a pass carrying nothing at all takes `## Review closed` and owes none. Owed covers a finding at any severity and a Testing question alike, which is what keeps the two halves from separating. Sending that dispatch is `claude-orchestrate`'s step rather than this one, which posts and stops. Post the open heading whether it is the first pass or the fourth. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `claude-address-review`, another `## Review` while anything stays open, and `## Review closed` when nothing does.
+Every `## For the reviewer` bullet Step 3 read goes in a `**For the reviewer**` block placed after the Testing block, one bullet per request, each followed by its answer or, where the pass could not answer it, by what would settle it. It carries no severity and enters no count.
+
+An unanswered bullet is owed the same way an unanswered Testing box is, so a pass carrying one takes `## Review` and the full body rather than either ✅ line. A bullet the pass answered is not owed, since the answer is discharged in the same comment that carries it. A pass still posting a numeric summary line, because a finding, a Testing question, or an unanswered bullet already forces one, says so there as `plus N reviewer request(s)`. The all-answered close-out below carries the block in place of that line and needs no addition to it.
+
+```markdown
+**For the reviewer**
+
+- Confirm the 401 and 403 split reads correctly for the public API. Confirmed — `AuthService.authenticate()` returns 401 for an expired token and 403 for a missing scope, and both paths are covered under `## Testing`.
+```
+
+The threshold is stated here and nowhere else, and every other surface acting on it cites this skill rather than restating the grades. One rule governs both the heading and the dispatch: a pass carrying anything owed takes `## Review` and owes a dispatch to the session holding the branch, and a pass carrying nothing at all takes `## Review closed` and owes none. Owed covers a finding at any severity, a Testing question, and a reviewer request nobody has answered alike, which is what keeps the two halves from separating. Sending that dispatch is `claude-orchestrate`'s step rather than this one, which posts and stops. Post the open heading whether it is the first pass or the fourth. A pull request thread then reads as `## Review`, the worker's answer under `## Review response` from `claude-address-review`, another `## Review` while anything stays open, and `## Review closed` when nothing does.
 
 Keying either half on the grade was measured wrong: across 8 findings on one archived pass, 3 were posted as minor and 2 of those were defects a worker fixed rather than recorded, so a floor at should-fix loses real fixes to a grade that runs low. Splitting the two halves so the dispatch fired lower than the heading was the other candidate, and it left a thread reading closed while work was owed on it. The Testing question was first written to sit outside both, which is that same split reached from the other side, and it left the one party who could answer the question with no route to it.
 
@@ -170,7 +184,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`.
 
@@ -190,7 +206,7 @@ gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>
 
 A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No findings. Reviewed against project docs and the board.` On a later pass, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.`
 
-A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. A pass carrying only Testing questions takes the same route for the same reason. Keep whichever scope sentence the pass owes on the summary line:
+A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. A pass carrying only Testing questions, or only an unanswered reviewer request, takes the same route for the same reason. Keep whichever scope sentence the pass owes on the summary line:
 
 ```markdown
 ## Review
@@ -206,6 +222,8 @@ A pass carrying only minors is an ordinary finding-carrying pass, so it takes th
 
 A pass that closed by withdrawing a finding rather than by reading its fix takes neither ✅ line, per the withdrawal rule in Step 3. Both claim a fix landed, and the second names it, so posting either over a withdrawal credits work nobody did on the one comment a reader treats as the verdict. Write the withdrawal and the fact that settled it in place of the canned line, keeping the heading and the footer.
 
+A pass whose only content is a `## For the reviewer` block with every bullet answered, and that owes nothing else, takes the same shape: `## Review closed`, the block in place of the canned line, and the footer. The heading reports what the branch author still owes rather than what the pass did, and an answer discharged in the same comment owes nothing back.
+
 Post a close-out even when there is nothing to report. A review left with no closing comment reads as one nobody answered.
 
 ## Step 5: output
@@ -216,4 +234,6 @@ X critical, Y should-fix, Z minor. Posted to PR #<number>.
 
 Add `N Testing question(s) raised.` to that line when the Step 3 check raised any. The counts cover findings alone, so a pass whose only output was a question otherwise reports as silent to the session that drove it. That session is not who the question is addressed to, which is what the dispatch covers.
 
+Add `N reviewer request(s) answered.` to that line when the PR body carried a `## For the reviewer` section. The counts and the Testing question line both cover something else, so a pass that only answered a request otherwise reports as silent too.
+
 Report the merge decision as a plain recommendation in chat (merge, or address findings first). Do not merge.

package/package.json

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

package/standards/pr.md

@@ -43,7 +43,7 @@ Does not govern:
 - `## Testing` (optional): specify exact commands or test cases run
 - Omit Testing for docs, config, or trivial sync changes
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
-- `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
+- `## For the reviewer` (optional): what the reviewing session should confirm, one bullet per request
 - Visuals: include only when they clarify architecture, UI, or complex logic flows
 
 ## Testing discipline
@@ -88,7 +88,7 @@ Does not govern:
 
 ## For the reviewer
 
-- <What the reviewer should confirm>
+- <What the reviewing session should confirm>
 ```
 
 ### Correct
@@ -134,5 +134,5 @@ This PR updates the authentication system to be more robust. # "This PR" opener
 
 - Tested manually # no specific command or case
 - [ ] `npm run test:auth` # unchecked box for a check the agent can run
-- [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
+- [ ] The reviewing session confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
 ```