@erclx/aitk 3.42.1 → 3.43.1

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

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

package/claude/skills/claude-autoship/REQUIREMENT.md

@@ -17,7 +17,8 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 - Give every step a stop condition, and leave the code on the branch and the receipts on disk at each one
 - Classify the changed-file list by path as well as by extension, so informational prose skips a code review with no signal on it and executable prose still reaches one
 - Split findings by origin, stopping on a critical or should-fix one the branch inherited and repairing one this run caused
-- Open the pull request as a draft, then watch continuous integration to a terminal state
+- Delegate the ship sequence to `git-ship` rather than restating it, and name only what this chain adds to it
+- Open the pull request as a draft before the continuous integration watch begins, since a pull request marked after it is mergeable for the length of the run
 - Name the recovery for the stop it took, since the value of stopping is that the user knows where to resume
 
 ## Must not
@@ -27,6 +28,8 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 - Fix an inherited review finding or a failing check. Both stops are deliberate, since a green pull request reached by auto-fix hides what broke.
 - Loop on a self-introduced finding. One repair pass, then stop, which is the bound a failed verify already carries.
 - Read the plan's file list as the boundary on a repair. It scopes what the run builds, and a finding this run caused is in reach wherever it landed.
+- Restate the ship sequence. Two copies of one order drift with nothing comparing them, which is what the merge into `git-ship` closed.
+- Skip that skill's own verify for repeating this chain's. The gate exists for the resumed run, and a chain that suppresses it leaves the resumed run reaching nothing.
 - Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
 - Read an empty changed-file list as prose-only. It satisfies that test vacuously and would route the branch past review instead of through it.
 - Read a markdown extension as evidence the change only informs. A skill body, a governance rule, and a standard are behavior written in prose.
@@ -43,4 +46,4 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 
 - Writing the plan, which `claude-feature` owns. This chain starts from one already approved.
 - The behavior of each step, owned by the skill invoked. This skill owns the order and the stop conditions.
-- The resume path after a stop, which `git-ship` owns. That skill is the tail of this same sequence, which is why the two overlap by design.
+- The ship sequence and the resume path after a stop, both of which `git-ship` owns. That skill is the tail of this chain, invoked at Step 7 rather than copied into it, so the overlap is one body reached two ways rather than two bodies stating one order.

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

@@ -134,33 +134,17 @@ Bound the repair at one pass, the way Step 3 bounds verify. When that re-read sh
 
 ## Step 7: ship
 
-Invoke each sub-skill in order via the Skill tool. After each returns, invoke the next immediately. Do not output text between steps.
+Invoke `aitk:git-ship`. That body owns the sequence, being the verify gate, memory capture, both doc syncs, staging, the commit grouping, the branch rename, the pull request, the CI watch, and the scoped memory review, along with the reason each step sits where it does. This step used to restate that list and the two drifted apart with nothing comparing them, so read the order there and never here.
 
-1. `aitk:claude-memory-capture`: route what this session learned to the context entries that own it, and write the residue to `.claude/memory/`
-2. `aitk:claude-docs`: sync `.claude/` planning docs against session decisions, folding in the routed facts
-3. `aitk:docs-sync`: sync public docs against changes since main
-4. Run `git add -A` to stage files the sync skills wrote
-5. `aitk:git-stage`: group staged changes and commit by concern
-6. `aitk:git-branch`: rename the branch to conventional format
-7. `aitk:git-pr`: push and open the pull request
-
-Capture runs first because a routed fact lands in a context entry, which is a tracked file. Running it after `git-pr`, where it used to sit, leaves that edit outside the branch and outside the pull request, so the fact reaches nothing. Memory files stay gitignored either way, which is why the old order was invisible.
-
-After the PR is created, mark it as draft:
+One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch:
 
 ```bash
 gh pr ready --undo
 ```
 
-After marking draft, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status.
-
-On all-pass, continue. On any failure, stop and report the failing check with its URL. Do not auto-fix.
+Placement is the whole point of naming it. Marking after the watch leaves the pull request ready to merge for as long as CI runs, which is the window an unattended worker's branch is least supervised.
 
-8. `aitk:claude-memory-review`: if step 1's capture wrote or updated at least one memory file, propose fixes scoped to those entries, writing the decision-ready receipt while session context is fresh. Skip when capture wrote nothing to the folder, which is the ordinary outcome once routing has taken the domain facts.
-
-Review stays last because its receipt is gitignored and needs nothing from the commit, and because a proposal is worth more once CI has said whether the branch stands.
-
-Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body mutates how the agent operates and ships as its own change, separate from this feature.
+`git-ship` verifies again at its own gate, which repeats this chain's Step 3 on the run where nothing stopped. That cost is deliberate: four of the stop points in the table below hand the run straight back to that body, and a gate the chain skips for being redundant is a gate no resumed run ever meets.
 
 ## Output
 
@@ -176,6 +160,8 @@ Respond with up to five lines:
 
 Omit the second line if there were no minor findings, and the third if nothing routed. Omit the fourth and fifth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal. A run that routes every fact and writes none is the shape to expect, and it reports three lines.
 
+This block replaces the one `git-ship` closes on rather than following it. The two carry the same three trailing lines and differ on the two above them, since the first names the draft state and the second reports the minor findings Step 6 kept, neither of which that body has a counterpart for. Emitting both reports one run twice and buries the draft under a `✅ Shipped` that does not name it.
+
 ## Failure recovery
 
 Every stop point leaves recoverable state. The user resumes manually from the appropriate step.

package/claude/skills/claude-ux-measure/REQUIREMENT.md

@@ -16,6 +16,8 @@ A session that does start one picks a runner on the spot. The reading then comes
 - Detect the harness the project already carries before naming any runner
 - Report a number per metric beside the threshold it is measured against and the published source of that threshold
 - Cover paint, processor, and layout cost, and name what the run left unmeasured
+- Name the elements the layout figure came from, taken off the run that produced the median so the parts sum to the figure beside them
+- Distinguish a layout figure of zero from a harness that reported no attribution, since one is a page that held still and the other is a reading that went missing
 - Report what the measurement needs and stop when no harness is detected, since that is a project without a runner rather than a failure here
 - Take several readings and report the median, since one load carries startup noise wider than the gap between two thresholds
 - Write the reading to the branch-derived path at the main worktree root, overwriting
@@ -28,7 +30,8 @@ A session that does start one picks a runner on the spot. The reading then comes
 - Invent a threshold, or move a published one to fit a reading
 - Report an observation about the source in place of a measurement
 - Suggest a fix for what it measured, which is a change with its own review
-- Measure anything past the three metrics, since every adjacent ask doubles the run
+- Measure anything past the three metrics, since every adjacent ask doubles the run. Naming which elements shifted is not a fourth metric, being the composition of the third and already present in the reading it summarizes.
+- Read the source to improve an element name the harness gave. A better selector bought that way is the source judgment this skill replaces.
 
 ## Guards
 

package/claude/skills/claude-ux-measure/SKILL.md

@@ -54,10 +54,18 @@ Measure these three and nothing else:
 
 - **Paint**: Largest Contentful Paint, the moment the largest element in the viewport finishes rendering
 - **Processor**: Total Blocking Time, main-thread time past 50ms per long task between first paint and interactive
-- **Layout**: Cumulative Layout Shift, the summed score of unexpected shifts over the page lifetime
+- **Layout**: Cumulative Layout Shift, the summed score of unexpected shifts over the page lifetime, reported with the elements that shifted
 
 Through Playwright or an MCP server, read them from a `PerformanceObserver` registered before navigation against the `largest-contentful-paint`, `longtask`, and `layout-shift` entry types. Lighthouse reports all three under its JSON audits, so parse rather than re-derive them.
 
+### Attributing the layout figure
+
+A layout score on its own names nothing to look at, and the elements are already in the reading rather than a second measurement. Each `layout-shift` entry carries a `sources` array naming the nodes that moved, so sum each entry's `value` against the nodes its sources name and keep the three largest. Lighthouse carries the same attribution in the `details.items` of its layout-shift audit, which names elements rather than scores in some versions, so report what that audit gives and do not compute a score it withheld.
+
+Take the attribution from the run that produced the median rather than merging all three, so the parts sum to the figure printed beside them. Merging reports shares of a total no run measured.
+
+Identify each element the way the harness names it, which is a selector from Playwright and a node label from Lighthouse. Do not open the source to improve a name. Reading the tree that produced the page is what this skill exists to replace.
+
 Write any probe the harness needs into the project's own test folder, run it, then delete it. Leave no file behind.
 
 ### Thresholds
@@ -83,12 +91,16 @@ These are Google's published Core Web Vitals boundaries, with the Lighthouse lab
 | TBT    | <n>    | `≤ 200ms` | <verdict>                    |
 | CLS    | <n>    | `≤ 0.1`   | <verdict>                    |
 
+Shifted: `<element>` <n>, `<element>` <n>, `<element>` <n>.
+
 Thresholds: Google Core Web Vitals, Lighthouse lab boundary for TBT.
 
 Not measured: network waterfall, bundle size, accessibility, contrast.
 ```
 
-Report the reading and stop there. A remedy for a poor verdict is a change with its own review, so name no fix and edit no source.
+Write `Shifted: nothing recorded.` when the median run logged no shift, and drop any element past the third. A layout figure of zero and a harness that reported no sources are different states, and the line says which one the run met.
+
+Report the reading and stop there. A remedy for a poor verdict is a change with its own review, so name no fix and edit no source. Naming a shifted element stays inside that rule, since it says where the score came from rather than what to do about it.
 
 ### Persist
 

package/claude/skills/claude-worktree/REQUIREMENT.md

@@ -15,6 +15,8 @@ The tree the entry hands over is also not one the session can run. Dependencies
 
 A declined request also has to land somewhere. The description turns away a list, cleanup, or rotation request and names no destination, so the session that reads it picks one, while the sibling owning those requests already points back here. One half of a pair carrying the pointer reads as the boundary running one way.
 
+A submodule checkout is the state the entry path reads wrong while reporting nothing. The two directory reads that separate a linked worktree from a plain checkout return the same path there, so the guard passes and every derivation after it takes the submodule for the project: the main root, the plan lookup, and the folder entry builds all resolve inside a tree the superproject tracks as a commit.
+
 A stack that derives its ports from the working directory has the same shape. The number is correct and invisible, and `claude-orchestrate` sends a reader here to read it rather than assign one, so the entry that knows the working directory is the surface that owes it.
 
 ## Must
@@ -44,6 +46,7 @@ A stack that derives its ports from the working directory has the same shape. Th
 ## Guards
 
 - Already inside a linked worktree: stop rather than nesting
+- Inside a submodule checkout: stop and name the superproject, since the two reads that catch a linked worktree return the same path here and everything derived afterward would take the submodule for the project
 - Not a git repository and no creation hook configured: stop
 - Target branch already exists: stop before entering and leave it alone, since resolving it automatically risks the wrong branch
 - Target worktree directory already exists: stop before entering, which is the only read that sees two branches differing by type collapsing onto one name

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

@@ -11,6 +11,9 @@ Wrap the `EnterWorktree` entry path with name derivation so the user does not pi
 
 - If `git rev-parse --git-dir` and `git rev-parse --git-common-dir` differ, the session is already inside a linked worktree. Stop: `❌ Already in a worktree. Run ExitWorktree first.`
 - If neither command resolves, the session is not in a git repo and no `WorktreeCreate` hook is configured. Stop: `❌ Not a git repository. EnterWorktree needs git or a WorktreeCreate hook.`
+- If the two match and `git rev-parse --show-superproject-working-tree` prints a path, the session is inside a submodule checkout. Stop: `❌ Inside a submodule of <path>. Run this from there instead.`
+
+The submodule guard sits on the matching branch rather than ahead of the first one, and a measurement decided that. Inside a submodule at git 2.43.0 both reads return the same absorbed path under the superproject's `.git/modules/`, so the first guard does not fire and the session proceeds. Every derivation below then reads the submodule as the project: Step 1 resolves the main root to the submodule, the plan lookup reads a `.claude/plans/` the project never wrote, and entry builds `.claude/worktrees/` inside a tree the superproject tracks as a commit. The superproject read is empty in a linked worktree of a submodule and in one of the superproject alike, which is why it separates the two states rather than qualifying the first guard.
 
 ## Step 1: resolve the main worktree root
 

package/claude/skills/git-ship/REQUIREMENT.md

@@ -9,11 +9,17 @@ description: What the ship chain is for, the gaps it closes, and why it does not
 
 Without this skill, the post-feature sequence runs from memory. Doc sync gets skipped, so the pull request ships with planning docs describing the previous scope, or it runs after staging has already closed and its output never reaches a commit. Chaining by hand is also where a session narrates between steps, which turns one flow into a conversation and invites a decision at every boundary.
 
+The sequence also reaches the remote on work nothing re-checked. This skill is the resume point `claude-autoship` names at four of its stop points, including the one a failed verify takes, so the fix the user makes by hand after that stop is pushed with no suite run against it. Every branch shipped so far passed that verify on its first attempt, which is why the path has produced no instance rather than being closed.
+
 ## Must
 
+- Run the project's verify commands before the sequence starts, and stop on a failure rather than fixing it
+- Say so and continue when the project names no verify command, since silence there reads as a suite that passed
 - Invoke each step through the Skill tool in the stated order and continue without waiting
 - Stage after the sync skills write, so what they produced reaches a commit
 - Emit no text between steps. The sequence is the unit and prose inside it reopens settled decisions.
+- Name the one point a wrapping caller may act at, so a chain built on this one is not left to pick a gap of its own
+- Name the condition under which the closing block is not emitted, since a caller that closes on its own block leaves two instructions about the last line and nothing deciding between them
 - Watch continuous integration to a terminal state, and stop on a failure naming the check
 - Stop memory work at the Propose phase
 
@@ -22,13 +28,15 @@ Without this skill, the post-feature sequence runs from memory. Doc sync gets sk
 - Auto-trigger. Shipping is a decision the user takes, which is what the disabled model invocation encodes.
 - Fix a failing check. The stop is the point, since a green pull request reached by auto-fix hides what broke.
 - Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
-- Implement, verify, or review. This chain starts from work already believed done.
+- Attempt a fix for a failing verify. The user is already making one, which is what brought the run back here.
+- Implement or review. This chain starts from work already believed done.
 
 ## Guards
 
+- A failing verify stops the run before the sync skills write, so the tree is left as the user left it
 - A failing check stops the sequence. This is the one place text is allowed between steps.
 
 ## Out of scope
 
-- Implementation, verification, and review, which `claude-autoship` chains ahead of this same sequence. That skill is the full pipeline and this one is the resume point after a stop, which is why the two overlap by design.
+- Implementation and review, which `claude-autoship` chains ahead of this same sequence. That skill is the full pipeline and this one is the resume point after a stop, which is why the two overlap by design. Verification is the one of the three that belongs on both, since a resume point that trusts the caller's verify trusts a run that stopped.
 - The behavior of each step, owned by the skill invoked. This skill owns the order and nothing else.

package/claude/skills/git-ship/SKILL.md

@@ -8,7 +8,15 @@ disable-model-invocation: true
 
 Run the full post-feature workflow by invoking each skill in sequence using the Skill tool. After each skill returns, invoke the next step immediately in the same response.
 
-Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`.
+Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`, unless a wrapping caller states it closes on its own block, which `claude-autoship` does.
+
+## Verify
+
+Run the verify commands `CLAUDE.md` names (lint, typecheck, tests) before the sequence starts. On a failure, stop: `❌ Verify failed. Fix the reported errors and run /git-ship again.` Make no fix attempt. This skill is the resume point after a stop, so the fix is the one the user is already making.
+
+When `CLAUDE.md` names no verify command, say so on one line and continue. A project with no suite is not a project with a failing one.
+
+Verify runs ahead of the sync skills so a stop leaves the tree exactly as the user left it. Re-running a suite the caller already ran costs one command, and the path it closes is the one that has no other guard: `claude-autoship` verifies at its own Step 3 and then hands four of its stop points straight back here, so a fix made by hand after one of those stops otherwise reaches the remote with nothing re-run.
 
 ## Pre-check
 
@@ -26,6 +34,8 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 8. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
 9. If step 1 wrote or updated at least one memory file, invoke `aitk:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If the pen got nothing, skip this step.
 
+A caller wrapping this sequence may act between step 7 and step 8, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `claude-autoship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.
+
 Capture leads the sequence because a routed fact lands in a context entry, which is a tracked file. Running it after the pull request opens leaves that edit off the branch entirely, so the fact reaches nothing. Memory files are gitignored either way, which is what hid the ordering while capture wrote only those.
 
 Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body ships as its own change, separate from this feature.
@@ -42,3 +52,5 @@ Output up to four lines:
 ```
 
 Omit the second line if nothing routed. Omit the third and fourth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal.
+
+Emit nothing here when a wrapping caller states it closes on its own block. `claude-autoship` is that caller and its block carries these same three trailing lines above a first line naming the draft state, so emitting both reports one run twice. A caller that states no such thing gets this block, which is every direct invocation.

package/docs/ai-workflow.md

@@ -63,7 +63,7 @@ Start a fresh Claude Code session. The diff is sufficient context for both revie
 
 - Invoke `aitk:claude-review` to review all changes since main and output a findings report
 - Fix any valid findings
-- Invoke `aitk:git-ship` to sync docs, commit by concern, rename branch, and open PR
+- Invoke `aitk:git-ship` to run the project's verify commands, sync docs, commit by concern, rename branch, and open PR
 
 ### Parallel features
 
@@ -146,7 +146,7 @@ An empty changed-file list stops the chain rather than counting as prose-only. T
 
 #### Memory in the chain
 
-Both `autoship` and `git-ship` open with `claude-memory-capture`, which sends what the session learned to the surface that owns it. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.claude/memory/`.
+`git-ship` runs its verify gate and then opens on `claude-memory-capture`, which sends what the session learned to the surface that owns it. `autoship` reaches the same step by invoking that skill at its Step 7 rather than restating the order. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.claude/memory/`.
 
 Capture leads rather than trails because a routed fact edits a tracked file, which has to reach the branch before the commit steps run.
 
@@ -226,17 +226,17 @@ This section is the corpus the coverage claim is measured against: every name `a
 
 ### Ship it
 
-| Skill                        | When to use                                                                        |
-| ---------------------------- | ---------------------------------------------------------------------------------- |
-| `aitk:git-ship`              | To run the whole post-feature chain from docs sync through open PR                 |
-| `aitk:claude-memory-capture` | First in that chain, to route what the session learned to the surface owning it    |
-| `aitk:claude-docs`           | When decisions diverged from the plan, or a shipped task needs its outcomes marked |
-| `aitk:docs-sync`             | When a change since main left `README.md` or `docs/` stale                         |
-| `aitk:git-stage`             | When the staged set spans several concerns and wants one commit each               |
-| `aitk:git-commit`            | When the staged set is one concern, or was staged hunk by hand                     |
-| `aitk:git-branch`            | When a branch name needs generating or renaming to conventional form               |
-| `aitk:git-pr`                | When a pull request needs a title and body written from the diff                   |
-| `aitk:claude-memory-review`  | After capture writes an entry, to propose where each one belongs                   |
+| Skill                        | When to use                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `aitk:git-ship`              | To run the whole post-feature chain from the verify gate through open PR              |
+| `aitk:claude-memory-capture` | First skill in that chain, to route what the session learned to the surface owning it |
+| `aitk:claude-docs`           | When decisions diverged from the plan, or a shipped task needs its outcomes marked    |
+| `aitk:docs-sync`             | When a change since main left `README.md` or `docs/` stale                            |
+| `aitk:git-stage`             | When the staged set spans several concerns and wants one commit each                  |
+| `aitk:git-commit`            | When the staged set is one concern, or was staged hunk by hand                        |
+| `aitk:git-branch`            | When a branch name needs generating or renaming to conventional form                  |
+| `aitk:git-pr`                | When a pull request needs a title and body written from the diff                      |
+| `aitk:claude-memory-review`  | After capture writes an entry, to propose where each one belongs                      |
 
 ### After the pull request opens
 

package/package.json

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