@erclx/aitk 0.21.0 → 0.22.1

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

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

package/claude/skills/claude-address-review/REQUIREMENT.md

@@ -17,6 +17,7 @@ Without this skill, review findings are worked in whatever order the author read
 - Push before replying, so the comment never runs ahead of the code it describes
 - Map every finding to what changed, or to a one-line reason when it is a question or a conscious accept
 - Post the terminal comment only when the findings are addressed and every check passes
+- Scan the reply for banned characters and internal phase labels before posting, since the comment leaves for the remote unchecked
 
 ## Must not
 

package/claude/skills/claude-address-review/SKILL.md

@@ -73,9 +73,10 @@ bullet per finding, each opening with the bolded finding identifier.
 Close the body with `🤖 Addressed by Claude Code` on its own line so the reply
 reads as an independent machine pass, not a human sign-off.
 
-Before posting, run the banned-character scan in `.claude/standards/prose.md`
-against the reply. The hook skips `.claude/.tmp/`, so this scan is the only gate
-on the published reply. Post it to the PR:
+Before posting, run the pre-publish scan in `.claude/standards/prose.md`
+against the reply, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the
+project does not have it. The hook skips `.claude/.tmp/`, so this scan is the
+only gate on the published reply. Post it to the PR:
 
 ```bash
 gh pr comment <number> --body-file .claude/.tmp/address-review/reply-<number>.md

package/claude/skills/claude-diagram/SKILL.md

@@ -80,7 +80,7 @@ The code paths the explanation cites are what the `claude-docs` sweep watches fo
 
 Quote node labels containing spaces or special characters with double quotes (`A["Web shell"]`). Avoid parentheses inside labels, they break some renderers. Use `<br/>` for line breaks inside labels.
 
-Run the banned-character scan in `.claude/standards/prose.md` against the whole file, including inside mermaid `subgraph` labels and node text, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. A colon also works as a replacement inside a label. The pedagogical voice the diagram standard asks for is a yield on voice alone and buys no exemption from these bans.
+Run the pre-publish scan in `.claude/standards/prose.md` against the whole file, including inside mermaid `subgraph` labels and node text, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. The file lands in the repository rather than on a remote, so the scan's destination scoping leaves the character checks and not the phase-label one. A colon also works as a replacement inside a label. The pedagogical voice the diagram standard asks for is a yield on voice alone and buys no exemption from these bans.
 
 Nothing enforces the ban inside the diagram. The standards-audit hook toggles on a fence and skips every line within it, so a label carrying an em dash passes silently while the same character in the explanation paragraph below is caught. Check the labels by reading them. This is the one place in the file where the author is the only gate.
 

package/claude/skills/claude-pr-review/REQUIREMENT.md

@@ -17,6 +17,7 @@ Without this skill, a pull request is reviewed only by the session that wrote it
 - Apply the integration, contract, and consumer lenses a self-review structurally cannot
 - Post a close-out even with nothing to report, since a first pass left unanswered reads as a review nobody closed
 - Key the body file on both the pull request number and the head commit, so no two passes overwrite each other
+- Scan the comment for banned characters and internal phase labels before posting, since a finding phrased against a phase label reaches a reader with no task board
 
 ## Must not
 

package/claude/skills/claude-pr-review/SKILL.md

@@ -131,7 +131,7 @@ The `What is right` section is optional, capped at three bullets, and included o
 
 Close the body with `🤖 Reviewed by Claude Code` on its own line so the review reads as an independent machine pass, not a human sign-off.
 
-Before posting, run the banned-character scan in `.claude/standards/prose.md` against the body. The hook skips `.claude/.tmp/`, so this scan is the only gate on the published comment.
+Before posting, run the pre-publish scan in `.claude/standards/prose.md` against the body, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. The hook skips `.claude/.tmp/`, so this scan is the only gate on the published comment. A finding phrased against an internal phase label is what the label half of the scan catches here.
 
 ```bash
 gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>-<short-sha>.md

package/claude/skills/git-followup/REQUIREMENT.md

@@ -14,7 +14,7 @@ Without this skill, an edit made after a pull request is already open ships as a
 - Refuse unless the branch has an upstream and an open pull request, since every later step addresses one of the two
 - Delegate the message to `git-commit` rather than composing one, so a follow-up commit reads like every other commit
 - Sync the body when the new commit moves the scope, and the title when the shift makes it inaccurate
-- Reply on the pull request when it carries review comments, and scan that reply for the banned characters before posting. The hook watches files and never sees a comment body on its way to the remote.
+- Reply on the pull request when it carries review comments, and scan that reply for the banned characters and internal phase labels before posting. The hook watches files and never sees a comment body on its way to the remote.
 - Suppress the reply when the caller owns it, and still run the push and the body sync
 
 ## Must not

package/claude/skills/git-followup/SKILL.md

@@ -24,7 +24,7 @@ its own reply, so skip the comment in step 6. The push and body sync still run.
 3. Invoke `aitk:git-commit` to generate one conventional commit from the staged diff
 4. Run `git push` to the tracking branch
 5. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
-6. When invoked with `reply-owned`, skip this step's comment: the caller posts the reply. Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first running the banned-character scan in `.claude/standards/prose.md` against it, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it, since the hook does not see an inline comment body. If it is zero, run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
+6. When invoked with `reply-owned`, skip this step's comment: the caller posts the reply. Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first running the pre-publish scan in `.claude/standards/prose.md` against it, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it, since the hook does not see an inline comment body. If it is zero, run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
 
 ## After completion
 

package/claude/skills/git-issue/REQUIREMENT.md

@@ -13,7 +13,7 @@ Without this skill, an issue takes the shape of whatever the session was saying.
 
 - Read the issue reference and the prose standard before formatting
 - Confirm a remote and an authenticated `gh` before composing, so the failure lands before a body is written rather than after
-- Scan the title and body for banned characters as an explicit step. Reading the standard does not catch them, because the text is generated after the read.
+- Scan the title and body for banned characters and internal phase labels as an explicit step. Reading the standard does not catch them, because the text is generated after the read.
 - Map the type to exactly one label, so filing and filtering agree
 - Ask once when the type is ambiguous between a bug and a task, since the label follows from it and a wrong label buries the issue
 - Pass the body through a file and remove it afterward, so shell quoting cannot mangle it

package/claude/skills/git-issue/SKILL.md

@@ -40,7 +40,7 @@ After outputting the preview, execute the final command immediately. Claude Code
 
 ### Pre-publish scan
 
-Before running the final command, run the banned-character scan in `.claude/standards/prose.md` against the title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/issue.md`.
+Before running the final command, run the pre-publish scan in `.claude/standards/prose.md` against the title and body, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/issue.md`.
 
 ### Final command
 

package/claude/skills/git-pr/REQUIREMENT.md

@@ -15,7 +15,7 @@ Without this skill, a pull request body is written from memory of the branch rat
 - Derive the title and body from the commits and the diff against main, with lockfiles excluded
 - Run each check before writing its line, then state the result the run reported
 - Leave a box unchecked only for a human-only case, naming which human and why on the same line
-- Scan the title and body for banned characters as an explicit step, on top of reading the prose standard
+- Scan the title and body for banned characters and internal phase labels as an explicit step, on top of reading the prose standard
 - Detect an open pull request and edit it in place, so a follow-up push keeps the body in sync instead of failing
 
 ## Must not

package/claude/skills/git-pr/SKILL.md

@@ -69,7 +69,7 @@ Leave a box unchecked only for the human-only cases the reference defines, and n
 
 ### Pre-publish scan
 
-Before running the final command, run the banned-character scan in `.claude/standards/prose.md` against the PR title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/pr.md`.
+Before running the final command, run the pre-publish scan in `.claude/standards/prose.md` against the PR title and body, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/pr.md`.
 
 ### Final command
 

package/claude/skills/git-split/REQUIREMENT.md

@@ -17,7 +17,7 @@ Without this skill, a branch carrying unrelated commits ships as one pull reques
 - Account for every commit ahead of main in the preview
 - State the merge order and the reason behind it, since the order is not recoverable from reading the pull requests afterward
 - Carry the restack loop for stacked mode, where each branch is rebased onto main once the one below it merges
-- Scan every generated title and body for banned characters as an explicit step before opening a pull request
+- Scan every generated title and body for banned characters and internal phase labels as an explicit step before opening a pull request
 
 ## Must not
 

package/claude/skills/git-split/SKILL.md

@@ -69,7 +69,7 @@ If Mode is Independent, append this line to the preview:
 
 After outputting the preview, execute the final commands immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 
-Before running them, run the banned-character scan in `.claude/standards/prose.md` against every title and body, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. Each body stages under `.claude/.tmp/` and leaves through `gh`, so the hook sees neither and this scan is the only gate.
+Before running them, run the pre-publish scan in `.claude/standards/prose.md` against every title and body, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. Each body stages under `.claude/.tmp/` and leaves through `gh`, so the hook sees neither and this scan is the only gate.
 
 ### Final commands
 

package/docs/agents.md

@@ -66,7 +66,7 @@ Full help: `aitk <command> --help`.
 | `aitk init [path]`       | Bootstrap a project with selected toolkit domains                                              |
 | `aitk sync [path]`       | Sync all installed domains in a target project                                                 |
 | `aitk sync --check`      | Report toolkit drift without writing (`--json`, `--exit-code`)                                 |
-| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed)                                                  |
+| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads             |
 | `aitk sandbox reset`     | Reset sandbox to baseline                                                                      |
 | `aitk sandbox clean`     | Wipe the sandbox                                                                               |
 | `aitk sandbox check`     | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)          |
@@ -189,7 +189,7 @@ inside an already-open frame.
 
 ### Sandbox 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. Route non-interactively with `SANDBOX_SCENARIO`:
+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
@@ -222,7 +222,7 @@ Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a ma
 
 ### 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.
+`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

package/docs/target-projects.md

@@ -77,7 +77,7 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 `governance`, `standards`, and `wiki` are skippable:
 
 - `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/prose.md` lands with nothing pointing at it and no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
-- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root. That fallback now carries runtime behavior rather than reference prose alone, because the banned-character scan and the branch-slug transform are defined in the standards and cited by the skills that run them.
+- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root. That fallback now carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform are defined in the standards and cited by the skills that run them.
 - `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
 
 ## Add a domain later

package/package.json

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

package/src/commands/sandbox.ts

@@ -17,6 +17,7 @@ import {
   type Verdict,
 } from '@/sandbox/expect'
 import {
+  frameError,
   intro,
   logError,
   logInfo,
@@ -29,6 +30,34 @@ import {
 
 const SANDBOX_DIR = join(PROJECT_ROOT, 'scripts', 'sandbox')
 
+/**
+ * Reports that the scenario tree does not ship, and answers whether it reported,
+ * so a caller that sees `true` returns without touching the tree.
+ *
+ * `scripts/sandbox` is excluded from the published package, so an installed
+ * `aitk` resolves `SANDBOX_DIR` to a directory that is not there. Both entry
+ * points that walk the tree ask here rather than carrying a check each, because
+ * absence is a property of the install rather than of a verb, and a second copy
+ * of the question is a second message to keep true. `check` reads the tree as
+ * well, through `expectFilePath`, and needs no guard because its provisioned-tree
+ * check already stops an installed run before the read.
+ *
+ * The distinction it preserves is between an absent tree and an empty one. Only
+ * the second is a real zero, and a coverage percentage over a denominator nobody
+ * looked at reads as a suite that examined everything and found it clean.
+ *
+ * The frame opens and closes here, so this runs before `intro` rather than
+ * inside an open frame.
+ */
+function reportAbsentScenarioTree(): boolean {
+  if (existsSync(SANDBOX_DIR)) return false
+
+  frameError('sandbox is toolkit-only and is absent from an installed aitk')
+  process.exitCode = 1
+
+  return true
+}
+
 /**
  * The provisioned tree, as opposed to `SANDBOX_DIR` above, which holds the
  * scenario scripts. It sits outside the toolkit worktree so the toolkit's own
@@ -217,6 +246,8 @@ function reportCoverage(report: CoverageReport): void {
 }
 
 function runCoverage(options: CoverageOptions): void {
+  if (reportAbsentScenarioTree()) return
+
   intro('aitk sandbox coverage')
 
   const report = collectCoverage(PROJECT_ROOT)
@@ -284,6 +315,8 @@ export function register(program: Command): void {
     .allowExcessArguments(true)
     .passThroughOptions()
     .action(async (_opts: unknown, cmd: Command) => {
+      if (reportAbsentScenarioTree()) return
+
       const args = cmd.args
 
       if (args.length === 0) {
@@ -336,7 +369,8 @@ export function register(program: Command): void {
         '  aitk sandbox coverage',
         '  aitk sandbox coverage --json',
         '',
-        'Exit codes: 0 always, unless --strict and a scenario declares nothing.',
+        'Exit codes: 0, unless --strict and a scenario declares nothing.',
+        'Where the scenario tree does not ship, exits 1 without a report.',
       ].join('\n'),
     )
     .action((options: CoverageOptions) => {

package/standards/index.md

@@ -18,5 +18,5 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, and content rules for .claude/tasks/
-- [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, commits, and tags
+- [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/prose.md

@@ -74,10 +74,14 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 - Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
 - Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
 
-## Banned-character scan
+## Pre-publish scan
 
 Wherever text leaves through a channel no automated check covers, the author is the only gate and runs this scan. Text sent to another service, written to a path the project's checks exclude, and text inside a fenced block are the usual cases. The surface that publishes the text is what knows which gap applies, so it names its own rather than reading one here.
 
+Run the scan as an explicit step against the finished text. Having read this file before drafting does not cover it, because the check has to happen after the text exists.
+
+### Banned characters
+
 Scan the drafted text and rewrite each occurrence:
 
 - `—` (em dash): split into two sentences, or use a comma
@@ -85,7 +89,17 @@ Scan the drafted text and rewrite each occurrence:
 
 Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
 
-Run the scan as an explicit step against the finished text. Having read this file before drafting does not cover it, because the check has to happen after the text exists.
+### Phase labels
+
+The versioning standard beside this file holds the label rule and the table of surfaces. Read it at scan time rather than working the format from memory.
+
+Scope this check by destination. Text published to a remote takes it. Text scanned on its way into the repository, where the reader has the task board, takes the character checks alone.
+
+### An unreadable source
+
+Stop and name the source when one this scan reaches for cannot be read. Do not scan what resolved and report the result.
+
+A run that covers half its sources and says nothing is worse than one that visibly did not happen, because the surfaces running this scan are the ones that describe themselves as the only gate. A clean result from a half-run scan is read as coverage.
 
 ## Frontmatter descriptions
 

package/standards/versioning.md

@@ -1,6 +1,6 @@
 ---
 title: Versioning reference
-description: Phase label vs semver discipline across tasks, PRs, commits, and tags
+description: Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 ---
 
 # Versioning reference
@@ -31,6 +31,9 @@ External release identity used in git tags and release notes. Independent of pha
 | `.claude/tasks/`          | yes          | no                                  |
 | Chat with the operator    | yes          | no                                  |
 | PR titles                 | no           | only when the PR cuts a release     |
+| PR bodies                 | no           | only when the PR cuts a release     |
+| Review comments           | no           | only when referencing a release     |
+| Issue titles and bodies   | no           | only when referencing a release     |
 | Commit messages           | no           | only when the commit cuts a release |
 | Git tags                  | no           | yes                                 |
 | README and `CHANGELOG.md` | no           | yes                                 |
@@ -41,6 +44,13 @@ External release identity used in git tags and release notes. Independent of pha
 - Commit subjects do not embed phase labels.
 - Git tags use semver only. Phase labels never become tags.
 - A PR that cuts a release may reference its semver tag in the title or body. Phase labels still do not appear.
+- PR bodies, review comments, and issue text name the change itself, never the internal stream that scheduled it. Describe the work rather than the label it was planned under.
+
+## Pre-publish check
+
+Text bound for a remote is checked for phase labels against the finished draft, before it is sent. A body, comment, or title reaches a reader who has no task board, so a label that survives to publication cannot be resolved by anyone downstream.
+
+The surface publishing the text is the last gate on it. Where no automated check covers that surface, the author performs the check as an explicit step rather than relying on having read this file while drafting.
 
 ## Why