@erclx/aitk 3.26.1 → 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.1",
+  "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/package.json

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