Citations to confirm

​

For

A citation belongs to one revision of an entity. An edit gives the entity a new revision, and that revision starts with no citations of its own. Penumbra then checks each citation of the earlier revision against the edit. A citation that still holds moves to the new revision. A citation that may not hold waits for an answer, and it stays off the new revision until someone answers. Each waiting citation asks one question: does this text still support the entity? The answers are keep, change back, and true before the edit. Nothing deletes a citation or a File. This queue is where edits meet sources. A passage supports an entity through its citation (card Passage and citation). An edit to the entity, directly or in a workspace (card Entity, card Workspace), may leave that support in doubt. The queue keeps the entity honest about what it still stands on.

​

Use when

• You updated or restored an entity, and it had citations.
• You submitted a workspace that changed entities you checked out.
• The person asks what still waits to be confirmed.
• An entity shows fewer citations than it had before your edit.

​

Not this

• You stage a new entity and cite a passage for it: use card Passage and citation.
• You need every entity that rests on an old edition of a File: use recipe find-stale-entities.

​

Rules

1. citations-to-confirm.1 An edit of an entity or relationship that had citations queues a check of them. An update, a restore and a workspace submit of checked-out items all do. A delete queues one that Penumbra then skips. A first write queues none. Your job: after such an edit, look for waiting citations. penumbra attention counts the sources to confirm, and penumbra evidence list shows them.
2. citations-to-confirm.2 A citation that waits is not on the new revision. Only citations that still hold are carried over. Your job: do not read a shorter list of citations as a lost source. On MCP, the entity read counts the waiting ones and lists them apart.
3. citations-to-confirm.3 When Penumbra cannot check a citation, it marks the citation unchecked, and it waits like any other. Your job: compare the cited text with the edit yourself before you answer.
4. citations-to-confirm.4 Read each item before you answer it. Your job: run penumbra evidence list. Each item shows the entity, what changed, who edited it and when. It also shows the cited text and its File, why it was flagged, and the open answers. Add --resolved for answered items, and --limit or --cursor to page.
5. citations-to-confirm.5 Three answers exist, one command each. penumbra evidence keep says the text still supports the entity as it is now. penumbra evidence true-then says it was true before the edit, so it stays with the earlier revision only. penumbra evidence change-back says the edit was wrong. Your job: open the entity and the File version, and compare before you answer. An answer takes effect at once and waits for no approval.
6. citations-to-confirm.6 Change back is open only when the cited text states the earlier value of a field the edit changed. Enforced: otherwise the CLI refuses it with evidence_review_change_back_unavailable, and the MCP tool answers change_back_unavailable. If the entity changed again, the CLI refuses with evidence_review_record_changed, and the MCP tool answers record_changed. Nothing is applied. List again, then decide on the current entity.
7. citations-to-confirm.7 A first answer stands. Enforced: answering a citation again returns the first answer, marked as answered earlier. A citation that needs no answer is refused with not_flagged.
8. citations-to-confirm.8 One call answers up to 100 citations, and you name each verdict ID once. Enforced: the three answer commands refuse a longer list or a repeated ID with invalid_arguments.
9. citations-to-confirm.9 Change back puts the earlier values back with an ordinary update made as you. It can settle more citations than you named. If the entity then equals the revision they were written for, the other waiting citations of that edit are settled the same way. Your job: read the full result before you list again.
10. citations-to-confirm.10 Answering needs permission to change entities: an owner, admin or editor, or a key with graph.lifecycle.apply. A viewer can read the flags but not answer them. Enforced: a person limited to a View sees no queue. Your job: ask an owner or editor to answer when you cannot.
11. citations-to-confirm.11 To cite the new value of an entity in a workspace, check the entity out and give the edit with its citations. Your job: the citations you give replace the pending list, and leaving them out makes no new claim. Earlier citations stay on the earlier revision (card Entity).
12. citations-to-confirm.12 A File that Penumbra writes (card file) cannot be cited. Enforced: keep and change back refuse a citation of such a File with file_not_evidence. Your job: answer with penumbra evidence true-then instead, or cite a File that was uploaded or synced (card Passage and citation).

​

Failure signs

• An edited entity shows fewer citations than before: rule citations-to-confirm.2.
• An answer is refused with evidence_review_record_changed: list again and decide on the current entity (rule citations-to-confirm.6).
• Entities cite a version that a new edition replaced: problem entities-cite-replaced-version. Edits queue this check. A replace does not.
• You must find the entities that rest on an old edition: recipe find-stale-entities.

​

Doors

The default catalog may tell an editor to answer with evidence_review. Use the CLI, the SDK or HTTP then, because that catalog does not list the tool.

​

The CLI word

The CLI calls an entity a record and a citation a quote in penumbra evidence list. The CLI calls an entity a node in penumbra graph nodes.

​

Keep going

Entity · Passage and citation · Workspace · File · Entities still cite a replaced version · Find entities that rest on an old version or a trashed File