How to read a report
A conformance comment is constitution triage, not a product review and not a vote to close the ticket.
This page is for engineers reading that comment on a GitHub issue.
The clerk (human or agent) loads the .invariants cascade and asks:
does this proposal threaten a claim?
The comment you see is the answer. Bug fixes, refactors, and backlog priority stay with engineering.
Ground truth is code (what runs) plus GitHub labels (clerk state).
The report itself is not law.
Share a deep link by copying the URL after you open a page in the sidebar — e.g. reading.html#verdicts.
Quick rules
Three facts. Then pick up the issue.
- CLEAR does not mean close the issue. Constitution triage is done. Leave the ticket open; engineering still owns the work.
- CLEAR and PROCEED are both pickable. Neither is a hold. They differ in what the PR must not break, not in whether you may start.
- PASS / FAIL is not the verdict. Today’s code can FAIL a claim while the issue is still CLEAR or PROCEED. Do not mix the columns.
Two questions
Every report answers both. Separately.
Mixing them is the usual misread: “code is FAIL, so we are BLOCKED,” or “CLEAR, so the bug isn’t real.”
- Findings table
-
Does today’s code match the claim?
PASS / FAIL / UNKNOWN against source you can open.
Audit for this run. Never written back into .invariants.
A FAIL is often the acceptance criteria for “done,” not a reason to stop the issue.
- Recommendation
-
Does doing this issue break a claim?
CLEAR / PROCEED / PROCEED TO TRIAGE / BLOCKED.
Pattern-matched from the highest threatened severity. That is the only constitution gate.
Verdicts
Same backlog. Different review.
If you only care “can we pick it?”, CLEAR and PROCEED collapse.
The split exists so an additive API change is not reviewed like dropping unused tables.
| Verdict |
When |
Pick it? |
Review watches |
| CLEAR |
No assertion threatened. Not an interface or protocol concern. |
Yes — normal product work. |
Do not accidentally start changing FROZEN surfaces. |
| PROCEED |
ADDITIVE claim in play: new optional fields, endpoints, or UX. Existing consumers stay valid. |
Yes — implement with the report’s guards. |
Stay additive. If the PR changes today’s list shape, field names, or default semantics, it is no longer PROCEED. |
| PROCEED TO TRIAGE |
VERSIONED claim threatened. Breaking change is allowed only with a documented migration path. |
Not until the migration path exists. |
Upgrade story, lockstep consumers, major-level communication. |
| BLOCKED |
FROZEN claim would be falsified. Cross-repo guarantee at risk. |
No — constitution first. |
Coordinated / MAJOR decision. Do not merge around it. |
Mixed issues split the recommendation (e.g. BLOCKED for the FROZEN part, PROCEED for the additive part).
Highest severity still wins the primary line.
GitHub labels
in_triage is not a hold.
Labels track constitution clerk state, not engineering assignment.
| Label |
Means |
Does not mean |
| needs_triage |
Waiting for a cascade evaluation. |
The issue is invalid or low priority. |
| in_triage |
A report was posted. Clerk step finished (or in flight). |
“Don’t pick this.” CLEAR and PROCEED issues are ready for engineering. |
The agent workflow only flips needs_triage → in_triage.
It does not close issues and does not define a “ready for eng” label.
Drop in_triage on CLEAR / PROCEED if your board treats that label as “still ours.”
Leave it on BLOCKED and PROCEED TO TRIAGE.
Report anatomy
What each heading is for.
- Scope Decision
- Is this a constitution question? Out of scope → usually CLEAR. In scope names which claims could be touched.
- Surface Classification
- Threatened severity → the verdict. Guards live here (“optional params only”, “don’t rename fields”).
- Invariant Findings
- PASS / FAIL / UNKNOWN vs today’s code, with file evidence. Not the recommendation.
- Implementation Alignment
- How to do the work without falsifying a claim. Advice, not new policy.
- Downstream Impact
- Which repos move together. Lockstep notes belong here.
- Recommendation
- One primary verdict. If it says CLEAR, it should spell out: triage complete — do not close the GitHub issue.
Artifacts
What is law, what is a map, what is a comment.
| Artifact |
Role |
How to treat it |
| .invariants |
Constitution — claims + severity. |
Read-only for agents. Maintainers change it in a PR. No issue numbers, no “currently failing,” no fork flags in the file. |
| GitHub comment / reports/*.md |
This evaluation, posted once. |
The thing you are reading. Skip if a report already exists (idempotency). Not governance. |
| GitHub labels |
Clerk state. |
needs_triage → in_triage. Not a close, not a priority. |
| CONTRACT.md / GLOSSARY.md |
Navigational prose (·NAV:S). |
Orient. If it conflicts with a claim, the claim wins. |
| IMPLEMENTATION_MAP.md |
Code-path index (·NAV:M). |
Points at files. Proof is still the source, not the map. |
| Code (vecs + files) |
What actually runs. |
Ground truth for PASS/FAIL. Markdown is not in the search corpus. |
Intentional fork: if a sub-repo claim is incompatible with the apex, that is said in the report.
Operators decide. It is never stored as metadata in .invariants.
CLEAR vs CLOSE
Never write bare CLOSE.
Older docs and some starter-kit copies used CLOSE for “no assertion threatened.”
Peers read it as “close this GitHub issue.” The token is CLEAR —
constitution triage complete; work may continue.
If you see CLOSE in a comment, read it as CLEAR unless the author explicitly asked to close the ticket.