@erclx/aitk 0.39.0 → 0.41.0

package/docs/agents/output-shape.md

@@ -0,0 +1,45 @@
+---
+title: Output shape
+description: The two framed shapes every command renders into, and how JSON and --names modes keep stdout clean
+---
+
+# Output shape
+
+Every CLI command renders into one of two framed shapes. Data goes to stdout. UI and logs go to stderr. Help output is the exception. It prints to stdout so it can be piped and grepped.
+
+## Data shape (lists, runs, errors)
+
+```plaintext
+┌
+│ aitk <domain>
+│
+├ Section
+│ ✓ item
+│ ✓ item
+└
+```
+
+Rules:
+
+- `┌` opens the frame on stderr
+- `│ aitk <domain>` is the command banner, one per invocation
+- `├ Section` headers introduce groups of items. `log_step` produces the blank `│` spacer before each.
+- `└` closes the frame on stderr, wired via `trap close_timeline EXIT`
+- Errors render as `│ ✗ message` inside the same frame. Never emit a lone error line without a frame.
+
+## Help shape
+
+```plaintext
+┌
+├ Usage: aitk <domain> [command]
+│
+│  Commands:
+│    ...
+└
+```
+
+Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to stdout because `--help` is documentation, not runtime UI.
+
+## JSON and `--names` modes
+
+`--json` and `--names` keep stdout clean and machine-readable. The frame still renders on stderr (open, banner, close) so the stream discipline is consistent across modes. Consumers that only read stdout see pure data.

package/docs/agents/overview.md

@@ -0,0 +1,26 @@
+---
+title: Overview
+description: What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+---
+
+# Overview
+
+CLI catalog and invocation rules for agents working in this repository.
+
+This folder is an index of what an agent can run and how to run it cleanly from a script. It does not cover domain behavior. Read `CLAUDE.md` for project behaviors and load the matching `.claude/skills/aitk-*` skill when working inside a domain.
+
+## Invocation rules
+
+See `CLAUDE.md` design principles. They apply to every command in this folder.
+
+## Where to start
+
+- `output-shape.md`: the stream contract every command renders into, which is what a caller parsing stdout depends on
+- `commands.md`: the full command catalog, project-level and per-domain
+- `scripting.md`: the runtime catalogs that replace hardcoded names, plus headless invocation examples
+
+## Related
+
+- `CLAUDE.md`: project behaviors and design principles
+- `.claude/skills/aitk-*`: domain-scoped guidance for editing work
+- `docs/index.md`: full docs directory

package/docs/agents/sandbox.md

@@ -0,0 +1,65 @@
+---
+title: Sandbox
+description: Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
+---
+
+# Sandbox
+
+`aitk sandbox` provisions isolated project states, scores a provisioned one against a declared expectation, and reports which scenarios declare an expectation at all.
+
+## Scenarios
+
+Scenarios live under `scripts/sandbox/`, one folder per category. `scripts/sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. `files` in `package.json` excludes that tree, so an installed `aitk` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
+
+```bash
+SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
+```
+
+Scenario categories: `infra:*` (domain flows), `git:*`, `scaffold:*`. `create` scenarios require interactive input and loop on empty input, so skip them in automated runs.
+
+## Scenario expectations
+
+`aitk sandbox check <category>:<command> [arm]` scores a provisioned sandbox against the arm's `expect.toml`, printing a verdict on stderr and, with `--json`, the same verdict as a record on stdout.
+
+```bash
+aitk sandbox check claude:docs drift --json
+```
+
+| Flag                | Effect                                                     |
+| ------------------- | ---------------------------------------------------------- |
+| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text  |
+| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope |
+| `--json`            | Emit the verdict record on stdout                          |
+| `--strict`          | Exit 1 on `unchecked` instead of 0                         |
+
+The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
+
+Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
+
+An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
+
+Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a malformed target, or a sandbox that was never provisioned. A missing sandbox reports as an error rather than a failed verdict, because failing every path assertion would read as a skill that did nothing. `--strict` moves `unchecked` to exit 1 for a caller that has finished arming its scenarios.
+
+## Scenario coverage
+
+`aitk sandbox coverage` reports which scenarios declare expectations and which only provision a state. It reads the fixture tree, so it needs no provisioned sandbox and runs nothing. Where that tree does not ship it exits 1 and prints no percentage, since a denominator nobody looked at is not a coverage result. A tree that is present and holds no scenarios is a real zero and still reports one.
+
+```bash
+aitk sandbox coverage --json
+```
+
+| Flag       | Effect                                                      |
+| ---------- | ----------------------------------------------------------- |
+| `--json`   | Emit the coverage record on stdout                          |
+| `--strict` | Exit 1 while any scenario declares no expectation           |
+| `--skills` | Add a per-skill asserted, should-be-asserted, exempt census |
+
+The record carries every scenario with the arms that declare, plus `totalScenarios`, `armedScenarios`, and `armedArms`. Scenarios and arms count separately, since several arms can share one scenario and dividing one by the other overstates the rollout.
+
+### The skills census
+
+`--skills` answers what the scenario count cannot, which is whether anything can fail a given skill. It adds `skills`, `totalSkills`, `asserted`, `shouldBeAsserted`, `exempt`, `staleExemptions`, and `supersededExemptions` to the record, and keeps the scenario view rather than replacing it. The two denominators disagree on purpose: an armed scenario under `infra/` or `tooling/` exercises a CLI domain and pairs with no skill at all.
+
+A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make. `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
+
+`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit. Stdout carries the same bytes it did before the record existed.

package/docs/agents/scripting.md

@@ -0,0 +1,115 @@
+---
+title: Scripting
+description: The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
+---
+
+# Scripting
+
+What a skill or script reads to discover names at runtime, and how each domain is invoked with no TTY.
+
+## Runtime catalogs
+
+Use these to discover what's available instead of hardcoding names.
+
+| Command                          | Returns                                       |
+| -------------------------------- | --------------------------------------------- |
+| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts  |
+| `aitk snippets list --json`      | Presets and categories with their slugs       |
+| `aitk standards list --json`     | Standards docs and the paths each governs     |
+| `aitk gov list --json`           | Governance stacks and rule sets               |
+| `aitk claude seeds list --json`  | Seed doc sources with content                 |
+| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag |
+| `aitk docs list --json`          | Consumer docs plus per-domain context         |
+
+### Catalog fields
+
+Every catalog serializes through `JSON.stringify`, so a name carrying a quote
+emits valid JSON. `aitk tooling list` and `aitk snippets list` previously built
+their output with `printf` and no escaping.
+
+`aitk standards list` carries `appliesTo` per standard, the paths that standard's
+`## Scope` statement declares. It holds the backticked paths from the first
+sentence of the statement, the single entry `*` for a standard governing an
+attribute rather than a document type, and an empty array when the statement
+declares nothing a parser can read. A consumer mapping a file to its governing
+standards reads this rather than holding a table of its own, and reports an empty
+array rather than skipping the standard behind it.
+
+`aitk claude seeds list` reads the same plan `aitk claude init` applies, so the
+listing and the install cannot disagree. It now reports
+`.claude/context/index.md`, which `init` has always installed and the listing
+never named, and it emits the project-level `CLAUDE.md` last rather than first.
+
+### The skills catalog
+
+`aitk claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder
+name with the frontmatter description, sorted by name. Internal skills under
+`.claude/skills/` are excluded, since they never install into a target and a
+count spanning both overstates what ships. A skill whose frontmatter is missing
+or unparseable returns an empty description rather than failing the listing, so
+one malformed file cannot hide the rest of the catalog. `--names` emits skill
+names one per line.
+
+Each entry also carries `requirement`, whether the folder holds a sibling
+`REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
+close rather than a recorded exemption, and the flag answers which skills are
+missing theirs without a caller listing the directory itself. Nothing gates the
+rule yet, which is why the flag is worth reading against the shipped corpus after
+a merge.
+
+## Non-interactive examples
+
+```bash
+# Create a new tooling stack
+AITK_NON_INTERACTIVE=1 aitk tooling create astro
+
+# Sync a stack into a target project
+AITK_NON_INTERACTIVE=1 aitk tooling sync astro /path/to/project
+
+# Install a governance stack (the stack argument is required headlessly)
+AITK_NON_INTERACTIVE=1 aitk gov install astro --add 260-shadcn /path/to/project
+
+# Update installed governance rules, dropping a retired .claude/GOV.md
+AITK_NON_INTERACTIVE=1 aitk gov sync /path/to/project
+
+# Concatenate installed rules into a paste payload
+AITK_NON_INTERACTIVE=1 aitk gov build /path/to/project
+
+# Sync a monorepo subtree, skipping the base layer the repo root already owns
+AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react /path/to/repo/frontend --skip base
+
+# Verify a stack end-to-end in a throwaway scaffold
+aitk tooling verify vite-react
+
+# Apply one stack without scanning or prompting, for scripted provisioning
+aitk tooling inject base /path/to/project
+aitk tooling inject base /path/to/project --configs --seeds
+
+# Drop managed gitignore entries a manifest no longer declares
+# Prints the number removed on stdout, diagnostics on stderr
+aitk tooling prune-gitignore base /path/to/project
+
+# Install a snippet preset
+AITK_NON_INTERACTIVE=1 aitk snippets install essentials /path/to/project
+
+# Update snippets already installed, leaving project-authored ones alone
+AITK_NON_INTERACTIVE=1 aitk snippets sync /path/to/project
+
+# Report standards drift without applying it, which is what headless does here
+AITK_NON_INTERACTIVE=1 aitk standards sync /path/to/project
+
+# Copy every standard into a target, overwriting what is there
+AITK_NON_INTERACTIVE=1 aitk standards install /path/to/project
+
+# Bootstrap a project. Any flag suppresses the confirmation prompt
+AITK_NON_INTERACTIVE=1 aitk init --stack astro --skip wiki /path/to/project
+
+# Run every domain sync. The git workflow is refused headlessly, so nothing is pushed
+AITK_NON_INTERACTIVE=1 aitk sync /path/to/project
+
+# Scaffold .claude/wiki/ with a stub index. The target must already exist
+AITK_NON_INTERACTIVE=1 aitk wiki init /path/to/project
+
+# Run a sandbox scenario non-interactively
+SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
+```

package/docs/agents/tasks.md

@@ -0,0 +1,33 @@
+---
+title: Tasks
+description: Selecting a shipped task by stem or pull request, the refusal reasons, and why the board root defaults to the main worktree
+---
+
+# Tasks
+
+`aitk tasks archive` moves a shipped task from `.claude/tasks/` into `.claude/.tmp/task-archive/`, drops its row from `priority.md`, and regenerates the board index. The three run as one unit, so the attended and unattended callers cannot archive differently.
+
+Name the task by its filename stem, or by the pull request it carries:
+
+```bash
+aitk tasks archive v28.1-trigger-escalation
+aitk tasks archive --pull-request 673 --json
+```
+
+| Option               | Behavior                                                     |
+| -------------------- | ------------------------------------------------------------ |
+| `--pull-request <n>` | Select the task whose `Pull request:` line names this number |
+| `--json`             | Emit a machine-readable record on stdout                     |
+| `--root <path>`      | Board root, defaulting to the main worktree                  |
+
+Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, or `plan-unswept`.
+
+The board is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree archives against the same board every other session reads.
+
+Skills branch on the reason rather than on the exit code:
+
+```bash
+aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
+```
+
+For the board format, the `Pull request:` line, and the archive rules, see `.claude/standards/tasks.md`.

package/docs/index.md

@@ -9,7 +9,6 @@ One-line reference for each doc in this folder.
 
 ## Agent surface
 
-- [Agents](agents.md): CLI catalog and invocation rules for agents
 - [AI workflow](ai-workflow.md): Overarching AI workflow across domains
 - [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
 
@@ -18,3 +17,7 @@ One-line reference for each doc in this folder.
 - [Operating model](operating-model.md): Orchestrator and worker roles for building across parallel sessions
 - [Visual design workflow](visual-design-workflow.md): Tiered guide for design and wireframe authoring with Claude Code
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations
+
+## Sub-catalogs
+
+- [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.

package/docs/target-projects.md

@@ -8,7 +8,7 @@ category: Agent surface
 
 How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
 
-This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
+This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents/index.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
 
 ## Getting the skills
 
@@ -179,7 +179,7 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 
 ## Related
 
-- [agents](agents.md): CLI flags, exit codes, and JSON output shapes
+- [agents](agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
 - [sandbox](../.claude/context/sandbox/index.md): scenario catalog for verifying domain flows

package/package.json

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

package/scripts/docs/list.sh

@@ -38,6 +38,35 @@ is_internal_topic() {
   esac
 }
 
+# Emits `name<TAB>description<TAB>category<TAB>target` per target-facing doc,
+# sorted so a domain split into a folder lands in its alphabetical place rather
+# than after every file. A folder declares its category on its own index, since
+# the allowlist is what separates a target-facing doc from a workflow one and a
+# split domain is not exempt from it.
+collect_docs() {
+  local file name description category
+  {
+    while IFS= read -r file; do
+      name=$(basename "$file" .md)
+      [ "$name" = "index" ] && continue
+      category=$(read_frontmatter_field "$file" "category")
+      is_target_facing "$category" || continue
+      description=$(read_frontmatter_field "$file" "description")
+      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name.md"
+    done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md")
+
+    # A split domain is named by its folder and described by its generated
+    # index, which carries subtitle where a sibling file carries description
+    while IFS= read -r file; do
+      name=$(basename "$(dirname "$file")")
+      category=$(read_frontmatter_field "$file" "category")
+      is_target_facing "$category" || continue
+      description=$(read_frontmatter_field "$file" "subtitle")
+      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name/index.md"
+    done < <(find "$DOCS_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
+  } | sort
+}
+
 # Emits `name<TAB>description<TAB>target` per context entry, sorted so a domain
 # split into a folder lands in its alphabetical place rather than after every
 # file. Matches listTopics in src/docs/read.ts, which sorts both together.
@@ -64,16 +93,11 @@ collect_context() {
 }
 
 list_text() {
-  local file name description category target
+  local name description category target
   log_step "Docs"
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    category=$(read_frontmatter_field "$file" "category")
-    is_target_facing "$category" || continue
-    description=$(read_frontmatter_field "$file" "description")
+  while IFS=$'\t' read -r name description category target; do
     log_info "$name : $description"
-  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  done < <(collect_docs)
 
   # Absent in a registry install, which ships docs/ without .claude/
   if [ -d "$CONTEXT_DIR" ]; then
@@ -97,17 +121,12 @@ emit_json_entry() {
 }
 
 list_json() {
-  local file name description category target
+  local name description category target
   JSON_FIRST=1
   printf '['
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    category=$(read_frontmatter_field "$file" "category")
-    is_target_facing "$category" || continue
-    description=$(read_frontmatter_field "$file" "description")
-    emit_json_entry "$name" "$description" "$category" "docs/$(basename "$file")"
-  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  while IFS=$'\t' read -r name description category target; do
+    emit_json_entry "$name" "$description" "$category" "$target"
+  done < <(collect_docs)
 
   if [ -d "$CONTEXT_DIR" ]; then
     while IFS=$'\t' read -r name description target; do

package/snippets/claude/orchestrator-handoff.md

@@ -0,0 +1,37 @@
+Write the pre-compact handoff as orchestrator. Do this before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them, and no other file in the repository carries that reasoning.
+
+1. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Write `.claude/tasks/session.md` under it.
+2. Write only what a compaction destroys and no other file already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a groundwork folder holds its track.
+3. Use this shape:
+
+```markdown
+---
+title: Session map
+description: <what the board cannot show, and the date it was written>
+---
+
+# Session map
+
+<one line marking the file throwaway and naming the board as the real source>
+
+## State
+
+<what is clean, what is running, what is open, and any untracked file that needs committing>
+
+## Decisions taken under delegated authority
+
+<each decision and why it went that way, so nobody re-proposes it>
+
+## Mistakes worth not repeating
+
+<what went wrong and the rule it yields>
+
+## Standing cautions
+
+<commands that lie, tools that measure the wrong tree, and anything unbacked>
+```
+
+4. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
+5. Overwrite the previous handoff rather than appending to it. A stale entry read as current is worse than no handoff.
+
+Add a section only for content that fits none of the four and would otherwise be lost. Do not restate the board, and do not summarize the work that shipped, because git already carries it.

package/src/commands/context.ts

@@ -408,6 +408,9 @@ function reportDepth(entries: readonly EntryReport[]): void {
   logInfo(
     `Fenced blocks are excluded, and so are peer lists averaging under ${PEER_BULLET_CHECKPOINT} characters a bullet.`,
   )
+  logInfo(
+    'A run that is entirely table rows is excluded too, since a heading inside a table splits the table rather than the run.',
+  )
 
   const over = entries
     .filter((entry) => entry.longestRun > RUN_CHECKPOINT)

package/src/commands/sandbox.ts

@@ -389,7 +389,7 @@ function runCheck(
 
   // The report always renders on stderr. `--json` adds the machine copy on
   // stdout rather than replacing the frame, per the stream contract in
-  // `docs/agents.md`, so one invocation serves a human and a caller at once.
+  // `docs/agents/output-shape.md`, so one invocation serves a human and a caller at once.
   reportVerdict(verdict)
   if (options.json === true)
     process.stdout.write(`${JSON.stringify(verdict)}\n`)

package/src/context/audit.ts

@@ -231,6 +231,36 @@ function isScannablePeerList(run: readonly BodyLine[]): boolean {
   return characters / items < PEER_BULLET_CHECKPOINT
 }
 
+/**
+ * Reports whether a run is a table, the second shape the checkpoint cannot fix.
+ *
+ * The peer list above is exempt because it is already navigable. A table is
+ * exempt for the other reason: the remedy does not exist. A heading dropped
+ * inside one splits the table into two tables rather than breaking the run, so
+ * a catalog renders as an unbroken stretch by construction and no edit short of
+ * rewriting it as a list clears the report.
+ *
+ * Every non-blank line has to be a row. A run holding a table between
+ * paragraphs is genuinely mixed, and a heading breaks it at a seam either side,
+ * so testing whether the run holds a table would hide the case the checkpoint
+ * exists for.
+ *
+ * A delimiter is required rather than assumed, matching the table scan below. A
+ * stack of lines opening with a pipe and no delimiter renders as paragraph text
+ * and would otherwise earn the exemption on its punctuation.
+ */
+function isTableRun(run: readonly BodyLine[]): boolean {
+  let separators = 0
+
+  for (const line of run) {
+    if (line.text.trim() === '') continue
+    if (!TABLE_ROW.test(line.text)) return false
+    if (TABLE_SEPARATOR.test(line.text)) separators++
+  }
+
+  return separators > 0
+}
+
 /**
  * Height a source line occupies once wrapped.
  *
@@ -272,7 +302,7 @@ function longestRun(lines: readonly BodyLine[]): {
     // two headings rather than a stretch a reader travels, so it never counts.
     const first = run.find((line) => line.text.trim() !== '')
 
-    if (first && !isScannablePeerList(run)) {
+    if (first && !isScannablePeerList(run) && !isTableRun(run)) {
       const height = run.reduce(
         (sum, line) => sum + renderedHeight(line.text),
         0,

package/src/ui.ts

@@ -31,7 +31,7 @@ export function logRemove(message: string): void {
 }
 
 /**
- * Renders the `✗` shape `docs/agents.md` specifies for a failure inside an
+ * Renders the `✗` shape `docs/agents/output-shape.md` specifies for a failure inside an
  * open frame. It does not exit, so the caller closes the frame and returns an
  * exit code rather than terminating mid-write.
  */

package/standards/context.md

@@ -104,6 +104,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
 - Both checkpoints count rendered lines, so wrap each source line at 80 columns and sum the heights. Source lines undercount an entry authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. Counting the two checkpoints in different units would put a file measured one way beside a run measured another.
 - Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides. Mixing prose with the list, or nesting levels inside it, ends the exemption at any weight.
+- Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint. Prose either side of the table ends the exemption, since that block has a seam and a heading breaks it there.
 - Past roughly 400 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, check whether the incident that motivated the decision sits beside the decision itself. Keep the current design and the alternative that lost, and move the incident to the change that introduced it, the issue that tracked it, or the research record behind it. The number is a checkpoint like the two above, and a bullet reading well past it means the number is wrong rather than the rule.
 - Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.