Applied Insurance Reference — Machines, Branches and Merges

Epic: applied-insurance-reference Purpose: which machine and agent builds each slice, on which branch, in which round, and who merges what. Slice content stays in the phase plans.

1. Machines and agents

Three rules follow:

• The human runs the branching and merging. Agents must not run the git commands this plan gives for creating, switching, fetching, pulling, pushing, bundling, rebasing or merging branches (§3, §6). They may run any other local git command their normal workflow needs, such as git status, git diff, git log or committing on the branch the human has checked out. When a step needs one of the human’s commands, the agent stops and says so. The one exception: machine R’s agent may run them when the human explicitly asks it to. Machine S’s agent never does.
• Branches are created, pushed and merged on R only. S pulls, works and hands its commits back as a bundle (§3).
• Brief before branch. A slice’s branch is created only once its brief is written: an “in detail” section in its phase plan and a Validation Pack skeleton, both on main. Rolling-wave slices are outlines until R drafts them. Whenever machine R’s agent reports what comes next, it ends with exactly one of these, on its own line:
  • 🔴 PLAN FIRST: AIR-x.y needs its brief drafted on main before you branch. It lists every such slice, and R drafts them before anything else.
  • 🟢 READY TO BRANCH: create and push air/<slice>, … It names every branch whose brief is on main and whose “Branch after” slices have merged.
• Every S branch is verified on R before it merges. S cannot regenerate catalogs or run the versioning check, so it bumps owl:versionIRI literals and .version files by hand under ADR-A86, and R checks them.

2. Slices

Branch names are fixed here, so both machines use the same ones.

Sequence 1 is AIR-0.1, merged as 3377a71. “Branch after” lists the sequence numbers that must be on main before R creates the branch. A branch merges once it is verified and signed off (§6). When several are ready, R merges them in sequence order. Substrate branches merge after AIR-6.1, because each substrate bump makes every merged applied module re-pin its imports.

3. The round trip for an S slice

Every command in this section is run by the human. Machine R pushes to the origin-ssh remote (SSH avoids GitHub’s HTTP authentication). Machine S only fetches, from origin.

On R, create and push the branch:

git switch main && git pull --ff-only

git switch -c air/1.1-layout && git push -u origin-ssh air/1.1-layout

On S, pick it up, let the agent work, and bundle the commits:

git fetch origin && git switch air/1.1-layout

git bundle create air-1.1.bundle origin/air/1.1-layout..air/1.1-layout

Carry the bundle file to R.

On R, take the commits and push them:

git switch air/1.1-layout && git pull --ff-only /path/to/air-1.1.bundle air/1.1-layout && git push origin-ssh

Then verify, sign off and merge (§6). After R pushes main, on S refresh before the next slice:

git fetch origin && git switch main && git pull --ff-only

Several S branches can travel in one trip: bundle each one, carry them together.

4. Rounds

A round is one working session on each machine, ending with R verifying and merging what both produced. A round’s last step is R’s 🔴 or 🟢 announcement (§1) for the branches in its last column. R and S work at the same time within a round. The plan assumes every verification passes. A failed one moves that branch’s merge to the next round.

S is the bottleneck, carrying 17 slices to R’s 4 plus the substrate. In rounds 4 to 8, R’s spare capacity goes to substrate work, which is off the critical path. If S falls behind, move 4.4 and 4.5 to R: they are Turtle and examples, which Claude or Copilot Pro+ can build.

5. Tracking progress: the status record

The status record is the single record for the epic. No per-phase status records are created. It has one section per machine, so the two machines’ edits never touch the same lines:

A slice moves through these states. The machine named in the last column sets each one:

Handoff notes go in the Validation Pack, docs/developer/validation/applied-insurance-reference-<slice>.md, which each slice creates. The building machine adds a “Handoff” section: what it built, what it could not run, and anything R should check first. On S that section is required, since nothing there was tested. Keeping these notes out of the status record means two branches never edit the same lines of it.

At the start of a session, an agent reads the status record on its checked-out branch, then its slice’s phase plan and Validation Pack. At the end, it updates its own section (position, the slice’s state, blockers) in the same commit as its work. Machine S never edits the Round, Machine R, Merge log or Phases sections. When a rebase conflicts in the status record, keep each section’s newest version: the sections are disjoint, so this never loses information.

6. Verifying and merging on R

For each branch, in the order of the round’s merge column:

1. Rebase (human). git rebase main on the branch, then git push --force-with-lease origin-ssh air/<slice>. The agent may help resolve conflicting files, and the human continues the rebase.
2. Regenerate catalogs and release rows (agent): mise run build:ontology-catalog, and after any version bump mise run build:ontology-releases, which adds a row to docs/architecture/ontology-releases.md for each new version and lists the tags to create. Commit the result on the branch.
3. Re-bump versions if needed (agent). If a merge since the branch was created bumped a document this branch also changes, take main’s version, bump again under ADR-A86, and re-pin the importers already on main.
4. Run the checks (agent): the Validation Pack’s single command, plus mise run check:ontology-catalog and mise run check:ontology-versioning when the slice touches ontology/.
5. Fix failures (agent). Copilot Pro+ first for simple ones. Claude when the fix needs a design judgement.
6. Sign off (human). The human runs the validation gate (review the pack, run the command, inspect the artefacts, one adversarial probe) and adds the slice to docs/developer/validation/LOG.md.
7. Record (agent). On the branch: the slice’s state becomes merged in its machine’s section, a merge log row is added, and at a round’s last merge the Round section and the epic’s INDEX.md entry are updated.
8. Merge (human). git switch main && git merge --ff-only air/<slice>, then git push origin-ssh main. Create the release tags step 2 listed and push them to origin-ssh. Delete the branch.

7. Critical path

2.1 and 1.1 → 1.2 → 2.2 → 2.4 → 3.4 → 3.5 (M2), all but the last on S. Loss history (4.4) is also on the path, because 3.5 reads aeo:LossCause.

8. Rules for shared files