assurance-cli 0.2.0__tar.gz → 0.2.2__tar.gz

assurance_cli-0.2.2/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: assurance-cli
+Version: 0.2.2
+Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
+Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://i-ops.dev
+Project-URL: Source, https://github.com/i-ops-hq/assurance-cli
+Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: assurance-core>=0.3.2
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# assurance-cli
+
+[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![Tests](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE)
+
+## Did the job cover everything it was supposed to cover?
+
+One command. One honest ratio. An exit code your pipeline can act on.
+
+```bash
+pip install assurance-cli
+```
+
+```bash
+assurance diff --expected corpus.txt --found retrieved.json \
+  --scope "documents the question spans" --where "the retrieved set" --fail-on-gap
+```
+```
+2 of 5 documents the question spans — not in the retrieved set: doc-2, doc-3, doc-5
+also present and not expected: doc-9
+```
+
+That second line matters as much as the ratio: the retriever drew on something the scope never
+allowed. It's reported, and it earns no credit.
+
+No account · no API key · no network call · **no model decides any of it**
+
+## Three commands
+
+### `assurance diff` — any two sets of keys
+
+```bash
+# code review agent actually read the diff?
+git diff --name-only origin/main...HEAD > changed.txt
+assurance diff --expected changed.txt --found reviewed.txt --fail-on-gap
+
+# eval suite ran every declared case?
+assurance diff --expected cases.json --found ran.json --fail-on-gap
+
+# straight from a pipe
+retriever --query "$Q" | jq -r '.chunks[].doc_id' | \
+  assurance diff --expected corpus.txt --found - --json
+```
+
+Inputs are whatever you already have: **one key per line**, a **JSON array** (strings, or objects
+with `key`/`id`/`name`/`path`), **`-` for stdin**, or an **inline comma list**.
+
+### `assurance check` — a folder of dated or numbered files
+
+```bash
+assurance check ~/reports
+```
+```
+22 of 24 months from 2024-01 to 2025-12 in reports — not in this folder: March 2025, July 2025
+— Range inferred from filenames: earliest 2024-01, latest 2025-12. Override with --from / --to.
+```
+
+```bash
+assurance check ~/invoices --expect numbered
+```
+```
+7 of 8 runs from inv_0001 to inv_0008 in invoices — not in this folder: INV-0006
+— Range inferred from filenames: earliest inv_0001, latest inv_0008. Override with --from / --to.
+```
+
+Monthly, quarterly, weekly, daily, numbered. That last line is the **derivation**: it prints with
+every ratio so you can disagree with the denominator, not just the result.
+
+### `assurance init` — did anything change underneath?
+
+```bash
+assurance init ~/thesis-data
+# ... weeks pass, several people touch the folder ...
+assurance check ~/thesis-data --against-baseline
+```
+
+## Exit codes
+
+| | |
+|---|---|
+| `0` | it checked, and either found no gap or wasn't asked to fail on one |
+| `1` | a finding: a gap with `--fail-on-gap`, a stale baseline, or **nothing it could check** |
+| `2` | could not run: bad path, unreadable list, unparseable JSON, a table where keys were expected |
+
+**"I couldn't check this" exits 1, not 0.** A folder whose filenames it can't parse must not look
+like a folder it checked and found whole.
+
+Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
+
+## It expects your files, not tidy ones
+
+- **Excel exports work.** UTF-8 BOM and CRLF are handled; a BOM used to glue itself to your first
+  key and report it as missing *and* unexpected in the same sentence
+- **Spaces, unicode and month words in filenames** — `Inventory Report August 2024.csv` parses
+- **`.xlsx`, and nested subfolders**
+- **A piped CSV is refused, not misread.** It names the column-picking command instead of quietly
+  admitting your header row as a key
+- **When it can't work out a series it says so**, rather than reporting an empty check as a pass
+
+## Use it for
+
+| | expected | found |
+|---|---|---|
+| **RAG** | documents the question spans | chunks retrieved |
+| **Code review in CI** | `git diff --name-only` | files reviewed |
+| **ETL / batch** | records or partitions declared | records or partitions loaded |
+| **Compliance** | controls in scope | controls with evidence |
+| **Research data** | the series you expect | what's actually in the folder |
+
+## What it won't do
+
+- **Invent your expected set.** `diff` takes your declaration; `check` derives one and prints how
+- **Send anything anywhere.** No network, no telemetry, no keys
+- **Guess.** A JSON object of id → metadata is refused, not interpreted
+
+## Family
+
+[assurance-core](https://pypi.org/project/assurance-core/) — the pure arithmetic, zero dependencies ·
+[assurance-mcp](https://pypi.org/project/assurance-mcp/) — the same checks as MCP tools
+
+Upstream is [I-Ops](https://i-ops.dev); this repo is a publication, never a source. Apache-2.0.

assurance_cli-0.2.2/README.md

@@ -0,0 +1,123 @@
+# assurance-cli
+
+[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![Tests](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE)
+
+## Did the job cover everything it was supposed to cover?
+
+One command. One honest ratio. An exit code your pipeline can act on.
+
+```bash
+pip install assurance-cli
+```
+
+```bash
+assurance diff --expected corpus.txt --found retrieved.json \
+  --scope "documents the question spans" --where "the retrieved set" --fail-on-gap
+```
+```
+2 of 5 documents the question spans — not in the retrieved set: doc-2, doc-3, doc-5
+also present and not expected: doc-9
+```
+
+That second line matters as much as the ratio: the retriever drew on something the scope never
+allowed. It's reported, and it earns no credit.
+
+No account · no API key · no network call · **no model decides any of it**
+
+## Three commands
+
+### `assurance diff` — any two sets of keys
+
+```bash
+# code review agent actually read the diff?
+git diff --name-only origin/main...HEAD > changed.txt
+assurance diff --expected changed.txt --found reviewed.txt --fail-on-gap
+
+# eval suite ran every declared case?
+assurance diff --expected cases.json --found ran.json --fail-on-gap
+
+# straight from a pipe
+retriever --query "$Q" | jq -r '.chunks[].doc_id' | \
+  assurance diff --expected corpus.txt --found - --json
+```
+
+Inputs are whatever you already have: **one key per line**, a **JSON array** (strings, or objects
+with `key`/`id`/`name`/`path`), **`-` for stdin**, or an **inline comma list**.
+
+### `assurance check` — a folder of dated or numbered files
+
+```bash
+assurance check ~/reports
+```
+```
+22 of 24 months from 2024-01 to 2025-12 in reports — not in this folder: March 2025, July 2025
+— Range inferred from filenames: earliest 2024-01, latest 2025-12. Override with --from / --to.
+```
+
+```bash
+assurance check ~/invoices --expect numbered
+```
+```
+7 of 8 runs from inv_0001 to inv_0008 in invoices — not in this folder: INV-0006
+— Range inferred from filenames: earliest inv_0001, latest inv_0008. Override with --from / --to.
+```
+
+Monthly, quarterly, weekly, daily, numbered. That last line is the **derivation**: it prints with
+every ratio so you can disagree with the denominator, not just the result.
+
+### `assurance init` — did anything change underneath?
+
+```bash
+assurance init ~/thesis-data
+# ... weeks pass, several people touch the folder ...
+assurance check ~/thesis-data --against-baseline
+```
+
+## Exit codes
+
+| | |
+|---|---|
+| `0` | it checked, and either found no gap or wasn't asked to fail on one |
+| `1` | a finding: a gap with `--fail-on-gap`, a stale baseline, or **nothing it could check** |
+| `2` | could not run: bad path, unreadable list, unparseable JSON, a table where keys were expected |
+
+**"I couldn't check this" exits 1, not 0.** A folder whose filenames it can't parse must not look
+like a folder it checked and found whole.
+
+Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
+
+## It expects your files, not tidy ones
+
+- **Excel exports work.** UTF-8 BOM and CRLF are handled; a BOM used to glue itself to your first
+  key and report it as missing *and* unexpected in the same sentence
+- **Spaces, unicode and month words in filenames** — `Inventory Report August 2024.csv` parses
+- **`.xlsx`, and nested subfolders**
+- **A piped CSV is refused, not misread.** It names the column-picking command instead of quietly
+  admitting your header row as a key
+- **When it can't work out a series it says so**, rather than reporting an empty check as a pass
+
+## Use it for
+
+| | expected | found |
+|---|---|---|
+| **RAG** | documents the question spans | chunks retrieved |
+| **Code review in CI** | `git diff --name-only` | files reviewed |
+| **ETL / batch** | records or partitions declared | records or partitions loaded |
+| **Compliance** | controls in scope | controls with evidence |
+| **Research data** | the series you expect | what's actually in the folder |
+
+## What it won't do
+
+- **Invent your expected set.** `diff` takes your declaration; `check` derives one and prints how
+- **Send anything anywhere.** No network, no telemetry, no keys
+- **Guess.** A JSON object of id → metadata is refused, not interpreted
+
+## Family
+
+[assurance-core](https://pypi.org/project/assurance-core/) — the pure arithmetic, zero dependencies ·
+[assurance-mcp](https://pypi.org/project/assurance-mcp/) — the same checks as MCP tools
+
+Upstream is [I-Ops](https://i-ops.dev); this repo is a publication, never a source. Apache-2.0.

{assurance_cli-0.2.0 → assurance_cli-0.2.2}/assurance_cli/cli.py

@@ -136,7 +136,12 @@ def _has_findings(payload: dict[str, Any]) -> bool:
     if payload.get("baseline") and not payload["baseline"].get("ok", True):
         return True
     coverage = payload.get("coverage") or payload
-    return bool(coverage.get("error"))
+    if coverage.get("error"):
+        return True
+    # "I could not work out what to check" is a finding, not a success. Exiting 0 here made a folder
+    # whose filenames we cannot parse indistinguishable, to a CI job, from a folder we checked and
+    # found whole — which is the one thing this tool exists not to do.
+    return bool((coverage.get("coverage") or {}).get("undetermined"))
 
 
 def _format_text(payload: dict[str, Any]) -> str:

{assurance_cli-0.2.0 → assurance_cli-0.2.2}/assurance_cli/gather.py

@@ -73,7 +73,7 @@ def check_coverage(
             "complete": False,
             "derivation": "",
             "coverage": _coverage_to_dict(
-                Coverage(scope_label=f"items in {root.name}", expected=[])
+                Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)
             ),
         }
 
@@ -88,7 +88,7 @@ def check_coverage(
             "complete": False,
             "derivation": "",
             "coverage": _coverage_to_dict(
-                Coverage(scope_label=f"items in {root.name}", expected=[])
+                Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)
             ),
         }
 
@@ -122,7 +122,7 @@ def check_coverage(
             "complete": False,
             "derivation": "",
             "coverage": _coverage_to_dict(
-                Coverage(scope_label=f"items in {root.name}", expected=[])
+                Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)
             ),
         }
 
@@ -264,13 +264,21 @@ def _unit_for_kind(kind: SeriesKind) -> str:
     }[kind]
 
 
+_UNDETERMINED = "no dated or numbered series could be read from these filenames"
+"""Why nothing was checked. Carried INTO the coverage record, not just the wrapper around it.
+
+Until 0.2.2 these paths emitted an empty `Coverage`, whose `complete` is True by the arithmetic —
+nothing was required, so nothing is missing. So the payload carried `complete: false` at the top and
+`complete: true` one level down, and an integrator reading either one was reading a real field."""
+
+
 def _error_result(root: Path, message: str) -> dict[str, Any]:
     return {
         "folder": str(root),
         "summary": message,
         "complete": False,
         "derivation": "",
-        "coverage": _coverage_to_dict(Coverage(scope_label=f"items in {root.name}", expected=[])),
+        "coverage": _coverage_to_dict(Coverage(scope_label=f"items in {root.name}", expected=[], undetermined=_UNDETERMINED)),
         "error": message,
     }
 
@@ -290,6 +298,7 @@ def _coverage_to_dict(cov: Coverage) -> dict[str, Any]:
         "unreadable": dict(cov.unreadable),
         "unauthorized": dict(cov.unauthorized),
         "truncated": cov.truncated,
+        "undetermined": cov.undetermined,
     }
 
 

{assurance_cli-0.2.0 → assurance_cli-0.2.2}/assurance_cli/setdiff.py

@@ -45,7 +45,11 @@ def read_keys(spec: str | None, *, label: str) -> list[str]:
         if candidate.exists():
             if candidate.is_dir():
                 raise KeySpecError(f"{label}: {spec} is a directory, not a list of keys")
-            text = candidate.read_text(encoding="utf-8")
+            # `utf-8-sig`, not `utf-8`. Excel writes CSV and TXT with a byte-order mark by default,
+            # and reading it as plain utf-8 glues U+FEFF to the FIRST key — so `doc-1` was reported
+            # as missing AND as unexpected in the same sentence, which is a confidently wrong answer
+            # produced by the most common export path there is.
+            text = candidate.read_text(encoding="utf-8-sig")
 
     if text is None:
         return _dedupe(part.strip() for part in spec.split(","))
@@ -64,11 +68,38 @@ def _parse(text: str, *, label: str) -> list[str]:
         return _keys_from_json(payload, label=label)
     # A full-line comment is dropped; a `#` inside a key is part of the key, because guessing which
     # is which would silently change someone's denominator.
-    return [
+    lines = [
         line.strip()
         for line in stripped.splitlines()
         if line.strip() and not line.lstrip().startswith("#")
     ]
+    _refuse_a_table(lines, label=label)
+    return lines
+
+
+def _refuse_a_table(lines: list[str], *, label: str) -> None:
+    """A delimited table is not a list of keys, and reading it as one is silent nonsense.
+
+    Piping a CSV is the obvious thing to try — it is what people have. Read line by line it produced
+    `0 of 3 — also present and not expected: doc_id,score, doc-1,0.9, doc-2,0.8`: a header row and
+    two score columns admitted as keys, and a confident zero. We cannot pick the column for you, so
+    this says which command does.
+
+    Deliberately narrow, because a key may legitimately contain a comma: it fires only when EVERY
+    line carries the SAME delimiter the SAME number of times, which is a table and not a coincidence.
+    """
+    if len(lines) < 2:
+        return
+    for delimiter, flag in (("\t", "-f1"), (",", "-d, -f1")):
+        counts = {line.count(delimiter) for line in lines}
+        if len(counts) == 1 and counts.pop() >= 1:
+            name = "tab" if delimiter == "\t" else "comma"
+            raise KeySpecError(
+                f"{label}: this looks like a {name}-delimited table, not a list of keys — every "
+                f"line has the same number of {name}s. Reading it line by line would admit the "
+                f"header and every other column as keys. Pick the column you mean, e.g. "
+                f"`cut {flag} file | assurance diff ... --{label.lstrip('-')} -`, or pass JSON."
+            )
 
 
 def _keys_from_json(payload: Any, *, label: str) -> list[str]:
@@ -106,7 +137,9 @@ def _dedupe(values: Any) -> list[str]:
     seen: set[str] = set()
     out: list[str] = []
     for value in values:
-        value = str(value).strip()
+        # A BOM can still arrive from stdin, where there is no decode step to strip it, and inside a
+        # JSON string. Strip it per key too: a stray U+FEFF changes what a key IS.
+        value = str(value).replace("\ufeff", "").strip()
         if value and value not in seen:
             seen.add(value)
             out.append(value)

assurance_cli-0.2.2/assurance_cli.egg-info/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: assurance-cli
+Version: 0.2.2
+Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
+Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://i-ops.dev
+Project-URL: Source, https://github.com/i-ops-hq/assurance-cli
+Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: assurance-core>=0.3.2
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# assurance-cli
+
+[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![Tests](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE)
+
+## Did the job cover everything it was supposed to cover?
+
+One command. One honest ratio. An exit code your pipeline can act on.
+
+```bash
+pip install assurance-cli
+```
+
+```bash
+assurance diff --expected corpus.txt --found retrieved.json \
+  --scope "documents the question spans" --where "the retrieved set" --fail-on-gap
+```
+```
+2 of 5 documents the question spans — not in the retrieved set: doc-2, doc-3, doc-5
+also present and not expected: doc-9
+```
+
+That second line matters as much as the ratio: the retriever drew on something the scope never
+allowed. It's reported, and it earns no credit.
+
+No account · no API key · no network call · **no model decides any of it**
+
+## Three commands
+
+### `assurance diff` — any two sets of keys
+
+```bash
+# code review agent actually read the diff?
+git diff --name-only origin/main...HEAD > changed.txt
+assurance diff --expected changed.txt --found reviewed.txt --fail-on-gap
+
+# eval suite ran every declared case?
+assurance diff --expected cases.json --found ran.json --fail-on-gap
+
+# straight from a pipe
+retriever --query "$Q" | jq -r '.chunks[].doc_id' | \
+  assurance diff --expected corpus.txt --found - --json
+```
+
+Inputs are whatever you already have: **one key per line**, a **JSON array** (strings, or objects
+with `key`/`id`/`name`/`path`), **`-` for stdin**, or an **inline comma list**.
+
+### `assurance check` — a folder of dated or numbered files
+
+```bash
+assurance check ~/reports
+```
+```
+22 of 24 months from 2024-01 to 2025-12 in reports — not in this folder: March 2025, July 2025
+— Range inferred from filenames: earliest 2024-01, latest 2025-12. Override with --from / --to.
+```
+
+```bash
+assurance check ~/invoices --expect numbered
+```
+```
+7 of 8 runs from inv_0001 to inv_0008 in invoices — not in this folder: INV-0006
+— Range inferred from filenames: earliest inv_0001, latest inv_0008. Override with --from / --to.
+```
+
+Monthly, quarterly, weekly, daily, numbered. That last line is the **derivation**: it prints with
+every ratio so you can disagree with the denominator, not just the result.
+
+### `assurance init` — did anything change underneath?
+
+```bash
+assurance init ~/thesis-data
+# ... weeks pass, several people touch the folder ...
+assurance check ~/thesis-data --against-baseline
+```
+
+## Exit codes
+
+| | |
+|---|---|
+| `0` | it checked, and either found no gap or wasn't asked to fail on one |
+| `1` | a finding: a gap with `--fail-on-gap`, a stale baseline, or **nothing it could check** |
+| `2` | could not run: bad path, unreadable list, unparseable JSON, a table where keys were expected |
+
+**"I couldn't check this" exits 1, not 0.** A folder whose filenames it can't parse must not look
+like a folder it checked and found whole.
+
+Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
+
+## It expects your files, not tidy ones
+
+- **Excel exports work.** UTF-8 BOM and CRLF are handled; a BOM used to glue itself to your first
+  key and report it as missing *and* unexpected in the same sentence
+- **Spaces, unicode and month words in filenames** — `Inventory Report August 2024.csv` parses
+- **`.xlsx`, and nested subfolders**
+- **A piped CSV is refused, not misread.** It names the column-picking command instead of quietly
+  admitting your header row as a key
+- **When it can't work out a series it says so**, rather than reporting an empty check as a pass
+
+## Use it for
+
+| | expected | found |
+|---|---|---|
+| **RAG** | documents the question spans | chunks retrieved |
+| **Code review in CI** | `git diff --name-only` | files reviewed |
+| **ETL / batch** | records or partitions declared | records or partitions loaded |
+| **Compliance** | controls in scope | controls with evidence |
+| **Research data** | the series you expect | what's actually in the folder |
+
+## What it won't do
+
+- **Invent your expected set.** `diff` takes your declaration; `check` derives one and prints how
+- **Send anything anywhere.** No network, no telemetry, no keys
+- **Guess.** A JSON object of id → metadata is refused, not interpreted
+
+## Family
+
+[assurance-core](https://pypi.org/project/assurance-core/) — the pure arithmetic, zero dependencies ·
+[assurance-mcp](https://pypi.org/project/assurance-mcp/) — the same checks as MCP tools
+
+Upstream is [I-Ops](https://i-ops.dev); this repo is a publication, never a source. Apache-2.0.

{assurance_cli-0.2.0 → assurance_cli-0.2.2}/assurance_cli.egg-info/requires.txt

@@ -1,4 +1,4 @@
-assurance-core>=0.3
+assurance-core>=0.3.2
 openpyxl>=3.1
 
 [dev]

{assurance_cli-0.2.0 → assurance_cli-0.2.2}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "assurance-cli"
-version = "0.2.0"
+version = "0.2.2"
 description = "CLI for folder assurance checks — coverage, staleness, and baselines."
 readme = "README.md"
 license = { text = "Apache-2.0" }
 authors = [{ name = "I-Ops Operations Intelligence, LLC", email = "hello@i-ops.dev" }]
 requires-python = ">=3.10"
 dependencies = [
-  "assurance-core>=0.3",
+  "assurance-core>=0.3.2",
   "openpyxl>=3.1",
 ]
 keywords = ["cli", "ai-agents", "governance", "auditing", "assurance", "reproducibility"]

{assurance_cli-0.2.0 → assurance_cli-0.2.2}/tests/test_cli.py

@@ -123,3 +123,34 @@ def test_mixed_series_folder_reports_none(tmp_path: Path):
         (root / name).write_text("v\n1\n", encoding="utf-8")
     result = check_coverage(str(root))
     assert "No dated or numbered series detected" in result["summary"]
+
+
+# --- "I could not check" must not exit like "I checked and it was fine" ---------------------------
+
+
+def test_a_folder_with_no_readable_series_is_a_finding(tmp_path: Path) -> None:
+    """Exit 0 here made an unparseable folder indistinguishable, to a CI job, from a whole one."""
+    for name in ("15.01.2024 shipment.csv", "Jan-24 summary.csv", "20240115_dump.csv"):
+        (tmp_path / name).write_text("a,b\n1,2\n", encoding="utf-8")
+
+    assert main(["check", str(tmp_path)]) == 1
+
+
+def test_the_nested_record_agrees_with_the_wrapper(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """The payload carried `complete: false` at the top and `complete: true` one level down, and an
+    integrator reading either one was reading a real field."""
+    (tmp_path / "Jan-24 summary.csv").write_text("a,b\n1,2\n", encoding="utf-8")
+
+    main(["check", str(tmp_path), "--json"])
+    payload = json.loads(capsys.readouterr().out)["coverage"]
+
+    assert payload["complete"] is False
+    assert payload["coverage"]["complete"] is False
+    assert payload["coverage"]["undetermined"]
+
+
+def test_a_folder_that_checks_out_still_exits_zero(monthly_folder: Path) -> None:
+    """The counterweight: the ordinary path must not start failing."""
+    assert main(["check", str(monthly_folder)]) == 0

{assurance_cli-0.2.0 → assurance_cli-0.2.2}/tests/test_setdiff.py

@@ -150,3 +150,89 @@ def test_an_error_is_printed_rather_than_swallowed(capsys: pytest.CaptureFixture
     captured = capsys.readouterr()
     assert captured.out.strip() == ""
     assert "folder does not exist" in captured.err
+
+
+# --- what an outsider's files actually look like --------------------------------------------------
+#
+# From the 2026-08-29 smoke test against fixtures nobody here designed against: Excel exports,
+# filenames with spaces, month words, six-digit purchase orders. Most of it worked. This did not.
+
+
+def test_a_byte_order_mark_does_not_change_what_a_key_is(tmp_path: Path) -> None:
+    """Excel writes CSV and TXT with a BOM by default. Read as plain utf-8 it glues U+FEFF to the
+    FIRST key, so `doc-1` came back reported as missing AND as unexpected in one sentence — a
+    confidently wrong answer, from the most common export path there is."""
+    listing = tmp_path / "keys.txt"
+    listing.write_bytes(b"\xef\xbb\xbfdoc-1\r\ndoc-2\r\ndoc-3\r\n")
+
+    assert read_keys(str(listing), label="--expected") == ["doc-1", "doc-2", "doc-3"]
+
+
+def test_a_bom_in_a_json_export_is_stripped_too(tmp_path: Path) -> None:
+    listing = tmp_path / "found.json"
+    listing.write_bytes(b'\xef\xbb\xbf["doc-1", "doc-2"]')
+
+    assert read_keys(str(listing), label="--found") == ["doc-1", "doc-2"]
+
+
+def test_the_bom_case_end_to_end_reports_one_gap_not_two_wrong_ones(tmp_path: Path) -> None:
+    listing = tmp_path / "keys.txt"
+    listing.write_bytes(b"\xef\xbb\xbfdoc-1\r\ndoc-2\r\ndoc-3\r\n")
+
+    payload = diff_sets(str(listing), "doc-1,doc-2")
+
+    assert payload["read"] == 2
+    assert [entry["key"] for entry in payload["missing"]] == ["doc-3"]
+    assert payload["unexpected"] == []
+
+
+def test_crlf_line_endings_do_not_become_part_of_the_key(tmp_path: Path) -> None:
+    listing = tmp_path / "keys.txt"
+    listing.write_bytes(b"doc-1\r\ndoc-2\r\n")
+
+    assert read_keys(str(listing), label="--expected") == ["doc-1", "doc-2"]
+
+
+def test_a_bom_arriving_on_stdin_is_stripped(monkeypatch: pytest.MonkeyPatch) -> None:
+    """`cat export.txt | assurance diff --found -` has no decode step to strip a BOM: `sys.stdin`
+    is already decoded, by the locale's plain utf-8. The README documents piping, so this path is
+    real and needs the per-key strip that `utf-8-sig` cannot reach."""
+    import io
+
+    monkeypatch.setattr("sys.stdin", io.StringIO("doc-1\ndoc-2\n"))
+
+    assert read_keys("-", label="--found") == ["doc-1", "doc-2"]
+
+
+def test_a_piped_csv_is_refused_rather_than_read_as_keys(tmp_path: Path) -> None:
+    """Piping a CSV is the obvious thing to try. Read line by line it produced a confident `0 of 3`
+    with the header row and two score columns admitted as keys."""
+    listing = tmp_path / "found.csv"
+    listing.write_text("doc_id,score\ndoc-1,0.9\ndoc-2,0.8\n", encoding="utf-8")
+
+    with pytest.raises(KeySpecError, match="comma-delimited table"):
+        read_keys(str(listing), label="--found")
+
+
+def test_the_refusal_names_the_command_that_fixes_it(tmp_path: Path) -> None:
+    listing = tmp_path / "found.tsv"
+    listing.write_text("doc_id\tscore\ndoc-1\t0.9\n", encoding="utf-8")
+
+    with pytest.raises(KeySpecError, match=r"cut -f1"):
+        read_keys(str(listing), label="--found")
+
+
+def test_a_key_that_merely_contains_a_comma_is_still_a_key(tmp_path: Path) -> None:
+    """The guard fires only when EVERY line has the SAME delimiter count — a table, not a
+    coincidence. A false refusal blocks a legitimate user, so it stays narrow."""
+    listing = tmp_path / "keys.txt"
+    listing.write_text("Smith, John\nDoe, Jane\nplain-key\n", encoding="utf-8")
+
+    assert read_keys(str(listing), label="--expected") == ["Smith, John", "Doe, Jane", "plain-key"]
+
+
+def test_a_single_line_is_never_a_table(tmp_path: Path) -> None:
+    listing = tmp_path / "keys.txt"
+    listing.write_text("a,b,c\n", encoding="utf-8")
+
+    assert read_keys(str(listing), label="--expected") == ["a,b,c"]

assurance_cli-0.2.0/PKG-INFO

@@ -1,158 +0,0 @@
-Metadata-Version: 2.4
-Name: assurance-cli
-Version: 0.2.0
-Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
-Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
-License: Apache-2.0
-Project-URL: Homepage, https://i-ops.dev
-Project-URL: Source, https://github.com/i-ops-hq/assurance-cli
-Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-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.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: assurance-core>=0.3
-Requires-Dist: openpyxl>=3.1
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Dynamic: license-file
-
-# assurance-cli
-
-[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
-[![Tests](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml)
-[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE)
-
-### Did the job cover everything it was supposed to cover?
-
-One command, one honest ratio, and an exit code your pipeline can act on. No model, no API key, no
-network call, nothing uploaded.
-
-```bash
-pip install assurance-cli
-```
-
-## `assurance diff` — coverage over any two sets
-
-The general form. Give it what a task **required** and what it **actually read**; it tells you the
-difference and exits non-zero on a gap. Keys are anything you can name.
-
-```bash
-# A retrieval agent: did the retriever see the whole question?
-assurance diff \
-  --expected corpus-for-this-question.txt \
-  --found    retrieved.json \
-  --scope "documents the question spans" \
-  --where "the retrieved set" \
-  --fail-on-gap
-```
-
-```
-2 of 5 documents the question spans — not in the retrieved set: doc-2, doc-3, doc-5
-also present and not expected: doc-9
-```
-
-That last line matters as much as the ratio: the retriever drew on a document the scope never
-allowed. It is reported, and it earns no credit against the denominator.
-
-**Inputs are whatever you already have** — a file with one key per line, a JSON array of strings or
-of objects with a `key`/`id`/`name`/`path` field, `-` for stdin, or a comma-separated list inline.
-
-```bash
-# Gate an agentic code review on having actually read the diff
-git diff --name-only origin/main...HEAD > changed.txt
-assurance diff --expected changed.txt --found reviewed.txt \
-  --scope "files changed in this pull request" --where "the review log" --fail-on-gap
-
-# Did the eval suite run every declared case?
-assurance diff --expected cases.json --found ran.json --scope "declared eval cases" --fail-on-gap
-
-# Were all the partitions loaded?
-aws s3 ls s3://lake/dt=2026-08-14/ | awk '{print $4}' > loaded.txt
-assurance diff --expected expected-partitions.txt --found loaded.txt --where "the warehouse"
-
-# Straight from a pipe
-retriever --query "$Q" --json | jq -r '.chunks[].doc_id' | \
-  assurance diff --expected corpus.txt --found - --json
-```
-
-`--json` gives you the full record for a CI artefact: `complete`, `read` of `required`, and each way
-an expectation failed to be evidence kept separate.
-
-## `assurance check` — coverage over a folder of dated files
-
-When the thing you must account for is a series on disk, the expected set is derived for you from the
-filenames. Monthly, quarterly, weekly, daily, or plain numbered.
-
-```bash
-assurance check ~/reports
-# 22 of 24 months from 01/2024 to 12/2025 in reports — not in this folder: 03/2025, 07/2025
-
-assurance check ~/reports --from 2024-01 --to 2025-12 --fail-on-gap
-assurance check ~/invoices --expect numbered          # gaps in INV-0001..INV-0450
-```
-
-The derivation is printed with the ratio, so you can disagree with the **denominator** rather than
-only with the result. That is deliberate: a denominator a tool invents for you is a denominator
-nobody can argue with.
-
-## `assurance init` / `--against-baseline` — did anything change underneath?
-
-Write a baseline of a folder, then ask later whether it still holds. Catches the file that was
-quietly replaced, the row count that moved, the figure that no longer matches its source.
-
-```bash
-assurance init ~/thesis-data
-# ... weeks pass, several people touch the folder ...
-assurance check ~/thesis-data --against-baseline
-```
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | Ran, and either found no gap or was not asked to fail on one |
-| `1` | A finding — a coverage gap with `--fail-on-gap`, or a baseline that no longer holds |
-| `2` | Could not run: bad path, unreadable key list, unparseable JSON |
-
-Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
-
-## Who this is for
-
-| If you run | Use it to check |
-|---|---|
-| RAG or retrieval pipelines | The retrieved set against the documents the question spans |
-| Agentic code review in CI | Files reviewed against `git diff --name-only` |
-| Batch or ETL jobs | Records processed against records declared |
-| Eval harnesses | Cases executed against cases declared |
-| Compliance evidence collection | Controls with evidence against controls in scope |
-| Research or thesis data | A folder that several people have been editing for months |
-| Any reporting series | Months, quarters, weeks, days, or invoice numbers with a hole in them |
-
-## What it will not do
-
-- **It will not invent your expected set.** `diff` takes your declaration; `check` derives one from
-  filenames and prints how. Both are arguable on purpose.
-- **It does not read file contents** except to profile a baseline you asked for.
-- **It never sends anything anywhere.** No network calls, no telemetry, no keys.
-- **No model decides any of it.** See [`assurance-core`](https://pypi.org/project/assurance-core/)
-  for the arithmetic; this package owns all filesystem I/O.
-
-## Also in this family
-
-- **[assurance-core](https://pypi.org/project/assurance-core/)** — the pure decision modules, zero dependencies
-- **[assurance-mcp](https://pypi.org/project/assurance-mcp/)** — the same checks as MCP tools any agent can call
-
-## Licence
-
-Apache-2.0. See [LICENSE](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE).
-Upstream is [I-Ops](https://i-ops.dev); this repo is a publication, never a source.

assurance_cli-0.2.0/README.md

@@ -1,131 +0,0 @@
-# assurance-cli
-
-[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
-[![Tests](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml)
-[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE)
-
-### Did the job cover everything it was supposed to cover?
-
-One command, one honest ratio, and an exit code your pipeline can act on. No model, no API key, no
-network call, nothing uploaded.
-
-```bash
-pip install assurance-cli
-```
-
-## `assurance diff` — coverage over any two sets
-
-The general form. Give it what a task **required** and what it **actually read**; it tells you the
-difference and exits non-zero on a gap. Keys are anything you can name.
-
-```bash
-# A retrieval agent: did the retriever see the whole question?
-assurance diff \
-  --expected corpus-for-this-question.txt \
-  --found    retrieved.json \
-  --scope "documents the question spans" \
-  --where "the retrieved set" \
-  --fail-on-gap
-```
-
-```
-2 of 5 documents the question spans — not in the retrieved set: doc-2, doc-3, doc-5
-also present and not expected: doc-9
-```
-
-That last line matters as much as the ratio: the retriever drew on a document the scope never
-allowed. It is reported, and it earns no credit against the denominator.
-
-**Inputs are whatever you already have** — a file with one key per line, a JSON array of strings or
-of objects with a `key`/`id`/`name`/`path` field, `-` for stdin, or a comma-separated list inline.
-
-```bash
-# Gate an agentic code review on having actually read the diff
-git diff --name-only origin/main...HEAD > changed.txt
-assurance diff --expected changed.txt --found reviewed.txt \
-  --scope "files changed in this pull request" --where "the review log" --fail-on-gap
-
-# Did the eval suite run every declared case?
-assurance diff --expected cases.json --found ran.json --scope "declared eval cases" --fail-on-gap
-
-# Were all the partitions loaded?
-aws s3 ls s3://lake/dt=2026-08-14/ | awk '{print $4}' > loaded.txt
-assurance diff --expected expected-partitions.txt --found loaded.txt --where "the warehouse"
-
-# Straight from a pipe
-retriever --query "$Q" --json | jq -r '.chunks[].doc_id' | \
-  assurance diff --expected corpus.txt --found - --json
-```
-
-`--json` gives you the full record for a CI artefact: `complete`, `read` of `required`, and each way
-an expectation failed to be evidence kept separate.
-
-## `assurance check` — coverage over a folder of dated files
-
-When the thing you must account for is a series on disk, the expected set is derived for you from the
-filenames. Monthly, quarterly, weekly, daily, or plain numbered.
-
-```bash
-assurance check ~/reports
-# 22 of 24 months from 01/2024 to 12/2025 in reports — not in this folder: 03/2025, 07/2025
-
-assurance check ~/reports --from 2024-01 --to 2025-12 --fail-on-gap
-assurance check ~/invoices --expect numbered          # gaps in INV-0001..INV-0450
-```
-
-The derivation is printed with the ratio, so you can disagree with the **denominator** rather than
-only with the result. That is deliberate: a denominator a tool invents for you is a denominator
-nobody can argue with.
-
-## `assurance init` / `--against-baseline` — did anything change underneath?
-
-Write a baseline of a folder, then ask later whether it still holds. Catches the file that was
-quietly replaced, the row count that moved, the figure that no longer matches its source.
-
-```bash
-assurance init ~/thesis-data
-# ... weeks pass, several people touch the folder ...
-assurance check ~/thesis-data --against-baseline
-```
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | Ran, and either found no gap or was not asked to fail on one |
-| `1` | A finding — a coverage gap with `--fail-on-gap`, or a baseline that no longer holds |
-| `2` | Could not run: bad path, unreadable key list, unparseable JSON |
-
-Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
-
-## Who this is for
-
-| If you run | Use it to check |
-|---|---|
-| RAG or retrieval pipelines | The retrieved set against the documents the question spans |
-| Agentic code review in CI | Files reviewed against `git diff --name-only` |
-| Batch or ETL jobs | Records processed against records declared |
-| Eval harnesses | Cases executed against cases declared |
-| Compliance evidence collection | Controls with evidence against controls in scope |
-| Research or thesis data | A folder that several people have been editing for months |
-| Any reporting series | Months, quarters, weeks, days, or invoice numbers with a hole in them |
-
-## What it will not do
-
-- **It will not invent your expected set.** `diff` takes your declaration; `check` derives one from
-  filenames and prints how. Both are arguable on purpose.
-- **It does not read file contents** except to profile a baseline you asked for.
-- **It never sends anything anywhere.** No network calls, no telemetry, no keys.
-- **No model decides any of it.** See [`assurance-core`](https://pypi.org/project/assurance-core/)
-  for the arithmetic; this package owns all filesystem I/O.
-
-## Also in this family
-
-- **[assurance-core](https://pypi.org/project/assurance-core/)** — the pure decision modules, zero dependencies
-- **[assurance-mcp](https://pypi.org/project/assurance-mcp/)** — the same checks as MCP tools any agent can call
-
-## Licence
-
-Apache-2.0. See [LICENSE](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE).
-Upstream is [I-Ops](https://i-ops.dev); this repo is a publication, never a source.

assurance_cli-0.2.0/assurance_cli.egg-info/PKG-INFO

@@ -1,158 +0,0 @@
-Metadata-Version: 2.4
-Name: assurance-cli
-Version: 0.2.0
-Summary: CLI for folder assurance checks — coverage, staleness, and baselines.
-Author-email: "I-Ops Operations Intelligence, LLC" <hello@i-ops.dev>
-License: Apache-2.0
-Project-URL: Homepage, https://i-ops.dev
-Project-URL: Source, https://github.com/i-ops-hq/assurance-cli
-Keywords: cli,ai-agents,governance,auditing,assurance,reproducibility
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-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.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: assurance-core>=0.3
-Requires-Dist: openpyxl>=3.1
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Dynamic: license-file
-
-# assurance-cli
-
-[![PyPI](https://img.shields.io/pypi/v/assurance-cli)](https://pypi.org/project/assurance-cli/)
-[![Tests](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/i-ops-hq/assurance-cli/actions/workflows/tests.yml)
-[![Python](https://img.shields.io/pypi/pyversions/assurance-cli)](https://pypi.org/project/assurance-cli/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE)
-
-### Did the job cover everything it was supposed to cover?
-
-One command, one honest ratio, and an exit code your pipeline can act on. No model, no API key, no
-network call, nothing uploaded.
-
-```bash
-pip install assurance-cli
-```
-
-## `assurance diff` — coverage over any two sets
-
-The general form. Give it what a task **required** and what it **actually read**; it tells you the
-difference and exits non-zero on a gap. Keys are anything you can name.
-
-```bash
-# A retrieval agent: did the retriever see the whole question?
-assurance diff \
-  --expected corpus-for-this-question.txt \
-  --found    retrieved.json \
-  --scope "documents the question spans" \
-  --where "the retrieved set" \
-  --fail-on-gap
-```
-
-```
-2 of 5 documents the question spans — not in the retrieved set: doc-2, doc-3, doc-5
-also present and not expected: doc-9
-```
-
-That last line matters as much as the ratio: the retriever drew on a document the scope never
-allowed. It is reported, and it earns no credit against the denominator.
-
-**Inputs are whatever you already have** — a file with one key per line, a JSON array of strings or
-of objects with a `key`/`id`/`name`/`path` field, `-` for stdin, or a comma-separated list inline.
-
-```bash
-# Gate an agentic code review on having actually read the diff
-git diff --name-only origin/main...HEAD > changed.txt
-assurance diff --expected changed.txt --found reviewed.txt \
-  --scope "files changed in this pull request" --where "the review log" --fail-on-gap
-
-# Did the eval suite run every declared case?
-assurance diff --expected cases.json --found ran.json --scope "declared eval cases" --fail-on-gap
-
-# Were all the partitions loaded?
-aws s3 ls s3://lake/dt=2026-08-14/ | awk '{print $4}' > loaded.txt
-assurance diff --expected expected-partitions.txt --found loaded.txt --where "the warehouse"
-
-# Straight from a pipe
-retriever --query "$Q" --json | jq -r '.chunks[].doc_id' | \
-  assurance diff --expected corpus.txt --found - --json
-```
-
-`--json` gives you the full record for a CI artefact: `complete`, `read` of `required`, and each way
-an expectation failed to be evidence kept separate.
-
-## `assurance check` — coverage over a folder of dated files
-
-When the thing you must account for is a series on disk, the expected set is derived for you from the
-filenames. Monthly, quarterly, weekly, daily, or plain numbered.
-
-```bash
-assurance check ~/reports
-# 22 of 24 months from 01/2024 to 12/2025 in reports — not in this folder: 03/2025, 07/2025
-
-assurance check ~/reports --from 2024-01 --to 2025-12 --fail-on-gap
-assurance check ~/invoices --expect numbered          # gaps in INV-0001..INV-0450
-```
-
-The derivation is printed with the ratio, so you can disagree with the **denominator** rather than
-only with the result. That is deliberate: a denominator a tool invents for you is a denominator
-nobody can argue with.
-
-## `assurance init` / `--against-baseline` — did anything change underneath?
-
-Write a baseline of a folder, then ask later whether it still holds. Catches the file that was
-quietly replaced, the row count that moved, the figure that no longer matches its source.
-
-```bash
-assurance init ~/thesis-data
-# ... weeks pass, several people touch the folder ...
-assurance check ~/thesis-data --against-baseline
-```
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | Ran, and either found no gap or was not asked to fail on one |
-| `1` | A finding — a coverage gap with `--fail-on-gap`, or a baseline that no longer holds |
-| `2` | Could not run: bad path, unreadable key list, unparseable JSON |
-
-Diagnostics go to **stderr**, results to **stdout**, so `--json` stays pipeable.
-
-## Who this is for
-
-| If you run | Use it to check |
-|---|---|
-| RAG or retrieval pipelines | The retrieved set against the documents the question spans |
-| Agentic code review in CI | Files reviewed against `git diff --name-only` |
-| Batch or ETL jobs | Records processed against records declared |
-| Eval harnesses | Cases executed against cases declared |
-| Compliance evidence collection | Controls with evidence against controls in scope |
-| Research or thesis data | A folder that several people have been editing for months |
-| Any reporting series | Months, quarters, weeks, days, or invoice numbers with a hole in them |
-
-## What it will not do
-
-- **It will not invent your expected set.** `diff` takes your declaration; `check` derives one from
-  filenames and prints how. Both are arguable on purpose.
-- **It does not read file contents** except to profile a baseline you asked for.
-- **It never sends anything anywhere.** No network calls, no telemetry, no keys.
-- **No model decides any of it.** See [`assurance-core`](https://pypi.org/project/assurance-core/)
-  for the arithmetic; this package owns all filesystem I/O.
-
-## Also in this family
-
-- **[assurance-core](https://pypi.org/project/assurance-core/)** — the pure decision modules, zero dependencies
-- **[assurance-mcp](https://pypi.org/project/assurance-mcp/)** — the same checks as MCP tools any agent can call
-
-## Licence
-
-Apache-2.0. See [LICENSE](https://github.com/i-ops-hq/assurance-cli/blob/main/LICENSE).
-Upstream is [I-Ops](https://i-ops.dev); this repo is a publication, never a source.