FE-755: Cook codebase mode for brownfield brunch

[kostandinang]

Summary

• resolveCookMode selects fixture vs codebase when .brunch/cook/plan.yaml is present, the tracked working tree is clean, and the target directory is a git repository.
• Codebase runs use a parent git worktree on branch cook/<runId> and per-slice worktrees on cook-slice/<runId>/<sliceId>, with copy-on-write for untracked/gitignored content where the OS supports it.
• Cook run artifacts live under .brunch/cook/runs/<runId>/ (replacing .cook/); adds docs/praxis/orchestration-guide.md for operators running cook on real repos.

Context

• Stacks on the Petri substrate delivered in FE-738 through FE-747. This frontier moves brunch cook from fixture-only greenfield runs to brownfield repositories while keeping the user’s source branch byte-identical for the duration of a run.
• Hybrid sandboxes avoid fully duplicating large trees (node_modules, build outputs): APFS clonefile, Linux reflink, then cpSync fallback.
• Agent invocation (pi-actions.ts) stays unchanged at the seam; only sandbox resolution and filesystem layout change.

What changed

• Brownfield resolver wired into the existing cook CLI entry; fixture mode behavior unchanged when resolver conditions are not met.
• cowCopy seeds untracked/gitignored files into slice sandboxes without mutating the source checkout.
• Slice id validation rejects ids that would collide with real repo paths.
• Integration coverage via brownfield-smoke.integration.test.ts plus a documented 2026-05-26 real-pi smoke on a temporary git repo.

Verification

• Unit tests for mode resolver, sandbox paths, and hybrid seed behavior.
• Brownfield integration smoke; full npm run verify green (1449 tests at PR time).

Out of scope

• Branch commit/merge promotion and artifact lifecycle (cook-artifact-lifecycle frontier).
• Evaluator tool scoping and Sandcastle adoption.

Traceability

• Requirements 46–50; SPEC §D50, §A49, §I123-K; frontier cook-codebase-mode in memory/PLAN.md; stacks on FE-747.

[cursor]

PR Summary

Medium Risk
New git worktree and filesystem sandbox logic must preserve the source-repo byte-identical invariant; mistakes could touch the user's checkout, though resolver gates and integration tests target that boundary.

Overview
Cook brownfield mode replaces the reserved "not implemented" path: resolveCookMode picks fixture (plan.yaml) vs codebase (.brunch/cook/plan.yaml), requiring a git repo and a clean tracked working tree (untracked .brunch/ is ignored). Run output moves from .cook/ to .brunch/cook/runs/<runId>/.

Codebase runs seed sandboxes with git worktree add on cook/<runId>, per-slice worktrees on cook-slice/<runId>/<sliceId>, and CoW copies of untracked/gitignored top-level dirs (node_modules, etc.) so agents see real deps without duplicating the whole tree. The petrinet path calls seedSliceFromParentWorktree when sandboxMode is codebase; pi-actions is unchanged.

Petri declarative routing (FE-747 prep): branching handlers use typed RouteGuard + evalRouteGuard instead of inline routeField checks; enumerateCandidateOutputs exposes topology-only output places for static analysis. Docs/SPEC/PLAN and a new docs/praxis/orchestration-guide.md describe operator workflow; brownfield-smoke.integration.test.ts locks source-byte-identical isolation.

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

[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-755: Cook codebase mode for brownfield brunch #155 👈 (View in Graphite)
• FE-747: Declarative output routing for branching transitions #154
• FE-745: Epic-scoped sandbox merge for verify-epic #152
• FE-743: Petri parallel execution with resource pools and per-slice sandboxes #149
• FE-738: Petri semantic lanes with two-lane subnet and engine factory #148
• FE-730: Greenfield orchestrator POC with pi-agent dispatch #143
• main

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

[augmentcode]

🤖 Augment PR Summary

Summary: This PR implements “codebase mode” for brunch cook <dir>, enabling brownfield runs against an existing git repo while keeping the source branch’s tracked files unchanged.

Changes:

• Introduced resolveCookMode(dir) (fixture/codebase/error) and replaced the prior “not yet implemented” exit.
• Added a clean-tree gate for codebase mode using git status --porcelain --untracked-files=no and rejected non-git dirs.
• Extended createSandbox to support codebase mode via git worktree add -b cook/<runId> ... HEAD.
• Added per-slice seeding from the parent worktree (excluding .git, sibling slice dirs, and __epic__/) and wired it into the Petri net compiler.
• Threaded sandboxMode through orchestrator input so engines can branch on fixture vs codebase behavior.
• Consolidated cook run output paths from .cook/ to .brunch/cook/ and updated docs/spec/plan accordingly.
• Added unit + integration coverage, including an end-to-end brownfield smoke test using a real tmp git repo.

Technical notes: Codebase mode checks out a separate worktree branch (cook/<runId>) and runs agents against seeded slice worktrees without mutating the source repo’s HEAD or tracked-file status.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c2cfb6e. Configure here.}