@erclx/aitk 3.51.1 → 3.52.1

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

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

package/claude/skills/claude-orchestrate/scripts/watch.sh

@@ -5,7 +5,12 @@
 # holds. This answers "what just changed" on a loop of its own, and it exists
 # because the two readings a dispatch needs are not one reading: a worker that
 # finishes goes idle and a worker that crashes vanishes, so a watch matching
-# only the pull request list stays silent through the second.
+# only the pull request list stays silent through the second. A third case is
+# neither: a worker that stops on a question or a prompt neither finishes nor
+# crashes, and sits reading "waiting" beside the two statuses that resolve on
+# their own until something reports it, which is the WORKER-STOPPED line
+# below, or WORKER-UNMEASURABLE for a "waiting" row too old to carry a stamp
+# this reads.
 #
 # `set -e` is deliberately not set. This runs for hours, and one transient `gh`
 # failure aborting the loop is a silent stop rather than a reported one. Every
@@ -17,6 +22,28 @@ set -uo pipefail
 # in a project whose workers run long.
 INTERVAL=60
 
+# Seconds a worker can sit in "waiting" before this reports it as stopped
+# rather than folding it into the ordinary status-change lines below. "busy"
+# and "idle" resolve on their own; "waiting" does not, so a dwell that keeps
+# growing there is a session blocked on something outside itself.
+#
+# Measured against the live session registry: 341 usable records carried a
+# status at all, and exactly one carried "waiting", too sparse a sample to fit
+# a distribution. The number is picked from the two bounds the measurement can
+# still name rather than from a round guess: well above INTERVAL, so a handful
+# of passes confirm the row before it reports rather than one slow tool call
+# tripping it, and well inside the ten-to-thirty-minute span a dispatched build
+# ordinarily runs, so a real stall is caught with most of that window still
+# open to act on it.
+#
+# That one record carried `waitingFor: "approve Bash"`, a permission prompt
+# rather than a question, and the two clear on different schedules: a prompt
+# resolves the moment a person approves it, where a question can sit
+# legitimately while a controller finishes a turn. This number is defensible
+# for the second and generous for the first, and the gap stays open rather
+# than splitting the constant on a sample of one.
+STALL_THRESHOLD_S=300
+
 # Resolving the main worktree root rather than this file's folder keeps a watch
 # started from a linked worktree reading the same repository as one started from
 # main. The repository field on a roster row is that root's `.git`.
@@ -40,13 +67,19 @@ BASE_BRANCH="${BASE_REF#origin/}"
 # worker, whoever launched it. The prototype matched the `orchestrator-` prefix
 # instead, which reads a dispatched worker and misses every hand-launched one,
 # and those are the ordinary shape whenever the operator is launching.
+#
+# The row goes out tab-separated and comes back read with IFS set to a tab. A
+# name this client actually writes carries spaces, `Update session markdown
+# and check runnable commands (3)` among them, and splitting on whitespace
+# took that one apart into a wrong name, branch, status, and dwell.
 read_workers() {
   aitk sessions list --json 2>/dev/null | tail -1 | jq -r \
     --arg repository "$REPOSITORY" --arg base "$BASE_BRANCH" '
       .sessions[]?
       | select(.repository == $repository)
       | select(.branch != null and .branch != $base)
-      | "\(.name) \(.branch) \(.status)"
+      | [.name, .branch, .status, (.statusDwellMs // -1 | tostring)]
+      | @tsv
     ' 2>/dev/null | sort
 }
 
@@ -70,6 +103,15 @@ prev_names=""
 pulls_seen=0
 workers_seen=0
 
+# One row per worker name currently reported, waiting past STALL_THRESHOLD_S
+# or waiting with no stamp to measure, so a reader watching the log is told
+# once rather than on every remaining pass. The prototype for that shape is
+# the WORKER-GONE/WORKER pair above, tracked in the same state a status change
+# is: a name drops out the pass it stops reading "waiting", which lets the
+# same worker report a second stall later in its life rather than being
+# marked forever by its first one.
+declare -A stalled
+
 while true; do
   pulls="$(read_pulls)"
   pulls_read=$?
@@ -83,7 +125,7 @@ while true; do
     echo "watch: the session roster failed to load, so no worker is classified this pass"
   fi
 
-  names="$(printf '%s\n' "$workers" | awk 'NF {print $1}' | sort -u)"
+  names="$(printf '%s\n' "$workers" | awk -F'\t' 'NF {print $1}' | sort -u)"
 
   if [ "$pulls_seen" -eq 1 ] && [ "$pulls_read" -eq 0 ]; then
     comm -13 <(printf '%s\n' "$prev_pulls") <(printf '%s\n' "$pulls") | grep . || true
@@ -96,6 +138,35 @@ while true; do
       grep . | sed 's/^/WORKER-GONE /' || true
   fi
 
+  if [ "$workers_read" -eq 0 ]; then
+    while IFS=$'\t' read -r w_name w_branch w_status w_dwell_ms; do
+      [ -z "$w_name" ] && continue
+
+      if [ "$w_status" != "waiting" ]; then
+        unset "stalled[$w_name]"
+        continue
+      fi
+
+      if [ "$w_dwell_ms" = "-1" ]; then
+        if [ -z "${stalled[$w_name]:-}" ]; then
+          echo "WORKER-UNMEASURABLE $w_name $w_branch"
+          stalled[$w_name]=1
+        fi
+        continue
+      fi
+
+      w_dwell_s=$((w_dwell_ms / 1000))
+      if [ "$w_dwell_s" -ge "$STALL_THRESHOLD_S" ]; then
+        if [ -z "${stalled[$w_name]:-}" ]; then
+          echo "WORKER-STOPPED $w_name $w_branch ${w_dwell_s}s"
+          stalled[$w_name]=1
+        fi
+      else
+        unset "stalled[$w_name]"
+      fi
+    done <<<"$workers"
+  fi
+
   if [ "$pulls_read" -eq 0 ]; then
     prev_pulls="$pulls"
     pulls_seen=1

package/docs/agents/audits.md

@@ -34,7 +34,7 @@ Each is invoked as the CLI the caller is running rather than as a global `aitk`.
 
 Four findings fail the run: an unresolved context citation, a banned character, word, or spelling, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
 
-Three of the four are the ones `scripts/core/verify.sh` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
+Three of the four are the ones `aitk gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
 
 Everything else reports. A heavy bullet, a long entry, a board row nothing resolves, a degradation term in a comment, and an implementation reaching history ahead of its test are judgments a reader settles. A push failing on one of those teaches contributors to route around the stage, which is the split recorded across every audit here and the one this command inherits rather than moves.
 

package/docs/agents/commands.md

@@ -64,6 +64,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk census [path]`       | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                  |
 | `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)                                |
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                             |
+| `aitk gate run`            | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`)                           |
 | `aitk inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                  |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                 |
 | `aitk serve [dir]`         | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                               |
@@ -116,6 +117,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `labels`    | `audit`                                                                                                                               |
 | `autoship`  | `classify`                                                                                                                            |
 | `audits`    | `run`, `list`                                                                                                                         |
+| `gate`      | `run`                                                                                                                                 |
 
 Common patterns:
 

package/docs/agents/gate.md

@@ -0,0 +1,84 @@
+---
+title: Merge gate
+description: Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
+---
+
+# Merge gate
+
+`aitk gate run` runs every stage that guards a branch here, in order, stopping at the first stage that finds a fact. `bun run check` and `bun run check:ci` resolve to it, and `scripts/core/update.sh` calls it with `--nested` after a dependency update.
+
+```bash
+aitk gate run
+aitk gate run --all --no-write
+aitk gate run --json
+```
+
+| Option       | Behavior                                                                      |
+| ------------ | ----------------------------------------------------------------------------- |
+| `--all`      | Run every stage instead of scoping shell, types, and tests to the changed set |
+| `--no-write` | Check formatting instead of applying it, which is what a merge gate wants     |
+| `--nested`   | Suppress the outer frame when a calling script has already opened one         |
+| `--json`     | Add a machine-readable record on stdout                                       |
+
+## What the command owns and what it runs
+
+Three things sit in the command: the stage table in `src/gate/stages.ts`, the changed-file scoping and the run loop in `src/gate/sequencer.ts`, and every threshold comparison in `src/gate/measures.ts`. Each individual check is the script or the verb it already was, under `scripts/core/` or behind another `aitk` command, and the move changed none of them. Sequencing, scoping, and comparison are where the recurring defects were, and a check whose behavior changed while its sequencing moved would make any regression impossible to attribute.
+
+A stage is a list of checks and a check is one of four kinds:
+
+| Kind      | What it is                                                                      |
+| --------- | ------------------------------------------------------------------------------- |
+| `command` | Any binary, run from the project root                                           |
+| `cli`     | This checkout's own `src/cli.ts`, never a globally installed `aitk`             |
+| `drift`   | A regenerated pathspec asserted against the index and against the untracked set |
+| `measure` | A reading whose verdict is a comparison rather than an exit code                |
+
+A `cli` check runs the source rather than the binary because a globally installed `aitk` resolves to the main checkout no matter which worktree is running, so a gate reading through it would measure the wrong tree and pass a branch it never opened.
+
+Every check is an argument vector rather than a shell line, so no stage carries a quoting hazard and a `drift` pathspec reaches git exactly as the table spells it.
+
+## Scoping
+
+Shell, types, and tests read the changed set. Everything else always runs, because its input is diffuse enough that no path predicts it.
+
+The changed set unions the branch diff against the merge base with `origin/main`, the working tree, and untracked files, which is what a pull request will contain. The baseline is the remote ref and not local `main`, since on `main` itself the local ref is HEAD and every unpushed commit would drop out. Every fallback widens rather than narrows: no merge base at all runs every stage, and a local baseline equal to HEAD does the same. `--all` turns scoping off outright, which is what `bun run check:ci` passes so CI stays the backstop for a wrong local scoping decision.
+
+## A stage that cannot read its input
+
+A stage reports one of four states. It passed, it was scoped out, it found a fact, or it could not measure its input at all.
+
+The fourth is the one worth naming. An absent tool, a catalog that did not report, a corpus with nothing under it: each used to print a line that read like a pass. Now the run records it as unmeasured, the closing line says how many stages measured nothing, and the reader is not told a verdict nobody took.
+
+What happens next depends on where the run is. On a contributor's machine it warns and the run still exits 0, because an absent tool there is somebody mid-setup. Under CI, read off `CI=true`, it refuses, because the same absence on a runner is a broken workflow step.
+
+## Exit codes
+
+| Code | Meaning                                                       |
+| ---- | ------------------------------------------------------------- |
+| `0`  | every stage that ran reported, and none found a fact          |
+| `1`  | a stage found a fact, or could not measure its input under CI |
+
+One code for a failure, which is what a `bun run` caller and a git hook both read. An unmeasured stage takes no code of its own, since it has already refused under CI and reports on a contributor's machine, so a second code would name a state no caller branches on.
+
+## The record
+
+`--json` puts one record on stdout and keeps every diagnostic on stderr:
+
+```json
+{
+  "ok": true,
+  "root": "/path/to/checkout",
+  "scoped": true,
+  "changed": 12,
+  "summary": {
+    "ran": 23,
+    "passed": 22,
+    "skipped": 1,
+    "unmeasured": 0,
+    "failed": 0
+  },
+  "stages": [{ "id": "indexes", "label": "Indexes", "status": "passed" }]
+}
+```
+
+A failing stage carries its remedy in `failure`, and the same line goes to stderr so a caller reading neither the record nor the frame is still told what to fix.

package/docs/agents/index.md

@@ -18,6 +18,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, the pointer the recording paints, and what each refusal reports
 - [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
+- [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
 - [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file

package/docs/agents/markdown-audit.md

@@ -126,9 +126,9 @@ The condition on that was something identifying a finite verb rather than guessi
 
 Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling fails the run. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
 
-`3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `scripts/core/verify.sh` is right to warn and skip. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
+`3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `aitk gate run` is right to report it as unmeasured rather than as a pass. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
 
-`2` rather than `1` for the gate keeps a measurement that succeeded and found something distinct from the audit declining to measure at all. A caller reading one as the other sends a reader hunting a defect that does not exist, which is the distinction `aitk context audit` and the `verify.sh` seed stage already draw between the same two codes.
+`2` rather than `1` for the gate keeps a measurement that succeeded and found something distinct from the audit declining to measure at all. A caller reading one as the other sends a reader hunting a defect that does not exist, which is the distinction `aitk context audit` and the gate's own seed stage already draw between the same two codes.
 
 A banned character is a fact rather than a judgment, which is the test that admits it to a gate. What held it back was that gating on day one against a corpus never checked mechanically fails loudly on work nobody has had a chance to fix. The order was to land the verb reporting, measure the corpus once, fix what it finds, and turn the gate on as its own change, and the gate is the last of the four.
 
@@ -148,7 +148,7 @@ A hit the closed set cannot separate from correct prose is the case with no thir
 
 ### Where the rules are enforced
 
-Four surfaces apply the ban sets and three of them go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, and the `Markdown bans` stage in `scripts/core/verify.sh` runs it across the whole corpus before a push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
+Four surfaces apply the ban sets and three of them go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, and the `Markdown bans` stage in `aitk gate run` runs it across the whole corpus before a push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
 
 The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `aitk` gets a report naming the binary to install rather than a silent pass. `scripts/core/check-seed-independence.sh` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
 

package/docs/agents/sessions.md

@@ -105,6 +105,14 @@ Every report states how liveness was decided, on a pass as well as a failure.
 
 The registry holds one record per session and is never pruned, so it accumulates thousands of entries. On the `unverified` path a stale record whose pid has been reused reads as live, which is why the field is reported rather than assumed.
 
+## The status dwell
+
+Every row carries `statusUpdatedAt`, the stamp a client writes beside `status` at the moment it last changed, and `statusDwellMs`, the elapsed milliseconds since that stamp. Measured over the live registry, 23 of 341 usable records carry `statusUpdatedAt`, so `null` is the ordinary answer rather than an edge case, and the absence tracks a client version rather than a record's age alone: the one record ever measured carrying `status: "waiting"` is among the 318 without it.
+
+`statusDwellMs` falls back to the coarser `updatedAt` stamp when `statusUpdatedAt` is absent, so it is `null` only where a record carries neither. `statusUpdatedAt` itself is never backfilled from the fallback and stays `null` in that case, since it names the exact stamp rather than an estimate. A stamp ahead of the reading clock clamps the dwell to zero rather than reporting a negative one.
+
+The dwell is what separates a status that resolves on its own from one that does not. `busy` and `idle` transition without help, so a long dwell there is ordinary. `waiting` does not: a session in that state is blocked on something outside itself, and a dwell that keeps growing past the ordinary span of a prompt is a session stalled rather than paused. `aitk sessions list` renders the dwell beside the status at the coarsest unit that keeps it a whole number, and the JSON record carries both fields on every row.
+
 ## What the read depends on
 
 The records live under the Claude Code configuration directory, which the verb resolves from `CLAUDE_CONFIG_DIR` and falls back to `~/.claude`. Their location, their filenames, and the fields inside them are a client implementation detail rather than a published interface, so a client change can move them. The verb reports an absent registry as a refusal rather than as a machine running no sessions, which is what surfaces the move instead of burying it in an empty roster.

package/docs/agents/state-scoped-risk.md

@@ -59,7 +59,7 @@ The exemption travels with the line rather than sitting in a path list away from
 
 Exit codes are `0` when the shipped tree carries no credential-shaped value, `1` for a refusal, and `2` for at least one value found.
 
-This is the one entry in `aitk audits run` that gates without a `verify.sh` stage behind it. A credential in the published tree is a fact rather than a judgment, which is the test the catalog asks any gating addition to pass, and the architecture record already ranks content leaving the repository above content that stays.
+This is the one entry in `aitk audits run` that gates without an `aitk gate run` stage behind it. A credential in the published tree is a fact rather than a judgment, which is the test the catalog asks any gating addition to pass, and the architecture record already ranks content leaving the repository above content that stays.
 
 A refusal is never a clean tree. Five reasons produce one, and each exits `1`, because zero findings over zero files reads in the report exactly like zero findings over the whole shipped tree.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.51.1",
+  "version": "3.52.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -34,8 +34,8 @@
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",
     "prepare": "husky",
-    "check": "./scripts/core/verify.sh",
-    "check:ci": "VERIFY_WRITE=false ./scripts/core/verify.sh --all",
+    "check": "bun src/cli.ts gate run",
+    "check:ci": "bun src/cli.ts gate run --all --no-write",
     "update": "./scripts/core/update.sh",
     "clean": "./scripts/core/clean.sh",
     "snapshot": "./scripts/core/snapshot.sh",

package/scripts/core/list-seed-roots.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Prints every seed root carrying a `.claude/`, one per line and relative to
+# the project root.
+#
+# The discovery rule has one definition, `collect_seed_roots` in
+# `scripts/lib/tooling.sh`, which `check-seed-independence.sh` already reads.
+# This file is the route a caller outside bash takes to that same answer, so a
+# stack seeding `.claude/` later reaches both readers and the two stages
+# measuring seed content cannot disagree about which roots exist.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
+
+collect_seed_roots

package/scripts/core/repair-bare-flag.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
+# shared config with nothing restoring it. The flag strands the main worktree
+# and breaks the git reads that scope a verification run, so this runs ahead of
+# every stage rather than as one of them.
+#
+# The rule itself lives in `scripts/lib/worktree.sh`, the one bash function in
+# this repository under test, so this file is the invocation and never a second
+# copy of the guard that spares a genuinely bare repository.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/worktree.sh"
+
+repair_bare_flag "$PROJECT_ROOT"

package/scripts/core/update.sh

@@ -21,11 +21,11 @@ main() {
   bun update --interactive
 
   log_step "Verifying project health"
-  if [ -f "$SCRIPT_DIR/verify.sh" ]; then
-    VERIFY_NESTED=true "$SCRIPT_DIR/verify.sh"
+  if [ -f "$PROJECT_ROOT/src/cli.ts" ]; then
+    bun "$PROJECT_ROOT/src/cli.ts" gate run --nested
     log_info "All checks passed"
   else
-    log_warn "Verification script not found, skipping."
+    log_warn "Verification entry point not found, skipping."
   fi
 
   echo -e "${GREY}└${NC}\n"

package/src/audits/catalog.ts

@@ -469,8 +469,8 @@ const RECORD_KINDS: readonly (readonly [string, Corpus])[] = [
 /**
  * Every audit the aggregate runs.
  *
- * `context`, `markdown`, and `skills` gate because `scripts/core/verify.sh`
- * already fails a push on each. `secrets` is the one entry that gates without
+ * `context`, `markdown`, and `skills` gate because the merge gate in
+ * `src/gate/stages.ts` already fails a push on each. `secrets` is the one entry that gates without
  * a stage behind it, added deliberately rather than as a side effect, since a
  * credential in the published tree is a fact and the split this repository
  * records gates a fact and reports a judgment. Weigh any further addition

package/src/audits/run.ts

@@ -32,7 +32,8 @@ export type Spawn = (spec: AuditSpec) => Promise<SpawnResult>
  * Runs each verb out of the checkout this CLI is executing from.
  *
  * `process.execPath` and the resolved `cli.ts` rather than a bare `aitk`, for
- * the reason `verify.sh` already names: a globally installed binary resolves to
+ * the reason `cliRunner` in `src/gate/sequencer.ts` already names: a globally
+ * installed binary resolves to
  * the main checkout no matter which worktree is running, so the aggregate would
  * measure the wrong tree and report a pass over a branch it never read.
  *

package/src/cli.ts

@@ -30,6 +30,7 @@ import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
 import { register as worktrees } from '@/commands/worktrees'
 import { register as audits } from '@/commands/audits'
+import { register as gate } from '@/commands/gate'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
@@ -84,6 +85,7 @@ function showHelp(): void {
     `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
     `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
+    `${GREY}│${NC}    gate [cmd]         ${GREY}# Run the merge gate stage by stage (run)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
@@ -132,6 +134,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk labels audit --json`,
     `${GREY}│${NC}    aitk census --json`,
     `${GREY}│${NC}    aitk audits run --json`,
+    `${GREY}│${NC}    aitk gate run --all --no-write`,
     `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
   ]
@@ -186,6 +189,7 @@ labels(program)
 autoship(program)
 census(program)
 audits(program)
+gate(program)
 upgrade(program)
 
 program.parse()

package/src/commands/claude.ts

@@ -1136,8 +1136,8 @@ function refuseAudit(
 /**
  * Prints nothing when every skill carries a requirement.
  *
- * `--requirements-only` is what `verify.sh` runs on every push, and that script
- * pipes a stage's whole output into its own frame. A passing gate that printed
+ * `--requirements-only` is what the merge gate runs on every push, and it pipes
+ * a stage's whole output into its own frame. A passing gate that printed
  * its frame would nest one inside the other on every contributor's push.
  */
 function reportRequirementGate(report: SkillsAudit): void {

package/src/commands/context.ts

@@ -349,8 +349,8 @@ function refuse(
 /**
  * Prints nothing when every path resolves.
  *
- * `--citations-only` is what `verify.sh` runs on every push, and that script
- * pipes a stage's whole output into its own frame. A passing gate that printed
+ * `--citations-only` is what the merge gate runs on every push, and it pipes
+ * a stage's whole output into its own frame. A passing gate that printed
  * its frame would nest one inside the other on every contributor's push.
  */
 function reportGate(report: ScannedCitations): void {