frappe-builder 1.1.0-dev.9 → 1.2.0-dev.29

package/extensions/frappe-tools.ts

@@ -1,21 +1,20 @@
 import { Type } from "@sinclair/typebox";
-import { startFeature, completeComponent } from "../tools/feature-tools.js";
+import type { PiPlugin } from "./pi-types.js";
+import { startFeature, completeComponent, createComponent } from "../tools/feature-tools.js";
 import { setActiveProject, getProjectStatus } from "../tools/project-tools.js";
 import { getAuditLog } from "../state/journal.js";
 import { invokeDebugger, endDebug } from "../tools/debug-tools.js";
 import { spawnAgent } from "../tools/agent-tools.js";
-import { scaffoldDoctype, benchExecute, runTests } from "../tools/bench-tools.js";
+import { benchExecute, runTests } from "../tools/bench-tools.js";
 import { frappeQuery } from "../tools/frappe-query-tools.js";
-import { getFrappeDocs } from "../tools/frappe-context7.js";
+import { getLibraryDocs, getFrappeDocs } from "../tools/frappe-context7.js";
 
-// pi.registerTool's execute callback is untyped (pi is `any`); params are
-// enforced at runtime via TypeBox schemas. One explicit-any alias avoids
-// noImplicitAny errors across all callbacks without per-line suppressions.
+// pi.registerTool's execute callback params are enforced at runtime via TypeBox schemas.
+// ToolParams = any avoids noImplicitAny across all callbacks without per-line suppressions.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type ToolParams = any;
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
+export default function (pi: PiPlugin) {
   pi.registerTool({
     name: "start_feature",
     label: "Start Feature",
@@ -54,6 +53,26 @@ export default function (pi: any) {
     },
   });
 
+  pi.registerTool({
+    name: "create_component",
+    label: "Create Component",
+    description:
+      "Registers a planned unit of work as an in-progress component for the active feature. Call this BEFORE writing any code — one component per logical deliverable. Updates sprint-status.yaml and sets the active component on the session. Valid in planning and implementation phases.",
+    parameters: Type.Object({
+      featureId: Type.String({ description: "Feature ID (kebab-case slug, e.g. 'po-approval')" }),
+      componentId: Type.String({ description: "Component ID (e.g. 'auth-module', 'po-doctype')" }),
+      description: Type.Optional(Type.String({ description: "Short description of what this component implements" })),
+      sortOrder: Type.Optional(Type.Number({ description: "Order within the feature (lower = earlier)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = createComponent(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
   pi.registerTool({
     name: "set_active_project",
     label: "Set Active Project",
@@ -62,6 +81,9 @@ export default function (pi: any) {
     parameters: Type.Object({
       projectId: Type.String({ description: "Project identifier (e.g. 'my-frappe-site')" }),
       sitePath: Type.String({ description: "Absolute path to the Frappe bench site (e.g. '/home/user/frappe-bench/sites/site1.local')" }),
+      siteUrl: Type.Optional(Type.String({ description: "Frappe site URL (e.g. 'http://site1.localhost'). Required for frappe_query." })),
+      apiKey: Type.Optional(Type.String({ description: "Frappe API key from User > API Access. Required for frappe_query." })),
+      apiSecret: Type.Optional(Type.String({ description: "Frappe API secret from User > API Access. Required for frappe_query." })),
     }),
     execute: async (_toolCallId: string, params: ToolParams) => {
       const result = await setActiveProject(params);
@@ -122,29 +144,11 @@ export default function (pi: any) {
     },
   });
 
-  pi.registerTool({
-    name: "scaffold_doctype",
-    label: "Scaffold DocType",
-    description:
-      "Creates a new Frappe DocType via bench. Valid only in the 'implementation' phase. (Story 4.2 deferred)",
-    parameters: Type.Object({
-      name: Type.String({ description: "DocType name in PascalCase (e.g. 'Purchase Order')" }),
-      module: Type.String({ description: "Frappe module name (e.g. 'Buying')" }),
-    }),
-    execute: async (_toolCallId: string, params: ToolParams) => {
-      const result = scaffoldDoctype(params);
-      return {
-        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
-        details: result,
-      };
-    },
-  });
-
   pi.registerTool({
     name: "run_tests",
     label: "Run Tests",
     description:
-      "Runs the Frappe test suite for the active feature via bench. Valid only in the 'testing' phase. (Epic 6)",
+      "NOT YET IMPLEMENTED (Epic 6 deferred). Returns an error. Use bench_execute with 'bench run-tests --app {app}' instead.",
     parameters: Type.Object({
       featureId: Type.Optional(Type.String({ description: "Feature ID to scope tests (optional)" })),
     }),
@@ -192,12 +196,31 @@ export default function (pi: any) {
     },
   });
 
-  // 9th tool — outside the 8 core Frappe-semantic tools; bypasses phase guard via ALWAYS_ALLOWED_TOOLS
+  // General-purpose library docs tool via context7 — bypasses phase guard via ALWAYS_ALLOWED_TOOLS
+  pi.registerTool({
+    name: "get_library_docs",
+    label: "Get Library Docs",
+    description:
+      "Retrieves up-to-date documentation for any library via context7 MCP (React, Next.js, Frappe, ERPNext, Python, etc.). Raw web content never enters the LLM context. Valid in any phase.",
+    parameters: Type.Object({
+      query: Type.String({ description: "What you want to know (e.g. 'how do hooks work', 'useEffect cleanup')" }),
+      library: Type.Optional(Type.String({ description: "Library name (e.g. 'frappe', 'react', 'nextjs'). Defaults to 'frappe'." })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await getLibraryDocs(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  // Frappe-specific alias kept for backwards compatibility
   pi.registerTool({
     name: "get_frappe_docs",
     label: "Get Frappe Docs",
     description:
-      "Retrieves compressed Frappe/ERPNext documentation via context7 MCP. Raw web content never enters the LLM context (~90% token reduction). Valid in any phase. (Story 4.4)",
+      "Retrieves Frappe/ERPNext documentation via context7. Alias for get_library_docs with library='frappe'. Valid in any phase.",
     parameters: Type.Object({
       topic: Type.String({ description: "Documentation topic (e.g. 'DocType', 'hooks', 'frappe.db')" }),
       version: Type.Optional(Type.String({ description: "Frappe version to scope docs (e.g. 'v15')" })),

package/extensions/frappe-ui.ts

@@ -1,72 +1,126 @@
 import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
 import { db, getCurrentPhase } from "../state/db.js";
+import { loadConfig } from "../config/loader.js";
+import { DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
+import type { PiPlugin, PiUiContext } from "./pi-types.js";
 
-interface FooterState {
+interface DashboardState {
   projectId: string | null;
   featureName: string | null;
+  featureMode: string | null;
+  componentId: string | null;
   phase: string;
-  tokenCount: number;
+  chainStep: string | null;
+  progressDone: number;
+  progressTotal: number;
+  permissionMode: string;
 }
 
-function readFooterState(): FooterState {
+// Keep FooterState alias so existing tests compile without changes.
+type FooterState = Pick<DashboardState, "projectId" | "featureName" | "componentId">;
+
+function readDashboardState(): DashboardState {
   try {
     const session = db
       .prepare(
-        `SELECT s.project_id, f.name AS feature_name, s.current_phase
+        `SELECT s.project_id, s.current_phase, s.component_id, s.chain_step,
+                f.name AS feature_name, f.mode AS feature_mode,
+                f.progress_done, f.progress_total
          FROM sessions s
          LEFT JOIN features f ON f.feature_id = s.feature_id
          WHERE s.is_active = 1 LIMIT 1`
       )
       .get() as
-      | { project_id: string | null; feature_name: string | null; current_phase: string }
+      | {
+          project_id: string | null;
+          current_phase: string;
+          component_id: string | null;
+          chain_step: string | null;
+          feature_name: string | null;
+          feature_mode: string | null;
+          progress_done: number | null;
+          progress_total: number | null;
+        }
       | undefined;
 
-    // Token count: count journal_entries for active session; table may not exist yet
-    let tokenCount = 0;
-    try {
-      const tokenRow = db
-        .prepare(
-          `SELECT COUNT(*) as count FROM journal_entries
-           WHERE session_id = (SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1)`
-        )
-        .get() as { count: number } | undefined;
-      tokenCount = tokenRow?.count ?? 0;
-    } catch {
-      // journal_entries table not yet created — default to 0
-    }
+    const permissionMode = (() => {
+      try { return loadConfig().permissionMode ?? DEFAULT_PERMISSION_MODE; } catch { return DEFAULT_PERMISSION_MODE; }
+    })();
 
     return {
       projectId: session?.project_id ?? null,
       featureName: session?.feature_name ?? null,
+      featureMode: session?.feature_mode ?? null,
+      componentId: session?.component_id ?? null,
       phase: session?.current_phase ?? "idle",
-      tokenCount,
+      chainStep: session?.chain_step ?? null,
+      progressDone: session?.progress_done ?? 0,
+      progressTotal: session?.progress_total ?? 0,
+      permissionMode,
     };
   } catch {
-    return { projectId: null, featureName: null, phase: "idle", tokenCount: 0 };
+    return { projectId: null, featureName: null, featureMode: null, componentId: null, phase: "idle", chainStep: null, progressDone: 0, progressTotal: 0, permissionMode: DEFAULT_PERMISSION_MODE };
   }
 }
 
 /**
- * Pure formatting function — no I/O, no side effects.
+ * Formats dashboard state as a string[] for ctx.ui.setWidget().
  * Exported for unit testing.
  */
-export function formatFooter(state: FooterState): string {
+export function formatDashboard(state: DashboardState): string[] {
   if (!state.projectId) {
-    return `No active project | Phase: ${state.phase}`;
+    return ["frappe-builder  |  No active project"];
   }
-  if (!state.featureName) {
-    return `Project: ${state.projectId} | No active feature | Phase: ${state.phase}`;
+
+  const parts: string[] = [`Project: ${state.projectId}`];
+
+  if (state.featureName) {
+    const modeTag = state.featureMode ? ` [${state.featureMode}]` : "";
+    parts.push(`Feature: ${state.featureName}${modeTag}`);
+  } else {
+    parts.push("No active feature");
+  }
+
+  if (state.componentId) {
+    parts.push(`Component: ${state.componentId}`);
+  }
+
+  if (state.phase === "chain_running") {
+    parts.push(`Phase: chain:${state.chainStep ?? "starting"}`);
+  } else {
+    parts.push(`Phase: ${state.phase}`);
+  }
+
+  if (state.progressTotal > 0) {
+    parts.push(`${state.progressDone}/${state.progressTotal} components`);
   }
-  return `Project: ${state.projectId} | Feature: ${state.featureName} | Phase: ${state.phase} | Tokens: ${state.tokenCount}`;
+
+  parts.push(`Mode: ${state.permissionMode}`);
+
+  return [`frappe-builder  |  ${parts.join("  |  ")}`];
+}
+
+/**
+ * Legacy single-line footer format — kept for backward-compat with existing tests.
+ * Exported for unit testing.
+ */
+export function formatFooter(state: FooterState): string {
+  if (!state.projectId) return "No active project";
+  if (!state.featureName) return `Project: ${state.projectId} | No active feature`;
+  if (!state.componentId) return `Project: ${state.projectId} | Feature: ${state.featureName}`;
+  return `Project: ${state.projectId} | Feature: ${state.featureName} | Component: ${state.componentId}`;
 }
 
-function renderFooter(): void {
+function renderWidget(ctx: PiUiContext | undefined): void {
   try {
-    const state = readFooterState();
-    const line = formatFooter(state);
-    process.stderr.write(`\r\x1b[2K[frappe-builder] ${line}\n`);
+    const lines = formatDashboard(readDashboardState());
+    ctx?.ui.setWidget?.("frappe-builder", lines, { placement: "aboveEditor" });
   } catch {
-    // Silently swallow all rendering errors — footer is non-critical
+    // Fallback: write to stderr if widget API unavailable
+    try {
+      const state = readDashboardState();
+      process.stderr.write(`\r\x1b[2K[frappe-builder] ${formatDashboard(state).join(" ")}\n`);
+    } catch { /* non-critical */ }
   }
 }
 
@@ -98,22 +152,28 @@ export async function handleAfterToolCall(
   _context: AfterToolCallContext,
   _signal?: AbortSignal
 ): Promise<AfterToolCallResult | undefined> {
-  renderFooter();
   return undefined;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
-  pi.on("session_start", () => {
-    renderFooter();
+export default function (pi: PiPlugin) {
+  pi.on("session_start", (_event?: unknown, ctx?: PiUiContext) => {
+    renderWidget(ctx);
   });
 
   // Announcement hook — fires before FSM guard in frappe-workflow.ts (FR25)
-  pi.on("tool_call", (event: { toolName?: string }) => {
-    return handleBeforeToolCall(event.toolName ?? "");
+  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }, ctx?: PiUiContext) => {
+    try {
+      const state = readDashboardState();
+      const lines = formatDashboard(state);
+      const callLine = `→ ${event.toolName ?? "tool"} [${state.phase}]`;
+      ctx?.ui.setWidget?.("frappe-builder", [...lines, callLine], { placement: "aboveEditor" });
+    } catch {
+      handleBeforeToolCall(event.toolName ?? "");
+    }
   });
 
-  pi.on("after_tool_call", async (context: AfterToolCallContext) => {
-    return await handleAfterToolCall(context);
+  // "tool_result" fires after each tool completes — update the persistent widget.
+  pi.on("tool_result", (_event?: unknown, ctx?: PiUiContext) => {
+    renderWidget(ctx);
   });
 }

package/extensions/frappe-workflow.ts

@@ -1,26 +1,37 @@
 import { getCurrentPhase, db } from "../state/db.js";
 import { isToolAllowedInPhase, getValidPhase, type Phase } from "../state/fsm.js";
 import { appendEntry } from "../state/journal.js";
+import { loadConfig } from "../config/loader.js";
+import { type PermissionMode, DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
+import { ALWAYS_ALLOWED_TOOLS, WRITE_TOOLS } from "../config/constants.js";
+import type { PiPlugin, PiUiContext } from "./pi-types.js";
+
+// Re-export for use in tests and other modules
+export type { PermissionMode };
+
+// WRITE_TOOLS imported from config/constants.ts — single source of truth
+export { WRITE_TOOLS };
 
 interface BlockedResponse {
   blocked: true;
   tool: string;
   current_phase: Phase;
-  valid_phase: Phase | "any";
+  valid_phase: string;
   message: string;
 }
 
 function buildBlockedResponse(
   tool: string,
   currentPhase: Phase,
-  validPhase: Phase | "any"
+  validPhase: Phase | Phase[] | "any"
 ): BlockedResponse {
+  const validLabel = Array.isArray(validPhase) ? validPhase.join(", ") : validPhase;
   return {
     blocked: true,
     tool,
     current_phase: currentPhase,
-    valid_phase: validPhase,
-    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validPhase}`,
+    valid_phase: validLabel,
+    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validLabel}`,
   };
 }
 
@@ -33,15 +44,14 @@ function buildBlockedResponse(
  *
  * Never throws — always returns a value or undefined.
  */
-// Tools valid in all phases — never blocked by the phase guard (FR34)
-const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_audit_log"];
+// ALWAYS_ALLOWED_TOOLS imported from config/constants.ts — single source of truth
 
 export function beforeToolCall(
   toolName: string,
   args: Record<string, unknown>
 ): BlockedResponse | undefined {
   // Always-allowed bypass — checked before everything else
-  if (ALWAYS_ALLOWED_TOOLS.includes(toolName)) return undefined;
+  if (ALWAYS_ALLOWED_TOOLS.has(toolName)) return undefined;
 
   const currentPhase = getCurrentPhase() as Phase;
 
@@ -73,13 +83,72 @@ export function beforeToolCall(
   return undefined; // allow
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
-  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }) => {
-    const result = beforeToolCall(event.toolName ?? "", event.input ?? {});
-    if (result) {
-      return { block: true, reason: result.message };
+/**
+ * Checks the active permission mode for write tools.
+ * - auto: always allowed
+ * - plan: always blocked with dry-run message
+ * - default: prompts via ctx.ui.input(); falls through if unavailable
+ *
+ * Returns a blocked response to halt execution, or undefined to allow.
+ * Never throws.
+ */
+export async function checkPermissionMode(
+  toolName: string,
+  mode: PermissionMode,
+  ctx?: PiUiContext,
+): Promise<BlockedResponse | undefined> {
+  if (!WRITE_TOOLS.has(toolName)) return undefined;
+  if (mode === "auto") return undefined;
+
+  if (mode === "plan") {
+    return {
+      blocked: true,
+      tool: toolName,
+      current_phase: getCurrentPhase() as Phase,
+      valid_phase: "any",
+      message: `[plan mode] ${toolName} is a write operation — dry-run only. Switch to default or auto mode to execute.`,
+    };
+  }
+
+  // default mode: prompt via ctx.ui.input()
+  if (ctx) {
+    try {
+      const answer = await ctx.ui.input?.(`Allow ${toolName}? (yes/no)`);
+      if (!["yes", "y"].includes(answer?.toLowerCase?.() ?? "")) {
+        return {
+          blocked: true,
+          tool: toolName,
+          current_phase: getCurrentPhase() as Phase,
+          valid_phase: "any",
+          message: `${toolName} blocked by user.`,
+        };
+      }
+    } catch {
+      // ctx.ui.input unavailable — fail open (allow)
+    }
+  }
+
+  return undefined;
+}
+
+export default function (pi: PiPlugin) {
+  pi.on("tool_call", async (event: { toolName?: string; input?: Record<string, unknown> }, ctx?: PiUiContext) => {
+    const toolName = event.toolName ?? "";
+
+    // Phase guard
+    const phaseResult = beforeToolCall(toolName, event.input ?? {});
+    if (phaseResult) {
+      return { block: true, reason: phaseResult.message };
+    }
+
+    // Permission mode guard (Story 9.2–9.4)
+    const config = loadConfig();
+    const mode: PermissionMode = config.permissionMode ?? DEFAULT_PERMISSION_MODE;
+    const permResult = await checkPermissionMode(toolName, mode, ctx);
+    if (permResult) {
+      return { block: true, reason: permResult.message };
     }
+
     return undefined;
   });
 }

package/extensions/pi-types.ts

@@ -0,0 +1,53 @@
+import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
+
+/** Minimal structural type for the pi event context — covers all current usages.
+ *  Methods are optional because the pi API is unversioned and tests use partial mocks.
+ *  All call sites wrap invocations in try-catch or use optional chaining. */
+export interface PiUiContext {
+  ui: Partial<{
+    setWidget(name: string, lines: string[], options?: { placement?: string }): void;
+    setStatus(name: string, message: string): void;
+    notify(message: string, severity: string): void;
+    input(prompt: string): Promise<string>;
+  }>;
+}
+
+/** Structural type for the `pi` plugin object passed to each extension's default export.
+ *  Derived from observed pi-agent-core v0.62.0 behaviour; no published schema exists. */
+export interface PiPlugin {
+  on(event: "session_start", handler: (event?: unknown, ctx?: PiUiContext) => void | Promise<void>): void;
+  on(event: "session_shutdown", handler: (event?: unknown, ctx?: PiUiContext) => void): void;
+  on(
+    event: "tool_call",
+    handler: (
+      event: { toolName?: string; input?: Record<string, unknown> },
+      ctx?: PiUiContext,
+    ) => unknown,
+  ): void;
+  on(event: "tool_result", handler: (event?: unknown, ctx?: PiUiContext) => void): void;
+  on(
+    event: "after_tool_call",
+    handler: (
+      ctx: AfterToolCallContext,
+      signal?: AbortSignal,
+    ) => AfterToolCallResult | undefined | Promise<AfterToolCallResult | undefined>,
+  ): void;
+  registerTool(definition: PiToolDefinition): void;
+  registerCommand?: (name: string, definition: PiCommandDefinition) => void;
+}
+
+export interface PiToolDefinition {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (toolCallId: string, params: unknown) => Promise<{
+    content: Array<{ type: string; text: string }>;
+    details?: unknown;
+  }>;
+}
+
+export interface PiCommandDefinition {
+  description: string;
+  handler: (args: string, ctx: Record<string, unknown>) => Promise<string>;
+}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.9",
+  "version": "1.2.0-dev.29",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
   "bin": {
     "frappe-builder": "./dist/cli.mjs"
   },
   "pi": {
-    "_note": "TODO: verify 'pi' field schema against @mariozechner/pi-agent-core docs — no schema found in installed package. Reference schema below is a best-guess pending confirmation.",
     "extensions": [
       "./extensions/frappe-session.ts",
       "./extensions/frappe-state.ts",
@@ -38,6 +37,7 @@
   "dependencies": {
     "@mariozechner/pi-agent-core": "0.62.0",
     "@mariozechner/pi-ai": "0.62.0",
+    "@mariozechner/pi-coding-agent": "^0.63.1",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.8.0",
     "execa": "^9.6.1",

package/state/artifacts.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { db } from "./db.js";
+
+/**
+ * Returns the artifact directory for a feature.
+ * When app_path is set: {app_path}/.frappe-builder/{featureId}/
+ * Fallback (no app_path): {cwd}/.frappe-builder/{featureId}/
+ */
+export function getArtifactDir(featureId: string): string {
+  const row = db
+    .prepare("SELECT app_path FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { app_path: string | null } | undefined;
+  const root = row?.app_path ?? process.cwd();
+  return join(root, ".frappe-builder", featureId);
+}
+
+/**
+ * Regenerates sprint-status.yaml for the given feature from current DB state.
+ * Called after every create_component and complete_component.
+ * Creates the artifact directory if it does not exist.
+ * Non-fatal — caller should catch any errors.
+ */
+export function regenerateSprintStatus(featureId: string): void {
+  const feature = db
+    .prepare("SELECT feature_id, name, mode, current_phase FROM features WHERE feature_id = ?")
+    .get(featureId) as
+    | { feature_id: string; name: string; mode: string; current_phase: string }
+    | undefined;
+
+  if (!feature) return;
+
+  const components = db
+    .prepare(
+      `SELECT component_id, description, sort_order, status, completed_at
+       FROM components WHERE feature_id = ?
+       ORDER BY sort_order ASC, component_id ASC`
+    )
+    .all(featureId) as Array<{
+      component_id: string;
+      description: string | null;
+      sort_order: number;
+      status: string;
+      completed_at: string | null;
+    }>;
+
+  const done = components.filter((c) => c.status === "complete").length;
+  const total = components.length;
+
+  const componentLines = components
+    .map((c) => {
+      const descLine = c.description
+        ? `    description: "${c.description.replace(/"/g, '\\"')}"`
+        : "";
+      return [
+        `  - id: ${c.component_id}`,
+        descLine,
+        `    sort_order: ${c.sort_order}`,
+        `    status: ${c.status}`,
+        `    completed_at: ${c.completed_at ?? "null"}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    })
+    .join("\n");
+
+  const yaml = `feature_id: ${feature.feature_id}
+feature_name: "${feature.name.replace(/"/g, '\\"')}"
+mode: ${feature.mode}
+phase: ${feature.current_phase}
+updated_at: ${new Date().toISOString()}
+
+components:
+${componentLines || "  []"}
+
+progress:
+  done: ${done}
+  total: ${total}
+`;
+
+  const artifactDir = getArtifactDir(featureId);
+  const implDir = join(artifactDir, "implementation-artifacts");
+  mkdirSync(implDir, { recursive: true });
+  writeFileSync(join(implDir, "sprint-status.yaml"), yaml, "utf-8");
+}