@erclx/aitk 0.9.0 → 0.11.0

package/README.md

@@ -13,29 +13,31 @@ claude plugin marketplace add https://github.com/erclx/aitk
 claude plugin install aitk@aitk
 ```
 
-The skills are then available as `/aitk:<name>`. Run `/reload-plugins` to pick them up inside a session that was already open. Updates arrive on release, so a push to this repo does not reach an installed copy.
+The skills land as `/aitk:<name>`. If your session was already open, run `/reload-plugins` to pick them up. Updates arrive on release, so a push to this repo won't reach your installed copy.
 
-Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin does not put it on your path. Install it from the registry.
+Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin doesn't put it on your path. Install it from the registry.
 
 ```bash
 bun install --global @erclx/aitk
 ```
 
-[Bun](https://bun.sh) is the CLI runtime and has to be on the path first. Confirm the install by resolving `aitk --help`.
+[Bun](https://bun.sh) is the CLI runtime and has to be on your path first. Confirm the install by resolving `aitk --help`.
 
 ## Why
 
-Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Across enough projects the copies drift, and agents stop getting consistent signals.
+Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
 
 Three design choices shape the toolkit.
 
 - Agent-first: every command has a non-interactive path and a JSON catalog. If a Claude Code skill or any other agent cannot drive the CLI without prompts, the design is wrong.
-- Text-native: conventions, rules, and prompts are authored as markdown that humans and agents read the same way. No hidden behavior, no compiled state.
-- One source, many consumers: this repo is the authoritative copy. Target projects install and sync on demand, never author in place.
+- Text-native: conventions, rules, and prompts are authored as markdown that you and your agents read the same way. No hidden behavior, no compiled state.
+- One source, many consumers: this repo is the authoritative copy. Your projects install and sync on demand, never author in place.
+
+Two limits worth knowing before you install. Claude Code is the only agent runtime the plugin targets, and the CLI needs Bun on your path. Snippets are the one surface that also travels to Gemini chat.
 
 ## What is inside
 
-Each domain has a canonical source in this repo and a thin install or sync CLI on the target side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it.
+Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it, so skip them on a first pass.
 
 - [Claude Code plugin](.claude/context/claude-plugin.md): skills for planning, review, docs sync, and the git ship chain
 - [Governance rules](.claude/context/governance.md): Cursor rules and stacks, installable per project
@@ -49,6 +51,8 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 
 ## Documentation
 
+Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.
+
 - [AI workflow](docs/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/operating-model.md): orchestrator and worker roles for building across parallel sessions
 - [Visual design workflow](docs/visual-design-workflow.md): tiered guide for design and wireframe authoring
@@ -58,7 +62,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 
 ## Development
 
-Working on the toolkit starts from a clone. Running the CLI does not, since it installs from the registry.
+Working on the toolkit starts from a clone. Running the CLI doesn't, since it installs from the registry. Skip this section unless you're changing the toolkit itself.
 
 ### Prerequisites
 
@@ -67,7 +71,7 @@ Working on the toolkit starts from a clone. Running the CLI does not, since it i
 - [GitHub CLI](https://cli.github.com) (optional) for ship flows
 - Shell: `zsh` or bash 4+ (`brew install bash` on macOS).
 
-Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and adds the Claude Code shell aliases to `~/.zshrc`.
+Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and adds the Claude Code shell aliases to your `~/.zshrc`.
 
 ```bash
 git clone https://github.com/erclx/aitk.git
@@ -76,7 +80,7 @@ bun install
 bun run bootstrap
 ```
 
-The script is idempotent. Re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `aitk --help` on the last step. See [zshrc aliases](docs/zshrc-aliases.md) for what each alias does.
+The script is idempotent, so re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `aitk --help` on the last step. See [zshrc aliases](docs/zshrc-aliases.md) for what each alias does.
 
 With the CLI linked, scaffold a fresh project.
 
@@ -86,13 +90,13 @@ git init
 aitk init
 ```
 
-`aitk init` installs base tooling configs, Claude seeds, governance rules, standards, and snippets in one pass, and scaffolds a `.claude/wiki/` stub for the project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/` alongside the standards they route to. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `aitk tooling list --json` to see the catalog.
+`aitk init` installs base tooling configs, Claude seeds, governance rules, standards, and snippets in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/` alongside the standards they route to. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `aitk tooling list --json` to see the catalog.
 
-For the full outsider journey (scaffold, add a domain later, sync upstream drift), see [target projects](docs/target-projects.md).
+For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
 
 ## Contributing
 
-Portfolio project. Issues are welcome. Pull requests are accepted by invitation only. See the [contributing guidelines](CONTRIBUTING.md) for the local loop, the authoring split, and the commit convention.
+Portfolio project. Issues are welcome. Pull requests are accepted by invitation only, so open an issue rather than a branch. Read the [contributing guidelines](CONTRIBUTING.md) for the local loop, the authoring split, and the commit convention before you file anything.
 
 ## License
 

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

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

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

@@ -73,10 +73,9 @@ 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, scan the reply for em dashes and semicolons and rewrite each,
-splitting into two sentences or using a comma. The standards-audit hook skips
-`.claude/.tmp/`, so this scan is the only gate on the published reply. Post it to
-the PR:
+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:
 
 ```bash
 gh pr comment <number> --body-file .claude/.tmp/address-review/reply-<number>.md

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

@@ -11,7 +11,7 @@ Chain the post-plan pipeline in a single run. Every step has a stop condition. S
 ## Guards
 
 - All `.claude/plans/` and `.claude/review/` reads resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
-- Run `git branch --show-current` and replace `/` with `-` to derive `<slug>`. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.`
+- Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.`
 - If `.claude/plans/feature-<slug>.md` does not exist at the main worktree root, stop: `❌ No approved plan at .claude/plans/feature-<slug>.md. Run /claude-feature first.`
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 

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

@@ -75,7 +75,7 @@ When sources came from a code scan rather than planning prose, lead the explanat
 
 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.
 
-Apply the toolkit's prose bans to the whole file, including inside mermaid `subgraph` labels and node text. No em-dashes, no semicolons. Use a colon or split into two sentences instead. The pedagogical voice the standard asks for is a yield on voice alone and buys no exemption from these bans.
+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.
 
 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-docs/SKILL.md

@@ -181,7 +181,7 @@ A plan can serve more than one task, and archiving on the first task to close st
 
 Write the retarget as a markdown link, `Plan: [feature-<slug>](../.tmp/plans-archive/feature-<slug>.md)`, updating both halves so the text and the target stay in step. This branch is the only writer that produces a `Plan:` line nobody authored by hand, so a retarget that emits a bare path converts every task to the old form as it closes and drifts the board back to two shapes on its own.
 
-**Reviews.** Derive `<slug>` from the current branch name (replace `/` with `-`). If `.claude/review/review-<slug>.md` exists, delete it. `claude-review` writes with this convention. Do not sweep any other `review-*.md` file.
+**Reviews.** Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result. If `.claude/review/review-<slug>.md` exists, delete it. `claude-review` writes with this convention. Do not sweep any other `review-*.md` file.
 
 Do not sweep `ui-checklist-*.md` (pending human verification) or `ux-audit-*.md` (standalone deliverable).
 

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

@@ -78,7 +78,7 @@ Rules that resist crisp one-line phrasing default to **Delete** over promote. Ne
 
 ### Step 4: write the proposal to the review file
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace `/` with `-`. Fall back to `latest` on empty output.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full proposal to `.claude/review/memory-review-<slug>.md` at the main worktree root. Do not print it inline.
 

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, scan the body for em dashes and semicolons and rewrite each, splitting into two sentences or using a comma. The standards-audit hook skips `.claude/.tmp/`, so this scan is the only gate on the published comment.
+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.
 
 ```bash
 gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>-<short-sha>.md

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

@@ -116,7 +116,7 @@ If nothing is wrong, use: `✅ No findings.`
 
 ### Persist
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full report directly to `.claude/review/review-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
 

package/claude/skills/claude-seed-sync/SKILL.md

@@ -52,7 +52,7 @@ Before proposing an Update, grep the target section for the seed text's keywords
 
 ## Step 4: write the proposal to the review file
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace `/` with `-`. Fall back to `latest` on empty output.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full proposal to `.claude/review/seed-audit-<slug>.md` at the main worktree root. Do not print the proposal inline.
 

package/claude/skills/claude-ui-test/SKILL.md

@@ -57,7 +57,7 @@ If all changes are automatable, skip the manual checklist:
 
 ### Persist the checklist
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 When a manual checklist is produced, write it directly to `.claude/review/ui-checklist-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
 

package/claude/skills/claude-ux-audit/SKILL.md

@@ -58,7 +58,7 @@ If nothing is wrong, use: `✅ No observations.`
 
 ### Persist
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full report directly to `.claude/review/ux-audit-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
 

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

@@ -34,10 +34,10 @@ The directory test separates the defect from a genuinely bare repository, which
 
 Try each source in order. Stop at the first match.
 
-1. **Plan matched to current branch.** Take the branch name and replace `/` with `-` to get `<slug>`. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
+1. **Plan matched to current branch.** Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. An empty result falls through to the next source here rather than becoming `latest`, since the slug is one candidate among several. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
 2. **Single plan file.** List `<main-root>/.claude/plans/feature-*.md`. If exactly one match, derive `<slug>` from the filename.
 3. **Multiple plan files, no branch match.** Ask the user which plan. Show the candidate slugs as a numbered list. Do not pick.
-4. **Current branch.** When no plan exists, use the branch name (with `/` replaced by `-`) if it is not `main` or `master`.
+4. **Current branch.** When no plan exists, use the `<slug>` from step 1 if it is not `main` or `master`.
    4b. **Session context.** When on `main` or `master` with no matching plan, read the current conversation to infer a kebab slug from the topic being discussed. Propose it: `Infer: <slug>. Confirm or rename?` Do not enter the worktree until the user confirms or provides a corrected name.
 5. **Ask.** None of the above applies. Ask the user for a name. Do not invent one.
 

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 scanning it for em dashes and semicolons and rewriting each 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 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.
 
 ## After completion
 

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

@@ -40,12 +40,7 @@ After outputting the preview, execute the final command immediately. Claude Code
 
 ### Pre-publish scan
 
-Before running the final command, scan the title and body for banned characters and rewrite each occurrence:
-
-- `—` (em dash): split into two sentences or use a comma
-- `;` (semicolon): split into two sentences
-
-These bans come from `.claude/standards/prose.md`. Reading it is not enough. The scan is an explicit step.
+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`.
 
 ### Final command
 

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

@@ -69,12 +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, scan the PR title and body for banned characters and rewrite each occurrence:
-
-- `—` (em dash): split into two sentences or use a comma
-- `;` (semicolon): split into two sentences
-
-These bans come from `.claude/standards/prose.md` and apply to PR text on top of `${CLAUDE_SKILL_DIR}/references/pr.md`. Reading `prose.md` is not enough. The scan is an explicit step.
+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`.
 
 ### Final command
 

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

@@ -7,7 +7,7 @@ description: What branch splitting is for, the gaps it closes, and how it differ
 
 ## Gap
 
-Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong.
+Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong. Every body it writes stages under `.claude/.tmp/` and leaves through `gh`, neither of which the audit hook watches, so a banned character survives into a published pull request and has to be edited on the remote.
 
 ## Must
 
@@ -17,6 +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
 
 ## Must not
 

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

@@ -69,6 +69,8 @@ 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.
+
 ### Final commands
 
 For independent mode, base every branch on `main`:

package/docs/agents.md

@@ -79,6 +79,7 @@ Full help: `aitk <command> --help`.
 | `aitk feedback`          | Write toolkit feedback from stdin to `.claude/review/`, 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 comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
 
 ### Domain commands
 
@@ -95,6 +96,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `design`    | `render`                                                               |
 | `slides`    | `render`, `list`                                                       |
 | `tasks`     | `archive`                                                              |
+| `comments`  | `scan`                                                                 |
 
 Common patterns:
 
@@ -134,6 +136,16 @@ headlessly, so a call that names its stack or category is unchanged.
 `aitk snippets install`. Both resolve the target before anything else, so a path
 that does not exist fails rather than being scaffolded.
 
+`aitk gov regen` is the one governance verb that runs against the toolkit root,
+because the `.claude/rules/` it writes there is produced output rather than an
+operator's working copy. It reads the stack recorded in `internal/governance.toml`,
+installs it alongside anything under `internal/rules/`, and clears the
+destination first so a rule the record stopped naming disappears. It takes
+`--root <path>` and defaults to the toolkit root, prints nothing on success, and
+reports the reason on stderr with exit 1 when the record names a stack or rule
+that does not resolve. `scripts/core/regen-claude-copies.sh` calls it, and the
+Consumed copies stage of `bun run check` asserts the result is committed.
+
 `aitk sync` runs every installed domain sync, then offers to commit the result
 and open a pull request. Under `AITK_NON_INTERACTIVE=1` it applies the domain
 syncs and then refuses the git workflow, reporting the branch and commit it
@@ -285,6 +297,30 @@ aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .re
 
 For the board format, the `Pull request:` line, and the archive rules, see `.claude/standards/tasks.md`.
 
+## Comments
+
+`aitk comments scan [path]` reports comment density for a tree, split by language and by comment kind. It is the only command that parses the target's own source, so its scope stays deliberately narrow: TypeScript and bash, line-oriented, no AST.
+
+```bash
+aitk comments scan
+aitk comments scan src --json
+aitk comments scan --since v0.5.0
+```
+
+| Option               | Behavior                                                        |
+| -------------------- | --------------------------------------------------------------- |
+| `--json`             | Add a machine-readable record on stdout, keeping the frame      |
+| `--since <rev>`      | Report the trend from this revision instead of a snapshot alone |
+| `--languages <list>` | Comma-separated subset of `ts,sh` (default: both)               |
+
+A line counts as a comment when its first non-whitespace token opens one, which is what keeps a URL in a string literal from reading as a `//` comment without a parser. Density is `commentLines / lines`, reported and never graded. The command produces the number and a rule produces the judgment.
+
+Two exclusions are structural rather than tuning. Heredoc bodies are dropped from both the numerator and the denominator, because a scenario script carrying markdown inside one has `#` opening a heading rather than a comment, which inflated a measured 112 comment lines to 427. Fixture trees are pruned by path segment for the same reason. The line-1 shebang is not a comment, since every script has one and counting it puts a floor under density that reports the file count.
+
+`--since` recomputes each point from git via `ls-tree` and `cat-file --batch`, checking nothing out. No ledger is written or read. Six points spread evenly across the window by default, and the boundary revision is always included so the series keeps the reading it is measured against. This works only because density is a pure function of a tree. Which author or session wrote a comment is not recoverable from git and does not belong here.
+
+The degradation sweep reads its vocabulary from whichever rule publishes a `## Degradation vocabulary` heading, preferring `.claude/rules/` over `governance/rules/`, so one definition serves the toolkit and every target. Discovery anchors on the heading rather than a filename, because a renumbered rule would otherwise empty the vocabulary while the sweep still reported clean. With no such rule the sweep reports **skipped** rather than zero hits, since finding nothing and looking for nothing mean opposite things.
+
 ## Runtime catalogs
 
 Use these to discover what's available instead of hardcoding names.

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.
+- `--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 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.9.0",
+  "version": "0.11.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-claude-copies.sh

@@ -23,4 +23,13 @@ mirror_dir "$PROJECT_ROOT/snippets" "$PROJECT_ROOT/.claude/snippets" -name "*.md
 
 # `internal/` is the surface the plugin does not symlink. Mirrored on its own so
 # toolkit sessions read it at a `.claude/` path like every other consumed copy.
-mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md"
+# `internal/rules/` is excluded because it lands in `.claude/rules/` below, and
+# mirroring it here too would publish each rule at a second inert path. The
+# exclusion is anchored to that one folder, since an unanchored `*/rules/*` would
+# also drop a later `internal/standards/rules/` and report nothing for it.
+mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md" -not -path "$PROJECT_ROOT/internal/rules/*"
+
+# `.claude/rules/` is a subset rather than a mirror, so it resolves through the
+# stack machinery instead of a fourth `mirror_dir` call. The record naming the
+# subset is `internal/governance.toml`.
+bun "$PROJECT_ROOT/src/cli.ts" gov regen --root "$PROJECT_ROOT"

package/scripts/core/verify.sh

@@ -132,7 +132,7 @@ main() {
 
   log_step "Consumed copies"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-claude-copies.sh" "Consumed-copy regen failed"
-  assert_no_drift ".claude/standards .claude/snippets .claude/internal" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, and .claude/internal."
+  assert_no_drift ".claude/standards .claude/snippets .claude/internal .claude/rules" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, .claude/internal, and .claude/rules."
   log_info "Consumed copies clean"
 
   log_step "Skill references"

package/src/cli.ts

@@ -17,6 +17,7 @@ import { register as slides } from '@/commands/slides'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
+import { register as comments } from '@/commands/comments'
 
 const GREY = '\x1b[0;90m'
 const WHITE = '\x1b[1;37m'
@@ -44,6 +45,7 @@ function showHelp(): void {
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
+    `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -73,6 +75,7 @@ function showHelp(): void {
     `${GREY}│${NC}    pbpaste | aitk feedback`,
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
+    `${GREY}│${NC}    aitk comments scan src --json`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
@@ -107,5 +110,6 @@ slides(program)
 feedback(program)
 transcripts(program)
 tasks(program)
+comments(program)
 
 program.parse()