feat: support named crew and base branches

[lakshyads05]

Intent

PR #4071 is stale; discard it. Evaluate current upstream main for support for custom crew and base branches, needed for bare repositories and office work that ships against a named feature branch. If upstream still lacks that support, create a fresh PR with the minimum surgical changes required for custom named branches.
go with your recommended option
ask the worker to refresh the PR by rebasing.
yes i authorize
there are failing CI on #5616 fix this
bring the PR 5616 upto date with upstream main
Preserve local tip 9182114b under a separate reference and adopt published head bee45299 locally. Proceed with the guarded reconciliation and refresh #5616 against upstream main.

The pull request is the minimum surgical support for selecting a named crew branch and a named base branch at task launch, pull-request target, and landing, including bare repositories and office work that ships against a named feature branch. The chosen option removes the new generic Done-title suffix parsing rather than introducing a persisted completion-note marker. Keep ordinary titles intact. Named local-branch landing details may be narrower in the fleet view. Keep the focused test correction that pins an isolated claude crew-harness so a missing named base is reported as missing rather than as an unknown harness. Refresh that existing pull request by rebasing onto current upstream main and keep the same pull request.

What Changed

• Add per-task named crew and base branch selection across briefs, spawns, scout promotion, and task metadata, with branch validation and collision checks.
• Make review, teardown, and local landing honor the recorded base branch, including bare repositories and linked-worktree safety checks.
• Preserve named local landing notes in backlog replay and fleet snapshots, with updated documentation and regression coverage.

Risk Assessment

⚠️ Medium: This is a cross-cutting but bounded lifecycle update for named crew and base branches, and no concrete source-verifiable defect was substantiated in the reviewed changes.

Testing

Ran the three focused behavioral suites and drove all derived branch, landing, bare-repository, fleet-note, replay, and Herdr guard scenarios against real scripts with disposable labs. No UI surface was involved, so no screenshot was applicable. Worktree remained clean.

• Live validation: ✅ go - 8 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
Create a ship brief using crew branch feature/widget and base branch office; the generated contract names both branches and local landing.	✅ pass	live	Named brief contract
Submit the same crew and base branch; brief generation refuses the invalid selection.	✅ pass	live	Named brief contract
Attempt a local-only launch with missing base office in a disposable Herdr session; launch is refused before task metadata is published.	✅ pass	live	Herdr launch guard
Review and land a task recorded against office; review compares against office and landing fast-forwards office.	✅ pass	live	Named review and landing
Land the recorded named branch in a bare repository; refs/heads/office fast-forwards to feature/widget.	✅ pass	live	Bare repository landing
Promote a scout with named crew and base branches; ship metadata and instructions retain feature/widget and office.	✅ pass	live	Named promotion
Project completed backlog rows; an exact local office completion body becomes a note while an ordinary title ending in local office remains unchanged.	✅ pass	live	Fleet note projection
Replay an interrupted close with local office; the row becomes Done, the marker is removed, and the note is preserved.	✅ pass	live	Session-start replay

Evidence: Named brief contract

Brief generated: feature/widget, office, Herdr lab contract, and local landing text present.

Evidence: Herdr launch guard

Herdr preflight refused missing named base 'office'; meta_exists=no.

Evidence: Named review and landing

review: diff base: office; merge: merged feature/widget into local office; refs_equal=yes.

Evidence: Bare repository landing

Bare merge completed into local office; refs_equal=yes.

Evidence: Fleet note projection

Fleet projection preserved 'Release local office' and extracted local office only from the completion body.

Evidence: Session-start replay

Replay resulted in row_state=done, close_marker=removed, replayed_note=local office.

- Outcome: 🔧 1 issue found → no changes applied ✅ across 2 runs (27m55s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - medium risk

✅ No issues found.

🔧 **Test** - 1 issue found → no changes applied ✅

• ⚠️ live validation verdict: inconclusive (1 of 5 scenarios were driven live against the product); untested: Brief generation and invalid custom crew/base selections produce the requested launch, PR, landing, and refusal behavior, Promotion, review, local landing, and bare-repository fast-forward preserve named branches, Named local completion notes project correctly while ordinary titles ending in local <branch> remain unchanged, Session-start replay preserves a named local landing note
• Live validation: ⚠️ inconclusive - 1 of 5 scenarios driven live against the product

Scenario	Result	Live	Evidence
Brief generation and invalid custom crew/base selections produce the requested launch, PR, landing, and refusal behavior	⏸️ untested	no	The prior payload recorded this as pass with live=false, so it did not establish a live product result.
Promotion, review, local landing, and bare-repository fast-forward preserve named branches	⏸️ untested	no	The prior payload recorded this as pass with live=false, so it did not establish a live product result.
Named local completion notes project correctly while ordinary titles ending in local <branch> remain unchanged	⏸️ untested	no	The prior payload recorded this as pass with live=false, so it did not establish a live product result.
Session-start replay preserves a named local landing note	⏸️ untested	no	The prior payload recorded this as pass with live=false, so it did not establish a live product result.
Real isolated Herdr spawn, pane execution, teardown, and default-session isolation succeed	✅ pass	live	herdr-autodetect-smoke-final.log

• tests/fm-named-branches.test.sh focused named-branch cases
• tests/fm-fleet-snapshot-view.test.sh
• test_recovery_preserves_a_named_local_landing_note
• tests/fm-backend-autodetect-smoke.test.sh with disposable FM_HOME

🔧 No changes applied.
✅ Re-checked - no issues remain.

• Live validation: ✅ go - 8 of 8 scenarios driven live against the product

Scenario	Result	Live	Evidence
Create a ship brief using crew branch feature/widget and base branch office; the generated contract names both branches and local landing.	✅ pass	live	Named brief contract
Submit the same crew and base branch; brief generation refuses the invalid selection.	✅ pass	live	Named brief contract
Attempt a local-only launch with missing base office in a disposable Herdr session; launch is refused before task metadata is published.	✅ pass	live	Herdr launch guard
Review and land a task recorded against office; review compares against office and landing fast-forwards office.	✅ pass	live	Named review and landing
Land the recorded named branch in a bare repository; refs/heads/office fast-forwards to feature/widget.	✅ pass	live	Bare repository landing
Promote a scout with named crew and base branches; ship metadata and instructions retain feature/widget and office.	✅ pass	live	Named promotion
Project completed backlog rows; an exact local office completion body becomes a note while an ordinary title ending in local office remains unchanged.	✅ pass	live	Fleet note projection
Replay an interrupted close with local office; the row becomes Done, the marker is removed, and the note is preserved.	✅ pass	live	Session-start replay

• bash tests/fm-named-branches.test.sh
• bash tests/fm-fleet-snapshot-view.test.sh
• bash tests/fm-backlog-atomicity.test.sh
• Disposable live brief, promotion, review, local landing, bare-repository, fleet projection, and session-start replay checks
• Disposable named Herdr lab launch-preflight check

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[lakshyads05]

@kunchenguid please approve the workflows

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds named crew and integration branch selection to task delivery.

The PR appears safe to merge based on the changes reviewed.

_{Reviews (3) · Last reviewed commit: "no-mistakes(document): Document named br..."}

[kunchenguid]

Speaking as Kun's firstmate:

HEAD ba8e0ddb2c97ee8ae17719b7a4bfc6a019f88f31. MERGEABLE/UNSTABLE vs main. Author lakshyads05 not blocked. Fork PR; no .github/workflows. Greptile FAILURE non-blocking. Attestation MATCH.

Contract-class: opt-in (own tip-vs-main). --branch-name / --base-branch are explicit captain selections at brief/spawn/promote; docs state omitted keeps prefix-plus-id crew branch and repository default integration base (including bare repos). Unconfigured launch path unchanged. Collision/remote-base guards are fail-closed around the opt-in path, not a new always-on default surface.

VISION.md (each rule)

1. One captain, one interface — aligns (named branches compose with existing delivery modes; ordinary titles kept).
2. Authority explicit — aligns (flags required; no inferred branch rewrite).
3. Scripts own mechanics — aligns (validation/reservation in spawn/promote/merge-local).
4. Restart non-event — aligns (base_branch= / branch meta durable).
5. Delegation with a spine — aligns (brief contract lines checked at spawn).
6. Fleet outlives vendor — aligns (forge-agnostic base selection; gerrit/gh paths).
7. Scope — aligns (command-layer delivery plumbing; presentation opt-in).

Fork CI: approved this tip after diff review — CI 36463857987, Require no-mistakes 36463857946 / 36463988683. No security risk.
Firstmate flag: no. Waiting on: CI/NM green (not captain). Auto-merge eligible as opt-in once CLEAN + green; no merge this pass while checks unfinished. Not 14-day stale (created 2026-09-25).

[lakshyads05]

@kunchenguid please review and approve the workflows

[lakshyads05]

@kunchenguid please review and approve the workflows

[lakshyads05]

why are the workflows not yet triggered? @kunchenguid Please fasttrack this as I have been waiting for this work to land since more than a month now - and this is my third PR as the old ones got too old with lots of commits just to resolve merge conflicts.

[wesleymatosdev]

Rebased onto current main and completed — the branch is now mergeable.

What this rebased branch contains (pr-5616 @ 715f0ef6, git am-able patch: https://gist.github.com/wesleymatosdev/baaf78443935927e9a138f077b534095):

• Resolves the ~30 conflict hunks against main's post-feat(bin): make the ship-branch prefix configurable per project #2648/feat(bin): start tasks from a named base branch #6442 base-branch machinery. main's contract is canonical (fm_base_branch_valid, fm_brief_base_branches, SETUP_BASE, parameterized freshen_spawn_worktree_base); the PR grafts --branch-name / --base-branch parsing, the relaunch guard, and the --branch-name ≠ --base-branch guard on top.
• Contract simplification this surfaced: mode=local-only cannot carry a base branch (its landing fast-forwards local main), so all local-only+base paths now refuse at validation — briefs, spawns, and promotions — instead of silently ignoring the base.
• Bug fix found by the tests: fm-promote.sh overwrote the CLI-parsed BASE_BRANCH from meta before the changed-base comparison, so a --base-branch release that differed from the scout's recorded base was silently ignored and promotion proceeded on the stale base. Fixed: the CLI value is preserved and compared; a changed base refuses. Remote-base verification now runs only when the base came from the CLI (a meta-recorded base was already verified at spawn time), and the qualified refs/remotes/origin/<branch> wording is reserved for the remote-verified path so main's "copy of the base branch" prose is preserved.
• Tests: tests/fm-named-branches.test.sh fully realigned (12/12 ok) and tests/fm-spawn-pool-base-freshen.test.sh green; fm-brief, fm-dod-lib, fm-review-diff all pass. Missing-base refusals name origin/<branch>; the dropped-base refusal uses main's wording. ShellCheck clean relative to main.

The remaining suite failures in this environment (herdr/orca/zellij/backend e2e, backlog-atomicity, teardown-with-backlog, bearings-board) reproduce identically on pristine main — they're environment-dependent (missing herdr lab / tasks-axi ≥ 0.2.6 fixtures), not caused by this branch.

Note: neither side of this PR grants push access to wesleymatosdev (maintainerCanModify is off), so the rebased branch is delivered as the patch above. Apply with:

curl -sL https://gist.githubusercontent.com/wesleymatosdev/baaf78443935927e9a138f077b534095/raw | git am
git push -f origin <this PR's head branch>

Closes #1887's ask: named crew and base branches, reconciled with everything main has landed since.