blindspot

blindspot

blindspot is a vendor-neutral guardrail kit for agentic software work. It combines reasoning skills, deterministic Git checks, a correction pipeline, bounded coverage metadata, and behavioral evaluation.

It does not claim to cover every blindspot. Coverage is explicitly limited to the named taxonomy, versioned lesson dataset, current rule set, and behavioral scenarios. Unknown lesson patterns remain visible in _unclassified.

Coverage model

The authoritative map is coverage/matrix.v1.json. It records the gate type, engine rules, lesson selectors, behavioral-eval categories, and known gaps for eleven classes:

Some semantic classes cannot be enforced reliably from a diff alone. Their matrix entries say so; prose and behavioral gates are not represented as deterministic proof.

Lesson corpus and feedback loop

data/lessons/v1/ contains:

• dataset.jsonl: 169 normalized, stable-ID lesson records derived from the DivAI experience corpus;
• manifest.json: taxonomy version, dataset version, class counts, checksum, provenance reference, and bounded claim;
• _unclassified.json: the review queue, currently one unmatched entry plus fifteen low-confidence classifications.

The raw lessons.md source is not copied into this repository. Its provenance is recorded as divai/tasks/lessons.md.

Audit or build a new immutable version:

node bin/blindspot.mjs lessons-audit /path/to/lessons.md \
  --project project-name --version proposed-v2

node bin/blindspot.mjs lessons-build /path/to/lessons.md \
  --out data/lessons/v2 --project project-name --version universal-lessons-v2 \
  --source-ref project/tasks/lessons.md

The local hook writes observations to .blindspot/learn/observations.jsonl. Observations are telemetry, not evidence that a change was correct. A pattern becomes eligible for review only after it is linked to a confirmed correction:

node bin/blindspot.mjs link-correction <commit-hash> <lesson-id>
node bin/blindspot.mjs review-learned --min 3

Promotion still requires review, an invariant, positive and false-positive tests, a coverage-matrix update, and the strongest feasible enforcement layer.

Deterministic engine

The Node engine reads staged changes or a commit range and emits evidence-linked findings. Current rules include:

• applied migration modification;
• secret files and credential-like literals;
• dependency changes without the corresponding scoped lockfile;
• unpinned container images and build/native-config changes;
• untrusted GitHub event data interpolated into shell and mutable workflow actions;
• removed authorization or validation guards;
• process-local state used for durable retry coordination;
• retried mutations without stable operation identity;
• stale revisions that fail open;
• structured database values stringified without schema evidence;
• completion claims without an evidence boundary;
• canonical-value changes, shared auth surfaces, failure conflation, generic failure collapse, and skill changes without lesson artifacts.

Rules are signals. A clean result means only that no configured rule matched.

node bin/blindspot.mjs check
node bin/blindspot.mjs check --strict
node bin/blindspot.mjs check-range <base-sha> <head-sha> --strict --fail-on=medium
node bin/blindspot.mjs review change.diff
node bin/blindspot.mjs list

Behavioral evaluation

eval/scenarios.v1.jsonl contains 44 scenarios: trigger, compliance, pressure, and false-positive coverage for every class. The grader accepts normalized output from any agentic tool:

node bin/blindspot.mjs eval-prompts > prompts.jsonl
# Run prompts through the tool under evaluation and produce responses.jsonl.
node bin/blindspot.mjs eval --responses responses.jsonl

The response shape and reproducibility requirements are documented in eval/README.md. Repository validation checks the harness and scenario coverage; it does not claim that any model or agent has passed.

Installation

Requires Node 18 or newer and Git.

# POSIX
./install.sh --target /path/to/repo --tool agents --strict

# PowerShell
.\install.ps1 -Target C:\path\to\repo -Tool agents -Strict

Configured skill destinations include .agents, Claude, OpenCode, Codex, Kiro, Cursor, and Windsurf directories. This list is a convenience, not a claim about native discovery support. For any other tool, provide its documented directory:

./install.sh --target /path/to/repo --skills-dir .my-agent/skills

The installer:

1. copies eleven skills;
2. copies the CLI, rules, matrix, normalized dataset, and eval scenarios into <repo>/.blindspot;
3. preserves and chains existing pre-commit, prepare-commit-msg, and post-commit hooks;
4. in strict mode, fails commits when high rules fire or enforcement is missing.

Local hooks can be bypassed, so they are feedback—not a trusted server boundary.

Optional server-side enforcement

If you want protected-branch or required-status enforcement, run the bundled range script in whatever CI system your Git host already uses:

BLINDSPOT_BASE_SHA=<base> bash .blindspot/ci/check-range.sh

A GitLab example is in ci/gitlab-ci.yml. The same script can be wired into any other server-side runner or protected-branch policy.

Validation

npm test
npm run integration          # PowerShell/Windows path
npm run integration:posix    # Bash/POSIX path
npm pack --dry-run

npm test verifies rule behavior, lesson parsing, dataset checksum, _unclassified consistency, coverage mapping, and behavioral scenario structure. Integration tests exercise the actual installer, hook chaining, strict blocking, post-commit linkage, range enforcement, and fail-closed availability.

Known limits

• Static diff rules cannot prove absent work, runtime behavior, architecture, production topology, or user intent.
• Regex rules can still produce false positives or miss semantically equivalent code; every rule needs maintained positive and negative tests.
• The DivAI-derived dataset is one seed corpus, not a representative sample of every language, organization, agent, or deployment model.
• Behavioral results depend on the exact model, tool, prompt wrapper, permissions, and configuration and must be reported with those versions.
• Server enforcement depends on repository policy controlled outside this repo.
• _unclassified is expected to grow as new experience is ingested.

License

MIT. See LICENSE.