[Alex-lop]

Title

docs: rewrite README in customer voice — what it does, what it never does, the tests behind each claim

Body

What changed

README.md is rewritten from 185 lines of judge-facing prose to 88 lines aimed at
the person who would actually install this: someone who owns an internal agent
platform and needs a boundary between coding agents and company data.

• Line 1 states the job and the mechanism — lease, a value-level screen on every
  model-bound and browser-bound payload, suspension of only the intersecting capability
  — and what it never does: no tool takes arbitrary SQL or a generic mutation, no client
  approves its own work, and a screened payload is refused whole when a value matches an
  identifier shape the screen knows (email, US SSN, US phone, hmac-sha256: join token)
  or its key or field path is one the MCP screen or the approved plan denies. The screen
  is a shape-and-name allowlist, not a judgement about meaning, and "What it does not do"
  now says so and names where it is not wired.
• Install plus one runnable block. uv sync --frozen and a nine-line snippet that
  releases an aggregate and refuses a payload carrying an email address. The output in
  the README is the output that command printed here on 2026-08-31, and test_readme_truth
  re-executes the block on every run. Commands are written the way the rest of the repo
  invokes them, uv run --frozen python -m reglineage ... — there is no reglineage console script.
• "What it does" is an eight-row table: capability → the command or API → the test
  file that proves it. Nothing is claimed that a test does not cover.
• "What it does not do" states the demo-only half plainly: the 70-line PDF
  extractor that finds one section between two literal markers, no obligation
  extractor, no authentication anywhere, nothing deployed and no second user, replayed
  historical data rather than live traffic, NOT_RUN for actual Claude Code / Codex
  invocation, twelve tests that skip without a live DataHub, and no legal claim.
• "Evidence" compresses the old proof tables to three rows and links the raw JSON and
  the generated report instead of restating them. Every row is a count re-measured on this
  branch and read back from the artifact that produced it; the header says which suites CI
  runs and marks the rest local only. No latency figure and no functional hash is pasted:
  the digest folds in the commit under test (scripts/benchmark_north_star.py:960 feeds candidate_commit into the projection functional_hash digests at :1014)
  and would be wrong at the next commit, and wall-clock timing moves run to run on one
  machine (four runs here gave medians 4.906 / 4.446 / 4.564 / 4.850 ms and maxima 6.065 / 4.870 / 5.587 / 89.283 ms), so it is left
  in the linked JSON where its run and machine are recorded.
• Deleted: the truth-label taxonomy tables, the 22-step transcript, the "what the
  control loop proves" essay, the judge-guide links, and every superlative without a
  measurement behind it. The legacy fitness fixture keeps the exact sentences the
  submission-contract test asserts on, moved under "What it does not do" where it
  belongs.

Why

STRENGTHS.md names the defect directly: "Prose for judges, not customers. Every
README needs a rewrite of the top-of-funnel voice." ASSETS.md §2 draws the honest
split this rewrite respects — the lease runtime, both egress firewalls, the zero-dep
MCP server, the impact assessor and the validators are real; the regulatory-text
extraction is not, and the README no longer implies otherwise.

Tests run (worktree, uv sync --frozen, Python 3.11.15, macOS, acryl-datahub 1.5.0.6)

Suite	Result
tests/unit (includes the new test_readme_truth.py)	234 passed
tests/capability (includes test_phase3a_submission_contract.py, the existing doc-truth test)	36 passed
tests/e2e	3 passed
tests/mcp_runtime	14 passed
tests/monitoring	32 passed
tests/replay	26 passed
tests/integration	81 run, 69 passed, 12 skipped (need a live DataHub GMS or an opt-in provider key)
scripts/benchmark_north_star.py, run twice with --compare-output at this commit	claim gate PASS; 24 fault cases, 30 timing runs, 5/5 repairs, 12/12 release targets at 0 violations; functional hash identical across both runs; publication readback 13 entities, 5 memberships, 11 dataset-lineage edges, 20 field-lineage mappings, 5 Context Documents, manifest equal to a fresh readback. The digest is commit-bound, so it is quoted neither here nor in the README; re-run the pair on any commit and the two runs match each other
ruff check (pinned 0.14.0, default rules — the repo has no ruff config and CI does not run it)	new file clean; 25 pre-existing findings elsewhere left untouched
Every command the README prints	install block reproduces its pasted output byte-for-byte; uv run --frozen python -m reglineage mcp stops at RuntimeError: REGLINEAGE_TAXI_STAGE_PATH is required, as its parenthetical now says; approve --help and publish --help print their usage

The new test executes the README's console block and asserts its output equals the block
pasted below it, asserts every relative link resolves, and reads every counted claim back
from what produced it: len(server._FORBIDDEN_KEYS), len(server.TOOLS),
len(server.SUPPORTED_VERSIONS) and len(LeaseState) from the code, and the claim-gate,
release-target and publication counts from evidence/north-star/agent-06-benchmark.json.
Two further tests fail if a functional hash is ever pasted back into the README, or if a
millisecond figure appears that the committed benchmark did not measure. All six live in
tests/unit, which CI already discovers.

Review fixes applied to this branch

Finding	Fix
reglineage mcp / approve / publish name an executable that does not exist	Written as uv run --frozen python -m reglineage …, the form the install block uses; verified by running all three
A functional hash was pasted that belonged to an earlier commit, not the branch	Digits dropped — the hash folds in candidate_commit, so any pasted value is wrong one commit later; the README claims the match, and a doc-truth test keeps a digest from coming back
Evidence table mixed base-commit and HEAD provenance under one header	Every row re-measured on this branch; the header no longer names the base commit
Lede and row 1 promised that no identifier, secret or suppressed value ever crosses	Both scoped to the shapes and names the code actually matches, plus a "What it does not do" bullet naming what is not covered and the boundaries where the screen is not wired
Timing row was a single unreproducible observation under a "Reproduced" header	Row deleted in round 2 — see below
"a value-level screen on everything that leaves"	"on every model-bound and browser-bound payload", matching the module docstring
CI badge alt text claimed offline test status for suites CI never runs	Retitled "unit / capability / e2e test status"; the Evidence table says CI runs 273 of the 426 tests and marks the rest local only
Line 70 contradicted line 64 about the suite running offline	"apart from the twelve live-integration tests"
Doc-truth test guarded only the console block and links	Extended to the counted claims, as above

Round 2 review fixes

Finding	Fix
blocker — the timing row published median 8.178 / p95 16.510 / max 18.759 ms, figures with no source in the repo that contradicted the benchmark JSON they were attributed to (4.277729 / 4.672041 / 4.729583)	Row deleted. Four fresh runs here on 2026-08-31 gave medians 4.906 / 4.446 / 4.564 / 4.850 ms and maxima 6.065 / 4.870 / 5.587 / 89.283 ms event-to-enforcement — nothing near the published digits, and a spread wide enough that no single observation is worth publishing; timing stays in the linked JSON, which records the run and machine that produced it. tests/unit/test_readme_truth.py::test_no_unmeasured_latency_is_pasted now fails on any millisecond figure the committed benchmark did not measure
The "committed from an earlier candidate commit" caveat covered only the generated report, while the JSON beside it came from the same stale commit	Caveat moved to cover both: "both committed from an earlier candidate commit; the counts above were re-run on this branch"
uv run python -m reglineage mcp traceback-fails as printed and was the only command missing --frozen	Now uv run --frozen python -m reglineage mcp (needs REGLINEAGE_TAXI_STAGE_PATH pointing at a provisioned taxi cache stage); the approve / publish row takes --frozen too
Two items on ASSETS.md §2's demo list were missing from "What it does not do"	New bullet: the reviewed draft is a seeded-defect fixture (src/reglineage/workflow/draft.py) and the compiler returns one hardcoded SQL statement for the single registered fitness analysis (src/reglineage/analytics/compiler.py)
The governance-polling row cited 32 tests that all run against InMemoryMonitoringDataHub	Row now says the impact computation is proven against the in-memory catalog twin, since live GMS polling runs only in the tests that skip offline
Adding a test moved the totals	426 tests, 414 pass, 12 skipped; CI runs 273 of them

AI assistance disclosure

This branch was written by an AI agent (Claude Code, model Opus 5) working from
venture/CLAUDE.md, ASSETS.md §2 and STRENGTHS.md. Every claim in the README was
checked against the code or a command run in this worktree; the console output and the
benchmark figures are pasted from runs made here, not reproduced from memory. A human
should read the README once before this is merged.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 69587dd4-1bad-462f-9ef0-724916f5cd71

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}