fix(#2639): warn when local is ahead of origin before forking phase branch (#2981)

* test(#2639): add regression for local-ahead-of-origin warning in handle_branching

execute-phase.md's handle_branching forks from origin/$DEFAULT_BRANCH. When
local is ahead (unpushed commits), the phase branch silently misses them.
The test asserts the workflow checks for local-ahead-of-origin and warns.

* fix(#2639): warn when local is ahead of origin before forking phase branch

handle_branching forks the phase branch from origin/$DEFAULT_BRANCH. When
local $DEFAULT_BRANCH is ahead (unpushed commits like plan/research docs),
the fork silently misses those commits. Now a loud WARNING is printed to
stderr naming the commit count and advising the user, matching the existing
uncommitted-changes warning pattern.

* chore(#2639): add changeset fragment

* fix(#2639): condense warning under ADR-857 cap + merge emitted-drift ack

gsd-test gate caught: (1) execute-phase.md exceeded the 93600-byte Phase 6
ceiling — condensed the WARNING from 3 echo lines to 1. (2) emitted-attribution
flagged the growth without an ack — merged into the existing #2930 ack fragment
(execute-phase.md was already acked there; can't have two acks for the same path).

* fix(#2639): condense warning further to clear the 93400 comfortable-margin gate

The ADR-857 Phase 6 test has two assertions: <93600 (hard ceiling) and
<=93400 (comfortable margin). Condensed from 3 lines to 2 to fit under
93400 (now 93369).

* chore(#2639): backfill changeset PR number 2981

---------

Co-authored-by: sim <sim@local>

.changeset/bold-jays-cheer.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 2981
+---
+**`execute-phase` now warns when local commits are ahead of origin** — forking the phase branch from `origin/$DEFAULT_BRANCH` silently missed unpushed local commits (e.g. plan/research docs). A loud WARNING now names the divergence before the fork. (#2639)

gsd-core/workflows/execute-phase.md

@@ -301,7 +301,9 @@ else
   else
     git switch --quiet "$DEFAULT_BRANCH" 2>/dev/null && git merge --ff-only --quiet "origin/$DEFAULT_BRANCH" 2>/dev/null || true
   fi
-  # Pinned base (#2916); --no-track (#2498) so default autoSetupMerge doesn't wire upstream to origin/$DEFAULT_BRANCH.
+  # Pinned base (#2916); --no-track (#2498). #2639: warn if local ahead of origin.
+  AHEAD=$(git rev-list --count "origin/$DEFAULT_BRANCH..$DEFAULT_BRANCH" 2>/dev/null || echo 0)
+  [ "$AHEAD" != "0" ] && [ -n "$AHEAD" ] && echo "WARNING: $DEFAULT_BRANCH is $AHEAD ahead of origin — '$BRANCH_NAME' won't include those commits (#2639)." >&2
   git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH" --no-track \
     || { echo "ERROR: Could not create '$BRANCH_NAME' from origin/$DEFAULT_BRANCH (#2916)." >&2; exit 1; }
 fi

tests/emitted-drift-acks/2930-fragmentize-execute-phase-markers.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
   "paths": {
-    "execute-phase.md": "#2930 (epic #1671 Phase 3): pilots the in-file `<!-- gsd:section -->` marker grammar by wrapping the --wave/gap-closure/regression-gate branch sections (partial-wave, gap-closure-artifacts, regression-gate) in marker pairs, proving the composeWorkflow seam runs at install time before per-runtime rewrites. Retargeted from plan-phase.md (chore/2930 review): plan-phase.md sits only 36 B under the ADR-857 Phase-6 PRE_PHASE6 gate (tests/phase6-capstone-conformance.test.cjs) and cannot absorb marker overhead, so the maintainer retargeted the pilot to execute-phase.md, which has 728 B of headroom under its own PRE_PHASE6 cap. SOURCE grows by exactly 275 marker bytes (6 marker lines); the EMITTED artifact composeWorkflow produces at install is byte-identical to the pre-#2930 file (markers are stripped, never shipped). See .gsd/phase/chore-2930-fragmentize-xl-workflow/40-design.md 'Known limits' item 5."
+    "execute-phase.md": "#2930 (epic #1671 Phase 3): pilots the in-file `<!-- gsd:section -->` marker grammar by wrapping the --wave/gap-closure/regression-gate branch sections (partial-wave, gap-closure-artifacts, regression-gate) in marker pairs, proving the composeWorkflow seam runs at install time before per-runtime rewrites. Retargeted from plan-phase.md (chore/2930 review): plan-phase.md sits only 36 B under the ADR-857 Phase-6 PRE_PHASE6 gate (tests/phase6-capstone-conformance.test.cjs) and cannot absorb marker overhead, so the maintainer retargeted the pilot to execute-phase.md, which has 728 B of headroom under its own PRE_PHASE6 cap. SOURCE grows by exactly 275 marker bytes (6 marker lines); the EMITTED artifact composeWorkflow produces at install is byte-identical to the pre-#2930 file (markers are stripped, never shipped). See .gsd/phase/chore-2930-fragmentize-xl-workflow/40-design.md 'Known limits' item 5. #2639: handle_branching now warns when local is ahead of origin (+376 B condensed one-line WARNING + rev-list --count check)."
   }
 }

tests/execute-phase-branch-base-ahead-warning.test.cjs

@@ -0,0 +1,37 @@
+// allow-test-rule: source-text-is-the-product (see #2639)
+// gsd-core/workflows/execute-phase.md is the deployed CI contract; asserting
+// that handle_branching warns when local is ahead of origin is only expressible
+// against the workflow text.
+
+'use strict';
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const WORKFLOW = path.join(__dirname, '..', 'gsd-core', 'workflows', 'execute-phase.md');
+
+describe('#2639 — handle_branching warns when local is ahead of origin', () => {
+  const text = fs.existsSync(WORKFLOW) ? fs.readFileSync(WORKFLOW, 'utf8') : '';
+
+  test('the fork block checks for local-ahead-of-origin before branching', () => {
+    assert.ok(text.length > 0, 'execute-phase.md must exist');
+    // The fix adds a `git rev-list --count origin/$DEFAULT_BRANCH..$DEFAULT_BRANCH`
+    // check before the `git checkout -b` fork, with a WARNING to stderr.
+    assert.ok(
+      /rev-list.*--count.*DEFAULT_BRANCH/i.test(text),
+      'handle_branching must check if local $DEFAULT_BRANCH is ahead of origin before forking (git rev-list --count) — without this, unpushed local commits are silently missing from the phase branch (#2639)',
+    );
+  });
+
+  test('the warning names the divergence and advises the user', () => {
+    assert.ok(text.length > 0, 'execute-phase.md must exist');
+    // The warning must mention "ahead" and "unpushed" so the user understands
+    // their commits won't be on the phase branch.
+    assert.ok(
+      /ahead.*origin.*DEFAULT_BRANCH/i.test(text) || /unpushed/i.test(text),
+      'handle_branching must warn that local commits are ahead/unpushed when forking from origin (#2639)',
+    );
+  });
+});