mirror of
https://github.com/zernie/vigiles.git
synced 2026-09-14 20:53:57 +08:00
zernie
45a7690ec2
* fix(site): replace unmeasured claims about other tools with a measurement The hero opened with "Nothing checks that the tools, events, files and rules your skills and hooks name actually exist." Nobody had ever run the other tool. Two things were wrong with the sentence: it is a universal negative over every tool that exists, which is unmeasurable, and on its own terms it is false for one of its four nouns. Measured instead, and the probe is committed as tools/measure-validate-overlap.mjs so the next reader reruns it rather than trusting prose. Against Claude Code 2.1.263, seven planted defects, both harness shapes: repo-local .claude/ 0 of 7 flagged, default AND --strict packaged plugin 1 of 7 — "hooks.PreToolUze: unknown hook event" The silence is real silence: the same binary errors on invalid manifest JSON and on a hooks.json missing its root key, and warns on an agent with no description, so it does read these files. That measurement moved claims in BOTH directions, which is the point: - Hero drops the universal negative and describes only what vigiles does. - Wedge credits `claude plugin validate` with the hook-event check it really makes, scoped to plugin form, and stops listing that check among the ones it misses. A draft of this paragraph had it in the wrong column. - docs/rules/hook-script-exists.md said the rule "matches Anthropic's own `claude plugin validate`, making vigiles a superset on the hook surface". Measured false — validate does not check hook-script existence at all. We were under-crediting our own rule. Corrected in place rather than deleted, so it does not read as a wording change and get added back. - Same false credit removed from the subagent-frontmatter keyFile: validate flags neither `model: sonnnet` nor `color: purpel`, and cclint was never run. Every claim of exclusivity, scope or comparison now carries a comment above it with the claim, the command that backs it and the version, what the earlier version said and why it was wrong, and what would invalidate it. The record of the mistake is the part that prevents the repeat. Two live falsehoods found on the page while verifying the above: - The first failure card and the `audit` example both used `event: "Setup"` as a hook event that does not exist. `Setup` IS a real Claude Code event, with its own docs sections; this repo's own catalog learned that on 2026-08-17 and the site never followed. The page's opening example of "config that parses and does the wrong thing" was config that works. Now `PreToolUze`, verified wrong in both directions against the real binary. - The `eval` row quoted the debunked claim as 65%. Three places in this repo and the linked post all say 65%. A debunk that misquotes its own target is the one number a reader checks in ten seconds. Also: the hero's language chip said "Any language · 11 linter catalogs" — an overclaim wrapped around a term a cold visitor cannot gloss, which never told a Python developer that Ruff and Pylint are covered. It now names the languages, still derived from BUILTIN_LINTERS, with a test that fails if a shipped linter has no language decision or a covered language is missing from the display order. Both directions proved by mutation. The landing-site skill is committed in this public repo and carried a "backend (roadmap)" design for an unbuilt capability plus a growth-loop framing, which no-product-strategy-here forbids here. The technical guidance stays; the roadmap and the growth narrative are gone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: replace the unmeasured exclusivity claim with the mechanism "No other tool resolves rules across 11 catalog APIs" stood in five places. It rested on a competitor matrix whose cells were checked against DOCUMENTATION rather than against a run — the same matrix that put a false claim on the landing page, corrected in the previous commit after measuring the real binary. Two independent reasons to drop it, not one: 1. It was never measured. Verifying it means enumerating 11 catalog APIs across every comparable tool, which nobody did. 2. This repository is public, and its own `no-product-strategy-here` rule forbids competitive positioning here outright. "The core moat" and "no other tool" are positioning, so those lines were a rule violation independent of whether they happened to be true. Replaced with what the engine actually does, which a reader can check by running it: the rule name is resolved against the linter's own catalog rather than matched as a string, and the enabled state is read from the project's config. The removal is recorded in the source rather than performed silently. A silent deletion reads as a wording change and invites the claim back; the comment in linters.ts says what stood there and why it went. Sites: docs/linter-support.md, docs/what-vigiles-catches.md, src/core/linters.ts, CLAUDE.md.spec.ts, examples/CLAUDE.md.spec.ts (the two CLAUDE.md artifacts recompiled). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(compile): the section size guard measured the wrong unit `DEFAULT_MAX_SECTION_LINES = 200` reads as "a section may not sprawl" and never fired on the section that actually sprawled. Two reasons, both measured on this repo 2026-09-08: 1. The cap counts LINES. A `keyFiles` entry is ONE line of any length, so `## Key Files` reached 173 KB — 59% of the compiled CLAUDE.md — while staying far under 200 lines. Longest single description: 4782 chars. 2. `keyFiles` never reached the check at all. `compileKeyFilesSection` is a separate path that calls `validateFileRef` and nothing else, so the one section with no length control was the one that grew. Both closed: a character budget beside the line budget (whichever runs out first reports), and a per-entry cap on a key-file description, since an entry is a pointer and the reasoning belongs in that file's own header where a reader meets it on opening the file. RATCHETED, not bare. Introduced bare these caps open with 60 findings and get switched off the same day. `.vigiles/keyfile-debt.json` records the existing oversize once; the caps report only what is NEW or has GROWN, and a repo without the file gets every finding, which is the right default for everyone else. Lowering a number is the fix; raising one is the edit the file exists to make visible in review. Verified in three directions, not one: silent on the recorded debt, fires on an entry whose recorded size was lowered, fires on an entry removed from the debt entirely. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(docs): withdraw the unmeasured #30519 matcher claim, and record the probe `docs/compiled-hooks.md` and CLAUDE.md both said the native `if:` matcher misses a compound `cd repo && git push -f`, citing #30519, and offered that as a reason to prefer the AST-backed `runs()`. Measured against Claude Code 2.1.263: the native matcher CAUGHT the compound command, in both spellings. Either the issue was fixed the way #34692 was, or the claim was wrong when written. Withdrawn rather than repeated; a focused re-measure decides. What the same run DID establish is a real gap, and a sharper one: form input hook spawned prefix git push --force origin main YES prefix /usr/bin/git push --force origin main NO glob git push --force origin main YES glob /usr/bin/git push --force origin main NO An ABSOLUTE program head is matched by neither spelling. That holds for `Bash(git push:*)`, the form Anthropic ships in its own security-guidance plugin, as much as for the glob form — so a guard written either way does not run on `/usr/bin/git push --force`, which is the whole guard when the hook body is unconditional. The probe is committed as tools/measure-if-matcher-forms.mjs so the next person re-runs it after a Claude Code minor instead of trusting this note. It measures someone else's matcher, and prose cannot notice when that moves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(claude-md): key files are pointers again — 73k tokens to 43k `## Key Files` was 59% of the compiled CLAUDE.md. Its 266 entries had grown from index lines into paragraphs, median 371 characters, longest 4782 — and every one of them is loaded on every turn of every session in this repo. Measured before cutting anything: 220 of the 266 files ALREADY carry the same reasoning in their own header comment, usually in a fuller form. So this is mostly not a move, it is deletion of a duplicate that had drifted from the copy people actually read when they open the file. For the 17 entries whose file had no header, the prose was moved into one rather than dropped; 29 short entries were left alone. compiled CLAUDE.md 291579 -> 173682 chars ~72900 -> ~43400 tokens AND THE RATCHET IS GONE. The cap landed an hour earlier with a `.vigiles/keyfile-debt.json` recording 60 existing violations so it would not open loud enough to be switched off. That was the wrong order of work: a mechanism to tolerate the problem, invented instead of spending one pass fixing it. With the entries pruned the debt file is empty, so both it and the code reading it are deleted and the cap stands bare — 0 findings on a clean tree, fires on a lengthened entry. The section CHARACTER cap goes with it, for the same reason it should never have shipped ratcheted: `positioning` is 24877 characters and would fail it today, and a guard that cannot fire is the defect this product is about. That section is a real and separate piece of work, named here rather than recorded as debt. Verified in both directions on a clean tree: silent at 0 findings, and a mutation that lengthens one description fails on its own assertion. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(tools): record the WIDENED if: forms, which are the ones that are sound The probe measured the two `if:` spellings found in the wild and stopped there, leaving the useful half unmeasured: what a native `if:` would have to look like for a compiler to be allowed to emit one. Measured on Claude Code 2.1.263: emitted if: plain absolute unrelated Bash(git push *--force*) fires NO no Bash(git push:*) fires NO no Bash(*git*) fires fires no Bash(*) fires fires fires The natural translation of a typed predicate is strictly NARROWER than the body it guards — it misses an absolute program head — so emitting it turns a guard off on exactly the input a careful author wrote it for. Widening to the PROGRAM NAME alone keeps every case the body would catch and still filters unrelated commands, which is the property an emission needs: it may only ever add spawns, never remove one. Flags and subcommand refinement are dropped on purpose. Including them is what makes the natural translation too narrow, and the body re-checks them anyway. Left explicitly unmeasured so nobody assumes it: the widening for `touches()` and `pipesToShell()`. Either may have none, and the honest answer for such a primitive is to emit nothing rather than something that looks like a filter. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(claude-md): the two "layer" paragraphs point at their guides again `## Positioning` was 24891 characters, and two of its twelve paragraphs were 64% of it: Second layer — testing the harness 7859 chars Third layer — COMPILED HOOKS 8108 chars Both are summaries of a document that already exists, is far richer, and was already linked from the same paragraph: docs/harness-testing.md 37114 chars 4.8x the summary docs/compiled-hooks.md 62167 chars 7.8x the summary Same shape as the key-files entries in the previous commit: a copy that duplicates the text people actually read, drifts from it, and is loaded into every session's context whether or not the turn is about hooks. What was KEPT in each is the part that constrains what gets built or claimed, because that has to be in context and cannot live behind a link: the tier discipline (push a question down a tier; only firing and behaviour-movement touch a real model), that the mock-model tier is table stakes and must not be sold as distinctive, the `experimental_*` marking, that compile and verify fix authoring and logic and never delivery, and that a gate is a strong default and never an unbypassable wall. What went to the guides is the mechanics: the tier APIs, the role family, the vocabulary, the stamp. ## Positioning 24891 -> 11361 chars CLAUDE.md 43420 -> 40038 tokens (72894 before this branch) The section CHARACTER cap is still not restored, and this says why rather than leaving it looking forgotten: `## Rules` is 82586 characters and would fail any cap that means anything. Rules are a different problem — measured across 53 of them, median 1449 characters, and unlike a key-files entry or a layer summary there is no richer copy elsewhere to point at, because a rule's text IS the instruction. Trimming it loses information rather than removing a duplicate, so it is judgement, not a mechanical pass, and a 500-char cap would open on 40 of 53 and be switched off the same day. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(hook)!: a bash gate is Bash by construction — delete its match field `HookProgram.match: { tool: string }` was a representable illegal state, and the same false-confidence class the module header says this subsystem exists to eliminate: if (rawEvent.tool_name !== program.match.tool) return allow(); `match: tool("Edit")` type-checked, compiled, wired a PreToolUse matcher `Edit`, fired on edits, built `commandView("")` from a missing `tool_input.command`, found every predicate false and returned allow() — a silently dead guard. The comparison was `!==` while every sibling role routes through `matchesTool`; that runtime/emit disagreement is the one MEASURED and fixed for reacts on 2026-08-12 and documented in this very file's header. It survived on the flagship role. The field carried no information either: `BashToolEvent.tool` is the literal "Bash", and all 34 call sites across both repos wrote `match: tool("Bash")`. So the fix is deletion rather than unification: the matcher moves to `hookRouting`, the runtime keeps a defensive `!== "Bash"` on a literal nobody can mis-set, and the author's file loses a line it could only get wrong. BREAKING CHANGE: `tool` is no longer exported from `vigiles/hook`, and `HookProgram` no longer accepts `match`. Both are part of the compiled-hook vocabulary, whose entry points are `experimental_*`; taken now precisely because the vocabulary is still young. `tools()` — the plural, for file gates and reacts — is untouched, and so is the `tool()` CHECK in `vigiles` (a different function that happens to share the name). Found by an architecture review that was asked to break a different proposal. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(hook): restore the CHECK `tool()` a careless sweep took with it The previous commit removed `tool` from the compiled-hook vocabulary, and the regex that cleared its call sites also stripped `tool,` from `src/test.ts` — the `vigiles` ROOT barrel, where a DIFFERENT `tool()` lives: the check from `src/check.ts`, used as `assertChecks(run, [tool("Bash")])`. Two unrelated functions that happen to share a name, and the sweep could not tell them apart. That silently removed a stable public export. Nothing in the change was about it, the commit message did not mention it, and the api-surface diff that would have shown it was regenerated only afterwards. Caught by `docs-imports`, which type-checks the code blocks in `docs/` against the real surface and failed on `docs/testing-api.md:210` importing `tool` from `"vigiles"`. Worth noting which gate did it: the unit tests stayed green, because no test imports that symbol from the root barrel. A doc example was the only consumer standing in for every external one. Also completes the docs half of the previous commit, which shipped without it: `docs/compiled-hooks.md` still imported `tool` from `vigiles/hook` in three places, wrote `match: tool("Bash")` in four, and listed `tool(name)` in the vocabulary — all naming a function that no longer exists. And `api-surface/vigiles-hook.api.md` is regenerated, so the removal is visible as a reviewed diff rather than a surprise. Gates: `npm run check` — the only failure is `cli-lint`, whose 480 errors are all inside other sessions' gitignored worktrees (0 outside; CI never sees them). `docs-imports` 0 findings. `src/hook.test.ts` + `src/core/hook-program.test.ts` 120/120. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(examples): drop the `tool` import the sweep left behind Two example hooks kept importing `tool` from the hook vocabulary after the sweep removed their `match: tool("Bash")` line — and `tool` no longer exists, so the module failed to load: HookCompileError: Cannot load hook "examples/harness/protect-main.hook.mjs": Named export 'tool' not found. `compiled-hook-inprocess.harness.mjs` loads that file BY PATH and asserts over its decisions, so it went red. The runtime behaved correctly — a hook that cannot load must not pass traffic — which is why the failure surfaced as a refusal rather than a silent skip. HOW IT REACHED CI, which is the part worth recording: `npm run check` prints the CI jobs it does not cover, and `harness` was on that list. The change touched hooks throughout. I read the list, decided the harness tier was the known-environment-red one (`claude` 2.1.187 pinned vs 2.1.263 installed) and skipped it — while the note that records that redness says in as many words that redness IN CI is no longer environmental. The printed list did its job; I did not do mine with it. The unit tiers could not have caught this either: `src/hook.test.ts` writes its fixtures as source text and was updated with the sweep, so 120/120 stayed green while a shipped example was unloadable. Verified: `node examples/harness/compiled-hook-inprocess.harness.mjs` → 6/6. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(test): the `tool` import inside a fixture STRING, which no sweep reached `hook-state-store.test.ts:387` expected a throttled gate to stay quiet on a ten-minute-old fact and got `blocked: true`. The gate was not misbehaving — it could not load: const THROTTLED_GATE = `import { experimental_defineHook, tool, state, … }` `tool` was removed two commits ago, so the module threw on import and the runtime failed closed, which is correct behaviour for a gate that cannot run. Same in `hook-load-wedge.test.ts` and `core/hook-program.test.ts`. WHY THIS TOOK THREE ROUNDS TO FINISH, since that is the reusable part. The reference lived in four forms and a regex over source reaches one: real import in an example .mjs caught by the CI `harness` job re-export in a barrel caught by `docs-imports` import inside a template STRING caught by the CI `test` job code block in a doc caught by `docs-imports` That is verbatim the class already written down in this project's own notes after `.claude/pipeline/` was relocated — "four forms of a reference, of which a path search sees ONE" — including its conclusion that the only check which covers all four is one that RESOLVES the reference, not one that greps for it. I could have quoted the rule and still edited by regex and verified by a subset, three times running. Verified this time by the whole suite rather than the files I expected to break. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(test): a FIFTH spelling of the same import — built by concatenation `cli-coverage-record.test.ts` builds its fixture's import line with string concatenation: `import { experimental_defineHook, tool, deny, allow } from ` + JSON.stringify(HOOK_ENTRY) + … so no search for `from "…"` reaches it. Two tests failed because the fixture hook could not load and the runtime failed closed — correct behaviour, stale fixture. That is the fifth form this one removed symbol lived in. The running tally, because the tally is the finding: real import in an example .mjs caught by the CI `harness` job re-export in a barrel caught by `docs-imports` import inside a fixture template caught by the CI `test` job code block in a doc caught by `docs-imports` import assembled by concatenation caught by the full local suite Five spellings, four different gates, and every one of them found by a gate rather than by the sweep that created the problem. The lesson already written down in this project — that a reference search sees one form and only RESOLVING the reference sees all of them — held on every round. Verified: `npx vitest run src/cli-coverage-record.test.ts` 16/16. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: say why the emitted hook block has a matcher and no native `if:` Claude Code lets a hook action carry an `if:` precondition, checked before the hook process spawns. `vigiles compile` does not emit one, and the guide never said why — the first question a reader who knows Claude Code will ask, with no public home. That fails `document-the-why`. The rule the decision rests on: a prefilter may only ever be a proven SUPERSET of the typed predicate. Narrower and the process never starts, nothing is logged, and the guard reads as passing — the silent-guard bug this whole page exists to make unwritable. The safe superset is not a useful filter: `command.runs("git push", {force})` is AST-backed (compound, subshell, pipeline, absolute program head), and the narrowest string condition provably covering that is about `Bash(*git*)`. Same measurement as the "Matcher bypass" row (tools/measure-if-matcher-forms.mjs, 2.1.263). Two smaller reasons: `if:` is Claude Code only (Codex has no equivalent field, so emitting it would make one typed source mean different scopes per harness), and it would not buy the latency it appears to — same-event hooks run concurrently, so a filtered-out hook does not shorten the turn by its own duration. Per-event cost is the runtime's startup, which is where it belongs. Also cross-referenced from the "Runtime cost" limitation, which previously left `if:` looking like the obvious escape hatch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: `tool` is no longer in the hook vocabulary — the Status list still named it `tool("Bash")` was removed from `vigiles/hook` earlier today: a bash gate is Bash BY CONSTRUCTION, the matcher is emitted for the author, and every call site in both repos wrote the same literal. The removal swept the imports, the `match: tool("Bash")` lines and the vocabulary bullet — and missed this one. The Status/pending section lists the vocabulary as prose to explain why only the entry points carry the `experimental_` prefix. `tool` sat in that list, naming a symbol that no longer exists, in a section about a different subject. Measured limit this exposes: nothing catches it. self-command-refs resolves `vigiles <cmd>` invocations; doc-refs resolves marks inside fenced ts blocks. A vocabulary word named in PROSE is a form neither resolves, and a grep for the symbol also matches the CHECK `tool()` in docs/testing-api.md, which is a different, live function — so the sweep that would have found it also had to tell two same-named symbols apart. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: reading an `if:` and emitting one are different acts — say so The new "why no native `if:`" section explained the refusal to EMIT a condition and left a reader free to conclude vigiles ignores the field entirely. That inference is wrong in a way that costs trust in a different feature: the test tiers already honour a hook's own `if:` when measuring it (`decideHookCondition`, src/core/hook-condition.ts, on main since #211), precisely so a guard is scored as the harness would really run it rather than as an unconditional stand-in that flatters it. One paragraph, stated as the asymmetry it is: we read yours, we do not generate one for you, because a generated filter can be narrower than the program behind it and a hand-written one is the author's own declared intent. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: cut a paragraph that took five lines to carry one fact "None of this means vigiles ignores `if:`. Reading one and emitting one are different acts." — an aphorism standing in for a point, opening on a negation of an objection nobody raised, then five lines to say one thing. It broke this repo's own prose-clarity rule at the first sentence: lead with the point. Two lines now, the fact first: an `if:` you wrote is honoured, `runHook` reads it, only generating one is refused. Also dropped "a bad trade at any price" from the paragraph above — the preceding sentence already establishes that the failure is silent, so the flourish added emphasis to a point that was already made. Correction to9898a76, which this supersedes in content: that commit's message describes only my paragraph, but the commit also carried two edits another agent made to the same file (the 650→80 ms measurement and the rewritten Runtime cost bullet). `git commit <pathspec>` separates files, not authors; a shared file cannot be split that way. Left in history rather than rewritten — the content is right, and force-pushing a branch with live writers on it is the worse trade. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(skills): hold the contributor skills to the trigger-rate bar Of the 14 skills under .claude/skills/, 9 were model-invocable and only 2 (ship-a-feature, generate-logo) had a trigger-rate eval; 7 could auto-fire with no measurement. The first question per skill was not "write an eval" but "should this auto-fire at all" — a skill a human always reaches for by name costs nothing to disable and leaves the trigger surface entirely. Disabled (disable-model-invocation: true): - dogfood-cli — a deliberate multi-agent find-and-fix session a human starts on purpose; its own body says "NOT for a single known bug". - verify-docs-findable — a scheduled, cost-bearing docs audit with an argument-hint; already shaped as a command. Disabling it also dissolves its overlap with review-docs without an eval. - deep-research — both of its save targets (research/, the startup/ vault) no longer exist in this repo; the skill is stale here and its description invites competitive/market research this repo does not hold. (Despite the CLAUDE.md label, neither it nor review-docs is vendored: both were authored in-repo,39b729aand a0dddb7.) Kept model-invocable, each with a trigger eval on the ship-a-feature template (>=10 recall + >=10 precision prompts, stubSkillBodies, drawn from this repo's real work): - code-quality — "clean this up" never carries the skill's name. - landing-site — a design bar that must arrive BEFORE site/ is touched. - screenshot — a miss makes the model reach for the blocked `playwright install` or capture scroll-reveal sections blank. - review-docs — authored as auto-triggering ("review the readme"). Two genuine prompt-space overlaps are named in the eval headers and deliberately left out of every precision bank rather than picked around: code-quality vs ship-a-feature on "new public export", and landing-site vs screenshot on "screenshot the landing page". Those are measureSelectionMatrix questions over the whole .claude/skills/. The evals were authored, not run (keyless env; a real-model eval spends money). The thresholds are the template's defaults, uncalibrated. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(skills): deep-research routed strategy findings into a public repo Its "Where to save" section named two directories, and NEITHER exists — both were removed in #68. So the routing has not worked for some time, and the way it fails is the problem: - `research/<topic>.md` — gone. - "Sensitive: competitive / VC / strategy / fundraising → the encrypted `startup/` vault (see `startup/CLAUDE.md`)" — gone. Two defects, and the second is not cosmetic. The line DISCLOSES that a private strategy vault exists, in a public repository. And because the vault it names is deleted, an agent following the instruction today has nowhere to put competitive or fundraising material except this repo — the skill's own safety valve had become a funnel toward the exact content `no-product-strategy-here` forbids. Rewritten to say what is true now: technical findings go to a `docs/` page or a contributor note cited from keyFiles (the tier decided by public-vs-internal-docs and doc-tiers); strategy, market, pricing, GTM and roadmap research goes into no directory here at all, because the rule is unconditional and a deleted file survives in history and on other branches. Findings come back in the answer instead, for a human to place privately. Found while verifying a subagent's report rather than accepting it — the skill was in scope for a frontmatter change and this is a body defect it flagged and correctly declined to patch under its brief. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * perf(hook): a decision no longer loads the CLI to decide allow/deny A compiled hook runs on every matching tool call, and `dist/cli.js` is the bin — so `vigiles hook-runtime run-program` resolved ~85 top-level imports (compile, lint, audit, eval, init, the report template loader) before argv was parsed, to answer a question that touches none of them. CommonJS gives no way to defer that from inside the file; the entrypoint had to split. MEASURED, Node 22.22.2, median of 20 spawns, `tools/measure-hook-startup.mjs`, before =04f2c2a: layer before -> after bare `node -e ''` 42 -> 41 ms require dist/core/hook-program.js 170 -> 64 ms require dist/hook.js 171 -> 64 ms end-to-end run-program before -> after bash gate (safe-bash-guard.mjs) 661 -> 199 ms 3.3x file gate 628 -> 80 ms 7.9x inject 610 -> 83 ms 7.3x For scale: a shell hook doing the same job is ~12 ms and a python one ~35 ms. Roughly 40 ms of what remains is Node itself starting. Four lazy boundaries, each with its measurement at the call site: src/cli.ts reduced to a dispatcher shim with NO top-level imports; the verbs moved verbatim to src/cli-main.ts src/hook-runtime.ts the run-program runtime, lifted out of the verb barrel; the adapter registry (279 ms) is required only by react core/hook-program.ts @iarna/toml (56 ms) at its one serialize site hook-install.ts the same, and it is the edge that put toml back into every decision through hook-state-store's normalizeHookRef core/bash-effects.ts mvdan-sh (~100 ms) on first parse, not at module load The parser deferral is clean rather than forced: `decideProgram` returns allow() before building a commandView when the tool is not Bash, and every entry point in bash-effects begins by parsing — so no path reaches the parser without needing it. A bash gate still pays, and that is the work it asked for. THE EMITTED COMMAND IS BYTE-IDENTICAL, which outranks the win: `npx vigiles hook-runtime run-program <file>` is baked into every already-emitted settings block and covered by the SHA stamp beside each hook. Verified by compiling the same gate and inject with both trees and diffing the artifacts — `.claude/ settings.json`, `.codex/config.toml` and both stamp sidecars are identical. The invariant is asserted as a MODULE GRAPH, not a duration (#216 asks for this: a timing threshold on a shared runner is flaky and gets quarantined first). src/hook-runtime-graph.test.ts dumps require.cache from the real spawned CLI, so it sees the lazy requires a static scan would miss, and it asserts both directions — a bash gate DOES load mvdan-sh, `--help` DOES load the barrel. Proven to fire: hoisting each of the three imports back turns it red on its own assertion, and the tree is green again with them restored. Docs updated where the old claim was now wrong: the public runtime-cost bullet said "tens to hundreds of ms" and now states the measured per-role figures. Closes #216. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(config)!: rename the `testGlobs` rule option to `include` One config file, two words for "the set to consider". `orphans` took `include` (`options.include ?? DEFAULT_INCLUDE`, its own doc calling them "tsconfig-style glob arrays") while the `untested-*` rules took `testGlobs` for the same job with the same replace semantics. Both already had `exclude`. Now both read `include`/`exclude` and mean the same thing by them. Semantics are UNCHANGED — `include` replaces the defaults, as `orphans.include` does, as tsconfig and vitest do. No alias and no fallback: a stale `testGlobs` key is simply not read. WHAT THIS EXPOSED, which outlasts the rename: `.vigilesrc.json` is an UNGUARDED public surface. `testGlobs` ships in v26.0.0 through v26.1.1 and is documented with a copy-paste example, so a user can have it committed today — yet every one of the eighteen checks passes on this diff. `api-surface/*.api.md` guards TS exports and `TestCoverageOptions` is not one; nothing at all watches config keys. The property that makes a rename consequential is precisely the one no gate sees. Renamed across 14 files: the option in core/types.ts, its consumers (test-coverage, coverage-evidence, audit-score, cli-main), three test suites, and five docs plus HANDOFF.md. The eight `.claude/worktrees/agent-*/` copies are other sessions' gitignored trees and were deliberately not touched. Gates: format RC=0 (`prettier --check .`, clean) · targeted vitest RC=0 (test-coverage, cli-untested-options, cli-nudge-config — 80 tests) · `npm run check` RC=1 on `cli-lint` ONLY, whose 480 errors are 480-of-480 inside `.claude/worktrees/`, zero in tracked files — the same pre-existing condition recorded on this PR when it was 18 errors. `api-surface` passed (14.5s). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(lint): "A `include` entry" — the rename left bad grammar in a user-facing message The `testGlobs` → `include` rename produced "A `include` entry WITHOUT {surface}…" in the untested-surface advisory. It shipped to a place I could see it: the `vigiles lint` output posted as this PR's sticky comment. Two passes had already fixed the same a/an break in docs/rules/untested-skill.md, src/test-coverage.test.ts and src/coverage-evidence.ts — and both missed this one, because the string is assembled from template literals with ESCAPED backticks (A \`include\` entry). A grep for "A `include`" cannot match it. That form is on this repo's own list of reference spellings a search does not reach, alongside a path built by concatenation and an import inside a fixture string. Found by reading the tool's actual output rather than the source, which is the only view where the assembled sentence exists at all. Gates: prettier --check on the file RC=0 · vitest src/test-coverage.test.ts RC=0 (69 passed). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(harness): nudge when product code moves and no doc follows `doc-consistency` says: ship, rename or remove a capability and update its docs in the SAME change, across BOTH tiers — public `docs/` + README, and the contributor record in `CLAUDE.md`. That rule is prose, and this evening measured what prose is worth: · `tool()` was deleted from the hook vocabulary while docs/compiled-hooks.md kept listing it as vocabulary — through TWO sweeps of that same file. · An exclusivity claim outlived the measurement that withdrew it. · deep-research routed findings to a `startup/` vault deleted in #68. No check caught any of them. self-command-refs resolves `vigiles <cmd>`; doc-refs resolves marks in fenced ts blocks; orphan-docs finds unreferenced files. Prose describing a capability whose BEHAVIOUR changed is invisible to all three — nothing about it is broken, it is merely no longer true. WHY A HOOK, NOT A LINT RULE. `lint` reads a checkout; "the code changed and the docs did not" is a property of a DIFF. A tree-level rule would have to guess which prose belongs to which symbol, which is undecidable, and by lint-rule-calibration a heuristic can never gate. A hook sees edits accumulate across a session, which is the only place the fact exists. WHY NOT ship-a-feature. That skill covers this for a NEW export, with executable DOCUMENTED/FINDABLE checks. Its own trigger eval asserts it stays QUIET on "Rename the internal helper posixly to toPosix" and "Tighten the wording in docs/compiled-hooks.md" — firing there is a false positive against maxFalsePositive: 0.2. Widening it would break its own precision assertion, so this covers what that skill is measured NOT to. TWO FACTS, NOT ONE, and the test asserts them apart. `docs.followed` is recorded on any doc edit, so a session already maintaining its docs stays silent; that silence is SUCCESS. `docs.nudged` is the rate limit; that silence is a CAP. One fact could not tell them apart, and the hook would then go quiet for two hours after a single doc edit. Tests are excluded from the trigger deliberately: a test states what the code already does, so a test-only edit changes no documented behaviour. Including them would make it fire through ordinary red-green work, which is how a nudge gets muted. Gates: vitest src/docs-drift-nudge.test.ts + src/test-tier-nudge.test.ts RC=0 (34 passed) · prettier --check . RC=0 · `vigiles compile` wired it into .claude/settings.json and wrote its SHA stamp. MUTATION, patch proven landed before the run: deleting the `docs.followed` branch (collapsing the two silences) fails exactly one test — "QUIET because docs are being edited (success)" — and restoring it returns 11/11. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(coverage): credit the tests this repo already had — 25 untested surfaces to 14 vigiles ships `include` with a `{surface}` placeholder for exactly the case where a test lives somewhere other than beside its surface, and this repo had never configured it. So its own audit called eleven tested surfaces untested, including four trigger evals written today and both compiled hooks. MEASURED, each step run rather than reasoned: 25 baseline 16 `examples/harness/dogfood/{surface}.trigger.eval.mjs` on untested-skill — credits fable's four new evals plus generate-logo, strengthen, test-harness, edit-spec, debug-my-harness 25 adding a SECOND, narrower list to untested-hook — the count went BACK UP 16 one identical list on both rules 15 renaming src/docs-drift-nudge.test.ts → .hook.test.ts 14 the same for test-tier-nudge TWO THINGS THAT SURPRISED ME, both worth knowing before touching this config: 1. THE OPTIONS ARE SHARED ACROSS THE `untested-*` RULES. Setting `include` on untested-hook REPLACED what untested-skill had, and nine credited surfaces silently went back to untested. docs/rules/untested-subagent.md does say the options are shared; the failure mode it produces — a second config UNDOING the first, with the count moving in the alarming direction — is not obvious from that sentence. The lists are identical on both rules deliberately. 2. A HOOK'S SURFACE NAME CARRIES `.hook`. `{surface}` for `.vigiles/hooks/docs-drift-nudge.hook.mjs` is `docs-drift-nudge.hook`, not `docs-drift-nudge` — so `src/docs-drift-nudge.test.ts` did not bind and `src/docs-drift-nudge.hook.test.ts` does. Established by renaming and watching the count, not inferred from the suggestion string. The first two globs restate DEFAULT_TEST_GLOBS on purpose: `include` REPLACES the defaults rather than extending them, so omitting them would strip credit from every `*.harness.*` and `*.eval.*` in the repo while the number looked better. The 14 that remain are honest: five shell hooks under `hooks/` and nine skills with no test of any kind. Gates: vitest both renamed suites RC=0 (34 passed) · prettier --check . RC=0 · `node dist/cli.js lint` re-run after every step above. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix: two committed artifacts drifted from the files they index CI went red twice, both mine, both from the same shape — an artifact that is GENERATED but COMMITTED, so adding or renaming a source file silently invalidates it until it is regenerated in the same change. 1. `generated-types:committed` oned9eaf1. `.vigiles/generated.d.ts` enumerates every project file; `src/docs-drift-nudge.hook.test.ts` was not in it. The gate is `git diff --exit-code .vigiles/generated.d.ts`, so the artifact must be regenerated AND committed — regenerating alone leaves it red. 2. The SPEC REFERENCE check on6ce464a: ✗ CLAUDE.md: File not found: "src/test-tier-nudge.test.ts" Renaming that test to `.hook.test.ts` (so its `{surface}` name binds) left a `file()` keyFile in CLAUDE.md.spec.ts pointing at a path that no longer exists. This one is worth naming plainly: it is the cross-referencing engine — the thing this product IS — catching its own author's stale reference, minutes after the rename, exactly as designed. Also indexes what the rename left undocumented: `.vigiles/hooks/docs-drift-nudge.hook.mjs` and its test now have keyFiles, and the tier-nudge entry says WHY the file is named `<surface>.hook.test.ts` — a hook's `{surface}` name carries `.hook`, which is what binds it under the `include` globs in .vigilesrc.json. Without that sentence the next rename repeats this. HOW BOTH GOT THROUGH, since the cause is procedural rather than technical: after adding the hook I ran targeted vitest and prettier instead of `npm run check`, and the re-run after that was taken from a tree I was still editing — a gate on a moving tree measures a state that never existed. Both are the `run-the-gates` rule, failed in two different ways within twenty minutes. Gates on a settled tree: build · types:root · types:test · types:site · jest · api-surface · prettier — all RC=0. `cli-lint` red with every finding inside `.claude/worktrees/` (gitignored, CI never sees it). `generated-types:committed` red only because the regenerated artifact was uncommitted at the time — this commit is what makes it green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(hook): reject a tool matcher that names no real tool `compileHookProgram` cross-references the `on:` event against the harness catalog, so a typo'd EVENT fails the build. It did not do the same for the tool matcher, and the existing check there validates REGEX SYNTAX only — so `tools("Edt")` parses fine, compiles, wires a matcher `Edt`, and the hook never fires. Same defect the event check exists to kill, on the axis it did not cover. WHY THIS IS NOT A UNION TYPE, which is the obvious answer and the wrong one: a tool matcher IS a regex — that is why `tools("Edit|Write")` works, and `tools("mcp__github__.*")` is documented-correct. A literal union would reject both. So the check reads only entries with NO regex metacharacter as literal NAMES, which is exactly the spelling a typo produces. A fully-spelled MCP tool is skipped inside verifyToolContract itself (dialect.mcpToolPattern), so it passes on both counts. Reuses verifyToolContract + authoringIssues — the same detector the subagent tool-contract rule runs, so the hook matcher and the subagent contract cannot drift into two vocabularies (one-detector-no-drift). Both directions tested, and MUTATION-PROVEN with the patch grepped as landed: disabling the throw fails exactly one test ("a typo'd tool NAME in match does NOT compile"); restoring returns 98/98. The second test pins what must KEEP compiling — a real name beside `mcp__github__.*` and a spelled-out MCP tool. 🔴 AND THE GATE CAUGHT A REGRESSION THE TESTS COULD NOT. `api-surface` failed with one line — `// @public` → `// @public (undocumented)`. Inserting the REGEX_META const put it BETWEEN `invalidToolPatterns`'s JSDoc and its declaration, so the comment documented my constant and the real function went bare. That is verbatim the failure `ship-a-feature` was written after ("inserted between verifyGuardrail's JSDoc and its declaration; the diff said so, nobody read it"). Fixed by moving the comment back, NOT by regenerating — `api:report` would have committed the degraded surface and called it green. api:check now passes with the surface UNCHANGED, which is the correct outcome for adding an internal const. Gates: build RC=0 · tsc --noEmit RC=0 · api:check RC=0 (surface unchanged) · vitest hook-program 98 passed · prettier RC=0 · `npm run check` red only on `cli-lint`, entirely inside `.claude/worktrees/`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(site): the landing page showed a hook that no longer compiles The Guard section's headline sample — the first compiled hook a visitor ever sees — opened with a symbol deleted from the vocabulary earlier today: import { experimental_defineHook, tool, deny, allow } from "vigiles/hook"; export default experimental_defineHook({ on: "PreToolUse", match: tool("Bash"), `tool()` is gone. A bash gate is Bash BY CONSTRUCTION — `BashToolEvent.tool` is the literal "Bash", the matcher is emitted for the author, and the field existed only to be got wrong (`match: tool("Edit")` type-checked, compiled, wired an Edit matcher, and never fired). Removing it is the fix; the site kept advertising it. So a reader copying the landing page's own example got a build error on line 1, and the file's header claims the snippet is REAL — "node dist/cli.js hook-runtime run-program <this file> # via verifyGuardrail" — which makes it a claim about executed code rather than an illustration. 🔴 WHAT THIS SAYS ABOUT THE HOOK SHIPPED TWO HOURS AGO. `docs-drift-nudge` exists to catch exactly this: product code changed, the prose describing it did not. It would NOT have fired here. It watches `src/**` for the trigger and treats `docs/**`, README and CLAUDE.md.spec.ts as the docs — a `.tsx` under `site/` is neither, so the site is invisible to it in both directions. The landing page is a front door under `cohesive-feature-delivery`, and the nudge does not cover it. Recorded here rather than widened in the same commit: the trigger set is a calibration question (a `site/` edit is often styling, not a claim), and widening a nudge on a hunch is how a nudge gets muted. Gates: prettier --check RC=0 · `npm --prefix site run test:browser` RC=0 — 7 files, 49 tests. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>