porch declares PROTOCOL COMPLETE while the builder branch is still ahead of main

[pseudoseed]

What happens

porch done emits its own state commits after the PR it was tracking has already merged, so those commits can never be in that PR. The builder branch is then ahead of origin/main at the exact moment porch prints:

🎉 PROTOCOL COMPLETE

  Project <id> has completed the <protocol> protocol.

Observed on a BUGFIX run (dvarr issue cluesmith#109, PR cluesmith#116). After the PR merged:

$ git log --oneline origin/main..HEAD
68e9e2d [Issue 109] docs: landing record for the seam fix
9bef385 chore(porch): bugfix-109 protocol complete
d93585d chore(porch): bugfix-109 PR #116 merged

Two of those three are porch's own, from packages/codev/src/commands/porch/index.ts:

• L487 — chore(porch): ${state.id} PR #${options.merged} merged, written by done --merged N, which by definition runs after the merge.
• L656 — chore(porch): ${state.id} protocol complete, written by advanceProtocolPhase on the terminal transition, immediately before the completion banner.

Why it matters

The completion banner is the builder's done signal, and it is wrong at the moment it prints. A builder that trusts it stops. A builder that doesn't trust it improvises a second, unmodelled "docs" PR to land the leftovers — which is what happened here (PR cluesmith#118).

That improvised PR is the real damage, because it exists outside the protocol:

• No phase owns it, so porch status shows verified with nothing outstanding.
• No gate covers it.
• No notification step is attached to it, so the architect is never told the builder is waiting on a decision. The builder sits idle and the worktree is never cleaned up, with nothing anywhere reporting a problem.

The last point is the one that cost real time. Every other hand-off in the protocol has an afx send architect attached; this one has none, because the protocol does not know the PR exists.

Related

approve() already carries a note acknowledging half of this (L897-L900):

// NOTE: The 'verified' state is committed to the builder branch, which may not
// be merged back to main. The closed GitHub Issue serves as the canonical "done"
// signal on main. State alignment (making status.yaml on main authoritative) is
// tracked as future work per spec 653.

Spec 653 covers making status.yaml on main authoritative. This issue is the adjacent problem: not where state lives, but that porch reports success while work is still unlanded, and provides no path or notification for landing it. Fixing 653 might dissolve it; fixing it alone would not fix 653.

Suggested fixes

Roughly in order of cost.

1. Don't lie in the banner. Before printing PROTOCOL COMPLETE, check whether the branch is ahead of its base:

git rev-list --count origin/<base>..HEAD

If non-zero, print what is unlanded and the next action instead of a clean completion. Cheap, and it converts a silent wrong signal into an explicit one.

2. Model the landing step. Give protocols that produce post-merge state commits a terminal land step with its own phase prompt and its own afx send architect notification, so the follow-up PR is a first-class thing rather than something each builder improvises differently.

3. Remove the orphan commits. Have done --merged N and the terminal transition write state without committing to the builder branch — amend into the PR before it merges, or write where main already owns it. Nothing is left behind and neither of the above is needed. Largest change, and probably wants to be designed together with spec 653.

Reproduction

Any protocol run to completion. BUGFIX is the shortest:

1. Run a BUGFIX project through to porch done <id> --pr N --branch <branch>.
2. Merge the PR.
3. porch done <id> --merged N
4. porch done <id> → prints PROTOCOL COMPLETE.
5. git log --oneline origin/main..HEAD → two commits, unlanded.

[pseudoseed]

Another instance, and a third from a sibling project

Adding two occurrences from today so this is not absorbed as one-off workarounds.

Project 63 (experiment). PRs #67 and #68 both merged, issue #63 closed, and porch sat at hypothesis afterwards. The builder had to work around it by hand to reach experiment-complete. Current state reads PHASE: analyze while every artifact the project produced is already on main.

Project 13 (yesterday, main architect). PR merged, issue closed, porch still sat at review.

Project 52 (SPIR, today). Related but distinct: phase 4 force-advanced at porch's safety ceiling after 3 REQUEST_CHANGES iterations rather than passing. That is porch's phase state diverging from review reality rather than from merge reality, so it may be a different fault, but it lands in the same place — the recorded phase does not describe what happened.

The shape

In each case porch's phase is behind what actually shipped, and the builder or architect reconciles it by hand. The workarounds are invisible afterwards: once someone runs the approve command, the state looks like it advanced normally.

That matters beyond tidiness. Phase state is what afx status reports and what an architect reads to decide whether a project is alive, stuck, or done. A project showing analyze when its work is merged is indistinguishable from one that is genuinely mid-analysis.

Not proposing a fix; noting that three projects hit this in two days across two protocols (experiment, spir) and two architects.

[pseudoseed]

Fix 1 shipped in #87. The banner no longer claims completion over unlanded commits:

PROTOCOL COMPLETE — 2 COMMITS NOT LANDED

  Project bugfix-109 has completed the bugfix protocol, but this
  branch is ahead of origin/main, so these commits are in no PR:

    9bef385 chore(porch): bugfix-109 protocol complete
    d93585d chore(porch): bugfix-109 PR #116 merged

  Porch writes its own state commits after the PR merges, so they cannot be
  in it. This is expected — it is being reported rather than hidden.

  Do NOT open a follow-up PR on your own. Tell your architect and wait:
    afx send architect "bugfix-109 complete; 2 porch state commits unlanded on this branch, need a decision"

Three outcomes, three renderings. "Could not check" (no origin ref, not a repo) is deliberately not folded into "clean" — they lead to opposite actions, and collapsing them is how a branch with unlanded work gets a clean bill of health.

The check runs after the state commit, on purpose: that commit is one of the ones being reported.

Fixes 2 and 3 — a modelled terminal land step with its own prompt and notification, and not writing the orphan commits at all — remain. Tracked separately; the third wants designing together with spec 653.