@chemx/starter-kit 26.10.10-75 → 26.10.26-386

package/AGENTS.md

@@ -8,16 +8,31 @@
 ## ⚡ Quick Agent Reflex Table (Token-Bounded Commands)
 | Standard Reflex | `chemx` Equivalent | Token & Architecture Advantage |
 | :--- | :--- | :--- |
-| `grep -rn "pattern" .` | `chemx q -g "pattern"` or `chemx q -g "pattern" -l` | Fixed-string search of every text file `.gitignore` allows (submodules, docs, styles, JSON, PHP); full `path:line:text` lines or line-only (-l); `--regex` opts into regex; `-- <pattern>` for a pattern starting with `-`. Uses `rg` when installed, a JS walker otherwise; the header states files searched and the engine. |
+| `grep -rn "pattern" .` | `chemx q -g "pattern" --bare` or `chemx q -g "pattern" -C 3 --bare` | Fixed-string search matching rg token-for-token (57 chars / 14 tokens per hit); add `-C <N>` to inspect surrounding code in a single turn without a second read call. `a\|b` is literal text: add `--regex` for alternation (RE2 subset). `-l` prints the matching files once, `-o --unique` prints the distinct matched text (a `--gs-[a-z-]+` token list in one call), paths after the pattern scope it (`--glob <path>` is `--dir`; `--max <N>` is `-n`), dot-directories such as `.github` and `.claude` are searched (only git-ignored paths are left out; `--hidden` adds them), and `chemx q <text>` with no symbol hit runs this search for you. See [docs/search.md](docs/search.md). |
+| `sed -n 'N,Mp' <file>` | `chemx read <file>:N-M --bare` | Verbatim slice matching sed byte-for-byte; 0 header, box or line number tokens. |
 | `git diff` | `chemx d` | Zero-context (`-U0`), auto-collapses to `--stat` if > 80 lines, micro-syncs index. |
+| Editing `docs/CHANGELOG.md` for your change | write `docs/changelog.d/<ticket>.md` (first line `### Fixed`, `### Added` or a title with the ticket id, then bullets); `chemx changelog --check` validates, `chemx changelog` folds the fragments into Unreleased and deletes them | One file per change, so parallel tickets never edit the same lines. Never edit `docs/CHANGELOG.md` directly. See [docs/changelog.d/README.md](docs/changelog.d/README.md). |
 | `git log` | `chemx log -n 5` | One-line commit history (5 commits measured about 140 tokens on 2026-10-09, roughly 28 per commit). |
 | `find . -name "*.vue"` | `chemx f "*.vue"` | Strictly filters by `.gitignore` and ignored dirs. |
 | `cat package.json` | `chemx p -s` / `chemx p <script>` | Single script or dep extraction (`p -s` listing 15 scripts measured about 240 tokens on 2026-10-09). |
 | `cat <data.json>` | `chemx j <file.json>` | Structural schema shape only; collapses repeating arrays. |
 | `cat <file>` / `head <file>` | `chemx read <file> --outline` | AST signatures only (outline of `cli/reader.js` measured about 300 tokens against about 4,800 for the file, 2026-10-09; other targets in `benchmarks/README.md`). |
 | `npm test` / `tsc` | `chemx test` / `chemx verify` | Prints a summary on success and the failing diffs on failure. |
+| `eslint <paths>` / `npm run lint` | `chemx lint <paths> [--fix]` | ESLint grouped by file, plus the `chemx check` hazards of those paths in the same pass (inline booleans, dispatch switches), so there is no second pass. With no ESLint config or package.json (a WordPress plugin dir) it says so in one line and runs `chemx check` on the files instead. |
+| `node tests/run-tests.mjs` (a repo's own harness runner, e.g. the WordPress plugins) | `chemx test` / `chemx test tests/x.test.mjs` | One file through a generated copy of the runner, failures only and one summary line, one run at a time on the machine (shared database). `.chemxrc` `guard.allow` (or its alias `test.runners`) lists a raw runner the guard should leave alone. |
 | `cat .chemx/history.json` | `chemx audit --feed=scopes` / MCP `audit_feed` | Recorded audit results as flat rows (per scope, per run or per pillar) without re-running the audit; `--json` for every row. |
 | Auditing each package by hand | `chemx audit --each=submodules` | One scoped audit per submodule or workspace package, then a one-line-per-package summary. |
+| `cd ../other-repo && <command>` / `git -C ../other-repo log` | `chemx <command> --root=../other-repo` (any command: `log`, `d`, `status`, `q -g`, `read`, `team ...`; or `CHEMX_PROJECT_ROOT=<dir>`) | Runs as if started in that project, from any cwd; the shell never changes directory. `chemx read /abs/path/in/another/chemx/project` picks that project's index too. |
+| `cd ../other-repo && chemx team task show 12` | `chemx team task show ../other-repo#12` or `--board=../other-repo` | A task number belongs to a board; this names it. A `team task list`/`show` footer says when you hold a claim on a different board. |
+| `gh pr checks <n>`, `gh pr view <n> --json mergeStateStatus`, `sleep 120; gh pr checks <n>` | `chemx ci <n>` or `chemx ci <n> --wait` | One line per check (state, duration, name) and one merge-state line; exit 0 all passed, 1 a check failed, 3 pending or no checks reported yet, 2 could not read. `--wait` polls every 30 s and prints only what changed. `chemx ci --protection` warns (exit 1) when the default branch requires no status checks, because `gh pr merge --auto` then merges at once. See [docs/ci.md](docs/ci.md). |
+| Adding up task costs by hand | `chemx team tokens --epic <id>` | Prompt, completion and cached tokens, cost and wall time over an epic's children (recursively), one line each and a total; a child that never recorded usage is a dash and counted unknown, not zero. See [docs/team-tokens.md](docs/team-tokens.md). |
+| A shell loop of `team task add` to file an epic and its children | `chemx task add --from tasks.yaml` (`--dry-run` first) | Rows with `ref`, `parent_ref` and `deps` by ref, one transaction, one `#<id> added` line per row and a `refs:` map; any wrong row writes nothing. `chemx task` is `chemx team task`. |
+| A 7 KB design contract in `--desc`, or in a `.md` file agents cat | `chemx team brief <id> --file design.md` (read: `task show <id> --full`) | The brief is stored on the task apart from its description; `task show` prints only its length. |
+| `sleep`/poll loops for a peer's report | `chemx wait --post-matching "K9 merged" --from=@sonnet-k9` | Resolves when a feed post (any case, no lock events) matches; exit 0 / 2 on timeout. |
+| `chemx test ... &` then a `sleep` or `kill -0` loop until it ends | `chemx test ... & chemx wait --job=$!` | Resolves when that chemx process has ended and exits with the job's own code (0 pass, 1 fail, 3 inconclusive); 2 on timeout. See [docs/test-lanes.md](docs/test-lanes.md). |
+| A one-off script in a scratchpad other agents also write to (`/tmp/one.mjs`) | `chemx scratch one.mjs` (the directory: `chemx scratch`) | Prints `<project>/.chemx/scratch/<handle>/one.mjs` and makes the folder: one directory per handle, git-ignored, so another agent's `one.mjs` never replaces yours. See [docs/agent-workspace.md](docs/agent-workspace.md). |
+| `git worktree add ../w -b fix/x origin/main` then a hand-made `node_modules` symlink; later `git worktree remove` and `git branch -d` | `chemx worktree add <path> -b <branch> [--link-modules\|--install]` / `chemx worktree remove <path>` | Branches from the remote default branch, gives the worktree a real `node_modules` of symlinks into the main checkout's (so an install in it never writes into the main checkout) or installs, and prints the path first plus the reminder that `chemx team` runs from the main checkout or with `--board`. `remove` deletes the branch when it is merged, squash merges included, into the default branch or the branch it was cut from (recorded at `add`), and refuses an unmerged one without `--force`. See [docs/agent-workspace.md](docs/agent-workspace.md). |
+| `cp f f.bak; sed -i ... f; <test>; cp -i f.bak f` (a mutation check) | `chemx mutate f --apply 's/a/b/' --then "<test>"` | Applies a sed substitution or a diff file, runs the command like `chemx run`, always restores the original byte for byte (a copy sits in your scratch directory; `--keep` retains it) and exits with the command's code (125 = chemx stopped, e.g. nothing changed or a lease is held). See [docs/agent-workspace.md](docs/agent-workspace.md). |
 | Multiple CLI actions | `chemx do "<cmd1>" "<cmd2>"` | Executes sequentially in a single warm Node process. |
 | Multiple MCP tool calls | `chemx({ commands: [...] })` | Executes multiple sub-operations in a single agent turn. |
 
@@ -111,7 +126,7 @@ Use same-name shorthand across all languages; eliminate redundant `key: key` dup
 ### L. Database-First Swarm Coordination & The Zero-Markdown-Monolith Directive
 - **Database as the Master Source of Truth**: The multi-agent orchestrator and subagents MUST record all milestones, task assignments, status changes, file locks, and architectural contracts directly in `.chemx/index.db` (`agent_tasks`, `file_lock_queue`, `agent_feed`) rather than creating monolithic, multi-thousand-token markdown specification files.
 - **Prohibition on Monolithic Project Markdown Parsing**: Subagents MUST NOT load giant monolithic `PROJECT.md` or status markdown files into context. Subagents query only their assigned task slice and dependencies via `pnpm chemx team task list --agent=@my-id` or MCP `chemx_team_task`.
-- **Leases and handoff**: A file lock is a 5-minute lease that any chemx command run as the holder extends and that lapses after 5 minutes without activity (`docs/team-locks.md`). The commit hook refuses staged files another handle leases live. `chemx team task handoff <id> @<to> --as=@<from>` passes a task on (assignee or task creator only); it keeps the task `in_progress`, records from/to/by in the feed, and does not move file locks, so the old holder releases and the new owner acquires.
+- **Leases and handoff**: A file lock is a 5-minute lease that any chemx command run as the holder extends (from a git worktree too, once the holder has claimed a task) and that lapses after 5 minutes without activity; a lapse of at most 10 minutes is undone by the holder's next chemx command while the task is in_progress and nobody took or queued for the file. Wrap a long non-chemx command (a plugin's test runner, a script) as `chemx run -- <command>` and it renews your leases every minute while it runs (`docs/team-locks.md`). The commit hook refuses staged files another handle leases live. Claude's native `Edit`/`Write` are refused on a file another handle leases, but a lease held by a handle you named in an earlier chemx call (`--as`, `CHEMX_AGENT_ID`) this session is yours: name your handle on your lock and claim calls (`docs/hooks.md`, "Native edits and file locks"). `chemx team task handoff <id> @<to> --as=@<from>` passes a task on (assignee or task creator only); it keeps the task `in_progress`, records from/to/by in the feed, moves the board pointer to the new owner (their next `chemx commit` finds the task's board without `--board`), and does not move file locks, so the old holder releases and the new owner acquires. `chemx team lock a.js b.js c.js --as=@<you>` takes several paths in one call and answers one line per path (`granted until HH:MM`, `queued behind @x`, or `refused: <reason>`); an absolute path in a sibling repo works from any directory under the board root.
 - **Project Markdown as a Generated Read-Only Projection**: If a human-readable `PROJECT.md` is requested, it MUST be generated on-demand as a read-only projection compiled from the database state via `pnpm chemx team status` or export tools.
 
 ### M. The Master MCP Tool Protocol & Single-Permission Dispatch
@@ -150,6 +165,8 @@ Use same-name shorthand across all languages; eliminate redundant `key: key` dup
   // Preview first: dryRun returns the unified diff and writes nothing (CLI: --dry-run or -n)
   chemx({ action: 'patch', params: { path: 'src/...', target: 'oldCode', replacement: 'newCode', dryRun: true } });
   chemx({ action: 'patch', params: { path: 'src/...', target: 'oldCode', replacement: 'newCode' } });
+  // Several edits to one file go in ONE call (CLI: SEARCH/REPLACE blocks in a heredoc; API: blocks: [{ search, replace }]): all-or-nothing,
+  // and a block that does not match or trips a guard fails the call as "Block 2 of 3: ..." with the file untouched
   // Removing a top-level declaration (renames included) is refused unless named (CLI: --allow-remove=oldName)
   chemx({ action: 'patch', params: { path: 'src/...', target: 'oldName', replacement: 'newName', allowRemoved: ['oldName'] } });
   // write creates; replacing an existing file needs overwrite (CLI: --overwrite)
@@ -175,7 +192,7 @@ Use same-name shorthand across all languages; eliminate redundant `key: key` dup
 ### N. Database-First Navigation, Symbol Connections & The Zero-Native-File-Dump Directive
 - **Database Master Index First**: Before inspecting or modifying any file, AI agents MUST query the SQLite database (`.chemx/index.db`) or the AST Query Machine (`chemx({ action: 'team', params: { action: 'list' } })`, `chemx({ action: 'q', params: { query } })`) rather than exploring the filesystem with broad find or ripgrep commands.
 - **Targeted Symbol-Only Extraction**: AI agents MUST NEVER dump entire source files into context. When an agent needs to inspect a function, hook, interface, or class, it MUST request only that specific symbol: `chemx({ action: 'read', params: { path, symbol: '<name>' } })`.
-- **Read Window Auto-Outline**: Files longer than the chemx read window (100 lines by default), read without a target symbol or slice, automatically render an AST outline to prevent token exhaustion and host buffer spillovers (such as IDE `output.txt` dumps). The read window is a tool budget, not an architecture rule; file size is governed by 1.A.
+- **Read Window Auto-Outline**: Files longer than the chemx read window (100 lines by default), read without a target symbol or slice, automatically render an AST outline to prevent token exhaustion and host buffer spillovers (such as IDE `output.txt` dumps). A file with nothing to outline (yaml, json, txt, shell, or Markdown without headings) reads as its first window of text with the next range named, not an empty outline. The read window is a tool budget, not an architecture rule; file size is governed by 1.A.
 - **Enrich Mode (Component Capsules Only)**: When an agent needs both exported signatures AND logic flow for a component capsule, use `enrich: true` with `outline: true`: one response card holds the outline and a compacted logic skeleton, optionally with a forward trace or reverse caller chain (`traceSymbol`, `backtraceSymbol`). The skeleton generator is tuned for components; on procedural modules (services, CLI code, utilities) enrich saves only a few percent over reading the whole file, so use plain `outline: true` or `symbol: '<name>'` there.
 - **Symbol Connection Graph Over Multi-File Dumps**: Rather than reading multiple files to understand imports and consumers, agents MUST request symbol connections: `chemx({ action: 'read', params: { path, symbol: '<name>', connections: true } })` or `chemx({ action: 'q', params: { query, connections: true } })`. This returns the definition, imported dependencies, and caller references. Size grows with the symbol: `q <symbol> --connections` measured about 140 tokens and `read --symbol --connections` about 2,400 for `readTokenOptimized` on 2026-10-09.
 - **Token-First File Inspection & Native Fallback**: AI agents should prioritize Chemical X AST readers (`chemx read --outline` or `chemx read --symbol`) to conserve tokens. Dumping raw files burns thousands of tokens and causes premature context exhaustion. If an agent requires exact raw verification or unformatted bytes, native tools (`view_file`, `grep`, `cat`) are permitted as an intentional fallback.
@@ -251,7 +268,7 @@ Use same-name shorthand across all languages; eliminate redundant `key: key` dup
 ### A. Named Conditions & Two-Stage Composition
 > The `if` never asks a question. The question is asked and named before the branch, and the `if` reads the answer.
 
-- Every conditional test is a named boolean: an identifier, its negation, or a call or member access whose name is an assertion (3.F). A raw comparison (`x === y`, `n >= 5`), a truthiness check on a non-boolean (`if (user)`, `if (obj.prop)`), inline compound logic (`a && b`), or a verb-named call (`RE.test(s)`, `fs.existsSync(p)`) inside the test is a violation.
+- Every conditional test is a named boolean: an identifier, its negation, a bare property read (`sale.ok`, `items.length`), or a call whose name states an assertion or a predicate (3.F: `hasItems(cart)`, `map.has(key)`, `fs.existsSync(p)`). A raw comparison (`x === y`, `n >= 5`), inline compound logic (`a && b`), or a call whose name states no predicate (`RE.test(s)`, `user.getName()`) inside the test is a violation.
 - Naming is the point, not the ceremony: it forces the question inline code hides (why `<= 0` and not `=== -1`?), and an edit to a named condition changes its definition without touching the branch.
 - **Stage 1** names each atomic concept. **Stage 2** names the decision, only when 2 or more concepts compose; a single comparison gets one name and no wrapper. Guard with early returns.
   ```typescript
@@ -276,6 +293,7 @@ Use same-name shorthand across all languages; eliminate redundant `key: key` dup
   1. **Structural primitives** (`lib/is/`: `value`, `collection`, `text`, `fs`, `type`): subject-agnostic and finite (`isAbsent`, `hasItems`, `isNonEmptyString`, `pathExists`). They import nothing, and the set does not grow. Every primitive is a TypeScript type predicate (`(x: unknown): x is string`), never a plain `boolean`, or callers lose narrowing.
   2. **Domain vocabulary** (`<subsystem>/<domain>-predicates.<ext>`, colocated with the subsystem it describes): built from Layer 1. A condition earns a domain predicate at its 2nd use; a threshold duplicated across files (`score >= 90`) silently disagrees the day one copy changes, so name it once (`isGradeA`). Promote threshold literals in predicate bodies to named constants (`score >= GRADE_A_THRESHOLD`).
   3. **Decisions**: single-use composites declared at the call site per 3.A. Never extract them: extracting every condition is *indirection masquerading as modularity* (1.A).
+- A bare property read (`sale.ok`, `items.length`) or a predicate-method call (`map.has(key)`, `fs.existsSync(p)`) is already a named condition; 3.A does not ask for a const alias of it.
 - Before naming a new predicate, search for an existing one: `chemx q -g "<likely words>"` for the literal names, plus `chemx({ action: 'q', params: { query: '<concept>', hybrid: true } })` for spelling variants. Neither finds pure synonyms (`hasNoItems` vs `isEmpty`), so also scan the predicates module of the domain. A synonym beside an existing predicate is lexicon rot.
 - Repeated filter conditions are Layer 2 candidates: extract the predicate, compose a named higher-order filter, and keep derivations declarative:
   ```typescript
@@ -416,6 +434,7 @@ Raw inline `style="..."` attributes are strictly prohibited. Visual styling flow
 - Long strings of utility shorthand recreate the exact cognitive noise and AI context degradation of inline styles.
 - Decouple visual styling into scoped classes via `@apply` or centralized SCSS mixins (`@include glass;`).
 - Templates must read like a clean, semantic outline rather than an unreadable wall of styling shorthand.
+- Class strings must stay where Tailwind looks (`TAILWIND_UNSCANNED_CLASS_STRING`): in a Tailwind v3 project, a string of 3 or more utility classes in a `.js`, `.ts`, `.mjs` or `.cjs` file that no `content` glob of `tailwind.config` matches is purged from production CSS. Move it into a template or a file the globs scan, or add the file pattern to `content`. The rule reads the config as text and stays silent for Tailwind v4 or a config whose `content` list is not literal.
 
 ### C. Wrapper Atoms & Explicit Slot Forwarding
 - Never use dynamic slot iteration with `v-for="(_, slot) in $slots"` in wrapper components.
@@ -524,9 +543,10 @@ Raw inline `style="..."` attributes are strictly prohibited. Visual styling flow
 - Strictly prohibit executing verbose raw `npm test` or `pnpm test` in the shell: hundreds of passing test markers pollute context. If tests pass, agents get a short green summary; if tests fail, they get the failing test names, assertion messages, and diffs.
 - **Test loop, in order of cost** (details: `docs/test-lanes.md`):
   1. `chemx test --changed --depth=3`: only the specs within 3 import hops of your change. Fastest, and NOT proof: the report lists how many deeper specs were skipped.
-  2. `chemx test --changed`: every spec the import graph says your change can reach, fast lane only. Slow-lane specs that it reaches are named as not run.
-  3. `chemx test`: the whole fast lane. `chemx test --all` adds the slow lane (specs that spawn the CLI or MCP server, stress and timing specs); that is what CI's `npm test` runs. `chemx test --slow` runs only the slow lane.
-  4. `chemx test --profile [--all] [--top=<n>]`: per-spec-file wall time, slowest first, with the measuring method printed beside the numbers.
+  2. `chemx test --changed`: every spec the import graph says your change can reach, plus the meta specs that scan the whole repo (`test-lanes.json` `meta`), fast lane only. On a clean tree it compares with the merge base of origin/main (or origin/master) and prints the base it chose. Slow-lane specs that it reaches are named as not run. A line `widened by cli/x.js (computed import without open-ok): +N specs` names a file whose computed `import()` put N specs into the run; declare a real entry point with `// chemx: open-ok` or an `openImports` rule in `test-lanes.json` instead of paying for it.
+  3. `chemx test --changed --all`: the same affected set, both lanes. CI runs both lanes, so run this (not step 2) before you push.
+  4. `chemx test`: the whole fast lane. `chemx test --all` adds the slow lane (specs that spawn the CLI or MCP server, stress and timing specs); that is what CI's `npm test` runs. `chemx test --slow` runs only the slow lane.
+  5. `chemx test --profile [--all] [--top=<n>]`: per-spec-file wall time, slowest first, with the measuring method printed beside the numbers.
 - Lane membership lives in `test-lanes.json`, not in `package.json`. A new spec is fast unless the manifest (or a `*.slow.spec.js`, `*.perf.spec.js`, `*.e2e.spec.js` file name) says otherwise. A spec file that no test glob collects fails `cli/test-lanes-coverage.spec.js`.
 - A spec that asserts a wall-clock or CPU budget belongs in the slow lane (name it `*.perf.spec.js`), or its margin must hold on a machine running many agents.
 
@@ -568,7 +588,7 @@ Raw inline `style="..."` attributes are strictly prohibited. Visual styling flow
 ### A. Installed Hooks, Not Prose
 * Install the Claude Code integration with `chemx install-hooks --host=claude [--scope=local|project] [--dry-run]`. It adds the PreToolUse guard (`chemx hook claude-pre-tool`), the PostToolUse check (`claude-post-edit`), the SessionStart card and the statusline. The `.mcp.json` launch, the git pre-commit hook and the CI pin are opt-in: add `--write-mcp`, `--git-hooks` and `--pin-ci`; without them none of those files is written. Run `chemx doctor` when MCP answers look stale; `chemx doctor --fix` repairs hooks and the MCP launch only.
 * Alternatively install the Claude Code plugin (`plugins/claude-code`, marketplace `.claude-plugin/marketplace.json`): the same hooks, the chemical-x MCP server and a short chemx skill, resolving the kit from `CHEMX_KIT`, the project's node_modules or PATH. Use the plugin or install-hooks, not both, or every hook runs twice. The statusline comes only from install-hooks.
-* The guard tokenizes the shell command. Raw test/typecheck/lint/build runners, `git diff`/`git log` and reads of repo source files are routed through chemx. Native Read, Edit, Write and Grep on project text files are warned by default (`nativeFileTools` in `.chemxrc`, or `CHEMX_NATIVE_FILE_TOOLS`): `warn` names the chemx equivalent, `block` denies the call, `allow` is silent.
+* The guard tokenizes the shell command. Raw test/typecheck/lint/build runners, `git diff`/`git log` and reads of repo source files are routed through chemx, but a call is denied only where the chemx call covers its exact shape: `git -C <dir> log`, `git log A..B`, `grep -c`/`-o` and similar get a nudge with the closest chemx form (`chemx log --root <dir>`, `chemx log -n 50 A..B`, `chemx q -g ... -o --unique`), and shapes chemx cannot do (`grep -v`, `find -mtime`, `command -v tool`, `sleep 30`, `git rebase|push|worktree`) run silently. A denied compound command names the denied segment and says the rest did not run. `.chemxrc` `guard.allow` lists command prefixes to leave alone; `guard.plainGit: true` drops the git status/add/commit nudges. Native Read, Edit, Write and Grep on project text files are warned by default (`nativeFileTools` in `.chemxrc`, or `CHEMX_NATIVE_FILE_TOOLS`): `warn` names the chemx equivalent, `block` denies the call, `allow` is silent.
 
 ### B. Bypass and Friction
 * When chemx truly cannot do the job, append `# chemx-bypass: <reason>` to the Bash command. The bypass and every guard denial are logged to `.chemx/friction.jsonl`.
@@ -582,17 +602,19 @@ Shared-workspace protocol. Several agents edit this checkout at once, and chemx
 
 1. Identity: Pass `--as=@<your session name>` on every `chemx team` command, or set `CHEMX_AGENT_ID`. Never act as the default `@agent`.
 2. Before choosing work: Run `chemx status`, `chemx team status`, `chemx team inbox @<you>` and `chemx team task list --status=in_progress` so you know what is claimed and locked.
-3. Claim: Find or create the task (`chemx team task add "<title>" --needs=light|standard|deep`), then run `chemx team task claim <id> --as=@<you>`.
-4. Lock before edit: Run `chemx team lock acquire <file> --as=@<you> --purpose="#<id>"` before the first edit of each file. If another handle holds the lock, do not edit that file: send `chemx team dm @<handle> "<msg>" --as=@<you>` or pick other work.
-5. Edit through chemx: Read with `chemx read <path> --outline` or `--symbol=<name>`, search with `chemx q` or `chemx q -g "<text>"`, find files with `chemx f`, and edit with `chemx patch` or `chemx write`. Avoid cat, sed, grep and direct file writes where chemx has an equivalent.
-6. Test: Run targeted specs with `chemx test <spec files> [-t name]`. Run a full suite only after parallel editors have finished.
-7. Commit: Run `chemx commit <files> -m "<type>(<area>): <summary> (#<id>)"`. It stages and commits only the listed files, runs the repository pre-commit hook and refuses a file under another handle's lease. Do not use `git add -A`, `git commit -a`, `git stash`, git worktrees or side branches.
-8. Wait: Use `chemx wait --task=<id>`, `chemx wait --lock-free=<file>` or `chemx wait --verify-idle` instead of sleep loops. The result is true as of the last poll only.
-9. Progress: Record progress with `chemx team task comment <id> "<msg>" --as=@<you>` and decisions with `chemx team post "<msg>" --type=decision --task=<id> --as=@<you>`.
-10. Inbox: Run `chemx team inbox @<you>` at every task boundary: after claiming, after committing, and before starting the next task.
-11. Handoff: To pass a task to another agent, run `chemx team task handoff <id> @<to> --as=@<you>`. Only the assignee or creator can hand off.
-12. Finish: Run the package gate (`chemx verify`), commit, release every lock with `chemx team lock release <file> --as=@<you>`, then run `chemx team task done <id> --target=<file> --as=@<you>`. If the gate refuses, mark the task blocked with a reason. Do not use `--force`.
-13. Friction: When a chemx command misbehaves, you bypass it, or a flag is missing, file `chemx team task add "Friction: <what happened>" --needs=light --desc="<exact command and output>"` and keep going.
+3. Claim: Find or create the task (`chemx team task add "<title>" --needs=light|standard|deep`; `chemx task` is short for `chemx team task`), then run `chemx team task claim <id> --as=@<you>`. Read a task cheaply with `chemx team task show <id> --brief`. An epic with children goes in one file: `chemx task add --from tasks.yaml --dry-run` checks it, the same command without `--dry-run` files it. A long brief is stored with `chemx team brief <id> --file <md>`.
+4. Lock before edit: Run `chemx team lock acquire <file> --as=@<you> --purpose="#<id>"` before the first edit of each file; several files go in one call (`chemx team lock acquire a.js b.js --as=@<you>`, one result line per path). If another handle holds the lock, do not edit that file: send `chemx team dm @<handle> "<msg>" --as=@<you>` or pick other work.
+5. Edit through chemx: Read with `chemx read <path> --outline`, `--symbol=<name>` or a line range (`chemx read <path>:N-M --bare`), search with `chemx q` (symbols) or `chemx q -g "<text>" -C 3 --bare` (text), find files with `chemx f`, and edit with `chemx patch` or `chemx write`. Avoid cat, sed, grep and direct file writes where chemx has an equivalent.
+6. Workspace: Keep one-off files and branches out of the shared tree. A script or scratch file: `chemx scratch <name>` prints a path in your own git-ignored directory (`.chemx/scratch/<handle>/`), so another agent's file of the same name never replaces yours. Work that needs its own branch: `chemx worktree add <path> -b <branch> --link-modules`, then `chemx worktree remove <path>` once the branch has merged (it refuses an unmerged one). Run `chemx team` commands from the main checkout or with `--board=<dir>`, because a worktree can resolve another board. A mutation check: `chemx mutate <file> --apply "s/old/new/" --then "<command>"` runs the command on a changed file and puts the original back byte for byte. A long non-chemx command: `chemx run -- <command>` renews your file leases while it runs.
+7. Test: Run targeted specs with `chemx test <spec files> [-t name]`. Run a full suite only after parallel editors have finished.
+8. Commit: Run `chemx commit <files> -m "<type>(<area>): <summary> (#<id>)"`. It stages and commits only the listed files, runs the repository pre-commit hook and refuses a file under another handle's lease. From a worktree add `--board=<dir>` (the main checkout) so the task id is checked and the commit recorded on the board you claimed on; add `--no-skip-ci` when the commit must run CI (a commit to the default branch otherwise gets `[skip ci]` where the project sets commit.skipCi). Do not use `git add -A`, `git commit -a` or `git stash`; make a branch or worktree only through the Workspace step.
+9. Pull request: Once a pull request is open, read its checks with `chemx ci <pr> --wait` instead of `gh pr checks --watch` or a sleep loop: exit 0 means every check passed, 1 a check failed, 3 still pending or none reported yet. `chemx ci --protection` warns when the default branch requires no status checks, because `gh pr merge --auto` then merges at once. If the project keeps `docs/changelog.d/`, write `docs/changelog.d/<ticket>.md` (a `###` heading line, then bullets citing `#<id>`) and leave `docs/CHANGELOG.md` alone: `chemx changelog --check` validates the fragments and `chemx changelog` folds them into Unreleased.
+10. Wait: Use `chemx wait --task=<id>`, `chemx wait --lock-free=<file>`, `chemx wait --verify-idle`, `chemx wait --job=<pid>` (a backgrounded `chemx test ... & chemx wait --job=$!`; it exits with the job's own code) or `chemx wait --post-matching=<text> [--from=@<handle>]` (until a feed post matches) instead of sleep loops (a plain `sleep` of up to 120 seconds is fine). `--timeout=<30s|5m|2h>` bounds any of them. The result is true as of the last poll only.
+11. Progress: Record progress with `chemx team task comment <id> "<msg>" --as=@<you>` and decisions with `chemx team post "<msg>" --type=decision --task=<id> --as=@<you>`.
+12. Inbox: Run `chemx team inbox @<you>` at every task boundary: after claiming, after committing, and before starting the next task.
+13. Handoff: To pass a task to another agent, run `chemx team task handoff <id> @<to> --as=@<you>`. Only the assignee or creator can hand off.
+14. Finish: Run the package gate (`chemx verify`), commit, release every lock with `chemx team lock release <file> --as=@<you>`, then run `chemx team task done <id> --target=<file> --as=@<you>`. If the gate refuses, mark the task blocked with a reason. Do not use `--force`.
+15. Friction: When a chemx command misbehaves, you bypass it, or a flag is missing, file `chemx team task add "Friction: <what happened>" --needs=light --desc="<exact command and output>"` and keep going.
 
 Regenerate with `chemx pillars --protocol --write`; edits inside this block are overwritten.
 <!-- chemx:protocol end -->

package/README.md

@@ -28,7 +28,7 @@
 npm install -g chemx          # or: npx chemx <command>
 
 # 2. Check the install in your project
-chemx doctor                  # read-only; reports stale index rows, hooks and coverage
+chemx doctor                  # read-only; kit commit vs CI pin, stale MCP servers by session, index, hooks, coverage
 
 # 3. Wire Claude Code to chemx (writes .claude/settings.json; --dry-run shows the change first)
 chemx install-hooks --host=claude --dry-run
@@ -180,7 +180,7 @@ chemx build --json
 
 #### One gate rule
 
-The pre-commit hook (`chemx audit --staged-delta`), the ratchet step of `chemx verify` (`chemx-ratchet.json`), `chemx team task done` and the `introducedViolations` list in `patch`/`write` results share one rule: a change fails when any rule's violation count rises in a file, at any severity. A commit the hook accepts therefore cannot turn the ratchet step red. `CHEMX_SKIP_PRECOMMIT=1` skips only the hook; `chemx verify` still applies the rule. On failure the hook prints each new hazard as `RULE@file:line`. Guarantees, non-guarantees and the specs that prove parity are in [docs/audit-gates.md](docs/audit-gates.md).
+The pre-commit hook (`chemx audit --staged-delta`), the base delta gate (`chemx audit --delta-base=<ref>`, `chemx verify --changed --base=<ref>`), the ratchet step of `chemx verify` (`chemx-ratchet.json`), `chemx team task done` and the `introducedViolations` list in `patch`/`write` results share one rule: a change fails when any rule's violation count rises in a file, at any severity. A commit the hook accepts therefore cannot turn the ratchet step red. The base delta gate scores only the files a branch changed against their merge-base, so a branch that fixes one rule stays green even while the trunk is over the ratchet on other rules. `CHEMX_SKIP_PRECOMMIT=1` skips only the hook; `chemx verify` still applies the rule. On failure the hook prints each new hazard as `RULE@file:line`. Guarantees, non-guarantees and the specs that prove parity are in [docs/audit-gates.md](docs/audit-gates.md).
 
 #### Interactive audit navigator
 
@@ -204,8 +204,11 @@ chemx read src/components/m-card.vue --start=10 --end=40
 
 # Surgical file patching without full-file rewrites (literal replace, written through a temp file and rename, backup kept).
 # Multi-line edits: SEARCH/REPLACE blocks in a quoted heredoc ($, quotes and backticks stay literal).
-# Repeat the block for several edits; they apply in order and all-or-nothing. To edit text that
-# itself contains these markers, use 8 or more characters on all three marker lines.
+# Repeat the block for several edits; they apply in order and all-or-nothing: a block that does not
+# match, or that the guards refuse (parse, a removed declaration, a missing import), fails the call,
+# is named ("Block 2 of 3") and writes nothing. Keep every edit to a file in one call. To edit text that
+# itself contains these markers, use 8 or more characters on all three marker lines (a SEARCH holding a
+# conflict left by a botched rebase works with 7: the file decides which divider ends the SEARCH, longest match).
 chemx patch <file> [--dry-run] <<'PATCH'
 <<<<<<< SEARCH
 const total = items.length;
@@ -219,8 +222,8 @@ chemx patch <file> --target="oldCode" --replacement="newCode"
 # Removing a top-level declaration (renames included) is refused unless named
 chemx patch <file> --target="oldName" --replacement="newName" --allow-remove=oldName
 
-# write creates files; replacing an existing one needs --overwrite. Unknown flags refuse.
-chemx write <file> - [--overwrite] [--dry-run] <<'EOF'
+# write creates files (replacing one needs --overwrite; unknown flags refuse). Piped stdin is the content; `-` is optional.
+chemx write <file> [--overwrite] [--dry-run] <<'EOF'
 export const a = 1;
 EOF
 chemx write <file> --content="export const a = 1;" [--overwrite] [--dry-run]
@@ -230,6 +233,9 @@ chemx write <file> --content=$'\nexport const b = 2;\n' --append
 
 # Literal text search; add paths to scope it. A missing path is an error, not an empty result.
 chemx q -g "useCardController" src/components docs
+# `a|b` is literal text: --regex searches a regular expression (RE2 subset). -l prints each matching file
+# once; -o --unique prints the distinct matched text. `chemx q <text>` with no symbol hit runs this search itself.
+chemx q -g "--gs-[a-z0-9-]+" --regex -o --unique
 
 # Check that every chemx command named in your markdown exists (names only: flags and arguments are
 # not checked, and nothing is run). Exits 1 with file:line for each failure.
@@ -266,9 +272,10 @@ chemx use-task-filter
 ### 4. Database-Driven Multi-Agent Swarm Coordination
 Coordinate multi-agent swarms using the local SQLite store (`.chemx/index.db`) without multi-thousand-token markdown specification bloat:
 ```bash
-# Auto-triage: a full-scope `chemx audit` converts hazards into assignable team tasks by default.
-# Partial runs (--git, --fast, --staged, --no-index) never triage; `--no-triage` opts out.
-chemx audit
+# Triage is opt-in: `chemx audit --triage` (or `autoTriage: true` in .chemxrc) converts hazards into
+# assignable team tasks, at most 50 per run. A plain `chemx audit` files nothing.
+# Partial runs (--git, --fast, --staged, --no-index) never triage.
+chemx audit --triage
 chemx team task triage   # triage on demand
 
 # List tasks assigned to a specific agent
@@ -312,16 +319,17 @@ All reference pages: [docs/INDEX.md](docs/INDEX.md).
 
 ## Language-Agnostic Polyglot Architecture
 
-Chemical X audits more than one language. The table below lists the extensions it parses and the checks each gets; any other file type is not audited. Depth differs by language: TypeScript, JavaScript, Vue and Svelte use a real parser, and C#, Python, Go and Rust use structural patterns, so they get fewer checks.
+Chemical X audits more than one language. The table below lists the extensions it parses and the checks each gets; any other file type is not audited. Depth differs by language: TypeScript, JavaScript, Vue and Svelte use the Babel parser, PHP uses `php-parser`, C# uses structural patterns, and Python, Go and Rust get the universal text passes only, so they get fewer checks.
 
 ### Supported Language Ecosystems
 
 | Language / Framework | Extensions | Parser Engine | Capabilities |
 | :--- | :--- | :--- | :--- |
 | **C# / .NET 10** | `.cs` | Structural Regex / AST | Line budgets, MediatR handlers, shallow catch detection, fake in-memory stubs (`UseInMemoryDatabase`), `using` namespace indexing |
-| **Python** | `.py` | Structural Regex / AST | Line budgets, AI slop text patterns, fake assertions (`assert True`), `def`/`class` and `import` indexing |
-| **Go** | `.go` | Structural Regex / AST | Line budgets, mock data scanning, tautological assertions, `func`/`type` package indexing |
-| **Rust** | `.rs` | Structural Regex / AST | Line budgets, AI slop text patterns, secret scanning, struct and fn indexing |
+| **Python** | `.py` | Universal text passes | Line budgets, AI slop text patterns, mock data and secret scanning, fake assertions (`assert True`), `def`/`class` and `import` indexing |
+| **Go** | `.go` | Universal text passes | Line budgets, mock data scanning, tautological assertions, `func`/`type` package indexing |
+| **Rust** | `.rs` | Universal text passes | Line budgets, AI slop text patterns, secret scanning, struct and fn indexing |
+| **PHP / WordPress** | `.php` | `php-parser` AST (loaded only when a PHP file is audited) | Complexity, structural weight, nested ternary, swallowed catches, dynamic code and command execution, and in a WordPress plugin, theme or core tree: REST route permissions, missing nonces, and opt-in SQL, input, output, SSRF and redirect rules. See [docs/php-wordpress.md](docs/php-wordpress.md) |
 | **TypeScript / JavaScript** | `.ts`, `.tsx`, `.js`, `.jsx` | `@babel/parser` AST (`.vue` via `@vue/compiler-sfc`: every script block plus the template) | AST visitors across 11 audit categories, mapped to the 7 pillars; hook contracts, 2-stage booleans, lazy rule trees |
 | **Vue & Svelte** | `.vue`, `.svelte` | Babel + Template Registry | SFC template clone detection, reactive state verification |
 
@@ -334,7 +342,9 @@ Chemical X audits more than one language. The table below lists the extensions i
    * **Polyglot Fake Green Tests:** Catches tautological assertions in C# (`Assert.True(true)`), Python (`assert True`), and Go (`assert.True(t, true)`).
 2. **Tier 2: Deep Language-Specific Analyzers**
    * **Babel Engine:** Deep AST inspection for JS/TS/Vue/Svelte (runs on JS, TS, Vue and Svelte files only).
+   * **PHP Engine:** `php-parser` AST passes for `.php` files, plus WordPress passes (REST permissions, nonces, SQL, input flow) when a plugin, theme or core tree is detected. Some rules are default-off; `docs/php-wordpress.md` lists the shipped defaults, the per-plugin index and its caps.
    * **Control Flow & Guard Disciplines (`CONTROL_FLOW_CASCADE_GUARDS`, `CONTROL_FLOW_SILENT_GUARD`):** Flags silent bare returns in side-effecting code, and detects cascading early-return clusters (>= 3 guards), recommending extraction into `ruleTree` with 1-line callback aborts (Directive 3.H).
+   * **Tailwind content coverage (`TAILWIND_UNSCANNED_CLASS_STRING`):** In a Tailwind v3 project, flags a string literal of 3 or more utility classes (2 or more of them Tailwind-shaped) in a `.js`, `.ts`, `.mjs` or `.cjs` file that no `content` glob of `tailwind.config` covers, since Tailwind purges classes it never scans. The config is read as text and never imported; Tailwind v4, a missing config or a non-literal `content` list keep the rule silent. HIGH, Directive 5.B. `options.tailwindContent` overrides the globs for tests.
    * **C# / Clean Architecture Analyzer:** Flags empty `catch (Exception) {}` blocks, simulated delays (`Task.Delay`), and monolithic controllers.
    * **Swallowed catches (`ERROR_SWALLOWED_EXCEPTION`, `AI_SLOP_SHALLOW_CATCH`):** Each swallowing catch site reports once, as `ERROR_SWALLOWED_EXCEPTION` when the error is discarded or `AI_SLOP_SHALLOW_CATCH` when it is only logged to the console. Both are MEDIUM by default. A JS/TS catch escalates to HIGH when a `let` or `var` assigned in the try is read after it with no default or check first (silent `undefined` propagation); C# findings stay MEDIUM. Mark an intentional swallow with a `chemx-allow: best-effort <reason>` comment on the line above the catch, on the catch line, inside its body, or after the try block's closing brace when `catch` starts the next line. Only comments count (never string literals), and the reason is mandatory: an annotation without one is still flagged and its hazard says so.
 

package/blueprints/_vitest.config.svelte.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+
+export default defineConfig({
+  plugins: [svelte()],
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['**/*.spec.ts', '**/*.test.ts']
+  }
+});

package/blueprints/_vitest.config.vue.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    include: ['**/*.spec.ts', '**/*.test.ts']
+  }
+});

package/blueprints/molecule-capsule/index.svelte.ts

@@ -0,0 +1,2 @@
+export { default as MSampleCard } from './m-sample-card.svelte';
+export type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';

package/blueprints/molecule-capsule/index.vue.ts

@@ -0,0 +1,2 @@
+export { default as MSampleCard } from './m-sample-card.vue';
+export type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';

package/blueprints/molecule-capsule/m-chemx-badge/index.svelte.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export { default as MChemxBadge } from './m-chemx-badge.svelte';
+export { default } from './m-chemx-badge.svelte';

package/blueprints/molecule-capsule/m-chemx-badge/index.vue.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export { default as MChemxBadge } from './m-chemx-badge.vue';
+export { default } from './m-chemx-badge.vue';

package/blueprints/molecule-capsule/m-sample-card.spec.svelte.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { render } from 'svelte/server';
+import MSampleCard from './m-sample-card.svelte';
+
+describe('m-sample-card: MSampleCard Component', () => {
+  it('renders title, formatted value, and standard badge correctly', () => {
+    const { body } = render(MSampleCard, {
+      props: { title: 'Core Subscription', subtitle: 'Monthly compute tier', value: 750 }
+    });
+
+    expect(body).toContain('class="m-sample-card"');
+    expect(body).toContain('Core Subscription');
+    expect(body).toContain('Monthly compute tier');
+    expect(body).toContain('$750');
+    expect(body).toContain('m-sample-card__badge--standard');
+    expect(body).not.toContain('m-sample-card__action');
+  });
+
+  it('renders high-value modifier when numeric value exceeds 1000', () => {
+    const { body } = render(MSampleCard, { props: { title: 'Enterprise Cluster', value: 2500 } });
+
+    expect(body).toContain('Enterprise Cluster');
+    expect(body).toContain('$2,500');
+    expect(body).toContain('m-sample-card__badge--high-value');
+  });
+
+  it('renders the action button only when onAction is given', () => {
+    const { body } = render(MSampleCard, { props: { title: 'Actionable Unit', value: 1200, onAction: () => undefined } });
+
+    expect(body).toContain('m-sample-card__action');
+    expect(body).toContain('Action');
+  });
+});

package/blueprints/shims-svelte.d.ts

@@ -0,0 +1,3 @@
+// Svelte ships the `*.svelte` module declaration; this reference loads it for every tsc run,
+// including one where no .ts file imports from 'svelte' itself.
+/// <reference types="svelte" />

package/cli/apply-edits.js

@@ -21,9 +21,12 @@ import { findForeignLease } from './edit-locks.js';
 import { syncLeasesAfterEdit } from './team/lease-renew.js';
 import { countLines } from './line-count.js';
 
+// A refusal caused by one block of a multi-block patch carries { block, blocks } (cli/patch-block-blame.js).
+const issueLine = (issue) => `${issue.block ? `Block ${issue.block} of ${issue.blocks}: ` : ''}${issue.file}: ${issue.reason}`;
+
 export class EditRefusedError extends Error {
   constructor(issues) {
-    super(issues.map((i) => `${i.file}: ${i.reason}`).join('\n'));
+    super(issues.map(issueLine).join('\n'));
     this.name = 'EditRefusedError';
     this.issues = issues;
   }

package/cli/args-unsplit-hint.js

@@ -0,0 +1,33 @@
+/**
+ * The zsh unsplit-argument hint (#6773). zsh does not word-split an unquoted $var, so `chemx commit $files`
+ * receives ONE argument, "a.js b.js", and every command answered with a message that blamed the files
+ * (not tracked, File not found, matched nothing). One shared check lets commit, check and test say the
+ * real cause: an argument that has whitespace between words and is not a path on disk.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const UNSPLIT_HINT = 'one argument contains spaces: did a zsh variable not split? use an array or ${=var}';
+
+const hasInnerSpace = (arg) => /\S\s+\S/.test(String(arg));
+
+const diskLookup = (cwd) => (arg) => fs.existsSync(path.resolve(cwd, arg));
+
+/**
+ * @param {string[]} args Paths or specs a command expected as separate arguments.
+ * @param {{ cwd?: string, exists?: (arg: string) => boolean }} [options] `exists` decides what is on disk (default: relative to `cwd`).
+ * @returns {string|null} The first argument that has spaces between words and is not a path on disk.
+ */
+export const findUnsplitArgument = (args, { cwd = process.cwd(), exists = diskLookup(cwd) } = {}) => {
+  const candidates = (args ?? []).filter(hasInnerSpace);
+  return candidates.find((arg) => !exists(arg)) ?? null;
+};
+
+/** @returns {string} UNSPLIT_HINT when an argument looks unsplit, else ''. */
+export const unsplitHint = (args, options = {}) => (findUnsplitArgument(args, options) === null ? '' : UNSPLIT_HINT);
+
+/** @returns {string} `message` with the hint in parentheses when an argument looks unsplit. */
+export const withUnsplitHint = (message, args, options = {}) => {
+  const hint = unsplitHint(args, options);
+  return hint ? `${message} (${hint})` : message;
+};

package/cli/audit/audit-plain.js

@@ -10,6 +10,14 @@ const formatGate = (gate) => {
   return `gate: ${verdict}${basis}${note}`;
 };
 
+// One line per language, only when more than one language was scanned.
+const formatLanguageLines = (coverage) => {
+  const entries = Object.entries(coverage?.byLanguage ?? {});
+  const isMultiLanguage = entries.length > 1;
+  if (!isMultiLanguage) return [];
+  return entries.map(([language, c]) => `  ${language}: ${c.files} files, ${c.ast} ast, ${c.textOnly} text-only, ${c.parseErrors} parse errors`);
+};
+
 export const formatPlainAuditSummary = (summary) => {
   const { critical, highMedium, low } = summary.hazards;
   const total = critical + highMedium + low;
@@ -21,6 +29,7 @@ export const formatPlainAuditSummary = (summary) => {
   for (const { rule, baseline, current } of summary.gate.regressions ?? []) {
     lines.push(`  regression: ${rule} ${baseline} -> ${current}`);
   }
+  lines.push(...formatLanguageLines(summary.coverage));
   lines.push('detail: chemx audit --json | chemx audit --unroll | chemx q --hazards');
   return `${lines.join('\n')}\n`;
 };

package/cli/audit/audit-summary.js

@@ -14,8 +14,8 @@ const countHazards = (violations = []) => {
 
 const summarizeCoverageForCard = (coverage) => {
   if (!coverage) return null;
-  const { files, astPct, parseErrors, textOnly, isPartial, sfc } = coverage;
-  return { files, astPct, parseErrors, textOnly, isPartial, sfcTemplates: sfc?.templatesParsed ?? 0 };
+  const { files, astPct, parseErrors, textOnly, isPartial, sfc, byLanguage = {} } = coverage;
+  return { files, astPct, parseErrors, textOnly, isPartial, sfcTemplates: sfc?.templatesParsed ?? 0, byLanguage };
 };
 
 export const buildAuditSummary = (report, { projectRoot, scope }) => {

package/cli/audit/base-delta.js

@@ -0,0 +1,89 @@
+/**
+ * Delta gate against a base ref (#6091): each changed source file's working-tree content
+ * is audited against the same file at the base, and the gate fails only when a rule's
+ * violation count rises in a file, at any severity (gate-delta.js, the rule the pre-commit
+ * hook and the ratchet apply). Hazards the base already has never count, so a change that
+ * fixes one rule is not held red by other rules the repo-wide ratchet fails on.
+ *
+ * The base is merge-base(<ref>, HEAD) when there is one, the same starting point
+ * `verify --changed --base=<ref>` uses to list changed files; otherwise <ref> itself.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/index.js';
+import { isSourceFilePath } from '../audit-preflight-git.js';
+import { evaluateChanges, formatSites } from './gate-delta.js';
+import { gitText, parseNameStatus, changeFromContents } from './staged-delta.js';
+
+const DIFF_ARGS = ['diff', '--name-status', '-z', '-M', '--diff-filter=ACMR', '--relative'];
+
+/** { label, rev } for an existing commit-ish, null when `baseRef` names none. A leading `-` is never a ref. */
+const resolveBase = (cwd, baseRef) => {
+  const isOptionLike = typeof baseRef !== 'string' || baseRef === '' || baseRef.startsWith('-');
+  if (isOptionLike) return null;
+  const commit = gitText(cwd, ['rev-parse', '--verify', '--quiet', `${baseRef}^{commit}`]);
+  const isMissing = commit === null;
+  if (isMissing) return null;
+  const mergeBase = gitText(cwd, ['merge-base', baseRef, 'HEAD']);
+  return { label: baseRef, rev: (mergeBase ?? commit).trim() };
+};
+
+/** Untracked, non-ignored source files: new content in the working tree that git diff does not list. */
+const listUntrackedSources = (cwd) =>
+  (gitText(cwd, ['ls-files', '--others', '--exclude-standard', '-z']) ?? '')
+    .split('\0')
+    .filter((file) => file !== '' && isSourceFilePath(file))
+    .map((file) => ({ file, basePath: null, isRename: false }));
+
+/** Changed source files vs `rev` as { file, basePath, isRename }, paths relative to `cwd`; a file is listed once. */
+const listBaseSources = (cwd, rev) => {
+  const tracked = parseNameStatus(gitText(cwd, [...DIFF_ARGS, rev, '--']) ?? '');
+  const seen = new Set(tracked.map((entry) => entry.file));
+  return [...tracked, ...listUntrackedSources(cwd).filter((entry) => !seen.has(entry.file))];
+};
+
+const readWorkingTree = (cwd, file) => {
+  const absPath = path.join(cwd, file);
+  const isFile = fs.statSync(absPath, { throwIfNoEntry: false })?.isFile() === true;
+  return isFile ? fs.readFileSync(absPath, 'utf-8') : null;
+};
+
+const toChange = (cwd, rev, entry, config) => {
+  const afterText = readWorkingTree(cwd, entry.file);
+  const isReadable = afterText !== null;
+  if (!isReadable) return null;
+  const baseText = entry.basePath ? gitText(cwd, ['show', `${rev}:./${entry.basePath}`]) ?? '' : '';
+  return changeFromContents(cwd, entry, { baseText, afterText, config });
+};
+
+/**
+ * Per-rule delta of the working tree against `baseRef`. `options.config` replaces the project
+ * config loaded from `cwd` and `rawArgs` (verify passes the one it already holds).
+ *
+ * @returns {{ isPassing: boolean, base: string, rev?: string, checked: number, files: object[], baseMissing?: boolean, error?: string }}
+ * An unknown ref never throws and never passes: it returns baseMissing with isPassing false, so
+ * a typo cannot turn the gate green.
+ */
+export const evaluateBaseDelta = (cwd = process.cwd(), baseRef, rawArgs = [], options = {}) => {
+  const resolved = resolveBase(cwd, baseRef);
+  const isMissing = resolved === null;
+  if (isMissing) return { isPassing: false, base: baseRef ?? null, checked: 0, files: [], baseMissing: true, error: `unknown base revision "${baseRef ?? ''}"` };
+  const config = options.config ?? loadProjectConfig(cwd, rawArgs);
+  const entries = listBaseSources(cwd, resolved.rev);
+  const changes = entries.map((entry) => toChange(cwd, resolved.rev, entry, config)).filter(Boolean);
+  return { ...evaluateChanges(changes), base: resolved.label, rev: resolved.rev, checked: changes.length };
+};
+
+/** The delta as the compact block `verify --json` carries: rising rules and one `RULE@file:line [SEVERITY]` per new hazard. */
+export const summarizeBaseDelta = (delta) => ({
+  base: delta.base,
+  passing: delta.isPassing,
+  checked: delta.checked,
+  ...(delta.error ? { error: delta.error } : {}),
+  files: delta.files.map((entry) => ({
+    file: entry.file,
+    ...(entry.renamedFrom ? { renamedFrom: entry.renamedFrom } : {}),
+    increases: entry.increases.map(({ rule, severity, before, after }) => ({ rule, severity, before, after })),
+    sites: formatSites(entry)
+  }))
+});

package/cli/audit/coverage.js

@@ -13,10 +13,33 @@ export const COVERAGE_KINDS = Object.freeze({
 
 export const createCoverageCollector = () => ({ files: [] });
 
-/** Records one file. `sfc` is { scriptBlocks, hasTemplate, isTemplateParsed } for .vue files. */
-export const recordFileCoverage = (collector, { relativePath, kind, sfc = null }) => {
+/**
+ * Records one file. `sfc` is { scriptBlocks, hasTemplate, isTemplateParsed } for .vue files;
+ * `language` (language id) and `reason` (why the file was not fully parsed) are optional.
+ */
+export const recordFileCoverage = (collector, { relativePath, kind, sfc = null, language = null, reason = null }) => {
   if (!collector) return;
-  collector.files.push({ relativePath, kind, sfc });
+  collector.files.push({ relativePath, kind, sfc, language, reason });
+};
+
+const BUCKET_FIELD_BY_KIND = {
+  [COVERAGE_KINDS.AST]: 'ast',
+  [COVERAGE_KINDS.TEXT_ONLY]: 'textOnly',
+  [COVERAGE_KINDS.PARSE_ERROR]: 'parseErrors'
+};
+
+const summarizeByLanguage = (entries) => {
+  const byLanguage = {};
+  for (const entry of entries) {
+    if (!entry.language) continue;
+    const bucket = byLanguage[entry.language] ?? { files: 0, ast: 0, textOnly: 0, parseErrors: 0 };
+    bucket.files += 1;
+    const field = BUCKET_FIELD_BY_KIND[entry.kind];
+    const isCounted = Boolean(field);
+    if (isCounted) bucket[field] += 1;
+    byLanguage[entry.language] = bucket;
+  }
+  return byLanguage;
 };
 
 const isPartialEntry = (entry) => {
@@ -42,6 +65,7 @@ export const summarizeCoverage = (collector) => {
       scriptBlocks: sfcEntries.reduce((sum, e) => sum + (e.sfc.scriptBlocks ?? 0), 0),
       templatesParsed: sfcEntries.filter((e) => e.sfc.isTemplateParsed).length
     },
+    byLanguage: summarizeByLanguage(entries),
     isPartial: partialFiles.length > 0,
     partialFiles: partialFiles.slice(0, 20)
   };