avtc-pi-featyard 1.1.0

package/src/state/artifact-paths.ts

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Artifact directory path constants — single source of truth.
+ *
+ * Design docs live either IN-REPO (`docs/featyard/designs/`, tracked) or OUT of the repo under `.featyard/designs/`
+ * (the gitignored `.featyard/` junction → `~/.pi/featyard/artifacts/<key>/`), per the `designDocStorage`
+ * setting. Task-plans, research, and reviews always live under `.featyard/`. All consumers (feature-state,
+ * template-substitution, guardrails, feature-management, phase-progression, review-context) import
+ * these to avoid drift.
+ *
+ * This is a LEAF module (no imports from other extension modules) so it can be imported safely
+ * from anywhere without creating circular-dependency cycles (e.g. feature-state ↔ phase-progression).
+ * The design-doc directory depends on the `designDocStorage` setting, so it is RESOLVED by callers
+ * (which pass the mode in) rather than read here — keeping this module settings-free.
+ */
+
+/** Design-doc storage mode (mirrors the `designDocStorage` setting values). */
+export type DesignDocStorageMode = "local" | "committed";
+
+/**
+ * Directory holding design docs, RELATIVE to the project root, for a given storage mode.
+ *
+ * - `committed` → `docs/featyard/designs/` — in-repo, tracked in git (published with the repo, survives clone).
+ * - `local` → `.featyard/designs/` — out-of-repo via the gitignored `.featyard/` junction (not committed,
+ *   survives worktree removal, shared across worktrees of the project).
+ *
+ * Kept relative so it composes under any project root and resolves identically via git mv,
+ * guardrail prefix-checks, and path.resolve. The `.featyard/` path resolves through the junction
+ * transparently; the guardrails' string-prefix checks match because agents write to this relative
+ * path.
+ */
+export function resolveDesignRelativeDir(mode: DesignDocStorageMode): string {
+  return mode === "local" ? ".featyard/designs" : "docs/featyard/designs";
+}
+
+/**
+ * Both recognized design-doc directories (relative), in no particular order. Detection/guarding
+ * recognize EITHER location so a project can carry docs from both modes (e.g. committed docs from
+ * before a switch to local, or vice-versa) without the current `designDocStorage` mode gating which
+ * writes count as design-doc writes. New docs are written to {@link resolveDesignRelativeDir} for
+ * the active mode (via the skill marker); this list is for read-side detection only.
+ */
+export const DESIGN_DOC_DIRS: readonly string[] = [
+  resolveDesignRelativeDir("local"),
+  resolveDesignRelativeDir("committed"),
+];
+export const FY_TASK_PLANS_DIR = ".featyard/task-plans";
+export const FY_RESEARCH_DIR = ".featyard/research";
+export const FY_REVIEWS_DIR = ".featyard/reviews";
+
+/** Sentinel for resolveKnownIssuesPath: no per-task scope (design/plan/feature-level review). */
+export const NO_TASK_NUM: string | undefined = undefined;
+
+/**
+ * Slugify a plan-task designation (which includes its number, e.g. '3. Wire the login form')
+ * into a path-safe key used in review/verify/known-issues filenames and the per-task review
+ * loop counter. Lowercases, collapses runs of non-alphanumeric chars to a single `-`, trims edges.
+ */
+export function slugifyTaskDesignation(task: string): string {
+  return task
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Resolve the known-issues file path for a feature, scoped by phase so design and plan
+ * review dismissals stay separate from each other and from code-review dismissals.
+ *   - "design"      -> {slug}-design-known-issues.md
+ *   - "plan"        -> {slug}-plan-known-issues.md
+ *   - otherwise     -> per-task ({slug}-task-{taskNameSlug}-known-issues.md) when taskName is active,
+ *                      else per-feature ({slug}-known-issues.md)
+ * taskName, when active, is the plan-task designation string set by task_ready_advance
+ * (slugified here for path safety). phase is a plain string (not the Phase union) to keep this module a dependency-free
+ * leaf; callers pass a typed Phase which is assignable to string. Returns null when slug
+ * is absent.
+ */
+export function resolveKnownIssuesPath(
+  slug: string | undefined,
+  phase: string | undefined,
+  taskName: string | undefined,
+): string | null {
+  if (!slug) return null;
+  return phase === "design"
+    ? `${FY_REVIEWS_DIR}/${slug}/${slug}-design-known-issues.md`
+    : phase === "plan"
+      ? `${FY_REVIEWS_DIR}/${slug}/${slug}-plan-known-issues.md`
+      : taskName
+        ? `${FY_REVIEWS_DIR}/${slug}/${slug}-task-${slugifyTaskDesignation(taskName)}-known-issues.md`
+        : `${FY_REVIEWS_DIR}/${slug}/${slug}-known-issues.md`;
+}
+
+/**
+ * Date-based fallback known-issues path when no feature slug is active.
+ * Mirrors the report-path fallback (buildFallbackReportPath) so a manual skill
+ * invocation without an active workflow still has a writable file.
+ * Single stable file per scope per date (known-issues accumulate), phase-scoped so
+ * design/plan/task/review dismissals stay separate:
+ *   - "design"      -> {date}/{date}-design-known-issues.md
+ *   - "plan"        -> {date}/{date}-plan-known-issues.md
+ *   - taskName active-> {date}/{date}-task-{taskNameSlug}-known-issues.md
+ *   - otherwise     -> {date}/{date}-review-known-issues.md
+ * date is a yyyy-mm-dd string passed in to keep this a dependency-free leaf module.
+ */
+export function buildFallbackKnownIssuesPath(
+  date: string,
+  phase: string | undefined,
+  taskName: string | undefined,
+): string {
+  const suffix =
+    phase === "design"
+      ? "design-known-issues"
+      : phase === "plan"
+        ? "plan-known-issues"
+        : taskName
+          ? `task-${slugifyTaskDesignation(taskName)}-known-issues`
+          : "review-known-issues";
+  return `${FY_REVIEWS_DIR}/${date}/${date}-${suffix}.md`;
+}
+
+/** Regex special characters that need escaping in filename patterns. */
+const REGEX_SPECIAL_CHARS = /[.+?^${}()|[\]\\]/g;
+
+/** Sanitize a string for use in filenames: strip path separators, traversal, and unsafe chars. */
+function sanitizeForFilename(value: string): string {
+  return value
+    .replace(/\.\./g, "") // path traversal
+    .replace(/[\\/]/g, "-") // path separators
+    .replace(/[^a-zA-Z0-9._-]/g, "") // keep only filename-safe chars
+    .replace(/--+/g, "-") // collapse repeated hyphens
+    .replace(/^-|-$/g, ""); // strip leading/trailing hyphens
+}
+
+/**
+ * Build a report file path with the standard naming convention.
+ * The slug already includes the date prefix (e.g. "2026-05-18-session-todo"),
+ * so the filename uses the slug directly without a separate date prefix.
+ *
+ * Scans the slug directory for existing numbered files and picks
+ * max(loopNumber, nextAvailable) to prevent overwrites when the in-memory
+ * counter is out of sync (manual skill dispatch, session restart, etc).
+ *
+ * @param _fs - Optional filesystem mock for testing.
+ */
+export function buildReportFilePath(
+  slug: string,
+  prefix: string,
+  loopNumber: number | null, // no-optional-params: null = no loop suffix, number = include suffix
+  _fs: typeof import("node:fs"),
+): string {
+  const safeSlug = sanitizeForFilename(slug);
+  const safePrefix = sanitizeForFilename(prefix);
+  const dir = `${FY_REVIEWS_DIR}/${safeSlug}`;
+
+  // Scan for existing files matching {slug}-{prefix}-{N}.md
+  const escapedSlug = safeSlug.replace(REGEX_SPECIAL_CHARS, "\\$&");
+  const escapedPrefix = safePrefix.replace(REGEX_SPECIAL_CHARS, "\\$&");
+  const pattern = new RegExp(`^${escapedSlug}-${escapedPrefix}-(\\d+)\\.md$`);
+
+  let maxExisting = -1; // -1 means no numbered file exists yet
+  try {
+    if (_fs.existsSync(dir)) {
+      for (const entry of _fs.readdirSync(dir)) {
+        const match = entry.match(pattern);
+        if (match) {
+          const n = parseInt(match[1], 10);
+          if (n > maxExisting) maxExisting = n;
+        }
+      }
+    }
+  } catch {
+    // directory might not exist yet — that's fine
+  }
+
+  const nextFromFs = maxExisting + 1; // 0 if no files exist (maxExisting = -1)
+
+  if (loopNumber != null) {
+    const effectiveLoop = Math.max(loopNumber, nextFromFs);
+    return `${dir}/${safeSlug}-${safePrefix}-${effectiveLoop}.md`;
+  }
+
+  // loopNumber undefined: only add suffix if files already exist (avoid collision)
+  if (nextFromFs > 0) {
+    return `${dir}/${safeSlug}-${safePrefix}-${nextFromFs}.md`;
+  }
+  return `${dir}/${safeSlug}-${safePrefix}.md`;
+}
+
+/**
+ * Build a date-based fallback report path when no slug/feature is active.
+ * Scans {FY_REVIEWS_DIR}/{date}/ for existing files matching {date}-{topic}-{agentName}-{N}.md,
+ * finds the highest N for this topic+agentName combo, and returns the next available path.
+ * Creates the date subdirectory if it doesn't exist.
+ */
+export function buildFallbackReportPath(
+  date: string,
+  topic: string,
+  agentName: string | undefined,
+  _fs: typeof import("node:fs"),
+): string {
+  const reviewsDir = FY_REVIEWS_DIR;
+  const dateDir = `${reviewsDir}/${date}`;
+  const safeTopic = sanitizeForFilename(topic) || "review";
+  const safeAgent = agentName ? sanitizeForFilename(agentName) : undefined;
+  const escapedDate = date.replace(/-/g, "\\-");
+  const escapedTopic = safeTopic.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const agentSuffix = safeAgent ? `-${safeAgent.replace(/[.+?^${}()|[\]\\]/g, "\\$&")}` : "";
+  const pattern = new RegExp(`^${escapedDate}-${escapedTopic}${agentSuffix}-(\\d+)\\.md$`);
+
+  let maxN = 0;
+  try {
+    if (_fs.existsSync(dateDir)) {
+      for (const entry of _fs.readdirSync(dateDir)) {
+        const match = entry.match(pattern);
+        if (match) {
+          const n = parseInt(match[1], 10);
+          if (n > maxN) maxN = n;
+        }
+      }
+    }
+  } catch {
+    // If filesystem access fails, start from 1
+  }
+  // Ensure the directory exists (mkdirSync with recursive is a no-op if it already exists)
+  _fs.mkdirSync(dateDir, { recursive: true });
+
+  return `${dateDir}/${date}-${safeTopic}${agentSuffix}-${maxN + 1}.md`;
+}

package/src/state/feature-activation.ts

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Feature activation — bring a feature into the active handler session from a
+ * design-doc write, plan-doc write, or skill invocation.
+ *
+ * Three entry points share a common bootstrap skeleton (load-or-create +
+ * optional kanban-link + activate + track + setPhase):
+ *  - {@link activateFromDocWrite}   — design/plan doc WRITE (tool_call path)
+ *  - {@link activateFromPlanSkill}  — fy-implement skill invocation (plan-doc source)
+ *  - {@link activateFromDesignSkill} — fy-plan / fy-design skill invocation (design-doc source)
+ *
+ * The guardrails engine and the events/input router call these; the activation
+ * logic itself has no knowledge of pi.on events.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ExecFn, resolveMainRepoPath, resolveMainRepoPathSync } from "../git/worktrees/worktree-lifecycle.js";
+import { interactiveSessionIdFor } from "../kanban/data/kanban-database.js";
+import type { Lane } from "../kanban/data/kanban-types.js";
+import { ensureKanbanFeature } from "../kanban/ensure-feature.js";
+import { log } from "../log.js";
+import { setActiveFeatureEnv } from "../phases/env-sync.js";
+import type { Phase } from "../phases/phase-progression.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import { trackSessionFileInState } from "./feature-management.js";
+import {
+  createFeatureState,
+  createFeatureStateFromPlan,
+  DEFAULT_DIR,
+  type FeatureState,
+  loadFeatureState,
+  saveFeatureState,
+} from "./feature-state.js";
+
+/** Callbacks the doc-write activator needs from the composition root (git exec + sub-feature writer). */
+export interface ActivationDeps {
+  /** Build a git exec helper from the extension context (for main-repo resolution). */
+  createGitExec: (ctx: ExtensionContext) => ExecFn;
+  /** Handle a write to a doc belonging to a non-active (sub) feature. */
+  handleSubFeatureWrite: (
+    ctx: ExtensionContext,
+    slug: string,
+    filePath: string,
+    artifactType: "design" | "plan",
+    activeSlugForLog: string | null,
+  ) => Promise<void>;
+}
+
+/** Doc-slot accessors — how to read/write the design or plan doc path on a FeatureState. */
+export interface DocSlotAccess {
+  getDoc: (s: FeatureState) => string | null;
+  setDoc: (s: FeatureState, value: string) => void;
+}
+
+/** Common bootstrap: link a freshly-created feature to the kanban board (best-effort). */
+async function linkToKanbanAsync(
+  ctx: ExtensionContext,
+  deps: ActivationDeps,
+  featureState: FeatureState,
+  slug: string,
+  lane: Lane,
+): Promise<void> {
+  try {
+    const { ensureDatabase } = await import("../kanban/kanban-bridge.js");
+    const kanbanDb = await ensureDatabase();
+    let mainRepoPath: string | null = null;
+    try {
+      const gitExec = deps.createGitExec(ctx);
+      mainRepoPath = await resolveMainRepoPath(gitExec);
+    } catch {
+      // Not in a git repo or worktree
+    }
+    // Mutates featureState in place (sets featureId) + persists it; featureState
+    // is our sole-owner record, adopted via setActiveFeatureState by the caller.
+    await ensureKanbanFeature(kanbanDb, featureState, mainRepoPath, interactiveSessionIdFor(slug), lane);
+  } catch {
+    // Kanban not available — feature state is still created + activated
+  }
+}
+
+/** Best-effort kanban link using the SYNC main-repo resolver (no git exec needed). */
+async function linkToKanbanSync(featureState: FeatureState, slug: string, lane: Lane): Promise<void> {
+  try {
+    const { ensureDatabase } = await import("../kanban/kanban-bridge.js");
+    const kanbanDb = await ensureDatabase();
+    let mainRepoPath: string | null = null;
+    try {
+      mainRepoPath = resolveMainRepoPathSync();
+    } catch {
+      // Not in a git repo — kanban linking proceeds with a null path
+    }
+    await ensureKanbanFeature(kanbanDb, featureState, mainRepoPath, interactiveSessionIdFor(slug), lane);
+  } catch {
+    // Kanban not available — feature state is still created + activated
+  }
+}
+
+/** Common tail: activate the feature in the handler + track its session file. */
+function activateInHandler(
+  ctx: ExtensionContext,
+  handler: FeatureSession,
+  featureState: FeatureState,
+  slug: string,
+): void {
+  // Activate FIRST so the handler holds the authoritative record; then tracking
+  // mutates that live ref directly (single source of truth) instead of loading a
+  // separate cached object that a later write-through would stomp.
+  setActiveFeatureEnv(slug);
+  handler.setActiveFeatureState(featureState);
+  trackSessionFileInState(ctx, slug);
+}
+
+/**
+ * Activate a feature from a design-doc or plan-doc WRITE.
+ *
+ * Returns true if the activation (re-activation or new creation) mutated state;
+ * false for a sub-feature write (delegated to handleSubFeatureWrite) or a no-op
+ * (the doc's feature is already active — recordDoc already recorded it).
+ */
+export async function activateFromDocWrite(
+  ctx: ExtensionContext,
+  handler: FeatureSession,
+  deps: ActivationDeps,
+  opts: {
+    slug: string;
+    filePath: string;
+    artifactType: "design" | "plan";
+    kanbanLane: Lane;
+    docSlot: DocSlotAccess;
+    create: (slug: string, filePath: string) => FeatureState;
+    postCreate: (() => Promise<void>) | null;
+  },
+): Promise<boolean> {
+  const { slug, filePath, artifactType, kanbanLane, docSlot, create, postCreate } = opts;
+  const activeSlug = handler.getActiveFeatureSlug();
+  const isAlreadyActive = activeSlug && activeSlug !== slug;
+
+  if (isAlreadyActive) {
+    await deps.handleSubFeatureWrite(ctx, slug, filePath, artifactType, activeSlug ?? null);
+    return false;
+  }
+
+  // Active feature === slug: doc already recorded by recordDoc — no-op.
+  if (activeSlug) return false;
+
+  // No active feature — bootstrap from the file.
+  const existing = loadFeatureState(slug, DEFAULT_DIR);
+  if (existing) {
+    if (!docSlot.getDoc(existing)) {
+      docSlot.setDoc(existing, filePath);
+      saveFeatureState(existing, DEFAULT_DIR);
+    }
+    // Re-activate an existing feature whose handler state was lost (e.g. after
+    // a reload that failed to bind). ensureKanbanFeature no-ops when featureId
+    // is set, so re-linking is idempotent and skipped here.
+    setActiveFeatureEnv(slug);
+    handler.setActiveFeatureState(existing);
+    return true;
+  }
+
+  // No state file — create a new feature, register it in the kanban, activate.
+  const featureState = create(slug, filePath);
+  saveFeatureState(featureState, DEFAULT_DIR);
+  await linkToKanbanAsync(ctx, deps, featureState, slug, kanbanLane);
+  activateInHandler(ctx, handler, featureState, slug);
+  if (postCreate) await postCreate();
+
+  // If still nothing is active (e.g. activation deferred), load + activate.
+  if (!handler.getActiveFeatureSlug()) {
+    const loaded = loadFeatureState(slug, DEFAULT_DIR);
+    if (loaded) handler.setActiveFeatureState(loaded);
+    setActiveFeatureEnv(slug);
+  }
+  return true;
+}
+
+/**
+ * Activate a feature from an fy-implement skill invocation (plan-doc source).
+ * Creates from the plan-doc path if no state exists; sets phase to "plan".
+ * No kanban linking (the plan-doc write path or a later fy-plan handles that).
+ */
+export function activateFromPlanSkill(
+  ctx: ExtensionContext,
+  handler: FeatureSession,
+  slug: string,
+  planDocPath: string,
+): void {
+  const existing = loadFeatureState(slug, DEFAULT_DIR);
+  if (existing) {
+    handler.setActiveFeatureState(existing);
+    setActiveFeatureEnv(slug);
+    return;
+  }
+  const featureState = createFeatureStateFromPlan(slug, planDocPath);
+  saveFeatureState(featureState, DEFAULT_DIR);
+  handler.setActiveFeatureState(featureState);
+  trackSessionFileInState(ctx, slug);
+  setActiveFeatureEnv(slug);
+  handler.setCurrentPhase("plan");
+}
+
+/**
+ * Activate a feature from an fy-plan / fy-design skill invocation (design-doc
+ * source). Activates an existing feature or creates + kanban-links a new one,
+ * then advances to the target phase (plan for fy-plan, design for fy-design).
+ * Uses the SYNC main-repo resolver (no git exec / ActivationDeps needed).
+ */
+export async function activateFromDesignSkill(
+  ctx: ExtensionContext,
+  handler: FeatureSession,
+  slug: string,
+  designDocPath: string,
+  targetPhase: Phase,
+): Promise<void> {
+  // A feature is already active — never displace it.
+  if (handler.getActiveFeatureSlug()) return;
+
+  const existing = loadFeatureState(slug, DEFAULT_DIR);
+  if (existing) {
+    setActiveFeatureEnv(slug);
+    handler.setActiveFeatureState(existing);
+    log.info(`[workflow] activateFromDesignSkill: re-activated existing feature ${slug}`);
+    return;
+  }
+
+  const featureState = createFeatureState(slug, designDocPath);
+  saveFeatureState(featureState, DEFAULT_DIR);
+  const lane: Lane = targetPhase === "plan" ? "in-progress" : "design";
+  await linkToKanbanSync(featureState, slug, lane);
+  activateInHandler(ctx, handler, featureState, slug);
+  // createFeatureState starts at "design"; advance to plan when invoked via
+  // fy-plan (the design doc already exists → design effectively complete).
+  if (targetPhase === "plan") {
+    handler.setCurrentPhase("plan");
+  }
+  log.info(`[workflow] activateFromDesignSkill: created + activated feature ${slug} (targetPhase=${targetPhase})`);
+}