@erclx/aitk 0.61.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.61.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/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.61.0",
+  "version": "0.62.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

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