intent-verify

imageCI imagePyPI imageLicense: MIT

When a written acceptance list may have drifted from a changed repository, intent-verify provides a fast, deterministic lexical coverage signal before human review. Give it the Markdown spec you maintain—an INTENT.md, SPEC.md, requirements list, or handoff document—and it reports whether the selected repository evidence visibly uses the same terms.

Use check for a repository-wide signal, or map when you need each acceptance item tied to explicit source and test roots. A gap can stop a claim that scope is covered. A covered result sends work to review; it never authorizes acceptance, merge, release, or publication.

INTENT.md is an input-file example, not an integration point. Claude Code's project-instruction documentation describes CLAUDE.md and AGENTS.md; this tool does not load either automatically and only reads the file passed to --spec. See Anthropic's project memory documentation for how Claude Code handles those instruction files.

How it works

intent-verify is intentionally simple and fully deterministic — no model, no network:

1. Parse acceptance items from the spec (inline Accepts:/Requirements:/Scope: lines and bullet/numbered lists under matching headings).
2. Tokenize each item, dropping common stop words.
3. For each item, compute the fraction of its tokens that appear as substrings in the selected evidence files (the spec file itself is excluded).
4. Score each item against two thresholds and roll up to a single verdict.

Coverage is a lexical token-overlap signal, not a semantic judgment.

Orchestration coverage map

Name implementation evidence explicitly. This prevents a matching README elsewhere in the repository from satisfying the map:

intent-verify map \
  --spec INTENT.md \
  --repo . \
  --evidence-path src \
  --evidence-path tests

The command emits only JSON using the versioned intent-verify.coverage-map.v1 contract. Each item includes the files that contributed matching terms. The top-level acceptance_authority is always false; decision is review for covered scope and inspect for partial or gap results.

GitHub Action

The root composite Action applies the same contract. A workflow can target the planned versioned v0.2.1 release:

- name: Map intent to changed implementation surfaces
  uses: hermes-labs-ai/intent-verify@v0.2.1
  with:
    spec: INTENT.md
    repo: .
    evidence-paths: |
      src
      tests
    summary: true # optional; defaults to false

After the v0.2.1 tag is published, resolve it to its commit SHA when your supply-chain policy requires a full commit pin.

Upload the path returned by the Action's receipt output when the JSON should remain as a build artifact.

Set summary: true to add a bounded, escaped advisory coverage table to the GitHub Actions job summary. It includes the caller's spec path and acceptance item labels, so leave it off when those labels are sensitive. The summary does not grant acceptance authority: it reports lexical evidence only; review, tests, and human judgment still decide correctness and merge readiness. The summary-written output reports whether the requested summary was rendered.

The repository retains .zenodo.json as passive metadata. Its listed DOI is a reference to the associated paper, not a software identity; Zenodo archiving is not a release prerequisite or a promised release side effect.

Agent plugin (Claude Code, Codex CLI, Gemini CLI)

The repository root is one portable Agent Plugin (plugin.json, Agent Plugins 1.0.0) with a single skill, skills/intent-verify/SKILL.md. Each host installs that same skill with its own native command; none of them gets a separate copy.

What each host reads:

• Claude Code reads .claude-plugin/marketplace.json (its entry is ., the root) and .claude-plugin/plugin.json.
• Codex reads the repo marketplace .agents/plugins/marketplace.json (its entry is ./, the root) and the portable plugin.json.
• Gemini CLI reads gemini-extension.json and discovers the skill under skills/. Keep --ref v0.2.1 so installation resolves the reviewed semantic release rather than a mutable branch.

The skill uses an installed intent-verify CLI, or the pinned uvx intent-verify==0.2.1 with your agreement.

In Claude Code the plugin also adds two on-demand commands. Use /intent-verify:check --spec INTENT.md --repo . for a normal coverage check, or /intent-verify:map --spec INTENT.md --repo . --evidence-path src to emit a provenance map for explicit implementation roots. Both commands use the local intent-verify CLI and run only when you invoke them. Their results remain advisory lexical evidence: covered and verified do not authorize acceptance, merge, release, or publication.

Install

pip install intent-verify

Or install the CLI from the Hermes Labs Homebrew tap:

brew install hermes-labs-ai/tap/intent-verify

For local development:

pip install -e ".[dev]"

60-second quickstart

Given a spec like:

# Intent

## Accepts
- uploads PDF invoices
- retries provider timeout

run:

intent-verify check --spec INTENT.md --repo .

You get a per-item breakdown and a single verdict:

intent-verify: INTENT.md vs . (12 files)
  [OK   100%] uploads PDF invoices
  [PART  50%] retries provider timeout
  [LOW   20%] writes audit log for rejected invoices
intent-verify: MISSING — 1/3 items below 30% (avg 57%)

(The file count, percentages, and items above are illustrative — your numbers depend on your spec and repo.)

The exit code mirrors the verdict, so it drops straight into CI or a pre-commit hook:

imageintent-verify preview

Usage

intent-verify check --spec INTENT.md --repo .
intent-verify check --spec SPEC.md --repo . --json
intent-verify check --spec docs/handoff.md --repo src --min-verified 0.75 --min-item 0.35

Flags:

• --spec — path to the markdown spec, intent, or handoff file (required).
• --repo — path to the repo or source tree to scan (required).
• --section — target a specific markdown heading, for example Requirements.
• --json — emit machine-readable JSON instead of text.
• --min-verified — coverage an item must clear to count as verified (default 0.7).
• --min-item — minimum per-item coverage before an item is treated as missing (default 0.3).

What it parses

By default it extracts items from:

• inline lines such as Accepts: upload PDF invoices, retry on timeout
• markdown sections such as ## Accepts with bullet or numbered items (Accepts, Requirements, Scope headings, or a custom one via --section)

JSON output

intent-verify check --spec INTENT.md --repo . --json

The JSON object includes spec_path, repo_path, files_scanned, average_coverage, verdict, the thresholds used, and an items[] array with each item's parsed text, tokens, coverage, verdict, and contributing evidence paths. Legacy check output remains compatible and now includes the explicit non-authority metadata.

Limitations / what it does NOT do

• Not runtime agent intent verification. It does not authorize or monitor AI-agent actions, MCP/tool calls, or permissions; it checks static repository source against a markdown spec.
• Lexical, not semantic. It matches tokens as substrings; it does not understand meaning, control flow, or behavior.
• It can over-credit. A token appearing anywhere in any scanned file counts, even if it is in a comment, a string, or an unrelated context.
• It can under-credit. A correct implementation written with different vocabulary than the spec will score low.
• It is not proof of correctness and does not replace tests or code review. It answers "does the implementation visibly cover the stated scope?" — not "is the software correct?"
• It needs a human-readable spec. With no INTENT.md/SPEC.md/requirements/handoff file there is nothing to check against.
• Source-file scope only. It scans a fixed set of source extensions (Python, JS/TS, Go, Rust, shell, config, markdown, etc.) and skips common build/vendor directories.
• Evidence paths are not behavioral proof. map prevents unrelated paths from contributing, but comments, docstrings, and dead code inside selected paths can still match. Tests and review remain authoritative.

Development

ruff check .
python3 -m pytest -q
python3 -m py_compile src/intent_verify/*.py

Repository layout

src/intent_verify/
tests/
examples/
skills/intent-verify/SKILL.md   canonical agent skill
commands/                       Claude Code slash commands
plugin.json                     portable Agent Plugins 1.0.0 manifest
.claude-plugin/                 Claude Code plugin + marketplace
.agents/plugins/marketplace.json Codex CLI marketplace
gemini-extension.json           Gemini CLI extension

Part of the Hermes Labs reliability stack. Complementary siblings, not duplicates: rule-audit analyzes logical contradictions in system prompts, and lintlang lints agent-config structure — intent-verify instead checks spec-vs-code drift.

About Hermes Labs

Hermes Labs is an AI reliability engineering studio for product and engineering teams shipping production agents and LLM applications. We find the structural AI failures standard evals miss, then harden retrieval, memory, agents, and the language layers around production AI systems with runtime controls and defensible evidence.

Browse the open-source catalog or contact roli@hermes-labs.ai.