spec-gap-scout 0.1.0

Trace markdown requirements against repository evidence and flag likely implementation gaps.

spec-gap-scout

spec-gap-scout checks whether requirements in a markdown spec have visible evidence in a repository. It is built for the awkward moment before a release review when a PRD, checklist, or customer promise says one thing and the code may say another.

Problem

Specs drift. A release checklist says "export CSV", "prevent duplicate retries", or "redact provider responses", but reviewers still have to search the repository by hand. spec-gap-scout extracts requirement-like lines, scans code and docs, scores evidence, and flags likely gaps without sending repository contents anywhere by default.

Install

pip install spec-gap-scout

Optional LLM risk notes need provider SDKs:

pip install "spec-gap-scout[llm]"

Quick Start

spec-gap-scout examples/product-spec.md --repo examples/sample_repo

Markdown and JSON reports are available:

spec-gap-scout SPEC.md --repo . --format markdown --output spec-gap-report.md
spec-gap-scout SPEC.md --repo . --format json --output spec-gap-report.json

The command exits with 1 when one or more requirements are missing, which makes it useful in release scripts and pre-merge checks.

LLM Risk Notes

The scanner is local-first. If you want a concise risk note from an LLM, choose a provider explicitly:

spec-gap-scout SPEC.md --repo . --format markdown --llm-provider openai
spec-gap-scout SPEC.md --repo . --llm-provider anthropic --llm-model claude-3-5-haiku-latest
spec-gap-scout SPEC.md --repo . --llm-provider ollama --llm-model llama3.1

Provider configuration uses the normal environment variables:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• OLLAMA_HOST

Only the compact scan report is sent to the selected provider, not full source files.

What Counts as Evidence

For each requirement, the tool:

• extracts keywords from requirement-like markdown bullets and numbered lines
• scans common source, config, and documentation extensions
• scores matching lines by keyword coverage, path relevance, and test/spec locations
• redacts common key, token, secret, and password patterns in snippets
• labels each requirement as covered, partial, or missing

This is not a proof of correctness. It is a fast review map that tells you where to look first.

Python API

from pathlib import Path
from spec_gap_scout import ScoutOptions, run_scan

report = run_scan(ScoutOptions(spec=Path("SPEC.md"), repo=Path(".")))
print(report["summary"])

Development

python3 -m venv .venv
. .venv/bin/activate
pip install -e . pytest
pytest

License

MIT