Skip to content

feat: Plan jobs should branch from integration HEAD, not main — dependencies are ordering-only #33

@nigel-dev

Description

@nigel-dev

Description

When a plan job has dependsOn, the orchestrator waits for upstream jobs to merge into the integration branch before launching the downstream job. However, the downstream job's worktree is created from main HEAD — not from the integration branch HEAD.

This means plan dependencies only control launch ordering, not code visibility. Job B cannot actually see job A's code changes, even though it declared a dependency on it.

Expected Behavior

When job B depends on job A:

  1. Job A completes and merges into the integration branch
  2. Job B's worktree is created from the integration branch HEAD (which includes job A's changes)
  3. Job B can import/use code that job A created

Current Behavior

createWorktree() always branches from the current main HEAD:

// src/lib/worktree.ts
createResult = await gitCommand([
  'worktree', 'add', '-b', opts.branch, worktreePath,
  // no startPoint — defaults to HEAD of main
]);

Proposed Fix

  1. Extend createWorktree() to accept an optional startPoint parameter:

    async function createWorktree(opts: {
      branch: string;
      basePath?: string;
      startPoint?: string;  // commit SHA or ref
      postCreate?: PostCreateHook;
    })

    Use: git worktree add -b <branch> <path> <startPoint>

  2. In the orchestrator, when launching a plan job with satisfied deps, pass the integration branch as startPoint:

    await createWorktree({
      branch,
      startPoint: plan.integrationBranch,  // or resolved HEAD SHA
      postCreate,
    });
  3. For root jobs (no deps), use plan.baseCommit as startPoint to ensure consistency.

Files

  • src/lib/worktree.ts — add startPoint support to createWorktree()
  • src/lib/orchestrator.ts — pass integration HEAD when launching dependent jobs

Impact

This is the highest-impact architectural improvement for the plan system. Without it, dependsOn is misleading — users expect code-level dependency, not just ordering.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1: highImportant fix or feature — next up after criticalenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions