Reports — the narration becomes part of the board

A chapter report about the chapter that made chapter reports possible.

milestone ms-6f7a24 · five cards · four workers · branch ms/reports-the-narration-becomes-pa
written by agent:berna/close1 on tk-37ac05, 2026-08-10 · every figure below is re-derivable

What it set out to do

A report is the one artefact a machine cannot regenerate. A commit can be re-derived from a diff, a status from the log, a board from its events — but what an agent understood after a day of work exists once, and until this chapter it existed in a chat transcript that nobody would ever open again.

The chapter's goal was to give it the same standing a commit has, under one constraint that decided everything else: the log stores references and measures, never content. That rule already keeps patches out of events.jsonl — a commit is recorded as a sha and a numstat, and the reader goes to git for the bytes. Applied to prose it gives the whole design: the report is a file, committed; the board holds {path, title, milestone, sha}; and the reader renders it from its own clone.

Four acceptance criteria, and they are what the five cards were cut against:

1. one taskops_activity call returns spec, thread, commits with numstat, standing and merged_into for every card of a chapter, and since=<seq> returns only what moved;
2. a report registered on chapter X appears in the UI's list for X and renders from the local clone — while taskops serve still serves no UI and no report;
3. events.jsonl grows by less than 1KB per report, whatever the report's size;
4. a report carrying a <script> tag cannot read the dashboard's token.

What each card actually built

The decisions that were argued

The sandbox pair is not two permissions

A report is untrusted HTML somebody's agent wrote, and the dashboard's origin holds the token. An html report is read inside <iframe sandbox="allow-scripts" srcdoc=…>, and scripts run on purpose — a panorama report is a self-contained page with inline behaviour, and rendering it dead ships a broken document that looks fine. The question was never whether script runs; it is what the script can reach.

allow-scripts beside allow-same-origin is not a slightly wider sandbox. It is the absence of one: with both, the frame reads parent.localStorage, writes parent.document, and can strip its own sandbox attribute from the inside. Without allow-same-origin the frame is an opaque origin — no parent, no storage, no cookie, no form, no popup, no top navigation.

So the value is a module constant, not a prop: there is no argument a caller can pass to widen it. And the proof is not a well-behaved fixture. The test fixture commits a hostile report that reads the token out of parent.localStorage, overwrites parent.document.title, removes its own frame's sandbox attribute and POSTs the loot; the headless smoke section then asserts those exact bytes reach the parent document escaped inside an attribute, so the dashboard's own document contains no script element of the report's at all.

assert "allow-scripts" in app and "allow-same-origin" not in app

content_type is a field, never a header

The file door answers the same JSON envelope every other question answers, and it reports content_type as data: text/html only for a literal .html, otherwise text/plain. It is never set as the HTTP response header, and that is the point — the token lives in this origin, so no file may make this origin serve HTML. What to do with text/html is the reader's decision, taken in exactly one place. A text/plain report is therefore not framed at all: srcdoc parses as HTML, so text goes into a <pre> as a React text node, and there is no dangerouslySetInnerHTML anywhere in this dashboard.

Why filed is its own verb

Registration is an act, not a side effect of committing. A hook that noticed a file appear under .taskops/reports/ and registered it would be a Claude hook that decides and writes — the thing this project bans by name — and it would file every draft, every rename, every experiment. Committing prose is cheap; saying "this is the chapter's report" is a claim, and a claim gets a door with a refusal attached to it.

The refusal is the interesting half. under() never repairs a path — a traversal normalised into something acceptable is the bug, not the fix — and the refusal names the directory and shows the call that works:

'…' is not a report path — a report is a file COMMITTED under
.taskops/reports/ (no '..', no absolute path). Move it there, commit it,
and file it: filed path=".taskops/reports/<name>.md" title="…" sha=<the commit>

Nothing that can be derived is stored

There is no reports table and no column on Milestone. The list is a fold over the report events on every read, newest first, capped with its honest total beside it. A stored list would be a second fact somebody has to keep in step with the events that produced it, which is this project's oldest bug and has its own module docstring elsewhere.

What it cost, and what it bought

110 minutes of card time, one card at a time on the seam and three in parallel after it. The suite went from 468 to 485 passing. Every new module is inside the 200-line budget: core/reports.py 116, verbs/filed.py 114, verbs/activity.py 145, verbs/_stories.py 94, mcp/activity.py 131, http/gitdoor.py 188.

Against the criteria: (1) is taskops_activity, with its budget measured rather than asserted; (2) and (4) are pinned headlessly and at the byte level in the shipped bundle; (3) is one line — the log's size before and after a filed call, differing by under 1024 bytes for a report of any size — and it is a test, not a claim.

Writing this report took four taskops_card calls, one per card, because the tool that collapses them into one is the tool this chapter built and it is not reachable from the session that built it. That is the next section, and it is the most useful thing this exercise found.

What the dogfood found

What was verified for real, in this worktree, with no board involved: the file below is committed, and the /git file door reads it back at that commit through gitdoor.answer() — the same function the dashboard calls — returning the resolved 40-hex sha, content_type: text/html, truncated: false, and the bytes. The half of criterion 2 that is about the reader's own clone is therefore closed here; the half that is about the board's list is closed by one taskops_filed call in the next session.

One defect, found by the read itself and fixed

Reading this report back through the door turned up a copy-paste slip in gitwork/patch.py::show(): the git show <sha>:<path> line appeared twice, so every report read forked git twice and threw the first result away. Nothing was wrong with the answer, which is exactly why nothing caught it — the behaviour is identical, ruff sees a reassignment rather than an unused name, and pyright sees valid code. It took running the real door against a real committed file and looking at the function to notice. Removed in this close; the topology suite is unchanged and green either side of it.

The general form is worth keeping: a test suite proves the answer, and only exercising the thing proves the work done to produce it. That is an argument for the dogfood step, not against it.

Two smaller findings, flagged not fixed

• core/types.py is at exactly 200 lines. Zero headroom against the budget is a finding, not a pass — the next card that touches it has nowhere to put a line. Splitting it while two chapters were in flight over it would have been a conflict on purpose, so it was flagged during the chapter and is still flagged now: it wants a card of its own.
• The MCP handshake's INSTRUCTIONS does not mention the two new tools, and this close deliberately left it that way. The budget is a cliff, not a slope: the panorama gets whatever the protocol leaves under a 2900-character cap, and below 300 characters of room it is dropped whole. It currently has 1040 and is already being cut. INSTRUCTIONS is the role protocol — it names the tools a role can be refused — and neither new tool is either role's alone, while both arrive fully described through tools/list. Spending the panorama to repeat a description the host already has is a bad trade.

Where the pieces live

Re-derive anything above: uv run pytest · git diff --numstat 665e37b..a85182f · find src/taskops -name '*.py' -exec wc -l {} + | awk '$2!="total" && $1>=190'