FE-745: Epic-scoped sandbox merge for verify-epic

[kostandinang]

Summary

• verify-epic now runs in a merged tree at <parentSandbox>/__epic__/<epicId>/ built from completed slice sandboxes, following plan order (later slice wins on duplicate relative paths).
• Adds epic-sandbox-merge handler/transition and epic-sandbox-merged report event; SPEC invariant I124-K captures merge semantics for reviewers and future automation.

Context

• FE-743 gave each slice an isolated sandbox and enabled parallel firing. Epic integration tests that span multiple slices previously executed in an empty parent sandbox, so multi-slice plans with cross-slice checks could not pass honestly.
• Merge order follows plan topology so dependency direction is reflected in which slice artifacts land in the epic tree when paths collide.
• Follow-up fixes in this branch address parallel races, rework orphans, and dependency seeding so merge does not overwrite in-flight slice work.

What changed

• epic-sandbox-merge: assembles slice outputs into an epic-scoped directory immediately before verify-epic runs.
• Dependency-aware seeding and pruning so parallel rework and cross-epic dependencies preserve completed slice artifacts and do not leave orphan sandboxes.
• Reserved __epic__ slice id rejected at validation time to prevent merge namespace poisoning.

Verification

• Five focused merger unit tests plus updated engine contract coverage on the epic verification path.
• npm run verify green.

Out of scope

• Declarative conditional output arcs and static reachability (FE-747).
• Promoting cook branches or merging run results back to the user’s main branch (artifact lifecycle frontier).

Traceability

• Requirement 49; decision D159-K; invariant I124-K; frontier petri-epic-verification-merge in memory/PLAN.md; umbrella H-6476.

[cursor]

PR Summary

Medium Risk
Changes orchestrator filesystem layout and merge semantics on the critical cook/verify path; mistakes could hide missing slice artifacts or corrupt parallel slice sandboxes, though coverage is strong.

Overview
Epic verify-epic no longer runs in the empty parent worktree. Before verify-epic, the orchestrator rebuilds <parentSandboxDir>/__epic__/<epicId>/ by merging completed slice worktrees (dependency epics and cross-epic slice deps included, in plan declaration order). Colliding paths keep the later slice’s file; conflicts are recorded and emitted as an epic-sandbox-merged report event. Slice worktrees are not modified by the merge.

Per-slice execution now seeds each slice sandbox from completed dependency worktrees (seedSliceSandboxFromDeps), with preserveExisting on actions/tests so parallel runs and rework do not blindly overwrite in-flight edits; full re-seed can prune orphans on rework reset.

New module epic-sandbox-merge plus broad unit/contract tests; memory/SPEC.md adds invariant I124-K; memory/PLAN.md marks petri-epic-verification-merge done. The txt fixture plan shifts epic integration tests to text-ops and defers scaffolding epic verify until more slices exist.

Also in the diff: brunch --version / -V (from package.json) with tests/version.test.ts.

^{Reviewed by Cursor Bugbot for commit 78bf6ee. 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-763: Petrinaut event stream — initial markings + transition firings #158
• FE-762: Petrinaut-format JSON export of the compiled net #157
• FE-761: Petri-net semantic alignment for Petrinaut visualization #156
• FE-755: Cook codebase mode for brownfield brunch #155
• FE-747: Declarative output routing for branching transitions #154
• FE-745: Epic-scoped sandbox merge for verify-epic #152 👈 (View in Graphite)
• 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 fixes multi-slice epic verification by running verify-epic against a deterministic, freshly-merged epic-scoped sandbox directory.

Changes:

• Added mergeSlicesIntoEpicSandbox to materialize <parentSandboxDir>/__epic__/<epicId>/ from completed slice worktrees, with last-wins collision handling.
• Updated the Petri net compiler’s verify-epic wiring to invoke the merger and emit a new epic-sandbox-merged report event.
• Extended contract coverage to assert verify-epic receives the merged epic sandbox and that the merge event is logged.
• Documented the new invariant (I124-K) and marked the related plan frontier item as completed.

Technical Notes: Merge order follows slice declaration order; later slices overwrite earlier paths and conflicts are surfaced in the event payload. Per-slice worktrees remain unmodified and the epic sandbox is rebuilt on each verification run.

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

[augmentcode]

Review completed. 1 suggestion posted.

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

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