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
Filesystem merge and sandbox path rules affect cook correctness and parallel slice isolation; mistakes could leak wrong artifacts into epic integration tests or overwrite in-flight slice work.

Overview
Epic verification no longer runs against the empty parent worktree. The Petri compiler rebuilds <parentSandboxDir>/__epic__/<epicId>/ from completed slice sandboxes (plan order; later slice wins on path clashes) immediately before verify-epic, logs an epic-sandbox-merged report with conflicts, and passes that merged tree to the handler. Per-slice worktrees stay untouched.

A new epic-sandbox-merge module centralizes merge logic, dependency-aware seedSliceSandboxFromDeps (preserve vs reset for parallel/rework), path-safety checks, and helpers to pick epic/slice ids for merge (including cross-epic slice deps). Slice actions/tests/assess now seed deps at fire time with preserveExisting: true instead of relying on a static per-slice dir only.

SPEC adds invariant I124-K; PLAN marks petri-epic-verification-merge done and drops the open “epic verification sandbox scope” note from graph-compilation. Contract tests assert merged epic dirs and the merge event; a large dedicated unit suite covers merge/seed edge cases.

Collateral: fixtures/txt/plan.yaml defers scaffolding epic verify and moves cli-scaffolding integration to text-ops; brunch --version / tests/version.test.ts ship the scaffolding slice behavior.

^{Reviewed by Cursor Bugbot for commit 72abdb1. 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 98729e9. Configure here.}