[bitswell]

Summary

• Adds a stack-project orchestrator-only tool that publishes a read-only stacked-PR projection of an integrated LOOM epic via gh-stack.
• Mirror branches are built by walking git rev-list --reverse base..layer.branch and cherry-picking onto the previous mirror tip — never force-branching to workspace merge commits — which avoids the workspace-history leak Drift flagged in the original Team 1 proposal review.
• Zero changes to any existing tool source file. No new protocol surface. No new commit trailers. No schema edits.

Closes #24. Picked from the gh-stack RFP round — Team 1 "read-only presentation projection" was the winning angle.

What changed

File	Change
src/tools/stack-project.ts	NEW — 137 lines, orchestrator-only tool
tests/tools/stack-project.test.ts	NEW — 249 lines, 6 vitest scenarios
src/tools/index.ts	Registration only (import + export + register call)
tests/runtime/mcp-server.test.ts	Tool count fixture bumped 24→25, name list updated (orchestrator post-terminal commits)

Mirror construction algorithm

prev = base   # e.g. "main"
for each layer (NN = 01, 02, ...):
  mirror = stack/<epic>/<NN>-<agent>-<slug>
  commits = git rev-list --reverse base..layer.branch
  git branch -f mirror prev
  git checkout mirror
  git cherry-pick <commits>
  prev = mirror

After all mirrors are built: gh stack init --base <base> --adopt <mirrors...> followed by gh stack submit --auto (with --draft if input.draft). If reproject: true, gh stack unstack runs first. Any error before publish bails with a typed err() — no half-published stack.

Schema

const StackProjectInput = z.object({
  epic: z.string(),
  order: z.array(z.object({
    agent: z.string(),
    slug: z.string(),
    branch: z.string(),
  })),
  base: z.string().optional(),       // default: 'main'
  draft: z.boolean().optional(),      // default: true
  reproject: z.boolean().optional(),  // default: false
});

const StackProjectOutput = z.object({
  mirrorBranches: z.array(z.string()),
  prUrls: z.array(z.string()),
});

roles: ['orchestrator'] — matches pr-create.ts precedent.

Deviation from the issue spec: spec used z.string().default('main') etc.; switched to .optional() with handler-side defaults (input.base ?? 'main') because Zod .default() conflicts with the existing Tool<I,O> typing. Runtime behavior is identical.

Test coverage

tests/tools/stack-project.test.ts — 6/6 pass:

1. Happy path: 3-layer epic → mirrors built via cherry-pick → gh stack init --adopt + gh stack submit --auto --draft invoked with correct args
2. reproject: true invokes gh stack unstack as the first exec call
3. Cherry-pick failure returns err('mirror-cherry-pick-failed', ...) and never calls gh stack init
4. gh stack init failure returns err('stack-init-failed', ...) and never calls gh stack submit
5. draft: false omits --draft from the submit command
6. roles includes exactly orchestrator (role-gating assertion)

Test plan

• npm test — 403/403 passing
• npm run lint (= tsc --noEmit) — zero errors
• Sanity-check the cherry-pick algorithm on a real 2-agent epic in staging (out of scope for this PR; verified via mocked tests)
• loom-plugin recipe PR (separate follow-up) documenting when the orchestrator should call stack-project — this PR is loom-tools only

🤖 Generated with Claude Code