@erclx/aitk 0.47.0 → 0.48.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.47.0",
+  "version": "0.48.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -9,14 +9,21 @@ description: What the review return leg is for, the gaps it closes, and why the
 
 Without this skill, review findings are worked in whatever order the author read them and the thread never records which landed. A reply posted before the push describes code the remote does not have, so a reviewer checks the branch and finds the old version. A failing check gets treated as separate from the review, which produces a follow-up that answers every comment and leaves continuous integration red. One finding nobody can resolve stalls the rest.
 
+A branch also goes stale from `main` moving rather than from anything the branch did. Nothing in the return leg rebases it, so the worker closes every finding, reports the pull request answered, and the branch still cannot merge. Half the resolution is mechanical and wrong to do by hand, since a generated file merged manually produces a diff the next regen discards.
+
 ## Must
 
 - Treat a failing check as a finding alongside the review comments, so the follow-up closes both
 - Handle each finding independently, so one unresolved item does not block the others
 - Verify before pushing, since a red follow-up costs the reviewer a second pass
+- Rebase onto `origin/main` when the branch no longer merges, after the findings are addressed and before the push, so one force-push carries both
+- Test staleness on every invocation, including one carrying no findings, since a branch goes stale from `main` moving rather than from anything the review said
+- Re-test once the fixes are commits, since the first test reads committed history and cannot see a fix that touches lines `main` moved
+- Rebuild a generated file through the project check rather than resolving its conflict by hand
 - Push before replying, so the comment never runs ahead of the code it describes
 - Map every finding to what changed, or to a one-line reason when it is a question or a conscious accept
 - Post the terminal comment only when the findings are addressed and every check passes
+- Say what the run actually did on a rebase-only pass, since a reply mapping findings and a terminal comment claiming they were addressed are both false on a pull request carrying none
 - Scan the reply for banned characters and internal phase labels before posting, since the comment leaves for the remote unchecked
 
 ## Must not
@@ -26,11 +33,15 @@ Without this skill, review findings are worked in whatever order the author read
 - Post the closing comment while a check is failing
 - Reimplement the follow-up push or the doc refresh. Both have owners, and a second copy here drifts from them.
 - Edit silently. A finding answered without a reply leaves the reviewer re-deriving the change from the diff.
+- Take one side of a conflict wholesale. Both sides are valid content, so `--ours` or `--theirs` drops one silently and passes every check.
+- Merge `main` into the branch. The repository squash-merges, so a merge commit reads as noise on the pull request.
+- Guess at a hunk the tree does not settle. That case reaches the operator as an ordinary finding on the next pass only if the worker stops.
 
 ## Guards
 
 - No open pull request for the current branch: stop
-- The pull request carries no review comments or threads: stop with a pass
+- The pull request carries no review comments or threads and the branch still merges: stop with a pass. A closed review says nothing about whether the branch still merges, so the staleness test decides this one rather than the finding count.
+- A conflict needing a decision the tree does not carry: stop with the branch left on its old base
 
 ## Out of scope
 
@@ -38,3 +49,4 @@ Without this skill, review findings are worked in whatever order the author read
 - Staging, committing, and pushing the follow-up, which `git-followup` owns under this skill's direction
 - Refreshing the `.claude/` docs the fixes made stale, which `claude-docs` owns
 - Re-reviewing its own fixes, which hands back to the orchestrator
+- Re-reading a rewritten branch, which `claude-pr-review` absorbs by testing whether the prior reviewed commit still reaches the head and paying for a full pass when it does not

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

@@ -11,7 +11,7 @@ the PR from an independent session. This skill consumes them: fix, reply, push.
 ## Guards
 
 - If no open PR resolves for the current branch via `gh pr view`, stop: `❌ No open PR. Nothing to address.`
-- If the PR has no review comments or threads, stop: `✅ No review findings to address.`
+- If the PR has no review comments or threads, run step 5's staleness test before deciding. A branch that still merges stops here: `✅ No review findings to address.` One that does not skips steps 1 through 4 and runs step 5 onward, since a branch goes stale from `main` moving and a closed review says nothing about whether it still merges.
 - Fix findings. Do not merge.
 
 ## Step 1: pull the review findings and CI status
@@ -48,7 +48,57 @@ Do not push a red follow-up.
 
 The fixes may have changed or added behavior that `.claude/` context entries, docs, or wireframes describe. Refresh them with the `claude-docs` skill, which maps the changed files to the entries that reference them and rewrites the stale sections. Do not reimplement that mapping here. When a fix adds a new capability with no existing entry, `claude-docs` flags it rather than creating one.
 
-## Step 5: push, then reply
+## Step 5: rebase a stale branch
+
+A branch goes stale from `main` moving rather than from anything the branch did,
+so the test runs on every invocation, including the one the second guard sends
+straight here with no findings to fix. Fetch first. A stale local `origin/main`
+reports no conflict on a branch that has one.
+
+```bash
+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.
+
+`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,
+whose fixes touch lines `main` moved, passes here and reaches the remote
+unmergeable. Step 6 re-runs the test once those fixes are commits.
+
+## Step 6: push, then reply
 
 Push the fixes before posting the reply so the comment never runs ahead of the
 code it describes. Ship the fixes as a follow-up commit on the same branch with
@@ -56,7 +106,21 @@ the `git-followup` skill, invoked with `reply-owned` so it stages, commits,
 pushes, and refreshes the open PR body without posting its own comment. This
 skill owns the reply. Do not reimplement that flow here. For in-place fixes to
 files the PR body already covers, `git-followup` leaves the body untouched and
-the reply comment carries the fix log.
+the reply comment carries the fix log. A rebase in step 5 rewrote the branch, so
+that push is a force-push and `git-followup` resolves it from the tracking
+branch. Worker branches are single-owner here, which is what makes overwriting
+the remote safe.
+
+`git-followup` stops on an unchanged tree. A run that answered every finding as a
+conscious-accept and whose rebase left the generated files alone has nothing for
+it to commit, so the rebase would never reach the remote. Push that case directly
+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
+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`
 mapping each finding to what changed, or to a one-line reason when it is a
@@ -72,6 +136,18 @@ review itself carries. Follow it with a one-line summary sentence, then one
 bullet per finding, each opening with the bolded finding identifier.
 Close the body with `🤖 Addressed by Claude Code` on its own line so the reply
 reads as an independent machine pass, not a human sign-off.
+When step 5 rebased the branch, say so in the summary sentence and name which
+files were resolved by hand and which the regen rebuilt. The next review is a
+full pass rather than a delta, and the reader is owed the reason.
+
+A run the second guard sent straight to step 5 has no findings to map, so it
+takes a different body rather than an empty list. Open it with `## Rebase`, not
+`## Review response`, since nothing on the pull request is being responded to and
+that heading claims a review this run never read. State that the branch stopped
+merging, name what landed on `main`, name the files resolved by hand and those
+the regen rebuilt, and close the same way. The heading stays outside the
+`## Review` family so the close-out's equality test on the first line never
+matches it.
 
 Before posting, run the scan in `.claude/standards/publish.md`
 against the reply, or `${CLAUDE_SKILL_DIR}/../../standards/publish.md` when
@@ -82,7 +158,7 @@ only gate on the published reply. Post it to the PR:
 gh pr comment <number> --body-file .claude/.tmp/address-review/reply-<number>.md
 ```
 
-## Step 6: confirm resolution
+## Step 7: confirm resolution
 
 After the follow-up push, watch CI on the PR. Poll `gh pr checks <number>`
 until no check is pending, then read the final status. When every finding is
@@ -93,15 +169,33 @@ clear terminal state:
 gh pr comment <number> --body "✅ All review findings addressed, CI green."
 ```
 
+A rebase-only run addressed no finding, so it takes its own terminal comment
+rather than that one. Claiming findings were addressed on a pull request that
+carries none is false on a surface nothing else checks:
+
+```bash
+gh pr comment <number> --body "✅ Rebased onto origin/main, CI green. No review findings were open."
+```
+
 If any check fails, do not post the closing comment. Report the failing check
 so it can be fixed first. This is a resolution signal, not a formal approval,
 since the PR author cannot approve their own PR.
 
-## Step 7: output
+## Step 8: output
 
 ```plaintext
 Addressed <N> findings on PR #<number>. Follow-up pushed.
+<Rebased onto origin/main. <N> files resolved by hand, <N> rebuilt by the check.>
+```
+
+Omit the second line when the branch still merged. Name any finding left as a
+reply rather than a code change, with its one-line reason.
+
+A rebase-only run drops the first line rather than reporting zero findings
+addressed, and leads with the rebase instead:
+
+```plaintext
+Rebased PR #<number> onto origin/main. <N> files resolved by hand, <N> rebuilt by the check.
 ```
 
-Name any finding left as a reply rather than a code change, with its one-line
-reason. Do not merge. Hand back to the orchestrator for re-review.
+Do not merge. Hand back to the orchestrator for re-review.

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

@@ -7,7 +7,7 @@ description: What the follow-up push is for, the gaps it closes, and how it spli
 
 ## Gap
 
-Without this skill, an edit made after a pull request is already open ships as a bare push. The body still describes the scope from before the edit, so a reviewer returning to the page reads a description the diff no longer matches. A reviewer who left comments gets no reply, and when a caller has already posted its own reply, a second one lands underneath it.
+Without this skill, an edit made after a pull request is already open ships as a bare push. The body still describes the scope from before the edit, so a reviewer returning to the page reads a description the diff no longer matches. A reviewer who left comments gets no reply, and when a caller has already posted its own reply, a second one lands underneath it. A caller that rebased the branch before handing over hits a rejected push, since the tracking branch no longer reaches the head.
 
 ## Must
 
@@ -16,6 +16,7 @@ Without this skill, an edit made after a pull request is already open ships as a
 - Sync the body when the new commit moves the scope, and the title when the shift makes it inaccurate
 - Reply on the pull request when it carries review comments, and scan that reply for the banned characters and internal phase labels before posting. The hook watches files and never sees a comment body on its way to the remote.
 - Suppress the reply when the caller owns it, and still run the push and the body sync
+- Force the push under a lease when the tracking branch no longer reaches the head, so a caller's rebase lands and a commit this session never read is not overwritten
 
 ## Must not
 

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

@@ -22,7 +22,7 @@ its own reply, so skip the comment in step 6. The push and body sync still run.
 1. Run `git status` to confirm the changes are intentional
 2. Run `git add -A` to stage every change
 3. Invoke `aitk:git-commit` to generate one conventional commit from the staged diff
-4. Run `git push` to the tracking branch
+4. Run `git push` to the tracking branch. When `git merge-base --is-ancestor @{u} HEAD` exits non-zero, a caller rewrote the branch and a plain push is rejected, so push with `--force-with-lease` instead. The lease is what stops the force from overwriting a commit this session never read.
 5. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
 6. When invoked with `reply-owned`, skip this step's comment: the caller posts the reply. Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first running the scan in `.claude/standards/publish.md` against it, or `${CLAUDE_SKILL_DIR}/../../standards/publish.md` when the project does not have it, since the hook does not see an inline comment body. If it is zero, run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
 

package/docs/ai-workflow.md

@@ -139,7 +139,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 | `aitk:claude-design-extract` | Draft `.claude/DESIGN.md`, sourcing tokens from existing UI code or proposing them from requirements on day one      |
 | `aitk:claude-review`         | In a fresh session, review all changes since main                                                                    |
 | `aitk:claude-pr-review`      | Review an open PR from an independent session, then re-review the commits added since until nothing is open          |
-| `aitk:claude-address-review` | Address PR findings and CI status, refresh stale docs, then push a follow-up                                         |
+| `aitk:claude-address-review` | Address PR findings and CI status, refresh stale docs, rebase a branch that stopped merging, then push a follow-up   |
 | `aitk:claude-tasks`          | Add a task to `.claude/tasks/` or archive a shipped one out of the folder                                            |
 | `aitk:claude-docs`           | When decisions diverged from plan, update `.claude/` docs                                                            |
 | `aitk:claude-ui-test`        | After UI changes, generate and run e2e tests + visual checklist                                                      |

package/docs/operating-model.md

@@ -33,9 +33,9 @@ One feature travels this path end to end.
 2. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
 3. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The worker builds, self-checks, opens a PR, and stops at the PR boundary.
 4. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
-5. Worker addresses the findings with `claude-address-review`, then pushes a follow-up.
+5. Worker addresses the findings with `claude-address-review`, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up.
 6. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, and posts under `## Review closed` when it finds nothing open or under `## Review` when it does, so a reader learns the state from the heading. Repeat from step 5 until the review closes.
-7. The human reads the result and merges. The orchestrator tells any trailing worker to rebase when its branch shares a seam with the merged one.
+7. The human reads the result and merges. The orchestrator tells any trailing worker whose branch shares a seam with the merged one to run `claude-address-review`, which rebases whether or not the review left anything open.
 
 There is no loop construct here. Each worker is a single build that halts at the
 PR. The merge stays a manual human gate. Reliability comes from the plan being
@@ -61,6 +61,14 @@ the PR. `claude-address-review` reads them back, fixes each, replies or resolves
 the threads, and pushes a follow-up. `claude-pr-review` then runs again, reading
 only what the follow-up added.
 
+A branch that stopped merging while the review was open is the worker's problem
+to close. `claude-address-review` rebases onto `origin/main` between the fixes
+and the push, so one force-push carries both and the reviewer reads one delta.
+The staleness test sits ahead of the no-findings guard, so a branch whose review
+closed clean and then went stale still rebases when the skill is invoked. The
+re-read costs a full pass rather than a delta, since the prior reviewed commit no
+longer reaches the head, and `claude-pr-review` detects that itself.
+
 The heading carries the state rather than the pass number. A pass with a finding
 takes `## Review` and a pass with none takes `## Review closed`, so a thread can
 be scanned for what is still open without opening a comment. The feedback

package/package.json

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