@erclx/aitk 3.43.1 → 3.44.0

package/docs/agents/targets.md

@@ -0,0 +1,83 @@
+---
+title: Targets
+description: The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
+---
+
+# Targets
+
+## List
+
+`aitk targets list` reports the projects this toolkit has installed into, with where each answer came from.
+
+```bash
+aitk targets list
+aitk targets list --json
+aitk targets list --sweep ~/repos --json
+```
+
+| Option            | Behavior                                                |
+| ----------------- | ------------------------------------------------------- |
+| `--json`          | Add a machine-readable record on stdout                 |
+| `--sweep <path…>` | Also walk these roots for targets the record never held |
+| `--depth <n>`     | How deep below each swept root to walk, defaulting to 4 |
+
+Exit codes: `0` the population was read, `1` refused. A refusal carries a `reason` of `bad-depth`, and an absent index reports as unknown rather than as no targets.
+
+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's fields rather than the exit when a skill consumes this.
+
+## Where the answer comes from
+
+Every sync that stamps a target records it in a machine-level index at `$XDG_STATE_HOME/aitk/targets.json`, falling back to `~/.local/state/aitk/targets.json`. A project installed into since that shipped is therefore known without anyone naming it, and each row carries `stampedAt` from the sync that last touched it.
+
+`--sweep` walks the roots given and finds what the record never held, which is every target installed before the index existed. A row says which of the two found it, and a row the record knows keeps that source even when the sweep reaches it too.
+
+The record is the primary source and the sweep is the fallback, because they fail in opposite directions. A record only knows an install that ran after it shipped. A walk only knows the paths someone thought to name, which is how a hand census of this population was wrong in both directions at once: it counted two folders that had never been targets, counted one clone of a target already counted, and missed the clone a repair had actually run in.
+
+## What bounds a sweep
+
+A `--sweep` run carries a `bound` object naming the roots walked, the depth, the folders the walk stopped at on reaching the cap, the roots it could not read, and the directory symlinks it did not follow. Read it before treating a count as the population.
+
+The bound a sweep can never state is the machine. It reads this one, so a target on another machine or under a path nobody named is outside every answer it gives. That is the same limit the hand census had, and the record above is what closes it going forward rather than the sweep.
+
+`--depth` refuses anything that is not a whole number rather than falling back to the default. A value that is not one leaves every depth test false, so the walk runs to the bottom of its root while the bound claims a cap it never applied.
+
+## A project held in more than one clone
+
+A target cloned twice is one target. The sweep reads each checkout's `origin`, trims it to a form an ssh URL and an https URL of one repository agree on, and reports a single row holding every path.
+
+The row leads with the clone the record knows, because the record only names one a sync actually ran in. Every caller reading a single path takes the first, and picking that by sort order is the shape behind a repair that ran in one clone while a count was taken against another, leaving the target reported as untouched.
+
+Nothing removes a row. A project deleted, moved, or that dropped the toolkit stays in the index, so a count drifts upward over time. It surfaces on use rather than silently, since the read below refuses a path it cannot open.
+
+## Pulls
+
+`aitk targets pulls` reports, per target, every open pull request with its checks and the heading its newest review pass carries.
+
+```bash
+aitk targets pulls
+aitk targets pulls ../caret ../stackr --json
+```
+
+Naming paths reads those and looks up nothing. Naming none reads every target `aitk targets list` reports. One clone per project is read, since two checkouts sharing an origin answer the same query and reading both spends the rate limit to print one answer twice.
+
+Exit codes: `0` at least one target was read, `1` refused or every target refused.
+
+| Field            | Holds                                                                   |
+| ---------------- | ----------------------------------------------------------------------- |
+| `checks`         | `passing`, `failing`, `pending`, or `null` when GitHub reported none    |
+| `review`         | `open`, `closed`, or `null` when no pass has landed                     |
+| `reviewReadable` | `false` when the review query failed, leaving `review` covering nothing |
+
+`checks` is `null` rather than `passing` when no check ran at all, which is not the same answer. A failure outranks a run still going, since a job that already failed cannot be cleared by one still in flight.
+
+`review` reads the first line of the newest pass carrying `## Review` or `## Review closed`, which `claude-pr-review` owns and posts. A target leaves a wave on `closed` rather than on a worker's reply.
+
+A target that could not be read carries a `reason` rather than an empty pull list. Reading a failed query as no open work is what reports a target as done having read nothing, which is the failure mode of the hand-written shell loop this replaces.
+
+| Reason            | Means                                                  |
+| ----------------- | ------------------------------------------------------ |
+| `not-a-directory` | the path is not a directory, so nothing was read there |
+| `gh-unavailable`  | `gh` is not on the path                                |
+| `list-failed`     | the open pull request list could not be read           |
+
+The reads run one target at a time. They share one GitHub API quota, and a wave firing a dozen at once meets the secondary rate limit rather than an answer.

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.1",
+  "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')