Address informational findings from Testing and Maintainability specialists
during /ship pre-landing review. All findings auto-fixed except the
feature-array asymmetry (M3), which the user approved as Option B (extend
report shape now rather than defer).

state.ts (mergeReparsedPhases):
- Extract arePhasesAligned() predicate so the resume-time trigger and the
  merge function share a single agreement contract (M1).
- Backfill kind on existing PhaseStates symmetrically with the new-entry
  branch (default to "code" when parser supplies none) so post-merge
  invariant is uniform (M4).
- Sync features by number, not array position, surfacing addedFeatures and
  orphanedFeatures in MergeReparsedPhasesReport. Production never adds or
  removes top-level features today, but the asymmetry was a latent gap and
  the report now reports both deltas (M3 / option B).
- Document last-write-wins semantic on duplicate phase numbers and the
  hands-off contract on currentPhaseIndex / currentFeatureIndex.

cli.ts:
- Use arePhasesAligned() in the resume guard instead of an inline predicate.
- Extract logMergeReport(report, context) helper so the resume-time repair
  and the phases_added path emit identical, greppable [plan] log shapes
  with a context tag distinguishing the call site (M2).

tests:
- Add makeSentinelInvocation() typed helper to replace `as unknown as`
  double-casts on SubAgentInvocation sentinels (M_test).
- Pin duplicate-number collapse semantics: plant distinct sentinels on two
  same-numbered PhaseStates and assert the second one (last-write) wins (T1).
- Assert mergeReparsedPhases does NOT mutate currentPhaseIndex /
  currentFeatureIndex (T3 — cursor preservation contract).
- New test for feature-level orphan/added drift surfaced via the extended
  report shape.
- Update existing assertions to verify addedFeatures and orphanedFeatures
  are empty in the happy-path cases.

Suite: 1300 pass / 2 skip / 0 fail (4066 expects). The earlier sub-agents
timing flake also cleared on this run.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…number defense

Address 3 HIGH findings from cross-model adversarial review (Claude
subagent + Codex structured review).

The biggest concern: the resume-time auto-repair I introduced in the
previous commit preserves runtime artifacts (gemini.outputFilePath,
codexReview, committedAt) under whatever `number` is stored in
state.json. But state.json corrupted by the pre-fix /build has the
artifacts persisted at slots whose `number` is wrong — by-number merge
re-attributes those artifacts to the wrong phase. If a downstream
--mark-phase-committed then marks the wrong phase done, the real
phase silently skips its real work. Same silent-corruption shape as
the bug being fixed.

Resolution per user-approved option A: the resume guard becomes
fail-closed. On detected disagreement, gstack-build now exits with code 2
and prints a clear remediation message (delete state, --no-resume, or
manually realign). Users decide what to keep; no silent heal.

The in-run phases_added merge stays auto: there, state.phases[i]
genuinely holds the prior phase's runtime state because the splice
hasn't been re-parsed yet. By-number merge is the correct semantic.

state.ts:
- arePhasesAligned() now also checks feature-level alignment (count +
  per-index number). Resume desync of features alone (user renamed a
  `## Feature N:` heading) no longer slips past the guard.
- mergeReparsedPhases() throws on duplicate phase numbers from the
  parser, defending against aliasing where two same-numbered phases
  would share a single PhaseState object across two array slots.
- Document the contract: cli.ts does NOT auto-invoke the merge on
  resume; the function is wired only on the in-run phases_added path.

cli.ts:
- Resume guard: on disagreement, print a remediation block and exit 2
  via the existing setupFailed flow. No mergeReparsedPhases call on
  resume. The error message names all four counts (state vs parsed,
  for phases and features), names the root cause (pre-fix gstack or
  hand-edit), and lists three recovery paths.
- statePath imported so the remediation message can name the on-disk
  state file explicitly.
- logMergeReport() kept; doc updated to note "resume" context tag is
  reserved for future use (not currently wired now that resume is
  fail-closed).

tests:
- New describe block for arePhasesAligned covering phase-count drift,
  per-index phase-number drift, feature-count drift, and feature-number
  drift with phases preserved.
- New test for duplicate-number rejection (asserts the thrown error).
- Resume-path test renamed and rescoped: it now exercises the PURE
  function's behavior (the shape of the merge if called) without
  claiming this is the runtime recovery path. Comment makes the
  contract clear.

Cross-model adversarial review findings addressed:
- Claude F1 / Codex Med#2 (failedAtPhase desync): moot — fail-closed
  resume means the merge never runs on shifted on-disk state.
- Codex High#1 (resume preserves shifted artifacts): fixed by
  fail-closed.
- Codex High#2 (duplicate phase aliasing): fixed by parser-side
  duplicate detection.
- Codex High#3 / Claude F11 (arePhasesAligned ignores features): fixed.
- Codex Med#1 (corrupted .index survives valid JSON loads): moot
  on resume (fail-closed) and impossible on in-run merge (.index is
  rewritten to i unconditionally).
- Codex Med#2 / Claude F5 (last-write-wins duplicate collapse drops
  recoverable state): moot — resume is fail-closed, so any disk
  duplicates surface as a fail-closed error rather than silent collapse.

Suite: 1305 pass / 2 skip / 1 pre-existing flake in sub-agents.test.ts
(timeout-fix integration block — same shape on main, unrelated to this
diff; passes intermittently). Regression test now: 12 pass / 84
assertions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Signal that the build skill's orchestrator runtime changed in this
branch (FEATURE_NEEDS_PHASES merge fix + fail-closed resume guard).
No top-level VERSION bump per Fork versioning rule — fork-local
skill work bumps skill frontmatter only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Cross-reference the FEATURE_NEEDS_PHASES mid-array merge fix in the two
canonical docs that future debuggers / orchestrator readers go to first.

docs/orchestrator-state-machine.md
- Add Inv F (phases-array alignment with parsed plan), naming
  arePhasesAligned as the predicate and pointing at the two
  paths that can violate it (in-run splice, cross-run state.json
  desync).
- Add §9: mergeReparsedPhases contract — strategy, last-write-wins on
  pre-existing duplicates, parser-side duplicate rejection, hands-off
  cursor, in-run-only wiring. Names the regression test file.
- Add §10: resume-time alignment guard (fail-closed) — exit code 2
  conditions, remediation paths printed to the user, and the
  silent-corruption rationale for refusing to auto-heal on resume.
- Refresh the §11 glossary line numbers (logMergeReport pushed every
  cli.ts pointer down) and add arePhasesAligned, mergeReparsedPhases,
  and the resume-guard call site.

build/README.md
- Add a "Resume-time state/plan desync (exit 2)" subsection to
  Failure Handling describing the new fail-closed error, the three
  recovery options the orchestrator prints, and a back-reference to
  state-machine §10 for the rationale.

No code changes. Diataxis quadrant: reference (state machine) +
how-to (recovery in build/README.md).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>