avtc-pi-featyard 1.1.0

package/src/state/feature-management.ts

@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Feature management functions — activating, resuming, tracking, and recovering
+ * feature state for workflow features.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getBranchOrShortSha, getHeadSha, PROCESS_CWD } from "../git/git-queries.js";
+import { log } from "../log.js";
+import { setActiveFeatureEnv, syncEnvVarsFromState } from "../phases/env-sync.js";
+import { isPhaseActive, isPhaseDone, type Phase } from "../phases/phase-progression.js";
+import { getSettings } from "../settings/settings-ui.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import {
+  createFeatureStateForSubFeature,
+  DEFAULT_DIR,
+  DESIGN_DOC_DIRS,
+  type FeatureState,
+  FY_TASK_PLANS_DIR,
+  stateFilePath as featureStateFilePath,
+  loadFeatureState,
+  saveFeatureState,
+} from "./feature-state.js";
+import { isSubagentSession } from "./state-persistence.js";
+
+/** Pass as `applyModelOverrideForPhase` when no model override is needed. */
+export const NO_MODEL_OVERRIDE: ((pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>) | null =
+  null;
+
+/**
+ * Cross-extension bridge for kanban auto-designer: activates a feature slug
+ * and advances the workflow to the specified phase.
+ */
+export async function activateWorkflowForFeature(
+  slug: string,
+  phase: Phase,
+  ctx: ExtensionContext | null,
+  applyModelOverrideForPhase: ((pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>) | null,
+): Promise<void> {
+  const handler = globalThis.__piWorkflowMonitor?.handler ?? null;
+  if (!handler) {
+    log.warn(
+      `[workflow] activateWorkflowForFeature: handler not registered on globalThis, skipping (slug=${slug}, phase=${phase})`,
+    );
+    return;
+  }
+  // Set the active feature env so subagent tool resolves the right slug.
+  setActiveFeatureEnv(slug);
+
+  // Load the durable record into the handler (seeds the workflow tracker);
+  // guardrails reset since they are session-only.
+  try {
+    const state = loadFeatureState(slug, DEFAULT_DIR);
+    if (state) {
+      handler.setActiveFeatureState(state);
+      log.info(
+        `[workflow] activateWorkflowForFeature: reconstructed state from ${featureStateFilePath(slug, DEFAULT_DIR)}`,
+      );
+    }
+  } catch (err) {
+    log.warn(`[workflow] activateWorkflowForFeature: failed to reconstruct state: ${err}`);
+  }
+
+  // Now advance to the target phase
+  handler.setCurrentPhase(phase);
+  log.info(`[workflow] activateWorkflowForFeature: slug=${slug}, phase=${phase}`);
+
+  // Apply model override for the new phase
+  const refs = globalThis.__piWorkflowMonitor?.modelOverrideRefs;
+  if (refs?.pi && ctx && applyModelOverrideForPhase) {
+    await applyModelOverrideForPhase(refs.pi, ctx, phase);
+  }
+}
+
+/**
+ * Cross-extension bridge for kanban auto-agent: resumes a feature that has
+ * prior session history. Reconstructs workflow state from the feature state
+ * file WITHOUT advancing to a new phase.
+ */
+export async function resumeWorkflowForFeature(
+  slug: string,
+  ctx: ExtensionContext | null,
+  applyModelOverrideForPhase: ((pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>) | null,
+): Promise<FeatureState | null> {
+  const handler = globalThis.__piWorkflowMonitor?.handler ?? null;
+  if (!handler) {
+    log.warn(`[workflow] resumeWorkflowForFeature: handler not registered on globalThis, skipping (slug=${slug})`);
+    return null;
+  }
+
+  // Set the active feature env so subagent tool resolves the right slug.
+  setActiveFeatureEnv(slug);
+
+  // Reconstruct handler state from feature state file
+  let featureState: FeatureState | null = null;
+  try {
+    featureState = loadFeatureState(slug, DEFAULT_DIR);
+    if (featureState) {
+      handler.setActiveFeatureState(featureState);
+      log.info(
+        `[workflow] resumeWorkflowForFeature: reconstructed state from ${featureStateFilePath(slug, DEFAULT_DIR)}`,
+      );
+    }
+  } catch (err) {
+    log.warn(`[workflow] resumeWorkflowForFeature: failed to reconstruct state: ${err}`);
+  }
+
+  // Sync env vars from restored state
+  syncEnvVarsFromState(handler);
+
+  // Capture base commit SHA if in implement phase and not yet captured (path 10 — setFullState bypasses onPhaseChange)
+  if (featureState && handler.getWorkflowState()?.currentPhase === "implement" && !featureState.git.baseCommitSha) {
+    captureBaseCommitSha(featureState);
+  }
+
+  // Apply model override for the restored phase
+  const refs = globalThis.__piWorkflowMonitor?.modelOverrideRefs;
+  if (refs?.pi && ctx && applyModelOverrideForPhase) {
+    const currentPhase = handler.getWorkflowState()?.currentPhase;
+    if (currentPhase) {
+      await applyModelOverrideForPhase(refs.pi, ctx, currentPhase);
+    }
+  }
+
+  log.info(
+    `[workflow] resumeWorkflowForFeature: slug=${slug}, currentPhase=${handler.getWorkflowState()?.currentPhase ?? "null"}`,
+  );
+  return featureState;
+}
+
+/**
+ * Capture the base commit SHA and branch name for a feature at execution start.
+ * Called from onPhaseChange (when entering implement phase) and resumeWorkflowForFeature.
+ * Guarded by !baseCommitSha — only captures once per feature.
+ */
+export function captureBaseCommitSha(featureState: FeatureState): void {
+  if (featureState.git.baseCommitSha) return;
+
+  const sha = getHeadSha(PROCESS_CWD);
+  if (sha) {
+    featureState.git.baseCommitSha = sha;
+  } else {
+    log.warn(
+      `[workflow] captureBaseCommitSha: git rev-parse HEAD failed for ${featureState.featureSlug}, baseCommitSha remains null`,
+    );
+    // Git unavailable — skip saving unchanged state
+    return;
+  }
+
+  if (!featureState.git.branch) {
+    const settings = getSettings();
+    // worktree policy uses conventional "feature/{slug}" branch name
+    featureState.git.branch =
+      settings.branchPolicy === "worktree" ? `feature/${featureState.featureSlug}` : getBranchOrShortSha(PROCESS_CWD);
+  }
+
+  saveFeatureState(featureState, DEFAULT_DIR);
+}
+
+/**
+ * Track the current session file in the feature state for context recovery.
+ * Skips subagent sessions. Idempotent — won't duplicate.
+ */
+export function trackSessionFileInState(ctx: ExtensionContext, slug: string): void {
+  // Skip subagent sessions — only track root sessions for context recovery
+  if (isSubagentSession()) {
+    log.info(`[trackSessionFile] skipped: subagent session (slug=${slug})`);
+    return;
+  }
+  if (ctx.sessionManager?.getSessionFile) {
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    if (sessionFile) {
+      // Active feature: mutate the handler's authoritative record (single source of
+      // truth) and write it through. Non-active feature (e.g. a registered
+      // sub-feature): the handler holds no record, so load/mutate/save the file.
+      const handler = globalThis.__piWorkflowMonitor?.handler ?? null;
+      const active = handler?.getActiveFeatureState();
+      const featureState = active?.featureSlug === slug ? active : loadFeatureState(slug, DEFAULT_DIR);
+      if (featureState && !featureState.sessionFiles.includes(sessionFile)) {
+        featureState.sessionFiles.push(sessionFile);
+        saveFeatureState(featureState, DEFAULT_DIR);
+        log.info(
+          `[trackSessionFile] tracked: sessionFile=${sessionFile} (slug=${slug}, total=${featureState.sessionFiles.length})`,
+        );
+      } else if (!featureState) {
+        log.warn(`[trackSessionFile] no feature state found for slug=${slug}`);
+      } else {
+        log.info(`[trackSessionFile] already tracked: sessionFile=${sessionFile} (slug=${slug})`);
+      }
+    } else {
+      log.warn(`[trackSessionFile] sessionFile is null/empty (slug=${slug}, hasUI=${ctx.hasUI})`);
+    }
+  } else {
+    log.warn(`[trackSessionFile] no sessionManager or getSessionFile (slug=${slug}, hasUI=${ctx.hasUI})`);
+  }
+}
+
+/**
+ * Recover missing workflow artifacts from disk by checking for expected files.
+ */
+export function recoverArtifactsFromDisk(handler: FeatureSession): void {
+  const active = handler.getActiveFeatureState();
+  if (!active) return;
+  const slug = active.featureSlug;
+  const ws = active.workflow;
+
+  // Design docs may live in either recognized dir (committed or local); recovery scans BOTH
+  // so a doc written under either mode is found regardless of the current designDocStorage mode.
+  const designDirs = DESIGN_DOC_DIRS.map((d) => path.join(process.cwd(), d));
+  const taskPlansDir = path.join(process.cwd(), FY_TASK_PLANS_DIR);
+  const view = { currentPhase: ws.currentPhase, completedAt: active.completedAt };
+  const workflowPatch: { designDoc?: string; planDoc?: string } = {};
+
+  // Check for design doc if design artifact is missing
+  if (!ws.designDoc && (isPhaseActive(view, "design") || isPhaseDone(view, "design"))) {
+    const designFile = `${slug}-design.md`;
+    for (const dir of designDirs) {
+      const designPath = path.join(dir, designFile);
+      if (fs.existsSync(designPath)) {
+        log.info(`[workflow] Recovered missing design artifact from disk: ${designPath}`);
+        workflowPatch.designDoc = designPath;
+        break;
+      }
+    }
+  }
+
+  // Check for task-plan doc if plan artifact is missing
+  if (!ws.planDoc && (isPhaseActive(view, "plan") || isPhaseDone(view, "plan"))) {
+    const planFile = `${slug}-task-plan.md`;
+    const planPath = path.join(taskPlansDir, planFile);
+    if (fs.existsSync(planPath)) {
+      log.info(`[workflow] Recovered missing plan artifact from disk: ${planPath}`);
+      workflowPatch.planDoc = planPath;
+    }
+  }
+
+  if (Object.keys(workflowPatch).length > 0) {
+    // Apply the recovered docs to the in-memory record (re-seeds the workflow
+    // engine) and mirror into the phase-data objects, then write-through.
+    const patched: FeatureState = {
+      ...active,
+      workflow: { ...ws, ...workflowPatch },
+      design: { ...active.design, doc: workflowPatch.designDoc ?? active.design.doc },
+      plan: { ...active.plan, doc: workflowPatch.planDoc ?? active.plan.doc },
+    };
+    handler.setFullState({ featureState: patched });
+    saveFeatureState(patched, DEFAULT_DIR);
+  }
+}
+
+/**
+ * Handle a sub-feature write when a different feature is already active.
+ * Checks the kanban DB for a registered sub-feature card. If found, creates/updates
+ * sub-feature state. If not found (hallucinated filename), silently skips.
+ */
+export async function handleSubFeatureWrite(
+  ctx: ExtensionContext,
+  subSlug: string,
+  subFilePath: string,
+  artifactType: "design" | "plan",
+  activeSlugForLog: string | null,
+): Promise<void> {
+  try {
+    const { getDatabaseInstance } = await import("../kanban/kanban-bridge.js");
+    const kanbanDb = getDatabaseInstance();
+    if (kanbanDb) {
+      const { detectProject } = await import("../kanban/data/kanban-detect-project.js");
+      const projectId = await detectProject(kanbanDb, process.cwd());
+      const kanbanFeature = projectId ? kanbanDb.findFeatureBySlug(subSlug, projectId) : null;
+      if (kanbanFeature) {
+        // Registered sub-feature
+        const existingSubState = loadFeatureState(subSlug, DEFAULT_DIR);
+        if (existingSubState) {
+          // State already exists — just update the doc artifact
+          const hasDoc = artifactType === "design" ? !!existingSubState.design.doc : !!existingSubState.plan.doc;
+          if (!hasDoc) {
+            if (artifactType === "design") existingSubState.design.doc = subFilePath;
+            else existingSubState.plan.doc = subFilePath;
+            saveFeatureState(existingSubState, DEFAULT_DIR);
+          }
+        } else {
+          // No state yet — create new sub-feature state
+          const designDoc = artifactType === "design" ? subFilePath : "";
+          const subState = createFeatureStateForSubFeature(subSlug, designDoc);
+          subState.featureId = kanbanFeature.id;
+          if (artifactType === "plan") {
+            subState.plan.doc = subFilePath;
+          }
+          saveFeatureState(subState, DEFAULT_DIR);
+          trackSessionFileInState(ctx, subSlug);
+          // Update kanban feature columns
+          try {
+            const kanbanUpdate: {
+              featureId: number;
+              stateFile: string;
+              designDoc?: string;
+              planDoc?: string;
+            } = {
+              featureId: kanbanFeature.id,
+              stateFile: featureStateFilePath(subSlug, DEFAULT_DIR),
+            };
+            if (artifactType === "design") {
+              kanbanUpdate.designDoc = subFilePath;
+            } else {
+              kanbanUpdate.planDoc = subFilePath;
+            }
+            kanbanDb.updateFeature(kanbanUpdate);
+          } catch (e) {
+            log.error(`[workflow] Failed to update kanban feature columns for sub-feature ${subSlug}:`, e);
+          }
+        }
+        log.info(
+          `[workflow] Registered sub-feature ${subSlug} ${artifactType} doc written while ${activeSlugForLog} is active`,
+        );
+      }
+      // No kanban card — silently skip (hallucinated filename)
+    }
+  } catch (e) {
+    log.error(`[workflow] handleSubFeatureWrite failed for ${subSlug}:`, e);
+  }
+}

package/src/state/feature-record-store.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * FeatureRecordStore — the persistent tier holder.
+ *
+ * Wraps the active feature record (`FeatureState | null`) in an explicit holder
+ * class so the persistence-fate boundary is structural, not conventional. Disk
+ * serialization goes through this holder ONLY — the sibling SessionGuardrails
+ * holder is structurally unreachable from persistence.
+ *
+ * Holds the single source of truth: get() returns the live reference (not a
+ * clone), so callers mutate it in place then persist via saveFeatureState.
+ */
+
+import type { FeatureState } from "./feature-state.js";
+
+export interface FeatureRecordStore {
+  /** The active feature record (live reference — mutate then persist), or null when idle. */
+  get(): FeatureState | null;
+  /** Replace the record. Pass null to clear. Stores the live reference (no clone). */
+  set(record: FeatureState | null): void;
+  /** Clear to idle (no active feature). */
+  clear(): void;
+}
+
+/** Construct the persistent-tier holder. Starts empty (no active feature). */
+export function createFeatureRecordStore(): FeatureRecordStore {
+  let record: FeatureState | null = null;
+  return {
+    get: () => record,
+    set: (rec) => {
+      record = rec;
+    },
+    clear: () => {
+      record = null;
+    },
+  };
+}

package/src/state/feature-session.ts

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { getHeadSha, getWorkingTreeFiles } from "../git/git-queries.js";
+import { createSessionGuardrails } from "../guardrails/session-guardrails.js";
+import { TddEnforcement, type TddGitDeps, type TddViolation } from "../guardrails/tdd-enforcement.js";
+import { type Phase, PhaseProgression, type PhaseProgressionState } from "../phases/phase-progression.js";
+import { type RouteConfig, type RouteResult, WorkflowRouter } from "../phases/workflow-router.js";
+import { createFeatureRecordStore } from "./feature-record-store.js";
+
+export type Violation = TddViolation;
+
+/** Outcome of inspecting a tool call for discipline violations — bare nullable (a violation, or null). */
+export type ToolCallInspection = Violation | null;
+
+// Verification gate + GuardrailsState shapes + createGuardrailsState factory live in
+// the SessionGuardrails holder (guardrails/session-guardrails.ts) — ownership aligns
+// with responsibility. Re-exported here for the FeatyardState composition below.
+export type { GuardrailsState, VerificationGate } from "../guardrails/session-guardrails.js";
+export { createGuardrailsState } from "../guardrails/session-guardrails.js";
+
+import type { GuardrailsState, VerificationGate } from "../guardrails/session-guardrails.js";
+
+/**
+ * The session-resident wrapper: the ACTIVE feature record held in memory as the
+ * single source of truth, composed with the session-only guardrails tier.
+ * featureState === null means no feature is active.
+ */
+export interface FeatyardState {
+  featureState: import("../state/feature-state.js").FeatureState | null;
+  guardrailsState: import("../guardrails/session-guardrails.js").GuardrailsState;
+}
+
+/** Sparse update applied to a featyard session (only set sections change). */
+export type FeatyardStatePatch = {
+  featureState?: import("../state/feature-state.js").FeatureState | null;
+  guardrailsState?: Partial<import("../guardrails/session-guardrails.js").GuardrailsState>;
+};
+
+/** Sentinel for "no feature is active" — pass to setActiveFeatureState to clear it. */
+export const NO_ACTIVE_FEATURE_STATE: import("../state/feature-state.js").FeatureState | null = null;
+
+/** Real git-queries-backed TDD deps (the default for non-test handler construction). */
+const defaultTddGitDeps: TddGitDeps = {
+  workingTreeFiles: getWorkingTreeFiles,
+  isGitRepo: (cwd: string) => getHeadSha(cwd) !== null,
+};
+
+export interface FeatureSession {
+  /**
+   * TDD write-order check for a source-file write/edit. Stateless git query
+   * (tests-written-before-source); returns the violation or null. The caller has
+   * already classified the tool call as a write/edit with a path.
+   */
+  checkSourceWriteOrder(path: string): ToolCallInspection;
+  /**
+   * A source file was written/edited — clear the "tests passed since last edit"
+   * credit so the pre-commit gate requires a fresh test run before committing.
+   */
+  recordSourceWrite(): void;
+  /**
+   * Record the outcome of a test run. Passing satisfies the pre-commit gate;
+   * failing drops it to not-run (don't commit red). The caller has already
+   * classified the command as a test run and detected the outcome.
+   */
+  recordTestOutcome(passed: boolean): void;
+  handleReadOrInvestigation(toolName: string, path: string): void;
+  getVerificationState(): VerificationGate;
+  recordVerificationWaiver(): void;
+  /** Process a skill invocation input (e.g. /skill:fy-plan); returns whether the phase changed. */
+  processSkillInput(text: string): boolean;
+  /** Record a doc write into the phase progression; returns whether state changed. */
+  recordDoc(path: string): boolean;
+  getWorkflowState(): PhaseProgressionState | null;
+  getFullState(): FeatyardState;
+  setFullState(snapshot: FeatyardStatePatch): void;
+  restoreWorkflowStateFromBranch(branch: SessionEntry[]): void;
+  /** Extension-initiated: current phase verified done → route one step (review/uat-aware). Returns the routing decision; callers persist + handle `{completed}` (markFeatureDone). */
+  completeCurrentWorkflowPhase(config: RouteConfig): RouteResult;
+  /** User/explicit move to any phase (no guards). */
+  setCurrentPhase(phase: Phase): boolean;
+  /** Set the design/plan review-active flag (recorded into the live progression state). */
+  setReviewActiveFlag(phase: "design" | "plan", value: boolean): void;
+  /** The active feature record held in memory as single source of truth; null when no feature is active. */
+  getActiveFeatureState(): import("../state/feature-state.js").FeatureState | null;
+  /** Load/swap/clear the active feature record. Seeds the workflow tracker + resets session guardrails. */
+  setActiveFeatureState(state: import("../state/feature-state.js").FeatureState | null): void;
+  /** Update guardrails (verification) in place. */
+  setGuardrailsState(patch: Partial<GuardrailsState>): void;
+  getGuardrailsState(): GuardrailsState;
+  getActiveFeatureSlug(): string | null;
+  resetState(): void;
+}
+
+export interface FeatureSessionOptions {
+  /** Called whenever a phase-changing operation succeeds (advanceTo, completeCurrent, skipPhases, onInputText, setCurrentPhaseDirect, transitionToUat). */
+  onPhaseChange?: () => void;
+  /** TDD git deps (test seam); defaults to the real git-queries-backed functions. */
+  tddGitDeps?: TddGitDeps;
+}
+
+export function createFeatureSession(options: FeatureSessionOptions | null): FeatureSession {
+  const enforcement = new TddEnforcement(options?.tddGitDeps ?? defaultTddGitDeps);
+  const tracker = new PhaseProgression();
+  const router = new WorkflowRouter(tracker);
+  // Persistent tier: the active feature record held in memory as single source of
+  // truth (write-through to its file by persistState). Disk serialization goes
+  // through this holder ONLY — the SessionGuardrails holder is unreachable.
+  const recordStore = createFeatureRecordStore();
+  // Transient tier: session-only guardrail state (pre-commit verification gate).
+  // Never persisted; structurally unreachable from serialization.
+  const guardrails = createSessionGuardrails();
+
+  /** Push the workflow engine state into the active feature record (source of truth). */
+  const syncTrackerToFeature = (): void => {
+    const activeFeatureState = recordStore.get();
+    if (!activeFeatureState) return;
+    const ws = tracker.getState();
+    activeFeatureState.workflow = ws;
+    // mirror doc slots into the phase-data objects
+    activeFeatureState.design.doc = ws.designDoc;
+    activeFeatureState.plan.doc = ws.planDoc;
+  };
+
+  return {
+    checkSourceWriteOrder(path: string): ToolCallInspection {
+      return enforcement.checkSourceWrite(path);
+    },
+
+    recordSourceWrite(): void {
+      // Editing source clears the "tests passed since last edit" credit.
+      guardrails.resetOnSourceWrite();
+    },
+
+    handleReadOrInvestigation(_toolName: string, _path: string): void {
+      // No-op: debug-investigation tracking removed.
+    },
+
+    recordTestOutcome(passed: boolean): void {
+      // A passing test run satisfies the pre-commit verification gate; a failing
+      // run drops it back to "not-run" (don't commit red).
+      guardrails.markPassed(passed);
+    },
+
+    getVerificationState() {
+      return guardrails.getVerification();
+    },
+
+    recordVerificationWaiver() {
+      guardrails.waive();
+    },
+
+    processSkillInput(text: string) {
+      const changed = tracker.onInputText(text);
+      if (changed) {
+        syncTrackerToFeature();
+        options?.onPhaseChange?.();
+      }
+      return changed;
+    },
+
+    recordDoc(path: string) {
+      const changed = tracker.onFileWritten(path);
+      if (changed) {
+        syncTrackerToFeature();
+        options?.onPhaseChange?.();
+      }
+      return changed;
+    },
+
+    getWorkflowState() {
+      return tracker.getState();
+    },
+
+    getFullState(): FeatyardState {
+      return {
+        featureState: recordStore.get(),
+        guardrailsState: guardrails.getSnapshot(),
+      };
+    },
+
+    setFullState(snapshot: FeatyardStatePatch) {
+      if (snapshot.featureState !== undefined) {
+        // Load/swap the active feature record and seed the workflow engine from it.
+        recordStore.set(snapshot.featureState);
+        const activeFeatureState = recordStore.get();
+        if (activeFeatureState) {
+          tracker.setState(activeFeatureState.workflow);
+        }
+      }
+      // Backward-tolerant: older snapshots carried a `tdd` slice (now removed);
+      // only the `verification` field is read, and absent → keep current.
+      if (snapshot.guardrailsState?.verification !== undefined) {
+        guardrails.setSnapshot({ verification: snapshot.guardrailsState.verification });
+      }
+    },
+
+    restoreWorkflowStateFromBranch(branch: SessionEntry[]) {
+      const state = PhaseProgression.reconstructFromBranch(branch);
+      if (state) {
+        tracker.setState(state);
+        syncTrackerToFeature();
+      }
+    },
+
+    completeCurrentWorkflowPhase(config) {
+      const result = router.completeCurrent(config);
+      if (result) {
+        syncTrackerToFeature();
+        options?.onPhaseChange?.();
+      }
+      return result;
+    },
+
+    setCurrentPhase(phase) {
+      const changed = tracker.setCurrentPhase(phase);
+      if (changed) {
+        syncTrackerToFeature();
+        options?.onPhaseChange?.();
+      }
+      return changed;
+    },
+
+    setReviewActiveFlag(phase: "design" | "plan", value: boolean): void {
+      // review-active flags are durable phase data on the feature record; mirror
+      // into the active record so the in-memory copy stays authoritative.
+      const activeFeatureState = recordStore.get();
+      if (activeFeatureState) activeFeatureState[phase].reviewActive = value;
+    },
+
+    getActiveFeatureState() {
+      return recordStore.get();
+    },
+
+    setActiveFeatureState(state) {
+      recordStore.set(state);
+      if (state) {
+        tracker.setState(state.workflow);
+      }
+      // Guardrails are session-only: reset when the active feature changes.
+      guardrails.reset();
+    },
+
+    getGuardrailsState() {
+      return guardrails.getSnapshot();
+    },
+
+    setGuardrailsState(patch) {
+      if (patch.verification !== undefined) guardrails.setSnapshot({ verification: patch.verification });
+    },
+
+    getActiveFeatureSlug(): string | null {
+      return recordStore.get()?.featureSlug ?? null;
+    },
+
+    resetState() {
+      recordStore.clear();
+      tracker.setState(new PhaseProgression().getState());
+      guardrails.reset();
+    },
+  };
+}