@erclx/aitk 0.66.1 → 0.67.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.66.1",
+  "version": "0.67.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -1,13 +1,13 @@
 ---
 name: claude-worktree
-description: Why worktree entry is wrapped rather than called directly, covering name derivation, the branch rename downstream slugs depend on, and the shared-config repair
+description: Why worktree entry is wrapped rather than called directly, covering name derivation, the conventional branch rename the ship chain depends on, and the shared-config repair
 ---
 
 # Claude worktree requirement
 
 ## Gap
 
-Without this skill, the user names the worktree by hand, and a name matching no plan breaks every slug derived from it afterward. The entry tool then creates the branch as `worktree-<name>`, which diverges from the name the folder carries, so the ship chain looks for a plan file under a slug that does not exist and stops with nothing wrong except the name.
+Without this skill, the user names the worktree by hand, and a name matching no plan breaks every slug derived from it afterward. The entry tool then creates the branch as `worktree-<name>`, which diverges from the name the folder carries, so the ship chain looks for a plan file under a slug that does not exist and stops with nothing wrong except the name. Correcting that to the bare name leaves the branch carrying no type, which `git-pr` refuses on format, so the same run stops a second time with the work already done and uncommitted.
 
 Entry also writes the bare flag into the shared config, which strands the main worktree. Every command run there fails while the files sit untouched on disk, and the linked worktree keeps working, so nothing surfaces until the operator returns to the main checkout and finds the repository broken. A rename onto a branch that already exists is the third failure, and it is the one that destroys work rather than blocking it.
 
@@ -16,7 +16,9 @@ Entry also writes the bare flag into the shared config, which strands the main w
 - Derive the name from the plan matched to the current branch, falling through the ordered sources rather than picking
 - Validate and sanitize the derived name against what the entry tool accepts
 - Preview the resolved name and which source produced it before entering
-- Rename the created branch to match the worktree name, so downstream slug derivation resolves
+- Rename the created branch to a conventional `<type>/<name>`, so the pull request guard accepts it and the slug transform still reads `<name>` back out
+- Take the type from the plan the name came from, and default to `feat` when a branch or the user supplied it
+- Test the target branch and the target directory before entering, so a stop costs no worktree
 - Read the bare flag before writing it, and repair it on both sides of entry
 - Announce the repair only when a write actually happened
 
@@ -24,7 +26,7 @@ Entry also writes the bare flag into the shared config, which strands the main w
 
 - Pick between plans when more than one could match. Ask.
 - Enter on a name inferred from session context without confirmation
-- Delete or overwrite a branch that already carries the target name
+- Delete or overwrite a branch or a worktree directory that already carries the target name
 - Rename when the worktree was entered by path, since that branch already has its own identity
 - Invoke the exit path, which is the user's call
 
@@ -32,7 +34,8 @@ Entry also writes the bare flag into the shared config, which strands the main w
 
 - Already inside a linked worktree: stop rather than nesting
 - Not a git repository and no creation hook configured: stop
-- Target branch already exists: stop and leave it alone, since resolving it automatically risks the wrong branch
+- 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
 
 ## Out of scope
 

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

@@ -43,28 +43,48 @@ Try each source in order. Stop at the first match.
 
 Validate the result: letters, digits, dots, underscores, dashes only, max 64 chars (`/` separators are also allowed). If the derived name violates the rule, sanitize by replacing invalid chars with `-` and truncating. Show the sanitized name in the preview before invoking.
 
+Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a name from the user, and a plan whose lines settle nothing. Draw the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/references/branch.md`.
+
+A wrong type is cheap. `git-branch` renames to conventional format later in the same chain and runs ahead of `git-pr`, so a `feat/` written over a fix is corrected before any pull request opens.
+
+Then test both names the entry is about to claim. Neither read needs a worktree, and a stop after Step 4 leaves one built with the session sitting inside it, so both belong here rather than beside the rename:
+
+- Branch. `git show-ref --verify --quiet refs/heads/<type>/<name>` succeeding means the ref exists. Stop: `❌ Branch <type>/<name> already exists. Resolve manually before continuing.`
+- Directory. `<main-root>/.claude/worktrees/<name>/` existing means an earlier entry claimed the name. Stop: `❌ Worktree .claude/worktrees/<name>/ already exists. Resolve manually before continuing.`
+
+Leave both in place. Resolving either automatically risks the wrong one.
+
+The two tests catch different collisions. The branch test misses the one `.claude/standards/slug.md` records, where two branches differing only in type collapse onto one name: `feat/foo` and `fix/foo` are distinct refs and reach one directory. The directory test is the only read that sees it.
+
+The branch test fires on the tier 1 and tier 4 sources whenever the branch the session started on is already conventional, since a name derived from that branch resolves back onto it. Stopping is the answer there. The concern already has a branch, git refuses a second under the same name, and the bare-name rename this replaces only carried the collision forward to the `git-branch` step.
+
 ## Step 3: preview
 
 Output exactly:
 
 ```plaintext
 Worktree: .claude/worktrees/<name>/
-Source: <plan|branch|user>
+Branch:   <type>/<name>
+Source:   <plan|branch|user>
 ```
 
+Step 2 resolved `<type>`. Show it, since it is the one part of the entry the user cannot read off the name they supplied.
+
 ## Step 4: enter
 
 Call `EnterWorktree` with `name: "<name>"`. Claude Code's tool permission dialog is the confirmation gate. Do not pause for additional confirmation.
 
 ## Step 5: align the branch name and repair the shared config
 
-`EnterWorktree` creates a branch named `worktree-<name>`, which diverges from `<name>` and breaks downstream slug derivation in `claude-autoship` and any skill that reads `git branch --show-current`. Rename it to match:
+`EnterWorktree` creates a branch named `worktree-<name>`, which diverges from `<name>` and breaks downstream slug derivation in `claude-autoship` and any skill that reads `git branch --show-current`. A bare `<name>` fixes that and fails the branch-format guard in `git-pr`, which requires `<type>/<description>`. Rename to the conventional form, which satisfies both:
 
 ```bash
-git branch -m worktree-<name> <name>
+git branch -m worktree-<name> <type>/<name>
 ```
 
-Before renaming, guard against a collision: if `git show-ref --verify --quiet refs/heads/<name>` succeeds, the target branch already exists. Stop: `❌ Branch <name> already exists. Resolve manually before continuing.` Do not delete the existing branch.
+The slug transform drops a leading type segment, so `<name>` is what every downstream derivation reads back out of the typed branch. See `.claude/standards/slug.md`, or `${CLAUDE_SKILL_DIR}/../../standards/slug.md` when the project does not have it.
+
+Step 2 already cleared the target name, so the rename runs unguarded here. Do not repeat the test. A ref created between the two points is a second session racing this one, which a re-read narrows rather than closes.
 
 Skip the rename if the worktree was entered via `path` rather than `name`, since the branch already exists under its own identity.
 

package/claude/skills/claude-worktree/references/branch.md

@@ -0,0 +1,60 @@
+---
+title: Branch reference
+description: Branch naming format and type conventions
+consumers: git-branch, git-split, git-pr, claude-worktree
+---
+
+# Branch reference
+
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving a slug from a branch name for use in an output filename: `slug.md`
+
+## Format
+
+- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
+- Length: 50 characters maximum
+- Casing: kebab-case only, no underscores or camelCase
+- Description: 2 words maximum, 3 only when genuinely needed for specificity
+- Capture the core change, not the commit message verbatim
+- For branches with multiple commits, use the unifying concern as the description.
+- Do not duplicate type in description (e.g., `feat/feature-login`)
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Examples
+
+### Correct
+
+```plaintext
+feat/jwt-expiration                    # clear feature scope
+fix/AUTH-123-connection-pool           # includes ticket ID
+refactor/remove-deprecated-endpoints   # clear refactor intent
+```
+
+### Incorrect
+
+```plaintext
+feature/auth_stuff                                        # wrong type + underscore
+feat/feature-add-login                                    # duplicates type in description
+fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
+```

package/claude/skills/git-branch/references/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr
+consumers: git-branch, git-split, git-pr, claude-worktree
 ---
 
 # Branch reference

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

@@ -7,11 +7,12 @@ 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. A caller that rebased the branch before handing over hits a rejected push, since the tracking branch no longer reaches the head.
+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. A branch entered through a worktree hits the opposite shape, carrying an open pull request with no tracking ref at all, which read as a branch that had never been pushed.
 
 ## Must
 
-- Refuse unless the branch has an upstream and an open pull request, since every later step addresses one of the two
+- Refuse unless the branch has an open pull request, since every later step addresses it
+- Set the tracking ref at the push when the branch has none, since a branch entered through a worktree carries an open pull request without one
 - Delegate the message to `git-commit` rather than composing one, so a follow-up commit reads like every other commit
 - 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.
@@ -29,7 +30,6 @@ Without this skill, an edit made after a pull request is already open ships as a
 
 - On `main`: stop and say to switch to a pull request branch
 - Nothing changed: stop
-- No upstream: stop and name both recoveries
 - No open pull request: stop and route to the skill that opens one
 
 ## Out of scope

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

@@ -14,15 +14,16 @@ its own reply, so skip the comment in step 6. The push and body sync still run.
 
 - If `git branch --show-current` returns `main`, stop: `❌ On main. Switch to a PR branch first.`
 - If `git status --porcelain` is empty, stop: `❌ No changes to ship.`
-- If `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null` is empty, stop: `❌ No upstream. Push the branch first or use git-ship.`
 - If `gh pr view --json state -q '.state' 2>/dev/null` is not `OPEN`, stop: `❌ No open PR for this branch. Use git-ship to open one.`
 
+A missing tracking ref is no longer a guard. An open pull request proves the branch reached the remote, and a branch created by worktree entry has been measured carrying an open pull request with no tracking ref, where the old guard reported that the branch still needed pushing. That message describes a state the branch is not in, so the run stopped on a diagnosis nobody could act on. Step 4 sets the ref instead.
+
 ## Sequence
 
 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. 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.
+4. Push. When `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null` is empty, the branch has an open pull request and no tracking ref, so run `git push -u origin HEAD` to send the commit and set the ref in one step. Otherwise push to the tracking branch with `git push`, and 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. Run the ancestry test only where an upstream resolves, since it reads `@{u}`.
 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/references/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr
+consumers: git-branch, git-split, git-pr, claude-worktree
 ---
 
 # Branch reference

package/claude/skills/git-split/references/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr
+consumers: git-branch, git-split, git-pr, claude-worktree
 ---
 
 # Branch reference

package/docs/agents/install-and-sync.md

@@ -117,6 +117,29 @@ commits touching its own source path. The `covers` field names the domains a
 target has actually stamped, so a domain that was never stamped is legible
 rather than reading as a clean one.
 
+### Tooling
+
+Tooling records the stack chain an install resolved rather than per-file hashes,
+since `src/tooling/` runs its own inject machinery and has no walk to attribute.
+The chain is ordered nearest stack first, which is what a `--skip` run needs:
+recording the leaf alone would send the next report measuring against a layer the
+target deliberately does not carry. The report loads exactly those stacks, scans
+them the way `aitk tooling sync` would, and counts what differs per category
+under `tooling.counts`.
+
+`measured` is the field the section exists for. A target carrying no chain
+reports `measured: false`, which separates tooling nobody has ever looked at from
+tooling that is current. Both produce zero changes otherwise. Every target
+installed before the record shipped starts unmeasured and leaves on its next
+`aitk tooling sync`, since backfilling would mean inferring the chain from
+installed files, which is the guess the record replaces.
+
+A workspace root records nothing, because each package resolves its own chain and
+one written at the root would be that same guess. Run the check against a package
+to measure it. Tooling never counts toward `--exit-code`, on the grounds seeds
+are already excluded on, since it reports golden configs a project is expected to
+edit and a job counting those stays red with no remedy.
+
 ### Surfaces reported beside the domains
 
 Three sections sit outside the per-domain scan, because each names something

package/docs/ai-workflow.md

@@ -65,7 +65,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 
 - Create a worktree per feature, then start a Claude Code session in each
 - Invoke `aitk:claude-feature` in each session. Plans land at the main worktree root as `.claude/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
-- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review-<branch>.md`, `ui-checklist-<branch>.md`), so parallel sessions do not overwrite each other
+- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review-<slug>.md`, `ui-checklist-<slug>.md`), so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `aitk:git-ship`
 - For full autonomy per worktree, invoke `aitk:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
 

package/docs/target-projects.md

@@ -100,7 +100,7 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 `aitk sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next. A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `aitk:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is what `aitk:migration-standards` handles.
 
-That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes recording a hash per installed file. Each domain holds its own toolkit commit, so syncing governance today does not move the revision standards measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
+That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes. Standards, snippets, and governance record a hash per installed file. Tooling records the stack chain it resolved instead, since its install runs no per-file walk to attribute. Each domain holds its own toolkit commit, so syncing governance today does not move the revision standards measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
 
 A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
 
@@ -108,9 +108,9 @@ Three further causes sit outside the per-domain scan, each naming something that
 
 That last one matters most on an older project. Before it existed, a target holding `standards/` at its root reported zero entries for that domain, so a project that had never migrated was indistinguishable from one that was fully current.
 
-Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts or seed drift, since both need the user to move content only they can place. An unmigrated domain does count, because running the relocation closes it.
+Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts, seed drift, or tooling, since each reports content the project is expected to edit or place itself. An unmigrated domain does count, because running the relocation closes it.
 
-Tooling is not covered by the stamp. Reconcile those configs with `aitk tooling <stack> <path>`.
+Tooling reports under a section of its own, and `measured` there says whether the target ever recorded a chain. One that never ran a tooling sync reports unmeasured rather than clean, which is what separates tooling nobody has looked at from tooling that is current. A workspace root records nothing either way, since each package resolves its own chain. Reconcile the configs with `aitk tooling sync <stack> <path>`.
 
 ### Catch-all
 

package/package.json

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

package/src/commands/sync.ts

@@ -3,9 +3,13 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { cliPath, cliRun } from '@/cli-run'
 import { PROJECT_ROOT } from '@/exec'
-import { buildCheckReport, type CheckReport, hasDrift } from '@/sync/check'
+import {
+  buildCheckReport,
+  type CheckReport,
+  hasDrift,
+  SCANNED_DOMAINS,
+} from '@/sync/check'
 import { createGitRunner, createPullRequestOpener, hasGh } from '@/sync/git'
-import { STAMP_DOMAINS } from '@/sync/stamp'
 import {
   detectDomains,
   installedDomains,
@@ -133,6 +137,8 @@ function renderCheck(report: CheckReport): void {
     }
   }
 
+  renderTooling(report)
+
   for (const entry of report.unmigrated) {
     logStep(`${entry.domain} (not migrated)`)
     logWarn(
@@ -157,17 +163,56 @@ function renderCheck(report: CheckReport): void {
   }
 
   outro()
+  // Scanned domains only. Tooling renders a section on every managed target, so
+  // naming it here repeats what that section already said under a second
+  // remedy, where a scanned domain nobody installed has no section at all and
+  // this line is the only place it appears.
   const unmigrated = report.unmigrated.map((entry) => entry.domain)
-  const uncovered = STAMP_DOMAINS.filter(
+  const uncovered = SCANNED_DOMAINS.filter(
     (domain) => !report.covers.includes(domain) && !unmigrated.includes(domain),
   )
-  const unstamped =
-    uncovered.length === 0 ? '' : `Unstamped: ${uncovered.join(', ')}. `
+  if (uncovered.length === 0) return
+
   process.stderr.write(
-    `${GREY}${unstamped}Tooling is never stamped, run \`aitk tooling\` to reconcile configs.${NC}\n`,
+    `${GREY}Unstamped: ${uncovered.join(', ')}. Run the matching sync to record one.${NC}\n`,
   )
 }
 
+/**
+ * Tooling prints whether it was measured before it prints any count, because a
+ * target with no chain recorded produces the same zero a current target does.
+ * Naming the state is the whole reason the section exists.
+ */
+function renderTooling(report: CheckReport): void {
+  const { tooling } = report
+  logStep('tooling')
+
+  if (!tooling.measured) {
+    logWarn(
+      tooling.chain.length === 0
+        ? 'Not stamped. No chain recorded, so tooling drift is unmeasured.'
+        : `Recorded chain names no stack this toolkit ships: ${tooling.chain.join(' < ')}.`,
+    )
+    logInfo('Run `aitk tooling sync <stack>` to record what this target holds.')
+    return
+  }
+
+  logInfo(`Chain: ${tooling.chain.join(' < ')}`)
+  if (tooling.commit !== undefined) {
+    logInfo(`Synced from ${tooling.commit} on ${tooling.syncedAt}`)
+  }
+
+  if (tooling.changes === 0) {
+    logInfo('up to date')
+    return
+  }
+
+  for (const [category, count] of Object.entries(tooling.counts)) {
+    if (count > 0) logWarn(`${count} ${category}`)
+  }
+  logInfo('Run `aitk tooling sync` to reconcile these.')
+}
+
 /**
  * Seeds print their own section because no sync command applies them. A `stale`
  * seed is safe to take whole and a `drifted` one holds edits, which is the split

package/src/commands/tooling.ts

@@ -18,6 +18,7 @@ import {
   stackExists,
 } from '@/tooling/manifest'
 import { scan, type ScanResult } from '@/tooling/scan'
+import { recordToolingChain } from '@/tooling/stamp'
 import { intro, logAdd, logInfo, logStep, logWarn, outro, select } from '@/ui'
 
 const GREEN = '\x1b[0;32m'
@@ -219,6 +220,7 @@ async function runSync(
   report(result, includeReferences)
 
   if (result.totalChanges === 0) {
+    await stampChain(prepared.chain, prepared.target)
     outro()
     process.stderr.write(`${GREEN}✓ Everything up to date${NC}\n`)
     return 0
@@ -255,11 +257,35 @@ async function runSync(
     await applyReferences(prepared.chain, prepared.target, pending)
   }
 
+  await stampChain(prepared.chain, prepared.target)
+
   outro()
   process.stderr.write(`${GREEN}✓ Tooling sync complete${NC}\n`)
   return 0
 }
 
+/**
+ * Writes the chain after the copies land, so a partial apply that throws leaves
+ * the previous record rather than a claim the target does not meet.
+ */
+async function stampChain(chain: Manifest[], target: string): Promise<void> {
+  const recorded = await recordToolingChain(
+    PROJECT_ROOT,
+    target,
+    chain,
+    new Date(),
+  )
+
+  if (recorded) {
+    logInfo(`Recorded chain: ${chain.map((entry) => entry.name).join(' < ')}`)
+    return
+  }
+
+  logWarn(
+    'Workspace root: no chain recorded. Tooling reports unmeasured because the answer differs per package.',
+  )
+}
+
 async function runInject(
   stack: string,
   target: string,
@@ -290,6 +316,15 @@ async function runInject(
     await injectGitignore(prepared.chain, prepared.target)
   }
 
+  // Only a whole-stack inject records the chain. A flag-scoped run installs one
+  // category, and a chain recorded from it would send the report scanning for
+  // configs and deps the caller never asked to install. The claude stack is
+  // excluded here rather than in `prepare`, which is what keeps `aitk claude`
+  // able to drive injection while its stack stays out of the tooling record.
+  if (applyAll && !isStackExcluded(stack)) {
+    await stampChain(prepared.chain, prepared.target)
+  }
+
   if (framed) outro()
   return 0
 }

package/src/sync/check.ts

@@ -13,32 +13,47 @@ import {
 import { buildSeedsReport, type SeedsReport } from '@/sync/seeds-report'
 import {
   readStamp,
-  STAMP_DOMAINS,
   type Stamp,
+  stampedChain,
   stampedCommit,
   type StampDomain,
 } from '@/sync/stamp'
 import { createStandardsAdapter } from '@/standards/adapter'
 import { isDirectory } from '@/target'
+import { loadManifest } from '@/tooling/manifest'
+import { scan } from '@/tooling/scan'
+
+/**
+ * Domains the sync engine walks file by file. Tooling is a stamp domain without
+ * being one of these, because `src/tooling/` never calls `planSync`, so the
+ * three lookups below have no entry to offer it.
+ */
+export const SCANNED_DOMAINS = [
+  'standards',
+  'snippets',
+  'governance',
+] as const satisfies readonly StampDomain[]
+
+export type ScannedDomain = (typeof SCANNED_DOMAINS)[number]
 
 /**
  * The toolkit path whose commits change what each domain holds. `claude/skills/`
  * is deliberately absent: skills load live from the plugin directory, so they
  * never go stale and belong in the read-only section instead.
  */
-const SYNCED_SOURCES: Record<StampDomain, string> = {
+const SYNCED_SOURCES: Record<ScannedDomain, string> = {
   standards: 'standards/',
   snippets: 'snippets/',
   governance: 'governance/rules/',
 }
 
-const ADAPTERS: Record<StampDomain, (root: string) => SyncAdapter> = {
+const ADAPTERS: Record<ScannedDomain, (root: string) => SyncAdapter> = {
   standards: createStandardsAdapter,
   snippets: createSnippetsAdapter,
   governance: createGovAdapter,
 }
 
-const INSTALL_MARKERS: Record<StampDomain, readonly string[]> = {
+const INSTALL_MARKERS: Record<ScannedDomain, readonly string[]> = {
   standards: ['.claude', 'standards'],
   snippets: ['.claude', 'snippets'],
   governance: ['.claude', 'rules'],
@@ -54,7 +69,7 @@ export interface StateCounts {
 }
 
 export interface DomainReport {
-  readonly domain: StampDomain
+  readonly domain: ScannedDomain
   readonly stamped: boolean
   /** This domain's own anchor, not the target's most recent sync. */
   readonly commit?: string
@@ -74,11 +89,60 @@ export interface UpstreamCommit {
   readonly subject: string
 }
 
+/** Pending changes per category, from the same scan `aitk tooling sync` reads. */
+export interface ToolingCounts {
+  readonly configs: number
+  readonly seeds: number
+  readonly scripts: number
+  readonly deps: number
+  readonly gitignore: number
+  readonly references: number
+}
+
+/**
+ * Tooling's own section. `measured` is the field the report exists for: without
+ * it a target that never installed tooling and a target whose tooling is current
+ * both render as zero changes, which is a claim rather than an absence of one.
+ */
+export interface ToolingReport {
+  readonly measured: boolean
+  /**
+   * Stack names the install resolved, nearest first. Carried even when the
+   * report is unmeasured, so a chain naming stacks this toolkit no longer ships
+   * stays distinguishable from a target that recorded none.
+   */
+  readonly chain: readonly string[]
+  readonly commit?: string
+  readonly syncedAt?: string
+  readonly counts: ToolingCounts
+  readonly changes: number
+}
+
+const UNMEASURED_TOOLING: ToolingReport = {
+  measured: false,
+  chain: [],
+  counts: {
+    configs: 0,
+    seeds: 0,
+    scripts: 0,
+    deps: 0,
+    gitignore: 0,
+    references: 0,
+  },
+  changes: 0,
+}
+
 export interface CheckReport {
   readonly covers: readonly StampDomain[]
   /** False when the target is not a toolkit project, so every section stays empty. */
   readonly managed: boolean
   readonly domains: readonly DomainReport[]
+  /**
+   * Reported beside the domains rather than as one of them, because tooling
+   * carries no per-file entries and no upstream range, so it fills almost none
+   * of `DomainReport`.
+   */
+  readonly tooling: ToolingReport
   /**
    * Reported beside the domains rather than as one of them, because seeds carry
    * no stamp and produce no change. See `@/sync/seeds-report`.
@@ -89,12 +153,58 @@ export interface CheckReport {
   readonly newSkills: readonly string[]
 }
 
-export function installedStampDomains(target: string): StampDomain[] {
-  return STAMP_DOMAINS.filter((domain) =>
+export function installedStampDomains(target: string): ScannedDomain[] {
+  return SCANNED_DOMAINS.filter((domain) =>
     isDirectory(join(target, ...INSTALL_MARKERS[domain])),
   )
 }
 
+/**
+ * Reads the chain the install recorded and scans against those stacks rather
+ * than re-resolving from the leaf. A run that passed `--skip` installed fewer
+ * layers than the leaf's own chain reproduces, so re-resolving would report
+ * drift against a layer the target deliberately does not carry.
+ *
+ * A recorded stack the toolkit no longer ships resolves to nothing, and a chain
+ * where none resolve reads as unmeasured. Scanning the survivors would measure
+ * against a chain neither side agrees on.
+ */
+export function buildToolingReport(
+  toolkitRoot: string,
+  target: string,
+  stamp: Stamp | undefined,
+): ToolingReport {
+  const chain = stampedChain(stamp)
+  const manifests = chain
+    .map((name) => loadManifest(toolkitRoot, name))
+    .filter((manifest) => manifest !== undefined)
+
+  if (manifests.length === 0) return { ...UNMEASURED_TOOLING, chain }
+
+  const result = scan(manifests, target, { includeReferences: true })
+  const record = stamp?.domains.tooling
+
+  return {
+    measured: true,
+    chain,
+    commit: record?.commit,
+    syncedAt: record?.syncedAt,
+    counts: {
+      configs: result.configs.filter((entry) => entry.state !== 'matching')
+        .length,
+      seeds: result.seeds.filter((entry) => entry.state === 'missing').length,
+      scripts: result.scripts.filter((entry) => entry.state !== 'matching')
+        .length,
+      deps: result.deps.filter((entry) => entry.state === 'missing').length,
+      gitignore: result.gitignore.filter((entry) => entry.state === 'missing')
+        .length,
+      references: result.references.filter((entry) => entry.state === 'pending')
+        .length,
+    },
+    changes: result.totalChanges,
+  }
+}
+
 /**
  * Whether the target is a toolkit-managed project at all. Seeds are enumerated
  * from the source rather than from what a target installed, so without this gate
@@ -143,6 +253,11 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * the user can move content they wrote, so failing a job on it leaves the job
  * red with no mechanical remedy. Seeds are excluded on the same grounds, since
  * every seed a project edits would otherwise fail the check forever.
+ *
+ * Tooling is excluded on exactly the seeds grounds: a golden config is one the
+ * project is expected to edit, so a job counting it stays red with no remedy.
+ * Being unmeasured is not what excludes it, since an unmeasured report carries
+ * zero changes and would pass a count either way.
  */
 export function hasDrift(report: CheckReport): boolean {
   if (report.unmigrated.length > 0) return true
@@ -186,6 +301,7 @@ export async function buildCheckReport(
       covers: [],
       managed,
       domains: [],
+      tooling: UNMEASURED_TOOLING,
       seeds: { entries: [], historyUnavailable: false },
       superseded: [],
       unmigrated: [],
@@ -197,6 +313,7 @@ export async function buildCheckReport(
     covers: stamp?.covers ?? [],
     managed,
     domains,
+    tooling: buildToolingReport(toolkitRoot, target, stamp),
     seeds: buildSeedsReport(toolkitRoot, target),
     superseded: collectSuperseded(target),
     unmigrated,
@@ -208,7 +325,7 @@ async function buildDomainReport(
   toolkitRoot: string,
   target: string,
   stamp: Stamp | undefined,
-  domain: StampDomain,
+  domain: ScannedDomain,
 ): Promise<DomainReport> {
   const plan = planSync(ADAPTERS[domain](toolkitRoot), target)
   const record = stamp?.domains[domain]

package/src/sync/stamp.ts

@@ -5,10 +5,16 @@ import { dirname, join, sep } from 'node:path'
 import { execa } from 'execa'
 
 /**
- * Domains the stamp can attribute. Tooling runs its own inject and manifest
- * machinery rather than the sync engine, so it is absent by design.
+ * Domains the stamp can record. The first three attribute file by file through
+ * the sync engine. Tooling runs its own inject and manifest machinery, so it
+ * records the stack chain it resolved instead and carries no file hashes.
  */
-export const STAMP_DOMAINS = ['standards', 'snippets', 'governance'] as const
+export const STAMP_DOMAINS = [
+  'standards',
+  'snippets',
+  'governance',
+  'tooling',
+] as const
 
 export type StampDomain = (typeof STAMP_DOMAINS)[number]
 
@@ -31,6 +37,13 @@ export interface DomainStamp {
   readonly commit?: string
   readonly syncedAt: string
   readonly files: DomainHashes
+  /**
+   * Stack names the install resolved, nearest stack first. Present only for
+   * tooling. An ordered chain rather than the leaf name, because a stack that
+   * extends another cannot be reinstalled from its leaf alone, and a `--skip`
+   * run installs fewer layers than the leaf's own chain would reproduce.
+   */
+  readonly chain?: readonly string[]
 }
 
 export interface Stamp {
@@ -91,6 +104,15 @@ export function stampedHashes(
   return stamp.domains[domain]?.files ?? {}
 }
 
+/**
+ * The stack chain tooling last installed. An empty result is the state every
+ * target predating the tooling record sits in, and the report reads it as
+ * unmeasured rather than as clean.
+ */
+export function stampedChain(stamp: Stamp | undefined): readonly string[] {
+  return stamp?.domains.tooling?.chain ?? []
+}
+
 /**
  * Replaces one domain's record and leaves the others untouched, because domains
  * install and sync independently but share the one file.
@@ -100,6 +122,34 @@ export async function writeStamp(
   source: StampSource,
   hashes: DomainHashes,
   now: Date,
+): Promise<void> {
+  await putDomain(target, source, { files: sortKeys(hashes) }, now)
+}
+
+/**
+ * Records what tooling installed. `files` stays empty because `src/tooling/`
+ * never runs the sync engine, so there is no per-file attribution to store and
+ * the chain is the whole record.
+ */
+export async function writeChainStamp(
+  target: string,
+  toolkitRoot: string,
+  chain: readonly string[],
+  now: Date,
+): Promise<void> {
+  await putDomain(
+    target,
+    { domain: 'tooling', toolkitRoot },
+    { files: {}, chain: [...chain] },
+    now,
+  )
+}
+
+async function putDomain(
+  target: string,
+  source: StampSource,
+  payload: Pick<DomainStamp, 'files' | 'chain'>,
+  now: Date,
 ): Promise<void> {
   const previous = readStamp(target)
   const commit = await toolkitCommit(source.toolkitRoot)
@@ -107,7 +157,7 @@ export async function writeStamp(
   const record: DomainStamp = {
     ...(commit === undefined ? {} : { commit }),
     syncedAt: now.toISOString(),
-    files: sortKeys(hashes),
+    ...payload,
   }
 
   const domains = sortDomains({
@@ -187,16 +237,26 @@ function isStamp(value: unknown): value is Stamp {
   )
 }
 
+/**
+ * `chain` is optional, which is what keeps a stamp written before tooling
+ * joined the domains readable rather than parsing as corrupt and discarding
+ * the three records it does carry.
+ */
 function isDomainStamp(value: unknown): value is DomainStamp {
   if (!isRecord(value) || !isRecord(value.files)) return false
   if (typeof value.syncedAt !== 'string') return false
   if (value.commit !== undefined && typeof value.commit !== 'string') {
     return false
   }
+  if (value.chain !== undefined && !isStringArray(value.chain)) return false
 
   return Object.values(value.files).every((hash) => typeof hash === 'string')
 }
 
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string')
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

package/src/tooling/stamp.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { writeChainStamp } from '@/sync/stamp'
+import type { Manifest } from '@/tooling/manifest'
+import { readPackage } from '@/tooling/package'
+
+/**
+ * Whether the target is a workspace root, where every package resolves its own
+ * stack. `package.json` covers bun, npm, and yarn, and pnpm declares the same
+ * fact in its own file instead.
+ */
+export function isWorkspaceRoot(target: string): boolean {
+  if (existsSync(join(target, 'pnpm-workspace.yaml'))) return true
+
+  const workspaces = readPackage(join(target, 'package.json'))?.workspaces
+  return Array.isArray(workspaces) || isRecord(workspaces)
+}
+
+/**
+ * Records the chain an install resolved, and returns whether it wrote one. A
+ * workspace root is the single refusal: one chain recorded there would be a
+ * guess at what its packages hold, and the report reading tooling as unmeasured
+ * is the true answer rather than a clean one.
+ */
+export async function recordToolingChain(
+  toolkitRoot: string,
+  target: string,
+  chain: readonly Manifest[],
+  now: Date,
+): Promise<boolean> {
+  if (isWorkspaceRoot(target)) return false
+
+  await writeChainStamp(
+    target,
+    toolkitRoot,
+    chain.map((manifest) => manifest.name),
+    now,
+  )
+  return true
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/standards/bundled/branch.md

@@ -1,7 +1,7 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr
+consumers: git-branch, git-split, git-pr, claude-worktree
 ---
 
 # Branch reference

package/standards/slug.md

@@ -16,9 +16,11 @@ Does not govern:
 
 ## The transform
 
-Run `git branch --show-current` and replace every `/` with `-`. The result is `<slug>`. Anything reading a branch-derived name uses this transform, so two surfaces cannot spell it differently.
+Run `git branch --show-current`. Drop a leading segment naming one of the types `branch.md` defines when a further segment follows it, then replace every remaining `/` with `-`. The result is `<slug>`. Anything reading a branch-derived name uses this transform, so two surfaces cannot spell it differently.
 
-A surface that persists output to a shared folder carries the slug in the filename, which is what keeps parallel worktrees from overwriting each other's output.
+The type comes off because a plan takes its slug from the concern it covers and the branch executing that plan carries the same slug behind a type prefix. Keeping the prefix sends every surface that finds a plan from a branch name looking for `feat-jwt-expiration`, which no plan is filed under. A first segment matching no type stays, so `spike/parser` still yields `spike-parser`.
+
+A surface that persists output to a shared folder carries the slug in the filename, which is what keeps parallel worktrees from overwriting each other's output. Two branches differing only in type collapse onto one slug. That collision reaches the worktree directory as well, since it takes its name from the same string, so the branch is not where it would first surface.
 
 ## An empty result