Task: Describe the design the journey landed

The journey document still describes the design that was rejected. It puts the request in ores.workflow as an instance that suspends and resumes, names five IAM request subjects that were never built, and lists seven gaps of which five are answered. Rewrite it around the design that was built: an approval request is its own record with a kind, ores.inbox holds the queue and the decision, and IAM holds only the detail of a role grant. State which gaps are closed and how, and which the two new tasks close.

• The document's Entities composed names the approval request, and not a workflow instance, as the request.
• The document's Operations and messages names the subjects that exist, and drops the five that were never built.
• Every one of the seven gaps is marked closed or open, and the one that is not fully closed says what is left and where it is captured.
• No credential field is named, and no subject is spelled in a form the entity protocol forbids.

The third criterion was amended. It read "the two open ones point at their tasks", which was true when gaps 4 and 7 were the open pair; both are now built, so the criterion states the rule instead of a count that has moved on.

The document is rewritten in place rather than replaced, because a user journey is a design document that outlives its sprint, and a reader arriving from the older text should be able to see what changed and why. Six sections move; the rest — the goal, the actors, the steps' ordering, the screens — stand, because the journey was right about what a person is trying to do and wrong only about what holds the waiting.

The design change is stated where it matters rather than assumed. The old text put the request in ores.workflow as an instance that suspends and resumes; the new text says why that turned out to be unnecessary, in the section that made the claim, so the two readings sit side by side. The same applies to the seven gaps: they are kept as a table with a state per gap, because two of them were closed by changing the design rather than by building what they asked for, and that is the part a future reader would otherwise have to reconstruct.

The subjects are replaced with the ones that exist, taken from the models rather than from memory: compass codegen generates every subject from a model, so the models are the source and the document cites them. Nothing is spelled in a form the protocol forbids, which is checked rather than asserted.

Every number this task claims about a tree, with the command that produced it and the commit it was measured at. A number without both is not a measurement, because a clean-up record describes a tree and trunk moves under a branch: a consumer count, a gate's component count and a suite's size all change with no code changing, and the reader of a bare number cannot tell which tree it came from. Where the raw output matters, put it in an evidence/ file beside the task and name that file in the Command column.

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.

The journey document now describes the design that was built, and every one of its seven gaps is marked.

Six sections moved. The request is an approval request in ores.inbox with a kind, a state and a deadline, and not a workflow instance; the paragraph that claimed otherwise now says where that claim came from and why it was unnecessary, so a reader from the older text can follow the change rather than notice a gap. The entities table names the request, its kind, its decision, the IAM detail behind it and the notification a person is given. The operations table names the subjects that exist, taken from the models that generate them.

The seven gaps are a table with a state each, because two of them were closed by changing the design rather than by building what they asked for. Gap 2 — the workflow engine cannot wait on a person — was answered by not needing the engine; gap 6 — no query returns a request as a row — was answered by making the request a table. Gap 7 is half closed: the deadline is built, and the reminder before it is not. That remainder is captured, and the document says why it is a different behaviour rather than a loose end.

Two things were decided while writing it. The document names the screens that were built, because a journey that names only wireframes leaves a reader unable to find the code. And the credential sentence was reworded to state the guarantee without listing the fields: the acceptance said no credential field is named, and the old sentence named four in order to exclude them.

The deadline task's work had to land first. Its subject, inbox.v1.ops.expire_overdue_approvals, and the two pages this document links to — Approval request expiry and the reminder capture — were not on main when this was written, and a dangling id link fails compass lint. So the branch was rebased onto that work once it merged and the links were added then, rather than the document shipping a subject it could not point at.