avtc-pi-featyard 1.1.0

package/src/kanban/data/kanban-db-schema.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/*
+ * V2 scope — tag CRUD operations (schema tables exist, operations not yet implemented):
+ *   - createTag(name, color?) → tag id
+ *   - getTag(id) → Tag | null
+ *   - listTags() → Tag[]
+ *   - updateTag(id, { name?, color? }) → void
+ *   - deleteTag(id) → void
+ *   - addFeatureTag(featureId, tagId) → void
+ *   - removeFeatureTag(featureId, tagId) → void
+ *   - getFeatureTags(featureId) → Tag[]
+ *   - getFeaturesByTag(tagId) → Feature[]
+ *
+ * The `tags` and `feature_tags` tables are created in V1 schema for forward
+ * compatibility, but no CRUD operations, REST endpoints, or UI elements
+ * exist yet. Implement when tag-based filtering and categorization is needed.
+ */
+
+export const SCHEMA_V1 = `
+-- Projects
+CREATE TABLE IF NOT EXISTS projects (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  repo_path TEXT NOT NULL UNIQUE,
+  base_branch TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- Features
+CREATE TABLE IF NOT EXISTS features (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  slug TEXT, -- nullable: null until design doc is written
+
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  lane TEXT NOT NULL DEFAULT 'backlog',
+  priority INTEGER NOT NULL DEFAULT 0,
+  title TEXT NOT NULL,
+  description TEXT,
+  design_doc TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_features_project_slug ON features(project_id, slug) WHERE slug IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_features_project_lane ON features(project_id, lane);
+CREATE INDEX IF NOT EXISTS idx_features_priority ON features(project_id, lane, priority DESC);
+
+-- Tags (many-to-many)
+CREATE TABLE IF NOT EXISTS tags (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL UNIQUE,
+  color TEXT
+);
+
+CREATE TABLE IF NOT EXISTS feature_tags (
+  feature_id INTEGER NOT NULL REFERENCES features(id) ON DELETE CASCADE,
+  tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+  PRIMARY KEY (feature_id, tag_id)
+);
+CREATE INDEX IF NOT EXISTS idx_feature_tags_tag ON feature_tags(tag_id);
+
+-- Dependencies (directed graph)
+CREATE TABLE IF NOT EXISTS feature_dependencies (
+  feature_id INTEGER NOT NULL REFERENCES features(id) ON DELETE CASCADE,
+  depends_on_id INTEGER NOT NULL REFERENCES features(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK(kind IN ('blocks', 'requires', 'related')),
+  PRIMARY KEY (feature_id, depends_on_id),
+  CHECK(feature_id != depends_on_id)
+);
+CREATE INDEX IF NOT EXISTS idx_feature_deps_from ON feature_dependencies(feature_id);
+CREATE INDEX IF NOT EXISTS idx_feature_deps_to ON feature_dependencies(depends_on_id);
+
+-- Feature history (audit trail)
+CREATE TABLE IF NOT EXISTS feature_history (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  feature_id INTEGER NOT NULL REFERENCES features(id) ON DELETE CASCADE,
+  from_lane TEXT,
+  to_lane TEXT NOT NULL,
+  changed_by TEXT NOT NULL,
+  session_id TEXT,
+  note TEXT,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_feature_history_feature ON feature_history(feature_id);
+
+-- Lock tracking
+CREATE TABLE IF NOT EXISTS feature_locks (
+  feature_id INTEGER PRIMARY KEY REFERENCES features(id) ON DELETE CASCADE,
+  session_id TEXT NOT NULL,
+  locked_at TEXT NOT NULL,
+  last_heartbeat TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_feature_locks_session ON feature_locks(session_id);
+
+-- Migration tracking
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL
+);
+`;
+
+export const SCHEMA_V2 = `
+-- Add overlay_status column for waiting-for-response indicator
+ALTER TABLE features ADD COLUMN overlay_status TEXT DEFAULT NULL;
+`;
+
+export const SCHEMA_V3 = `
+-- Auto-agent state persistence for crash recovery
+CREATE TABLE IF NOT EXISTS auto_agent_state (
+  session_id TEXT PRIMARY KEY,
+  role TEXT NOT NULL CHECK(role IN ('worker', 'designer', 'agent')),
+  project_id INTEGER NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('idle', 'working', 'waiting', 'polling', 'stopped', 'error')),
+  current_feature_id INTEGER,
+  current_feature_lane TEXT,
+  stop_requested INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+
+export const SCHEMA_V4 = `
+-- Add metadata columns for cross-referencing and session tracking
+ALTER TABLE features ADD COLUMN plan_doc TEXT DEFAULT NULL;
+ALTER TABLE features ADD COLUMN state_file TEXT DEFAULT NULL;
+ALTER TABLE features ADD COLUMN assigned_session TEXT DEFAULT NULL;
+CREATE INDEX IF NOT EXISTS idx_features_assigned ON features(assigned_session);
+`;
+
+export const MIGRATIONS: { version: number; sql: string }[] = [
+  { version: 1, sql: SCHEMA_V1 },
+  { version: 2, sql: SCHEMA_V2 },
+  { version: 3, sql: SCHEMA_V3 },
+  { version: 4, sql: SCHEMA_V4 },
+];

package/src/kanban/data/kanban-detect-project.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+import { log } from "../../log.js";
+import type { KanbanDatabase } from "./kanban-database.js";
+
+/**
+ * Resolve the main repo path from the given cwd.
+ * Handles worktrees by using git to find the main repo.
+ * Encapsulates the dynamic import of node:child_process + node:util + worktree.js.
+ */
+export async function resolveRepoPath(cwd: string): Promise<string> {
+  const { exec } = await import("node:child_process");
+  const { promisify } = await import("node:util");
+  const execAsync = promisify(exec);
+  const { resolveMainRepoPath } = await import("../../git/worktrees/worktree-lifecycle.js");
+  const execFn: import("../../git/worktrees/worktree-lifecycle.js").ExecFn = async (cmd) => {
+    const { stdout } = await execAsync(cmd, { cwd });
+    return { exitCode: 0, stdout };
+  };
+  return resolveMainRepoPath(execFn);
+}
+
+/**
+ * Detect the kanban project ID for the given working directory.
+ * Resolves the main repo path (handles worktrees) and looks up the project.
+ */
+export async function detectProject(database: KanbanDatabase, cwd: string): Promise<number | null> {
+  try {
+    const repoPath = await resolveRepoPath(cwd);
+    log.info(`[kanban] detectProject: cwd=${cwd}, resolved repoPath=${repoPath}`);
+    const project = database.findProjectByRepoPath(repoPath);
+    if (project) {
+      log.info(`[kanban] detectProject: found project ${project.id} "${project.name}" for repoPath=${repoPath}`);
+    } else {
+      log.info(`[kanban] detectProject: no project found for repoPath=${repoPath}`);
+    }
+    return project?.id ?? null;
+  } catch (err) {
+    log.warn(`[kanban] detectProject failed (cwd=${cwd}): ${err}`);
+    return null; // not a git repo or git not available
+  }
+}

package/src/kanban/data/kanban-move-feature.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Helper to move a kanban feature to a lane with null-safe database access.
+ *
+ * Every call site follows the same pattern:
+ *   const { getDatabaseInstance } = await import("./kanban/index.js");
+ *   const kanbanDb = getDatabaseInstance();
+ *   if (kanbanDb) { kanbanDb.moveFeature({...}); }
+ *
+ * This helper collapses that boilerplate into a single call.
+ */
+
+import { log } from "../../log.js";
+import { getDatabaseInstance } from "../kanban-bridge.js";
+import type { Lane } from "./kanban-types.js";
+
+interface MoveFeatureOptions {
+  featureId: number;
+  toLane: Lane;
+  changedBy?: string;
+  note?: string;
+  fromLane: Lane | undefined;
+}
+
+/**
+ * Move a kanban feature to the specified lane.
+ * No-ops if the database is not initialized or featureId is null/undefined.
+ */
+export async function moveFeatureToLane(opts: MoveFeatureOptions): Promise<void> {
+  const kanbanDb = getDatabaseInstance();
+  if (!kanbanDb) return;
+
+  kanbanDb.moveFeature({
+    featureId: opts.featureId,
+    toLane: opts.toLane,
+    changedBy: opts.changedBy ?? "system",
+    note: opts.note ?? "",
+    fromLane: opts.fromLane,
+  });
+  log.info(`kanban: moved feature ${opts.featureId} to ${opts.toLane} lane`);
+}

package/src/kanban/data/kanban-types.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+export type Lane = "backlog" | "design" | "design-approval" | "ready" | "in-progress" | "uat" | "done";
+
+/** Canonical lane order — single source of truth for all lane ordering. */
+export const LANE_ORDER: readonly Lane[] = [
+  "backlog",
+  "design",
+  "design-approval",
+  "ready",
+  "in-progress",
+  "uat",
+  "done",
+] as const;
+
+/** Set of valid lane values for validation. */
+export const VALID_LANES: ReadonlySet<Lane> = new Set(LANE_ORDER);
+
+/** Type guard: narrows `string` to `Lane` using VALID_LANES. */
+export function isLane(value: string | undefined): value is Lane {
+  return value !== undefined && VALID_LANES.has(value as Lane);
+}
+
+export interface Project {
+  id: number;
+  name: string;
+  repo_path: string;
+  base_branch: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface Feature {
+  id: number;
+  slug: string | null;
+  project_id: number;
+  lane: Lane;
+  priority: number;
+  title: string;
+  description: string | null;
+  design_doc: string | null;
+  plan_doc: string | null;
+  state_file: string | null;
+  assigned_session: string | null;
+  overlay_status: string | null; // null | 'waiting-for-response'
+  created_at: string;
+  updated_at: string;
+  // Joined from feature_locks when present
+  locked_at?: string | null;
+  last_heartbeat?: string | null;
+  locked_by_session?: string | null; // fl.session_id from feature_locks
+}
+
+export interface FeatureHistoryEntry {
+  id: number;
+  feature_id: number;
+  from_lane: string | null;
+  to_lane: string;
+  changed_by: string;
+  session_id: string | null;
+  note: string | null;
+  created_at: string;
+}

package/src/kanban/ensure-feature.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Kanban ↔ Feature State linking hooks.
+ *
+ * Provides helpers that bridge the kanban database and per-feature state files,
+ * used when design docs are written or features are picked by auto-agent.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { log } from "../log.js";
+import type { FeatureState } from "../state/feature-state.js";
+import { DEFAULT_DIR, getDesignDoc, saveFeatureState, stateDir, stateFilePath } from "../state/feature-state.js";
+import type { KanbanDatabase } from "./data/kanban-database.js";
+import type { Lane } from "./data/kanban-types.js";
+import { generateFeatureMeta } from "./kanban-generate-title.js";
+
+/**
+ * Extract a human-readable title from a slug by removing the date prefix and capitalizing words.
+ * Used as fallback when LLM title generation is not available.
+ *
+ * "2026-05-22-auto-agent-notifications-and-widget-improvement" → "Auto Agent Notifications And Widget Improvement"
+ */
+function titleFromSlug(slug: string): string {
+  // Remove date prefix (YYYY-MM-DD-)
+  const withoutDate = slug.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+  // Capitalize words, replace hyphens with spaces
+  return withoutDate
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+/**
+ * Extract the first heading and paragraph from a markdown design doc.
+ * Returns { title, description } or null if the file can't be read.
+ */
+function extractMetaFromDesignDoc(designDocPath: string | null): { title: string; description: string } | null {
+  if (!designDocPath || !fs.existsSync(designDocPath)) return null;
+  try {
+    const content = fs.readFileSync(designDocPath, "utf-8");
+    // Extract first heading (# Title)
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch?.[1]?.trim();
+    // Extract first non-heading, non-empty paragraph
+    const lines = content.split("\n");
+    let description = "";
+    let pastFrontmatter = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      // Skip frontmatter
+      if (!pastFrontmatter && trimmed === "---") {
+        pastFrontmatter = true;
+        continue;
+      }
+      if (pastFrontmatter && trimmed === "---") {
+        pastFrontmatter = false;
+        continue;
+      }
+      if (pastFrontmatter) continue;
+      // Skip headings and empty lines
+      if (trimmed.startsWith("#") || trimmed === "") continue;
+      // Skip metadata lines (Date:, Status:, Branch:, **Date**, etc.)
+      if (/^\*?\*?(Date|Status|Branch|Author)/i.test(trimmed)) continue;
+      if (/^---/.test(trimmed)) continue;
+      description = trimmed;
+      break;
+    }
+    if (title || description) {
+      return { title: title ?? "", description: description ?? "" };
+    }
+  } catch {
+    // Can't read file — that's fine
+  }
+  return null;
+}
+
+/**
+ * Ensure a kanban feature exists for the given feature state.
+ *
+ * If the state already has kanbanFeatureId, no-ops.
+ * If a kanban feature with matching slug exists, links it.
+ * Otherwise, finds or auto-creates a project for cwd and adds the feature
+ * to the backlog lane with a proper title and description.
+ *
+ * When auto-creating a feature (user started working in TUI without adding to kanban):
+ * - Uses LLM to generate title + description from design doc content
+ * - Falls back to extracting title/description from markdown headings/paragraphs
+ * - Final fallback: derive title from slug
+ *
+ * Mutates `state` in place (sets `state.featureId`) and persists it to disk.
+ * The caller passes its sole-owner record and adopts it directly — consistent
+ * with the handler's single-source-of-truth model.
+ */
+export async function ensureKanbanFeature(
+  db: KanbanDatabase,
+  state: FeatureState,
+  resolvedCwd: string | null,
+  sessionId: string | null,
+  targetLane: Lane,
+): Promise<void> {
+  // Already linked — no-op
+  if (state.featureId !== null) {
+    return;
+  }
+
+  // Find or create project for current cwd (or resolved main repo path if in worktree)
+  const cwd = resolvedCwd ?? process.cwd();
+  let project = db.findProjectByRepoPath(cwd);
+  if (!project) {
+    const projectId = db.createProject({
+      name: path.basename(cwd),
+      repoPath: cwd,
+    });
+    project = {
+      id: projectId,
+      name: path.basename(cwd),
+      repo_path: cwd,
+      base_branch: null,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+  }
+
+  // Try to find existing kanban feature by slug scoped to this project
+  const existing = db.findFeatureBySlug(state.featureSlug, project.id);
+  if (existing) {
+    state.featureId = existing.id;
+    // Update state_file if not already set
+    if (!existing.state_file) {
+      const sf = stateFilePath(state.featureSlug, stateDir());
+      db.updateFeature({ featureId: existing.id, stateFile: sf });
+    }
+    // Lock FIRST if sessionId provided — prevents race where another agent picks up
+    // the feature between the move-to-target-lane and the lock attempt
+    if (sessionId) {
+      const locked = db.lockFeature(existing.id, sessionId);
+      if (!locked) {
+        log.warn(`[kanban-hooks] failed to lock feature ${existing.id} — already locked`);
+      } else {
+        db.updateFeature({ featureId: existing.id, assignedSession: sessionId });
+      }
+    }
+    // Move to the target lane if the feature is still in backlog (design doc ->
+    // "design", task-plan -> "in-progress"). Called from a doc-write handler, so the
+    // triggering doc always exists.
+    if (existing.lane === "backlog") {
+      db.moveFeature({
+        featureId: existing.id,
+        toLane: targetLane,
+        changedBy: "workflow-monitor",
+        note: `Doc written — moving from backlog to ${targetLane}`,
+      });
+    }
+    saveFeatureState(state, DEFAULT_DIR);
+    return;
+  }
+
+  // Auto-create feature with proper title and description
+  const designDocPath = getDesignDoc(state);
+  let title = titleFromSlug(state.featureSlug);
+  let description: string | null = null;
+
+  // Try to extract meta from design doc content
+  const docMeta = extractMetaFromDesignDoc(designDocPath);
+  if (docMeta?.title) {
+    title = docMeta.title;
+  }
+  if (docMeta?.description) {
+    description = docMeta.description;
+  }
+
+  // Try LLM-powered title + description generation
+  try {
+    const llmMeta = await generateFeatureMeta(designDocPath, title);
+    if (llmMeta.title) title = llmMeta.title;
+    if (llmMeta.description) description = llmMeta.description;
+  } catch (err) {
+    log.info(
+      `[kanban-hooks] LLM title/description generation failed, using fallback: ${
+        err instanceof Error ? err.message : err
+      }`,
+    );
+  }
+
+  // Auto-create feature in backlog first, then lock + move to the target lane if
+  // the triggering artifact exists. This avoids a race where the feature sits in
+  // the target lane unlocked between creation and lock acquisition — no agent picks
+  // from backlog, so it's safe there.
+  const featureId = db.createFeature({
+    projectId: project.id,
+    slug: state.featureSlug,
+    title,
+    description,
+    lane: "backlog",
+    designDoc: designDocPath ?? null,
+  });
+
+  // Set state_file path
+  const sf = stateFilePath(state.featureSlug, stateDir());
+  db.updateFeature({ featureId, stateFile: sf });
+
+  // Lock first (safe — still in backlog, no agent picks from there)
+  if (sessionId) {
+    const locked = db.lockFeature(featureId, sessionId);
+    if (!locked) {
+      log.warn(`[kanban-hooks] failed to lock feature ${featureId} — already locked`);
+    } else {
+      db.updateFeature({ featureId, assignedSession: sessionId });
+    }
+  }
+
+  // Now move to the target lane — feature is locked, safe to move
+  // (design doc -> "design", task-plan -> "in-progress").
+  db.moveFeature({
+    featureId,
+    toLane: targetLane,
+    changedBy: "workflow-monitor",
+    note: `Doc written — moving from backlog to ${targetLane}`,
+  });
+
+  state.featureId = featureId;
+  saveFeatureState(state, DEFAULT_DIR);
+}