@erclx/aitk 3.6.0 → 3.8.0

package/claude/skills/toolkit-feedback/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: toolkit-feedback
-description: Format a paste-back report about something broken, missing, or off in aitk and write it directly to the toolkit's `.claude/review/` folder via `aitk feedback`. Use when asked to "send this to the toolkit", "report this to aitk", "file toolkit feedback", or "give the toolkit feedback about X". Do NOT use for general complaints about other tooling, IDE issues, or in-project bugs that do not implicate aitk surfaces.
+description: Format a paste-back report about something broken, missing, or off in aitk and write it directly to the toolkit's `.claude/review/feedback/` folder via `aitk feedback`. Use when asked to "send this to the toolkit", "report this to aitk", "file toolkit feedback", or "give the toolkit feedback about X". Do NOT use for general complaints about other tooling, IDE issues, or in-project bugs that do not implicate aitk surfaces.
 ---
 
 # Toolkit feedback
@@ -48,7 +48,7 @@ Detect whether `aitk` is on PATH:
 command -v aitk >/dev/null 2>&1
 ```
 
-If present, pipe the block to `aitk feedback`. The CLI writes to its own repo's `.claude/review/feedback-<slug>-<ts>.md` and prints the absolute path on stdout:
+If present, pipe the block to `aitk feedback`. The CLI writes to its own repo's `.claude/review/feedback/feedback-<slug>-<ts>.md` and prints the absolute path on stdout:
 
 ```bash
 cat <<'EOF' | aitk feedback

package/claude/skills/write-human/REQUIREMENT.md

@@ -41,6 +41,6 @@ Importing that catalog wholesale fails on a different measurement. External mate
 
 - The banned words, characters, and spellings, which `markdown.md` states for a reader and `aitk markdown audit` gates from package data
 - Markdown mechanics, being headings, lists, code spans, punctuation, and file references
-- Restating text that already exists in plainer words, which is a different job on a different trigger, since a restatement is asked for by name and this arrives on a glob match
+- Restating text that already exists in plainer words, which `restate` owns on a different trigger, since a restatement is asked for by name and this arrives on a glob match. The rules here still govern how that restatement reads, and that body cites this one rather than carrying a copy.
 - What voice a given surface declares, which belongs to the standard governing that surface
 - Measuring whether finished output followed these rules, which needs a check this skill does not carry

package/claude/skills/write-human/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-human
-description: Carries the voice, rhythm, sentence construction, and information density rules a banned-word list cannot express, plus the catalog of machine tells that survive a clean ban scan. Use when writing or revising prose a person will read, when a passage reads flat or uniform, or when asked to "make this read like a person", "fix the cadence", "this reads like AI wrote it", "vary the sentences", or "tighten this without gutting it". Do NOT use for banned words, characters, or spellings, which `markdown.md` states and `aitk markdown audit` gates, and do NOT use to restate text that already exists in plainer words.
+description: Carries the voice, rhythm, sentence construction, and information density rules a banned-word list cannot express, plus the catalog of machine tells that survive a clean ban scan. Use when writing or revising prose a person will read, when a passage reads flat or uniform, or when asked to "make this read like a person", "fix the cadence", "this reads like AI wrote it", "vary the sentences", or "tighten this without gutting it". Do NOT use for banned words, characters, or spellings, which `markdown.md` states and `aitk markdown audit` gates, and do NOT use to restate text that already exists in plainer words, which is `restate`, whose body loads these rules from here.
 ---
 
 # Write human

package/docs/agents/capture.md

@@ -32,4 +32,6 @@ What is asserted is the font. The command reads the first family the captured el
 
 The browser binary installs separately from the package. A fresh clone runs `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
 
-The command is toolkit-only. Its render module holds every browser reference in the toolkit and `files` in `package.json` excludes it, so an installed `aitk` carries the command, reports it as absent on one line, and exits 1. Every other command is unaffected, which is the reason the browser import sits behind a dynamic import rather than at a command's top level.
+The command is toolkit-only. Its render module holds every browser reference capture makes and `files` in `package.json` excludes it, so an installed `aitk` carries the command, reports it as absent on one line, and exits 1. Every other command is unaffected, which is the reason the browser import sits behind a dynamic import rather than at a command's top level.
+
+`aitk demo` is the other browser command and it ships, because the reason capture stays here is that it regenerates images committed to this repository and a target has nothing to regenerate. See `demo.md`.

package/docs/agents/commands.md

@@ -24,7 +24,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                              |
 | `aitk slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                                                                     |
 | `aitk slides list`         | List the available slide layouts (`--json` for the catalog)                                                                                    |
-| `aitk feedback`            | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github`                                                 |
+| `aitk feedback`            | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github`                                        |
 | `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                          |
 | `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                            |
 | `aitk tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                       |
@@ -47,6 +47,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                 |
 | `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)      |
 | `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one                                    |
+| `aitk claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                 |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                             |
 | `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                          |
@@ -57,30 +58,33 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                          |
 | `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                          |
 
+`aitk demo` is the second browser command and the one that ships, since its purpose is running in a target rather than regenerating what this repository commits. It needs a browser binary the package does not carry, installed once with `bunx playwright install chromium`.
+
 ## Domain commands
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
 
-| Domain      | Subcommands                                                                                                 |
-| ----------- | ----------------------------------------------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                      |
-| `snippets`  | `list`, `install`, `sync`, `create`                                                                         |
-| `standards` | `list`, `<name>`                                                                                            |
-| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                     |
-| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
-| `wiki`      | `init`                                                                                                      |
-| `design`    | `render`                                                                                                    |
-| `slides`    | `render`, `list`                                                                                            |
-| `tasks`     | `archive`, `validate`                                                                                       |
-| `intake`    | `list`, `answer`                                                                                            |
-| `teach`     | `list`, `open`, `resource`, `glossary`                                                                      |
-| `comments`  | `scan`                                                                                                      |
-| `context`   | `audit`                                                                                                     |
-| `markdown`  | `audit`                                                                                                     |
-| `secrets`   | `scan`                                                                                                      |
-| `deps`      | `audit`                                                                                                     |
-| `labels`    | `audit`                                                                                                     |
-| `audits`    | `run`, `list`                                                                                               |
+| Domain      | Subcommands                                                                                                            |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                 |
+| `snippets`  | `list`, `install`, `sync`, `create`                                                                                    |
+| `standards` | `list`, `<name>`                                                                                                       |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                |
+| `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
+| `demo`      | `compile`, `run`                                                                                                       |
+| `wiki`      | `init`                                                                                                                 |
+| `design`    | `render`                                                                                                               |
+| `slides`    | `render`, `list`                                                                                                       |
+| `tasks`     | `archive`, `validate`                                                                                                  |
+| `intake`    | `list`, `answer`                                                                                                       |
+| `teach`     | `list`, `open`, `resource`, `glossary`                                                                                 |
+| `comments`  | `scan`                                                                                                                 |
+| `context`   | `audit`                                                                                                                |
+| `markdown`  | `audit`                                                                                                                |
+| `secrets`   | `scan`                                                                                                                 |
+| `deps`      | `audit`                                                                                                                |
+| `labels`    | `audit`                                                                                                                |
+| `audits`    | `run`, `list`                                                                                                          |
 
 Common patterns:
 

package/docs/agents/demo.md

@@ -0,0 +1,82 @@
+---
+title: Demo
+description: 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
+---
+
+# Demo
+
+`aitk demo` drives a project's running application and writes a recording of what it did, plus a still frame of the same run. It exists so a project card and a short demo stop depending on someone sitting down to record one by hand.
+
+Two verbs, and they are separate because the artifact between them is edited.
+
+```bash
+aitk demo compile .claude/.tmp/screencast/inline-edit.md
+aitk demo run demos/inline-edit.json
+aitk demo run demos/inline-edit.json --cursor ~/cursors/theme --out assets
+```
+
+## The draft and the plan are different files
+
+`claude-screencast` drafts beats for a person. A beat carries what is on screen, one verb, what to watch for, an emphasis, and a caption, and none of that names a selector, a URL, a wait condition, or a timing. Those four are what an executor needs and what would ruin the draft, since the format is pre-seeded so the operator edits down rather than fills blanks.
+
+So `aitk demo compile` writes a second artifact rather than adding fields to a beat. It maps each beat's verb to a step, seeds the timing, marks which beat the still comes from, and leaves the target and the URL empty for a person to fill. The report names every field it could not supply.
+
+The plan is committed, not scratch. Its timing is a starting point tuned by watching a recording, and the draft cannot reproduce a tuned value, so a recompile over an existing plan refuses and names `--force`.
+
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--out <dir>`   | Directory the plan and its output paths point at, default `demos` |
+| `--slug <slug>` | Plan name, defaulting to the draft filename                       |
+| `--force`       | Overwrite an existing plan, losing any timing tuned by hand       |
+| `--json`        | Add a record on stdout carrying the beats and what is unfilled    |
+
+## What a run does
+
+`aitk demo run` reads the plan, refuses if a field is still empty, and drives the application the plan's URL names. It records the whole run to `webm` and writes the still from the beat the draft calls the hero, falling back to the last beat, since a demo's final state is the payoff and a cold open is usually an empty screen.
+
+| Option           | Behavior                                                    |
+| ---------------- | ----------------------------------------------------------- |
+| `--out <dir>`    | Directory to write into, overriding what the plan names     |
+| `--cursor <dir>` | Cursor theme folder to draw the pointer from                |
+| `--no-video`     | Write only the still                                        |
+| `--no-still`     | Write only the recording                                    |
+| `--json`         | Add a record on stdout carrying both paths and the duration |
+
+A step waits on its `waitFor` selector becoming visible and then holds for its own `holdMs`, which is what puts a finished state on screen long enough to read. `navigate` uses the plan's URL unless the step names its own.
+
+## The pointer is painted inside the page
+
+The browser engine's own annotation draws a red dot at the moment of a click and an action label in a corner. It paints no cursor, so a run without more looks like the pointer teleports between targets.
+
+The recorder injects a pointer element before navigation and moves it through the engine's pointer with interpolated steps rather than through the element-clicking helper, which resolves a target and jumps to it. The step count is the whole difference between a cursor that travels and one that appears. The pointer reads the element under it on every move and switches between an arrow, a hand, and a text beam, so it reflects the page the way a real cursor does.
+
+`--cursor` points at a folder of Windows cursor resources and the browser decodes them directly, with no conversion step and no image tooling. Each resource carries a hotspot per size, and the largest entry's hotspot scaled to the drawn size is what puts the artwork's tip where the click lands. A theme contributes per state, so a folder holding an arrow and no hand still supplies its arrow and the bundled artwork covers the rest.
+
+Three of the nineteen states a theme carries are read. A drag, a resize, or a wait shows the arrow where a real session would show something else, and the two animated states have no still frame to draw.
+
+## What the refusals report
+
+Every refusal exits 1 and names its reason in the `--json` record, so a skill branches on `reason` rather than on the exit code.
+
+| Reason                | What happened                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `draft-missing`       | No file at the path given to `compile`                                              |
+| `draft-unreadable`    | The draft carries no beat sheet, or a sheet with no beats                           |
+| `plan-exists`         | A plan is already there and `--force` was not passed                                |
+| `plan-unresolved`     | A URL or a target is still empty, named field by field                              |
+| `no-output-requested` | `--no-video` and `--no-still` together, which would drive the app and write nothing |
+| `plan-unreadable`     | The plan is not JSON, or a step names a kind nothing drives                         |
+| `browser-missing`     | The browser binary is not installed, with `install` carrying the command            |
+| `engine-missing`      | The browser package itself did not resolve                                          |
+
+## The browser reaches every target
+
+Unlike `aitk capture`, this command ships. Capture is toolkit-only because it regenerates images committed to this repository, and that reason does not transfer to a command whose whole purpose is running in someone else's project.
+
+The cost is stated rather than hidden: the browser binary installs separately, so a target runs `bunx playwright install chromium` once before a recording works at all. A run that cannot launch reports that command inside the frame and exits 1.
+
+## What it does not do
+
+A generated recording is a raw take. Nothing trims it, scores it, or narrates it, and the beat's caption does not reach the video, since the engine's overlay carries the action it performed rather than text from the draft.
+
+It also does not replace a narrated screencast. That has a hero moment, a cut list, and a voice, none of which survives being generated. This answers the case where the alternative is recording nothing.

package/docs/agents/index.md

@@ -14,6 +14,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
 - [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length gate and claim coverage, which folders each check reaches, and what moved to the attribute tier
 - [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
+- [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
 - [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
@@ -23,6 +24,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on

package/docs/agents/install-and-sync.md

@@ -11,7 +11,9 @@ The behavior notes behind the verbs listed in `commands.md`. Each one records wh
 
 `aitk gov sync` updates only rules already present under `.claude/rules/` and
 never adds new ones. A rule the toolkit does not ship is left alone, which is
-how project-authored rules survive. It also removes a stale `.claude/GOV.md`
+how project-authored rules survive, and one under `.claude/rules/project/`
+is left alone regardless of its name, since that subfolder is project-authored
+by location. It also removes a stale `.claude/GOV.md`
 from the retired build. Use `aitk gov install` to add rules.
 
 There is no `aitk standards sync` and no `aitk standards install`. The corpus
@@ -23,7 +25,9 @@ the catalog.
 `aitk snippets sync` matches by path relative to `.claude/snippets/`. It
 matches by path relative to that directory, so a snippet the toolkit no longer
 ships, or one authored directly in the target, is reported and skipped rather
-than deleted. It is not preset-aware, so a project that installed `essentials`
+than deleted, and a snippet under `.claude/snippets/project/` skips the same
+way regardless of path, since that subfolder is project-authored by location.
+It is not preset-aware, so a project that installed `essentials`
 does not grow new snippets on a sync. Use `aitk snippets install` to add them.
 
 ## Install guards

package/docs/agents/records.md

@@ -110,7 +110,7 @@ aitk records push --json
 aitk records pull
 ```
 
-The backed folders are `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `review-archive`, `task-archive`, `tasks`, and `teach`, all under `.claude/`. They are the Claude ignore group the claude manifest ships, minus three entries: `.claude/.tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.claude/.records.git/`, which is the history the other ten are pushed into. The list is a constant rather than configuration, matching the four folder names `validate` hardcodes.
+The backed folders are `groundwork`, `intake`, `memory`, `plans`, `review`, `tasks`, and `teach`, all under `.claude/`. They are the Claude ignore group the claude manifest ships, minus three entries: `.claude/.tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.claude/.records.git/`, which is the history the other seven are pushed into. Each name is a top-level record folder and every archive sits inside the one it archives, so the list stays at one entry per surface however many archives appear. It is a constant rather than configuration, matching the six record kinds `validate` hardcodes.
 
 Records are gitignored by design, so the history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the ten folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched.
 
@@ -145,4 +145,4 @@ The two `pull` refusals exist because the directions are not symmetric. A push o
 
 ### When it runs
 
-`.husky/post-merge` runs `push` after the task-archive loop, on every merge rather than only on one that archived a task. A review report and a memory entry both land on runs that close nothing. The call sits inside an `if` and last in the file, so an unreachable remote neither aborts the hook nor delays the archiving above it, and a checkout that never ran the setup reports nothing. Anything the hook misses is covered by running the verb by hand.
+`.husky/post-merge` runs `push` after the task archiving loop, on every merge rather than only on one that archived a task. A review report and a memory entry both land on runs that close nothing. The call sits inside an `if` and last in the file, so an unreachable remote neither aborts the hook nor delays the archiving above it, and a checkout that never ran the setup reports nothing. Anything the hook misses is covered by running the verb by hand.

package/docs/agents/routing.md

@@ -0,0 +1,61 @@
+---
+title: Routing report
+description: Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
+---
+
+# Routing report
+
+`aitk claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the tier test in `.claude/rules/claude/592-claude-md.md`, which asks whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted.
+
+```bash
+aitk claude routing
+aitk claude routing --json
+aitk claude routing ../my-app
+```
+
+| Option   | Behavior                                                     |
+| -------- | ------------------------------------------------------------ |
+| `[path]` | Repository root to read, defaulting to the current directory |
+| `--json` | Add a machine-readable record on stdout, keeping the frame   |
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
+
+The root is the argument rather than the toolkit, matching the reach and drift verbs, so a linked worktree reads its own branch and a target reads its own file.
+
+## What it reads
+
+Every H2 and H3 owning at least one top-level bullet. An H3 is reported under the H2 containing it, as `Behavior / Scope discipline`, so a section and its subsections are counted apart rather than summed.
+
+Three things are read past. A nested bullet belongs to the one above it rather than to the section. A bullet inside a fenced block is example text rather than instruction. A heading carrying no bullet answers nothing the report asks, so it is dropped rather than listed at zero.
+
+## What counts as naming a path
+
+A bullet is path-scoped here when it names a path. That is evidence for the tier judgment rather than the judgment itself, and the gap runs both ways: a bullet naming a folder can still apply every session, and one firing on a path it never spells is invisible to the count. Read a section's number as a place to look rather than as a verdict on it.
+
+A backticked token counts when it carries a separator or an alphabetic extension, which admits `src/cli.ts` and `cspell.json` while leaving a flag, a bare word, and a version string out.
+
+A shape counts as the folder above its placeholder. `.claude/context/<domain>.md` names `.claude/context/` and nothing narrower, so dropping the token whole would report the section carrying it as naming no path at all. A placeholder opening the first segment has no openable prefix and is dropped.
+
+## When a rule counts as covering it
+
+A rule covers a named path only when its glob anchors to a location. A glob opening `**` reaches every folder in the tree, so it answers that a file type is governed and never that a named path is.
+
+The corpus-wide markdown rules are what force that. Counting one reports every markdown path as covered, which collapses the column to a constant and tells a reader nothing about which folder somebody actually scoped a rule to.
+
+A folder is probed with a handful of extensions rather than matched literally, because a glob narrowed by file type reaches under a folder without ever matching the folder's own name. Globs are read from each rule's frontmatter block alone, so a rule quoting a path in its body does not register a scope it never declared.
+
+The paths a section names that no rule reaches are listed beside it, which is where a reader looks first when deciding what a new rule would cover.
+
+## Refusals
+
+Two, each naming what a reader does about it. `no-claude-md` is a tree with no always-loaded file. `no-rules` is a tree carrying no path-scoped rule under `.claude/rules/`, where every path would report as uncovered and the column would say nothing.
+
+An always-on rule declaring no `paths` is skipped rather than refused. It applies at the same priority as the always-loaded file, so it covers no path in particular.
+
+## Exit codes
+
+Exit codes are `0` when the file was read and `1` for a refusal. No finding moves the exit code.
+
+Nothing wires this into `bun run check` or into a hook. Whether a bullet belongs in a rule is a judgment, and gating a measure that counts a judgment forces an escape hatch for every deliberate case.
+
+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 JSON record's `sections` array rather than the exit when a skill consumes this.

package/docs/agents/tasks.md

@@ -7,7 +7,7 @@ description: Selecting a shipped task by stem or pull request, recording a numbe
 
 ## Archive
 
-`aitk tasks archive` moves a shipped task from `.claude/tasks/` into `.claude/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.
+`aitk tasks archive` moves a shipped task from `.claude/tasks/` into `.claude/tasks/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:
 

package/docs/ai-workflow.md

@@ -71,7 +71,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 
 - Create a worktree per feature, then start a Claude Code session in each
 - Invoke `aitk:claude-feature` in each session. Plans land at the main worktree root as `.claude/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
-- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review-<slug>.md`, `ui-checklist-<slug>.md`), so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
+- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review/branch/review-<slug>.md`, `review/ui-checklist-<slug>.md`), so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `aitk:git-ship`
 - For full autonomy per worktree, invoke `aitk:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
 
@@ -93,15 +93,17 @@ An execution that picks other than the suggestion rewrites the `- Suggested:` li
 
 `aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, `memory`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all five folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
-`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Ten of them are backed: `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `review-archive`, `task-archive`, `tasks`, and `teach`. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
+`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Seven of them are backed: `groundwork`, `intake`, `memory`, `plans`, `review`, `tasks`, and `teach`, each carrying whatever it has archived inside it. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
 
 A person points it at a private repository once and both verbs refuse until they have, and `push` refuses when that origin is also a remote of the project, since the payload is the memory pen and the groundwork trails. `.husky/post-merge` runs the push after its archive loop, on every merge rather than only on one that closed a task. See [records](agents/records.md) for the refusal table.
 
 `aitk records size` reports what each of these folders holds, heaviest first, along with `.claude/.tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
 
-A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
+A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans/archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
-The sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.
+A branch review report takes the other route and is swept rather than archived. `claude-review` writes it to `.claude/review/branch/`, the session addressing it reads it once, and the durable record of what a review found is the comment `claude-pr-review` posts on the pull request, so `claude-docs` deletes the report at ship and any report whose branch is gone. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
+
+The plans sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.
 
 `aitk:claude-docs` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
 
@@ -111,7 +113,7 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and no two rows marked ready touch the same file. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
 
-`aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
+`aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/tasks/archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 
 Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses the last task pointing at a live plan. The sweep only reaches tasks still in the live folder, and archiving that task first would strand the plan there with nothing citing it. A task whose plan a sibling still cites archives freely, because the sweep is correct to leave that plan where it is and a gate reading the folder instead would park every task sharing one plan behind a sweep that will never move it.
 
@@ -286,6 +288,7 @@ This section is the corpus the coverage claim is measured against: every name `a
 | `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               |
 
 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/operating-model.md

@@ -101,13 +101,22 @@ closed clean and then went stale still rebases when the skill is invoked. The
 re-read costs a full pass rather than a delta, since the prior reviewed commit no
 longer reaches the head, and `claude-pr-review` detects that itself.
 
-The heading carries the state rather than the pass number. A pass carrying a
-finding at any severity takes `## Review` and a pass carrying nothing takes
+The heading carries the state rather than the pass number. A pass carrying
+anything owed takes `## Review` and a pass carrying nothing takes
 `## Review closed`, so a thread can be scanned for what still owes work without
 opening a comment. One threshold governs the heading and the dispatch alike, and
 `claude-pr-review` is where it is stated, so every other surface cites that skill
-rather than restating the grades. The merge decision comes off the counts on the
-summary line, since an open heading now covers a minor as well as a critical.
+rather than restating the grades.
+
+The merge decision comes off the counts on the summary line, since an open
+heading now covers a minor as well as a critical. One thing the pass posts sits
+outside those counts and inside the threshold anyway. It reads the description's
+Testing section against what the repository can drive, and asks about a box left
+unchecked for a person where a harness already covers the run. The question
+takes no severity, because whether a human is required is a judgment the author
+may hold a reason for, and it still opens the heading and sends the dispatch,
+because the author is the only party who can answer it.
+
 A minor the worker declines goes to the findings of the task the
 branch closes, since a thread does not survive the merge. The feedback
 becomes a durable artifact both sessions read, survives a session ending, and

package/governance/rules/claude/558-plan.md

@@ -2,7 +2,6 @@
 description: Route .claude/plans/ edits to the plan standard for sections, the answer contract, and the archive move
 paths:
   - '.claude/plans/**'
-  - '.claude/plans-archive/**'
 ---
 
 # Plan standards
@@ -15,7 +14,7 @@ paths:
 
 ## Archiving
 
-- Move a shipped plan to `.claude/plans-archive/`. Never delete one.
+- Move a shipped plan to `.claude/plans/archive/`. Never delete one.
 - Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
 
 ## Authority

package/governance/rules/lib/300-testing-ts.md

@@ -22,6 +22,7 @@ paths:
 - Use Playwright for end-to-end tests.
 - Place all Playwright tests within the `e2e/` directory.
 - Never place Playwright tests inside `src/`.
+- Scope the three rules above to tests the Playwright runner executes. A Vitest test importing a browser driver to exercise project code stays beside its module, where Vitest looks for it.
 
 ## Timers and async
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -46,6 +46,7 @@
   "dependencies": {
     "commander": "^13.1.0",
     "execa": "^9.5.2",
+    "playwright-core": "1.59.1",
     "pptxgenjs": "^4.0.1"
   },
   "devDependencies": {
@@ -53,7 +54,7 @@
     "@astrojs/react": "^5.0.4",
     "@commitlint/cli": "^20.4.1",
     "@commitlint/config-conventional": "^20.4.1",
-    "@playwright/test": "^1.59.1",
+    "@playwright/test": "1.59.1",
     "@tailwindcss/vite": "^4.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@types/bun": "^1.2.10",