avtc-pi-featyard 1.1.0

package/src/state/session-lifecycle.ts

@@ -0,0 +1,346 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Session lifecycle module — session_start + session_tree domain logic.
+ *
+ * Handles state reconstruction on reload/resume/fork, feature resumption,
+ * branch gating, execution mode dialog, widget setup, and workflow reset.
+ *
+ * All factory-coupled dependencies are injected via SessionLifecycleDeps.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { syncWorktreeStatus } from "../git/worktrees/worktree-helpers.js";
+import { setFinishPhaseWhitelisted } from "../git/worktrees/worktree-lifecycle.js";
+import { notifyAutoAgentBlocked, notifyAutoAgentUnblocked } from "../kanban/auto-agent/auto-agent-notify.js";
+import { log } from "../log.js";
+import {
+  clearActiveFeatureEnv,
+  clearFeatureEnvVars,
+  setActiveFeatureEnv,
+  syncEnvVarsFromState,
+} from "../phases/env-sync.js";
+import { applyModelOverride } from "../phases/phase-transitions.js";
+import { findLatestCustomEntry } from "../shared/session-entries.js";
+import { NO_AGENT_NAME, NO_FEATURE_STATE_OVERRIDE } from "../shared/workflow-refs.js";
+import type { ICompaction, IGuardrails, IPhaseReady, ISessionLifecycle } from "../shared/workflow-types.js";
+import { withCoordinator } from "../snippets/vendored/subscribe-to-dialog-coordinator.js";
+import { type FeatureSession, NO_ACTIVE_FEATURE_STATE } from "../state/feature-session.js";
+import { clearPostTurnFollowUp } from "../state/post-turn-dispatch.js";
+import { NO_FEATURE_STATE, updateWidget } from "../ui/featyard-widget.js";
+import { recoverArtifactsFromDisk, trackSessionFileInState } from "./feature-management.js";
+import {
+  DEFAULT_DIR,
+  type ExpandSkillCommandFn,
+  type FeatureState,
+  stateFilePath as featureStateFilePath,
+  loadFeatureState,
+} from "./feature-state.js";
+import { FEATYARD_STATE_ENTRY_TYPE, isSubagentSession, persistState, reconstructState } from "./state-persistence.js";
+
+export interface SessionLifecycleDeps {
+  pi: ExtensionAPI;
+  handler: FeatureSession;
+  compaction: ICompaction;
+  guardrails: IGuardrails;
+  phaseReady: IPhaseReady;
+  expandSkillCommand: ExpandSkillCommandFn;
+  applyModelOverrideForPhase: (pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>;
+  /** Resolve base branch via UI dialog or auto-detection */
+  resolveBaseBranch: (ctx: ExtensionContext) => Promise<string>;
+  /** Ensure worktree exists for execution if branch policy requires it */
+  ensureWorktreeForExecution: (featureState: FeatureState, ctx: ExtensionContext) => Promise<FeatureState>;
+  /** Resolve loop index for a given stage */
+  resolveLoopIndex: (stage: string) => number;
+}
+
+/**
+ * Set the workflow-initiated new-session flag and optional pending message.
+ */
+export function setWorkflowInitiatedNewSession(message: string | null): void {
+  if (globalThis.__piWorkflowMonitor) {
+    globalThis.__piWorkflowMonitor.workflowInitiatedNewSession = true;
+    if (message) globalThis.__piWorkflowMonitor.newSessionMessage = message;
+  }
+}
+
+/** Read and clear the pending new-session message. Returns undefined if none. */
+function consumeNewSessionMessage(): string | undefined {
+  const msg = globalThis.__piWorkflowMonitor?.newSessionMessage;
+  if (globalThis.__piWorkflowMonitor) globalThis.__piWorkflowMonitor.newSessionMessage = undefined;
+  return msg ?? undefined;
+}
+
+/** Check and consume the workflow-initiated flag. Returns true if set, clears it. */
+function consumeWorkflowInitiatedNewSession(): boolean {
+  const value = globalThis.__piWorkflowMonitor?.workflowInitiatedNewSession === true;
+  if (globalThis.__piWorkflowMonitor) globalThis.__piWorkflowMonitor.workflowInitiatedNewSession = undefined;
+  return value;
+}
+
+/**
+ * Create the session-lifecycle domain object: the bodies of the session_start
+ * (state branch) and session_tree handlers as callable methods, plus the shared
+ * workflow-reset. Pure domain logic — no pi.on registration.
+ */
+export function createSessionLifecycle(deps: SessionLifecycleDeps): ISessionLifecycle {
+  const { pi, handler, compaction, guardrails, expandSkillCommand } = deps;
+
+  const resetSessionTracking = () => {
+    guardrails.resetTracking();
+    compaction.resetTracking();
+    deps.phaseReady.resetTracking();
+    clearPostTurnFollowUp();
+  };
+
+  const trackSessionFile = (ctx: ExtensionContext, slug: string) => {
+    trackSessionFileInState(ctx, slug);
+  };
+
+  /**
+   * Restore workflow state from session branch entries.
+   */
+  const restoreFromSessionEntries = (ctx: ExtensionContext): boolean => {
+    const data = findLatestCustomEntry(ctx, FEATYARD_STATE_ENTRY_TYPE);
+    if (data) {
+      handler.setFullState(data);
+      const slug = handler.getActiveFeatureSlug();
+      if (slug) {
+        setActiveFeatureEnv(slug);
+      } else {
+        clearActiveFeatureEnv();
+      }
+      syncEnvVarsFromState(handler);
+      return true;
+    }
+    return false;
+  };
+
+  /**
+   * Shared handler for session events that restore from session entries.
+   */
+  const restoreAndReset = async (
+    ctx: ExtensionContext,
+    { clearOnMissing }: { clearOnMissing: boolean },
+  ): Promise<boolean> => {
+    const restored = restoreFromSessionEntries(ctx);
+    if (restored) {
+      recoverArtifactsFromDisk(handler);
+      resetSessionTracking();
+      updateWidget(handler, NO_FEATURE_STATE);
+      // Restore the worktree footer indicator from reconstructed state (lost on
+      // reload/resume/fork). Cleared below when no active feature remains.
+      syncWorktreeStatus(handler.getActiveFeatureState());
+      return true;
+    }
+    if (clearOnMissing) {
+      handler.resetState();
+      clearActiveFeatureEnv();
+      resetSessionTracking();
+      updateWidget(handler, NO_FEATURE_STATE);
+      syncWorktreeStatus(handler.getActiveFeatureState());
+      return true;
+    }
+    return false;
+  };
+
+  /**
+   * Shared reset logic used by /fy:reset, /resume session_start, and user-initiated /new.
+   */
+  function performWorkflowReset(): void {
+    setFinishPhaseWhitelisted(false);
+    handler.setActiveFeatureState(NO_ACTIVE_FEATURE_STATE);
+    clearActiveFeatureEnv();
+    clearFeatureEnvVars();
+    handler.resetState();
+    resetSessionTracking();
+    persistState(pi, handler);
+    updateWidget(handler, NO_FEATURE_STATE);
+    syncWorktreeStatus(handler.getActiveFeatureState());
+  }
+
+  // --- session_start handler branches ---
+
+  /**
+   * Handle reload/startup: restore state from session entries when present.
+   * On miss, keep state and fall through (env/file path for fresh subagents,
+   * clearAndReset for a clean new session). Startup shares this because it
+   * covers BOTH a clean new session (empty branch → miss → clean) AND opening
+   * an existing one via `pi --session`/`--continue`/`--fork` (branch has the
+   * feature entry → restore, like /resume). The forked-session copy also
+   * carries entries into a fork subagent, so the host's point-in-time state is
+   * restored there too.
+   */
+  async function handleReloadOrStartup(ctx: ExtensionContext): Promise<boolean> {
+    return restoreAndReset(ctx, { clearOnMissing: false });
+  }
+
+  /** Handle resume/fork: restore state from session entries, clear if missing. */
+  async function handleResumeOrFork(ctx: ExtensionContext): Promise<void> {
+    await restoreAndReset(ctx, { clearOnMissing: true });
+  }
+
+  /**
+   * Handle new session: if workflow-initiated, send pending followUp message;
+   * otherwise if active feature exists, prompt user to continue or reset.
+   */
+  async function handleNewSession(ctx: ExtensionContext): Promise<boolean> {
+    if (consumeWorkflowInitiatedNewSession()) {
+      const pendingMessage = consumeNewSessionMessage();
+      if (pendingMessage) {
+        pi.sendUserMessage(expandSkillCommand(pendingMessage, NO_FEATURE_STATE_OVERRIDE, NO_AGENT_NAME), {
+          deliverAs: "followUp",
+        });
+      }
+      return false; // do not continue to feature binding
+    }
+    if (process.env.PI_FY_FEATURE && !isSubagentSession()) {
+      const slug = process.env.PI_FY_FEATURE;
+      // Headless / non-interactive: no UI to prompt — proceed without the continue/reset dialog
+      // (mirrors the hasUI guard c6fee0b9 added to resolveBaseBranch). The feature stays active;
+      // a later interactive session can still offer the reset choice.
+      if (!ctx.hasUI) {
+        return false;
+      }
+      notifyAutoAgentBlocked(slug);
+      const choice = await withCoordinator(() =>
+        ctx.ui.select(`You have an active workflow (${slug}). Continue or reset?`, [
+          `Continue: ${slug}`,
+          "Reset workflow",
+        ]),
+      );
+      notifyAutoAgentUnblocked(slug);
+      if (choice === "Reset workflow") {
+        performWorkflowReset();
+        return true; // handled — stop processing
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Bind feature from PI_FY_FEATURE env var: reconstruct state,
+   * sync env vars, optionally resume last session, apply execution mode.
+   */
+  async function bindFeatureFromEnv(ctx: ExtensionContext): Promise<boolean> {
+    const slug = process.env.PI_FY_FEATURE;
+    if (!slug) return false;
+    const stateFile = loadFeatureState(slug, DEFAULT_DIR);
+    if (!stateFile) {
+      log.warn(`PI_FY_FEATURE=${slug} but no state file found — clearing env var`);
+      clearActiveFeatureEnv();
+      return false;
+    }
+
+    log.info(`Feature binding from env var: ${slug}`);
+    reconstructState(ctx, handler, featureStateFilePath(slug, DEFAULT_DIR));
+    resetSessionTracking();
+    updateWidget(handler, NO_FEATURE_STATE);
+    syncWorktreeStatus(handler.getActiveFeatureState());
+    syncEnvVarsFromState(handler);
+
+    trackSessionFile(ctx, slug);
+
+    if (!isSubagentSession()) {
+      const ws = handler.getWorkflowState();
+      if (ws?.currentPhase) {
+        await applyModelOverride(pi, ctx, ws.currentPhase, deps.resolveLoopIndex(ws.currentPhase));
+      }
+    }
+
+    const lastSession = stateFile.sessionFiles?.at(-1);
+    if (lastSession && fs.existsSync(lastSession) && !isSubagentSession()) {
+      notifyAutoAgentBlocked(slug);
+      const choice = await withCoordinator(() =>
+        ctx.ui.select(`Resume from last session? (${path.basename(lastSession)})`, [
+          "Resume from last session",
+          "Continue fresh",
+        ]),
+      );
+      notifyAutoAgentUnblocked(slug);
+      if (choice === "Resume from last session") {
+        // The session_start runtime context carries command capabilities even though
+        // the static event type is ExtensionContext; switchSession requires the command context.
+        await (ctx as ExtensionCommandContext).switchSession(lastSession, {
+          withSession: async (newCtx) => {
+            newCtx.ui.notify(`Resumed session for: ${slug}`, "info");
+          },
+        });
+        return true; // handled — session switched
+      }
+    }
+
+    return true; // feature bound
+  }
+
+  /** Clear all feature state — used for headless sessions or clean starts. */
+  function clearAndReset(): void {
+    clearFeatureEnvVars();
+    handler.resetState();
+    resetSessionTracking();
+    updateWidget(handler, NO_FEATURE_STATE);
+    syncWorktreeStatus(handler.getActiveFeatureState());
+  }
+
+  // --- session_start handler body (state branch) ---
+  async function onSessionStart(event: unknown, ctx: ExtensionContext): Promise<void> {
+    setFinishPhaseWhitelisted(false);
+    const reason = ((event as unknown as Record<string, unknown>).reason as string | undefined) ?? "startup";
+    log.info(
+      `session_start fired — reason=${reason}, hasUI=${ctx.hasUI}, PI_FY_FEATURE=${process.env.PI_FY_FEATURE ?? "unset"}`,
+    );
+
+    handler.setActiveFeatureState(NO_ACTIVE_FEATURE_STATE);
+
+    if (reason === "reload" || reason === "startup") {
+      if (await handleReloadOrStartup(ctx)) return;
+    }
+
+    if (reason === "resume" || reason === "fork") {
+      await handleResumeOrFork(ctx);
+      return;
+    }
+
+    if (reason === "new") {
+      const resetHandled = await handleNewSession(ctx);
+      if (resetHandled) return;
+    }
+
+    if (process.env.PI_FY_FEATURE) {
+      const bound = await bindFeatureFromEnv(ctx);
+      if (bound) return;
+    }
+
+    if (isSubagentSession()) {
+      log.warn("Subagent session started without PI_FY_FEATURE — no feature loaded");
+      clearAndReset();
+      return;
+    }
+
+    clearAndReset();
+  }
+
+  // --- session_tree handler body ---
+  async function onSessionTree(ctx: ExtensionContext): Promise<void> {
+    await restoreAndReset(ctx, { clearOnMissing: true });
+  }
+
+  return { onSessionStart, onSessionTree, performWorkflowReset };
+}
+
+/**
+ * Wire the globalThis workflow-monitor bridge hooks (requestWidgetUpdate,
+ * performWorkflowReset) so non-event callers (widgets, commands) can trigger them.
+ */
+export function wireSessionLifecycleBridge(handler: FeatureSession, lifecycle: ISessionLifecycle): void {
+  if (globalThis.__piWorkflowMonitor) {
+    globalThis.__piWorkflowMonitor.requestWidgetUpdate = () => {
+      // updateWidget now uses PiCtx for safe ctx access — no raw ctx needed
+      updateWidget(handler, NO_FEATURE_STATE);
+    };
+    globalThis.__piWorkflowMonitor.performWorkflowReset = lifecycle.performWorkflowReset;
+  }
+}

package/src/state/state-persistence.ts

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * State persistence — two tiers, three stores.
+ *
+ *   FeatureState    (durable record) → File (cross-session bootstrap) + AppendEntry
+ *   GuardrailsState (transient)      → AppendEntry ONLY (resets on a fresh session;
+ *                                       restored when resuming a session-tree node)
+ *
+ * The handler holds the active FeatureState in memory as the single source of
+ * truth. persistState write-throughs the in-memory record to its file (no
+ * merge — the handler record IS the record) and appends the full FeatyardState
+ * wrapper to the session log. reconstructState bootstraps a fresh session by
+ * loading the active feature's file into the handler (guardrails reset).
+ */
+
+import * as fs from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { log } from "../log.js";
+import { syncEnvVarsFromState } from "../phases/env-sync.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import { recoverArtifactsFromDisk } from "./feature-management.js";
+import {
+  DEFAULT_DIR,
+  type FeatureState,
+  stateFilePath as featureStateFilePath,
+  saveFeatureState,
+} from "./feature-state.js";
+
+export const FEATYARD_STATE_ENTRY_TYPE = "featyard_state";
+
+/** True when this session is a spawned subagent. Uses dual-signal detection:
+ *  checks PiCtx.mode (from globalThis.__piCtx, refreshed on session_start) first,
+ *  then falls back to PI_SUBAGENT_PARENT_PID env var. When mode is unavailable
+ *  (PiCtx not yet initialized), relies solely on the env var. Subagents READ
+ *  feature context on start but must NOT write the feature file — durable feature
+ *  state is host-owned; suppressing the file write eliminates the host/subagent
+ *  write race. Subagents still appendEntry (for in-session resume). */
+export function isSubagentSession(): boolean {
+  const ctx = globalThis.__piCtx;
+  if (ctx?.mode !== undefined && ctx.mode !== "tui") return true;
+  return process.env.PI_SUBAGENT_PARENT_PID !== undefined;
+}
+
+/**
+ * Returns the feature state file path for the currently active feature slug,
+ * or null if no feature is active.
+ */
+export function getStateFilePath(handler: FeatureSession): string | null {
+  const slug = handler.getActiveFeatureSlug();
+  if (slug) {
+    return featureStateFilePath(slug, DEFAULT_DIR);
+  }
+  return null;
+}
+
+/**
+ * Reconstruct handler state from a feature state file (fresh-session bootstrap).
+ * Guardrails (tdd/verification) are NOT restored — they are session-only and
+ * reset on a fresh session. Falls back to an empty handler if no file is found.
+ */
+export function reconstructState(
+  _ctx: ExtensionContext,
+  handler: FeatureSession,
+  stateFilePath: string | false | null,
+): void {
+  handler.resetState();
+
+  // Only restore from the feature state file — never from session branch entries
+  // to avoid cross-feature state contamination. Guardrails reset (session-only).
+  if (stateFilePath !== false) {
+    try {
+      const statePath = stateFilePath ?? getStateFilePath(handler);
+      if (statePath && fs.existsSync(statePath)) {
+        const raw = fs.readFileSync(statePath, "utf-8");
+        const data = JSON.parse(raw) as FeatureState;
+        // Load the durable record into the handler (seeds the workflow tracker;
+        // guardrails reset to neutral since they are session-only).
+        handler.setActiveFeatureState(data);
+        // Recover missing doc artifacts from disk into the in-memory record.
+        recoverArtifactsFromDisk(handler);
+        // Sync env vars from the restored record so subagent tool can resolve model overrides.
+        syncEnvVarsFromState(handler);
+        return;
+      }
+    } catch (err) {
+      log.warn(`Failed to read state file: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  // No state file found — reset to fresh defaults (no active feature).
+  handler.resetState();
+}
+
+/**
+ * Persist handler state to both the session log (AppendEntry) and the
+ * per-feature state file (write-through). The handler's in-memory record is the
+ * source of truth, so the file is written verbatim — no merge.
+ */
+export function persistState(pi: ExtensionAPI, handler: FeatureSession): void {
+  const fullState = handler.getFullState();
+  // AppendEntry stores the FULL wrapper (featureState + guardrailsState) so a
+  // session-tree resume restores BOTH tiers as of this point.
+  pi.appendEntry(FEATYARD_STATE_ENTRY_TYPE, fullState);
+
+  // Subagent sessions read feature context but never own the durable record —
+  // skip the file write so they cannot race the host's write-through.
+  if (!isSubagentSession()) {
+    try {
+      const active = handler.getActiveFeatureState();
+      if (active) {
+        // Write-through: the handler record IS the record. Stamp updatedAt + persist.
+        active.updatedAt = new Date().toISOString();
+        saveFeatureState(active, DEFAULT_DIR);
+      }
+    } catch (err) {
+      log.warn(`Failed to persist state file: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  // Keep env vars in sync after every state persistence.
+  syncEnvVarsFromState(handler);
+}

package/src/state/worth-notes.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Worth-notes pointer — the first RUNTIME reader of the worth-notes file.
+ *
+ * Worth-notes (`.featyard/reviews/<slug>/<slug>-worth-notes.md`, or a date-fallback when no slug is
+ * active) are unstructured LLM markdown written by the orchestrator/implementer for out-of-scope
+ * smells/bugs/oddities. They are surfaced by MERGING a pointer (existence + path)
+ * into existing boundary notifications — never standalone, because pi notifications are exclusive
+ * (a new one hides the previous). This module owns two concerns:
+ *
+ * - `worthNotesPath(slug, date)`: the path computation (single source of truth — the
+ *  `{{PI_FY_WORTH_NOTES_PATH}}` marker handler and every runtime caller delegate here, so the
+ *  slug-vs-date-fallback branch lives in exactly one place).
+ * - `worthNotesPointer(notesPath)`: given the resolved path, returns `📝 worth-notes: <path>` when
+ *  the file exists and is non-empty, else null (a stat + size check). Callers append the pointer
+ *  only when non-null, so absent/empty notes add no notification clutter.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+
+import { FY_REVIEWS_DIR } from "./artifact-paths.js";
+
+/**
+ * Resolve the worth-notes file path for a feature.
+ *
+ * - Slug present: `.featyard/reviews/<slug>/<slug>-worth-notes.md` (the per-feature worth-notes file).
+ * - No slug (manual skill run without an active feature): `.featyard/reviews/<date>/<date>-worth-notes.md`
+ *  (a single stable per-date file — worth-notes accumulate). `date` is a yyyy-mm-dd string.
+ *
+ * Mirrors the `{{PI_FY_WORTH_NOTES_PATH}}` marker resolution — both delegate here.
+ */
+export function worthNotesPath(slug: string | null, date: string): string {
+  return slug ? `${FY_REVIEWS_DIR}/${slug}/${slug}-worth-notes.md` : `${FY_REVIEWS_DIR}/${date}/${date}-worth-notes.md`;
+}
+
+/**
+ * Return `📝 worth-notes: <notesPath>` when the file exists and has non-whitespace content, else
+ * `null`. The caller resolves `notesPath` (`worthNotesPath`) and appends the pointer only when
+ * non-null — so absent or empty worth-notes produce no pointer line (no clutter).
+ *
+ * Existence + path only — never a count (the file is unstructured LLM markdown with no reliable
+ * entry delimiter; counting would be fragile — ). The path lets the user open it.
+ */
+export function worthNotesPointer(notesPath: string): string | null {
+  try {
+    if (!statSync(notesPath).isFile()) return null;
+  } catch {
+    // Absent (or otherwise unreadable) → no pointer.
+    return null;
+  }
+  // Existence + non-empty (non-whitespace) check. Worth-notes files are tiny, so a single read
+  // is cheap. A whitespace-only file carries nothing to surface → treat as empty.
+  let content: string;
+  try {
+    content = readFileSync(notesPath, "utf-8");
+  } catch {
+    return null;
+  }
+  if (content.trim().length === 0) {
+    return null;
+  }
+  return `📝 worth-notes: ${notesPath}`;
+}
+
+/**
+ * Convenience for the boundary notify sites: resolve today's worth-notes pointer for a feature
+ * in one call (the single repeated pattern at the 5 merge sites). `today` is the current
+ * yyyy-mm-dd; the pointer is non-null only when the notes file exists and is non-empty.
+ */
+export function worthNotesPointerFor(slug: string | null): string | null {
+  const today = new Date().toISOString().slice(0, 10);
+  return worthNotesPointer(worthNotesPath(slug, today));
+}
+
+/**
+ * Emit the `Feature "<slug>" completed.` notify with the worth-notes pointer MERGED in
+ * (existence + path, never standalone — notifications are exclusive, Completion
+ * site). No-op when no UI is attached (headless). Shared by the two completion paths
+ * (phase-transitions.ts completeFeature + phase-ready.ts finish→done).
+ */
+export function notifyFeatureCompleted(slug: string): void {
+  const guard = globalThis.__piCtx;
+  if (!guard?.hasUI || !guard?.ui?.notify) return;
+  const pointer = worthNotesPointerFor(slug);
+  const msg = pointer ? `Feature "${slug}" completed.\n${pointer}` : `Feature "${slug}" completed.`;
+  guard.ui.notify(msg, "info");
+}

package/src/tools/add-to-backlog.ts

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/** Register the add_to_backlog tool — adds a new feature to the kanban board backlog. */
+
+import { basename } from "node:path";
+import { Type } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { KanbanContext } from "../kanban/kanban-context.js";
+import { textResult } from "./text-result.js";
+
+/** Register the add_to_backlog tool. */
+export function registerAddToBacklogTool(pi: ExtensionAPI, ctx: KanbanContext): void {
+  const { getDatabase } = ctx;
+
+  pi.registerTool({
+    name: "add_to_backlog",
+    label: "Add Feature to Backlog",
+    description: [
+      "Add a new feature to the kanban board backlog.",
+      "Use when decomposing a feature into smaller parts (after user confirmation),",
+      "or when the user requests adding a new feature to the board.",
+      "Returns the feature ID and slug for reference.",
+    ].join(" "),
+    parameters: Type.Object({
+      slug: Type.String({
+        description:
+          "Unique slug for the feature (YYYY-MM-DD-<topic> format). Must match the design-doc/plan-doc filename pattern.",
+      }),
+      title: Type.String({
+        maxLength: 200,
+        description: "Short, descriptive title for the feature",
+      }),
+      description: Type.String({
+        description: [
+          "Detailed feature description with all known context, requirements, and constraints.",
+          "Include everything a future agent session would need to start working on this feature",
+          "without any prior context — problem statement, proposed approach, key decisions,",
+          "relevant code areas, and any user preferences discussed.",
+        ].join(" "),
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _toolCtx) {
+      const database = await getDatabase();
+
+      // Resolve or auto-create project
+      const { detectProject } = await import("../kanban/data/kanban-detect-project.js");
+      let projectId = await detectProject(database, process.cwd());
+      if (!projectId) {
+        const cwd = process.cwd();
+        // Check if a project with this repo path already exists (e.g. created by a previous call)
+        const existingProject = database.findProjectByRepoPath(cwd);
+        if (existingProject) {
+          projectId = existingProject.id;
+        } else {
+          projectId = database.createProject({
+            name: basename(cwd),
+            repoPath: cwd,
+          });
+        }
+      }
+
+      const slug = params.slug;
+
+      // Check for slug collision
+      const existingFeature = database.findFeatureBySlug(slug, projectId);
+      if (existingFeature) {
+        return textResult(
+          `A feature with slug "${slug}" already exists (ID: ${existingFeature.id}, lane: ${existingFeature.lane}). Not creating duplicate.`,
+        );
+      }
+
+      // Prefix description with LLM-generated note
+      const prefixedDescription =
+        "Important: content generated by LLM, based on user description — " +
+        "research and reask user regarding every section and nuances\n\n" +
+        params.description;
+
+      // Create feature in backlog
+      const featureId = database.createFeature({
+        projectId,
+        slug,
+        title: params.title,
+        description: prefixedDescription,
+        lane: "backlog",
+      });
+
+      return textResult(
+        [
+          "Feature added to backlog:",
+          `- ID: ${featureId}`,
+          `- Title: ${params.title}`,
+          `- Slug: ${slug}`,
+          "- Lane: backlog",
+          "",
+          "Move it to the design lane to have the auto-designer pick it up, or start a design session manually.",
+        ].join("\n"),
+      );
+    },
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("add_to_backlog "));
+      text += theme.fg("accent", `"${args.slug}"`);
+      return new Text(text, 0, 0);
+    },
+    renderResult(result, _options, theme) {
+      if (result.content?.[0]?.type === "text") {
+        const text = result.content[0].text;
+        if (text.includes("already exists")) {
+          return new Text(theme.fg("error", text), 0, 0);
+        }
+        return new Text(theme.fg("success", text), 0, 0);
+      }
+      return new Text("", 0, 0);
+    },
+  });
+}