@erclx/aitk 3.26.0 → 3.27.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.26.0",
+  "version": "3.27.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -67,12 +67,16 @@ The session also records nothing of what it learns. Both other callers of memory
 - Write each re-test into the row and its measurement into that task's Findings, since a result reported in chat is gone at the next compaction and the next pass measures the same thing
 - Plan a row the re-test clears, since a cleared row carrying no plan is one the next pass looks at again
 - Split a task whose file set collides with every other by construction, rather than re-measuring a scoping defect that reads as a blocker
+- Check a candidate branch is unclaimed by an existing worktree or a live session before dispatching a background worker for it, since the measured failure this closes is a worker colliding with someone else's work already sitting in the row
+- Cap concurrent self-dispatched workers at three, counted by a session name no human-launched worker carries, since the evidence behind self-dispatch is one task shipped once
+- Report each self-dispatch and the row it fired against loudly enough to follow, since a person no longer watches the launch step happen
+- Stop dispatching once `## Run now` is empty or every row in it reads claimed, rather than waking again to fire on a board nobody is clearing
 
 ## Must not
 
 - Implement a feature or edit any tracked file from this session, at any size, since the ban offers no proportionality exception
 - Merge. Recommend merge or changes and leave the gate to the human.
-- Spawn worker sessions with agents, since every build is meant to be an independent steerable stream
+- Spawn a worker with the Agent tool, since an in-process subagent shares this session's context and cannot be steered or reached independently. A dispatched `claude --bg` process is not this: it is a separate session with its own worktree and its own PR, gated by the collision check and the worker cap.
 - Hand a worker anything but a plan, because scope lives there
 - Run a second orchestrator against the same board
 - Promote a task to fill the queue when nothing qualifies. A thin queue is a real answer.
@@ -88,10 +92,12 @@ The session also records nothing of what it learns. Both other callers of memory
 - Cross-version sequencing asked for: say no surface carries it, rather than asserting an active version the tree does not state
 - This body dropped from a long session approaching a compaction: name the re-invocation and the runbook paths, since the routing lives in the body and a user-invoked skill routes nothing once it is gone
 - Blocker only an operator can clear: record the row as untestable this pass and name the action owed, rather than re-measuring what no session can move
+- Collision check refuses, with no session registry or no repository resolved: treat the candidate as unverified and fall back to the human-launch line, rather than reading a check that could not run as a clear one
+- Worker cap already at three: stop dispatching for the pass and leave the row ready, rather than queueing past it
 
 ## Out of scope
 
 - Writing the plan itself, which `claude-feature` owns and this session runs rather than reimplements
 - Reviewing a worker's pull request, which `claude-pr-review` owns
-- Entering the worktree a build runs in, which the human opens
+- Entering the worktree a build runs in, which the worker opens for itself whether a human launched it or this session dispatched it
 - The operating model this enacts, which the toolkit's own docs hold

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

@@ -10,7 +10,8 @@ This session is the orchestrator: the one warm session that holds the
 cross-feature picture. It plans and reviews.
 
 It does not build, and it does not merge. Building happens in cold worker
-sessions the human launches. Merging is the human's gate.
+sessions, dispatched by this skill once the collision check clears or launched
+by the human when it does not. Merging is the human's gate.
 
 This skill holds the framing, the board procedure, and the dispatch. Every step
 that builds something runs an existing skill. The queue rules below decide which
@@ -101,7 +102,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 1. Plan the next feature. Run `claude-feature` here, with the cross-feature context, to write a plan to `.claude/plans/`. Planning stays in this warm session so the plan front-loads reasoning a cold worker would otherwise re-derive. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
 2. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
 3. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
-4. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
+4. Hand off. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it: check the branch is unclaimed, check the worker cap, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the check refuses, the cap is reached, or the row fails Parallelism against something already in flight.
 5. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
    - Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. That runbook holds the routing, and a summary of it here is a second source that drifts from it.
 6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `claude-address-review`, rather than waiting for a person to relay it. Re-review when the answer lands, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
@@ -126,7 +127,8 @@ Stamp the block with the commit this session read the tree at, which the same se
 - Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes: two task files land minutes apart under different labels for the same work, one session archives a task mid-sweep in the other, and each archives a plan the other had retargeted. An Owner column does not fix this, since neither session can read the other's rows.
 - Do not implement features in this session. Hand the plan to a worker.
 - Do not merge. Recommend merge or changes. The human merges.
-- Do not spawn worker sessions with agents. The human launches each worktree so every build is an independent, steerable stream with its own PR. The handback dispatch in step 6 reaches a session the human already launched, so it leaves this boundary where it is.
+- Do not spawn a worker with the Agent tool. An in-process subagent shares this session's context and cannot be steered or reached independently, which breaks the property this boundary protects rather than the mechanism it names. The dispatch in `orchestrator-dispatch.md` is a separate `claude --bg` process with its own worktree and its own PR, so it preserves that property instead.
+- Dispatch a background worker only once the collision check in `orchestrator-dispatch.md` clears and the worker cap still has room. Colliding with an existing worktree or session, or exceeding the cap, is what the check and the cap exist to catch, not a judgment call this session makes case by case.
 - Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
 - Do not hand a worker anything but a plan, since scope lives there. A plan carries exact diffs only when they are already known, otherwise it states the scope and the open questions and lets the worker write the diff.
 

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

@@ -0,0 +1,44 @@
+---
+title: Orchestrator dispatch runbook
+description: The collision check before a self-dispatch, the worker cap, the launch command, and the loop's stopping condition
+---
+
+Run this at loop step 4, for a `## Run now` row whose plan is verified and whose file set has already cleared the Parallelism test against every track in flight, in place of handing the worktree to a human.
+
+## Derive the candidate
+
+Resolve `<slug>` from the row's plan the way `claude-worktree` Step 2 resolves a plan-matched name, per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Resolve `<type>` off that plan's `## Summary` and `**Files to touch:**` lines, per `${CLAUDE_SKILL_DIR}/../../standards/branch.md`, defaulting to `feat` when the lines settle nothing. The candidate branch is `<type>/<slug>`.
+
+## Check the branch is unclaimed
+
+Run `aitk sessions list --branch <type>/<slug> --json` and read `claimed` off the record.
+
+- `claimed: true`: the row is not free. Report what holds it, `worktree` when it names a path and `sessions` when it carries a row, and move to the next candidate rather than colliding.
+- `claimed: false` and `sessionsReadable: true`: proceed to the cap check.
+- `claimed: false` and `sessionsReadable: false`, or the command refuses, or the record carries no `claimed` key (`reason` reads `no-registry` or `no-repository`): treat the candidate as unverified rather than clear. Report the refusal and fall back to the human-launch line below. Dispatching on a check that could not be read reproduces the exact collision this exists to prevent.
+
+Reading `claimed` off the record is what keeps this a check rather than a rule a session can talk itself out of. The field is already the composed answer across the worktree listing and the live session listing, so nothing here re-derives the OR.
+
+## Check the worker cap
+
+Run `aitk sessions list --json` with no `--branch`, then count entries whose `name` starts with `orchestrator-` and whose `repository` matches this run's own (`git rev-parse --path-format=absolute --git-common-dir`). An unscoped listing spans every repository on the machine, so the repository match is what keeps a busy sibling project from binding this one's cap. Every dispatch below names its session that way for exactly this count, so a worker the human launched by hand carries no such name and is never counted against it.
+
+Three already out: report the cap and stop dispatching for this pass, leaving the row ready for the next one. The cap binds the self-dispatch path alone, since the evidence behind it is one task shipped once and the operator's own launches stay uncapped by count.
+
+## Dispatch
+
+```bash
+claude --bg -n "orchestrator-<slug>" "/aitk:claude-autoship .claude/tasks/<task-file>.md"
+```
+
+`claude-autoship`'s own Step 0 enters the worktree, so this session never does. `--bg, --background` starts the session as a background agent and returns immediately, and `-n, --name` sets the display name `aitk sessions list` reads back for the worker cap.
+
+Report the dispatch as loudly as the human-launch line it replaces: name the branch, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
+
+## Fall back to the human
+
+Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the collision check refused, the cap is reached, or the row's file set failed the Parallelism test against something already out.
+
+## Stop the loop
+
+Wrapped in `/loop`, re-run the check against `## Run now` on each wake. Stop rather than firing again once the group is empty or every row in it reads `claimed: true`. Report that once, on the wake that finds it, and let the loop end rather than continuing to poll a board nobody is clearing. `orchestrator-poll.md` already carries this reasoning for the review trigger, and it binds a dispatcher the same way.

package/docs/agents/sessions.md

@@ -34,6 +34,16 @@ A bare run reports every repository and carries a `repository` field on each row
 
 The match can return more than one session. Read the count rather than the first row, since nothing stops two sessions holding one branch, and a caller that treats the result as singular picks among candidates without knowing it.
 
+## Whether a branch is already claimed
+
+With `--branch`, the JSON record also carries `worktree` (the path of any worktree already checked out to it, or `null`) and `claimed` (`true` when either a worktree or a live session already holds the branch).
+
+Read `claimed` rather than composing the two fields by hand. A worktree can outlive the session that made it, and a session can hold a branch before a worktree exists for it, so either field alone can miss a real claim. A dispatcher deciding whether it is safe to start a build against a branch reads this one field instead of re-deriving the OR itself.
+
+`worktree` and `claimed` are `null` on a bare run with no `--branch`, since neither question has a branch to answer about. A refusal (`no-registry` or `no-repository`) carries neither key at all, which a caller should read as unverified rather than as clear.
+
+`sessionsReadable` is `false` when the session roster could not be read, which leaves `claimed` covering the worktree half alone. A `false` here is a report that ran short of evidence, not a report that the branch is clear, so a caller reads it as unverified alongside `claimed` rather than trusting `claimed` on its own.
+
 ## Why the verb exists
 
 A session listing reports a name, a kind, a status, and how long each session has been running. None of those names a branch. Resolving a branch to a session therefore meant ordering the roster by start time and matching it against the order the worktrees were created, which is an inference that fails whenever two sessions start inside the same minute.

package/docs/operating-model.md

@@ -37,7 +37,7 @@ and no later session recovers that vantage.
 One feature travels this path end to end.
 
 1. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
-2. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The worker builds, self-checks, opens a PR, and stops at the PR boundary.
+2. Orchestrator checks the branch is unclaimed and the worker cap has room, then dispatches a background worker with `claude --bg` against the plan. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the check refuses, the cap is reached, or the plan collides with a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
 3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
 4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `aitk sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
 5. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. Repeat from step 4 until a pass closes the review.

package/governance/rules/claude/510-context.md

@@ -10,7 +10,6 @@ paths:
 
 - Before non-trivial work in a domain, read its `.claude/context/<domain>.md` entry. Use `.claude/context/index.md` to find it.
 - Leave the entry conforming when work in its domain changes what it describes.
-- Rewrite the decision a change supersedes rather than appending a second one narrating the transition.
 
 ## Narration pronouns
 

package/governance/rules/claude/520-wireframes.md

@@ -6,14 +6,6 @@ paths:
 
 # Wireframe standards
 
-## Layout and intent
-
-- Draw each surface as an ASCII block inside a `plaintext` fence, one fence per distinct layout.
-- Label a region with its role. Never label one with a class name, a token name, or a computed value.
-- Carry on-screen copy verbatim, and mark copy the surface templates.
-- State interaction intent, never the mechanism behind it. Send algorithms, handlers, and thresholds to a `.claude/context/` entry.
-- Update a surface's wireframe in the same pull request that changes its layout or its interaction.
-
 ## Authority
 
 - Follow the wireframes standard for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `.claude/context/`. It is the single source. Read it with `aitk standards wireframes`.

package/governance/rules/claude/530-requirements.md

@@ -6,14 +6,6 @@ paths:
 
 # Requirements standards
 
-## Scope and non-goals
-
-- State a goal as a user-facing outcome, never as the implementation delivering it.
-- Record explicit non-goals. Mark a deferred item `(deferred)`.
-- Leave the MVP list as written once its features ship. Do not renumber it, extend it, or annotate an entry with status.
-- Add later scope as a new section rather than as an extension of the MVP list.
-- Drop a section rather than pad it. Include `## Distribution` only when the project ships outside its own repository.
-
 ## Authority
 
 - Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source. Read it with `aitk standards requirements`.

package/governance/rules/claude/540-architecture.md

@@ -6,16 +6,6 @@ paths:
 
 # Architecture standards
 
-## Decisions
-
-- Give each decision its own H3 under `## Key technical decisions`, naming what it chose and the alternative it passed over.
-- Keep line-by-line function behavior and full type definitions out.
-
-## Verification anchors
-
-- Close a decision citing a measured number with `Measured at <short-sha> on <YYYY-MM-DD>.` Leave a decision citing none unanchored.
-- Refresh that anchor whenever the number is re-read, whether or not it moved.
-
 ## Authority
 
 - Follow the architecture standard for the overview, named decision entries, and risks. It is the single source. Read it with `aitk standards architecture`.

package/governance/rules/claude/550-design.md

@@ -6,14 +6,6 @@ paths:
 
 # Design standards
 
-## Tokens
-
-- Describe a token as intent rather than as a computed value.
-- Keep CSS classes, component filenames, and prop names out.
-- Carry a token system as a table, one row per token, and a component rule as a short bullet.
-- Keep the token table headers verbatim.
-- Record a non-obvious omission, such as no motion or no custom icons.
-
 ## Authority
 
 - Follow the design standard for visual intent, the token tables, and the render contract. It is the single source. Read it with `aitk standards design`.

package/governance/rules/claude/555-tasks.md

@@ -6,14 +6,6 @@ paths:
 
 # Tasks standards
 
-## What a task carries
-
-- Name where the task came from, through a `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` line under the title.
-- Size the outcomes so one pull request closes all of them. Split the task before handing it off.
-- Use `## Outcomes` and `## Findings` and add no third heading. Note status inline on an outcome.
-- Keep class names, file paths, function names, and prop names out of every entry and title.
-- Never delete a task file. A shipped task moves to the archive under its own name.
-
 ## Authority
 
 - Follow the tasks standard for filenames, frontmatter, what belongs, and the task file format. It is the single source. Read it with `aitk standards tasks`.

package/governance/rules/claude/556-groundwork.md

@@ -6,15 +6,6 @@ paths:
 
 # Groundwork standards
 
-## Folder name
-
-- Name a new track `.claude/groundwork/<nn>-<slug>/`, a two-digit zero-padded ordinal followed by a kebab-case slug. Take the ordinal from the highest one already present across both `.claude/groundwork/` and `.claude/intake/`, incremented, or `01` when neither folder holds an entry. Never renumber an existing folder.
-
-## Measuring and closing
-
-- Never carry a figure from an earlier session without re-measuring it. Mark an inference as an inference.
-- Never close a track while an open question quietly fails an outcome. Resolve it, or record it as knowingly accepted.
-
 ## Authority
 
 - Follow the groundwork standard for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source. Read it with `aitk standards groundwork`.

package/governance/rules/claude/557-intake.md

@@ -6,15 +6,6 @@ paths:
 
 # Intake standards
 
-## Folder name
-
-- Name a new dump `.claude/intake/<nn>-<slug>/`, a two-digit zero-padded ordinal followed by a kebab-case slug. Take the ordinal from the highest one already present across both `.claude/intake/` and `.claude/groundwork/`, incremented, or `01` when neither folder holds an entry. Never renumber an existing folder.
-
-## The answer contract
-
-- Never fill a `You:` slot and never infer a disposition from an empty one. Empty means unread, never agreement.
-- Report unread items by count on a resume pass. Do not decide one.
-
 ## Authority
 
 - Follow the intake standard for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source. Read it with `aitk standards intake`.

package/governance/rules/claude/559-memory.md

@@ -6,15 +6,6 @@ paths:
 
 # Memory standards
 
-## Routing
-
-- Write no memory entry for a fact a per-domain context entry already owns.
-
-## The pen
-
-- Never delete a memory entry. Retire one by moving it to an archive under its own name, since the folder is gitignored and a wrong call has no undo.
-- Never hand-edit `.claude/memory/index.md`. A hook regenerates it from sibling frontmatter.
-
 ## Authority
 
 - Follow the memory standard for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source. Read it with `aitk standards memory`.

package/governance/rules/claude/560-diagrams.md

@@ -16,4 +16,3 @@ paths:
 
 - Write a new diagram to `.claude/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
 - Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it
-- Refresh only the entries whose source signal moved. Do not rewrite the folder wholesale.

package/governance/rules/claude/561-teach.md

@@ -6,16 +6,8 @@ paths:
 
 # Teach standards
 
-## What a workspace keeps
-
-- Never renumber an existing folder, lesson, or record. A later reader cites it by the name it opened under.
-- Write every success line as a task the learner can be asked to perform, never as something they will understand.
-- Keep a reference page free of the learner. A page carrying second person or a quiz belongs under `lessons/`.
-- Record the wrong answer a learner gave, never a count of what they missed.
-- Date the workspace once, in the `MISSION.md` frontmatter. Never repeat the date in the body of any file.
-
 ## Authority
 
 - Follow the teach standard for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source. Read it with `aitk standards teach`.
-- Read `references/glossary.md` inside the `claude-teach` skill for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it rather than invoking the skill, which resumes a workspace and runs lessons.
+- Read `references/glossary.md` inside the `aitk:claude-teach` skill for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it rather than invoking the skill, which resumes a workspace and runs lessons.
 - Report it rather than proceeding silently when that file does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.

package/governance/rules/claude/562-session.md

@@ -9,10 +9,6 @@ paths:
 ## What a handoff carries
 
 - Follow this rule rather than `555-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
-- Never write into a file another session owns. Overwrite only the file the writing session already wrote.
-- Resolve the containing folder at the main worktree root, never inside a linked worktree.
-- Write only what a compaction destroys. Do not restate the board and do not summarize what shipped.
-- Cite a commit, a task, or a file and line for every claim, so a reader can tell a read from a recall.
 
 ## Authority
 

package/governance/rules/claude/570-skill.md

@@ -11,9 +11,8 @@ paths:
 
 ## Before editing
 
-- Read the skill's sibling `REQUIREMENT.md` when one exists. If the change closes no gap it states, change the requirement first or drop the change.
-- Confirm `create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
-- Report it rather than proceeding silently when `create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
+- Confirm `aitk:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `aitk:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
+- Report it rather than proceeding silently when `aitk:create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
 
 ## After editing
 

package/governance/rules/claude/580-readme.md

@@ -6,14 +6,6 @@ paths:
 
 # README standards
 
-## Audience and voice
-
-- Write a repository-root README for someone deciding whether to commit to the project. A nested README keeps the reference voice.
-- Address the reader in second person.
-- Ground a claim in a command, a number, or a named constraint rather than an adjective.
-- Name what the project does not do.
-- Link out to full API documentation, license text, contribution guidelines, and troubleshooting rather than carrying them.
-
 ## Authority
 
 - Follow the readme standard for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source. Read it with `aitk standards readme`.

package/governance/rules/claude/590-rule-authoring.md

@@ -6,19 +6,6 @@ paths:
 
 # Rule authoring standards
 
-## Numbering
-
-- Name a rule `.claude/rules/<subdirectory>/<n>-<slug>.md`. Give every rule a numeric prefix and keep the slug to one to three kebab words.
-- Treat `000-899` as reserved for a rule set that ships to targets, `000-599` across the shared subdirectories and `600-899` held for ones it has not added.
-- Number a rule the project authored itself in `900-999` and write it at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`.
-- Do not take a reserved number for a project-authored rule because nothing installed holds it today. A later release can ship into it.
-
-## Body
-
-- State one directive per bullet in imperative voice. Do not explain the reasoning behind a rule.
-- Cut a rule that resists crisp one-line phrasing.
-- Do not restate a rule a sibling rule or `CLAUDE.md` already owns. Point once.
-
 ## Authority
 
 - Follow the rule-authoring standard for rule frontmatter, body shape, and voice. It is the single source. Read it with `aitk standards rule`.

package/governance/rules/claude/591-standard-authoring.md

@@ -7,14 +7,6 @@ paths:
 
 # Standard authoring standards
 
-## The scope statement
-
-- Govern one document type per standard, or one attribute across every document.
-- Open with a `## Scope` section naming what the standard governs and a `Does not govern:` list, placed above the shape rules.
-- Put the governed path in backticks in the first sentence, anchored deep enough to resolve from a project root. Keep an attribute standard's first sentence free of backticks and say in it that it governs an attribute.
-- Give each `Does not govern:` entry an excluded concern and the owner it goes to. Cut an entry naming no owner.
-- Declare a yield, an exemption, or a handoff from both sides of the boundary.
-
 ## Authority
 
 - Follow the standard-authoring standard for a standard's frontmatter, shape, scope, and success criterion. It is the single source. Read it with `aitk standards standard`.

package/governance/rules/core/045-memory.md

@@ -7,6 +7,6 @@ description: Keep memory writes scoped to .claude/memory/ and out of context-own
 ## Writing memory
 
 - Write all memory files to `.claude/memory/`, not `~/.claude/projects/`
-- A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `claude-memory-capture` routes it there and `claude-docs` folds it in. Memory keeps only what no context entry owns.
+- A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `aitk:claude-memory-capture` routes it there and `aitk:claude-docs` folds it in. Memory keeps only what no context entry owns. Report it rather than proceeding silently when either skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.
 - Never delete a memory entry. Retire one by moving it to `.claude/.tmp/memory-archive/`. A bulk retire runs through the shell, where no file edit fires a path-scoped rule, and the folder is gitignored with nothing to recover from.
-- Follow the memory standard, which your toolkit resolves by name, for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Check every entry in the pen against that standard and fix what breaks it, since nothing keeps the folder conforming on its own.
+- Follow the memory standard for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Read it with `aitk standards memory`. Check every entry in the pen against that standard and fix what breaks it, since nothing keeps the folder conforming on its own.

package/governance/rules/lang/120-bash.md

@@ -8,9 +8,10 @@ paths:
 
 ## Skill routing
 
-- Use `bash-script` for an interactive or human-facing script: prompts, a visual timeline UI, framed terminal output.
-- Use `cli-script` for a non-interactive script: automation, CI, cron, a pipeline helper, or anything run by an agent rather than watched by a person.
+- Use `aitk:bash-script` for an interactive or human-facing script: prompts, a visual timeline UI, framed terminal output.
+- Use `aitk:cli-script` for a non-interactive script: automation, CI, cron, a pipeline helper, or anything run by an agent rather than watched by a person.
 - Load the matched skill's own reference templates rather than hand-rolling interactivity or logging patterns outside them.
+- Report it rather than proceeding silently when the matched skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.
 
 ## Lint gate
 

package/package.json

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

package/src/commands/sessions.ts

@@ -1,4 +1,5 @@
 import type { Command } from 'commander'
+import { checkClaim, type ClaimReport } from '@/sessions/claim'
 import {
   repositoryOf,
   type ResolvedSession,
@@ -58,6 +59,18 @@ export function register(program: Command): void {
         'A bare run reports every repository and carries the repository field,',
         'so a caller filtering by hand has something that identifies one.',
         '',
+        'With --branch, the JSON also carries "worktree" (the path of any',
+        'worktree already checked out to it, or null) and "claimed" (true when',
+        'either a worktree or a live session already holds it). A dispatcher',
+        'reads "claimed" rather than composing the two fields itself, since',
+        'either one alone can miss a real claim: a worktree can outlive the',
+        'session that made it, and a session can hold a branch before a',
+        'worktree exists for it.',
+        '',
+        '"sessionsReadable" is false when the session roster could not be read,',
+        'which leaves "claimed" covering the worktree half alone. Treat that',
+        'case as unverified rather than as a clean "false".',
+        '',
         'The match can return more than one session. Read the count rather than',
         'the first row, since two sessions can hold one branch.',
         '',
@@ -132,9 +145,17 @@ async function runList(opts: ListCommandOptions): Promise<number> {
       )
     : report.sessions
 
+  const claim = opts.branch
+    ? await checkClaim(opts.branch, {
+        cwd: process.cwd(),
+        resolve: async () => report,
+      })
+    : null
+
   intro('aitk sessions list')
   reportConfidence(report)
   reportSessions(shown, opts.branch, repository)
+  if (claim) reportClaim(claim)
   outro()
 
   if (opts.json) {
@@ -144,6 +165,9 @@ async function runList(opts: ListCommandOptions): Promise<number> {
         confidence: report.confidence,
         branch: opts.branch ?? null,
         repository,
+        worktree: claim?.worktree ?? null,
+        claimed: claim?.claimed ?? null,
+        sessionsReadable: claim?.sessionsReadable ?? null,
         sessions: shown,
       })}\n`,
     )
@@ -229,3 +253,19 @@ function reportSessions(
       .join('\n'),
   )
 }
+
+function reportClaim(claim: ClaimReport): void {
+  logStep('Claim')
+
+  if (claim.worktree) {
+    logInfo(`Worktree: ${claim.worktree}`)
+  }
+
+  logInfo(claim.claimed ? 'Claimed.' : 'Unclaimed.')
+
+  if (!claim.sessionsReadable) {
+    logWarn(
+      'The session roster could not be read, so this reads the worktree listing alone. Treat the session half as unverified rather than clear.',
+    )
+  }
+}

package/src/sessions/claim.ts

@@ -0,0 +1,59 @@
+import {
+  repositoryOf,
+  resolveSessions,
+  type ResolvedSession,
+  type SessionReport,
+} from '@/sessions/resolve'
+import { listWorktrees, type WorktreeEntry } from '@/worktree'
+
+export interface ClaimReport {
+  readonly claimed: boolean
+  readonly worktree: string | null
+  readonly sessions: readonly ResolvedSession[]
+  /** False when the session roster could not be read, so `claimed` covers the worktree half alone and cannot be trusted as a clean "unclaimed". */
+  readonly sessionsReadable: boolean
+}
+
+export interface ClaimOptions {
+  readonly cwd?: string
+  readonly resolve?: () => Promise<SessionReport>
+  readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+}
+
+/**
+ * Answers whether a branch is already claimed, composing the two readings
+ * neither surface can answer alone: a worktree can outlive the session that
+ * made it, and a session can hold a branch before a worktree exists for it.
+ */
+export async function checkClaim(
+  branch: string,
+  opts: ClaimOptions = {},
+): Promise<ClaimReport> {
+  const cwd = opts.cwd ?? process.cwd()
+  const resolve = opts.resolve ?? resolveSessions
+  const listAll = opts.listWorktrees ?? listWorktrees
+
+  const [repository, worktrees, report] = await Promise.all([
+    repositoryOf(cwd),
+    listAll(cwd),
+    resolve(),
+  ])
+
+  const worktree =
+    worktrees.find((entry) => entry.branch === branch)?.path ?? null
+
+  const sessions =
+    report.kind === 'resolved'
+      ? report.sessions.filter(
+          (session) =>
+            session.branch === branch && session.repository === repository,
+        )
+      : []
+
+  return {
+    claimed: worktree !== null || sessions.length > 0,
+    worktree,
+    sessions,
+    sessionsReadable: report.kind === 'resolved',
+  }
+}

package/src/worktree.ts

@@ -37,3 +37,46 @@ export async function mainWorktreeRoot(): Promise<string> {
 
   return line ? line.slice('worktree '.length).trim() : process.cwd()
 }
+
+export interface WorktreeEntry {
+  readonly path: string
+  readonly branch: string | null
+}
+
+/**
+ * Parses `git worktree list --porcelain`, which emits one block per worktree
+ * separated by a blank line. A detached worktree carries no `branch` line,
+ * reported here as `null` rather than a guessed name.
+ */
+export async function listWorktrees(
+  cwd: string = process.cwd(),
+): Promise<readonly WorktreeEntry[]> {
+  const result = await $`git -C ${cwd} worktree list --porcelain`
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return []
+
+  const entries: WorktreeEntry[] = []
+  let path: string | undefined
+  let branch: string | null = null
+
+  for (const line of result.stdout.toString().split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (path !== undefined) entries.push({ path, branch })
+      path = line.slice('worktree '.length).trim()
+      branch = null
+      continue
+    }
+
+    if (line.startsWith('branch ')) {
+      const ref = line.slice('branch '.length).trim()
+      branch = ref.startsWith('refs/heads/')
+        ? ref.slice('refs/heads/'.length)
+        : ref
+    }
+  }
+
+  if (path !== undefined) entries.push({ path, branch })
+
+  return entries
+}

package/standards/markdown.md

@@ -13,7 +13,7 @@ Governs what a check can decide about a markdown file: headings, paragraph and l
 
 The two frontmatter fields it reaches are `title` and `description`. They are named here rather than in the statement above, since a backticked token in a scope statement's first sentence is published as the standard's jurisdiction.
 
-The split with the voice guidance is what reads the rule rather than what the rule covers. Every ban below ships as data `aitk markdown audit` and the installed audit hook both read, so a violation is measured on every run. Cadence, rhythm, and information density are judgments a reader settles, and those travel in the `write-human` skill, which a markdown edit routes to.
+The split with the voice guidance is what reads the rule rather than what the rule covers. Every ban below ships as data `aitk markdown audit` and the installed audit hook both read, so a violation is measured on every run. Cadence, rhythm, and information density are judgments a reader settles, and those travel in the `aitk:write-human` skill, which a markdown edit routes to.
 
 Does not govern:
 

package/standards/teach.md

@@ -97,7 +97,7 @@ Record the wrong answer rather than the fact of an error. A wrong answer names t
 
 ## GLOSSARY.md
 
-Required in every workspace, holding one entry per term the subject defines. The glossary reference the `claude-teach` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
+Required in every workspace, holding one entry per term the subject defines. The glossary reference the `aitk:claude-teach` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
 
 Name the lesson or reference page a term first appears in as that reference requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.