{
  "markdown": "<div align=\"center\">\n\n<h1>intent-verify</h1>\n\nintent-verify deterministically checks whether a repository still lexically covers the acceptance items in a Markdown spec before human review.\n\nintent-verify is developed by [Hermes Labs](https://hermes-labs.ai).\n\nHermes Labs is an agentic infrastructure company building the reliability layer for autonomous systems.\n\n[![CI](https://github.com/hermes-labs-ai/intent-verify/actions/workflows/ci.yml/badge.svg)](https://github.com/hermes-labs-ai/intent-verify/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/intent-verify.svg)](https://pypi.org/project/intent-verify/)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-yellow.svg)](LICENSE)\n\n</div>\n\nGive it an `INTENT.md`, `SPEC.md`, requirements list, or handoff document, and it reports whether the selected repository evidence visibly uses the same terms.\n\nUse `check` for a repository-wide signal, or `map` when you need each\nacceptance item tied to explicit source and test roots. A gap can stop a claim\nthat scope is covered. A covered result sends work to review; it never\nauthorizes acceptance, merge, release, or publication.\n\n`INTENT.md` is an input-file example, not an integration point. Claude Code's\nproject-instruction documentation describes `CLAUDE.md` and `AGENTS.md`; this\ntool does not load either automatically and only reads the file passed to\n`--spec`. See Anthropic's [project memory documentation](https://code.claude.com/docs/en/memory)\nfor how Claude Code handles those instruction files.\n\n## How it works\n\nintent-verify is intentionally simple and fully deterministic — no model, no network:\n\n1. Parse acceptance items from the spec (inline `Accepts:`/`Requirements:`/`Scope:` lines and bullet/numbered lists under matching headings).\n2. Tokenize each item, dropping common stop words.\n3. For each item, compute the fraction of its tokens that appear as substrings in the selected evidence files (the spec file itself is excluded).\n4. Score each item against two thresholds and roll up to a single verdict.\n\nCoverage is a lexical token-overlap signal, not a semantic judgment.\n\n## Orchestration coverage map\n\nName implementation evidence explicitly. This prevents a matching README\nelsewhere in the repository from satisfying the map:\n\n```bash\nintent-verify map \\\n  --spec INTENT.md \\\n  --repo . \\\n  --evidence-path src \\\n  --evidence-path tests\n```\n\nThe command emits only JSON using the versioned\n`intent-verify.coverage-map.v1` contract. Each item includes the files that\ncontributed matching terms. The top-level `acceptance_authority` is always\n`false`; `decision` is `review` for covered scope and `inspect` for partial or\ngap results.\n\n| Map verdict | Exit | Orchestration meaning |\n| --- | ---: | --- |\n| `covered` | `0` | Continue to tests and review; do not accept automatically. |\n| `partial` | `1` | Inspect the weak items before claiming scope coverage. |\n| `gap` | `2` | Stop the scope-covered claim and inspect missing evidence. |\n\n### GitHub Action\n\nThe root composite Action applies the same contract. A workflow can use the\nversioned `v0.2.1` tag:\n\n```yaml\n- name: Map intent to changed implementation surfaces\n  uses: hermes-labs-ai/intent-verify@v0.2.1\n  with:\n    spec: INTENT.md\n    repo: .\n    evidence-paths: |\n      src\n      tests\n    summary: true # optional; defaults to false\n```\n\nResolve the tag to its commit SHA when your supply-chain policy requires a\nfull commit pin.\n\nUpload the path returned by the Action's `receipt` output when the JSON should\nremain as a build artifact.\n\nSet `summary: true` to add a bounded, escaped advisory coverage table to the\nGitHub Actions job summary. It includes the caller's spec path and acceptance\nitem labels, so leave it off when those labels are sensitive. The summary does\nnot grant acceptance authority: it reports lexical evidence only; review,\ntests, and human judgment still decide correctness and merge readiness. The\n`summary-written` output reports whether the requested summary was rendered.\n\nThe repository retains `.zenodo.json` as passive metadata. Its listed DOI is a\nreference to the associated paper, not a software identity; Zenodo archiving is\nnot a release prerequisite or a promised release side effect.\n\n### Agent plugin (Claude Code, Codex CLI, Gemini CLI)\n\nThe repository root is one portable Agent Plugin (`plugin.json`, Agent Plugins\n1.0.0) with a single skill, `skills/intent-verify/SKILL.md`. Each host installs\nthat same skill with its own native command; none of them gets a separate copy.\n\n| Host | Install | Read back |\n| --- | --- | --- |\n| Claude Code | `claude plugin marketplace add hermes-labs-ai/intent-verify`<br>`claude plugin install intent-verify@intent-verify` | `claude plugin list` |\n| OpenAI Codex CLI | `codex plugin marketplace add hermes-labs-ai/intent-verify`<br>`codex plugin add intent-verify@intent-verify` | `codex plugin list` |\n| Gemini CLI | `gemini extensions install https://github.com/hermes-labs-ai/intent-verify --ref v0.2.1` | `gemini skills list` |\n| skills.sh | `npx skills add https://github.com/hermes-labs-ai/intent-verify#v0.2.1 --skill intent-verify` | `npx skills list` |\n\nWhat each host reads:\n\n- Claude Code reads `.claude-plugin/marketplace.json` (its entry is `.`, the\n  root) and `.claude-plugin/plugin.json`.\n- Codex reads the repo marketplace `.agents/plugins/marketplace.json` (its\n  entry is `./`, the root) and the portable `plugin.json`.\n- Gemini CLI reads `gemini-extension.json` and discovers the skill under\n  `skills/`. Keep `--ref v0.2.1` so installation resolves the reviewed semantic\n  release rather than a mutable branch.\n\nThe skill uses an installed `intent-verify` CLI, or the pinned\n`uvx intent-verify==0.2.1` with your agreement.\n\nIn Claude Code the plugin also adds two on-demand commands. Use\n`/intent-verify:check --spec INTENT.md --repo .` for a normal coverage check,\nor `/intent-verify:map --spec INTENT.md --repo . --evidence-path src` to emit a\nprovenance map for explicit implementation roots. Both commands use the local\n`intent-verify` CLI and run only when you invoke them. Their results remain\nadvisory lexical evidence: `covered` and `verified` do not authorize\nacceptance, merge, release, or publication.\n\n## Install\n\n```bash\npip install intent-verify\npython -c \"from importlib.metadata import version; print(version('intent-verify'))\"   # confirm the installed release\n```\n\nOr install the CLI from the [Hermes Labs Homebrew tap](https://github.com/hermes-labs-ai/homebrew-tap):\n\n```bash\nbrew install hermes-labs-ai/tap/intent-verify\n```\n\nFor local development:\n\n```bash\npip install -e \".[dev]\"\n```\n\n## 60-second quickstart\n\nGiven a spec like:\n\n```markdown\n# Intent\n\n## Accepts\n- uploads PDF invoices\n- retries provider timeout\n```\n\nrun:\n\n```bash\nintent-verify check --spec INTENT.md --repo .\n```\n\nYou get a per-item breakdown and a single verdict:\n\n```text\nintent-verify: INTENT.md vs . (12 files)\n  [OK   100%] uploads PDF invoices\n  [PART  50%] retries provider timeout\n  [LOW   20%] writes audit log for rejected invoices\nintent-verify: MISSING — 1/3 items below 30% (avg 57%)\n```\n\n(The file count, percentages, and items above are illustrative — your numbers depend on your spec and repo.)\n\nThe exit code mirrors the verdict, so it drops straight into CI or a pre-commit hook:\n\n| Verdict | Meaning | Exit code |\n| --- | --- | --- |\n| `verified` | every parsed item cleared the verified threshold | `0` |\n| `partial` | at least one item is only partly covered | `1` |\n| `missing` | at least one item fell below the per-item minimum | `2` |\n\n![intent-verify preview](assets/preview.png)\n\n## Usage\n\n```bash\nintent-verify check --spec INTENT.md --repo .\nintent-verify check --spec SPEC.md --repo . --json\nintent-verify check --spec docs/handoff.md --repo src --min-verified 0.75 --min-item 0.35\n```\n\nFlags:\n\n- `--spec` — path to the markdown spec, intent, or handoff file (required).\n- `--repo` — path to the repo or source tree to scan (required).\n- `--section` — target a specific markdown heading, for example `Requirements`.\n- `--json` — emit machine-readable JSON instead of text.\n- `--min-verified` — coverage an item must clear to count as verified (default `0.7`).\n- `--min-item` — minimum per-item coverage before an item is treated as missing (default `0.3`).\n\n### What it parses\n\nBy default it extracts items from:\n\n- inline lines such as `Accepts: upload PDF invoices, retry on timeout`\n- markdown sections such as `## Accepts` with bullet or numbered items (`Accepts`, `Requirements`, `Scope` headings, or a custom one via `--section`)\n\n### JSON output\n\n```bash\nintent-verify check --spec INTENT.md --repo . --json\n```\n\nThe JSON object includes `spec_path`, `repo_path`, `files_scanned`,\n`average_coverage`, `verdict`, the thresholds used, and an `items[]` array with\neach item's parsed text, tokens, coverage, verdict, and contributing evidence\npaths. Legacy `check` output remains compatible and now includes the explicit\nnon-authority metadata.\n\n## Limitations / what it does NOT do\n\n- **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.\n- **Lexical, not semantic.** It matches tokens as substrings; it does not understand meaning, control flow, or behavior.\n- **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.\n- **It can under-credit.** A correct implementation written with different vocabulary than the spec will score low.\n- **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?\"\n- **It needs a human-readable spec.** With no `INTENT.md`/`SPEC.md`/requirements/handoff file there is nothing to check against.\n- **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.\n- **Evidence paths are not behavioral proof.** `map` prevents unrelated paths\n  from contributing, but comments, docstrings, and dead code inside selected\n  paths can still match. Tests and review remain authoritative.\n\n## Development\n\n```bash\nruff check .\npython3 -m pytest -q\npython3 -m py_compile src/intent_verify/*.py\n```\n\n## Repository layout\n\n```text\nsrc/intent_verify/\ntests/\nexamples/\nskills/intent-verify/SKILL.md   canonical agent skill\ncommands/                       Claude Code slash commands\nplugin.json                     portable Agent Plugins 1.0.0 manifest\n.claude-plugin/                 Claude Code plugin + marketplace\n.agents/plugins/marketplace.json Codex CLI marketplace\ngemini-extension.json           Gemini CLI extension\n```\n\n---\n\nPart of the [Hermes Labs reliability stack](https://github.com/hermes-labs-ai). Complementary siblings, not duplicates: [rule-audit](https://github.com/hermes-labs-ai/rule-audit) analyzes logical contradictions in system prompts, and [lintlang](https://github.com/hermes-labs-ai/lintlang) lints agent-config structure — intent-verify instead checks spec-vs-code drift.\n\n## About Hermes Labs\n\nHermes Labs is an agentic infrastructure company building the reliability layer for autonomous systems.\n\nBrowse the [open-source catalog](https://hermes-labs.ai/open-source) or contact [roli@hermes-labs.ai](mailto:roli@hermes-labs.ai).\n",
  "bytes": 11485,
  "sha": "48763b032792e1108f72b3c862ddad7ea9f7b0fc2bdc8a147a0f4669bc320ba7",
  "repo_slug": "roli-lpci/intent-verify",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/plg_roli_lpci_intent_verify_28569aa0/readme"
}