avtc-pi-featyard 1.1.0

package/src/index.ts

@@ -0,0 +1,598 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Workflow Monitor extension — featyard orchestration.
+ *
+ * Wires the tool_call / tool_result / session event handlers that drive a
+ * feature through its phases (design → plan → implement → verify → review →
+ * uat → finish): TDD write-order enforcement, guardrail warnings, review-loop
+ * tracking, worktree + feature-state management, and the TUI widget.
+ */
+
+import { homedir } from "node:os";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerUatCommands } from "./commands/auto-agent-commands.js";
+import { registerWorkflowCommands } from "./commands/workflow-commands.js";
+import { createCompaction } from "./compaction/compact-handler.js";
+import { registerAllEvents } from "./events/index.js";
+import { resolveBaseBranch as _resolveBaseBranch } from "./git/resolve-base-branch.js";
+// --- Shared utility functions (in helper modules to eliminate circular imports) ---
+import { cleanupWorktreeOnFinishWrapper, createGitExec, syncWorktreeStatus } from "./git/worktrees/worktree-helpers.js";
+import { createWorktree } from "./git/worktrees/worktree-lifecycle.js";
+import {
+  applyExtensionOverride,
+  buildExtensionOverride,
+  resetExtensionOverride,
+} from "./guardrails/file-classifier.js";
+import { createGuardrails } from "./guardrails/guardrails-engine.js";
+import { getTodoCompletedItemId, getTodoInProgressItem } from "./integrations/todo-integration.js";
+import { createAgentLifecycle } from "./kanban/auto-agent/auto-agent-events.js";
+import * as autoAgentNotify from "./kanban/auto-agent/auto-agent-notify.js";
+import kanbanExtension from "./kanban/kanban-bridge.js";
+import { createKanbanTurnHandlers } from "./kanban/kanban-turn-handlers.js";
+import { getLogFilePath, log } from "./log.js";
+import { clearActiveFeatureEnv, syncEnvVarsFromState } from "./phases/env-sync.js";
+import { createExecutionModeApplier } from "./phases/execution-mode.js";
+import type { Phase } from "./phases/phase-progression.js";
+import { createReviewLoopHandlers } from "./review/review-loops.js";
+import { DEFAULT_GLOBAL_DIR, getSettings, loadFeatyardConfig, resolveReviewSkill } from "./settings/settings-ui.js";
+import { PiCtx } from "./shared/types.js";
+// --- Orchestrator refs (shared module-level state for child modules) ---
+import * as orchestratorRefs from "./shared/workflow-refs.js";
+import { subscribeToNotificationApi } from "./snippets/vendored/subscribe-to-notifications.js";
+import { archiveDesignsOlderThan, archiveStaleArtifacts, MS_PER_DAY } from "./state/archive-artifacts.js";
+import {
+  type EnsureFeatyardJunctionResult,
+  ensureFeatyardJunction,
+  resolveArchiveBase,
+  resolveDesignsDirs,
+} from "./state/artifact-junction.js";
+import {
+  activateWorkflowForFeature as _activateWorkflowForFeature,
+  resumeWorkflowForFeature as _resumeWorkflowForFeature,
+  captureBaseCommitSha,
+  handleSubFeatureWrite,
+  recoverArtifactsFromDisk,
+} from "./state/feature-management.js";
+import { createFeatureSession, NO_ACTIVE_FEATURE_STATE } from "./state/feature-session.js";
+import type { FeatureState } from "./state/feature-state.js";
+import {
+  createSessionLifecycle,
+  setWorkflowInitiatedNewSession,
+  wireSessionLifecycleBridge,
+} from "./state/session-lifecycle.js";
+import { isSubagentSession, reconstructState } from "./state/state-persistence.js";
+import { registerPhaseReady } from "./tools/phase-ready.js";
+import { registerTaskReadyAdvance } from "./tools/task-ready-advance.js";
+
+// Idempotent wiring guard. featyard can be bundled into the avtc-pi umbrella
+// AND installed standalone — whichever copy loads first wires, the rest no-op.
+const WIRED_KEY = "__avtcPiFeatyardWired";
+type GlobalWithWired = typeof globalThis & { [WIRED_KEY]?: boolean };
+
+export { stripFrontmatter } from "@earendil-works/pi-coding-agent";
+export { safeSetEditorText } from "./compaction/safe-editor-write.js";
+export { resolveBaseBranch as _resolveBaseBranch } from "./git/resolve-base-branch.js";
+export {
+  bashSingleQuote,
+  cleanupWorktreeOnFinishWrapper as _cleanupWorktreeOnFinish,
+  createGitExec,
+  getActiveWorktreeContext,
+  WORKTREE_STATUS_KEY,
+} from "./git/worktrees/worktree-helpers.js";
+export { selectValue } from "./ui/select-dialog.js";
+// --- Re-exports for backward compatibility with test imports ---
+export { reconstructState };
+
+export async function _ensureWorktreeForExecution(
+  featureState: FeatureState,
+  ctx: ExtensionContext,
+): Promise<FeatureState> {
+  const settings = getSettings();
+  if (settings.branchPolicy !== "worktree") return featureState;
+  if (featureState.git.worktreePath) return featureState; // already has worktree
+
+  const slug = featureState.featureSlug;
+  const baseBranch = await _resolveBaseBranch(ctx);
+  const gitExec = createGitExec(ctx);
+
+  try {
+    const result = await createWorktree({
+      slug,
+      baseBranch,
+      exec: gitExec,
+    });
+
+    // .featyard must never be tracked. git worktree add may have checked out a tracked.featyard/ as a
+    // real directory; untrack it from the worktree index (aligns with the.featyard guardrail) so
+    // the worktree's git status stays clean and the implementer never sees a wall of
+    // "deleted.featyard/..." files. --ignore-unmatch makes this a no-op when.featyard is untracked.
+    // Non-fatal: a failure here (e.g. exotic git state) only leaves stale index entries; the
+    // junction is still created below, so log rather than halt worktree setup.
+    const rmResult = await gitExec("git rm -r --cached --ignore-unmatch .featyard", { cwd: result.path });
+    if (rmResult.exitCode !== 0) {
+      log.info(
+        `[workflow] git rm --cached .featyard in worktree ${result.path} exited ${rmResult.exitCode} (non-fatal): ${rmResult.stdout.trim()}`,
+      );
+    }
+
+    // Ensure <worktree>/.featyard is a junction to the shared external store (same key/dir the
+    // main repo uses). ensureFeatyardJunction heals any real-directory / wrong-target entry into
+    // the correct junction. Required before the implementer subagent runs in this worktree
+    // (its skills read/write relative.featyard/... paths, resolved against the worktree cwd).
+    // Worktree checkout: a real-dir.featyard here is the git-checked-out tracked content (also in
+    // git + the external store), so delete-and-replace is safe — avoids leaving stale backups.
+    ensureFeatyardJunction(
+      result.path,
+      settings.branchPolicy ?? "current-branch",
+      process.env.PI_FY_HOME ?? homedir(),
+      "delete",
+    );
+
+    // All setup steps succeeded — commit the worktree path.
+    featureState.git.worktreePath = result.path;
+    featureState.git.baseBranch = baseBranch; // store for finish phase
+    log.info(`[workflow] Created worktree for ${slug}: ${result.path}`);
+    // Footer indicator (syncWorktreeStatus is the single source of truth for the
+    // indicator; also re-applied on every UI restore so it survives a reload).
+    syncWorktreeStatus(featureState);
+  } catch (err: unknown) {
+    // Programming errors (TypeError/ReferenceError/SyntaxError) propagate — they are bugs.
+    if (err instanceof TypeError || err instanceof ReferenceError || err instanceof SyntaxError) {
+      throw err;
+    }
+    // Predictable setup failure (git error,.featyard healing, path validation). In worktree mode
+    // execution cannot fall back to the main repo (the implementer is dispatched into the
+    // worktree with path-rewriting interception), so HALT visibly without throwing (pi must
+    // not exit over this). The caller checks worktreePath and skips dispatch when unset.
+    const errMsg = err instanceof Error ? err.message : String(err);
+    // Trace arg carries err — the logger appends it; do not also inline it (would double-print).
+    log.error(`[workflow] Worktree setup failed for ${slug}`, err);
+    if (ctx.hasUI && ctx.ui?.notify) {
+      ctx.ui.notify(
+        `Worktree setup failed for "${slug}": ${errMsg} — log: ${getLogFilePath(new Date())}. To continue without a worktree, set branchPolicy="current-branch".`,
+        "error",
+      );
+    }
+    // Leave worktreePath unset so the caller halts (does not dispatch the implementer).
+  }
+  return featureState;
+}
+
+export const {
+  expandSkillCommand,
+  substituteTemplates,
+  resolveLoopIndex,
+  applyModelOverrideForPhase,
+  getActiveFeatureSlug,
+} = orchestratorRefs;
+export type { SubstitutionResult } from "./shared/workflow-refs.js";
+
+/** Test-only: clear active feature slug while preserving handler and workflow state */
+export function _clearActiveFeatureSlug(): void {
+  orchestratorRefs.getHandlerRef()?.setActiveFeatureState(NO_ACTIVE_FEATURE_STATE);
+  clearActiveFeatureEnv();
+}
+
+// globalThis key for cross-module-instance handler reference.
+// Pi loads each extension with jiti moduleCache:false, so kanban/index.ts's import
+// of workflow-monitor creates a separate module instance with its own _handlerRef (null).
+// Using globalThis.__piWorkflowMonitor ensures all instances share the same handler.
+// Initialization order: workflow-monitor factory (this file) MUST initialize
+// __piWorkflowMonitor before any kanban code runs. This is guaranteed because:
+// 1. package.json pi.extensions lists workflow-monitor.ts, NOT kanban/index.ts
+// 2. kanban/ is loaded via dynamic imports from workflow-monitor sub-modules
+// 3. KanbanExtensionDeps provides typed callbacks instead of direct bridge access
+
+export async function activateWorkflowForFeature(
+  slug: string,
+  phase: Phase,
+  ctx: ExtensionContext | null,
+): Promise<void> {
+  await _activateWorkflowForFeature(slug, phase, ctx, applyModelOverrideForPhase);
+}
+
+export async function resumeWorkflowForFeature(
+  slug: string,
+  ctx: ExtensionContext | null,
+): Promise<FeatureState | null> {
+  return _resumeWorkflowForFeature(slug, ctx, applyModelOverrideForPhase);
+}
+
+// globalThis keys for workflow-initiated new-session state.
+// Set before ctx.newSession by /fy:next.
+// Checked in session_start (reason="new") to distinguish user-initiated vs workflow-initiated /new.
+
+export { applyModelOverride } from "./phases/phase-transitions.js";
+export { resolveReviewLoopDecision } from "./review/review-loops.js";
+export { trackSessionFileInState } from "./state/feature-management.js";
+export { setWorkflowInitiatedNewSession };
+
+export const {
+  _getExpectedSkill,
+  _resetFeatureState,
+  _incrementEmptyLoop,
+  _resetEmptyLoop,
+  _getEmptyLoopsForSlug,
+  _resetAllEmptyLoops,
+  _isReviewerSkipped,
+  _getReviewerEmptyLoops,
+  getStateFilePath,
+} = orchestratorRefs;
+
+export { handleSubFeatureWrite } from "./state/feature-management.js";
+
+import _settingsExtension from "./settings/settings-ui.js";
+
+const settingsExtension = _settingsExtension;
+
+import { initGuardrailIntegration } from "./integrations/parallel-work-guardrail-integration.js";
+import { initSubagentIntegration } from "./integrations/subagent-integration.js";
+import { initTodoIntegration } from "./integrations/todo-integration.js";
+
+/**
+ * Build the background-sweep options, reading the threshold from settings at call time. Extracted
+ * as an exported seam so the setting→threshold wiring is testable without driving the 24h timer
+ * (the on-start dispatch is gated off in the test sandbox). The sweep closure delegates here, so a
+ * regression hardcoding/mistyping the threshold fails this contract ((c)).
+ */
+export function buildArchiveSweepOptions(
+  externalDir: string,
+  archiveBase: string,
+): {
+  externalDir: string;
+  archiveBase: string;
+  maxAgeDays: number;
+} {
+  return {
+    externalDir,
+    archiveBase,
+    maxAgeDays: getSettings().autoArchiveArtifactsOlderThanDays,
+  };
+}
+
+export default async function (pi: ExtensionAPI) {
+  const g = globalThis as GlobalWithWired;
+  if (g[WIRED_KEY]) return;
+  g[WIRED_KEY] = true;
+
+  subscribeToNotificationApi(pi);
+
+  // Settings
+  settingsExtension(pi);
+
+  // Integration wiring (all sync — subscribeToTodo returns lazy proxy).
+  // Each integration logs via its own avtc-pi-logger singleton (no shared logger injection).
+  initGuardrailIntegration(pi);
+  initSubagentIntegration(pi);
+  const todoApi = initTodoIntegration(pi);
+
+  // Workflow monitor
+  try {
+    await initWorkflowMonitor(pi, { todoApi });
+  } catch (err) {
+    // Clean up partially-initialized globalThis bridge on failure
+    delete globalThis.__piWorkflowMonitor;
+    throw err;
+  }
+}
+
+async function initWorkflowMonitor(pi: ExtensionAPI, _deps: { todoApi: ReturnType<typeof initTodoIntegration> }) {
+  // Ensure the.featyard junction for external artifact storage (throws on failure — visible + debuggable).
+  // Runs at init (cwd is fixed for the pi process). Cross-platform; aggregates worktrees.
+  // When PI_FY_HOME is set we're in the test sandbox → be best-effort (never block extension load
+  // on test-filesystem quirks). Production (no PI_FY_HOME) throws so real failures surface.
+  const fyHome = process.env.PI_FY_HOME;
+  const testSandbox = fyHome !== undefined;
+  let featyardResult: EnsureFeatyardJunctionResult | undefined;
+  try {
+    // Main-repo/init path: a stray real-dir.featyard is preserved (moved aside) — never lose data.
+    featyardResult = ensureFeatyardJunction(
+      process.cwd(),
+      getSettings().branchPolicy ?? "current-branch",
+      fyHome ?? homedir(),
+      "rename",
+    );
+    if (featyardResult.created) {
+      log.info(
+        `[featyard] .featyard junction ready at .featyard → ${featyardResult.externalDir} (root: ${featyardResult.rootSource})`,
+      );
+    }
+  } catch (err) {
+    if (testSandbox) {
+      log.warn(`[featyard] .featyard junction setup skipped in test sandbox: ${err}`);
+    } else {
+      log.error("[featyard] Failed to set up .featyard junction", err);
+      throw err;
+    }
+  }
+
+  const handler = createFeatureSession({
+    onPhaseChange: () => {
+      const slug = handler.getActiveFeatureSlug();
+      syncEnvVarsFromState(handler);
+      if (handler.getWorkflowState()?.currentPhase === "verify") {
+        orchestratorRefs.getGuardrailsRef()?.setVerifyTestsPassed(false);
+      }
+      // Capture base commit SHA when entering implement phase
+      if (handler.getWorkflowState()?.currentPhase === "implement") {
+        if (slug) {
+          const featureState = handler.getActiveFeatureState();
+          if (featureState && !featureState.git.baseCommitSha) {
+            captureBaseCommitSha(featureState);
+          }
+        }
+      }
+    },
+  });
+  // Set handler ref on orchestrator-refs module for child module access
+  orchestratorRefs.setHandlerRef(handler);
+
+  // Shared getAutoAgentCallback — reads from globalThis.__piKanban bridge
+  const getAutoAgentCallback = () => globalThis.__piKanban?.autoAgentCallback ?? null;
+  orchestratorRefs.setAutoAgentCallbackRef(getAutoAgentCallback);
+  autoAgentNotify.setAutoAgentCallbackGetter(getAutoAgentCallback);
+
+  // Register on globalThis so other module instances (jiti moduleCache:false) can access it
+  if (!globalThis.__piWorkflowMonitor) {
+    globalThis.__piWorkflowMonitor = {
+      handler,
+      requestWidgetUpdate: () => {},
+      performWorkflowReset: () => {},
+      modelOverrideRefs: { pi },
+      finishPhaseWhitelisted: false,
+      workflowInitiatedNewSession: false,
+      newSessionMessage: undefined,
+      archiveTimer: undefined,
+    };
+  } else {
+    globalThis.__piWorkflowMonitor.handler = handler;
+    globalThis.__piWorkflowMonitor.modelOverrideRefs = { pi };
+  }
+  if (!globalThis.__piCtx) {
+    globalThis.__piCtx = new PiCtx();
+  }
+
+  // --- background artifact-archive sweep ((c)/) ---------------------------
+  // Relocates artifact groups whose newest file mtime is older than `autoArchiveArtifactsOlderThanDays`
+  // into a sibling artifacts-archive/ dir. Main session only (subagents skip — durable state is
+  // host-owned); non-blocking (dispatched as a fire-and-forget async sweep). Repeats every 24h; the interval handle
+  // lives on the bridge so session_shutdown clears it (no leak across /reload re-evaluation).
+  if (featyardResult) {
+    const archiveBase = resolveArchiveBase(featyardResult);
+    const designsDirs = resolveDesignsDirs(featyardResult.externalDir, process.cwd());
+    const sweepOpts = () => buildArchiveSweepOptions(featyardResult.externalDir, archiveBase);
+    const runSweep = async () => {
+      try {
+        await archiveStaleArtifacts(sweepOpts());
+      } catch (e) {
+        log.warn(`[featyard] background archive sweep failed: ${e instanceof Error ? e.message : e}`);
+      }
+      // Design-doc sweep: opt-in via autoArchiveDesignsOlderThanDays (null = disabled). Sweeps BOTH
+      // .featyard/designs (local) and docs/featyard/designs (committed) so docs from either mode age out.
+      const designsDays = getSettings().autoArchiveDesignsOlderThanDays;
+      if (designsDays != null) {
+        try {
+          await archiveDesignsOlderThan({
+            designsDirs,
+            archiveBase,
+            days: designsDays,
+          });
+        } catch (e) {
+          log.warn(`[featyard] background design-doc archive sweep failed: ${e instanceof Error ? e.message : e}`);
+        }
+      }
+    };
+    if (!isSubagentSession()) {
+      // Fire once on start (non-blocking), then every 24h. Clear any prior handle first so a
+      // /reload re-evaluation never stacks duplicate timers. The bridge is set just above
+      // (both init branches assign it) — guard defensively regardless.
+      const bridge = globalThis.__piWorkflowMonitor;
+      if (bridge?.archiveTimer) {
+        clearInterval(bridge.archiveTimer);
+      }
+      if (bridge) {
+        // The on-start sweep dispatch is production-only: in the test sandbox (PI_FY_HOME set) the
+        // async sweep's synchronous fs body would race with test setup under isolate:false. The
+        // sweep itself is unit-tested in archive-feature.test.ts; the 24h timer (testable lifecycle)
+        // still starts below so timer-wiring is covered by archive-sweep-timer.test.ts.
+        if (!testSandbox) {
+          runSweep();
+        }
+        bridge.archiveTimer = setInterval(runSweep, MS_PER_DAY);
+      }
+    }
+  }
+
+  // Clear the 24h sweep interval on shutdown so /reload (which re-evaluates this module and
+  // starts a new interval) never leaks the old one. The clear is idempotent and the
+  // session_shutdown router (events/session/session-shutdown.ts) handles teardown.
+
+  function syncSourceExtensions(): void {
+    // source-extensions lives in the avtc-pi-featyard section of ~/.pi/agent/settings.json
+    // (NOT the settings-ui schema, which has no array editor). Read it from the featyard config.
+    const entries = loadFeatyardConfig(DEFAULT_GLOBAL_DIR, process.cwd())["source-extensions"];
+    if (entries) {
+      const result = buildExtensionOverride(entries);
+      if (result.kind === "custom") {
+        applyExtensionOverride(result.extensions);
+      } else {
+        resetExtensionOverride(); // all-invalid or mixed mode — use defaults
+      }
+    } else {
+      resetExtensionOverride();
+    }
+  }
+  syncSourceExtensions();
+
+  // Execution mode applier (createExecutionModeApplier)
+  const applyExecutionMode = createExecutionModeApplier({
+    pi,
+    handler,
+    expandSkillCommand,
+    applyModelOverrideForPhase,
+    resolveBaseBranch: _resolveBaseBranch,
+    ensureWorktreeForExecution: _ensureWorktreeForExecution,
+  });
+
+  // --- Compaction module (DI) ---
+  // NOTE: initTodoIntegration(pi) is called above in the default export.
+  // getTodoCompletedItemId / getTodoInProgressItem delegate to the lazy proxy from subscribeToTodo.
+  // Tests that need them to return data should emit pi-todo:ready
+  // with { getCompletedItemId, getInProgressItem, disableBuiltInFollowUp } on the fake pi.events.
+  const compaction = createCompaction(pi, {
+    handler,
+    expandSkillCommand,
+    resolveReviewSkill,
+    agentJustFinishedRef: orchestratorRefs.getAgentJustFinishedRef(),
+    getCompletedItemId: getTodoCompletedItemId,
+    getInProgressItem: getTodoInProgressItem,
+  });
+
+  // Wire module-level refs through compaction instance (stored in orchestrator-refs)
+  orchestratorRefs.setEmptyLoopRefs({
+    getEmptyLoopsForSlug: compaction.getEmptyLoopsForSlug.bind(compaction),
+    incrementEmptyLoop: compaction.incrementEmptyLoop.bind(compaction),
+    resetEmptyLoop: compaction.resetEmptyLoop.bind(compaction),
+    resetAllEmptyLoops: compaction.resetAllEmptyLoops.bind(compaction),
+    isReviewerSkipped: compaction.isReviewerSkipped.bind(compaction),
+    getReviewerEmptyLoops: compaction.getReviewerEmptyLoops.bind(compaction),
+  });
+  orchestratorRefs.setSkillResolutionRef({
+    getExpectedSkill: compaction.getExpectedSkill.bind(compaction),
+  });
+
+  // Helper to reset per-session tracking state (guardrails parts + compaction delegated)
+  const resetSessionTracking = () => {
+    guardrails.resetTracking();
+    compaction.resetTracking();
+  };
+
+  // getExpectedSkill now delegates to compaction module
+  function getExpectedSkill(): string | null {
+    return compaction.getExpectedSkill();
+  }
+
+  // --- Review loop handlers (must be created before guardrails which uses handleReviewLoopEnd) ---
+  const { handleReviewLoopEnd, handleReviewToUatTransition } = createReviewLoopHandlers({
+    handler,
+    expandSkillCommand,
+    applyModelOverrideForPhase,
+    getAutoAgentCallback,
+    recoverCompactFailure: compaction.recoverCompactFailure,
+    pi,
+  });
+
+  // --- Guardrails module (DI) ---
+  const guardrails = createGuardrails({
+    pi,
+    handler,
+    compaction,
+    expandSkillCommand,
+    applyModelOverrideForPhase,
+    recoverArtifactsFromDisk,
+    handleSubFeatureWrite,
+    applyExecutionMode,
+    createGitExec,
+    handleReviewLoopEnd,
+  });
+  orchestratorRefs.setGuardrailsRef(guardrails);
+
+  // --- Advance-to-Plan-Task Tool ---
+  registerTaskReadyAdvance(pi, compaction.recoverCompactFailure);
+
+  // --- Phase Ready Tool ---
+  // Registered before session-lifecycle so the IPhaseReady interface is available for DI.
+  const phaseReady = registerPhaseReady({
+    pi,
+    handler,
+    guardrails,
+    recoverCompactFailure: compaction.recoverCompactFailure,
+    expandSkillCommand,
+    applyModelOverrideForPhase,
+    handleReviewToUatTransition,
+    applyExecutionMode,
+    cleanupWorktreeOnFinish: cleanupWorktreeOnFinishWrapper,
+    getAutoAgentCallback,
+  });
+  orchestratorRefs.setPhaseReadyRef(phaseReady);
+
+  // --- Session lifecycle domain object (session_start/session_tree bodies + workflow reset) ---
+  const lifecycle = createSessionLifecycle({
+    pi,
+    handler,
+    compaction,
+    guardrails,
+    phaseReady,
+    expandSkillCommand,
+    applyModelOverrideForPhase,
+    resolveBaseBranch: _resolveBaseBranch,
+    ensureWorktreeForExecution: _ensureWorktreeForExecution,
+    resolveLoopIndex,
+  });
+  wireSessionLifecycleBridge(handler, lifecycle);
+
+  // Agent-lifecycle domain object (agent_start/agent_end handler bodies).
+  const agentLifecycle = createAgentLifecycle({
+    pi,
+    handler,
+    compaction,
+    phaseReady,
+    getAutoAgentCallback,
+  });
+
+  // Kanban turn-handler domain object (turn_start/turn_end handler bodies).
+  const kanbanTurn = createKanbanTurnHandlers(() => globalThis.__piWorkflowMonitor?.requestWidgetUpdate?.());
+
+  // Register all pi.on event handlers (events/)
+  registerAllEvents({
+    pi,
+    handler,
+    guardrails,
+    compaction,
+    lifecycle,
+    agentLifecycle,
+    kanbanTurn,
+  });
+
+  // --- Format violation warning based on type ---
+
+  // --- TUI Widget ---
+  // Workflow commands (registerWorkflowCommands)
+  registerWorkflowCommands({
+    pi,
+    handler,
+    expandSkillCommand,
+    applyModelOverrideForPhase,
+    handleReviewToUatTransition,
+    resetSessionTracking,
+    reconstructState,
+    getAutoAgentCallback,
+    performWorkflowReset: lifecycle.performWorkflowReset,
+  });
+
+  // UAT commands (registerUatCommands)
+  registerUatCommands(pi, {
+    handler,
+    getExpectedSkill,
+    getAutoAgentCallback,
+  });
+
+  // --- Kanban extension (absorbed from standalone) ---
+  // Registers /fy:auto-agent, /fy:auto-worker, /fy:auto-designer, /fy:auto-pause,
+  // /fy:kanban, /fy:kanban-release commands + add_to_backlog tool + event handlers
+  await kanbanExtension(pi, {
+    activateWorkflowForFeature,
+    resumeWorkflowForFeature,
+    setWorkflowInitiatedNewSession,
+  });
+
+  // Reload-safety: pi re-evaluates this module fresh on /reload (jiti moduleCache:false), but
+  // globalThis persists across re-evaluation. The guard above short-circuits re-wiring, so an
+  // un-reset flag would leave the extension dead after /reload. session_shutdown fires before
+  // the reload re-evaluation — clear the flag here so the next entry call re-wires cleanly.
+  pi.on("session_shutdown", () => {
+    (globalThis as GlobalWithWired)[WIRED_KEY] = false;
+  });
+}

package/src/integrations/parallel-work-guardrail-integration.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Parallel work guardrail integration layer.
+ *
+ * This is the ONLY file that imports from both avtc-pi-featyard internals
+ * and the vendored subscribe-to-guardrail drop-in.
+ *
+ * Exports initGuardrailIntegration(pi) which calls subscribeToGuardrail
+ * with featyard-specific hooks (isWhitelisted).
+ *
+ * The guardrail wires its own requestAttention via pi-notification — this layer
+ * does NOT provide requestAttention.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { subscribeToGuardrail } from "../snippets/vendored/subscribe-to-parallel-work-guardrail.js";
+
+export function finishPhaseWhitelistCheck(categoryId: string): boolean {
+  return (
+    globalThis.__piWorkflowMonitor?.finishPhaseWhitelisted === true &&
+    (categoryId === "branch-switch" || categoryId === "merge")
+  );
+}
+
+export function initGuardrailIntegration(pi: ExtensionAPI): void {
+  subscribeToGuardrail(pi, finishPhaseWhitelistCheck);
+}