@erclx/aitk 3.43.2 → 3.44.0

package/docs/ai-workflow.md

@@ -185,7 +185,7 @@ This section is the corpus the coverage claim is measured against: every name `a
 | Skill                        | When to use                                                                             |
 | ---------------------------- | --------------------------------------------------------------------------------------- |
 | `aitk:setup-init`            | On a fresh scaffold, to detect the stack and run the whole install chain in one pass    |
-| `aitk:toolkit-operator`      | On a project that already exists, to read what it carries before an install is picked   |
+| `aitk:aitk-operator`         | On a project that already exists, to read what it carries before an install is picked   |
 | `aitk:setup-gov`             | When the governance rules are wanted without the tooling chain                          |
 | `aitk:setup-indexes`         | When a markdown-heavy folder needs an `index.md` a session can browse                   |
 | `aitk:setup-plugins`         | On a new machine, to install the community and official plugins user-scoped             |
@@ -266,32 +266,32 @@ This section is the corpus the coverage claim is measured against: every name `a
 | `aitk:migration-context`        | When `docs/` holds agent-flavored files belonging in `.claude/context/`            |
 | `aitk:migration-superseded`     | When a drift report names a `.claude/` file a folder has replaced                  |
 | `aitk:migration-standards-drop` | When the project still holds an installed `.claude/standards/` tree                |
-| `aitk:toolkit-feedback`         | When something in the toolkit is broken, missing, or off                           |
-| `aitk:toolkit-triage`           | In the toolkit repo, to work through the open feedback issues                      |
+| `aitk:aitk-feedback-file`       | When something in the toolkit is broken, missing, or off                           |
+| `aitk:aitk-feedback-triage`     | In the toolkit repo, to work through the open feedback issues                      |
 
 ### Generate an artifact on demand
 
-| Skill                      | When to use                                                           |
-| -------------------------- | --------------------------------------------------------------------- |
-| `aitk:create-rule`         | For a project-specific governance rule the toolkit does not ship      |
-| `aitk:create-skill`        | For a new `SKILL.md`                                                  |
-| `aitk:create-snippet`      | For a reusable prompt                                                 |
-| `aitk:create-standard`     | For a new authoring convention                                        |
-| `aitk:bash-script`         | For an interactive, human-facing shell tool                           |
-| `aitk:cli-script`          | For a non-interactive automation, CI, or pipeline script              |
-| `aitk:ci-workflow`         | For a GitHub Actions workflow file                                    |
-| `aitk:claude-slides-draft` | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint |
-| `aitk:claude-screencast`   | For a recording script with beats and defaults already seeded         |
+| Skill                    | When to use                                                           |
+| ------------------------ | --------------------------------------------------------------------- |
+| `aitk:create-rule`       | For a project-specific governance rule the toolkit does not ship      |
+| `aitk:create-skill`      | For a new `SKILL.md`                                                  |
+| `aitk:create-snippet`    | For a reusable prompt                                                 |
+| `aitk:create-standard`   | For a new authoring convention                                        |
+| `aitk:bash-script`       | For an interactive, human-facing shell tool                           |
+| `aitk:bash-cli-script`   | For a non-interactive automation, CI, or pipeline script              |
+| `aitk:ci-workflow`       | For a GitHub Actions workflow file                                    |
+| `aitk:aitk-slides-draft` | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint |
+| `aitk:aitk-screencast`   | For a recording script with beats and defaults already seeded         |
 
 ### Answer a question at any point
 
 | Skill                      | When to use                                                                    |
 | -------------------------- | ------------------------------------------------------------------------------ |
-| `aitk:toolkit-cli`         | Before a sync or install, to learn what it overwrites, merges, or leaves alone |
+| `aitk:aitk-cli`            | Before a sync or install, to learn what it overwrites, merges, or leaves alone |
 | `aitk:youtube-transcripts` | When a video transcript is wanted in the repo as context                       |
 | `aitk:claude-teach`        | To learn a subject across sessions, in a workspace that holds the progress     |
 | `aitk:write-human`         | Before drafting or revising prose, for voice, rhythm, and density              |
-| `aitk:restate`             | When an answer or a document has to be read again in plain words               |
+| `aitk:restate-plainly`     | When an answer or a document has to be read again in plain words               |
 
 Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
 

package/docs/target-projects.md

@@ -49,7 +49,7 @@ The chain is:
 - The agent reads `aitk tooling reference <stack>` (plus parents) as its audit context, follows it to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations: .claude/context/development.md -->
 - `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
 
-The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `aitk:toolkit-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `aitk claude init` for the seed docs and then `aitk:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
+The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `aitk:aitk-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `aitk claude init` for the seed docs and then `aitk:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
 
 Keep the `## Scripts` table in `.claude/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run that way. A project whose entry outgrew one file and split into `.claude/context/development/` keeps the table in `overview.md`, which is where the skill looks next. <!-- audit-ignore-citations: .claude/context/development.md -->
 

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

@@ -9,7 +9,7 @@ paths:
 ## Skill routing
 
 - 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.
+- Use `aitk:bash-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.
 

package/package.json

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

package/scripts/core/regen-tooling-paths.sh

@@ -15,7 +15,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
 TOOLING_DIR="$PROJECT_ROOT/tooling"
-CONTRACT="$PROJECT_ROOT/claude/skills/toolkit-cli/SKILL.md"
+CONTRACT="$PROJECT_ROOT/claude/skills/aitk-cli/SKILL.md"
 
 BEGIN="<!-- generated:tooling-paths -->"
 END="<!-- /generated:tooling-paths -->"

package/scripts/core/verify.sh

@@ -298,7 +298,7 @@ main() {
 
   log_step "Tooling paths"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-tooling-paths.sh" "Tooling-path regen failed"
-  assert_no_drift "claude/skills/toolkit-cli/SKILL.md" "The overwrite contract drifted from what the stacks hold. Run bun run check and commit claude/skills/toolkit-cli/SKILL.md."
+  assert_no_drift "claude/skills/aitk-cli/SKILL.md" "The overwrite contract drifted from what the stacks hold. Run bun run check and commit claude/skills/aitk-cli/SKILL.md."
   log_info "Tooling paths clean"
 
   # The claude manifest is the only route a target's ignore set travels, and it

package/src/claude/cases/authoring.ts

@@ -18,7 +18,7 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Write me a headless automation script with no interactive prompts.',
-    expect: 'cli-script',
+    expect: 'bash-cli-script',
   },
   {
     prompt: 'Scaffold a brand-new SKILL.md for this capability.',
@@ -39,7 +39,7 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Say what that dense answer actually means in plain terms.',
-    expect: 'restate',
+    expect: 'restate-plainly',
   },
   {
     prompt: 'This passage reads flat and robotic, give it some real cadence.',

package/src/claude/cases/claude-workflow.ts

@@ -81,7 +81,7 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Draft me a script with beats for a screencast recording.',
-    expect: 'claude-screencast',
+    expect: 'aitk-screencast',
   },
   {
     prompt:
@@ -90,7 +90,7 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Turn this topic into a slide deck I can render.',
-    expect: 'claude-slides-draft',
+    expect: 'aitk-slides-draft',
   },
   {
     prompt:

package/src/claude/cases/setup.ts

@@ -1,7 +1,7 @@
 import type { SkillCase } from '@/claude/skills-rank'
 
 /**
- * `setup-*`, `migration-*`, `toolkit-*`, and `create-rule`: scaffolding,
+ * `setup-*`, `migration-*`, `aitk-*`, and `create-rule`: scaffolding,
  * proposal-only migrations, and the toolkit's own reference and feedback
  * surfaces.
  */
@@ -53,20 +53,20 @@ export const SETUP_CASES: readonly SkillCase[] = [
   {
     prompt:
       "Before I run this sync, tell me exactly what it's going to overwrite.",
-    expect: 'toolkit-cli',
+    expect: 'aitk-cli',
   },
   {
     prompt:
       'Something about the toolkit itself is broken, write it up and send it back to the maintainers.',
-    expect: 'toolkit-feedback',
+    expect: 'aitk-feedback-file',
   },
   {
     prompt:
       "I don't know which specific toolkit skill I need, just handle it for me.",
-    expect: 'toolkit-operator',
+    expect: 'aitk-operator',
   },
   // The performing skill wins a phrase naming its operation over the front
-  // door's own routing framing, even though toolkit-operator's description
+  // door's own routing framing, even though aitk-operator's description
   // quotes a phrase near this one. See .claude/context/cli/audits.md.
   {
     prompt:
@@ -76,7 +76,7 @@ export const SETUP_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Work through the open feedback issues on the toolkit repo one by one.',
-    expect: 'toolkit-triage',
+    expect: 'aitk-feedback-triage',
   },
   {
     prompt:

package/src/cli.ts

@@ -33,6 +33,7 @@ import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
 import { register as census } from '@/commands/census'
+import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
@@ -72,6 +73,7 @@ function showHelp(): void {
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
+    `${GREY}│${NC}    targets [cmd]      ${GREY}# Report the projects this toolkit installed into (list, pulls)${NC}`,
     `${GREY}│${NC}    worktrees [cmd]    ${GREY}# Report which worktrees are reclaimable (list)${NC}`,
     `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
@@ -170,6 +172,7 @@ context(program)
 markdown(program)
 records(program)
 sessions(program)
+targets(program)
 worktrees(program)
 secrets(program)
 deps(program)

package/src/commands/demo.ts

@@ -42,7 +42,7 @@ export function register(program: Command): void {
   demo
     .command('compile')
     .description('Turn a screencast draft into a plan a run can drive')
-    .argument('<draft>', 'Screencast draft written by claude-screencast')
+    .argument('<draft>', 'Screencast draft written by aitk-screencast')
     .helpOption('-h, --help', 'Show this help message')
     .option('-o, --out <dir>', 'Directory the plan is written to', DEFAULT_OUT)
     .option('-s, --slug <slug>', 'Plan name, defaulting to the draft filename')

package/src/commands/sessions.ts

@@ -1,3 +1,4 @@
+import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { checkClaim, type ClaimReport } from '@/sessions/claim'
 import {
@@ -19,6 +20,7 @@ import {
 interface ListCommandOptions {
   readonly json?: boolean
   readonly branch?: string
+  readonly repository?: string
 }
 
 const REASONS: Record<string, string> = {
@@ -46,6 +48,10 @@ export function register(program: Command): void {
       '--branch <name>',
       'Report only the sessions holding this branch in this repository',
     )
+    .option(
+      '--repository <path>',
+      'Answer about this project rather than the working one',
+    )
     .addHelpText(
       'after',
       [
@@ -54,11 +60,18 @@ export function register(program: Command): void {
         '  0  the roster was read',
         '  1  refused, with the reason on stderr',
         '',
-        '--branch scopes the match to the repository the command runs in, since',
-        'a branch name identifies a branch there and nothing across a machine.',
+        '--branch scopes the match to one repository, since a branch name',
+        'identifies a branch there and nothing across a machine. That is the',
+        'repository the command runs in unless --repository names another.',
         'A bare run reports every repository and carries the repository field,',
         'so a caller filtering by hand has something that identifies one.',
         '',
+        '--repository moves every reading to the project at that path, the',
+        'session match and the worktree and ref reads alike. The roster is',
+        'machine-wide already, so this is what lets a dispatcher in one project',
+        'see a branch a live session holds in another rather than reading it as',
+        'unclaimed and sending a second session onto it.',
+        '',
         'With --branch, the JSON also carries "worktree" (the path of any',
         'worktree already checked out to it, or null), "refs" (the refs that',
         'already name it, local head and origin remote-tracking alike), and',
@@ -94,6 +107,7 @@ export function register(program: Command): void {
         '  aitk sessions list',
         '  aitk sessions list --json',
         '  aitk sessions list --branch feat/parser --json',
+        '  aitk sessions list --branch chore/agents --repository ../caret --json',
         '',
       ].join('\n'),
     )
@@ -125,13 +139,18 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   // A branch name identifies a branch inside one repository and nothing across
   // a machine, so an unscoped match reaches a session working in a different
   // project. `main` is the name that collides on every machine running two.
-  const repository = opts.branch ? await repositoryOf(process.cwd()) : null
+  //
+  // Which repository that is is the caller's to name. The roster this filters
+  // is machine-wide already, so a dispatcher asking about another project was
+  // answered "unclaimed" about a branch a live session there was holding.
+  const at = opts.repository ? resolve(opts.repository) : process.cwd()
+  const repository = opts.branch ? await repositoryOf(at) : null
 
   if (opts.branch && repository === null) {
     intro('aitk sessions list')
     logStep('Refused')
     logWarn(
-      '--branch scopes the match to the repository this command runs in, and no repository resolved here. Run it inside one, or read the whole roster and filter on the repository field.',
+      `--branch scopes the match to one repository, and none resolved at ${at}. Run it inside one, name another with --repository, or read the whole roster and filter on the repository field.`,
     )
     outro()
 
@@ -152,10 +171,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     : report.sessions
 
   const claim = opts.branch
-    ? await checkClaim(opts.branch, {
-        cwd: process.cwd(),
-        resolve: async () => report,
-      })
+    ? await checkClaim(opts.branch, { cwd: at, resolve: async () => report })
     : null
 
   intro('aitk sessions list')

package/src/commands/targets.ts

@@ -0,0 +1,319 @@
+import type { Command } from 'commander'
+import { readPullsAcross, type TargetPulls } from '@/targets/pulls'
+import {
+  type KnownTarget,
+  type ResolvedTargets,
+  resolveTargets,
+} from '@/targets/resolve'
+import { DEFAULT_DEPTH, type SweepBound } from '@/targets/sweep'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface ListOptions {
+  readonly json?: boolean
+  readonly sweep?: string[]
+  readonly depth?: string
+}
+
+interface PullsOptions extends ListOptions {}
+
+/**
+ * Reads the depth a sweep is bounded by, or null when the value is not one.
+ *
+ * `Number('abc')` is `NaN` and every `level >= NaN` test is false, so an
+ * unchecked value walks to the bottom of whatever root it was given while
+ * the bound reports a depth of `NaN`. Both halves of the guarantee go at once,
+ * which is why this refuses rather than falling back to the default.
+ */
+function readDepth(value: string | undefined): number | null {
+  const depth = Number(value ?? DEFAULT_DEPTH)
+
+  return Number.isInteger(depth) && depth >= 0 ? depth : null
+}
+
+const REFUSALS: Record<string, string> = {
+  'not-a-directory': 'the path is not a directory, so nothing was read there',
+  'gh-unavailable': 'gh is not on the path, so no pull request could be read',
+  'list-failed':
+    'the open pull request list could not be read, so this is not a target with no work',
+}
+
+export function register(program: Command): void {
+  const targets = program
+    .command('targets')
+    .description('Report the projects this toolkit has installed into')
+    .helpOption('-h, --help', 'Show this help message')
+
+  targets
+    .command('list')
+    .description('Report every known target with where the answer came from')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--sweep <path...>',
+      'Also walk these roots for targets the record never held',
+    )
+    .option(
+      '--depth <n>',
+      'How deep below each swept root to walk',
+      String(DEFAULT_DEPTH),
+    )
+    .addHelpText('after', LIST_HELP)
+    .action(async (opts: ListOptions) => {
+      process.exitCode = await runList(opts)
+    })
+
+  targets
+    .command('pulls')
+    .description(
+      'Report the open pull request, checks, and review heading per target',
+    )
+    .argument('[path...]', 'Targets to read, defaulting to every known one')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--sweep <path...>', 'Also walk these roots when no path is given')
+    .option(
+      '--depth <n>',
+      'How deep below each swept root to walk',
+      String(DEFAULT_DEPTH),
+    )
+    .addHelpText('after', PULLS_HELP)
+    .action(async (paths: string[], opts: PullsOptions) => {
+      process.exitCode = await runPulls(paths, opts)
+    })
+}
+
+const LIST_HELP = [
+  '',
+  'Sources:',
+  '  Every sync that stamps a target records it in a machine-level index, so',
+  '  a project installed since that shipped is known without being named.',
+  '  --sweep walks the roots given for anything installed before it, and a',
+  '  target found in two clones is reported once with both paths.',
+  '',
+  'Exit codes:',
+  '  0  the population was read',
+  '  1  refused, with the reason on stderr',
+  '',
+  'An absent index is reported as unknown rather than as no targets. Nothing',
+  'was read in that case, so a count of zero would be a confident wrong answer.',
+  '',
+  'The JSON carries a "bound" object whenever a sweep ran, naming the roots',
+  'walked, the depth, the folders the walk stopped at, the roots it could not',
+  'read, and the directory symlinks the walk did not follow. A sweep cannot',
+  'see another machine or a clone under a path nobody named, so read the bound',
+  'before treating the count as the population.',
+  '',
+  'An exit code says nothing about a call made from a session, since a shell',
+  'profile may wrap the binary in a function taking its status from a later',
+  'command. Read the record rather than the exit when a skill consumes this.',
+  '',
+  'Examples:',
+  '  aitk targets list',
+  '  aitk targets list --json',
+  '  aitk targets list --sweep ~/repos --json',
+  '',
+].join('\n')
+
+const PULLS_HELP = [
+  '',
+  'Reads, per target, every open pull request with its checks and the heading',
+  'its newest review pass carries. Naming paths reads those and looks up',
+  'nothing; naming none reads every target `aitk targets list` reports.',
+  '',
+  'Exit codes:',
+  '  0  at least one target was read',
+  '  1  refused, or every target refused',
+  '',
+  'A target that could not be read carries a "reason" rather than an empty',
+  'pull list, since reading a failed query as no open work is what reports a',
+  'target as done having read nothing.',
+  '',
+  '"checks" is null when GitHub reported no check at all, which is not the',
+  'same answer as passing. "review" is "open" while the newest pass carries',
+  '## Review, "closed" once one carries ## Review closed, and null when no',
+  'pass has landed. "reviewReadable" is false when that query failed, which',
+  'leaves "review" covering nothing.',
+  '',
+  'Examples:',
+  '  aitk targets pulls',
+  '  aitk targets pulls ../caret ../stackr --json',
+  '',
+].join('\n')
+
+async function runList(opts: ListOptions): Promise<number> {
+  intro('aitk targets list')
+
+  const depth = readDepth(opts.depth)
+
+  if (depth === null) return refuseDepth(opts)
+
+  const resolved = await resolveTargets({ sweep: opts.sweep, depth })
+
+  const unknown = reportTargets(resolved)
+  if (resolved.bound) reportBound(resolved.bound)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        registry: resolved.registry?.path ?? null,
+        known: resolved.registry?.kind !== 'absent',
+        targets: resolved.targets,
+        bound: resolved.bound,
+      })}\n`,
+    )
+  }
+
+  return unknown ? 1 : 0
+}
+
+async function runPulls(paths: string[], opts: PullsOptions): Promise<number> {
+  intro('aitk targets pulls')
+
+  const depth = readDepth(opts.depth)
+
+  if (depth === null) return refuseDepth(opts)
+
+  const resolved = await resolveTargets({ paths, sweep: opts.sweep, depth })
+
+  if (resolved.targets.length === 0) {
+    logStep('Refused')
+    logWarn(
+      resolved.registry?.kind === 'absent'
+        ? `No target index at ${resolved.registry.path}, and no path was given. Name the targets, or sweep for them with --sweep.`
+        : 'No target resolved, so nothing was read.',
+    )
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ reason: 'no-targets', targets: [] })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  // One clone per project. Two checkouts sharing an origin answer the same
+  // query, so reading both spends the rate limit to print one answer twice.
+  const reports = await readPullsAcross(
+    resolved.targets.map((target) => target.paths[0] ?? ''),
+  )
+
+  reportPulls(reports)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ targets: reports })}\n`)
+  }
+
+  return reports.every((report) => report.kind === 'refused') ? 1 : 0
+}
+
+function refuseDepth(opts: ListOptions): number {
+  logStep('Refused')
+  logWarn(
+    `--depth takes a whole number of levels and was given ${opts.depth}. A value that is not one leaves the walk with no cap at all.`,
+  )
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ reason: 'bad-depth', depth: opts.depth, targets: [] })}\n`,
+    )
+  }
+
+  return 1
+}
+
+/** Returns whether the population is unknown, which is the one refusal this read has. */
+function reportTargets(resolved: ResolvedTargets): boolean {
+  logStep('Targets')
+
+  if (resolved.registry?.kind === 'absent' && resolved.bound === null) {
+    logWarn(
+      `No target index at ${resolved.registry.path}. Nothing was read, so this is not a machine with no targets. Sweep for them with --sweep, or run a sync in a target to record it.`,
+    )
+    return true
+  }
+
+  if (resolved.targets.length === 0) {
+    logInfo('No target found.')
+    return false
+  }
+
+  logInfo(plural(resolved.targets.length, 'target'))
+  pipeOutput(resolved.targets.map(describe).join('\n'))
+  return false
+}
+
+function describe(target: KnownTarget): string {
+  const flags = [target.source, ...(target.legacy ? ['legacy stamp'] : [])]
+  const clones =
+    target.paths.length > 1 ? `\n  ${target.paths.slice(1).join('\n  ')}` : ''
+
+  return `${target.paths[0]}  ${flags.join(', ')}${clones}`
+}
+
+function reportBound(bound: SweepBound): void {
+  logStep('Bound')
+  logInfo(
+    `Walked ${plural(bound.roots.length, 'root')} to depth ${bound.depth} on this machine alone.`,
+  )
+
+  if (bound.truncated.length > 0) {
+    logWarn(
+      `${plural(bound.truncated.length, 'folder')} hit the depth cap, so a target below one is unseen.`,
+    )
+  }
+
+  if (bound.unreadable.length > 0) {
+    logWarn(
+      `${plural(bound.unreadable.length, 'root')} could not be read: ${bound.unreadable.join(', ')}`,
+    )
+  }
+
+  if (bound.symlinks.length > 0) {
+    const verb = bound.symlinks.length === 1 ? 'was' : 'were'
+    logWarn(
+      `${plural(bound.symlinks.length, 'symlink')} to a directory ${verb} not followed: ${bound.symlinks.join(', ')}`,
+    )
+  }
+}
+
+function reportPulls(reports: readonly TargetPulls[]): void {
+  logStep('Pull requests')
+
+  for (const report of reports) {
+    if (report.kind === 'refused') {
+      logWarn(`${report.path}: ${REFUSALS[report.reason] ?? report.reason}`)
+      continue
+    }
+
+    if (report.pulls.length === 0) {
+      logInfo(`${report.path}: nothing open.`)
+      continue
+    }
+
+    logInfo(`${report.path}`)
+    pipeOutput(
+      report.pulls
+        .map((pull) => {
+          const checks = pull.checks ?? 'no checks'
+          const review = pull.reviewReadable
+            ? (pull.review ?? 'no pass')
+            : 'review unreadable'
+          return `  #${pull.number}  ${checks}  ${review}  ${pull.url}`
+        })
+        .join('\n'),
+    )
+  }
+}

package/src/demo/beats.ts

@@ -1,5 +1,5 @@
 /**
- * Reads the human-facing draft `claude-screencast` writes. Nothing here knows
+ * Reads the human-facing draft `aitk-screencast` writes. Nothing here knows
  * about a browser: the draft is prose aimed at a person, and turning it into
  * something executable is `@/demo/compile`'s job.
  */

package/src/sessions/claim.ts

@@ -24,6 +24,13 @@ export interface ClaimReport {
 }
 
 export interface ClaimOptions {
+  /**
+   * The repository the claim is answered about, not merely where the caller
+   * stands. Every reading below is taken against it, so handing another
+   * project's path asks about that project, which is what lets a dispatcher in
+   * one repository see a branch held in another. Defaults to the caller's own
+   * directory, so a call omitting it answers exactly as it always has.
+   */
   readonly cwd?: string
   readonly resolve?: () => Promise<SessionReport>
   readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>