avtc-pi-featyard 1.1.0

package/src/kanban/kanban-turn-handlers.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Kanban turn-handler domain module — the turn_start and turn_end handler
+ * bodies as callable methods (no pi.on registration).
+ *
+ * turn_start pauses the grace-period timer and unblocks a "waiting" auto-agent
+ * (a new agent turn means the session is active again). turn_end captures the
+ * active model (for kanban title/topic generation) and resumes the grace-period
+ * timer. The events/agent/ routers own the pi.on registration and call these.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { log } from "../log.js";
+import { _kanbanModelRef } from "./kanban-bridge.js";
+import { captureModel } from "./model-capture.js";
+
+export interface KanbanTurnHandlers {
+  /** turn_start handler body: pause grace timer + unblock waiting auto-agent. */
+  onTurnStart(): void;
+  /** turn_end handler body: capture model + resume grace timer. */
+  onTurnEnd(ctx: ExtensionContext): void;
+}
+
+/**
+ * Construct the kanban turn-handler domain object. `requestWidgetUpdate` refreshes
+ * the widget after unblocking an auto-agent. Uses the shared `_kanbanModelRef`
+ * singleton (same one the model_select event writes to).
+ */
+export function createKanbanTurnHandlers(requestWidgetUpdate: () => void): KanbanTurnHandlers {
+  function onTurnStart(): void {
+    const gpm = globalThis.__piKanban?.gracePeriod;
+    gpm?.pause();
+    // Unblock any auto-agent in "waiting" state — a new agent turn means
+    // the session is active again (user sent a message or follow-up fired).
+    const sm = globalThis.__piKanban?.autoAgent;
+    if (sm && sm.getState() === "waiting") {
+      log.info(`[kanban] turn_start: unblocking auto-${sm.getRole()} agent (was ${sm.getState()})`);
+      sm.unblock();
+      requestWidgetUpdate();
+    }
+  }
+
+  function onTurnEnd(ctx: ExtensionContext): void {
+    // Capture model + resume grace timer (two concerns coordinated in one handler).
+    captureModel(_kanbanModelRef, ctx);
+    const gpm = globalThis.__piKanban?.gracePeriod;
+    gpm?.resume();
+    // Also reset timer on user activity (agent turn ended = user is active)
+    gpm?.onUserActivity();
+  }
+
+  return { onTurnStart, onTurnEnd };
+}

package/src/kanban/model-capture.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * captureModel — record the active model + model-registry into the shared ref so
+ * kanban title/topic generation can call the LLM later (outside any request ctx).
+ *
+ * Prefers the guard's stashed model/registry (survives runner invalidation);
+ * falls back to the event ctx only if the guard hasn't been refreshed yet
+ * (startup edge case). Stale ctx is silently skipped.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CapturedModelRef } from "./kanban-context.js";
+
+export function captureModel(ref: CapturedModelRef, extensionCtx: ExtensionContext): void {
+  // Prefer guard's stashed model/registry (survives runner invalidation).
+  // Fall back to event ctx only if guard hasn't been refreshed yet (startup edge case).
+  const guard = globalThis.__piCtx;
+  if (guard?.model && guard?.modelRegistry) {
+    ref.model = guard.model;
+    ref.registry = guard.modelRegistry;
+    return;
+  }
+  // Guard not yet refreshed — safe to use event ctx (only on initial session_start)
+  try {
+    if (extensionCtx.model && extensionCtx.modelRegistry) {
+      ref.model = extensionCtx.model;
+      ref.registry = extensionCtx.modelRegistry;
+    }
+  } catch {
+    // Stale ctx — skip model capture
+  }
+}

package/src/log.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Feature-flow logger.
+ *
+ * Thin wrapper over the shared `avtc-pi-logger` library (matches the sibling contract:
+ * avtc-pi-subagent/src/log.ts, avtc-pi-parallel-work-guardrail/src/log.ts). The library
+ * owns the file backend, rotation, retention, and level formatting; this module only
+ * owns the featyard singleton + the one featyard-specific helper.
+ *
+ * Logs land at `~/.pi/logs/avtc-pi-featyard/<YYYY-MM-DD>.log` (date-partitioned, with
+ * size roll-over + 2-day retention — all handled by the library). Best-effort: a logging
+ * failure never throws to the host.
+ *
+ * Per-module scoped loggers are derived via `log.child("<module>")` in each module.
+ */
+
+import { homedir } from "node:os";
+import { createLogger, NO_ERROR, resolveBaseDir, resolveLogPath } from "avtc-pi-logger";
+
+/** No custom logger options — use library defaults. */
+const NO_LOGGER_OPTIONS: Parameters<typeof createLogger>[1] = null;
+
+/** Name featyard logs under (passed to createLogger). Centralized so the log-path helper matches. */
+const LOGGER_NAME = "avtc-pi-featyard";
+
+/** Feature-flow's process-wide logger (writes under ~/.pi/logs/avtc-pi-featyard/). */
+export const log = createLogger(LOGGER_NAME, NO_LOGGER_OPTIONS);
+
+/** Re-exported library sentinel: the value to pass `log.error`'s required error-cause argument
+ *  when there is no caught exception (a config-level report). */
+export { NO_ERROR };
+
+/**
+ * Resolve the exact log file path where featyard is currently writing.
+ * Date-partitioned (`YYYY-MM-DD`.log, UTC); the current day's file is always where new lines
+ * land (rolled-over portions get a `.1` suffix). Mirrors the logger's own base-dir precedence
+ * (`options.baseDir ?? PI_LOGGER_DIR ?? resolveBaseDir(homeDir)`) so a relocated log store is
+ * honored. Unaffected by PI_FY_HOME. Pass the timestamp explicitly from the call site.
+ *
+ * Used by the worktree-setup error message to point the user at the exact log file to inspect.
+ */
+export function getLogFilePath(now: Date): string {
+  const baseDir = process.env.PI_LOGGER_DIR ?? resolveBaseDir(homedir());
+  return resolveLogPath(LOGGER_NAME, baseDir, now);
+}

package/src/phases/env-sync.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Environment variable synchronization — centralized management of
+ * PI_FY_* env vars. All writes to these env vars should go
+ * through this module to ensure atomicity and traceability.
+ *
+ * Note: PI_FY_REVIEW_LOOP and the per-task pointer (implement.currentTask) are
+ * intentionally NOT mirrored to env vars. They live in feature-state — the
+ * durable source of truth — and are read directly by the host-side consumers
+ * (subagent prompt-transformer, widget, template substitution), which all have
+ * handler access. Only PI_FY_FEATURE (child needs it to locate its state file
+ * on start) and PI_FY_STAGE (root fork-mode derivation) are env-mirrored.
+ */
+
+import { log } from "../log.js";
+import { syncForkModeEnv } from "../settings/settings-ui.js";
+import type { FeatureSession } from "../state/feature-session.js";
+
+/** Set the active feature slug env var */
+export function setActiveFeatureEnv(slug: string): void {
+  process.env.PI_FY_FEATURE = slug;
+}
+
+/** Clear the active feature slug env var */
+export function clearActiveFeatureEnv(): void {
+  delete process.env.PI_FY_FEATURE;
+}
+
+/**
+ * Clear feature-specific env vars (stage).
+ */
+export function clearFeatureEnvVars(): void {
+  delete process.env.PI_FY_STAGE;
+}
+
+/**
+ * Sync PI_FY_STAGE from current handler state.
+ *
+ * **When to call:** After ANY state change that affects currentPhase. Call sites include:
+ * - Phase transitions (phase-ready.ts, phase-transitions.ts)
+ * - Review loop increments (review-loops.ts)
+ * - Feature activation/restoration (feature-management.ts)
+ * - Session state restoration (session-lifecycle.ts, state-persistence.ts)
+ * - Workflow commands that change phase (workflow-commands.ts)
+ * - Guardrail state changes (guardrails.ts via syncEnvVars callback)
+ *
+ * `persistState()` calls this internally, so standalone calls immediately before
+ * `persistState()` are redundant and can be removed.
+ */
+export function syncEnvVarsFromState(handler: FeatureSession): void {
+  const ws = handler.getWorkflowState();
+  // Stage is independent of feature slug — always sync from currentPhase.
+  if (ws?.currentPhase) {
+    process.env.PI_FY_STAGE = ws.currentPhase;
+    log.info(`[workflow] syncEnvVars: set PI_FY_STAGE=${ws.currentPhase}`);
+  } else {
+    log.info(`[workflow] syncEnvVars: clearing PI_FY_STAGE (currentPhase=${ws?.currentPhase ?? "null"})`);
+    delete process.env.PI_FY_STAGE;
+  }
+  // Fork mode is derived from the (just-synced) stage + settings. Root-only inside.
+  syncForkModeEnv();
+}

package/src/phases/execution-mode.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Execution mode applier — applies the settings-configured execution mode
+ * when the plan phase completes.
+ *
+ * Reads `implementMode` from settings and advances to the implement
+ * phase: creates a worktree if needed, then dispatches the fy-implement
+ * skill in the current session (checkpoint / subagent / subagent-fork modes).
+ *
+ * No interactive dialog — the mode always comes from settings.
+ *
+ * All factory-coupled dependencies are injected via ExecutionModeDeps.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSettings } from "../settings/settings-ui.js";
+import { NO_AGENT_NAME, NO_FEATURE_STATE_OVERRIDE } from "../shared/workflow-refs.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import { DEFAULT_DIR, type ExpandSkillCommandFn, type FeatureState, saveFeatureState } from "../state/feature-state.js";
+import { schedulePostTurnFollowUp } from "../state/post-turn-dispatch.js";
+import { persistState } from "../state/state-persistence.js";
+import { NO_FEATURE_STATE, updateWidget } from "../ui/featyard-widget.js";
+
+export interface ExecutionModeDeps {
+  pi: ExtensionAPI;
+  handler: FeatureSession;
+  expandSkillCommand: ExpandSkillCommandFn;
+  applyModelOverrideForPhase: (pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>;
+  resolveBaseBranch: (ctx: ExtensionContext) => Promise<string>;
+  ensureWorktreeForExecution: (featureState: FeatureState, ctx: ExtensionContext) => Promise<FeatureState>;
+}
+
+export function createExecutionModeApplier(deps: ExecutionModeDeps) {
+  const { pi, handler, expandSkillCommand, applyModelOverrideForPhase, resolveBaseBranch, ensureWorktreeForExecution } =
+    deps;
+
+  /**
+   * Apply the settings-configured execution mode and advance plan → implement.
+   * Advances to implement, ensures a worktree when needed, and dispatches the
+   * fy-implement skill in the current session.
+   */
+  async function applyExecutionMode(ctx: ExtensionContext): Promise<void> {
+    const ws = handler.getWorkflowState();
+    if (!ws) return;
+
+    handler.setCurrentPhase("implement");
+    await applyModelOverrideForPhase(pi, ctx, "implement");
+    persistState(pi, handler);
+    updateWidget(handler, NO_FEATURE_STATE);
+
+    const slug = handler.getActiveFeatureSlug();
+    if (slug) {
+      const featureState = handler.getActiveFeatureState();
+      if (featureState) {
+        const settings = getSettings();
+        const worktreeMode = settings.branchPolicy === "worktree";
+        if (worktreeMode) {
+          await resolveBaseBranch(ctx);
+        }
+        const updated = await ensureWorktreeForExecution(featureState, ctx);
+        if (updated.git.worktreePath) {
+          saveFeatureState(updated, DEFAULT_DIR);
+        } else if (worktreeMode) {
+          // Worktree setup failed in worktree mode. Execution cannot fall back to the main
+          // repo here (the implementer is dispatched into the worktree with path-rewriting
+          // interception), and the failure was already notified + logged inside
+          // ensureWorktreeForExecution. Halt: do NOT dispatch the fy-implement skill.
+          return;
+        }
+      }
+    }
+
+    schedulePostTurnFollowUp(expandSkillCommand("/skill:fy-implement", NO_FEATURE_STATE_OVERRIDE, NO_AGENT_NAME));
+  }
+
+  return applyExecutionMode;
+}

package/src/phases/implement-to-verify.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { applyModelOverrideForPhase } from "../shared/workflow-refs.js";
+import type { IGuardrails } from "../shared/workflow-types.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import { persistState } from "../state/state-persistence.js";
+import { NO_FEATURE_STATE, updateWidget } from "../ui/featyard-widget.js";
+import type { RouteConfig } from "./workflow-router.js";
+
+/**
+ * Run the implement→verify transition side-effects (phase advance, mark verify
+ * tests not-yet-passed, apply the verify model override, persist, refresh the widget).
+ *
+ * Called by `task_ready_advance`'s last-task branch. Does NOT reset
+ * `implement.currentTask` or dispatch the verify skill — those are the caller's concern.
+ */
+export async function advanceImplementToVerify(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  handler: FeatureSession,
+  guardrails: IGuardrails,
+  routeConfig: RouteConfig,
+): Promise<void> {
+  handler.completeCurrentWorkflowPhase(routeConfig); // implement → verify
+  guardrails.setVerifyTestsPassed(false);
+  await applyModelOverrideForPhase(pi, ctx, "verify");
+  persistState(pi, handler);
+  updateWidget(handler, NO_FEATURE_STATE);
+}

package/src/phases/phase-progression.ts

@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Phase progression — pure pointer math over the ordered featyard phases.
+ *
+ * Models the agent's position in a fixed phase sequence
+ * (design → plan → implement → verify → review → uat → finish) as a single
+ * pointer: {@link PhaseProgressionState.currentPhase}. Phase status is NEVER
+ * stored — it is DERIVED from the pointer plus the feature's `completedAt`
+ * (see {@link isPhaseDone} / {@link isPhaseActive}):
+ *   - every phase before the pointer is `done` (moved through or skipped),
+ *   - the pointer phase is `in-progress`,
+ *   - every phase after the pointer is `pending`.
+ *
+ * This module owns ONLY pointer movement (setCurrentPhase, onInputText,
+ * recordDoc) + status derivation. Sub-loop-aware routing policy (which phase
+ * comes next per settings, review/UAT skipping) lives in
+ * {@link WorkflowRouter} (workflow-router.ts), which advances via
+ * {@link setCurrentPhase} on this progression.
+ *
+ * Moving forward implicitly completes every jumped-over phase (derived).
+ * Moving backward implicitly resets the target-onward phases (derived). No status
+ * map is kept, so it can never drift from the pointer.
+ */
+
+import type { CustomEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { log } from "../log.js";
+import { DESIGN_DOC_DIRS, FY_TASK_PLANS_DIR } from "../state/artifact-paths.js";
+
+/** The ordered featyard phases. */
+export const WORKFLOW_PHASES = ["design", "plan", "implement", "verify", "review", "uat", "finish"] as const;
+
+/** A single phase in the sequence. */
+export type Phase = (typeof WORKFLOW_PHASES)[number];
+
+/** Lifecycle status of one phase (derived, never stored on disk). */
+export type PhaseStatus = "pending" | "in-progress" | "done";
+
+/** Phases that may NOT bootstrap a brand-new workflow from idle. */
+export const FRESH_START_BLOCKED: ReadonlySet<Phase> = new Set(["verify", "review", "finish"]);
+
+/** Skill name → phase. A skill invocation drives progression to its phase. */
+export const SKILL_TO_PHASE: Record<string, Phase> = {
+  "fy-design": "design",
+  "fy-plan": "plan",
+  "fy-implement": "implement",
+  "fy-verify": "verify",
+  "fy-review": "review",
+  "fy-design-review": "design",
+  "fy-plan-review": "plan",
+  "fy-finish": "finish",
+};
+
+/** Phase → canonical skill name (inverse of the driver subset). */
+export const PHASE_TO_SKILL: Record<Phase, string> = {
+  design: "fy-design",
+  plan: "fy-plan",
+  implement: "fy-implement",
+  verify: "fy-verify",
+  review: "fy-review",
+  uat: "fy-review",
+  finish: "fy-finish",
+};
+
+/** Resolve a skill name for a phase, falling back to the phase name. */
+export function resolveSkillForPhase(phase: string): string {
+  return PHASE_TO_SKILL[phase as Phase] ?? phase;
+}
+
+/** Extract a skill name from a `/skill:name` or `<skill name="…">` line; null otherwise. */
+export function parseSkillName(line: string): string | null {
+  const slash = line.match(/^\s*\/skill:([^\s]+)/);
+  if (slash) return slash[1];
+  const xml = line.match(/^\s*<skill\s+name="([^"]+)"/);
+  if (xml) return xml[1];
+  return null;
+}
+
+/** Persisted entry customType for a phase-progression snapshot. */
+export const PHASE_PROGRESSION_ENTRY_TYPE = "phase_progression_state";
+
+/**
+ * Persisted phase-progression state: the pointer + the two doc artifacts the
+ * machine tracks (design / task-plan paths). Status is derived; loop counts,
+ * review history, review-active flags and tasks live in the feature file.
+ */
+export interface PhaseProgressionState {
+  currentPhase: Phase | null;
+  designDoc: string | null;
+  planDoc: string | null;
+}
+
+/**
+ * Structural view any state object with a phase pointer + completion flag
+ * satisfies. Used by the derived-status helpers so they accept a {@link
+ * PhaseProgressionState} (no completedAt) OR a full feature record, without a
+ * circular import on FeatureState.
+ */
+export interface PhaseProgressionView {
+  currentPhase: Phase | null;
+  completedAt: string | null;
+}
+
+/** Ordinal position of a phase in the sequence. */
+export function indexOfPhase(phase: Phase): number {
+  return WORKFLOW_PHASES.indexOf(phase);
+}
+
+/** A phase is done once the feature is completed OR the pointer has moved past it. */
+export function isPhaseDone(view: PhaseProgressionView, phase: Phase): boolean {
+  if (view.completedAt !== null) return true;
+  return view.currentPhase !== null && indexOfPhase(phase) < indexOfPhase(view.currentPhase);
+}
+
+/** A phase is in-progress iff it is the pointer AND the feature is not completed. */
+export function isPhaseActive(view: PhaseProgressionView, phase: Phase): boolean {
+  return view.completedAt === null && phase === view.currentPhase;
+}
+
+/** A phase is pending iff it is neither done nor in-progress. */
+export function isPhasePending(view: PhaseProgressionView, phase: Phase): boolean {
+  return !isPhaseDone(view, phase) && !isPhaseActive(view, phase);
+}
+
+/** Normalize to forward slashes, then prefix-compare (Windows-backslash safe). */
+function isInsideDir(filePath: string, dir: string): boolean {
+  const norm = filePath.replace(/\\/g, "/");
+  const prefix = dir.replace(/\\/g, "/");
+  return norm === prefix || norm.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`);
+}
+
+/** Artifact filename suffixes + their required directories. */
+const DESIGN_DOC = /-design\.md$/;
+const TASK_PLAN_DOC = /-task-plan\.md$/;
+
+/**
+ * Phase progression state machine — owns the pointer + the two doc artifacts.
+ */
+export class PhaseProgression {
+  private state: PhaseProgressionState = { currentPhase: null, designDoc: null, planDoc: null };
+
+  /** Read-only snapshot (defensively cloned). */
+  getState(): PhaseProgressionState {
+    return structuredClone(this.state);
+  }
+
+  /** Replace internal state from a snapshot (defensively cloned). */
+  setState(state: PhaseProgressionState): void {
+    this.state = structuredClone(state);
+  }
+
+  /** Clear the pointer + artifacts back to idle. */
+  reset(): void {
+    log.info("[phase] reset()");
+    this.state = { currentPhase: null, designDoc: null, planDoc: null };
+  }
+
+  /** The current phase pointer. */
+  get currentPhase(): Phase | null {
+    return this.state.currentPhase;
+  }
+
+  /** Recorded design doc path (null if none). */
+  get designDoc(): string | null {
+    return this.state.designDoc;
+  }
+
+  /** Recorded task-plan doc path (null if none). */
+  get planDoc(): string | null {
+    return this.state.planDoc;
+  }
+
+  /** Record a doc artifact path; returns whether it differed from the prior value. */
+  recordDoc(phase: "design" | "plan", path: string): boolean {
+    const key = phase === "design" ? "designDoc" : "planDoc";
+    if (this.state[key] === path) return false;
+    this.state[key] = path;
+    return true;
+  }
+
+  /**
+   * Atomically move the pointer to a target. NO guards — used by user moves
+   * (skill / fy:next) and by WorkflowRouter.completeCurrent. Forward jumps
+   * implicitly complete the jumped phases (derived); backward moves implicitly
+   * reset the target-onward phases (derived). Same-phase re-entry is a no-op.
+   * Returns true when the pointer changed.
+   */
+  setCurrentPhase(target: Phase): boolean {
+    const prev = this.state.currentPhase;
+    log.info(`[phase] setCurrentPhase(${target}) prev=${prev}`);
+    if (target === prev) {
+      log.info(`[phase] same-phase re-entry (${target}) — no change`);
+      return false;
+    }
+    this.state.currentPhase = target;
+    return true;
+  }
+
+  /**
+   * Progression driver: scan text for skill invocations and move to each invoked
+   * phase in turn. verify/review/finish cannot start a fresh workflow from idle;
+   * design/plan/implement can.
+   */
+  onInputText(text: string): boolean {
+    let changed = false;
+    for (const line of text.split(/\r?\n/)) {
+      const skill = parseSkillName(line);
+      if (!skill) continue;
+      const phase = SKILL_TO_PHASE[skill] ?? null;
+      log.info(`[phase] onInputText skill=${skill} phase=${phase}`);
+      if (phase === null) continue;
+
+      if (this.state.currentPhase === null && FRESH_START_BLOCKED.has(phase)) {
+        log.info(`[phase] onInputText skipping ${phase} — no active workflow`);
+        continue;
+      }
+      if (this.setCurrentPhase(phase)) changed = true;
+    }
+    return changed;
+  }
+
+  /**
+   * Detect artifact writes. A design doc (`-design.md` under the design-doc dir — docs/featyard/designs/
+   * when committed, .featyard/designs/ when local) or a task-plan (`-task-plan.md` under .featyard/task-plans/)
+   * is recorded into the machine's doc slots. Never moves the pointer. Returns true if recorded.
+   */
+  onFileWritten(filePath: string): boolean {
+    if (DESIGN_DOC.test(filePath) && DESIGN_DOC_DIRS.some((d) => isInsideDir(filePath, d))) {
+      return this.recordDoc("design", filePath);
+    }
+    if (TASK_PLAN_DOC.test(filePath) && isInsideDir(filePath, FY_TASK_PLANS_DIR)) {
+      return this.recordDoc("plan", filePath);
+    }
+    return false;
+  }
+
+  /** Restore the most recent phase-progression snapshot from a session branch. */
+  static reconstructFromBranch(branch: SessionEntry[]): PhaseProgressionState | null {
+    let latest: PhaseProgressionState | null = null;
+    for (const entry of branch) {
+      if (entry.type !== "custom") continue;
+      if ((entry as CustomEntry).customType !== PHASE_PROGRESSION_ENTRY_TYPE) continue;
+      const data = (entry as CustomEntry<PhaseProgressionState>).data;
+      if (data && typeof data === "object") latest = structuredClone(data);
+    }
+    return latest;
+  }
+}