@erclx/aitk 0.46.1 → 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.46.1",
+  "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/claude-tasks/SKILL.md

@@ -36,7 +36,7 @@ Do not derive the label from a version file. `.claude/standards/versioning.md` p
 
 Write `.claude/tasks/vXX.Y-<slug>.md` following the format in `.claude/standards/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
 
-Write `Plan:` and `Groundwork:` as markdown links relative to `.claude/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`. Leave `Issue:` a bare `#NNN`. A task written in the older bare-path form still parses, so it costs the board a clickable line rather than an archive, but it leaves the board in two shapes for every reader after.
+Write `Plan:`, `Groundwork:`, and `Intake:` as markdown links relative to `.claude/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`. Leave `Issue:` a bare `#NNN`. A task written in the older bare-path form still parses, so it costs the board a clickable line rather than an archive, but it leaves the board in two shapes for every reader after.
 
 Never write a `Pull request:` line here. `git-pr` adds it when a pull request opens, and a number guessed at create time points at someone else's work.
 

package/claude/skills/create-snippet/references/snippets.md

@@ -8,7 +8,7 @@ consumers: create-snippet
 
 ## Scope
 
-Governs a snippet file: what one is for, how it is invoked, and the structure of its body.
+Governs a snippet file: what one is for, whether a prompt qualifies as one, how it is invoked, and the structure of its body.
 
 Does not govern:
 
@@ -19,6 +19,17 @@ Does not govern:
 
 A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.
 
+## Admission
+
+Two tests decide whether a prompt becomes a snippet, and both have to pass. Apply them when adding one and when auditing the catalog.
+
+- Cadence: a prompt invoked many times across sessions qualifies. A one-shot audit, migration, or bootstrap prompt does not, and belongs in notes outside the catalog.
+- Audience: a prompt the consuming project would invoke ships in `snippets/`. One only the authoring repository can run stays outside every installable folder, which is a rule for a repository that authors snippets for others rather than for one that only consumes them.
+
+A subfolder under `snippets/` names where a prompt is invoked rather than what it is about. A prompt that reads or writes the project's own files goes in a folder, and one carrying its whole context in the message goes at the root.
+
+Overlapping a skill that does the same job is not disqualifying on its own. A snippet fires when a person asks for it by name and a skill fires on a description match, so the two coexist when those paths differ and the outputs do. Record the reason where the project keeps its decisions, or drop the snippet.
+
 ## Invocation channels
 
 - Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline

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/claude/skills/git-pr/SKILL.md

@@ -109,7 +109,7 @@ Write the `number` the final command printed onto the task the branch is closing
 
 Find the task by reading `.claude/tasks/` at the main worktree root, resolved with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The board is shared scratch, so a linked worktree writing to its own `pwd` creates a second board nothing reads.
 
-Confirm the match against the task's `Plan:` line, which names the plan this branch implemented. A branch name does not derive a plan slug and a plan slug does not derive a branch, so neither one alone identifies the task. Add `Pull request: #NNN` under the existing `Plan:`, `Groundwork:`, or `Issue:` lines when the task carries no such line, and correct the number in place when it does.
+Confirm the match against the task's `Plan:` line, which names the plan this branch implemented. A branch name does not derive a plan slug and a plan slug does not derive a branch, so neither one alone identifies the task. Add `Pull request: #NNN` under the existing `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines when the task carries no such line, and correct the number in place when it does.
 
 Skip this silently in three cases: no `.claude/tasks/` folder, no task whose `Plan:` line matches, or more than one match. One task, one pull request, so a second match is a misfile that a guessed write would compound. A wrong match archives the wrong task unattended once the branch merges.
 

package/docs/ai-workflow.md

@@ -88,7 +88,7 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every row and task file map one to one, no task sits in two groups, and no two rows marked ready touch the same file. That last check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made.
 
-`aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/.tmp/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, or an issue, since a task with no origin is either lost context or work nobody decided to do. Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses to run while the `Plan:` line still points into `.claude/plans/`. The sweep only reaches tasks still in the live folder, and archiving the task first would strand the plan there with nothing citing it.
+`aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/.tmp/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do. Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses to run while the `Plan:` line still points into `.claude/plans/`. The sweep only reaches tasks still in the live folder, and archiving the task first would strand the plan there with nothing citing it.
 
 Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `aitk:claude-autoship` or `aitk:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.
 
@@ -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.46.1",
+  "version": "0.48.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/install-check.sh

@@ -75,7 +75,11 @@ log_step "Assert scaffold"
 # no assertion can truncate silently: init still exits 0 because run_domain
 # catches a failed domain, and the gate stays green while the target is
 # missing everything that domain provides.
-for path in "CLAUDE.md" ".claude/snippets/compact-summary.md" ".claude/standards/prose.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
+#
+# The snippets path has to name a slug the default preset still carries, since
+# init resolves snippets through `essentials`. Editing that preset without
+# editing this line fails the gate on a correct install.
+for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/standards/prose.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/snippets/align.md

@@ -0,0 +1,12 @@
+Check alignment before acting, not after. State three lines, then proceed.
+
+- Outcome: what will be true when this is done
+- Scope: what this deliberately does not touch
+- Assumption: the one inference that would change the work if it is wrong
+
+Act without waiting, unless being wrong about the assumption wastes the work rather than costing an edit.
+
+- Three lines, not three paragraphs
+- Name the inference you are least sure of, not the safest one
+- Do not ask what the request already answers
+- Silence is agreement

package/snippets/snippets.toml

@@ -1,6 +1,12 @@
 [essentials]
 names = [
+    "align",
     "decision-help",
-    "compact-summary",
-    "step-by-step",
+]
+
+[orchestrator]
+names = [
+    "claude/orchestrator-handoff",
+    "claude/orchestrator-resume",
+    "claude/orchestrator-sweep",
 ]

package/standards/bundled/snippets.md

@@ -8,7 +8,7 @@ consumers: create-snippet
 
 ## Scope
 
-Governs a snippet file: what one is for, how it is invoked, and the structure of its body.
+Governs a snippet file: what one is for, whether a prompt qualifies as one, how it is invoked, and the structure of its body.
 
 Does not govern:
 
@@ -19,6 +19,17 @@ Does not govern:
 
 A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.
 
+## Admission
+
+Two tests decide whether a prompt becomes a snippet, and both have to pass. Apply them when adding one and when auditing the catalog.
+
+- Cadence: a prompt invoked many times across sessions qualifies. A one-shot audit, migration, or bootstrap prompt does not, and belongs in notes outside the catalog.
+- Audience: a prompt the consuming project would invoke ships in `snippets/`. One only the authoring repository can run stays outside every installable folder, which is a rule for a repository that authors snippets for others rather than for one that only consumes them.
+
+A subfolder under `snippets/` names where a prompt is invoked rather than what it is about. A prompt that reads or writes the project's own files goes in a folder, and one carrying its whole context in the message goes at the root.
+
+Overlapping a skill that does the same job is not disqualifying on its own. A snippet fires when a person asks for it by name and a skill fires on a description match, so the two coexist when those paths differ and the outputs do. Record the reason where the project keeps its decisions, or drop the snippet.
+
 ## Invocation channels
 
 - Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline

package/standards/tasks.md

@@ -125,6 +125,7 @@ description: One line on what this task achieves
 
 Plan: [feature-<slug>](../plans/feature-<slug>.md)
 Groundwork: [<slug>](../.tmp/groundwork/<slug>/)
+Intake: [<slug>](../intake/<slug>/)
 Issue: #NNN
 Pull request: #NNN
 
@@ -144,11 +145,11 @@ Why this task exists and what it depends on.
 
 ## Origin
 
-Every task names where it came from, through a `Plan:`, `Groundwork:`, or `Issue:` line under the title. Include each only when the file, folder, or issue it names exists.
+Every task names where it came from, through a `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` line under the title. Include each only when the file, folder, or issue it names exists.
 
-A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track or an open issue that no task points at is work already decided and on its way to being forgotten.
+A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track or an open issue that no task points at is work already decided and on its way to being forgotten. An intake folder is exempt from that direction, since it dispositions many items at once and most of them close without ever becoming a task.
 
-`Plan:` and `Groundwork:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.claude/tasks/`, which makes it `../plans/` and `../.tmp/groundwork/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
+`Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.claude/tasks/`, which makes it `../plans/`, `../.tmp/groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
 
 Phase-label format and where labels may appear are governed by `standards/versioning.md`.
 
@@ -156,6 +157,8 @@ Phase-label format and where labels may appear are governed by `standards/versio
 
 `Groundwork:` points at `../.tmp/groundwork/<slug>/`, the folder `claude-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
 
+`Intake:` points at `../intake/<slug>/`, the folder an intake pass fills. Use it rather than `Groundwork:`, because a groundwork track measures one question in depth while an intake dispositions many across a tree, and one key covering both loses which kind of pass produced the task. The line names the folder rather than an item inside it. A task routinely promotes several items at once, so an anchored line would name one and drop the rest, and the item numbers belong in that task's `## Findings`.
+
 `Pull request:` records which pull request carries the task's work, as a bare `#NNN` the way `Issue:` does. It is not an origin, so a task without one is well-formed. `git-pr` writes it when a pull request opens, which is the one step that always runs whether the chain drives it or a person does.
 
 The line is what lets a merge close its own task. Every merge on `main` is a squash carrying the number in its subject, so the number survives where a branch name does not, and `aitk tasks archive --pull-request <n>` resolves the task from it. Without the line the board can only be swept blind, and a blind sweep cannot tell a shipped task from an abandoned one. One task, one pull request: two tasks naming the same number refuse to archive rather than both moving.

package/tooling/claude/manifest.toml

@@ -8,4 +8,4 @@ runtime = ""
 scaffold = ""
 
 [gitignore]
-"# Claude" = [".claude/.tmp/", ".claude/memory/", ".claude/plans/", ".claude/review/", ".claude/worktrees/", ".claude/tasks/"]
+"# Claude" = [".claude/.tmp/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/review/", ".claude/worktrees/", ".claude/tasks/"]

package/tooling/claude/reference.md

@@ -49,7 +49,7 @@ A project installed before the diagram surface became a folder still holds `.cla
 
 ## Gitignore
 
-- `# Claude`: `.claude/.tmp/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`
+- `# Claude`: `.claude/.tmp/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`
 
 ## CLI
 

package/snippets/create-snippet.md

@@ -1,7 +0,0 @@
-Draft a new snippet following these conventions:
-
-- Filename is the slug: kebab-case, no capitals, no underscores
-- Plain markdown only, no YAML frontmatter, no headers or nested structure
-- One focused purpose, self-contained with no external file references
-
-Output the slug and the full file content.