Insert feature → main promotion before close_mark_satisfied (AB#3168)

[PolyphonyRequiem]

Closes AB#3168 — apex-driver never opens feature → main PR for indivisible apex roots

Root cause

Indivisible apex roots — those whose lifecycle_router only ever classifies their own work without decomposing into ADO children — never had feature-pr invoked under their item-dispatch lifecycle path. Instead the classifier flips through implement-merge-group for the MG → impl-PR cascade, and ObserveImplementationMergedAsync marks implementation_merged Satisfied as soon as the impl PR merges into mg/{root} (which itself merges into feature/{root}). The work is on feature/{root} but never reaches main, and close_mark_satisfied fires while the apex's own feature branch is still ahead of main — leaving a satisfied work item with un-promoted commits.

AB#3166's post-mortem reproduced this exactly: only plan-level and implement-merge-group lifecycles fired (never feature-pr); feature/3166 had to be manually merged via PR #374.

Fix (Option C — workflow-only)

Two new nodes in apex-driver.yaml's SECTION 4 (Close), funnelling both pre-existing paths to close_mark_satisfied:

• promote_feature_to_main — script that fetches origin/main and origin/feature/{apex_id}, runs git rev-list --count origin/main..origin/feature/{apex_id}, and routes:
  • needs_promotion=true → promote_feature_pr_dispatch
  • needs_promotion=false → close_mark_satisfied (catch-all; covers fast-pathed apexes and the case where the feature branch doesn't exist in origin)
• promote_feature_pr_dispatch — type: workflow invocation of feature-pr.yaml, mirroring the input shape from apex-item-dispatch.yaml's existing feature_pr_dispatch. Routes unconditionally to close_mark_satisfied after completion; feature-pr.yaml has its own escalation gates for non-merge outcomes.

Both upstream paths to close_mark_satisfied are rewired:

• apex_completion_gate_policy_router (auto branch) → promote_feature_to_main
• apex_completion_gate (confirm option) → promote_feature_to_main

Why Option C and not Option A (new requirement kind)

Considered adding a new feature_promoted RequirementKind + ObserveFeaturePromotedAsync observer + derivation rules + e2e tests. That is the highest-fidelity fix and may still be appropriate for AB#3169 (premature ADO Done cascade), but it carries engine churn that Option C avoids entirely. Option C is purely YAML, mirrors an existing dispatch shape, and is easy to reason about — and feature-pr.yaml is already battle-tested in the decomposed-apex path. If AB#3169's fix needs to introduce the feature_promoted kind anyway, this PR doesn't block that work — the workflow-level routing layer would simply remain in place as defense-in-depth.

Tests

• e2e-apex-driver.Tests.ps1 — 5 new structural assertions:
  • promote_feature_to_main is a script with the expected pwsh args + git rev-list --count shape
  • Routes to promote_feature_pr_dispatch when needs_promotion, else close_mark_satisfied
  • promote_feature_pr_dispatch invokes ./feature-pr.yaml with the apex root inputs
  • Funnel invariant: NO direct path from apex_completion_gate_policy_router or apex_completion_gate.confirm to close_mark_satisfied
• Updated existing apex_completion_gate exposes confirm/abandon test to assert confirm now routes via promote_feature_to_main
• Updated documented happy-path waypoint list to include both new nodes

Verification

• conductor validate apex-driver.yaml — Validation Successful
• Invoke-Pester e2e-apex-driver.Tests.ps1 — 105/105 pass (including the 5 new tests)
• Invoke-Pester lint-apex-driver.Tests.ps1 — 29/29 pass
• All registry lint scripts pass: lint-apex-driver, lint-strict-undefined, lint-bare-cross-branch-refs, lint-pwsh-jinja-bareword, lint-prose-children, lint-sync-after-mutation

The bare-cross-branch lint required a # bare-ref-ok: annotation on the line preceding the git rev-list call, since the lint tokenizer cannot see through PowerShell variable interpolation (origin/$targetBranch..origin/$featureBranch). The actual git command has explicit origin/ prefixes.

Deferred / known limitations

• target_branch = main is hard-coded, matching the existing feature_pr_dispatch invocation in apex-item-dispatch.yaml. If per-apex target branches are ever supported, this is the second of two sites to update.
• Pre-flight refusal when gh/az auth is missing is not added here — feature-pr.yaml already has its own auth-required gates that surface to a human.
• Two pre-existing failures in lint-plan-level.Tests.ps1 are unrelated (verified by stashing this PR's changes; same 2/25 failures on bare main).

Related

• Sibling fix: AB#3169 (premature ADO Done cascade)
• Sibling fix: AB#3170 (polyphony validate idempotency + cache coherence)
• Reproduced by: AB#3166 dogfood post-mortem