@chemx/starter-kit 26.10.19-530 → 26.10.26-386

package/AGENTS.md

@@ -8,17 +8,31 @@
 ## ⚡ Quick Agent Reflex Table (Token-Bounded Commands)
 | Standard Reflex | `chemx` Equivalent | Token & Architecture Advantage |
 | :--- | :--- | :--- |
-| `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. |
+| `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. |
 
@@ -112,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
@@ -151,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)
@@ -176,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.
@@ -527,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.
 
@@ -571,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`.
@@ -585,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
@@ -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,6 +342,7 @@ 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.

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/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)
   };

package/cli/audit/inconclusive.js

@@ -0,0 +1,36 @@
+/**
+ * Inconclusive audit results: a file whose language has an AST parser but whose coverage record
+ * is not "ast" (--fast, parser unavailable, minified, parse error) was only partly examined, so a
+ * low hazard count says nothing about it. Shared by `chemx check`, the edit guardrails and
+ * `task done`. An empty file is conclusive; a language with no AST parser is never inconclusive.
+ */
+import path from 'node:path';
+import { LANGUAGE_DEFINITIONS, getLanguageByExtension, isSourceFile } from '../languages.js';
+
+const AST_PARSERS = new Set(['babel', 'php']);
+const NO_REASON = 'no reason recorded';
+
+const hasAstParser = (language) => language === 'php' || AST_PARSERS.has(LANGUAGE_DEFINITIONS[language]?.parser);
+
+/** @param {{ kind?: string, language?: string|null, reason?: string|null }|null|undefined} coverage */
+export const isInconclusive = (coverage) => {
+  const hasLanguage = Boolean(coverage && coverage.language);
+  if (!hasLanguage) return false;
+  const isCovered = coverage.kind === 'ast' || coverage.kind === 'empty';
+  return hasAstParser(coverage.language) && !isCovered;
+};
+
+/** The "inconclusive: <reason>" text for a coverage record, or null when the result is conclusive. */
+export const inconclusiveReason = (coverage) => (isInconclusive(coverage) ? (coverage.reason || coverage.kind || NO_REASON) : null);
+
+/**
+ * True for a file the audit accepts: a known source extension, or one whose language was added to
+ * LANGUAGE_DEFINITIONS after load (the extension table is built once, so this also lets specs
+ * register a language). Tests count as source, matching auditFile.
+ */
+export const isAuditableSource = (name) => {
+  const isKnownSource = isSourceFile(name, { includeTests: true });
+  const isExcluded = name.includes('.min.') || name.endsWith('.d.ts');
+  const isRegistered = !isExcluded && Boolean(getLanguageByExtension(path.extname(name)));
+  return isKnownSource || isRegistered;
+};

package/cli/audit/line-budgets.js

@@ -63,6 +63,9 @@ const DEFAULT_TIER_PATTERNS = Object.freeze({
   view: [/(?:^|[\\/])views[\\/]/, /(?:^|[\\/])pages[\\/]/, /View\.[tj]sx?$/]
 });
 const VIEW_MARKUP_EXTENSIONS = new Set(['.vue', '.tsx', '.jsx', '.svelte']);
+// PHP is view markup only as a WordPress partial or template; PHP has no molecule tier.
+const PHP_VIEW_DIRECTORY = /(?:^|[\\/])(?:partials|templates)[\\/]/;
+const isPhpPath = (relativePath) => path.extname(relativePath).toLowerCase() === '.php';
 
 /** Lines as `wc -l` counts them: a trailing newline does not open a new line. */
 export const countLines = (content) => {
@@ -141,6 +144,7 @@ const matchesConfiguredTier = (relPath, globs = []) => globs.some((glob) => glob
 /** 'molecule' | 'view' | null. `.chemxrc` `tiers: { molecule: [globs], view: [globs] }` extends the defaults. */
 export const resolveFileTier = (relativePath, config = {}) => {
   const normalized = relativePath.split(path.sep).join('/');
+  if (isPhpPath(normalized)) return PHP_VIEW_DIRECTORY.test(normalized) ? 'view' : null;
   const baseName = path.basename(normalized);
   const tiers = config.tiers || {};
   const isMolecule = DEFAULT_TIER_PATTERNS.molecule.some((re) => re.test(normalized)) ||
@@ -151,4 +155,8 @@ export const resolveFileTier = (relativePath, config = {}) => {
 };
 
 /** View budgets apply to markup-bearing view entries, never to .ts/.js controllers. */
-export const isViewMarkupFile = (relativePath) => VIEW_MARKUP_EXTENSIONS.has(path.extname(relativePath));
+export const isViewMarkupFile = (relativePath) => {
+  const normalized = relativePath.split(path.sep).join('/');
+  if (isPhpPath(normalized)) return PHP_VIEW_DIRECTORY.test(normalized);
+  return VIEW_MARKUP_EXTENSIONS.has(path.extname(relativePath));
+};

package/cli/audit/ratchet.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { RULESET_VERSION, resolveRuleRevision } from './rule-revisions.js';
 import { RULE_REGISTRY } from './rules-registry.js';
+import { LANGUAGE_DEFINITIONS } from '../languages.js';
 
 /**
  * chemx-ratchet.json, format version 2:
@@ -12,10 +13,38 @@ import { RULE_REGISTRY } from './rules-registry.js';
  * `allRules: true` means `revisions` lists every rule that existed at recording time,
  * so a registered rule missing from it is new and is adopted even if nobody bumped its revision.
  * Every full scan upgrades the scope to the current rule set (see upgradeScope).
+ * `languages` lists the file extensions a scope was recorded over. A scope without it is
+ * read as the extensions scanned before PHP support (LEGACY_LANGUAGES). Counts from
+ * violations in a file whose extension is not in that set are adopted, not gated, and the
+ * extension is then recorded; violations without a file path are always gated.
  */
 export const RATCHET_FILE = 'chemx-ratchet.json';
 const RATCHET_VERSION = 2;
 
+const PRE_PHP_EXCLUDED = new Set(['.php']);
+const allExtensions = () => Object.values(LANGUAGE_DEFINITIONS).flatMap((lang) => [...lang.extensions]);
+const LEGACY_LANGUAGES = allExtensions().filter((ext) => !PRE_PHP_EXCLUDED.has(ext)).sort();
+
+/** The extensions a full scan covers now (what a scope records). */
+const currentLanguages = () => allExtensions().sort();
+
+const recordedLanguages = (entry) => (Array.isArray(entry.languages) ? entry.languages : LEGACY_LANGUAGES);
+
+const mergeLanguages = (entry, adopted = []) => {
+  const adoptedExtensions = adopted.flatMap((item) => item.extensions ?? []);
+  return [...new Set([...recordedLanguages(entry), ...currentLanguages(), ...adoptedExtensions])].sort();
+};
+
+const extensionOf = (violation) => {
+  const file = violation.filePath ?? violation.file;
+  return typeof file === 'string' ? path.extname(file).toLowerCase() : '';
+};
+
+const isOutsideLanguages = (violation, languages) => {
+  const ext = extensionOf(violation);
+  return ext !== '' && !languages.has(ext);
+};
+
 export const countViolationsByRule = (violations = []) => {
   const counts = {};
   for (const v of violations) counts[v.rule] = (counts[v.rule] ?? 0) + 1;
@@ -69,7 +98,7 @@ const readExistingOrEmpty = (projectRoot) => {
 export const writeRatchet = (projectRoot, { scope, violations }) => {
   const ratchet = readExistingOrEmpty(projectRoot);
   const rules = sortKeys(countViolationsByRule(violations));
-  ratchet.scopes[scope] = { ruleset: RULESET_VERSION, allRules: true, rules, revisions: currentRevisions(rules) };
+  ratchet.scopes[scope] = { ruleset: RULESET_VERSION, allRules: true, rules, revisions: currentRevisions(rules), languages: currentLanguages() };
   persistRatchet(projectRoot, ratchet);
   return ratchet.scopes[scope];
 };
@@ -86,7 +115,8 @@ const upgradeScope = (entry, adopted) => {
     ruleset: Math.max(entry.ruleset ?? 1, RULESET_VERSION),
     allRules: true,
     rules: sortKeys(rules),
-    revisions: currentRevisions(rules)
+    revisions: currentRevisions(rules),
+    languages: mergeLanguages(entry, adopted)
   };
 };
 
@@ -94,7 +124,8 @@ const upgradeScope = (entry, adopted) => {
 export const needsScopeUpgrade = (entry, adopted = []) => {
   if (!entry) return false;
   const upgraded = upgradeScope(entry, adopted);
-  const isSame = JSON.stringify(upgraded) === JSON.stringify({ ruleset: entry.ruleset, allRules: entry.allRules, rules: entry.rules, revisions: entry.revisions });
+  const stored = { ruleset: entry.ruleset, allRules: entry.allRules, rules: entry.rules, revisions: entry.revisions, languages: entry.languages };
+  const isSame = JSON.stringify(upgraded) === JSON.stringify(stored);
   return !isSame;
 };
 
@@ -116,7 +147,10 @@ const recordedRevision = (entry, rule) => {
 };
 
 const compareToBaseline = (entry, violations) => {
+  const languages = new Set(recordedLanguages(entry));
   const current = countViolationsByRule(violations);
+  const outsideViolations = violations.filter((v) => isOutsideLanguages(v, languages));
+  const outside = countViolationsByRule(outsideViolations);
   const allRules = new Set([...Object.keys(current), ...Object.keys(entry.rules)]);
   const regressions = [];
   const adopted = [];
@@ -125,9 +159,14 @@ const compareToBaseline = (entry, violations) => {
     const count = current[rule] ?? 0;
     const isNewerRevision = revision > recordedRevision(entry, rule);
     const baseline = entry.rules[rule] ?? 0;
-    if (isNewerRevision) adopted.push({ rule, baseline, current: count, revision });
-    const isRegression = !isNewerRevision && count > baseline;
-    if (isRegression) regressions.push({ rule, baseline, current: count });
+    const outsideCount = outside[rule] ?? 0;
+    const gatedCount = count - outsideCount;
+    const extensions = [...new Set(outsideViolations.filter((v) => v.rule === rule).map(extensionOf))];
+    if (isNewerRevision) adopted.push({ rule, baseline, current: count, revision, extensions });
+    const isLanguageAdoption = !isNewerRevision && outsideCount > 0;
+    if (isLanguageAdoption) adopted.push({ rule, baseline, current: baseline + outsideCount, revision, reason: 'language', extensions });
+    const isRegression = !isNewerRevision && gatedCount > baseline;
+    if (isRegression) regressions.push({ rule, baseline, current: gatedCount });
   }
   return { regressions, adopted };
 };

package/cli/audit/rule-overrides.js

@@ -3,17 +3,20 @@
  * (finding config-not-honored):
  *   rules: { "RULE_ID": "off" | "low" | "medium" | "high" | "critical" }
  *   overrides: [{ files: "glob" | ["globs"], rules: { "RULE_ID": "off" | <severity> } }]
+ *   A setting of "on" (or true) enables a default-off rule and keeps the engine's severities.
  *   ai-slop-detection: "off" drops AI_SLOP_* rules, "medium" caps them at MEDIUM.
  *   pillars (from .chemx/config.json): a disabled product pillar drops its rules.
  * Later overrides win over earlier ones, and every override wins over `rules`.
  */
 import { globToRegExp } from './line-budgets.js';
 import { resolvePillarDisabledRules } from './rule-pillars.js';
+import { RULE_REGISTRY } from './rules-registry.js';
 
 const SEVERITIES = new Map([['low', 'LOW'], ['medium', 'MEDIUM'], ['high', 'HIGH'], ['critical', 'CRITICAL']]);
 const SEVERITY_RANK = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
 const RULE_ID_SHAPE = /^[A-Z][A-Z0-9_]+$/;
 const OFF = 'off';
+const ON = 'on';
 
 const isSlopRule = (rule) => typeof rule === 'string' && rule.startsWith('AI_SLOP_');
 
@@ -21,6 +24,8 @@ const normalizeSetting = (value) => {
   const lowered = String(value).toLowerCase();
   const isOff = lowered === OFF || value === false;
   if (isOff) return OFF;
+  const isOn = lowered === ON || value === true;
+  if (isOn) return ON;
   return SEVERITIES.get(lowered) ?? null;
 };
 
@@ -60,17 +65,26 @@ const applySlopPolicy = (violation, policy) => {
   return isCapped ? { ...violation, severity: 'MEDIUM' } : violation;
 };
 
-/** Applies `rules`, `overrides` and `ai-slop-detection` to one file's violations. */
-export const applyRuleOverrides = (violations, relativePath, config = {}) => {
+/**
+ * Applies `rules`, `overrides` and `ai-slop-detection` to one file's violations.
+ * A rule is off by default when its registry entry has `isDefaultOff: true` or the caller's
+ * `defaultOff` set names it, until a setting names it: "on" (or true) enables it and keeps the
+ * engine's per-violation severities, a severity enables it and overwrites them.
+ * options: { registry (default RULE_REGISTRY), defaultOff (Set of rule ids) }.
+ */
+export const applyRuleOverrides = (violations, relativePath, config = {}, options = {}) => {
+  const { registry = RULE_REGISTRY, defaultOff = new Set() } = options;
   const settings = resolveRuleSettings(relativePath, config);
   const pillarDisabled = resolvePillarDisabledRules(config.pillars);
   const slopPolicy = String(config.rules?.aiSlopDetection ?? config.rules?.['ai-slop-detection'] ?? 'critical').toLowerCase();
   const result = [];
   for (const violation of violations) {
     const setting = settings[violation.rule];
-    const isOff = setting === OFF || (!setting && pillarDisabled.has(violation.rule));
+    const isDefaultOff = registry[violation.rule]?.isDefaultOff === true || defaultOff.has(violation.rule);
+    const isOff = setting === OFF || (!setting && (isDefaultOff || pillarDisabled.has(violation.rule)));
     if (isOff) continue;
-    const withSeverity = setting ? { ...violation, severity: setting } : violation;
+    const isSeverityOverride = Boolean(setting) && setting !== ON;
+    const withSeverity = isSeverityOverride ? { ...violation, severity: setting } : violation;
     const afterSlop = setting ? withSeverity : applySlopPolicy(withSeverity, slopPolicy);
     if (afterSlop) result.push(afterSlop);
   }