mirror of https://github.com/zernie/vigiles.git synced 2026-09-14 20:53:57 +08:00

Files

T

zernie 900dc7e06a refactor(spec)!: name things for what they are; retire the vigiles/experimental subpath (#169 )

Three exported symbols were named for something other than what they are, and
two mechanisms were doing one job.

RENAMES (old names kept one major, @deprecated, removed one major AFTER this one):
  claude()          → instructionFile()     compiles CLAUDE.md AND AGENTS.md, so a
                                            name from one harness was never right
  instructions``    → prose``               builds a prose FRAGMENT; the plural read
                                            as "the instruction file", which is what
                                            instructionFile() builds
  agent()           → experimental_agent()  the shape is not settled, and the tag was
                                            never there (git log -S empty)
  SkillSpec.result: → postcondition:        `result` already meant the subagent output
                                            contract one screen down; the doc comment
                                            had to spend a line disambiguating them

The alias window is not politeness. Measured: the previous rename shipped with
ZERO overlap (18.1.1 old names only, 19.0.0 new only). A container rollback put
the old node_modules under new sources, PreToolUse stopped loading, and a
PreToolUse that does not load denies EVERY Bash command — including the one that
fixes it. One window per major makes that pair unrepresentable.

SUBPATH RETIRED. vigiles/experimental is gone; its members moved to the door
their feature already uses. Of two mechanisms for one promise the subpath was the
weaker: it marks the import line, out of view by the time anyone reads the call.
Measured on the only user-facing example — with the prefix aliased away at
import, the marker survived at 0 of 5 call sites. So the prefix stays, the advice
to alias it away became an explicit prohibition, and the six define* entry points
are DECLARED prefixed rather than gaining it at re-export.

That de-aliasing is what unblocked moving the naming check into ESLint, and the
ORDER was load-bearing: measured before it, dropping the public/internal
exemption produced 14 findings, all from the re-export indirection. Measured
after, across all of src/ with no exemption: 22 tagged declarations, 0
unprefixed. The rule turns on silent.

EXPORT CLEANUP. vigiles/linting export * → curated, 103 → 79 symbols; its header
claimed to be curated with an `export *` one line below, and claimed the builders
were also at the package root (191 exports there, zero matches). ClaudeTool and
HookEvent deleted — zero references, and both had drifted off the dialect they
claimed to mirror; HookEvent listed 5 events, two of which do not exist, against
the 31 the vendor documents.

DOCS. experimental.md deleted and distributed per feature: the skill half into
skills.md §Status, the hook half into a new compiled-hooks.md §Status, and the
emit half — 111 of its 177 lines, a topic doc wearing a stability page's clothes
— into docs/emit-channel.md, which gains the "which channel when" comparison it
never had. The one cross-cutting sentence went to the README.

TWO GATES WERE GREEN AND WRONG, both found by this work:
  - api:check reported "verified for 11 entries — no drift" while reading
    dist/experimental.d.ts from a PREVIOUS build (tsc does not clean dist/) for a
    source file that no longer existed. Now asserted against package.json
    exports, with a mutation proving exit 1 on a phantom entry.
  - check-export-prefixes caught MY error: the R3 services first landed on
    vigiles/eval, where `paid_` means "this call can bill you" — and
    startServices takes a ContainerRuntime and calls no model. Naming it
    paid_experimental_startServices would have redefined paid_ as "expensive in
    some sense". They went to the package root.

SEVENTEEN review findings landed on this branch, all real. Two mechanical
closures came out of them: src/example-imports.test.ts resolves every relative
import under examples/ instead of matching a string, and the naming rule now
ENUMERATES the three export paths it visits rather than describing its coverage
in the abstract. One attempt is recorded as REFUTED: teaching the doc gate to
flag our own exports as free variables measured 66 findings across 93 blocks, so
that gate's original scoping was right.

BREAKING CHANGE: vigiles/experimental is removed. Its exports are unchanged in
name and behaviour and are now reached from `vigiles` (the emit channel, the R3
disposable-service tier). Every renamed symbol keeps a working @deprecated alias
for this major.

2026-08-21 07:54:51 +05:00

7.3 KiB

Raw Permalink Blame History

Documentation — index

How-to and reference docs for using vigiles. New here? Start with the README for the pitch and a 5-minute quick start, or try the live demo at vigiles.sh — grade any repo in your browser.

The docs are grouped by what you're trying to do:

Guides — step-by-step, task-first ("help me do X").
Reference — exact flags, symbols, rules.
Explanation — the reasoning and trade-offs.

Guides — "help me do X"

Verify your instruction files (the Lint layer)

verifying-instruction-files.md — the master guide: the markdown → typed-spec ladder, the three rule types (enforce / guidance / guard), verified references, and the before/after tables. Holds the full validation-rules matrix.
markdown-mode.md — the no-spec on-ramp: verify rules in plain markdown with inline  comments, no TypeScript.
skills-monorepo.md — adopt vigiles in a CI-tested skill library or a plain .claude/ repo (no plugin.json).

Test & measure your harness (the Test + Eval layers)

harness-testing.md — task-first how-to: pick what you want to test (hook / wiring / skill firing / behaviour) and the tier that answers it, with a copy-paste first test and CI.
- harness-testing-claude-code.md — Claude Code specifics: scriptModel, ${CLAUDE_PLUGIN_ROOT} / pluginDir / the Skill tool, the bubblewrap sandbox.
- harness-testing-codex.md — Codex specifics: runHarnessTest({ adapter: codexAdapter }) against real codex exec, the Responses mock, what maps and what doesn't.
measuring-skills.md — A/B a skill, plugin, model, or rule change on real coding tasks: the metric triple (bill / target / blast-radius), the worked example, and why it's affordable on your subscription.
migrating-from-promptfoo.md — move existing skill evals onto the subscription: the concept + assertion mapping, a worked side-by-side, and the honest gaps.

Author & ship

skills.md — authoring a SKILL.md across the three on-ramps; the prose-vs-gates split.
compiled-hooks.md — author a hook as a pure typed function against the closed vigiles/hook vocabulary and compile it, making whole classes of hook bugs unrepresentable (false confidence, matcher bypass, capability creep).
railway-subagents.md — the typed Result subagent contract: declare a typed outcome, compose flat workers, and assert the outcome deterministically (no model judge).
for-plugin-authors.md — the plugin-author journey end to end: scan a draft, fix what it flags, make your skills fire, rank against a marketplace, gate it in CI.
github-action.md — run vigiles in CI: the composite Action, every input, the sticky PR comment, versioning.

Harnesses, adapters & agents

harnesses.md — which harness vigiles targets and how you pick one (by import), plus the capability matrix.
authoring-an-adapter.md — teach vigiles a new harness: the five ports, a worked skeleton, validating with the conformance kit.
non-js-harnesses.md — running vigiles on a harness whose project is Kotlin, Go or anything else non-JS: what needs Node and what does not.
agent-setup.md — agent setup & workflows in one guide: what init does, per-agent recipes (Claude Code / Codex / multi-agent / Cursor), non-interactive setup + fallback hooks, and CI.

Reference — "the exact flag, symbol, or rule"

cli.md — the full CLI: every verb and flag, the Claude Code plugin, lint vs audit.
commands-and-how-they-relate.md — the mental model: how audit / lint / test / eval / init fit together, and why measuring "do my skills fire?" uses init, not audit.
testing-matrix.md — every use case of the harness-testing API mapped to the tier that tests it, and what each tier costs.
testing-api.md — the full harness-testing API: every predicate, assertion, check, matcher, and option (measureTriggerRate / runEval / significance).
spec-format.md — the typed .spec.ts format (target, sections, rules, verified references) — the source of truth.
linter-support.md — the 11 linters + generate-types / generate-schema.
adapter-api.md — the adapter API reference: every port field, the conformance functions, the registry API.
Validation rules: the full matrix lives in the linting guide; each rule has a doc under rules/.
Library entry points (grouped by concern so a future harness can sit beside the current one):
- vigiles/linting — the compiler + reference verification (compileClaude, compileSkill, …).
- vigiles/spec — the spec builders (claude, enforce, guidance, file, cmd, symbol, …) and the module-augmentation target for generated types.
- vigiles (the package root) — the free testing surface: the harness/hook runners, the check vocabulary and the runner-agnostic assertions.
- vigiles/eval — everything that can spend money, every symbol prefixed paid_: paid_runEval, paid_measure, paid_measureArms, paid_measureTriggerRate, paid_judge, paid_judged, paid_claudeEvalDriver.
- defineEval is on the free root, not here, and that is the point: a *.eval.mjs file DESCRIBES its eval and vigiles eval runs it, so importing one cannot spend. See eval files describe their eval.
- vigiles/claude-code, vigiles/codex — the per-harness adapters.
- vigiles/adapter — the adapter-authoring kit.
API reference (generated) → — every exported symbol across all entry points, generated from the source. The hand-written guides here are the human-facing layer; this is the exhaustive symbol-level reference.

Explanation — "why it's built this way"

what-vigiles-catches.md — the taxonomy of problems vigiles handles: the prevented / caught / measured model, biggest-problem-first.
comparison.md — before/after tables, the determinism breakdown, the flow diagram, and what vigiles composes with rather than replaces.
sandboxing.md — what the sandbox isolates vs records (honestly): IO / rm -rf, the three network modes, tiers and limits.
emit-channel.md — experimental_emitTool: a skill returns a typed result by calling a tool instead of ending its turn, which is how an INLINE skill can carry an output contract at all. Includes the measurements, and when to prefer the stable output: instead.
faq.md — the front-door FAQ across all four layers.

7.3 KiB Raw Permalink Blame History