Integration Target Configuration

LumenFlow’s WU lifecycle pushes, fetches, and compares against an integration target — a <remote>/<branch> pair that represents the canonical state of your codebase. By default that’s origin/main. Enterprise teams often need something different:

• A protected trunk named develop, trunk, or development
• A remote other than origin (common with upstream + fork topologies)
• A release-cut branch like release/2026-Q2
• Any combination of the above

All of this is configured in workspace.yaml, and every lifecycle command (wu:claim, wu:done, wu:block, wu:unblock, wu:release, wu:prune, wu:review, gates, pre-commit checks, spawn prompts, rebase helpers) honours the configured values.

The two knobs

workspace.yaml

software_delivery:
  git:
    mainBranch: develop # default: main
    defaultRemote: upstream # default: origin
    requireRemote: true # default: true; set false for airgapped / local-only work

• mainBranch — the branch LumenFlow treats as “the target we merge into.” Everything called origin/main in docs/messages reads from this key at runtime.
• defaultRemote — the git remote LumenFlow fetches and pushes against. Used for wu:claim canonical-state pushes, wu:done merges, and wu:review tracking-ref diffs.
• requireRemote — set to false for local-only development (airgapped machines, offline evaluation, pre-remote prototyping). See Local-only / offline setup for the full story.

Setting them

Use pnpm config:set — never hand-edit workspace.yaml (the CLI routes the change through a micro-worktree so concurrent agents don’t collide):

pnpm config:set --key software_delivery.git.mainBranch --value develop
pnpm config:set --key software_delivery.git.defaultRemote --value upstream

To verify:

pnpm config:get --key software_delivery.git.mainBranch
pnpm config:get --key software_delivery.git.defaultRemote

What changes after you configure it

Once set, every command that previously mentioned origin/main now reads your configured target. The effects are most visible here:

Surface	Before	After (with mainBranch: develop, defaultRemote: upstream)
wu:claim baseline fetch	git fetch origin main	git fetch upstream develop
wu:done merge target	origin/main	upstream/develop
wu:review diff base	merge-base vs origin/main	merge-base vs upstream/develop
Gate incremental diff (pnpm gates)	origin/main...HEAD	upstream/develop...HEAD
Pre-commit staged-changes base	origin/main	upstream/develop
Agent spawn-prompt guidance	pnpm wu:rebase --id WU-XXX	pnpm wu:rebase --id WU-XXX (configured target)
“Run from shared checkout on ‘main‘“	error message	error says 'develop'

The one place where main still appears literally in code is the resolver’s fallback when no config is set — so defaulting repos stay on origin/main with zero changes.

Claims pin their target

These two keys choose the target of a new claim. A claim then pins its remote and branch, repository identity and baseline, so editing mainBranch or defaultRemote later does not retarget work already in progress; if the pinned remote alias comes to point at a different repository, the next lifecycle write refuses. A claim made before this binding existed is upgraded with pnpm wu:repair --id WU-XXXX --claim --integration-target (see Scoped integration targets).

Optionally declare that your git server protects refs/lumenflow/claim-* against deletion and rewrite:

pnpm config:set --key software_delivery.git.declaresClaimRefProtection --value true

This is a declaration only. LumenFlow does not verify the server and does not refuse for its absence. The key is read from the trusted policy pinned by the claim, and the release, wu:done and wu:prune seal lines print declared (server enforcement is not verified) or unknown (no declaration was found, or it was unreadable). See the configuration reference.

Supported integration topologies

Protected trunk with a separate integration branch

software_delivery:
  git:
    mainBranch: develop
    defaultRemote: origin

Team flow: feature work lands on origin/develop. When develop is cut for release, the release branch is managed outside LumenFlow; LumenFlow keeps pointing at develop for ongoing WUs.

Fork-based contribution model

software_delivery:
  git:
    mainBranch: main
    defaultRemote: upstream

Team flow: each contributor works from a personal fork (origin) but integrates into the upstream maintainer’s repo (upstream). wu:done pushes lane branches to upstream/lane/<name>/wu-<id> and completes against upstream/main.

Release-cut branch

software_delivery:
  git:
    mainBranch: release/2026-Q2

Team flow: the team is deep into a Q2 release and all WUs target that branch directly. Any origin/release/2026-Q2 reference in commit messages, error hints, and diff output uses the full name verbatim.

Airgapped / local-only

software_delivery:
  git:
    mainBranch: main
    requireRemote: false

No remote fetching or pushing — wu:claim and wu:done work against local branches only. Useful for evaluation, secure environments, or pre-remote prototyping.

Reviewing work before it lands

With the integration target configured, pnpm wu:review --id <WU-ID> shows exactly what would merge — diffstat by default, --name-only for a file list, --patch for the full diff. The base ref is always the configured <remote>/<branch> pair, so “what will be pushed?” is accurate for any topology.

The output block also prints IDE-opening hints for non-technical reviewers (for example, product reviewers signing off on a WU before wu:done):

[wu:done] ℹ️  Reviewing <wu-id>
[wu:done] Worktree: /repo/worktrees/framework-foo-<wu-id>
[wu:done] Base: abc1234 (merge-base vs upstream/develop)

[wu:done] Review options:
[wu:done]   Terminal diff:   pnpm wu:review --id <WU-ID>
[wu:done]   VS Code:         code /repo/worktrees/framework-foo-<wu-id>
[wu:done]   Cursor:          cursor /repo/worktrees/framework-foo-<wu-id>
[wu:done]   Any IDE:         cd /repo/worktrees/framework-foo-<wu-id>   (use the Source Control panel)

A reviewer can open the worktree folder directly in their IDE and use the built-in Source Control panel for side-by-side diff inspection — no LumenFlow-specific tooling needed.

Decision authority

This configurable-integration-target behaviour is a ratified design decision. The rejected alternatives (a parallel integration.* config block, per-command flags, and a full PR-based integration strategy) and the rollout order were considered and recorded as part of that decision.

A separate concern — gated human review (requiring PO approval before wu:done runs) — is intentionally tracked separately. This page documents the configurable target and informational review surface only.