Working as a team

A veri/ directory shares the way code shares: branches, merges, and pull requests, with git as the only sync layer. No server, no accounts. This page covers the three things a second committer changes — id allocation, approval rights, and where the approval act happens.

Everything here is opt-in. A solo project behaves exactly as before — same ids, same stamps, zero new ceremony. Team semantics activate only when you declare maintainers, and collisions only exist once two branches allocate ids.

1. Branching: ids may collide, and that's handled

Ids are sequential per type, so two branches can each allocate the same next number — say both file a DEC-041. Git usually merges that cleanly: the filenames differ, so nothing conflicts. The merged tree is where the collision exists, and veri check — locally or as the CI gate on your pull request — refuses it:

decisions/DEC-041-ours.md, decisions/DEC-041-theirs.md: duplicate id DEC-041
  — 2 documents claim it; keep one and move the other with:
  veri renumber DEC-041 --file <path-to-move>

Resolve it on your branch, after merging the main branch in — that way the document that moves is yours, and you know which references meant it:

veri renumber DEC-041 --file veri/decisions/DEC-041-ours.md

One atomic pass moves your document to the next free id: the id: line, the filename, and the veri/ids floor all move together, so neither number is ever reissued. References to the contested id are never rewritten by guessing — they keep resolving to the remaining claimant, and the command lists every one for review. For references that meant your document, name their files and they follow:

veri renumber DEC-041 --file veri/decisions/DEC-041-ours.md \
  --refs veri/work-orders/WO-052-our-feature.md

Outside collisions, veri renumber <id> also works as a plain renumber: when the id is uniquely held, every inbound link and [[ref]] is rewritten in the same pass — nothing dangles.

If the merge does conflict on veri/ids (both branches raised the same counter to different values), keep the higher line — the file is a self-healing floor, and the next write repairs the rest.

2. Maintainers: who may stamp

Approval rights extend through one list on the workflow document's frontmatter (veri/workflow.md):

maintainers:
  - Ada Lovelace
  - Grace Hopper

The list's presence is the switch. Once it exists, every approval stamp names its maintainer:

veri approve DEC-041 --as "Ada Lovelace"

That writes approved_by: under the approved: date — the record lives in the file, like everything else. When your git user.name exactly matches a listed maintainer, --as defaults to it and you can omit the flag. The gate honors every maintainer's stamp identically; approved_by is provenance, not a permission hierarchy.

veri check enforces the roster in two tiers: a stamp naming someone not on the list is an error, while a promoted document with no approved_by at all — every stamp made before the team formed — only warns. Adopting a maintainers list mid-project breaks nothing; re-approve old documents with --as whenever you want the attribution.

3. Pull requests: the stamp rides the PR

The baseline model for promoting documents on a team:

1. Propose on a branch. Agents and teammates file requirements and decisions freely — born draft/proposed, binding on nothing.
2. The reviewing maintainer stamps on the branch. Approval is a deliberate act in the files: the reviewer runs veri approve <id> --as <name> and pushes that commit to the branch. The PR's diff now shows exactly what will bind — status, date, and approver.
3. Merge. The main branch receives the document already approved, with provenance for free: the stamp commit is authored by the maintainer who reviewed it.

Merging never approves. A document merged without a stamp simply stays pending — visible in context packages, binding on nothing, exactly like on a single machine. No bot, action, or merge hook ever writes a stamp; the CI gate verifies the merged result, it doesn't promote anything.

What agents see

The workflow document — including your maintainers list and team rules — arrives as the first section of every context package, so agent sessions on different branches follow the same allocation and approval rules you do. New projects scaffold with a "Working as a team" section in veri/workflow.md; existing projects can copy its three rules from this page.