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

Files

T

zernie d6b1ad06aa fix!: exclude reaches every pass, and the guard stops missing re-spelled commands (#194 )

`.vigilesrc.json#exclude` was honoured by 3 of 11 discovery walks, and the walks
that did honour it disagreed on the dialect: glob's string `ignore` treated bare
`bench` and `bench/` as matching nothing, while the minimatch helper accepted
them. One `ExcludeSet` is now parsed where `loadConfig()` runs and taken as a
REQUIRED parameter by every in-scope walk in cli.ts — the shape that let
`findSpecs` go a year without it was optional-with-default, which compiles
silently. Closes #192.

The disaster battery now generates its own inputs: `experimental_alternateSpellings`
(renamed from `equivalentDisasters`) re-spells hook test cases so the shell
executes them identically — nine families, 7 seeds to 136 spellings. Five of
those came from a normalizer fix: `g\it push --force` runs git but was not
matched by `runs("git push")`.

That fix then had to be scoped, because CI caught the regression it caused:
escapes are resolved for the HEAD and FLAG-shaped operands (what the command IS)
and never for a path operand (where it WRITES) — the same bytes are a resolved
escape to `sh` and a real Windows UNC path on Windows, and fail-closed keeps the
path. Both directions pinned by mutation.

Also: `spec-refs` and `duplicate-rules` had a meta and a doc but no row in the
canonical rules matrix, and nothing compared either against it. A test now
asserts every rule has a matrix ROW (matched on the table row, not a prose
mention).

BREAKING CHANGE: `findSpecs` changed signature; `orphans` gained a `repoExclude`
option; `equivalentDisasters` was renamed to `experimental_alternateSpellings`
and now takes a required argument. Any repo with an `exclude` key sees it applied
to every pass, so an excluded spec is no longer compiled and an excluded
harness/eval script is no longer discovered.

2026-09-03 15:56:41 +05:00

7.5 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 / safety-hook battery / 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.
experimental.md — what an experimental_ name promises (nothing), what is experimental today, and what has to be true before the prefix comes off.
faq.md — the front-door FAQ across all four layers.

7.5 KiB Raw Permalink Blame History