@workforge/gitq-core

@workforge/gitq-core

Stacked branch engine for Git. Manages branch stacks, cascade rebases, conflict detection, forge integration (GitHub/GitLab), and stack diagnostics.

Architecture

The engine is organized around a few core subsystems:

Stack Management (stack-manager.ts)

CRUD operations on branch stacks: add/remove/rename/reparent branches, fold and split branches, manage the StackStore (persisted JSON).

Rebase Engine (rebase-engine.ts)

Cascade rebase logic for stacked branches:

• preflight() — pre-rebase conflict prediction via git merge-tree --write-tree. Returns PreFlightReport with predicted conflict files, drift warnings, and thread warnings.
• cascadeRebase() / doCascadeLoop() — rebases all branches in topological order. Handles merged parents (tombstone resolution, fork-point detection). Pauses on conflict with CascadePauseInfo.
• classifyConflicts() — classifies conflict patterns from file types (e.g., parent-improved-child-moved from UD+AU pairs). Currently only runs post-failure; the active initiative moves it to preflight.
• syncLocalStack() — fetch + cascade rebase onto latest trunk.

Stack Diagnostics (stack-diagnostics.ts)

Two-layer diagnostic pipeline:

• collectSnapshot() — parallel git queries per branch: divergence, ancestry, tombstone drift. Produces StackSnapshot.
• diagnoseStack() — pure classifier that produces NodeDirective objects with situation codes (parent-merged, behind-parent, diverged, etc.), badges, action buttons, and edge/banner directives for the UI.

Conflict Resolution (conflict-resolver.ts)

• classifyConflictFiles() — classifies files as generated, lockfile, or manual-resolution
• prepareForAgent() — auto-resolves generated/lock files, returns AgentResolutionTask for remaining conflicts
• proposeResolutionPlan() — LLM-based resolution plan proposal
• Generated patterns — configurable glob patterns for auto-resolution (lockfiles, codegen output)

Forge Sync (forge-sync.ts)

Bidirectional sync with GitHub/GitLab: publish stacks as MRs/PRs, detect merges, refresh pipeline statuses, import stacks from existing MRs.

Git Shell (git-shell.ts)

Thin wrapper around git CLI commands. Key methods:

Category	Methods
Branch	getCurrentBranch, getBranchHead, getMergeBase, branchExists, createBranch, checkoutBranch, deleteBranch
Rebase	rebaseOnto, rebaseContinue, rebaseAbort
Merge/Conflict	mergeTreeDryRun, listConflictedFiles, listConflictedFilesWithTypes, checkoutOurs, checkoutTheirs
Tree/Content	lsTree, showFile, checkoutFileFromRef, diff, diffNameOnly
History	log, logDetailed, cherry, isAncestor, getMergeBaseForkPoint
Remote	fetch, pushForceWithLease, getRemoteUrl

Key Types

interface StackNode {
  branch: string;
  parent: string | null;
  status: 'local-only' | 'synced' | 'drift' | 'merged';
  lastKnownHead: string;     // tombstone for merged branches
  forkPoint: string | null;
  mrIid?: number;
  mrUrl?: string;
}

interface Stack {
  id: string;
  stackName: string;
  root: string;              // trunk branch (e.g., "main", "master")
  nodes: StackNode[];
}

type Situation =
  | 'up-to-date' | 'ahead' | 'behind' | 'diverged'
  | 'behind-parent' | 'parent-merged' | 'parent-merged-drifted'
  | 'remote-gone' | 'untracked' | 'unmanaged';

Development

bun install                     # install deps (from repo root)
bun run test:unit               # unit tests
bun run test:integration        # integration tests (creates temp git repos)
bun run test                    # both
bun run check-types             # type-check
bun run lint                    # eslint

Integration tests create isolated temporary git repositories, so they're safe to run without side effects on real repos.

Design Docs

Detailed design documents for active engineering initiatives:

• docs/mcp-agent-experience-redesign.md — How the MCP server should surface conflict intelligence to agents
• docs/parent-improved-child-moved-resolution.md — Detection and resolution pipeline for parent-improved-child-moved conflicts