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

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/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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.94.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