Worked example: a fictional export decision with an auditable handoff

@gram 2
doc blog-decision-handoff
t Worked example: a fictional export decision with an auditable handoff
d A fictional task demonstrates linking decision, risk, evidence and source records before handing work to another agent.
tag examples
view document

::rich
# Scenario (fictional)

Northstar Cooperative is an invented organization. Its team is deciding how to share a maintenance handoff with an external reviewer. This scenario and every result below are fictional; they are not a Thegram customer, deployment, or performance report. The team needs enough context for review while avoiding accidental disclosure of a private working file.

## Decision and records

**Decision:** create a minimal redacted copy of `handoff.gram` for the reviewer, rather than upload the original file. The fictional reviewer only needs the accepted decision, test evidence, and the next owner’s task. The source document includes unrelated internal notes, so the owner keeps it local and creates a separate copy after reviewing every record and relationship.

The evidence record says the owner reopened the redacted copy and confirmed that it contains the decision, one supporting test result, and no unrelated note. The risk record identifies a possible missed relationship that could reintroduce sensitive context. A review task asks a second person to compare the copy with the intended scope before sending. The source record points to the format and renderer API documentation, because the team is comparing a file-centered share with an ephemeral browser render. Links are explicit: evidence supports the decision; the risk blocks the decision from being handed off until review; source supports the boundary explanation.

A simplified fictional record relationship is:

```text
D redacted-copy
t Share a reviewed redacted copy
x proposed

E reopened-copy
t Reopened the fictional redacted copy
supports redacted-copy

X missed-link
t A retained link might expose unrelated context
blocks redacted-copy

T second-review
t Have a second person compare scope
x open
```

These values are examples only. In a real file, the person creating a record would describe observed evidence, link to the appropriate source record, and let Core write revision provenance. They would not invent a recorded timestamp, runtime actor, or chain hash in authored prose.

## Action sequence

1. Identify the canonical source file and do not overwrite it with a redacted export.
2. Create a copy with a clear document identity; inspect all records, rich blocks, references, and links, not only visible prose.
3. Add separate decision, evidence, risk, and task records. Use `supports` from evidence to decision, and `blocks` from the risk to the task or release condition as appropriate.
4. Ask a second reviewer to inspect the exact outgoing copy and verify that links and referenced sources stay within the approved scope.
5. Only after that check, deliver the specific copy through the channel authorized by the owner. If using a web renderer, remember it receives the bytes and is not durable storage.

## Tradeoffs and boundary

A copy reduces the chance of disclosing unrelated notes, but creates a second artifact that can become stale. The task and relationships make that cost visible: record which source revision was used and update the copy deliberately if the decision changes. A link to a browser view would not create a persistent document library. The example does not make a security guarantee; it demonstrates how to expose a risk and make a human check part of a decision.

## Next-agent prompt

> Inspect the fictional `handoff.gram` export without editing the canonical source. Verify every record, rich block, relation, and external reference against the intended reviewer scope. Report which records are included, which could expose unrelated information, and whether the second-review task is satisfied. If ambiguity remains, stop before delivery and name the exact unresolved relationship. Do not claim transmission, publication, or approval unless the owner explicitly authorizes it.

## Further reading

Use the format language guide for record and relation syntax, the renderer API for what a browser submission does, and the owning storage/service contract for any account-backed share. This example is intentionally fictional and demonstrates structure, not product usage evidence.
::end

SRC language-spec
d Internal source reviewed at revision 625edecee877ddf5f6c303cb478c64fa4cbca651 on branch main (spec/language.md); not publicly available.
t .gram record and relation syntax
SRC renderer-api
d Internal source reviewed at revision 971a0474fb4b97c3d23d6687be80664461f43a2f (main: docs/api.md); not publicly available.
t Web renderer API and submission boundary
SRC vault-spec
d Internal source reviewed at revision a193a190141054e07b268f0a38489467db82a335 (master: docs/SPEC.md); not publicly available.
t Vault storage and authorization contract
D redact-choice
x proposed
t Share reviewed redacted copy
d Northstar Cooperative is fictional; share only a separate copy after intended scope is verified.
source language-spec
source renderer-api
source vault-spec
E fictional-evidence
x observed
t Fictional copy reopened and checked
d In the invented scenario, the copy contains only the chosen decision, test, and next task.
source language-spec
supports redact-choice
X missed-link-risk
x open
t A retained relation may expose unrelated notes
d Fictional Northstar risk: a visible prose review can miss context reachable through an explicit relation or reference.
source renderer-api
blocks redact-choice
T second-review-task
x open
t Compare every outgoing record and link
d Fictional Northstar task: a second reviewer checks the exact export copy before authorized delivery.
source renderer-api
depends redact-choice