Task: Document the reports and the report workflow

A reader can find one page per report, one page for the report execution workflow, and architecture pages that agree with the code. The report document type carries the sections an individual report needs: purpose, audience, frequency, the ORE XML that configures it, and its inputs and outputs.

• The report document type is registered in codegen and in compass, with a contract page and a generated scaffold.
• A report inventory lists the documented reports, and at least one report is documented end to end.
• The report execution workflow has a workflow page with every required section, an interaction diagram, and a row in the workflow inventory.
• The reporting architecture pages state the two run chains and name-addressed step results, and the analysis records where reporting does not meet the engine guarantees.

1. Read the three clusters and verify the code each page describes, claim by claim. Four read-only surveys ran in parallel, one per cluster plus one for the report enumerations, and then every claim this task acts on was verified directly in the tree.
2. Add the report document type: the template, its registration in codegen and compass, the contract page, the glossary entry, the taxonomy row, the recipe section, the generator document, the regulatory-function row, the regenerated skill table, and a test suite.
3. Add the report inventory and two report pages, scaffolded through the new verb rather than written by hand.
4. Add the report execution workflow page, its interaction diagram, and its row in the workflow inventory.
5. Correct the four places where a page contradicted the code, and re-render the three diagrams that carried the same claims.
6. Record the analysis as an investigation, and state the idempotency, warning and deadline findings on the pages that own them.
7. Run the lint, the generator checks and the codegen suite, then open the PR.

The plan is unchanged from what was agreed before work started, except that the report pages number two rather than one: the test report the sibling story needs is a report page too, and documenting only a production report would have left the framework's second use case untested.

The commit column names the tree the numbers describe, which is the tree the branch started from. The suite size in the final run is on the PR.

• The analysis is Does reporting use what the workflow engine guarantees?. It found that reporting does not use three of the engine's guarantees: the idempotency check, the warning outcome, and a step deadline. The first is a correctness defect that restart recovery creates, and it is recorded on Define and enforce the orchestration contract.
• The report pages are written from the report's definition and its ORE configuration, not from a run. Neither report has been run yet, and the pages say so where it matters: the smoke test's * Test coverage names the four-step chain it will run, and the production report's * Outputs states that the result store is not built.
• The three report enumerations in the tree do not agree: 22 business reports on the risk reporting page, 31 operational definitions in the seed, and 35 ORE analytic types in the schema-derived taxonomy. The inventory states which is which rather than merging them.

Manual QA scenarios (scaffolded via compass add test_scenario) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

Delivered in PR #2344, all checks green.

The analysis. Running alongside the documentation work, it answered the story's question about whether reporting uses what the workflow engine offers. It does not, in three places. No handler uses the engine's idempotency check, so a run recovered after a restart repeats the work of every phase it re-dispatches, and assemble_bundle writes a second bundle row. No handler answers with warnings, and adopting them would also change failure behaviour, because the engine does not compensate a warned step. And no phase has a deadline, because the engine has none, so a silent phase needs a person. The analysis also found that the engine has no failure-policy field, so the compensate-or-stop choice the workflow pages describe is documentation rather than a mechanism. It is recorded as Does reporting use what the workflow engine guarantees?, and the story now starts the orchestration contract at the idempotency check.

The documents. The report document type exists, with its contract page, its registration in codegen and compass, its place in the taxonomy, the glossary and the recipe, and twelve generator cases. The report inventory and two report pages went in with it: Headline Position as a production report, and the sample bundle smoke test as the report the ACME story needs. The report execution workflow now has a page with every section its type requires, an interaction diagram, and a row in the workflow inventory.

The correction. Four statements on three pages described a system the code no longer has, and three diagrams carried the same claims. The pipeline page said a run is six phases with no chain selection; the orchestration page said the phase builder ignores its inputs; the scheduling page said the scheduler publishes the workflow start itself and derives the run's identity from a firing. The interfaces page named six subjects that do not exist, which is the correction that mattered most, because it is the page an implementer works from.

Two findings were recorded rather than fixed, because both are code rather than documentation and neither is in this task's scope: the idempotency gap above, and that neither bulk read filters by the run's scope beyond the trades call's book list, so a report narrower than its tenant exports the tenant's data.

The review. Six comments came back, all minor. Five were accepted and fixed: the report-code expression is split so its precedence is not something a reader has to parse, the code is now validated as a key, the scaffold helper asserts exactly which file it wrote, the test reads the glossary id instead of pinning it, and the idempotency gap now has a task of its own rather than living only on the investigation. The sixth, about the template's GENERATED FILE header, is answered rather than changed: no such source exists for any of the 144 templates, and doc_generator.md now states which of them are tangled and which are maintained in place. The table above records the decision on each.