@erclx/aitk 0.93.0 → 0.95.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.93.0",
+  "version": "0.95.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -217,7 +217,7 @@ Write the retarget as a markdown link, `Plan: [feature-<slug>](../plans-archive/
 
 If `.claude/review/review-<slug>.md` exists, delete it. `claude-review` writes with this convention. Do not sweep any other `review-*.md` file.
 
-Do not sweep `ui-checklist-*.md` (pending human verification) or `ux-audit-*.md` (standalone deliverable).
+Do not sweep `ui-checklist-*.md` (pending human verification), `ux-audit-*.md`, or `ux-measure-*.md` (standalone deliverables).
 
 Output one line per file swept:
 

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

@@ -38,7 +38,7 @@ The roadmap is optional and this skill does not require it. It carries why a seq
 
 A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do.
 
-On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It captures what the session learned, then writes `.claude/tasks/session.md` with the state of play, the decisions taken under delegated authority, the mistakes worth not repeating, and the standing cautions. That capture is the only one this session runs, since the refill sweep reports it as owed rather than paying it. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
+On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It captures what the session learned, then writes a session map per `.claude/standards/session.md`, or `${CLAUDE_SKILL_DIR}/../../standards/session.md` when the project does not have it, carrying the state of play, the mistakes worth not repeating, and the standing cautions, with the decisions taken under delegated authority added as this role's extension. That capture is the only one this session runs, since the refill sweep reports it as owed rather than paying it. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
 
 On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work.
 

package/claude/skills/claude-orchestrate/references/orchestrator-handoff.md

@@ -1,58 +1,30 @@
 ---
 title: Orchestrator handoff runbook
-description: Memory capture at the close of a session, what to write to .claude/tasks/session.md before a compaction, what to leave to the board, and the resume invocation the file carries out
+description: The two sections an orchestrating session adds over the shared session map, how capture runs from a session that never commits, and the resume invocation the file carries out
 ---
 
-Capture what the session learned, then write the pre-compact handoff as orchestrator. Do both before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them, and no other file in the repository carries that reasoning.
+Write the pre-compaction handoff as orchestrator. Follow `.claude/standards/session.md`, or `${CLAUDE_SKILL_DIR}/../../standards/session.md` when the project does not have it, for the filename, the three core sections, the write procedure, and the citation rule. Everything below is the extension this role adds over that core, and none of it belongs to a session holding no delegated authority.
 
-1. Invoke `aitk:claude-memory-capture` and tell it this session does not commit. Capture reads the session and this handoff summarizes it, so capturing first lets the handoff cite what was written instead of restating the same lesson in prose.
-2. Run `aitk claude skills drift <commit this session started from>` and re-read any body it names before writing anything below. Nothing on the machine records that commit, so recover it from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. A ref older than the oldest load over-reports and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making. A skill body enters a session once and re-invoking the skill replays the held copy rather than the file, so the drift is worst at exactly this moment and a name here is a body this session has been following out of date. Record what it named under `## Standing cautions`. The verb answers where the working directory carries `claude/skills/` with history behind it, which is the toolkit repository itself, and refuses by naming the absent tree anywhere else. A project consuming the plugin from a marketplace cache is that second case, so read the refusal as the boundary rather than as a fault.
-3. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Write `.claude/tasks/session.md` under it.
-4. Write only what a compaction destroys and no other file already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a groundwork folder holds its track.
-5. Use this shape, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
+1. Run the capture step the core opens with, and tell `aitk:claude-memory-capture` that this session does not commit.
+2. Add `## Decisions taken under delegated authority` directly after `## State`, holding each decision and why it went that way, so nobody re-proposes it. It sits there rather than after the core because a decision is read against the state it was taken in.
+3. Close the file with the block below, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
 
 ```markdown
----
-title: Session map
-description: <what the board cannot show, and the date it was written>
----
-
-# Session map
-
-<one line marking the file throwaway and naming the board as the real source>
-
-## State
-
-<what is clean, what is running, what is open, and any untracked file that needs committing>
-
-## Decisions taken under delegated authority
-
-<each decision and why it went that way, so nobody re-proposes it>
-
-## Mistakes worth not repeating
-
-<what went wrong and the rule it yields>
-
-## Standing cautions
-
-<commands that lie, tools that measure the wrong tree, and anything unbacked>
-
 Resume by loading the orchestrator skill and asking it to resume after a compaction. This repository spells that `/aitk:claude-orchestrate` followed by the request. Following <RESUME_RUNBOOK> reaches the same place with no skill loaded at all.
 
-That resume reads the board and stops. It restarts nothing, so the review poll is a second thing owed here, and <POLL_RUNBOOK> holds the prompt and the condition. Do not reach for `session-resume`, which reads tracked work and knows nothing about this board or the workers on it.
+That resume reads the board and stops. It restarts nothing, so the review poll is a second thing owed here, and <POLL_RUNBOOK> holds the prompt and the condition. Do not reach for `session-resume`, which reads tracked work and reports the newest map without restarting this loop.
 ```
 
-6. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
-7. Overwrite the previous handoff rather than appending to it. A stale entry read as current is worse than no handoff.
-
-The substitution belongs in step 5 because step 7 ends the write. A reader who treats the list as finished there ships the literal placeholders, and the variable expands while this runbook renders rather than in the turn that reads the handoff back, so a path left unresolved reaches a session holding no skill as a string matching nothing. `orchestrator-poll.md` resolves its script at the same point and for the same reason.
+The delegated-authority section is the orchestrator's alone because a worker holds no delegation to have exercised, and a section a session cannot fill teaches its reader to skip the file. The closing block is the orchestrator's for the same reason from the other direction: it restarts a review poll no other role runs.
 
-Add a section only for content that fits none of the four and would otherwise be lost. Do not restate the board, and do not summarize the work that shipped, because git already carries it. The closing block is the one exception, and the paragraph below states why.
+The substitution belongs in step 3 because that step ends the write. A reader who treats the list as finished elsewhere ships the literal placeholders, and the variable expands while this runbook renders rather than in the turn that reads the handoff back, so a path left unresolved reaches a session holding no skill as a string matching nothing. `orchestrator-poll.md` resolves its script at the same point and for the same reason.
 
-That block sits in this runbook and again in the file this runbook writes, which is the fix rather than a copy for a later pass to collapse. A session has to already be holding this runbook to read it, and a compaction that took the skill body took the routing to it too, so the session that most needs the resume is the one that can no longer find it. `session.md` survives that, so it carries the invocation itself. Each of the two reaches a reader the other cannot.
+That block sits in this runbook and again in the file this runbook writes, which is the fix rather than a copy for a later pass to collapse. A session has to already be holding this runbook to read it, and a compaction that took the skill body took the routing to it too, so the session that most needs the resume is the one that can no longer find it. The map survives that, so it carries the invocation itself. Each of the two reaches a reader the other cannot.
 
 The requirement is a resume request to the orchestrator skill with that skill loaded first. The command the block carries is this repository's spelling rather than the only one, since the skill ships to every target holding the plugin and each runs whatever client it runs. The poll restart is named beside it because the resume performs none.
 
 Step 1 exists because both other callers of capture are ship-chain skills and this session never ships. Without a call here, the session that receives every operator correction is the one session that records none. A compaction arriving with no warning takes the capture with it, and firing it once per batch of merges leaves the same window open across a long planning stretch, since a sweep runs only on a merge. The refill sweep reports the debt between handoffs so the operator knows one is owed.
 
 Capture is told this session does not commit, so it skips routing and writes memory files alone. A routed fact lands in a context entry, which is a tracked file, and the orchestrator's boundaries forbid writing one from this session. That split is correct rather than a limitation, since a domain fact belongs to the task that owns the surface and goes in that task's Findings, while what this session produces is feedback about how to work, which is the class the memory folder keeps.
+
+The core's drift step answers where the working directory carries `claude/skills/` with history behind it, which is the toolkit repository itself, and refuses by naming the absent tree anywhere else. A project consuming the plugin from a marketplace cache is that second case, so read the refusal as the boundary rather than as a fault.

package/claude/skills/claude-orchestrate/references/orchestrator-resume.md

@@ -6,7 +6,7 @@ description: What to read back after a compaction, and how to treat a groundwork
 Resume as orchestrator after a compaction. Read the board and the groundwork behind the live work before answering anything, because a compaction summary keeps conclusions and drops the reasoning that produced them.
 
 1. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Every path below resolves against it.
-2. Read `.claude/tasks/priority.md` for the ordering and what each task waits on. Read `.claude/tasks/session.md` when it exists, and treat it as this session's scratch rather than a source.
+2. Read `.claude/tasks/priority.md` for the ordering and what each task waits on. Read the newest `.claude/tasks/session-*.md` when one exists, per `.claude/standards/session.md`, and treat it as the previous session's scratch rather than a source.
 3. Read the task file for every entry under `## Run now`, plus any entry a live pull request names.
 4. Read the groundwork folder each of those tasks cites. Read `README.md` for the file map, then `06-decision.md` when the track is closed, or `07-next-session.md` and the numbered topic files when it is open. A task's Findings section is a lossy summary of its track, so planning against the summary re-derives what the folder already settled.
 5. Run `gh pr list --state open` and `git log --oneline -5` to see what shipped since the folder was written.

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

@@ -37,3 +37,4 @@ The pass slides into fixing what it finds, and then the audit and the change lan
 - Feature planning, which `claude-feature` owns
 - Verifying one specific change, which `claude-ui-test` owns
 - Defining the intent it audits against, which `claude-design-extract` and the wireframes own
+- Measuring what a running interface costs to paint, block, or shift, which `claude-ux-measure` owns. Contrast stays here rather than going with it, being computable from two color values this skill already reads off the token table.

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

@@ -1,6 +1,6 @@
 ---
 name: claude-ux-audit
-description: Audits the current UI for incomplete, inconsistent, or confusing patterns. Reads DESIGN.md and .claude/wireframes/ for intent, scans UI files, and outputs observations grouped by surface. Use when asked "audit the UX", "audit the UI", "UX audit", or "find UI roughness". Do NOT use for new feature planning or code changes.
+description: Audits the current UI for incomplete, inconsistent, or confusing patterns. Reads DESIGN.md and .claude/wireframes/ for intent, scans UI files, and outputs observations grouped by surface. Use when asked "audit the UX", "audit the UI", "UX audit", or "find UI roughness". Do NOT use for new feature planning or code changes, and do NOT use to measure what a running interface costs to paint, which is `claude-ux-measure`.
 ---
 
 # Claude UX audit
@@ -8,6 +8,7 @@ description: Audits the current UI for incomplete, inconsistent, or confusing pa
 ## Guards
 
 - If no UI files exist in the project (no JSX, TSX, Vue, Svelte, or HTML under `src/`), stop: `❌ No UI surfaces found to audit.`
+- If the request asks what the interface costs to paint, block, or shift at runtime, run nothing and name `claude-ux-measure`. This skill reads source and reaches no number a browser produces. Contrast is the exception and stays here, since it is computable from the two color values already in the token table.
 
 ## Step 1: read context
 

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

@@ -0,0 +1,45 @@
+---
+name: claude-ux-measure
+description: Why a rendering cost question is answered with a number against a published threshold, and why the runner is detected rather than prescribed
+---
+
+# Claude UX measure requirement
+
+## Gap
+
+Without this skill, a session asked what a page costs answers from source. It reads component code, names a suspicious loop, and reports a judgment, so nobody learns the number and the next session repeats the guess. Nothing in the corpus starts a browser, so the question has no surface at all and lands on whichever skill matched the word "UI".
+
+A session that does start one picks a runner on the spot. The reading then comes from a browser nobody chose, cannot be compared against the next run, and disappears with the chat. A number reported with no boundary beside it is the same dead end as the judgment it replaced, because a reader holding `1.9s` and no threshold concludes nothing from it.
+
+## Must
+
+- Detect the harness the project already carries before naming any runner
+- Report a number per metric beside the threshold it is measured against and the published source of that threshold
+- Cover paint, processor, and layout cost, and name what the run left unmeasured
+- Report what the measurement needs and stop when no harness is detected, since that is a project without a runner rather than a failure here
+- Take several readings and report the median, since one load carries startup noise wider than the gap between two thresholds
+- Write the reading to the branch-derived path at the main worktree root, overwriting
+- Reach the URL before measuring against it, starting the project's own command only when nothing already answers there
+- Leave the interface stopped and the probe deleted
+
+## Must not
+
+- Install a runner, add a dependency, or write a config to make detection succeed
+- Invent a threshold, or move a published one to fit a reading
+- Report an observation about the source in place of a measurement
+- Suggest a fix for what it measured, which is a change with its own review
+- Measure anything past the three metrics, since every adjacent ask doubles the run
+
+## Guards
+
+- No command that serves an interface and no URL from the user: stop, since there is nothing to reach. Test for a servable interface rather than for source under a named folder, which refuses a project laying its tree out differently while its server sits ready
+- No harness detected: name the runners this can drive and stop
+- No URL derivable from the project's own commands: ask rather than guessing a port
+
+## Out of scope
+
+- Judging the interface against stated intent, which `claude-ux-audit` owns
+- Contrast, which is computable from two color values in the token table `claude-ux-audit` already reads. A contrast failure from a color computed at runtime stays invisible to that reader, and the cost is accepted rather than overlooked.
+- Network waterfall, bundle size, and accessibility, which no version of this measures
+- Writing behavioral tests against the interface, which `claude-ui-test` owns
+- Fixing what the reading found

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

@@ -0,0 +1,110 @@
+---
+name: claude-ux-measure
+description: Measures paint, processor, and layout cost against a running interface and reports numbers against published thresholds. Detects the project's existing browser harness rather than requiring one. Use when asked "how fast is this page", "measure the UI", "what does this cost to render", "check Core Web Vitals", or "profile the interface". Do NOT use to judge UI quality by reading source, which is `claude-ux-audit`.
+---
+
+# Claude UX measure
+
+Report numbers. A sentence about what the source looks like is what this exists to replace, so every finding is a reading beside the threshold it is measured against.
+
+## Guards
+
+- If the project names no command that serves an interface and the user names no URL, stop: `❌ Nothing to serve. Name a running URL or a command that starts one.` Test for a servable interface rather than for source under a particular folder, since this measures what a browser receives and never reads the tree that produced it.
+- If the request is about intent, consistency, missing states, or contrast, run nothing and name `claude-ux-audit`. That skill reads source and this one runs the interface.
+
+## Step 1: reach the interface
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `package.json`: the `scripts` block naming a dev, preview, or start command
+- `.claude/context/development/`: the documented run commands and the port each serves
+- `CLAUDE.md`: project type and conventions
+
+Prefer a production-shaped build (`preview`, `start`) over the dev server. A dev server ships unminified modules and reports a cost no user pays.
+
+Ask for the URL when nothing names one. Do not guess a port.
+
+Then reach it. Request the URL first and measure whatever already answers, since a server the user started is the one they mean. Build and start the chosen command only when nothing answers, wait for it to accept a request before going on, and stop it once Step 4 has the readings. A run that measures before the server is listening reports a connection failure as a cost.
+
+## Step 2: detect the harness
+
+Test each in order and take the first that resolves. Name the one found before running it.
+
+1. A connected browser MCP server exposing navigation and a performance trace
+2. `@playwright/test` or `playwright` in `package.json`, or a `playwright.config.*` at the project root
+3. `lighthouse` in `package.json`, or a script whose command names it
+
+Never install a runner, add a dependency, or write a config to make one of these resolve. The project chooses its harness and this skill reads that choice.
+
+When none resolves, report what the measurement needs and stop:
+
+```plaintext
+❌ No browser harness detected. This measurement drives one of:
+   - a browser MCP server with a performance trace
+   - Playwright (@playwright/test)
+   - Lighthouse (lighthouse)
+Install one, or name a running URL and which runner to drive it with.
+```
+
+## Step 3: measure
+
+Take three readings against the same URL on a cold profile and report the median. One load carries startup noise wider than the gap between two thresholds, so a single number cannot be placed against them.
+
+Measure these three and nothing else:
+
+- **Paint**: Largest Contentful Paint, the moment the largest element in the viewport finishes rendering
+- **Processor**: Total Blocking Time, main-thread time past 50ms per long task between first paint and interactive
+- **Layout**: Cumulative Layout Shift, the summed score of unexpected shifts over the page lifetime
+
+Through Playwright or an MCP server, read them from a `PerformanceObserver` registered before navigation against the `largest-contentful-paint`, `longtask`, and `layout-shift` entry types. Lighthouse reports all three under its JSON audits, so parse rather than re-derive them.
+
+Write any probe the harness needs into the project's own test folder, run it, then delete it. Leave no file behind.
+
+### Thresholds
+
+| Metric | Good      | Needs work | Poor      |
+| ------ | --------- | ---------- | --------- |
+| LCP    | `≤ 2.5s`  | `≤ 4.0s`   | `> 4.0s`  |
+| TBT    | `≤ 200ms` | `≤ 600ms`  | `> 600ms` |
+| CLS    | `≤ 0.1`   | `≤ 0.25`   | `> 0.25`  |
+
+These are Google's published Core Web Vitals boundaries, with the Lighthouse lab boundary for Total Blocking Time. Cite that source in the report. Never move a number to fit a reading, and never invent a fourth metric's boundary.
+
+## Step 4: report and persist
+
+### Report format
+
+```markdown
+3 metrics measured against <url> over 3 runs. Harness: <name>.
+
+| Metric | Median | Threshold | Verdict                      |
+| ------ | ------ | --------- | ---------------------------- |
+| LCP    | <n>    | `≤ 2.5s`  | <good \| needs work \| poor> |
+| TBT    | <n>    | `≤ 200ms` | <verdict>                    |
+| CLS    | <n>    | `≤ 0.1`   | <verdict>                    |
+
+Thresholds: Google Core Web Vitals, Lighthouse lab boundary for TBT.
+
+Not measured: network waterfall, bundle size, accessibility, contrast.
+```
+
+Report the reading and stop there. A remedy for a poor verdict is a change with its own review, so name no fix and edit no source.
+
+### Persist
+
+Derive `<slug>` per `.claude/standards/slug.md`, or `${CLAUDE_SKILL_DIR}/../../standards/slug.md` when the project does not have it. Fall back to `latest` on an empty result.
+
+Write the full reading directly to `.claude/review/ux-measure-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+From a linked worktree the file-editing tools refuse that path, so the reading goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+### Chat output
+
+Output the summary line and the file path. Do not repeat the table in chat.
+
+```plaintext
+3 metrics measured against <url>. <n> past threshold.
+📝 Wrote .claude/review/ux-measure-<slug>.md
+```

package/claude/skills/session-resume/REQUIREMENT.md

@@ -1,6 +1,6 @@
 ---
 name: session-resume
-description: Why resuming reads an index before task files, resolves scratch at the main root, and never mutates what it reports
+description: Why resuming reads the handoff before the board, reads an index before task files, resolves scratch at the main root, and never mutates what it reports
 ---
 
 # Session resume requirement
@@ -9,14 +9,20 @@ description: Why resuming reads an index before task files, resolves scratch at
 
 Without this skill, a session picking up old work reconstructs state from the git log, which records what shipped and not what is queued, so finished work reads as pending and the actual next item goes unmentioned. The alternative failure is worse for a different reason. A session that reads every task file and every plan to be thorough spends the context the work needs before the work starts, and the summary arrives in a session with no room left to act on it.
 
+A compaction keeps conclusions and drops the reasoning that produced them, and the previous session can write that reasoning to a handoff before it goes. A resume that reads the board, the plans, and the memory index alone walks past that file, so the one artifact written to survive the compaction reaches nobody and the next session re-derives what it holds.
+
+The task index is a folder catalog rather than a task filter, so it carries a row for the ordering file and one for every handoff on the board. A session reporting each row as a backlog item queues work nobody filed, and the count grows with every session that ever wrote a handoff.
+
 From a linked worktree the shared scratch folders resolve against the worktree rather than the main root, where they are empty. That reports no tracked work on a repository carrying a full backlog, and the report is indistinguishable from the true empty case.
 
 A resume is a read, and a session that treats it as a cleanup pass offers to archive finished entries or refresh a memory it decided was stale. Both change tracked state on the strength of a summary the user has not confirmed yet.
 
 ## Must
 
-- Resolve the plans, memory, and tasks folders at the main worktree root
+- Read the newest handoff before the board, and report what it carries attributed to its writer
+- Resolve the handoff, plans, memory, and tasks folders at the main worktree root
 - Read the task index before any individual task file, and open only the task files the summary needs
+- Drop the board siblings from the index before reporting it as the backlog, since the catalog filters nothing and carries a row per handoff
 - Preserve the index's order in the report, since the order is the priority
 - Surface only the memory entries that inform the top item
 - Close with one recommendation naming the first item and whether a plan backs it
@@ -24,15 +30,20 @@ A resume is a read, and a session that treats it as a cleanup pass offers to arc
 ## Must not
 
 - Read the whole tasks folder to build a summary
+- Report the absence of a handoff, which is the common case and would train a reader to skip the line on the run where one exists
+- Restate a handoff's counts, sizes, or costs as current. Each was true when written.
 - Offer to remove, archive, or reorder an entry. Resume reports and does not mutate.
 - Update memory, which changes when a recorded fact becomes wrong rather than on a resume
 
 ## Guards
 
-- All three surfaces absent or empty reports no tracked work and stops, rather than inventing a next step from the repository
+- All four surfaces absent or empty reports no tracked work and stops, rather than inventing a next step from the repository
+- A handoff found beside an empty board recommends what the handoff leaves open, since the guard passes on the handoff alone and the recommendation has no backlog item to name
 
 ## Out of scope
 
+- Writing a handoff, which happens at the close of a session rather than at its start. This skill names the standard that governs one and follows it no further.
+- The sections a role adds over the core handoff, which belong to that role's own surface
 - Archiving a shipped task out of the folder: `claude-tasks`
 - Archiving a plan and marking an outcome, which `claude-docs` does when the work ships
 - Implementing the item it recommends, which is the next request rather than part of this one

package/claude/skills/session-resume/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-resume
-description: Resumes a previous session by reading tracked work and relevant context. Use when starting a new session, or when asked to "pick up where we left off", "what was I working on", or "resume".
+description: Resumes a previous session by reading the handoff it left behind, tracked work, and relevant context. Use when starting a new session, or when asked to "pick up where we left off", "what was I working on", or "resume".
 ---
 
 # Session resume
@@ -11,19 +11,24 @@ Resolve `.claude/plans/`, `.claude/memory/`, and `.claude/tasks/` at the main wo
 
 Read these in parallel, skipping any that do not exist:
 
-- `.claude/tasks/index.md`: the backlog, one line per task. Read this before any individual task file.
+- the newest `.claude/tasks/session-*.md`: the handoff a previous session wrote before a compaction, per `.claude/standards/session.md`, or `${CLAUDE_SKILL_DIR}/../../standards/session.md` when the project does not have it. It leads the report rather than the reads.
+- `.claude/tasks/index.md`: the folder catalog. Read this before any individual task file, and take the backlog from it by dropping the `index`, `priority`, and `session-` rows, which are siblings rather than tasks.
 - `.claude/plans/*.md`: execution detail for in-progress tasks
 - `.claude/memory/index.md` and any memory files relevant to the top backlog item
 
 Then read only the task files the summary needs, typically the top one. Do not read the whole folder.
 
-If all three surfaces are absent or empty, stop: `✅ No tracked work found. Start a new task.`
+Most projects carry no handoff. Say nothing about its absence, since a line reporting it every run trains a reader to skip the line on the run where a handoff exists.
+
+If all four surfaces are absent or empty, stop: `✅ No tracked work found. Start a new task.`
 
 ## Step 2: summarize
 
-Output three sections:
+Output these sections, omitting the first when no handoff was found:
+
+**Carried over:** the reasoning the handoff holds, as its writer stated it. Attribute it to the map rather than restating it as fact, and re-measure any count, size, or cost before acting on one.
 
-**Up next:** one line per entry in `.claude/tasks/index.md`, preserving order.
+**Up next:** one line per task row in `.claude/tasks/index.md`, preserving order. A board carrying handoffs has a row per session that wrote one, so a report listing every row queues work nobody filed.
 
 **Active plans:** one line per file in `.claude/plans/`, linking each to its task file in `.claude/tasks/`. Say "None" if empty.
 
@@ -33,6 +38,14 @@ Output three sections:
 
 End with one line: `Start with: <first Up next item>` and note whether it has a linked plan.
 
+When the board is empty and a handoff was found, name what the handoff leaves open instead: `Start with: <the open thread the handoff names>`. A recommendation slot filled with nothing reads as a failed run, and a handoff on an empty board is the shape a session leaves when it was reasoning rather than shipping.
+
 Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`.
 
 Memory is updated only when a recorded fact becomes wrong, never on resume. A domain fact reaches a session through `.claude/context/`, which `claude-memory-capture` routes to and the three-tier model loads on demand, so the memory folder read here is the residue no context entry owns.
+
+## Writing the next one
+
+This skill reads a handoff and never writes one. Reading and writing are two jobs, and the write happens at the close of a session rather than at its start.
+
+Name the standard when the session asks how to leave a handoff behind, and let the session follow it directly. Any session may write one, whatever role it holds, so nothing here routes the request to another skill. A role carrying sections of its own adds them over the core per that role's own runbook.

package/claude/skills/setup-gov/REQUIREMENT.md

@@ -11,12 +11,15 @@ Without this skill, a session picks a stack name from memory and installs rules
 
 The two costly failures are quieter. An unmatched technology gets the nearest rule instead of a stop, so the project carries governance authored for something adjacent and nothing marks it as a guess. A rule written directly into the target lands where no sync will ever reach it, so it drifts from the toolkit copy that owns it.
 
+The last failure sits at a boundary rather than inside a run. `setup-init` turns away a project whose language it carries no stack for and sends it here, and a body stating only what this skill does not cover leaves that route running one way, so a person arriving on it reads a skill that never says it is the destination.
+
 ## Must
 
 - Read the catalog at run time and resolve both the stack and every extra against it
 - Name the evidence file behind each detected technology in the preview, so a wrong match is visible before the install rather than after
 - Dedupe extras against the rules the picked stack already resolves
 - Run the install non-interactively, since the CLI picker blocks where no terminal is attached
+- State the inbound route from `setup-init`, so a project sent here for the language-neutral rule layer can tell it landed at the destination the chain named
 
 ## Must not
 

package/claude/skills/setup-gov/SKILL.md

@@ -7,6 +7,11 @@ description: Detects a project's stack from its files and installs matching tool
 
 Automates `aitk gov install` by inferring the stack and extras from the current project, then shelling out to the CLI with the resolved arguments.
 
+## Scope
+
+- Governance rules and nothing else. `setup-init` is the one-shot chain that installs governance beside tooling, standards, snippets, and the seeds.
+- This is where `setup-init` sends a project whose language the toolkit carries no stack for. Rules install without the `base` development dependencies the tooling layer would drop on it. Resolve and stop exactly as below, since a language with no stack is the unmatched case `## Gap handling` already owns and arriving by that route changes none of it.
+
 ## Read the catalog
 
 Run this first to load the current stacks and rules. Never hardcode names. The catalog is the source of truth.

package/claude/skills/setup-indexes/REQUIREMENT.md

@@ -11,6 +11,8 @@ Without this skill, a session bootstrapping the index system writes `index.md` i
 
 The scan is where the other failures start. A walk that does not prune reaches `node_modules`, gitignored output, and the snippets folder, which is invoked by reference rather than browsed and needs neither an index nor per-file frontmatter. A folder that already carries an `index.md` gets a second one written over the first.
 
+One failure predates the scan. `setup-init` declines an install that wants the Claude layer without the tooling chain and names this skill as where the index system gets bootstrapped, and a body that never states the inbound route leaves the person arriving on it unable to tell whether they landed at the destination or somewhere adjacent to it.
+
 Drafted frontmatter is a proposal, and a session that writes it before the user sees it turns a review into a cleanup. The convention block has the mirror failure. A session that paraphrases it into `CLAUDE.md` produces a copy that reads correctly and no longer matches its source, so the two drift with nothing reporting it. And a project with no `CLAUDE.md` gets one scaffolded to hold the block, which installs a file the project declined.
 
 ## Must
@@ -21,6 +23,7 @@ Drafted frontmatter is a proposal, and a session that writes it before the user
 - Validate with a dry run and stop on the first reported error, before writing for real
 - Paste the convention block verbatim from its single source
 - Emit the closeout exactly once, whatever the seed step concluded
+- State the inbound route from `setup-init`, so an install wanting the Claude layer without the tooling chain can tell it landed at the destination the chain named
 
 ## Must not
 

package/claude/skills/setup-indexes/SKILL.md

@@ -13,6 +13,7 @@ Read `.claude/context/indexes.md` from the toolkit if context on the system is n
 
 - Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.
 - All-or-nothing per chosen folder. Every `*.md` sibling in a chosen folder gets `title` and `description` injected, or none does. Partial migration creates folders that hard-error on regen.
+- This is where `setup-init` sends an install that wants the Claude layer without the tooling chain, once `aitk claude init` has seeded the docs. The work is the same either way, since the scan below prunes `.claude` and reads the project's own documentation folders whichever route reached it.
 
 ## Scan
 

package/claude/skills/setup-init/REQUIREMENT.md

@@ -11,12 +11,18 @@ Without this skill, a session installs a stack whose name it recalled rather tha
 
 Two failures are the expensive ones because both return success. A monorepo run drops husky into every subtree, git honors one `core.hooksPath`, and the extra hook directories go quiet with nothing reporting it. A caller reads the chain as onboarding complete when index bootstrap and plugin provisioning never ran, since no step states whether they belong to the chain.
 
+Two more start at the resolve step. A project whose language the toolkit carries no stack for resolves to `base`, and the preview reports the resolved name without marking it as a fallback, so `base` development dependencies, scripts, and hooks land on a project that will not use them and nobody had the moment to decline.
+
+The other is the refusal that ends rather than routes. An existing project, an install wanting the Claude layer without the tooling chain, and a language with no stack are the three states the chain does not serve, and each is declined by a declaration naming no destination, so the person who arrived with one reads a stop and goes no further.
+
 ## Must
 
 - Resolve every domain argument against a catalog read at run time, so a stack, rule, snippet, or tooling name the catalog does not carry cannot reach the command line
 - Preview the resolved chain before the first command runs, naming the evidence file behind each detected technology
 - Pass `--skip base` on every subtree past the first in a monorepo, so the shared hook layer lands once
 - State which onboarding steps the chain does not run, so a caller knows what is left rather than inferring completeness from a clean report
+- Mark a stack reached by fallback as a fallback in the preview, and name what `base` carries, so the write can be declined at the one point it is still declinable
+- Name a destination for every state the chain does not serve, in this body rather than only in a reference doc the person would have to already know to open, and say for each whether the chain stops or runs on a default
 
 ## Must not
 
@@ -35,3 +41,5 @@ Two failures are the expensive ones because both return success. A monorepo run
 - Provisioning Claude Code plugins: `setup-plugins`. Those install once per machine rather than into a project, so no project-scoped chain can carry them.
 - Running the verification scripts, which `setup-verify` owns and this chain invokes as its last step
 - Re-installing into a project that already has the files, which the per-domain `aitk <domain> install` and `aitk sync` commands own
+- Deciding which of those per-domain commands an existing project needs: `toolkit-operator`. That skill reads the target before naming one, which this chain never does, so it is the destination rather than a guess made here.
+- Seeding the `.claude/` folder without the tooling chain, which `aitk claude init` does on its own and `setup-indexes` finishes

package/claude/skills/setup-init/SKILL.md

@@ -12,6 +12,16 @@ Orchestrates the onboarding chain. Detects project type, resolves per-domain arg
 - This skill and `aitk init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `aitk <domain> install` or `aitk sync` paths instead.
 - The chain does not bootstrap the `index.md` system and does not provision Claude Code plugins. `setup-indexes` owns the first. `setup-plugins` owns the second, which installs once per machine rather than into a project, so no project-scoped chain can carry it. Name both in the report so a clean result does not read as onboarding complete.
 
+## Declined states
+
+Three states reach this skill that the chain does not serve. Name the destination for each, so the refusal routes rather than ends. The first two stop the chain outright and the third runs it on a default the person may not want.
+
+- **An existing project.** Stop and hand off to `toolkit-operator`. It reads what the target already carries before it names a command, which this chain never does, so any per-domain install picked here is a guess against configs nobody read. The Scope bullet above names the same commands as the authoring alternative, and this is the destination a person takes.
+- **An install wanting the `.claude/` folder alone.** Stop. Run `aitk claude init` for the seed docs, then invoke `setup-indexes` to bootstrap the `index.md` system over the project's own documentation folders. Neither needs the tooling sync this chain runs.
+- **A language the toolkit carries no stack for.** The chain still runs, on `base`, with the fallback marked in the preview. A project that wants none of what `base` carries declines there and takes `setup-gov` for the governance layer, which is language-neutral. Say so at the preview rather than resolving it here, since the fallback is a working default and only the person can say whether it fits.
+
+Do not add a stack, a mode switch, or an existing-project branch to satisfy one of these. Each destination already exists and routing to it costs a line.
+
 ## Read catalogs
 
 Run in parallel. Never hardcode stack, rule, snippet, or standards names.
@@ -36,8 +46,8 @@ Read these from the project root in parallel, skipping any that do not exist:
 
 ## Resolve arguments
 
-- **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base`.
-- **Tooling stack:** pick the closest tooling stack from `aitk tooling list --json` (e.g. `vite-react`, `astro`). Distinct from the governance stack. Fall back to `base` if no framework match.
+- **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base` and carry the fallback into the preview.
+- **Tooling stack:** pick the closest tooling stack from `aitk tooling list --json` (e.g. `vite-react`, `astro`). Distinct from the governance stack. Fall back to `base` if no framework match, and carry that fallback into the preview too.
 - **Extras:** identify technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology and pass it via `--add`. Do not add a rule the stack already pulls in.
 - **Snippets:** default to `all`. Narrow only if the user asked for a specific category.
 - **Skip (`--skip`):** `standards` and `wiki` are core and install by default. Add `--skip standards` or `--skip wiki` only when the user explicitly wants them left out.
@@ -56,14 +66,16 @@ Rules, snippets, and stacks are authored in the toolkit repo, never in the targe
 Before executing, output:
 
 - **Detected:** each technology with its evidence file
-- **Stack:** picked governance stack + resolved rule count
-- **Tooling stack:** picked tooling stack
+- **Stack:** picked governance stack + resolved rule count. Mark it `fallback` when no detected runtime or framework matched a catalog name.
+- **Tooling stack:** picked tooling stack. Mark it `fallback` on the same test, and name what `base` lands: configs, seeds, and gitignore entries in every case, plus the JavaScript development dependencies, scripts, and hook activation wherever a `package.json` exists to carry them. A project outside that ecosystem runs none of the second group and keeps the first.
 - **Extras:** each `--add` rule with a one-line reason
 - **Snippets:** resolved category
 - **Skip:** any `--skip` entries with reason
 - **Target:** resolved target path
 - **Commands:** the full chain that will run
 
+A resolved name and a fallback read alike once written, so mark the fallback here rather than in the report. The preview is the last point before the first write, and the report runs after the files have landed.
+
 ## Execute
 
 Run the chain in order, starting immediately after the preview. Each step's permission dialog is the confirmation gate. Do not pause for additional confirmation. Run from the target project's current directory.

package/claude/skills/toolkit-operator/REQUIREMENT.md

@@ -31,6 +31,7 @@ The last failure is a section no route reaches. `## Route` maps an intent or a d
 - Route a measurement intent to the audit offers from the route table itself, rather than leaving the section reachable only by reading past the table
 - Rank a lifecycle row against the audit offers where the route table itself states it, so a session acting on the lifecycle row reads the ranking without opening the section being ranked
 - Offer every audit whose surface the target carries, and offer none whose surface it lacks
+- Hand off an audit that is a skill rather than a command, since the execute contract governs a CLI run and says nothing about a skill's own guards
 - Re-check the target after any operation that wrote, and report what those writes changed against the state read before acting
 
 ## Must not

package/claude/skills/toolkit-operator/SKILL.md

@@ -69,7 +69,7 @@ On a measured report, take `<stack>` from the first name in `tooling.chain`, whi
 
 ### Audits
 
-Four audits measure a surface without changing it. Offer the ones whose surface the target carries, list them together, and let the user pick. Run none of them unasked, and never treat a finding as a reason to abandon the operation the user asked for, since each reports judgments beside facts.
+Five audits measure a surface without changing it. Offer the ones whose surface the target carries, list them together, and let the user pick. Run none of them unasked, and never treat a finding as a reason to abandon the operation the user asked for, since each reports judgments beside facts.
 
 A lifecycle row and these offers fire together on a project carrying a context folder and no installed domain, which is the ranking the preamble states. Scaffold work on a target with nothing installed is real work, so an audit offered instead of it answers a question nobody asked, while an audit dropped in favor of it loses the one the user did.
 
@@ -77,10 +77,13 @@ A lifecycle row and these offers fire together on a project carrying a context f
 - A record folder present under `.claude/`, one of `plans`, `groundwork`, `intake`, or `memory`: offer `aitk records validate <kind>` for each one found
 - Markdown that git lists: offer `aitk markdown audit`
 - TypeScript or shell source present: offer `aitk comments scan`
+- A `package.json` script that serves an interface, one of `dev`, `preview`, `serve`, or `start`: offer `claude-ux-measure`
 
 An audit offered against a surface the target lacks reports an empty run as a finding, which is the same defect as never offering it at all. Check the surface before naming the command.
 
-The markdown row is the one every target satisfies, since a project with no markdown is not one this reaches. Its condition is stated so the four rows read alike, and the row needs no gate beyond it.
+The markdown row is the one every target satisfies, since a project with no markdown is not one this reaches. Its condition is stated so the five rows read alike, and the row needs no gate beyond it.
+
+The last row is a skill handoff rather than a command, so `## Execute` does not govern it. Hand it off and stop, the way a lifecycle row hands off. Its condition reads a serving command rather than a source folder, since that skill measures what a browser receives and never opens the tree behind it. It carries a second condition this skill cannot read, which is a browser harness the project already installed, and the skill itself reports what it needs when it finds none. Testing for that here would put the detection in two places and let this one answer stale.
 
 ## Execute
 

package/docs/agents/tasks.md

@@ -103,7 +103,7 @@ The collision check is the one a person cannot run by eye. Paths come from the b
 
 Exit codes: `0` every check passed, `1` refused, `2` at least one finding. The `reason` field carries which gate refused: `no-board`, `no-ordering`, or `no-groups`. A board grouping under headings of its own trips `no-groups` rather than being read against columns it never declared.
 
-Columns are read from each table's own header rather than by position, so a project whose board differs from this one is reported for what it lacks. The `index`, `priority`, and `session` siblings are skipped, since none of the three is a task.
+Columns are read from each table's own header rather than by position, so a project whose board differs from this one is reported for what it lacks. The `index` and `priority` siblings are skipped, along with every pre-compaction handoff, which takes one file per session under a `session-` prefix. None of them is a task, and a handoff counted as one would be reported as a task carrying no row on every session that wrote one.
 
 Skills branch on the findings rather than on the exit code:
 

package/docs/ai-workflow.md

@@ -181,6 +181,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 | `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                                                      |
 | `aitk:claude-ux-audit`       | Audit existing UI surfaces for missing states, edge cases, inconsistencies                                           |
+| `aitk:claude-ux-measure`     | Measure paint, processor, and layout cost against a running interface, on the harness the project already carries    |
 | `aitk:claude-autoship`       | After plan approval, chain implement → verify → review → draft PR                                                    |
 | `aitk:systematic-debugging`  | When a test fails or bug surfaces, enforce root-cause investigation before fixes                                     |
 | `aitk:git-ship`              | Post-feature: sync docs, commit, rename branch, open PR                                                              |

package/docs/target-projects.md

@@ -49,6 +49,8 @@ The chain is:
 - The agent follows the reference to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations -->
 - `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
 
+The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `aitk:toolkit-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `aitk claude init` for the seed docs and then `aitk:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
+
 Keep the `## Scripts` table in `.claude/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run that way. A project whose entry outgrew one file and split into `.claude/context/development/` keeps the table in `overview.md`, which is where the skill looks next. <!-- audit-ignore-citations -->
 
 ### From scaffold to first feature
@@ -76,6 +78,8 @@ Escalate only for real web apps. The `setup-init` skill reads `package.json` and
 
 Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
 
+A project the toolkit ships no stack for lands on `base` the same way, and the skill marks that resolution as a fallback in its preview rather than reporting it as a match. Configs, seeds, and gitignore entries land either way, and the JavaScript development dependencies, scripts, and hook activation land only where a `package.json` exists to carry them. A project outside that ecosystem declines at the preview and takes `aitk:setup-gov` for the governance layer alone, which is language-neutral.
+
 Run `aitk tooling list --json` and `aitk gov list --json` to see the current catalogs. Never hardcode stack names.
 
 ### Core domains and skips
@@ -174,7 +178,7 @@ cd <your-project>
 claude
 ```
 
-In the session, invoke `aitk:setup-init`. The skill detects no framework, resolves tooling to `base`, governance to `base`, snippets to `all`, and auto-enables `standards` if `docs/` exists. It previews the chain, then runs `aitk init`.
+In the session, invoke `aitk:setup-init`. The skill detects no framework, resolves tooling to `base`, governance to `base`, snippets to `all`, and auto-enables `standards` if `docs/` exists. The preview marks both stacks as fallbacks, since neither came from a match, then the chain runs `aitk init`.
 
 Ongoing: run `aitk sync --check .` to see what has drifted, then invoke `aitk:claude-seed-sync` for seed drift or `aitk sync .` for a catch-all refresh.
 

package/docs/visual-design-workflow.md

@@ -34,6 +34,7 @@ The `aitk:claude-design-extract` skill drafts the file, sourcing tokens from a p
 - `aitk:claude-design-extract` to draft `.claude/DESIGN.md`, from existing project signals or from requirements alone on day one
 - `aitk:claude-ui-test` for e2e test generation after UI changes
 - `aitk:claude-ux-audit` for UX gap detection on existing surfaces
+- `aitk:claude-ux-measure` for what a running surface costs to paint, read against published thresholds
 - Anthropic's `frontend-design` plugin optional for light visual steering
 
 ### When to pick

package/package.json

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

package/src/sandbox/expect.ts

@@ -220,15 +220,39 @@ function checkPaths(
   )
 }
 
+/**
+ * An entry carrying `*` is matched as a glob, which is what lets an arm forbid
+ * a file whose name a run derives rather than fixes. Pinning one spelling of a
+ * derived name passes vacuously against every other spelling, which reads as
+ * coverage the arm does not have. Returns the offending path so a failure names
+ * the file the run wrote rather than the pattern that caught it.
+ */
+function writtenUnder(pattern: string, sandboxDir: string): string | undefined {
+  if (!pattern.includes('*')) {
+    return existsSync(join(sandboxDir, pattern)) ? pattern : undefined
+  }
+
+  for (const match of new Bun.Glob(pattern).scanSync({
+    cwd: sandboxDir,
+    dot: true,
+  })) {
+    return match
+  }
+
+  return undefined
+}
+
 function checkAbsent(
   expectation: Expectation,
   sandboxDir: string,
 ): AssertionResult[] {
-  return expectation.absent.map((path) =>
-    existsSync(join(sandboxDir, path))
-      ? { ok: false, message: `should not exist: ${path}` }
-      : { ok: true, message: `absent: ${path}` },
-  )
+  return expectation.absent.map((path) => {
+    const written = writtenUnder(path, sandboxDir)
+
+    return written
+      ? { ok: false, message: `should not exist: ${written}` }
+      : { ok: true, message: `absent: ${path}` }
+  })
 }
 
 /**

package/src/tasks/archive.ts

@@ -9,12 +9,21 @@ const PLANS_DIR = join('.claude', 'plans')
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
- * hand-maintained ordering, and the pre-compaction session map. `validate`
- * reads the same list, so neither verb can count a sibling as a task the other
- * does not.
+ * hand-maintained ordering, and a handoff a session wrote before the file took
+ * one name per session. `validate` reads the same list, so neither verb can
+ * count a sibling as a task the other does not.
  */
 export const RESERVED_STEMS = ['index', 'priority', 'session'] as const
 
+/** The pre-compaction handoff takes one file per session, so its stems vary. */
+const SESSION_MAP_PREFIX = 'session-'
+
+export function isReservedStem(stem: string): boolean {
+  const reserved: readonly string[] = RESERVED_STEMS
+
+  return reserved.includes(stem) || stem.startsWith(SESSION_MAP_PREFIX)
+}
+
 /**
  * `bad-input` describes the command line rather than the board, which is the
  * split `record.ts` draws for the same reason. A caller naming two selectors
@@ -190,12 +199,11 @@ function isLivePlan(target: string, dir: string, root: string): boolean {
 
 export async function listTaskStems(dir: string): Promise<string[]> {
   const entries = await readdir(dir)
-  const reserved: readonly string[] = RESERVED_STEMS
 
   return entries
     .filter((entry) => entry.endsWith('.md'))
     .map((entry) => entry.slice(0, -'.md'.length))
-    .filter((stem) => !reserved.includes(stem))
+    .filter((stem) => !isReservedStem(stem))
     .sort()
 }
 

package/src/tasks/validate.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
-import { RESERVED_STEMS, tasksDir } from '@/tasks/archive'
+import { isReservedStem, tasksDir } from '@/tasks/archive'
 
 const ORDERING_FILE = 'priority.md'
 
@@ -204,12 +204,11 @@ export function readBoard(text: string): {
 
 async function listTaskStems(dir: string): Promise<string[]> {
   const entries = await readdir(dir)
-  const reserved: readonly string[] = RESERVED_STEMS
 
   return entries
     .filter((entry) => entry.endsWith('.md'))
     .map((entry) => entry.slice(0, -'.md'.length))
-    .filter((stem) => !reserved.includes(stem))
+    .filter((stem) => !isReservedStem(stem))
     .sort()
 }
 

package/standards/index.md

@@ -21,6 +21,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
+- [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard

package/standards/session.md

@@ -0,0 +1,106 @@
+---
+title: Session map reference
+description: Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+---
+
+# Session map reference
+
+Applies to `.claude/tasks/session-<slug>.md`. A session writes one before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them. It is rewritten whenever the session that owns it learns something the next session would otherwise re-derive, and it is optional: a project whose sessions never approach a compaction carries none.
+
+Any session writes one. The role a session holds decides which sections it adds on top of the core, never whether it may write at all.
+
+## Scope
+
+Governs the pre-compaction handoff at `.claude/tasks/session-<slug>.md`: its filename, its sections, what a writer puts in each, and how a reader picks one up.
+
+Does not govern:
+
+- The task board the file sits beside, its filenames, and its archiving: `tasks.md`
+- The transform from a branch name to the slug in the filename: `slug.md`
+- The role-specific sections a caller adds over the core, which belong to that caller
+- Which memories a session captures before writing, which is the capture surface's own subject
+
+## What a working session map looks like
+
+A session map works when the session reading it can act on the reasoning without asking the session that wrote it:
+
+- What is clean, what is running, and what is open right now?
+- Which mistake already made would this session repeat?
+- Which command, tool, or held instruction lies about the tree?
+- Where did each claim come from, so a reader can tell a read from a recall?
+
+A session map failing these is non-conforming even when it satisfies every shape rule below.
+
+## Filename and location
+
+- Write one file per session, named `session-<slug>.md`, where `<slug>` is the branch-derived slug
+- Fall back to `session-latest.md` when the branch resolves empty, since a handoff is scratch rather than a commit and a stop would lose the reasoning it exists to save
+- Resolve the containing folder at the main worktree root, never inside a linked worktree
+- Overwrite the file the writing session already owns. A stale entry read as current is worse than no handoff.
+- Never write into a file another session owns. One file per session is what keeps two sessions closing near each other from each writing the whole file, where the loser leaves no trace.
+
+## Frontmatter
+
+- `title` (required): `Session map`, so every handoff reads the same in a generated catalog
+- `description` (required): what the board cannot show, and the date the file was written
+
+## Sections
+
+Three sections form the core, in this order, and every session fills all three.
+
+- `## State`: what is clean, what is running, what is open, and any untracked file that needs committing
+- `## Mistakes worth not repeating`: what went wrong and the rule it yields
+- `## Standing cautions`: commands that lie, tools that measure the wrong tree, and anything unbacked
+
+Add a section only for content that fits none of the three and would otherwise be lost.
+
+## Writing one
+
+1. Capture what the session learned first, so the map cites what was written instead of restating the same lesson in prose.
+2. Run `aitk claude skills drift <the commit this session started from>` and record what it names under `## Standing cautions`. A skill body enters a session once and re-invoking the skill replays the held copy rather than the file, so the drift is worst at exactly this moment and a name here is a body the session has been following out of date. This step belongs to session length rather than to any role, so every writer runs it, and a refusal names the boundary of what the verb can read rather than a fault.
+3. Recover that commit from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. Nothing on the machine records it. A ref older than the oldest load over-reports, and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making.
+4. Write only what a compaction destroys and no other artifact already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a measurement folder holds its track.
+5. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
+6. Fill a section from reasoning the session actually holds. A session with no cross-feature picture that fills `## State` from what is already in git has written a summary of the tree, which the reader can produce faster than they can read it.
+
+Do not restate the board, and do not summarize the work that shipped, since version control already carries it.
+
+## Reading one back
+
+- Read the newest map in the folder, by modification time, and treat it as the previous session's scratch rather than as a source
+- Say nothing when no map exists. Absence is the common case, and a line reporting it every run is the noise that makes the present case unnoticeable.
+- Re-measure every count, size, and cost the map states, since each was true when written
+
+## Extending it
+
+- Carry every core section whatever else a role adds, and state in the surface that adds a section why the core cannot carry it
+- Let the adding surface fix where its own section sits, so a role can place one between core sections where that reads better. The core order holds among the core sections alone.
+- Keep a section out of the core when a session holding no such role would leave it unfilled. An unfilled section teaches a reader to skip the file.
+- Carry a resume instruction inside the map itself when the routing to that instruction is what a compaction takes. The map survives what the instruction was loaded from, so each reaches a reader the other cannot.
+
+## Template
+
+```markdown
+---
+title: Session map
+description: <what the board cannot show, and the date it was written>
+---
+
+# Session map
+
+<one line marking the file throwaway and naming the board as the real source>
+
+## State
+
+<what is clean, what is running, what is open, and any untracked file that needs committing>
+
+## Mistakes worth not repeating
+
+<what went wrong and the rule it yields>
+
+## Standing cautions
+
+<commands that lie, tools that measure the wrong tree, and anything unbacked>
+```
+
+A role-specific section is placed by the surface that adds it, so the skeleton above shows the core alone.

package/standards/tasks.md

@@ -21,6 +21,7 @@ Does not govern:
 - Phase-label format and which surfaces a label may appear on: `versioning.md`
 - Sequencing across versions and why the order is what it is: `roadmap.md`
 - Architectural reasoning that outlives a task: `architecture.md`
+- The pre-compaction handoff sitting in the folder, its filename and its sections: `session.md`
 - When a project opens a task at all, which is project policy rather than a shape rule
 
 ## Layout
@@ -29,17 +30,21 @@ Does not govern:
 .claude/tasks/
 ├── index.md              ← generated, never hand-edited
 ├── priority.md           ← hand-maintained execution order
-├── session.md            ← optional, what a compaction is about to destroy
+├── session-<slug>.md     ← optional, what a compaction is about to destroy
 ├── v09.0-sync-paths.md
 └── v13.0-toolkit-drift.md
 ```
 
 One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
 
-Three siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md` and `priority.md` are governed here. `session.md` is the pre-compaction handoff, written by `orchestrator-handoff` and read by `orchestrator-resume`, and it is optional: a project running no orchestrator carries no such file. Anything reading the folder as a task list skips all three, so a name outside the set is a task whatever it holds.
+Siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md` and `priority.md` are governed here. Every `session-` file is a pre-compaction handoff governed by `session.md`, and each is optional: a project whose sessions never approach a compaction carries none. Anything filtering the folder to tasks skips all of them, so a name outside the set is a task whatever it holds.
+
+The handoff takes one file per session for the reason a task does. A single shared path puts two sessions closing near each other on one file that neither can watch the other write, and the loser leaves no trace on a board with no history behind it.
 
 `index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
 
+The catalog is the one reader that filters nothing, so it carries a row per sibling alongside the tasks. That is what a folder catalog is for, and the handoffs are what make it worth stating: a board accumulates one row per session that ever wrote one, with nothing pruning them. Anything reading the catalog as the backlog therefore does its own filtering, and a reader that takes every row as a task reports the handoffs as queued work.
+
 The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
 
 ## Ordering