intent-verify 0.1.0__tar.gz

intent_verify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rolando Bosch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

intent_verify-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: intent-verify
+Version: 0.1.0
+Summary: Repo intent verification and spec drift checks for markdown specs, handoffs, and codebases.
+Author: Rolando Bosch
+License: MIT
+Keywords: spec drift,repo intent verification,handoff verification,acceptance criteria,ci lint
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# intent-verify: repo intent verification and spec drift checks
+
+Find spec drift fast when your repo has an `INTENT.md`, `SPEC.md`, or handoff doc but nobody knows if the code still matches it.
+
+`intent-verify` checks a markdown spec against a repo and returns `verified`, `partial`, or `missing` so you can catch repo intent drift before review, release, or handoff.
+
+- "My repo has an `INTENT.md` but nobody knows if the code still matches it."
+- "Reviews catch scope drift too late."
+- "A handoff doc says one thing and the implementation says another."
+- "I want a cheap CI check for spec drift before merge."
+- "We need repo intent verification without inventing another full compliance system."
+
+Fastest install:
+
+```bash
+pip install intent-verify
+```
+
+Fastest real usage:
+
+```bash
+intent-verify check --spec INTENT.md --repo .
+```
+
+Exact outcome:
+
+```text
+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%)
+```
+
+![intent-verify preview](assets/preview.png)
+
+This is a guardrail, not proof of correctness. It answers “does the implementation visibly cover the stated scope?” not “is the software correct?”
+
+## Install
+
+```bash
+pip install intent-verify
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Common search-intent use cases
+
+- repo intent verification
+- spec drift check
+- handoff verification
+- acceptance criteria drift detection
+- CI check for markdown spec vs code
+
+## Usage
+
+```bash
+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
+```
+
+## 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 items
+
+It also supports custom headings:
+
+```bash
+intent-verify check --spec SPEC.md --section "Requirements"
+```
+
+## Output
+
+```text
+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 35% (avg 57%)
+```
+
+JSON mode:
+
+```bash
+intent-verify check --spec INTENT.md --repo . --json
+```
+
+## Limitations
+
+- Lexical, not semantic.
+- Can over-credit token overlap.
+- Can under-credit implementations expressed with different vocabulary.
+- Best used as a CI guardrail or review hint, not as a substitute for tests and code review.
+
+## When To Use It
+
+- You keep project intent in markdown.
+- You want a lightweight repo intent verification step in CI.
+- You need a handoff verification check before merging or releasing.
+
+## When Not To Use It
+
+- You need semantic verification of behavior.
+- You do not have any human-readable spec, intent, or requirements file.
+- You want proof of correctness instead of a fast drift signal.
+
+## More From Hermes Labs
+
+- [csv-quality-gate](https://github.com/roli-lpci/csv-quality-gate): CSV preflight validation and batch CSV quality checks
+
+## Development
+
+```bash
+ruff check .
+python3 -m pytest -q
+python3 -m py_compile src/intent_verify/*.py
+```
+
+## Repository layout
+
+```text
+src/intent_verify/
+tests/
+examples/
+```

intent_verify-0.1.0/README.md

@@ -0,0 +1,133 @@
+# intent-verify: repo intent verification and spec drift checks
+
+Find spec drift fast when your repo has an `INTENT.md`, `SPEC.md`, or handoff doc but nobody knows if the code still matches it.
+
+`intent-verify` checks a markdown spec against a repo and returns `verified`, `partial`, or `missing` so you can catch repo intent drift before review, release, or handoff.
+
+- "My repo has an `INTENT.md` but nobody knows if the code still matches it."
+- "Reviews catch scope drift too late."
+- "A handoff doc says one thing and the implementation says another."
+- "I want a cheap CI check for spec drift before merge."
+- "We need repo intent verification without inventing another full compliance system."
+
+Fastest install:
+
+```bash
+pip install intent-verify
+```
+
+Fastest real usage:
+
+```bash
+intent-verify check --spec INTENT.md --repo .
+```
+
+Exact outcome:
+
+```text
+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%)
+```
+
+![intent-verify preview](assets/preview.png)
+
+This is a guardrail, not proof of correctness. It answers “does the implementation visibly cover the stated scope?” not “is the software correct?”
+
+## Install
+
+```bash
+pip install intent-verify
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Common search-intent use cases
+
+- repo intent verification
+- spec drift check
+- handoff verification
+- acceptance criteria drift detection
+- CI check for markdown spec vs code
+
+## Usage
+
+```bash
+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
+```
+
+## 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 items
+
+It also supports custom headings:
+
+```bash
+intent-verify check --spec SPEC.md --section "Requirements"
+```
+
+## Output
+
+```text
+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 35% (avg 57%)
+```
+
+JSON mode:
+
+```bash
+intent-verify check --spec INTENT.md --repo . --json
+```
+
+## Limitations
+
+- Lexical, not semantic.
+- Can over-credit token overlap.
+- Can under-credit implementations expressed with different vocabulary.
+- Best used as a CI guardrail or review hint, not as a substitute for tests and code review.
+
+## When To Use It
+
+- You keep project intent in markdown.
+- You want a lightweight repo intent verification step in CI.
+- You need a handoff verification check before merging or releasing.
+
+## When Not To Use It
+
+- You need semantic verification of behavior.
+- You do not have any human-readable spec, intent, or requirements file.
+- You want proof of correctness instead of a fast drift signal.
+
+## More From Hermes Labs
+
+- [csv-quality-gate](https://github.com/roli-lpci/csv-quality-gate): CSV preflight validation and batch CSV quality checks
+
+## Development
+
+```bash
+ruff check .
+python3 -m pytest -q
+python3 -m py_compile src/intent_verify/*.py
+```
+
+## Repository layout
+
+```text
+src/intent_verify/
+tests/
+examples/
+```

intent_verify-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "intent-verify"
+version = "0.1.0"
+description = "Repo intent verification and spec drift checks for markdown specs, handoffs, and codebases."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "Rolando Bosch"},
+]
+keywords = ["spec drift", "repo intent verification", "handoff verification", "acceptance criteria", "ci lint"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+intent-verify = "intent_verify.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.5"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

intent_verify-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

intent_verify-0.1.0/src/intent_verify/__init__.py

@@ -0,0 +1,3 @@
+from .report import CheckResult, ItemResult, Verdict, run_check
+
+__all__ = ["CheckResult", "ItemResult", "Verdict", "run_check"]

intent_verify-0.1.0/src/intent_verify/cli.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .models import Verdict
+from .report import run_check, to_json, to_text
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="intent-verify",
+        description="Check a markdown spec or handoff doc against a repo to catch spec drift.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    check = subparsers.add_parser(
+        "check",
+        help="run repo intent verification against a markdown spec",
+    )
+    check.add_argument(
+        "--spec",
+        required=True,
+        help="path to markdown spec, intent, or handoff file",
+    )
+    check.add_argument("--repo", required=True, help="path to repo or source tree to scan")
+    check.add_argument(
+        "--section",
+        help="optional markdown heading to target, for example Requirements",
+    )
+    check.add_argument("--json", action="store_true", help="emit machine-readable JSON output")
+    check.add_argument(
+        "--min-verified",
+        type=float,
+        default=0.7,
+        help="coverage threshold an item must clear to count as verified",
+    )
+    check.add_argument(
+        "--min-item",
+        type=float,
+        default=0.3,
+        help="minimum per-item threshold before the result becomes missing",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command != "check":
+        parser.error("unsupported command")
+
+    spec_path = Path(args.spec)
+    repo_path = Path(args.repo)
+    if not spec_path.exists():
+        print(f"intent-verify: spec not found: {spec_path}", file=sys.stderr)
+        return 2
+    if not repo_path.exists() or not repo_path.is_dir():
+        print(f"intent-verify: repo path is not a directory: {repo_path}", file=sys.stderr)
+        return 2
+    if not 0 < args.min_item <= args.min_verified <= 1:
+        print(
+            "intent-verify: thresholds must satisfy 0 < min-item <= min-verified <= 1",
+            file=sys.stderr,
+        )
+        return 2
+
+    result = run_check(
+        spec_path,
+        repo_path,
+        section=args.section,
+        min_verified=args.min_verified,
+        min_item=args.min_item,
+    )
+    print(to_json(result) if args.json else to_text(result))
+    return {
+        Verdict.VERIFIED: 0,
+        Verdict.PARTIAL: 1,
+        Verdict.MISSING: 2,
+    }[result.verdict]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

intent_verify-0.1.0/src/intent_verify/models.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Verdict(str, Enum):
+    VERIFIED = "verified"
+    PARTIAL = "partial"
+    MISSING = "missing"
+
+
+@dataclass(frozen=True)
+class ItemResult:
+    text: str
+    tokens: list[str]
+    coverage: float
+    verdict: Verdict
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    spec_path: str
+    repo_path: str
+    files_scanned: int
+    items: list[ItemResult]
+    average_coverage: float
+    verdict: Verdict
+    min_verified: float
+    min_item: float

intent_verify-0.1.0/src/intent_verify/parser.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import re
+
+INLINE_RE = re.compile(r"(?:^|\n)\s*(Accepts?|Requirements?|Scope):\s*([^\n]+)", re.IGNORECASE)
+
+
+def parse_spec_items(text: str, section: str | None = None) -> list[str]:
+    items: list[str] = []
+    items.extend(_parse_inline_items(text))
+    items.extend(_parse_section_items(text, section))
+
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for item in items:
+        cleaned = item.strip().strip(".")
+        key = cleaned.casefold()
+        if cleaned and key not in seen:
+            seen.add(key)
+            deduped.append(cleaned)
+    return deduped
+
+
+def _parse_inline_items(text: str) -> list[str]:
+    items: list[str] = []
+    for match in INLINE_RE.finditer(text):
+        raw = match.group(2).strip()
+        parts = [part.strip(" .\t") for part in re.split(r",\s*|\s*;\s*", raw) if part.strip()]
+        items.extend(parts)
+    return items
+
+
+def _parse_section_items(text: str, section: str | None) -> list[str]:
+    target_names = ["Accepts", "Requirements", "Scope"]
+    if section:
+        target_names = [section]
+    pattern = "|".join(re.escape(name) for name in target_names)
+    header_re = re.compile(
+        rf"(?:^|\n)#+\s*({pattern})\s*\n(.+?)(?=\n#|\Z)",
+        re.IGNORECASE | re.DOTALL,
+    )
+    items: list[str] = []
+    for match in header_re.finditer(text):
+        body = match.group(2)
+        for line in body.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                continue
+            bullet = re.match(r"^[-*+]\s+(.+)$", stripped)
+            ordered = re.match(r"^\d+\.\s+(.+)$", stripped)
+            if bullet:
+                items.append(bullet.group(1).strip())
+            elif ordered:
+                items.append(ordered.group(1).strip())
+    return items

intent_verify-0.1.0/src/intent_verify/report.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .models import CheckResult, ItemResult, Verdict
+from .parser import parse_spec_items
+from .scanner import coverage_for_tokens, load_repo_blobs
+from .tokenizer import tokenize
+
+
+def coverage_verdict(coverage: float, min_verified: float, min_item: float) -> Verdict:
+    if coverage >= min_verified:
+        return Verdict.VERIFIED
+    if coverage >= min_item:
+        return Verdict.PARTIAL
+    return Verdict.MISSING
+
+
+def aggregate_verdict(items: list[ItemResult], min_verified: float, min_item: float) -> Verdict:
+    if not items:
+        return Verdict.MISSING
+    if any(item.coverage < min_item for item in items):
+        return Verdict.MISSING
+    if any(item.coverage < min_verified for item in items):
+        return Verdict.PARTIAL
+    average = sum(item.coverage for item in items) / len(items)
+    if average < min_verified:
+        return Verdict.PARTIAL
+    return Verdict.VERIFIED
+
+
+def run_check(
+    spec_path: Path,
+    repo_path: Path,
+    *,
+    section: str | None = None,
+    min_verified: float = 0.7,
+    min_item: float = 0.3,
+) -> CheckResult:
+    text = spec_path.read_text(encoding="utf-8")
+    items = parse_spec_items(text, section=section)
+    blobs = load_repo_blobs(repo_path, exclude_paths={spec_path})
+
+    item_results: list[ItemResult] = []
+    for item in items:
+        tokens = tokenize(item)
+        coverage = coverage_for_tokens(tokens, blobs)
+        item_results.append(
+            ItemResult(
+                text=item,
+                tokens=tokens,
+                coverage=coverage,
+                verdict=coverage_verdict(coverage, min_verified, min_item),
+            )
+        )
+
+    average = (
+        sum(item.coverage for item in item_results) / len(item_results)
+        if item_results
+        else 0.0
+    )
+    verdict = aggregate_verdict(item_results, min_verified, min_item)
+    return CheckResult(
+        spec_path=str(spec_path),
+        repo_path=str(repo_path),
+        files_scanned=len(blobs),
+        items=item_results,
+        average_coverage=average,
+        verdict=verdict,
+        min_verified=min_verified,
+        min_item=min_item,
+    )
+
+
+def to_json(result: CheckResult) -> str:
+    return json.dumps(
+        {
+            "spec_path": result.spec_path,
+            "repo_path": result.repo_path,
+            "files_scanned": result.files_scanned,
+            "average_coverage": round(result.average_coverage, 3),
+            "verdict": result.verdict.value,
+            "thresholds": {
+                "min_verified": result.min_verified,
+                "min_item": result.min_item,
+            },
+            "items": [
+                {
+                    "text": item.text,
+                    "tokens": item.tokens,
+                    "coverage": round(item.coverage, 3),
+                    "verdict": item.verdict.value,
+                }
+                for item in result.items
+            ],
+        },
+        indent=2,
+    )
+
+
+def to_text(result: CheckResult) -> str:
+    lines = [
+        f"intent-verify: {Path(result.spec_path).name} vs "
+        f"{result.repo_path} ({result.files_scanned} files)"
+    ]
+    for item in result.items:
+        label = {
+            Verdict.VERIFIED: "OK   ",
+            Verdict.PARTIAL: "PART ",
+            Verdict.MISSING: "LOW  ",
+        }[item.verdict]
+        lines.append(f"  [{label}{item.coverage:.0%}] {item.text}")
+    if result.verdict is Verdict.MISSING:
+        low_count = sum(1 for item in result.items if item.coverage < result.min_item)
+        lines.append(
+            f"intent-verify: MISSING — {low_count}/{len(result.items)} "
+            f"items below {result.min_item:.0%} "
+            f"(avg {result.average_coverage:.0%})"
+        )
+    elif result.verdict is Verdict.PARTIAL:
+        lines.append(f"intent-verify: PARTIAL — avg coverage {result.average_coverage:.0%}")
+    else:
+        lines.append(f"intent-verify: VERIFIED — avg coverage {result.average_coverage:.0%}")
+    return "\n".join(lines)

intent_verify-0.1.0/src/intent_verify/scanner.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+DEFAULT_EXTENSIONS = {
+    ".cfg",
+    ".go",
+    ".ini",
+    ".js",
+    ".json",
+    ".jsx",
+    ".md",
+    ".py",
+    ".rs",
+    ".sh",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".yaml",
+    ".yml",
+}
+
+DEFAULT_SKIP_DIRS = {
+    ".git",
+    ".mypy_cache",
+    ".next",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "target",
+    "venv",
+}
+
+
+def load_repo_blobs(
+    repo_path: Path,
+    extensions: set[str] | None = None,
+    exclude_paths: set[Path] | None = None,
+) -> list[tuple[str, str]]:
+    exts = extensions or DEFAULT_EXTENSIONS
+    excluded = {path.resolve() for path in (exclude_paths or set())}
+    blobs: list[tuple[str, str]] = []
+    for root, dirs, files in os.walk(repo_path):
+        dirs[:] = [
+            name
+            for name in dirs
+            if name not in DEFAULT_SKIP_DIRS and not name.startswith(".")
+        ]
+        for name in files:
+            suffix = Path(name).suffix.lower()
+            if suffix not in exts:
+                continue
+            path = Path(root) / name
+            if path.resolve() in excluded:
+                continue
+            try:
+                blobs.append((str(path), path.read_text(encoding="utf-8", errors="ignore").lower()))
+            except OSError:
+                continue
+    return blobs
+
+
+def coverage_for_tokens(tokens: list[str], blobs: list[tuple[str, str]]) -> float:
+    if not tokens:
+        return 0.0
+    found: set[str] = set()
+    for _, blob in blobs:
+        for token in tokens:
+            if token in found:
+                continue
+            if token in blob:
+                found.add(token)
+        if len(found) == len(tokens):
+            break
+    return len(found) / len(tokens)

intent_verify-0.1.0/src/intent_verify/tokenizer.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import re
+
+STOP_WORDS = {
+    "a",
+    "an",
+    "and",
+    "as",
+    "at",
+    "be",
+    "but",
+    "by",
+    "for",
+    "from",
+    "has",
+    "have",
+    "in",
+    "into",
+    "is",
+    "it",
+    "its",
+    "of",
+    "on",
+    "or",
+    "that",
+    "the",
+    "this",
+    "to",
+    "via",
+    "was",
+    "were",
+    "will",
+    "with",
+    "without",
+}
+
+TOKEN_RE = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]{2,}")
+
+
+def tokenize(text: str) -> list[str]:
+    words = [word.lower() for word in TOKEN_RE.findall(text)]
+    seen: set[str] = set()
+    result: list[str] = []
+    for word in words:
+        if word in STOP_WORDS or word in seen:
+            continue
+        seen.add(word)
+        result.append(word)
+    return result

intent_verify-0.1.0/src/intent_verify.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: intent-verify
+Version: 0.1.0
+Summary: Repo intent verification and spec drift checks for markdown specs, handoffs, and codebases.
+Author: Rolando Bosch
+License: MIT
+Keywords: spec drift,repo intent verification,handoff verification,acceptance criteria,ci lint
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# intent-verify: repo intent verification and spec drift checks
+
+Find spec drift fast when your repo has an `INTENT.md`, `SPEC.md`, or handoff doc but nobody knows if the code still matches it.
+
+`intent-verify` checks a markdown spec against a repo and returns `verified`, `partial`, or `missing` so you can catch repo intent drift before review, release, or handoff.
+
+- "My repo has an `INTENT.md` but nobody knows if the code still matches it."
+- "Reviews catch scope drift too late."
+- "A handoff doc says one thing and the implementation says another."
+- "I want a cheap CI check for spec drift before merge."
+- "We need repo intent verification without inventing another full compliance system."
+
+Fastest install:
+
+```bash
+pip install intent-verify
+```
+
+Fastest real usage:
+
+```bash
+intent-verify check --spec INTENT.md --repo .
+```
+
+Exact outcome:
+
+```text
+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%)
+```
+
+![intent-verify preview](assets/preview.png)
+
+This is a guardrail, not proof of correctness. It answers “does the implementation visibly cover the stated scope?” not “is the software correct?”
+
+## Install
+
+```bash
+pip install intent-verify
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Common search-intent use cases
+
+- repo intent verification
+- spec drift check
+- handoff verification
+- acceptance criteria drift detection
+- CI check for markdown spec vs code
+
+## Usage
+
+```bash
+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
+```
+
+## 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 items
+
+It also supports custom headings:
+
+```bash
+intent-verify check --spec SPEC.md --section "Requirements"
+```
+
+## Output
+
+```text
+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 35% (avg 57%)
+```
+
+JSON mode:
+
+```bash
+intent-verify check --spec INTENT.md --repo . --json
+```
+
+## Limitations
+
+- Lexical, not semantic.
+- Can over-credit token overlap.
+- Can under-credit implementations expressed with different vocabulary.
+- Best used as a CI guardrail or review hint, not as a substitute for tests and code review.
+
+## When To Use It
+
+- You keep project intent in markdown.
+- You want a lightweight repo intent verification step in CI.
+- You need a handoff verification check before merging or releasing.
+
+## When Not To Use It
+
+- You need semantic verification of behavior.
+- You do not have any human-readable spec, intent, or requirements file.
+- You want proof of correctness instead of a fast drift signal.
+
+## More From Hermes Labs
+
+- [csv-quality-gate](https://github.com/roli-lpci/csv-quality-gate): CSV preflight validation and batch CSV quality checks
+
+## Development
+
+```bash
+ruff check .
+python3 -m pytest -q
+python3 -m py_compile src/intent_verify/*.py
+```
+
+## Repository layout
+
+```text
+src/intent_verify/
+tests/
+examples/
+```

intent_verify-0.1.0/src/intent_verify.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/intent_verify/__init__.py
+src/intent_verify/cli.py
+src/intent_verify/models.py
+src/intent_verify/parser.py
+src/intent_verify/report.py
+src/intent_verify/scanner.py
+src/intent_verify/tokenizer.py
+src/intent_verify.egg-info/PKG-INFO
+src/intent_verify.egg-info/SOURCES.txt
+src/intent_verify.egg-info/dependency_links.txt
+src/intent_verify.egg-info/entry_points.txt
+src/intent_verify.egg-info/requires.txt
+src/intent_verify.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_parser.py
+tests/test_scanner.py
+tests/test_tokenizer.py

intent_verify-0.1.0/src/intent_verify.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

intent_verify-0.1.0/src/intent_verify.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+intent-verify = intent_verify.cli:main

intent_verify-0.1.0/src/intent_verify.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8.0
+ruff>=0.5

intent_verify-0.1.0/src/intent_verify.egg-info/top_level.txt

@@ -0,0 +1 @@
+intent_verify

intent_verify-0.1.0/tests/test_cli.py

@@ -0,0 +1,46 @@
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run_cli(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, "-m", "intent_verify.cli", *args],
+        cwd=ROOT,
+        env={"PYTHONPATH": str(ROOT / "src")},
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_cli_verified_fixture():
+    fixture = ROOT / "tests" / "fixtures" / "repo_ok"
+    result = run_cli("check", "--spec", str(fixture / "INTENT.md"), "--repo", str(fixture))
+    assert result.returncode == 0
+    assert "VERIFIED" in result.stdout
+
+
+def test_cli_partial_fixture_json():
+    fixture = ROOT / "tests" / "fixtures" / "repo_partial"
+    result = run_cli(
+        "check",
+        "--spec",
+        str(fixture / "INTENT.md"),
+        "--repo",
+        str(fixture),
+        "--json",
+    )
+    assert result.returncode == 1
+    payload = json.loads(result.stdout)
+    assert payload["verdict"] == "partial"
+
+
+def test_cli_missing_fixture():
+    fixture = ROOT / "tests" / "fixtures" / "repo_missing"
+    result = run_cli("check", "--spec", str(fixture / "INTENT.md"), "--repo", str(fixture))
+    assert result.returncode == 2
+    assert "MISSING" in result.stdout

intent_verify-0.1.0/tests/test_parser.py

@@ -0,0 +1,25 @@
+from intent_verify.parser import parse_spec_items
+
+
+def test_parse_inline_items():
+    text = "Accepts: upload PDF invoices, retry provider timeout"
+    assert parse_spec_items(text) == ["upload PDF invoices", "retry provider timeout"]
+
+
+def test_parse_section_items():
+    text = """
+# Spec
+
+## Accepts
+- uploads PDF invoices
+- retries provider timeout
+"""
+    assert parse_spec_items(text) == ["uploads PDF invoices", "retries provider timeout"]
+
+
+def test_parse_custom_section():
+    text = """
+## Requirements
+- writes audit log
+"""
+    assert parse_spec_items(text, section="Requirements") == ["writes audit log"]

intent_verify-0.1.0/tests/test_scanner.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+from intent_verify.scanner import coverage_for_tokens, load_repo_blobs
+
+
+def test_load_repo_blobs_skips_non_source_files():
+    fixture = Path(__file__).parent / "fixtures" / "repo_ok"
+    blobs = load_repo_blobs(fixture)
+    assert any(path.endswith("service.py") for path, _ in blobs)
+    assert all(not path.endswith(".png") for path, _ in blobs)
+
+
+def test_coverage_for_tokens():
+    blobs = [("a.py", "uploads pdf invoices and retries timeout")]
+    assert coverage_for_tokens(["uploads", "pdf", "timeout"], blobs) == 1.0

intent_verify-0.1.0/tests/test_tokenizer.py

@@ -0,0 +1,10 @@
+from intent_verify.tokenizer import tokenize
+
+
+def test_tokenize_dedupes_and_drops_stop_words():
+    assert tokenize("Accepts uploaded PDF invoices and invoices") == [
+        "accepts",
+        "uploaded",
+        "pdf",
+        "invoices",
+    ]