Metadata-Version: 2.4
Name: spec-gap-scout
Version: 0.1.0
Summary: Trace markdown requirements against repository evidence and flag likely implementation gaps.
Project-URL: Homepage, https://github.com/iwaheedsattar/spec-gap-scout
Project-URL: Repository, https://github.com/iwaheedsattar/spec-gap-scout
Project-URL: Issues, https://github.com/iwaheedsattar/spec-gap-scout/issues
Author: Haider Sattar
License-Expression: MIT
License-File: LICENSE
Keywords: ai,audit,developer-tools,repository,requirements,spec
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Provides-Extra: llm
Requires-Dist: anthropic>=0.39; extra == 'llm'
Requires-Dist: openai>=1.54; extra == 'llm'
Requires-Dist: requests>=2.32; extra == 'llm'
Description-Content-Type: text/markdown

![Spec Gap Scout terminal report](docs/terminal-report.svg)

# 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

```bash
pip install spec-gap-scout
```

Optional LLM risk notes need provider SDKs:

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

## Quick Start

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

Markdown and JSON reports are available:

```bash
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:

```bash
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

```python
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

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

## License

MIT
