It compares the work a project requires with the inspection records, documents and approvals actually captured, and decides whether the documentation package is ready for review under an explicit, versioned requirement pack. Every gap comes with its expected and observed values, what would resolve it, and the source rows it cites.
The expected work comes from an independently accepted scope, never from the records being checked: thirty-nine valid inspections cannot satisfy forty obligations. And a missing record proves nothing unless the capture is known to be complete, so the tool keeps an established failure apart from what the captured data cannot decide. Like the other tools in this shop, it has no model in it; the same inputs give the same answer, byte for byte.
The input is a captured snapshot: canonical CSV and JSON files, or a Quickbase export read through an explicit field mapping. The output is a JSON assessment, a self-contained HTML report with no scripts and no external requests, and a run manifest that records exactly which input bytes were read.
Every record can be well formed while an obligation has no inspection at all. The tool counts from the accepted scope outward, so a row that was never recorded still shows up as a gap.
Coverage is declared with a basis. If the capture was interrupted, a missing inspection is UNKNOWN, not FAIL — and the finding says what would resolve it.
An approval binds a specific inspection revision and the SHA-256 of specific evidence bytes. A photo replaced under the same revision label no longer has an approval, and the report shows both digests.
| OUTCOME | WHAT IT MEANS |
|---|---|
| PASS | The requirement holds in every completion of the captured data. |
| FAIL | It fails in every completion: an established defect. |
| UNKNOWN | The captured data cannot decide. The finding names what would. |
| NOT_EVALUATED | A prerequisite did not pass; blocked_by names it. |
Required findings roll up into BLOCKED (any FAIL), UNKNOWN, or READY_FOR_REVIEW. The last one is a statement about documentation for the captured snapshot. It is never approval, and never a judgment of physical inspection quality or compliance — the report says so on every page.
| CHECK | THE QUESTION |
|---|---|
| R0 input integrity | Duplicate keys, conflicting current revisions, invalid values, unsafe paths, dangling references? Defective rows are quarantined, never guessed. |
| R1 scope and coverage | Is there an accepted scope? How complete is each captured dataset, and on what basis? |
| R2 cardinality | Does each obligation have exactly one current, completed inspection? |
| R3 identity | Do the inspection and its documents name the obligation's project, asset and activity? |
| R4 required artifacts | Is there a current document of every kind the pack requires? |
| R5 availability | Can every required file be read and hashed — with exact-case resolution that behaves the same on every operating system? |
| R6 approval binding | Does the latest approval cover the current revision and the current evidence bytes? |
| R7 unmatched records | Are there current inspections outside the accepted scope? Advisory only. |
The adapter is built from Quickbase's published RESTful JSON API contract — the official OpenAPI document and the field-type pages — and maps by field ID, verified against the live field list, never by display label.
The client's allowlist holds four reads. A write or a delete cannot be issued, and the check runs before any I/O. The token is read only from the environment and redacted from every message, log and file.
Keyset pagination by Record ID#, per-page total accounting, and an interleaved second pass that catches any change made while other tables were being read. Only a read that passes all of it is declared complete.
A choice label missing from the mapping, or a value of an unexpected JSON type, becomes a visible UNMAPPED_VALUE finding. A Quickbase export normalizes to exactly the same identities as the equivalent canonical snapshot.
| STEP | WHAT IT PROVES | STATE |
|---|---|---|
| Export adapter | A Quickbase-shaped export normalizes to the canonical snapshot's exact identities | ✔ green |
| Capture client | Against a mock app built to the published contract: pagination, rate limits, retries, permission errors, schema drift, mid-capture changes, oversized files, token redaction | ✔ green |
| Live verification | A run against a real Quickbase test app, on 2026-10-09. In a free-trial realm, a separate, create-only builder made the test app through the API, with every field ID as mapped. The read-only capture paged by keyset, got 80 of 80 files and earned completeness on all three bases. The assessment matched the reference scenario finding for finding: READY_FOR_REVIEW, 207 of 207 PASS. | ✔ green |
This tool's status reads SOURCE rather than SHIPPED because v0.1.0 is a source release with no installable package: you run it from a clone with uv. The demonstration needs no account and no network.
The scenarios and their expected outcomes were written by hand from the specification before the engine existed, and re-derived independently in review. The tests never compute an expected verdict with the code under test.
| WHAT | MEASURED |
|---|---|
| The oracle | 24 of 24 scenarios match, in 5.3 s demo --all: every scenario assessed and checked against the hand-written expected status and every non-passing finding. |
| One assessment | 0.46 s for 40 obligations and 207 findings Scenario S02, wall clock including interpreter start. |
| The test suite | 896 passed, 1 skipped The skip needs a case-sensitive file system; it runs on Linux in CI. |
| Three operating systems | identical identities and report bytes CI runs Windows, macOS and Linux on Python 3.12 and 3.13, then compares every scenario's evaluation identity and report digest across all six. |
| Fault injection | 5 deliberate defects, each caught A test that cannot fail proves nothing; each injected defect must make its target scenarios fail. |
| Independent review | 7 review passes, 12 logged amendments Separate passes re-derived the oracle; read the engine, the adapters, the foundations and the outputs against the specification alone; ran a go/no-go on a fresh clone before publication; and attacked the test-app builder. Every confirmed code defect got a regression test that fails without its fix. |
Every command the guides annotate with an exit code runs in CI and must exit as printed, and the run-error catalog must list exactly the codes the tool can report. When the tool changes, a guide whose commands, codes or images drift fails the build.
For whoever runs an assessment and acts on the findings: reading the report, the four outcomes, the eight checks in plain language, comparing two runs, and a guided tour of six scenarios.
For whoever installs, configures and integrates it: requirement packs, the snapshot format, the Quickbase mapping and capture, the security model, provenance, and every exit and run-error code.
The report a person reads and the JSON an agent parses are the same findings: assessment.json carries every finding with its key, outcome, reason, expected and observed values and source locators, and the exit code carries the status.
uv run inspection-reconcile demo --all --out out/demo 24 scenarios against the oracle
uv run inspection-reconcile assess --snapshot DIR --policy FILE --out DIR
exit 0 READY_FOR_REVIEW · 10 BLOCKED · 11 UNKNOWN
uv run inspection-reconcile compare --before A --after B --out diff.json
what changed, finding by finding
uv run inspection-reconcile capture-quickbase --config FILE --mapping FILE --out DIR
read-only; the token comes from the environment
Two runs over the same inputs give byte-identical outputs, and the evaluation identity changes only when the semantic inputs do — so a finding's key is stable enough to diff, to file, and to quote back.