Make a recorded task readable: enforce data quality at the write path, and rebuild the record page around the reader

[FZ2000]

Supersedes #211, which is contained in this branch. Two halves that only work together: rules that make a record complete (#211) were never enough, because a complete record can still be meaningless — so this also makes the contract ask for meaning, and rebuilds the page that displays it.

Why

A reviewer using the app said: "noone will understand the page", "all of these are useless info". Measured on a real render, they were right. On task_5f7dbea9 the Usage+Recording tail was a near-constant ~1,250px regardless of how much work was done, and it broke down as:

	share of that tail
named absence	42.8%
restatement	25.5%
a raw task id	9.9%
structure	12.0%
actual new fact about the work	9.7%

Twelve statements, of which seven said "we don't know" and two repeated the title. The cause was structural: the page's sections were named after the receipt's own dimensions keys — Actions, Cost, Evidence, Gaps, Recording — so it faithfully reported what the recorder knew about its own recording.

The write path

A goal, at last. There was no goal field anywhere, so completed was unjudgeable: objectives is the list of section titles, which are steps, and on most records objectives[0] is the task title again. task_goal is recorded once on a task's first section. It is first-write-wins, unlike summary which is deliberately last-write-wins — a later section restating it must not redefine what the task was opened for. A task with none says so and never borrows a step title.

That chain broke in the middle once and nothing noticed: the MCP accepted it and the receipt read it off the work item, but WorkEvent dropped it in between. It is pinned end to end now, because only the whole chain is the behaviour.

summary asks for consequence. Its description said "lead with the result, not the process", which produced changelog entries. This one was fully compliant and the reviewer called it meaningless:

"Handing off with parenthesised negatives working and one case still red. ($12.34) and ($1,234.56) parse to the signed value… 6 of 7 parse tests pass…"

All mechanism, no purpose, no cost. The description now asks for the consequence first, with a worked weak-vs-strong contrast in the description itself. The description is the mechanism: across 38 live agent runs (below) no recording call was refused by a rule, and the records came back shaped by what the descriptions ask for. What an agent produces under the new description, reading only the tool descriptions:

"Do not point the importer at an export yet expecting one bad row to be skipped — it will abort the whole file. add(), subtract(), percentage()… let decimal.InvalidOperation escape while parse_amount() raises ValueError…"

Pre-rules history is accepted, not backfilled. Rules bind new writes; inventing summaries for work nobody remembers is fabrication. Those records are named as predating the rules rather than implied to be sloppy.

Prose is asked for and shown, never graded

An earlier revision of this branch also graded what agents wrote: 13 detectors over 119 hard-coded phrases decided whether a summary "stated an outcome" or "named a consequence", refused summaries under 40 characters, refused a check named e2e as "too generic", and picked which sentence of a check summary "is the finding". That layer is gone (7ad4c1a, −889 lines; semantic_rules.py 1,306 → 920, its only remaining regex strips control characters).

It was measured before it was removed. On 40 hand-labelled summaries from a real ledger the classifiers agreed with a human 25–50% of the time, against 88% for always answering "useful"; they would have attached an advisory to 94% of completed sections; they refused "Bumped requests to 2.32.3; CI green." while accepting "I did some work on this and then I finished doing it."; and they told honest review outcomes that they "described process". Nothing showed an advisory ever changing a later write.

Every structural rule stays — required fields, enums, path shape, the placeholder refusal, the file anchor — as do hygiene, the descriptions, and the structured fields. Two things the review found that a grep would not: the markdown renderer re-parsed the reducer's own attention label by word matching and ran the same matcher over titles agents wrote (it now splits on the payload's kind); and the old echo detector had been hiding a server artifact — released servers filled an omitted summary with the literal "<name>: <result>" — which is now inverted exactly, as the machine format it is.

Measured with real agents

benchmarks/agent_recording runs real headless agents (Claude Code and opencode verified; Codex and Gemini adapters written, unverified on this machine) in sandboxed repositories whose task never mentions recording, serves them one checkout's MCP server and instruction block, and grades the result twice: objectively, against the repository's diff and the harness's own run of the verification command; and with a blind judge on the four reader questions. --src points it at a different checkout, which is how the removal above was tested before and after.

The removal changed nothing agents record. Four of five scenarios score identically (read time 20.9s vs 21.0s); on the fifth the structured record is identical in all 12 runs, and the judge gap has no mechanism behind it and is within noise (3/6 vs 0/6, p≈0.18). Replayed over what the agent wrote under the old contract, the word lists would have told it to rewrite 4 of 8 summaries — including both correct "this is not a bug" conclusions, which the judge scored 6 and 7 of 8.

What it found instead is the real to-do list, and every item is about shaping the ask:

• A partial result is recorded as a success — 12 runs out of 12. Told not to edit vendor/, the agent monkeypatched the vendored function, then recorded completed, no failed check, no next_step. The record reads green over a red repository. The word lists never touched this.
• Checks are recorded when something is fixed, not when something is found. On "not a bug" and "blocked", the agent ran the tests or the script and did not record it.
• The title is frozen at started, before the outcome is known — "Fix is_business_day wrong for 2026-07-03" still heads a record whose conclusion is that nothing was wrong.
• files invites a false claim on work that changed nothing.

Three harness guards exist because live runs did what they guard against: PWD is set (opencode trusted the inherited one and first ran in the real repository, where it read the eval's ground truth — it changed nothing); verification ignores conftest.py; and off-limits paths are restored before reality is judged.

The page

Four sections, each answering a question a reviewer arrives with — what was this for / did it work / can I trust it / what do I do now.

	before	after
named absence	11.7% of page	1.9%
page height	7,270px	6,254px
HEAD when recorded:	4 prints, 2 values	2 group headers
the shared contradiction	3 byte-identical prints	1 banner
evidence tier	3 registers (prose, word, pip)	1

Passed. Exit 0. test. Agent-reported — four fragments punctuated as sentences — is one separated line. Summaries clipped at a character count, cutting exactly the clause carrying observed-vs-expected; they clip at a sentence boundary. Deleted: the five-tile strip (its SESSIONS tile read 1 on four of five records), the Usage and Recording headings, the WEEKLY PLAN and SOURCES rows, and the Recording ▸ TASK row that printed the title a third time.

Three latent CI failures this found, unrelated to the change

• A timezone bomb. The committed worked examples were generated in local time; CI's pytest job runs TZ=UTC. Green on a machine in the right zone, red in CI, with a diff (13:38→20:38) that reads like a data change. The generator now pins UTC — verified by generating from three zones and comparing checksums.
• A terminal-width bomb, found by CI on this branch and the same shape as the timezone one. At 80 columns now wrapped fresh tokens and cache-read tokens onto two lines each, and since rich bottom-aligns headers the last header line read tokens │ tokens — two adjacent columns named identically. The test guarding exactly this tried to pin its width with monkeypatch.setenv("COLUMNS", ...), which cannot work: rich reads COLUMNS once inside Console.__init__ and cli.console is built at import, so the pin was a silent no-op and the test really rendered at whatever width launched pytest. Green on every developer terminal, red in CI. Fixed in the renderer — both token columns and the money column are no_wrap, so the narrow case drops the redundant half (fresh toke…) instead of the informative one (tokens), and a starved money column can never render ≈$1,554… — and in the harness, where a conftest fixture pins the render width to 80. Before it, the suite failed 15 tests at 60 columns and 19 at 40; now 40, 80 and 200 return the same verdict.
• A stray MANIFEST.txt in the reference directory from an interrupted re-record, describing images that were discarded. It broke the promotion tool's inventory check; that check was right.

Verified

Every CI step run locally under CI's own environment (TZ=UTC, release config), because the failures on #267 all lived in shell and Python scripts swift test never executes.

pytest 4,899 passed, 1 skipped (the opt-in live eval) · swift test -c release 725 passed, 6 skipped · all four CI scripts pass · visual-snapshots verify matches · tree byte-clean afterwards, which is the property that actually failed before.

The 96 visual references, re-recorded

#267 made the six suites able to run, and running them showed the references were stale against every pane, not only this page: Metrics.pageMaxWidth caps pane content width, so Dashboard and Usage each moved 22–27% of pixels without being edited directly.

Re-recorded on a host matching the pinned axes, after first ruling out a regression — no Space/radius/Metrics constant changed value, and both size changes are explainable (menu 880→990 is the recent-sessions block plus a wrapped cost-basis legend; setup-failure 1028→1044 is one added line). Reviewed per suite rather than trusting the green verify, which the record script itself calls tautological.

The Work receipt reference is also the first end-to-end proof of the goal fix: the page renders Agent-reported · Review the generated PNG matrix where it used to say no goal was recorded — a field that had to survive four separate serializers to get there.

Known gaps, stated rather than hidden

• No exits exist. There is no commit, repo or PR URL anywhere on the payload, so what do I do now is the next step alone.
• Task identity is the client session, so one task can mix unrelated work under a single verdict.
• The absence budget is still 53% on a usage-only task — a task with no recorded work is honestly mostly absence, and that may be correct rather than broken.
• verify-fixes.py reads 29 of 30. The miss replays the recording machine's own live ledger against a <1% bar that predates its history (6.6% here, by the file-anchor rule and a few missing summaries); it fails identically without this branch's last changes, and REVIEW_GUIDE.md says so rather than the transcript claiming 30 of 30.
• The eval's numbers are a first reading: 38 runs, two agents, one judge model.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LJgWrWqv5QB2JbzLdx9JG4

[FZ2000]

Merged main into this branch to clear the conflict. Two things beyond the textual merge:

• PLATFORM.json: only the provenance stamp conflicted; kept main's, then re-recorded on the canonical renderer.
• Fixture lanes (ingestion_healthy_sources, ingestion_degraded): main added these Diagnostics lanes in fix(sources): report the store-wide reconciliation fault once, in plain words #294 without the reducer copy this branch introduces (state_title / state_detail), so after the merge every Sources row rendered "Source state not reported". Attached the reducer's copy to the two lanes with with_ingestion_state_copy (the daemon's own function) and re-recorded the four sources-*-reference images. Verified locally: visual-snapshots verify passes; pytest 4900 passed.

🤖 Generated with Claude Code