@erclx/aitk 3.4.0 → 3.6.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -40,7 +40,7 @@ No surface carries cross-version sequencing, so report none. A row's `Waiting on
 
 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 a session map per `${CLAUDE_SKILL_DIR}/../../standards/session.md`, 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 write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It sends the generic half to `aitk:session-map`, which captures what the session learned and writes a session map per `${CLAUDE_SKILL_DIR}/../../standards/session.md`, then adds the decisions taken under delegated authority 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

@@ -3,9 +3,11 @@ title: Orchestrator handoff runbook
 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
 ---
 
-Write the pre-compaction handoff as orchestrator. Follow `${CLAUDE_SKILL_DIR}/../../standards/session.md` 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.
+Write the pre-compaction handoff as orchestrator. Invoke `aitk:session-map` for the generic half, which is the filename, the three core sections, the write procedure, the drift step and the ref it reads, 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. Run the capture step the core opens with, and tell `aitk:claude-memory-capture` that this session does not commit.
+Settle all three steps below before the door writes, so one write carries the core and the extension together. The door reports the map as written and knows nothing of this role, so its success line ends the generic half rather than this runbook, and a session that stops there ships a map missing both of the things this file exists to add.
+
+1. Tell the door this session does not commit, which is the caveat its capture step takes and passes to `aitk:claude-memory-capture`.
 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>`:
 
@@ -25,6 +27,6 @@ The requirement is a resume request to the orchestrator skill with that skill lo
 
 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.
+Step 1 varies the door rather than replacing it, which is why the door is invoked first and this runbook states only what differs. The generic half moved out whole, the drift step and its ref recovery with it, so nothing here restates a step the door already carries and the two cannot disagree.
 
-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.
+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.

package/claude/skills/decision-escalate/REQUIREMENT.md

@@ -15,14 +15,14 @@ A body written around a named tool fails a third way. A session on a surface car
 
 The opposite failure is the one that ships silently. A session that takes a preference decision itself produces work the operator did not ask for and never learns a choice was made, because nothing in the output says a fork was passed.
 
-`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has the toolkit's `snippets/decision-help.md` behind it, which installs into a project as `.claude/snippets/decision-help.md`, and the second had no surface at all.
+`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has the toolkit's `snippets/decision-help.md` behind it, which installs into a project as `.claude/snippets/decision-help.md`. The second branch now states how a question is shaped and where it is put, so this skill inherits both and adds only what a batch needs on top of one question.
 
 ## Must
 
 - Collect every open decision before asking any of them, so the operator sees the set rather than the first one
 - Put the whole batch in one turn, since a batch split across turns is the per-decision ask this skill exists to replace
-- Give each question two to four options, each carrying what it means and what it costs, with the recommendation ranked first and named as such
-- State the behavior first and the tool second, so the body runs on a chat surface carrying no structured question tool
+- Give each question a short axis header and two to four options, taking the shape of an option from `CLAUDE.md` rather than restating it
+- Test the surface rather than the project's instruction file when choosing where the batch goes, so a target whose `CLAUDE.md` predates the rule still reaches the tool and loses only the shape
 - Cap a batch at four questions and say how many are held, since a structured question tool takes four and an uncapped batch hides the overflow
 - Hold every escalated decision until it is answered, and continue only the work depending on none of them
 - Route a pick that changes a written artifact into that artifact under the standard owning it, rather than leaving it in the session

package/claude/skills/decision-escalate/SKILL.md

@@ -31,9 +31,7 @@ Drop anything the session can settle. What survives is the batch.
 
 ## Step 2: shape each question
 
-Each entry carries a short header naming the axis, the question itself, and two to four options. Give every option what it means and what it costs. Rank the recommendation first and say it is the recommendation.
-
-An option with no stated cost is not an option, since the operator picks it without knowing what the other one buys.
+Each entry carries a short header naming the axis, the question itself, and two to four options. `CLAUDE.md` states what an option carries and how the set is ranked, so follow it rather than a second copy here. The header is what a batch adds. An operator scanning four questions needs an axis on each to tell one from the next.
 
 Cap the batch at four. A structured question tool takes four, and a batch past that is a session asking to be redesigned rather than answered. When more than four are open, send the four blocking the most work and say in one line how many are held.
 
@@ -41,11 +39,11 @@ Cap the batch at four. A structured question tool takes four, and a batch past t
 
 Put every question in one turn. Never split the batch across turns and never ask the first while the rest stay unstated.
 
-When the session runs on a surface carrying a structured question tool, such as `AskUserQuestion` in Claude Code, send the whole batch through one call with one entry per decision. The tool renders the options and collects the picks together.
+Send the batch through a structured question tool wherever the session runs on one, and write the shape below where it does not. What a batch adds is that one call carries the whole set, with one entry per decision, so the operator answers them together instead of one per turn.
 
-Otherwise write the batch as a numbered list in one message, each question followed by its lettered options with the recommendation marked. The behavior is the same on either surface, and only the rendering changes.
+The test is the surface rather than the project's instruction file. A target scaffolded before the rule shipped still reaches the tool, and what it loses is the option shape `CLAUDE.md` states, which the example below carries instead.
 
-Batch shape:
+Batch shape on the fallback surface:
 
 ```plaintext
 <N> open decisions. <M> held.

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

@@ -0,0 +1,57 @@
+---
+name: session-map
+description: Why the write procedure needs a route any session can take, why the door carries the drift step and its ref recovery, and why it states none of the shape the standard already fixes
+---
+
+# Session map requirement
+
+## Gap
+
+Without this skill, the standard governing the pre-compaction handoff carries a complete numbered write procedure and nothing routes a session to it. The reading half already works, since the resume path opens the newest map and leads its report with it, so a file nobody is routed to write is read by a surface built to find it.
+
+The only routed writer belongs to the orchestrator role. It disables model invocation, asserts that role on invocation, and adds a section for decisions taken under delegated authority, so a plain feature session that reaches it receives a section it cannot fill and a review poll it does not run.
+
+The nearest description by wording writes a different artifact. Capture routes facts to a context entry and writes memory files, and a request naming the session and the moment matches it, so the map goes unwritten while a session believes it has handed off.
+
+The drift step is the one most specific to session length and the easiest to skip. It reads the commit the session started from, nothing on the machine records that commit, and a route that names the step without naming how to recover the ref ships an instruction nobody can follow.
+
+A step that reads a surface a project may not carry gets skipped on the reasoning that it has nothing to act on. A cold session run against a project with no `.claude/` tree skipped both the capture and the drift step and wrote its own rationale into the map, so the step the route exists to carry did not run on the first test from outside. The skip is worst where it looks most defensible, and a session that takes it quietly leaves a map indistinguishable from a conforming one.
+
+A capture fired the same way for every caller breaks the one caller the split leaves. An orchestrating session may write no tracked file, so its capture has to skip routing, and a route offering no way to say so leaves that reader running capture twice or routing facts the role forbids it to fold.
+
+A body that restates the sections, the frontmatter, or the numbered steps becomes a second source that drifts from the standard, which is the failure the split between the role writer and the core was made to remove rather than move.
+
+## Must
+
+- Write from any session whatever role it holds, without asserting one
+- Cite the standard for the filename, the frontmatter, the sections, the numbered procedure, and the citation rule rather than restating any of them
+- Run the drift step and state how to recover the ref it reads from how long the session has run
+- Record what the drift verb names, and read a refusal as the boundary of what the verb can read
+- Resolve the folder at the main worktree root, and write the file whole from the shell where the editing tools refuse that root
+- Fall back to the branchless filename on an empty slug rather than stopping
+- Leave model invocation enabled, so a session that has dropped its routing still reaches this by description
+- Take a caller's statement that the session does not commit and pass it to capture, so no fact this route fires is routed into a tracked file
+- Report the map alone, plus the line capture returns when a fact routed, since a fold left unreported is a fold nobody runs
+
+## Must not
+
+- Restate the standard's sections, frontmatter, or numbered steps
+- Skip a step by predicting what its skill or verb would have answered, rather than running it and recording what came back
+- Assert a role, or add a role's section to a map written by a session holding no such role
+- Fold the capture step's output into this skill's report
+- Take the worktree-local copy the editing tools offer in place of the main-root path
+- Summarize the board, the task files, or the work that shipped, each of which is carried by an artifact a compaction leaves standing
+
+## Guards
+
+- Not a git repository: stop, since the filename comes from the branch
+- Empty slug: fall back rather than stop, since the reasoning is worth more than the name
+- The drift verb refusing: record the boundary under standing cautions and keep writing
+
+## Out of scope
+
+- Reading a handoff back at the start of the next session: `session-resume`
+- Routing a session fact to the context entry that owns it, and writing what no entry owns to the memory folder: `claude-memory-capture`
+- The sections a role adds over the core three, which belong to that role's own surface. `claude-orchestrate` owns the orchestrator's and cites this route for the generic half.
+- Validating a written map against the standard, which no record kind covers, so a conforming shape rests on the standard being followed
+- Firing the write without being asked, which is a question about what the harness supports and is measured on its own track

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

@@ -0,0 +1,57 @@
+---
+name: session-map
+description: Writes the session map, the pre-compaction handoff at `.claude/tasks/session-<slug>.md`, from any session whatever role it holds, running the skill-drift step the write procedure opens with. Use when asked to "write the handoff", "write the session map", "save the session before it compacts", "we are about to compact", "hand off to the next session", or "leave a note for whoever picks this up". Do NOT use to route session facts to a context entry or the memory folder, which is `claude-memory-capture` and writes a different artifact, and do NOT use to read a handoff back, which is `session-resume`.
+---
+
+# Session map
+
+Write the pre-compaction handoff for the current session. `${CLAUDE_SKILL_DIR}/../../standards/session.md` fixes the filename, the frontmatter, the three core sections, the numbered write procedure, and the citation rule. Follow that document rather than this body, which states when the procedure runs and what it runs against and leaves the shape where it already lives.
+
+Any session writes one. Do not assert a role on invocation, and do not add a role's sections to a map written by a session holding no such role.
+
+Run every step rather than judging in advance that one has nothing to act on. The capture skill and the drift verb each answer for themselves, refusal included, and a refusal recorded is a result where a prediction of one is not. A project carrying none of the scaffolding either step reads is the case this fires on, and it is the case where skipping looks most defensible.
+
+## Guards
+
+- If `git rev-parse --git-dir` does not resolve, stop: `❌ Not a git repository. A session map takes its filename from the branch.`
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. An empty result falls back to `latest` rather than stopping, since a handoff is scratch and a stop loses the reasoning the file exists to save.
+- Resolve the containing folder at the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The guard above already stopped where that read has no repository to answer from, so it takes no fallback.
+
+## Step 1: run the capture the procedure opens with
+
+Item 1 of `## Writing one` is a capture. Invoke `aitk:claude-memory-capture` and let it return before writing, so the map cites what was written instead of restating the same lesson in prose.
+
+Pass on the caveat a caller states about committing. A caller that does not commit says so, and capture then skips routing and writes memory files alone, since a routed fact lands in a context entry and that is a tracked file. A caller stating nothing leaves capture to decide for itself, which is the ordinary run.
+
+Carry through the line capture returns when a fact routed, so the session knows a fold is still owed. Report nothing else about what it wrote. The map is this skill's output.
+
+## Step 2: recover the commit the drift step reads
+
+Item 2 runs `aitk claude skills drift <ref>` against the commit this session started from, and nothing on the machine records that commit. Estimate how long the session has run, round the duration up, and read the ref item 3 recovers:
+
+```bash
+git log -1 --format=%H --before='<duration> ago'
+```
+
+Round up rather than down. A ref older than the oldest load over-reports, and confirming a name it raises costs one read of that body, so the generous end is the safe one.
+
+Record what the verb names under `## Standing cautions`. A refusal is the boundary of what the verb can read rather than a fault, since it answers where the working directory carries `claude/skills/` with history behind it and refuses in a project consuming the plugin from a cache. Record the boundary the verb reported and keep writing, rather than the one it looked likely to report.
+
+## Step 3: write the map
+
+Follow items 4 through 6. Write only what a compaction destroys and no other artifact already carries, and cite a commit, a task, or a file and line for every claim.
+
+The file sits at the main worktree root, which the file-editing tools refuse from inside a linked worktree while offering a copy under that worktree instead. Take neither the refusal nor the copy. The map is written whole every time, so send it out as one plain shell command carrying a heredoc.
+
+## Step 4: extend it only where a role is held
+
+`## Extending it` governs a section added over the core three. Add one only when this session holds the role and the surface owning that role states the section, since a section the writer cannot fill teaches its reader to skip the file. A session holding no role writes the core three and stops.
+
+## Output
+
+```plaintext
+✅ Session map written: .claude/tasks/session-<slug>.md
+<what the drift verb named, or the boundary it refused at>
+```
+
+Emit the path from the project root. The `## Output` section of the project's instruction file sets the form it takes.

package/docs/ai-workflow.md

@@ -250,6 +250,7 @@ This section is the corpus the coverage claim is measured against: every name `a
 | ------------------------- | ------------------------------------------------------------------------------ |
 | `aitk:claude-orchestrate` | To assert the control session that owns the queue and reviews each worker's PR |
 | `aitk:session-resume`     | At the start of a session, to pick up what a previous one left                 |
+| `aitk:session-map`        | At the close of a session, to write the handoff a compaction would destroy     |
 
 ### Keep the project current with the toolkit
 

package/package.json

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

package/standards/session.md

@@ -56,9 +56,11 @@ Add a section only for content that fits none of the three and would otherwise b
 
 ## Writing one
 
+The `session-map` skill is the invocable route onto this procedure and holds no role, so a session reaching for a handoff without knowing this document exists still lands here. A session that arrives at this document directly follows the steps below unchanged.
+
 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 does not re-read 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. Recording a name is not acting on it, and the verb misses a body this session edited and has not committed. 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.
+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. An empty result means no commit predates the window, so take the oldest commit the history holds and say which of the two the ref came from.
 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.
@@ -76,6 +78,7 @@ Do not restate the board, and do not summarize the work that shipped, since vers
 - 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.
+- Cite the route onto `## Writing one` rather than restating the procedure, so the extension is the only thing the adding surface carries and the two cannot fall out of step
 - 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

package/tooling/claude/seeds/CLAUDE.md

@@ -17,6 +17,9 @@
 
 - Flag concerns or alternatives when a proposed change has tradeoffs worth discussing
 - When facing a judgment call with 2-3 reasonable options mid-flow, pick one and state the tradeoff in one sentence. Enumerate options only when the user's preference is the deciding factor.
+- Put a call the user's preference decides through the structured question surface, such as `AskUserQuestion` in Claude Code, and fall back to a numbered list in one message where none exists. Rank the recommendation first and mark it, order the rest behind it, and give each option its cost, since an option with no stated cost is picked blind.
+- Author the real choices only. A structured surface appends its own trailing escapes for a free-text answer and for reopening the question as conversation, so never write either as an option. On the numbered-list fallback, say that answering outside the list is fine.
+- Answer from the artifact when one already put the question in writing with a suggestion, rather than re-asking it. A blank `- Answer:` slot in a plan accepts the `- Suggested:` line above it, per the plan standard, which your toolkit resolves by name.
 - Match edit scope to the request. Ship minimal v1 and queue extensions as follow-ups.
 - On simplification requests, edit only what the user named
 - Do not add features the user did not ask for