Overview
The pull request is where a shared vault’s quality is enforced. Keep the flow light enough that people actually use it: one branch per session, the auditor as the automated check, and human attention spent only on what the auditor cannot see. The coordination rules the review protects are in team-vaults; the mechanics of the pull request itself are in github-pr-workflow.
Branch per work session, not per note
Atoms are small. A branch per atom produces dozens of one-file pull requests nobody wants to review. A session’s worth of atoms, sources, and link edits (alice/2026-06-aml-reading) is the reviewable unit: large enough to see the shape of the work, small enough to read in one sitting.
Run the auditor as the merge check
Wire the auditor into the pull request workflow and let its exit code decide:
python3 99-Tools/audit.py --format jsonExit 2 (criticals) blocks merge. Exit 1 (warnings) is advisory and visible. Map the auditor’s severities onto the grading scale the team already uses for code so one vocabulary covers notes and software.
| Review grade | Auditor rules |
|---|---|
| BLOCKER | C000 unparseable frontmatter, C005 hindsight edit, C011 under-corroborated publishable claim |
| MAJOR | C001 orphan, C008 missing required field, C002 broken link |
| MINOR or NIT | C010 stale seedling, S009 naked link dump, C006 undigested source |
Lead the review comment with the counts (“1 BLOCKER, 3 MAJOR”) so the shape is visible before the detail. The full catalog is in audit-rule-catalog, and the workflow wiring follows the patterns in github-actions.
Spend human review only on what the auditor cannot check
The script has already verified structure and schema. The reviewer reads for the semantic tier: is the title a real claim, is the atom genuinely one idea, is the linked source the right source for that claim. Those are the same six dimensions the judge uses in semantic-audit.
Label the confidence of every finding. A reviewer who has read the linked source and found it does not support the claim reports a verified problem. A reviewer who has not read it says the claim looks unsourced, pending a read. Never inflate a heuristic into a merge blocker; the auditor’s criticals are the only findings that block by default.
Comment on a pre-decision section; never rewrite it
Decision notes have one owner, and the section written at decision time is frozen, per decision-journals. A reviewer may question an assumption or flag a missing alternative in a comment. A reviewer who edits the section has destroyed the thing the note exists to preserve, and Git history will show it as a change against a region that should never change.
Squash atoms; preserve decision history
Atom pull requests can squash-merge. The final note is what matters, and one commit per session keeps history readable. Decision-note commits must not be squashed. The timeline of when each section was written is the hindsight-bias defense, and squashing collapses it into a single timestamp that proves nothing.
Audit main on a schedule as well as on every merge
Merge checks catch what a branch introduces. They do not catch what time does to notes already on main: verification dates expiring, seedlings going stale, decisions passing their resolution date. Run the auditor weekly against main, append each run to the log, and surface the delta in the weekly review. “Four orphans resolved, two unsourced atoms introduced” is the team’s trend line, and it is caught while drift is still cheap to reverse. The run and its log format are described in vault-audit.