@erclx/aitk 0.60.0 → 0.62.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.62.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -60,38 +60,10 @@ git fetch origin main
 git merge-tree --write-tree origin/main HEAD
 ```
 
-A zero exit means the branch still merges. Skip to step 6. A non-zero exit means
-it does not. Stash the fixes first when `git status --porcelain` reports
-anything, since a rebase refuses to run over a dirty tree, then rebase onto
-`origin/main` and restore them:
-
-```bash
-git stash push -u
-git rebase origin/main
-git stash pop
-```
-
-Pop only when the stash ran. On a clean tree, which is what a run whose findings
-were all conscious-accepts leaves behind, `git stash push` saves nothing and
-exits zero, so the pop restores an unrelated entry from an earlier session.
-
-Never merge `main` into the branch. The repository squash-merges, so a merge
-commit here reads as noise on the pull request.
-
-Resolve every conflict under these rules, which apply to a hunk from the rebase
-and a hunk from the stash pop alike:
-
-- Never take one side wholesale with `--ours` or `--theirs`. Both sides are valid content, so the drop is silent and passes every check.
-- Never resolve a generated file by hand. A file the project check rebuilds, such as an `index.md` carrying no `auto: false`, takes either side to clear the conflict and gets its real content from the regen below.
-- Where two branches wrote prose into one file, keep both sides and rewrite what the merge broke. A section that opens by counting what follows needs the count updated rather than the two versions concatenated.
-- When a hunk needs a decision the tree does not carry, stop rather than guessing, and name where the branch was left. The two sources recover differently. A hunk raised by the rebase takes `git rebase --abort`, which restores the old base: `❌ Conflict needs a decision at <file>. Branch left on its old base.` A hunk raised by the stash pop arrives after the rebase already landed, so no abort applies and the conflict stays in the tree: `❌ Conflict needs a decision at <file>. Branch rebased, fixes left conflicted in the tree.` A guess that compiles is the failure this stage would otherwise introduce, and either case reaches the operator as an ordinary finding on the next review pass.
-
-Both sides of every hunk sit in the conflict and `git log origin/main` names what
-landed, so the tree carries the context. Do not wait on the orchestrator for it.
-
-Re-run the project check after the rebase. It rebuilds the generated files and
-covers what the replayed commits broke, and step 6 commits the result alongside
-the fixes.
+A zero exit means the branch still merges. Skip to step 6, which is the ordinary
+run. A non-zero exit means it does not, so read
+`${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` for the stash-and-rebase
+sequence, the conflict resolution rules, and the check to re-run afterward.
 
 `git merge-tree` reads committed history, so this test says nothing about the
 fixes still sitting in the working tree. A branch that merges clean as committed,
@@ -118,8 +90,9 @@ with `git push --force-with-lease`, then post the reply below.
 
 Once the fixes are commits, re-run step 5's staleness test against the new head.
 A conflict that appears only now is one the fixes introduced against lines `main`
-moved, which the earlier test could not see. Rebase again under step 5's rules
-and force-push, then continue. The second push costs one extra force-push in a
+moved, which the earlier test could not see. Rebase again under
+`${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` and force-push, then
+continue. The second push costs one extra force-push in a
 case that needs the fix and the sibling to touch the same lines.
 
 Then write a summary reply to `.claude/.tmp/address-review/reply-<number>.md`

package/claude/skills/claude-address-review/references/rebase-conflicts.md

@@ -0,0 +1,37 @@
+---
+title: Rebase a stale branch
+description: The stash-and-rebase sequence, the conflict resolution rules, and the two recovery messages a hunk needing a decision takes
+---
+
+# Rebase a stale branch
+
+Mechanics for Step 5 of `claude-address-review` once `git merge-tree` exits non-zero. A branch that still merges skips this file entirely, which is the ordinary run.
+
+## The sequence
+
+Stash the fixes first when `git status --porcelain` reports anything, since a rebase refuses to run over a dirty tree, then rebase onto `origin/main` and restore them:
+
+```bash
+git stash push -u
+git rebase origin/main
+git stash pop
+```
+
+Pop only when the stash ran. On a clean tree, which is what a run whose findings were all conscious-accepts leaves behind, `git stash push` saves nothing and exits zero, so the pop restores an unrelated entry from an earlier session.
+
+Never merge `main` into the branch. The repository squash-merges, so a merge commit here reads as noise on the pull request.
+
+## Resolving a conflict
+
+These rules apply to a hunk from the rebase and a hunk from the stash pop alike:
+
+- Never take one side wholesale with `--ours` or `--theirs`. Both sides are valid content, so the drop is silent and passes every check.
+- Never resolve a generated file by hand. A file the project check rebuilds, such as an `index.md` carrying no `auto: false`, takes either side to clear the conflict and gets its real content from the regen below.
+- Where two branches wrote prose into one file, keep both sides and rewrite what the merge broke. A section that opens by counting what follows needs the count updated rather than the two versions concatenated.
+- When a hunk needs a decision the tree does not carry, stop rather than guessing, and name where the branch was left. The two sources recover differently. A hunk raised by the rebase takes `git rebase --abort`, which restores the old base: `❌ Conflict needs a decision at <file>. Branch left on its old base.` A hunk raised by the stash pop arrives after the rebase already landed, so no abort applies and the conflict stays in the tree: `❌ Conflict needs a decision at <file>. Branch rebased, fixes left conflicted in the tree.` A guess that compiles is the failure this stage would otherwise introduce, and either case reaches the operator as an ordinary finding on the next review pass.
+
+Both sides of every hunk sit in the conflict and `git log origin/main` names what landed, so the tree carries the context. Do not wait on the orchestrator for it.
+
+## After the rebase
+
+Re-run the project check. It rebuilds the generated files and covers what the replayed commits broke, and step 6 commits the result alongside the fixes.

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

@@ -107,35 +107,7 @@ Skip this step silently when `.claude/wireframes/` does not exist or has no surf
 
 Reuse the diff from the baseline above and filter for UI-affecting paths. UI-affecting paths are framework-dependent. Default heuristic: any file under a `components/`, `features/`, `pages/`, `app/`, `routes/`, or `screens/` folder, plus any `*.tsx`, `*.jsx`, `*.vue`, or `*.svelte` file anywhere in the diff.
 
-For each UI-affecting path, derive a candidate surface slug from the file's basename and parent folder (e.g. `web/src/features/mock/MockDemoStrip.tsx` → `mock-demo-strip` or `mock`). Cross-reference against the surface files in `.claude/wireframes/`:
-
-- **Contradicted sections:** when a surface file exists for a path in the diff and the diff renames or removes a literal string that appears in the wireframe prose (e.g. provider name, button label, copy string), output a one-line report entry and stop. Do not auto-rewrite prose. Operator resolves.
-- **Uncovered surfaces:** when a UI-affecting path has no matching surface file by slug, write `.claude/wireframes/<slug>.md` with this stub:
-
-  ```markdown
-  ---
-  title: <Slug as title case>
-  description: TODO: describe the surface.
-  ---
-
-  # <Slug as title case>
-
-  TODO: describe when and where this surface appears.
-
-  ## Behavior
-
-  - TODO
-  ```
-
-  Skip the write when the slug would collide with an existing file (different surface, same slug). Surface the collision in the report instead.
-
-Output one line per finding:
-
-- `⚠ Wireframe drift in .claude/wireframes/<surface>.md: <contradicted string>`
-- `📝 Stubbed: .claude/wireframes/<surface>.md`
-- `⚠ Slug collision: <slug> matches existing <existing-surface>.md, review and rename`
-
-If the sweep finds nothing, skip silently.
+Skip silently when the filter leaves nothing, which is every branch touching no UI. Otherwise read `${CLAUDE_SKILL_DIR}/references/wireframe-sweep.md` for the slug derivation, the two findings it reports, the stub it writes, and the output lines.
 
 ## Step 5: diagram staleness sweep
 
@@ -147,49 +119,7 @@ Follow `.claude/standards/diagrams.md` for the marker fields this step writes, o
 
 Both findings key on something literally entering or leaving the tree. Anything looser fires on ordinary feature work and rebuilds the ignored warning this sweep replaced.
 
-**Contradicted entries.** For each entry, collect the backticked code paths its explanation cites. When a cited path is in the diff as a delete or a rename and no longer exists in the tree, append a `stale` key to that entry's frontmatter naming the path:
-
-```yaml
-stale: 'src/gov/install.ts no longer exists'
-```
-
-Append that key alone. Never edit `verified`, `title`, `description`, or `category`, and never touch the body. When the entry already carries `stale`, extend the existing line rather than adding a second key.
-
-**Uncovered kinds.** The standard fixes one source signal per kind. Stub a kind when the diff adds its signal file and no entry covers that kind. The trigger is the signal appearing, never a file under it changing, so a branch editing a component folder that `components.md` already covers produces nothing here.
-
-| Signal added by the diff                                                                                           | Kind stubbed when absent |
-| ------------------------------------------------------------------------------------------------------------------ | ------------------------ |
-| `.claude/REQUIREMENTS.md`                                                                                          | `system-context.md`      |
-| `.claude/ARCHITECTURE.md`                                                                                          | `components.md`          |
-| A deploy or infrastructure config (`Dockerfile`, `.github/workflows/*`, `vercel.json`, `fly.toml`, `compose.yaml`) | `deployment.md`          |
-
-Leave `request-flow.md` and `data-pipeline.md` out. Neither has a source signal a diff can point at, so a rule covering them would guess at when they went stale.
-
-Write the stub at `.claude/diagrams/<kind>.md`:
-
-```markdown
----
-title: <Kind as title case>
-description: 'TODO: name the question this entry settles.'
-category: <the category the standard fixes for this kind>
-verified: 'TODO: never verified'
----
-
-# <Kind as title case>
-
-TODO: draw this. `<signal path>` entered the tree with no entry covering this kind.
-
-Run `/claude-diagram <kind>` to replace the stub.
-```
-
-No mermaid fence. An empty stub is visible debt that reaches review through the branch diff, while a generated diagram nobody rendered is invisible debt that reads as verified. A fence here invites the next session to fill it in without a render.
-
-Output one line per finding:
-
-- `⚠ Diagram stale: .claude/diagrams/<kind>.md cites <path>, which left the tree`
-- `📝 Stubbed: .claude/diagrams/<kind>.md`
-
-If the sweep finds nothing, skip silently. An ordinary change that adds no signal and deletes no cited path produces no output at all.
+Past the skip above, read `${CLAUDE_SKILL_DIR}/references/diagram-sweep.md` for the two findings, the signal table deciding an uncovered kind, the stub it writes, and the output lines. Both tests need the cited paths and the signal list that file carries, so the folder check is the only one the body can settle on its own.
 
 ## Step 6: flag CLAUDE.md drift
 

package/claude/skills/claude-docs/references/diagram-sweep.md

@@ -0,0 +1,58 @@
+---
+title: Diagram staleness sweep
+description: The contradicted-entry marker, the source-signal table that decides an uncovered kind, the stub it writes, and the report lines
+---
+
+# Diagram staleness sweep
+
+Mechanics for Step 5 of `claude-docs`. The body owns the skip conditions, the frontmatter-only constraint, and the standard citation, and this file owns what the sweep does once the diff carries a delete or a new source signal.
+
+## Contradicted entries
+
+For each entry, collect the backticked code paths its explanation cites. When a cited path is in the diff as a delete or a rename and no longer exists in the tree, append a `stale` key to that entry's frontmatter naming the path:
+
+```yaml
+stale: 'src/gov/install.ts no longer exists'
+```
+
+Append that key alone. Never edit `verified`, `title`, `description`, or `category`, and never touch the body. When the entry already carries `stale`, extend the existing line rather than adding a second key.
+
+## Uncovered kinds
+
+The standard fixes one source signal per kind. Stub a kind when the diff adds its signal file and no entry covers that kind. The trigger is the signal appearing, never a file under it changing, so a branch editing a component folder that `components.md` already covers produces nothing here.
+
+| Signal added by the diff                                                                                           | Kind stubbed when absent |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| `.claude/REQUIREMENTS.md`                                                                                          | `system-context.md`      |
+| `.claude/ARCHITECTURE.md`                                                                                          | `components.md`          |
+| A deploy or infrastructure config (`Dockerfile`, `.github/workflows/*`, `vercel.json`, `fly.toml`, `compose.yaml`) | `deployment.md`          |
+
+Leave `request-flow.md` and `data-pipeline.md` out. Neither has a source signal a diff can point at, so a rule covering them would guess at when they went stale.
+
+Write the stub at `.claude/diagrams/<kind>.md`:
+
+```markdown
+---
+title: <Kind as title case>
+description: 'TODO: name the question this entry settles.'
+category: <the category the standard fixes for this kind>
+verified: 'TODO: never verified'
+---
+
+# <Kind as title case>
+
+TODO: draw this. `<signal path>` entered the tree with no entry covering this kind.
+
+Run `/claude-diagram <kind>` to replace the stub.
+```
+
+No mermaid fence. An empty stub is visible debt that reaches review through the branch diff, while a generated diagram nobody rendered is invisible debt that reads as verified. A fence here invites the next session to fill it in without a render.
+
+## Output
+
+Output one line per finding:
+
+- `⚠ Diagram stale: .claude/diagrams/<kind>.md cites <path>, which left the tree`
+- `📝 Stubbed: .claude/diagrams/<kind>.md`
+
+If the sweep finds nothing, skip silently. An ordinary change that adds no signal and deletes no cited path produces no output at all.

package/claude/skills/claude-docs/references/wireframe-sweep.md

@@ -0,0 +1,45 @@
+---
+title: Wireframe coverage sweep
+description: Slug derivation from a UI-affecting path, the contradicted and uncovered findings, the surface stub, and the report lines
+---
+
+# Wireframe coverage sweep
+
+Mechanics for Step 4 of `claude-docs`. The body owns the skip conditions and the UI-path filter, and this file owns what the sweep does once a UI-affecting path survives that filter.
+
+## Deriving a candidate slug
+
+For each UI-affecting path, derive a candidate surface slug from the file's basename and parent folder (e.g. `web/src/features/mock/MockDemoStrip.tsx` → `mock-demo-strip` or `mock`). Cross-reference against the surface files in `.claude/wireframes/`.
+
+## Findings
+
+**Contradicted sections.** When a surface file exists for a path in the diff and the diff renames or removes a literal string that appears in the wireframe prose (e.g. provider name, button label, copy string), output a one-line report entry and stop. Do not auto-rewrite prose. Operator resolves.
+
+**Uncovered surfaces.** When a UI-affecting path has no matching surface file by slug, write `.claude/wireframes/<slug>.md` with this stub:
+
+```markdown
+---
+title: <Slug as title case>
+description: TODO: describe the surface.
+---
+
+# <Slug as title case>
+
+TODO: describe when and where this surface appears.
+
+## Behavior
+
+- TODO
+```
+
+Skip the write when the slug would collide with an existing file (different surface, same slug). Surface the collision in the report instead.
+
+## Output
+
+Output one line per finding:
+
+- `⚠ Wireframe drift in .claude/wireframes/<surface>.md: <contradicted string>`
+- `📝 Stubbed: .claude/wireframes/<surface>.md`
+- `⚠ Slug collision: <slug> matches existing <existing-surface>.md, review and rename`
+
+If the sweep finds nothing, skip silently.

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

@@ -88,41 +88,7 @@ Rules that resist crisp one-line phrasing default to **Retire** over promote. Ne
 
 Derive `<slug>` per `.claude/standards/slug.md`, or `${CLAUDE_SKILL_DIR}/../../standards/slug.md` when the project does not have it. Fall back to `latest` on an empty result.
 
-Write the full proposal to `.claude/review/memory-review-<slug>.md` at the main worktree root. Do not print it inline.
-
-Structure: a summary block at the top, a legend, then one H2 per numbered item. Number items across all actions so the user can reference them by number. Fuse the status, action, and target into each H2. Put the memory filename on its own line, a one-line Why, the rewritten rule inline in a fenced `diff` block prefixed with `+` so reviewers see the additions in green, and a `Decision:` slot for the user. Do not include a `Take:` slot in the template. Discuss inserts one directly under `Decision:` only when responding to a question item. Status starts as 📝 pending for every item at proposal time.
-
-````plaintext
-# Memory review: <slug>
-
-**Pending:** <all numbers>
-
-Legend: ✅ applied · ⏭ skipped · 📦 retired · 🤝 handed off · 📝 pending
-
-How to respond: fill in `Decision:` per item (`apply`, `skip`, `defer`, or a question with `?`), then re-ping the skill. Say "discuss" for question rounds, "apply" to commit. Chat shortcut: `all`, `none`, or a list of numbers.
-
-## 1. 📝 Promote → `<target>`
-
-`<memory-file>`
-
-Why: <one-line pulled from the memory's Why>
-
-```diff
-+ <rewritten rule text>
-```
-
-Decision:
-
-## 2. 📝 Retire
-
-`<memory-file>`
-
-Reason: <one-line reason>
-
-Decision:
-````
-
-For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `aitk-governance` and `.claude/standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For Retire items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.
+Write the full proposal to `.claude/review/memory-review-<slug>.md` at the main worktree root. Do not print it inline. Read `${CLAUDE_SKILL_DIR}/references/receipt-format.md` for the file structure, the item template, and how each action type varies the body. The four phases below rewrite items inside an existing receipt rather than authoring one, so none of them opens it.
 
 Tell the user `✅ Wrote proposal to .claude/review/memory-review-<slug>.md`. Ask them to fill in `Decision:` per item, then re-ping with "discuss" for question rounds or "apply" to commit.
 

package/claude/skills/claude-memory-review/references/receipt-format.md

@@ -0,0 +1,46 @@
+---
+title: Memory review receipt format
+description: The proposal file structure, its item template, and how each action type varies the body
+---
+
+# Memory review receipt format
+
+The shape Step 4 of the Propose phase writes to `.claude/review/memory-review-<slug>.md`. Only Propose writes this file. Challenge, Discuss, and Apply rewrite items inside a receipt that already exists, and Cleanup deletes one, so none of the four needs this file.
+
+## Structure
+
+A summary block at the top, a legend, then one H2 per numbered item. Number items across all actions so the user can reference them by number. Fuse the status, action, and target into each H2. Put the memory filename on its own line, a one-line Why, the rewritten rule inline in a fenced `diff` block prefixed with `+` so reviewers see the additions in green, and a `Decision:` slot for the user. Do not include a `Take:` slot in the template. Discuss inserts one directly under `Decision:` only when responding to a question item. Status starts as 📝 pending for every item at proposal time.
+
+````plaintext
+# Memory review: <slug>
+
+**Pending:** <all numbers>
+
+Legend: ✅ applied · ⏭ skipped · 📦 retired · 🤝 handed off · 📝 pending
+
+How to respond: fill in `Decision:` per item (`apply`, `skip`, `defer`, or a question with `?`), then re-ping the skill. Say "discuss" for question rounds, "apply" to commit. Chat shortcut: `all`, `none`, or a list of numbers.
+
+## 1. 📝 Promote → `<target>`
+
+`<memory-file>`
+
+Why: <one-line pulled from the memory's Why>
+
+```diff
++ <rewritten rule text>
+```
+
+Decision:
+
+## 2. 📝 Retire
+
+`<memory-file>`
+
+Reason: <one-line reason>
+
+Decision:
+````
+
+## Variation by action
+
+For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `aitk-governance` and `.claude/standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For Retire items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.

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/docs/agents/skills-audit.md

@@ -40,7 +40,7 @@ A body whose frontmatter does not parse reports as declaring neither field rathe
 
 ## What it leaves alone
 
-The report names its own blind spots on every run, including the run where everything passed. Whether each `Must` traces to a stated gap is the rule in that standard worth the most and no parser reads it. Whether a gap states an observed failure rather than an intent, and whether a description routes, are the same kind of judgment. The 5,000-word body ceiling is mechanical and still absent here.
+The report names its own blind spots on every run, including the run where everything passed. Whether each `Must` traces to a stated gap is the rule in that standard worth the most and no parser reads it. Whether a gap states an observed failure rather than an intent, and whether a description routes, are the same kind of judgment. The 150-line body checkpoint is the one mechanical rule still absent here, and adding it would print a count rather than a defect, since the standard makes it a prompt to look with nothing enforcing it.
 
 A check with no rule behind it prints an opinion as a defect, which is where the list stops.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.60.0",
+  "version": "0.62.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",

package/src/commands/claude.ts

@@ -689,5 +689,7 @@ function reportUnmeasured(): void {
   logInfo(
     'Whether each Must traces to a stated gap, whether a gap reads as an observed failure rather than an intent, and whether a description routes.',
   )
-  logInfo('The 5,000-word body ceiling is mechanical and still absent here.')
+  logInfo(
+    'The 150-line body checkpoint is mechanical and still absent here, and it would print a count rather than a defect.',
+  )
 }

package/standards/skill.md

@@ -184,7 +184,11 @@ Without this skill, a session <observed failure>, <observed failure>.
 
 ### Progressive disclosure
 
-- Keep `SKILL.md` under 5,000 words. Move detailed docs to `references/`.
+- Look at a body once it passes 150 lines. The number prompts a look rather than gating a build, so nothing enforces it and a body carrying nothing but procedure stays whole at any length.
+- Move a catalog, a table of cases, or a format spec running past roughly 15 lines to `references/`. Procedure prose stays, since a session sent to a reference for its own steps pays two reads for one job.
+- Name the branch that skips a block before moving it. Body lines are paid on every invocation and a reference only when the body sends the session to it, so a block every run dereferences costs a read and saves nothing.
+- Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
+- Never point one skill at a sibling skill's folder for a reference both read. Each skill carries its own copy under `references/`, generated rather than hand-copied by the rule in `## Path resolution`.
 - Use progressive disclosure: `SKILL.md` for core instructions, `references/` for detail, `scripts/` for deterministic operations
 - Link to `references/` files explicitly so Claude knows to load them