# Citation Verifiability Auditor CLI

## PURPOSE
A reviewer receives a drafted contract or memo and must decide whether each factual assertion can be traced to a source. Doing that by hand across a 90-page global agreement is slow and inconsistent. This CLI ingests a draft as structured paragraphs, splits it into claims, checks which claims carry a citation marker, and emits a per-paragraph audit report plus a coverage score that can fail a CI gate.

## WHY THIS MATTERS
The video's promise is that with ChatGPT Enterprise plus the trust delivered through Counsel Legal and HiQu, "that judgement becomes verifiable, becomes cited." Verifiability is only real if someone can measure it. This tool turns an abstract trust claim into a number — percentage of claims with a resolvable citation — and a list of the exact sentences that would embarrass a lawyer asked to sign the document.

## HOW TO BUILD
1. `pip install -r requirements.txt`; use Click for the interface and Pandas for the report.
2. Define the input format: a JSON list of paragraphs, each with `id`, `text`, `office` and an optional `citations: [{source_id, quote}]`.
3. Mark claim-bearing sentences with a small rule set (presence of a modal or obligation verb such as "shall", "must", "is required", plus a noun phrase) — deterministic, no LLM needed.
4. A sentence is `unverified` when it is a claim and has no citation whose quote appears in the paragraph text.
5. Aggregate with Pandas: coverage per office, worst paragraphs first, exit code 1 when coverage drops below `--min-coverage`.
6. Write `audit_report.csv` and print a Rich-style table to stdout.

```python
@click.command()
@click.argument("draft", type=click.Path(exists=True, path_type=Path))
@click.option("--min-coverage", default=0.9, show_default=True, type=float)
@click.option("--out", default="audit_report.csv", type=click.Path(path_type=Path))
def audit(draft: Path, min_coverage: float, out: Path) -> None:
    paragraphs = json.loads(draft.read_text())
    rows = [r for p in paragraphs for r in audit_paragraph(p)]
    df = pd.DataFrame(rows)
    coverage = (df["verified"].sum() / len(df)) if len(df) else 1.0
    df.sort_values(["verified", "office"]).to_csv(out, index=False)
    click.echo(f"citation coverage: {coverage:.1%}  -> {out}")
    if coverage < min_coverage:
        raise SystemExit(1)
```

## WHEN TO USE IN PRODUCTION
Use it as a pre-signature gate in a document pipeline, as a nightly regression check on a drafting model, or as a dashboard feed for a knowledge/quality team. Do NOT use it to judge legal correctness — it only checks traceability. It is a poor fit for narrative prose without discrete claims, and it must never be pointed at privileged text outside the sanctioned environment.

## HOW IT HELPS STUDENTS
Students learn structured CLI design, deterministic text heuristics, Pandas aggregation and non-zero exit codes as a contract with CI. It teaches that "trustworthy AI" is mostly instrumentation: measure provenance or you cannot promise it.

## STARTER CODE
`starter/main.py` ships a working Click command with the claim heuristic, the citation resolver, the Pandas report and the coverage gate; `# TODO` markers show where a real sentence-splitter and a Counsel Legal citation resolver would plug in.
