FE-877: Brownfield promotion — commit the cook result onto cook/<runId>

[kostandinang]

Stack Context

Stacks on FE-876 (#220). Seventh Arc-1 frontier -- extends FE-827's greenfield promotion (promote-run.ts) to brownfield, closing the cook-codebase-mode follow-on: a completed brownfield result used to sit uncommitted in the worktree with no path back into the user's checkout.

What?

Commit a completed brownfield cook result onto the repo's own cook/<runId> branch as one reviewable commit.

• Promotion (promoteBrownfieldRun, promote-run.ts): the brownfield sandbox was created with git worktree add -b cook/<runId> ... HEAD, so the branch already exists at the base. This lands the composed tree on top of it via plumbing -- seed a throwaway index from the base (read-tree), stage the composed tree against an external work-tree (add -A), write-tree -> commit-tree -p <base> -> compare-and-swap update-ref. Reuses promotionSourceDir to compose across slice layouts (shared / per-slice + __epic__ merge, conflicts reported).
• CLI wiring (runCook, cook-cli.ts): brownfield promotion now runs automatically on a completed run (the old "greenfield-only" block is gone); greenfield stays opt-in via --out.

Why?

git plumbing is the whole point: the user's active branch, working tree, and index are never touched -- only one commit and one ref move. Merging cook/<runId> into the working branch stays the user's call (the orchestrator-arcs guardrail: promotion must not freelance into their branch). Gitignored deps (node_modules/) don't land, because add -A honors the worktree's .gitignore. Unblocks FE-872's deferred brownfield dep-delta capture over the CoW baseline.

Tests

Against throwaway git repos: composed tree lands on cook/<runId> (parent = base, app.ts modified + feature.ts added present, node_modules/ absent) while main/HEAD/working-tree/index stay untouched and no stray branches appear; a missing cook/<runId> branch throws.

Review fixes (this revision)

• Real linked-worktree test. The original test created cook/<runId> via git branch, not the production git worktree add -b cook/<runId> topology -- exactly where "update-ref a checked-out branch" could fail. Added a test that promotes from the main repo while the branch is checked out in a linked worktree (verified out-of-band that update-ref succeeds there): only the ref moves, main checkout untouched.
• Tracked-deletion test. Pinned the deletion claim -- a file dropped from the composed tree is removed in the cook commit (the read-tree base + add -A captures deletions, not just adds/mods).
• Brownfield --out warning. Brownfield auto-promotes, so --out no longer silently no-ops -- it warns that the result lands on cook/<runId>.
• Dropped a misleading CAS test that couldn't actually interleave the race from outside the function; CAS correctness is visible in the code (parent is update-ref's expected old-value).

Co-authored-by: Amp amp@ampcode.com

[kostandinang]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• FE-881: Cook agent loads the target repo's sandbox-scoped skills #227
• FE-883: Orchestrator operational improvements (serve reliability + Opus 4.8) #224
• FE-878: Brunch serve — one-shot plan-then-cook capstone #222
• FE-877: Brownfield promotion — commit the cook result onto cook/<runId> #221 👈 (View in Graphite)
• FE-876: Integration oracle — reachability gate + grounding seam #220
• FE-875: App runtime probe — boot, probe, classify #219
• FE-872: Install-failure classification — infra-vs-test split #218
• FE-871: Brunch toolchain detection — detect + plan-emitter wiring #214
• FE-867: Agent extension host — dual-mode pi-harness contract #213
• FE-864: Orchestrator improvements umbrella — brownfield feature delivery from spec #212 : 1 other dependent PR (#223 )
• FE-843: Expand cook toolchain profiles, selected at plan time #198
• FE-841: Embed pi as an in-process SDK to drop the external pi CLI dependency #194 : 1 other dependent PR (#211 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Medium Risk
Promotion mutates git refs in the user's repo (CAS on cook/<runId> only), but plumbing is designed to avoid touching the active branch or working tree; failures surface as CLI errors with non-zero exit.

Overview
Brownfield cook results now land as a single reviewable commit on cook/<runId> when a run completes successfully, extending FE-827's greenfield promotion story. New promoteBrownfieldRun in promote-run.ts uses read-tree → add -A → write-tree → commit-tree → CAS update-ref with a throwaway index and external work-tree pointed at the composed tree from promotionSourceDir, so only that ref moves—the user's active branch, working tree, and index stay untouched.

CLI (runCook) flips the old greenfield-only --out block: brownfield promotion runs automatically on success; --out is ignored with a warning. Incomplete runs still promote nothing. Greenfield behavior is unchanged (opt-in --out / --force).

Tests cover happy path, missing branch, real linked-worktree topology, and tracked deletions. memory/PLAN.md marks brownfield-promotion landed (FE-877).

^{Reviewed by Cursor Bugbot for commit 843025d. Bugbot is set up for automated code reviews on this repo. Configure here.}