reconcile: two facts on every card, the result and the fix (ACE-127)

[sandeep-agami]

Spec: ACE-127 (agami-sdlc main, projects/agami-core-extension/specs/reconcile-evidence/ACE-127-result-and-fix.md)

Do not merge without manual review. Stacked on #307 (ACE-126); merge bottom-up: #288 → … → #305 → #307 → this.

Why

Sandeep: "if the data matches, but query is different - should we show as match but have a tag as different query?" and then: "There are two dimensions - 1/ result of reconciliation - Should we distinguish between Data and SQL Match, Data Match+SQL mismatch, Partial Data Mismatch (missing columns), Data and SQL mismatch, 2/ suggested fix - query fix, semantic model fix, prompt fix examples fix etc." One pill mixed "did the data match" with "can we keep it", the owner tag mixed "who acts" with "what kind of fix", and a query written differently from agami's made a matching row read "matches, unverified" and blocked the keep offer.

What changes

result, two facts read by code on every item

• data: matches, partly, differs, could_not_compare. From the number diff or the table comparison; partly when rows and values agree on the shared columns and only the column sets differ.
• query: same, different, not_comparable. From the seven claims, plus the projection: two queries that return different columns are different queries.
• label, plain words from the pair: match; same answer, different query; same rows, different columns; different answer; same query, different answer; could not run. unchecked counts the checks on your query that could not run and is shown as a tag, not a status. differs_in names the claims that differ.

fix, in order of precedence

fix	when
your query	the ledger proved a part wrong, or your query returns columns the question did not ask for
the semantic model	a measured gap: value list, filter, relationship, metric
the question	a doubtful fit (a query that may not answer its question is never the example to teach), or the two queries read the question differently with nothing behind it
the examples	your query passed every check, no gap, and agami still wrote a different query; a prompt example is the lever
agami again	a failed run, or the same query giving a different answer
nothing	both facts match, or a cosmetic difference (ordering, limit)

The ledger. A claim that differs between the two queries is noted (kind different_query), never unresolved: a matching answer with a different query stays match and reaches the keep offer. It is the best test the run can write: two independent formulations vouch for the answer key.

The page. The result label is the pill, colored by the data fact (amber for a match by a different query), with an "n checks not run" tag; the fix sits on the action line and as filter chips; a row of result counts under the status chips; the suggested decision follows the fix (examples → keep where allowed, else change). Older items files without the two fields render as before.

Second commit (0e07e92). A doubtful fit outranks the examples fix: a query that may not answer its question is never the example to teach, however the data fell; the fix is the question. The precedence in the spec is updated to match.

Third commit. The result chips are filters (toggles that narrow the cards) and replace the older status chips when result labels exist; each filter row is labelled Result, Fix, Find; the reset reads "Clear filters"; the examples fix reads "add an example". After Sandeep: "these pill filters dont' seem to be working" and "should there be labels for each row of filters".

Fourth commit (bdf0edc). The third commit's result-chips block read a variable before its declaration and left the page blank on load; fixed, and tests/test_reconcile_pages_load_in_node.py now runs every page's script to the end of its load path under Node with a stub document (skipped where Node is not installed), so a load-time reference error becomes a test failure. That closes the gap the review round named: the page JavaScript had no behavioural test.

Unchanged. The five internal status words keep driving the chat counts, the chunk progress line and the keep gate; the parser is untouched.

Tests

• New tests/test_reconcile_result_and_fix.py: every result label with its fix over ten records, the sentence clauses, keep on a cosmetic difference, the unchecked count, and the ledger's noted claim. Renderer tests for the two fields' validation, the pills and the fallback. Pins on the ledger rule, the skill's items step and the status table. 369 tests green across the reconcile suites.
• Full uv run dev.py check on the final commit (bdf0edc): ruff clean, vendored library in sync, 5873 passed, 12 skipped, 1 failed, the failure being tests/test_golden_run.py::test_a_client_that_cannot_be_found_still_fails_as_a_generation, the known local failure on this machine. The Node smoke test ran (Node is installed here).

History note (review round). The gallery's staging folder (.artifact-stage/, generated pages over synthetic data) had been committed into the second commit by mistake, 2,881 lines that do not belong in the repo. Removed from that commit and the branch force-pushed with lease; every other commit is unchanged in content. #310 was replayed on top.

Rebase note (2026-09-13). Replayed onto main at 99e44a8 with every branch below it; content unchanged, force-pushed with lease.

🤖 Generated with Claude Code