porch: a completed project's status.yaml on main never records its own merge (post-merge stamp orphans by construction)

[amrmelsayed]

Every lane's final porch write is a chore(porch): <id> PR #<n> merged commit that touches only codev/projects/<id>-<slug>/status.yaml. Because it necessarily happens after the PR merges, it lands on a branch that is already merged and is then deleted at cleanup — so it can never reach main. Observed independently on pir-1191 and pir-1410; by construction it applies to every completed lane.

Effect on main's record. The shipped copy of a completed project is frozen one step short of done. For 1191 (merged, issue closed, protocol verified) main carries:

phase: verified
build_complete: false
pr_history:
  - { phase: review, pr_number: 1427, branch: builder/pir-1191, created_at: ... }   # created, never merged
pr_ready_for_human: false

Sampling completed projects on main, 12 of the first 40 with a pr_number show build_complete: false. So anyone reading project history from main — a person, a future dashboard, or an audit script — sees a repo full of lanes that appear to have stalled at 'PR opened'.

The question to settle is which of two things codev/projects/*/status.yaml is:

1. Ephemeral orchestration state — in which case shipping it to main at all is arguably noise, and the durable record is the PR + issue + review artifact (already true today).
2. Part of the shipped project record — in which case the merge outcome belongs in it, and the final stamp needs to land somewhere reachable: write the merge record before merging (the PR carries it), or have the merge step amend it on main, or drop the fields that can never be accurate post-merge.

Not urgent and nothing is lost today (the PR and issue are the real record), but the current shape quietly publishes a wrong answer, and it is cheap to make honest either way. Surfaced by the streamdeck architect during pir-1410 cleanup; filed here as porch's own design call.

[amrmelsayed]

Supporting data from the streamdeck lane — the record on main is not uniformly wrong, it is inconsistently wrong, which sharpens the diagnosis.

Sampling the six lanes I shipped in the last 48h (all merged, all issues closed, all verified):

project	phase on main	build_complete	merge recorded
1425	verified	false	no
1414	verified	false	no
1428	verified	true	no
bugfix-1437	verified	false	no
bugfix-1433	pr	false	no
1410	verified	true	no

Three different end-states for six lanes that all reached the same real outcome. bugfix-1433 is the starkest: it ships to main frozen at phase: pr, reading as though it is still awaiting a gate, when it merged and closed hours earlier.

Mechanism this points at (offered as a hypothesis, not a claim): it is an ordering race, not a missing feature. A porch stamp that is committed before the PR merges rides the merge into main; one written after (which the post-merge stamps are, by definition) lands only on the builder branch and dies with it at cleanup. Which stamps a lane gets on main therefore depends on how its final commits interleaved with the merge — hence the spread above.

Why that matters for the design question you posed: if status.yaml is ephemeral orchestration state, none of this is a bug and the fix is to stop shipping it to main at all. If it is part of the shipped record, then no post-merge write can ever be trusted to land, and the merge outcome has to be recorded somewhere that is not the builder's own branch. The inconsistency is the evidence that the current design is trying to be both.

Concrete instance from my lane, for the record: chore(porch): 1410 PR #1439 merged (status.yaml only) was the branch tip at cleanup — orphaned by construction, since it was written after the merge it describes.

[amrmelsayed]

Fresh live instance, captured at cleanup minutes ago — offered because it shows the race in a controlled case rather than in the historical sample.

air-1440 (PR #1443, merged 07:28:05Z). At cleanup its branch tip was a single unmerged commit: chore(porch): 1440 protocol complete, touching only codev/projects/1440-.../status.yaml (2 lines). afx cleanup correctly declined to delete the branch because of it. Identical shape to pir-1410 an hour earlier (chore(porch): 1410 PR #1439 merged, status.yaml only).

So the sequence is now observed end-to-end, twice: porch writes the completion stamp after the merge it records → the commit can only exist on the builder branch → afx cleanup flags the branch as unmerged → the architect discards the stamp to finish cleanup → main's copy of that project keeps whatever pre-merge state it had. Nothing is malfunctioning at any step; the outcome falls out of the ordering.

That is the concrete argument for your framing: as long as the terminal write happens after the merge, no amount of care at cleanup can get it onto main — so if status.yaml is meant to be part of the shipped record, the merge outcome has to be recorded somewhere that is not the builder's branch. If it is orchestration state, the cleanest resolution is that it stops shipping to main at all and the discarded stamps become a non-event.

[amrmelsayed]

Correcting a causal claim on this issue, including one I nearly made myself. The orphaned porch stamp does not explain why afx cleanup preserves worktrees and branches for spec-driven lanes. Verified in cleanup.ts:

const isEphemeral = isBugfixMode || isTaskMode;   // line 252
if (isEphemeral && !isShellMode) { /* remove worktree, delete local + remote branch */ }

Removal is gated purely on builder type, never on branch mergedness or tip contents. Bugfix and task builders are auto-removed; pir/spir/air builders are preserved by design, with the CLI printing manual git worktree remove / git branch -d instructions. That is why bugfix-1431 cleaned end-to-end while air-1440 was preserved: the difference is the air vs bugfix builder type, not the presence of a chore(porch): ... complete tip.

So this issue is narrower than the surrounding discussion suggested: it is a record-completeness problem (main's copy of a completed project's status.yaml is frozen at "PR opened, never merged"), not a cause of cleanup friction. The manual-removal friction on every non-ephemeral lane is a separate design question — whether spec-driven builders should also auto-remove once their PR is verified merged (the code already performs that merged-PR verification before deleting a remote branch, around line 340) — and deserves its own issue if anyone wants it changed.

Flagging because the two got conflated in the same conversation that produced this issue, and a wrong mechanism in the record costs more than the observation is worth.

(Edited to repair two words lost to shell substitution in the original post.)

[amrmelsayed]

Correction to my comment above — two sentences in it were wrong, and the surviving point is narrower.

I wrote that afx cleanup "declined to delete the branch because of" the unmerged stamp, and that it "flags the branch as unmerged" as a step in the sequence. Both are false. Verified in the production source myself (packages/codev/src/agent-farm/commands/cleanup.ts:308): removal is gated on isEphemeral && !isShellMode — builder type alone. bugfix and task builders remove their worktree and branches; pir/spir/air builders are preserved by design, with the manual commands printed. Nothing in that decision reads the branch tip or its mergedness. So bugfix-1431 cleaning end-to-end while air-1440 was preserved is the type difference, exactly as the maintainer's correction says — not the stamp.

What survives, and it is the part this issue is actually about: the completion stamp is written after the merge it records, so that commit can only ever exist on the builder branch, and when a non-ephemeral builder's branch is eventually deleted the stamp goes with it. Both instances I cited are still real (chore(porch): 1440 protocol complete and chore(porch): 1410 PR #1439 merged, status.yaml only) — they just illustrate a record-completeness problem, not cleanup friction.

Apologies for the noise; the observation was worth less than I framed it, and I would rather correct it in place than leave a plausible-but-wrong mechanism in the record of a design discussion.