@erclx/aitk 0.111.0 → 0.112.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.111.0",
+  "version": "0.112.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -53,6 +53,8 @@ The baseline lives at `.claude/.tmp/pr-poll/baseline.txt` under the main worktre
 
 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.
 
+`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.

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

@@ -48,11 +48,19 @@ JQ_LAST_REVIEWED_HEAD='
              | . == "## Review" or . == "## Review closed")
   ] | last | .commit.oid // empty
 '
-JQ_REPLY_COUNT='
+# 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")
-  ] | length
+  ] as $replies
+  | ($replies | length | tostring)
+    + " "
+    + ([ $replies[] | .createdAt // empty | fromdateiso8601 | floor ]
+       | max // 0 | tostring)
 '
 
 # `claude-pr-review` states the threshold and posts `## Review` exactly when a
@@ -69,18 +77,28 @@ JQ_REPLY_COUNT='
 # 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"
-    else ((.body | split("\n")[0] | rtrimstr("\r")
-           | if . == "## Review" then "open" else "closed" end)
-          + " "
-          + (if .submittedAt == null then "0"
-             else ((now - (.submittedAt | fromdateiso8601)) | floor | tostring)
-             end))
+  | 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
 '
 
@@ -102,7 +120,10 @@ carry_forward() {
   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. STALLED reads a heading that is carried too, so
+    # 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
@@ -146,9 +167,14 @@ snapshot() {
     fi
 
     prior=$(jq -r "$JQ_LAST_REVIEWED_HEAD" <<<"$payload")
-    resp=$(jq -r "$JQ_REPLY_COUNT" <<<"$payload")
-    # Two space-separated fields, so the line below carries them as its own
-    # sixth and seventh rather than needing a split.
+    # 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")
 
     # `gh pr view --json mergeable` reports UNKNOWN until GitHub finishes
@@ -168,7 +194,7 @@ snapshot() {
       merges=conflict
     fi
 
-    echo "$n $head ${prior:-none} $resp $merges $review_state"
+    echo "$n $head ${prior:-none} $resp $merges $review_state $reply_at"
   done
 }
 
@@ -185,7 +211,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; do
+while read -r n head prior resp merges heading age pass_at reply_at; do
   [ -z "$n" ] && continue
   state=$heading
   old=$(grep "^$n " "$STATE" || true)
@@ -244,7 +270,26 @@ while read -r n head prior resp merges heading age; do
       fi
     fi
     CHANGED=1
-  elif [ "$resp" -gt "$old_resp" ]; then
+  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 ] &&

package/governance/rules/claude/561-teach.md

@@ -0,0 +1,20 @@
+---
+description: Route .claude/teach/ edits to the teach standard for layout, ordinal naming, and the mission and record formats, in the projects that open a learning workspace
+paths:
+  - '.claude/teach/**'
+---
+
+# Teach standards
+
+## What a workspace keeps
+
+- Never renumber an existing folder, lesson, or record. A later reader cites it by the name it opened under.
+- Write every success line as a task the learner can be asked to perform, never as something they will understand.
+- Keep a reference page free of the learner. A page carrying second person or a quiz belongs under `lessons/`.
+- Record the wrong answer a learner gave, never a count of what they missed.
+- Date the workspace once, in the `MISSION.md` frontmatter. Never repeat the date in the body of any file.
+
+## Authority
+
+- Follow `.claude/standards/teach.md` for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source.
+- Follow `.claude/standards/glossary.md` for the glossary every workspace carries at its root.

package/governance/rules/claude/562-session.md

@@ -0,0 +1,19 @@
+---
+description: Route .claude/tasks/ session map edits to the session standard for the filename, the core sections, and what a handoff carries
+paths:
+  - '.claude/tasks/session-*.md'
+---
+
+# Session map standards
+
+## What a handoff carries
+
+- Follow this rule rather than `555-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
+- Never write into a file another session owns. Overwrite only the file the writing session already wrote.
+- Resolve the containing folder at the main worktree root, never inside a linked worktree.
+- Write only what a compaction destroys. Do not restate the board and do not summarize what shipped.
+- Cite a commit, a task, or a file and line for every claim, so a reader can tell a read from a recall.
+
+## Authority
+
+- Follow `.claude/standards/session.md` for the filename and location, frontmatter, the core sections, and the write and read procedures. It is the single source.

package/package.json

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