@kaddo/cli 3.72.2 → 3.74.0

package/dist/admin-server/index.js

@@ -61,6 +61,13 @@ import {
   getWorkItems as coreGetWorkItems,
   getWorkItem as coreGetWorkItem,
   WorkItemNotFoundError,
+  createWorkItem as coreCreateWorkItem,
+  updateWorkItem as coreUpdateWorkItem,
+  getWorkItemForEdit as coreGetWorkItemForEdit,
+  validateWorkItem as coreValidateWorkItem,
+  transitionWorkItem as coreTransitionWorkItem,
+  getWorkItemCaptureDefinition as coreGetCaptureDefinition,
+  WorkItemWriteError,
   exists,
   join,
   readFile
@@ -114,6 +121,60 @@ function getWorkItemDetail(dir, workItemId) {
     throw err;
   }
 }
+function assertValidWorkItemId(workItemId) {
+  if (!workItemId || workItemId.includes("..") || workItemId.includes("/") || workItemId.includes("\\") || workItemId.startsWith(".")) {
+    throw new CoreError("INVALID_WORK_ITEM_ID", "Invalid Work Item identifier.");
+  }
+}
+function mapWriteError(err) {
+  if (err instanceof WorkItemWriteError) throw new CoreError(err.code, err.message);
+  throw err;
+}
+function getCaptureDefinition() {
+  return coreGetCaptureDefinition();
+}
+function createWorkItemAdmin(dir, body) {
+  try {
+    const res = coreCreateWorkItem(dir, { intent: body.intent, type: body.type, answers: body.answers });
+    return { id: res.id, path: res.path, revision: res.revision, status: "draft" };
+  } catch (err) {
+    mapWriteError(err);
+  }
+}
+function getWorkItemEdit(dir, workItemId) {
+  assertValidWorkItemId(workItemId);
+  try {
+    return coreGetWorkItemForEdit(dir, workItemId);
+  } catch (err) {
+    mapWriteError(err);
+  }
+}
+function updateWorkItemAdmin(dir, workItemId, body) {
+  assertValidWorkItemId(workItemId);
+  try {
+    const res = coreUpdateWorkItem(dir, workItemId, body.model, body.expectedRevision);
+    return { id: workItemId, path: res.path, revision: res.revision };
+  } catch (err) {
+    mapWriteError(err);
+  }
+}
+function validateWorkItemAdmin(dir, workItemId) {
+  assertValidWorkItemId(workItemId);
+  try {
+    return coreValidateWorkItem(dir, workItemId);
+  } catch (err) {
+    mapWriteError(err);
+  }
+}
+function transitionWorkItemAdmin(dir, workItemId, to, expectedRevision) {
+  assertValidWorkItemId(workItemId);
+  try {
+    const res = coreTransitionWorkItem(dir, workItemId, to, expectedRevision);
+    return { id: workItemId, path: res.path, revision: res.revision, status: res.status };
+  } catch (err) {
+    mapWriteError(err);
+  }
+}
 function getModules(dir) {
   const mapped = loadMappedModules(dir);
   return {
@@ -255,226 +316,6 @@ var CoreError = class extends Error {
   code;
 };
 
-// src/server.ts
-async function createAdminServer(opts) {
-  const { projectDir, storage, staticDir, host = "127.0.0.1", port = 4173 } = opts;
-  const app = Fastify({ logger: false });
-  const sessionManager = new SessionManager(storage);
-  await app.register(fastifyCookie);
-  await app.register(fastifyCors, {
-    origin: `http://${host}:${port}`,
-    credentials: true
-  });
-  if (staticDir) {
-    await app.register(fastifyStatic, {
-      root: path.resolve(staticDir),
-      prefix: "/",
-      wildcard: false
-    });
-  }
-  const sessionId = sessionManager.createSession();
-  app.addHook("onRequest", async (request, reply) => {
-    if (!request.url.startsWith("/api/")) return;
-    if (request.url.startsWith("/api/v1/admin/session")) return;
-    if (request.url.startsWith("/api/v1/admin/health")) return;
-    const cookieSession = request.cookies["kaddo-session"];
-    if (!sessionManager.validateSession(cookieSession)) {
-      reply.code(401).send({ error: { code: "SESSION_INVALID", message: "Invalid or expired session." } });
-    }
-  });
-  app.get("/api/v1/admin/health", async () => ({ status: "ok" }));
-  app.get("/api/v1/admin/session", async (_request, reply) => {
-    reply.setCookie("kaddo-session", sessionId, {
-      path: "/",
-      httpOnly: true,
-      sameSite: "strict",
-      maxAge: 86400
-    });
-    return { status: "active" };
-  });
-  const coreRoute = (handler) => {
-    return async () => {
-      try {
-        return handler(projectDir);
-      } catch (err) {
-        if (err instanceof CoreError) {
-          return { error: { code: err.code, message: err.message } };
-        }
-        throw err;
-      }
-    };
-  };
-  app.get("/api/v1/admin/overview", coreRoute(getProjectOverview));
-  app.get("/api/v1/admin/project", coreRoute(getProjectSummary));
-  app.get("/api/v1/admin/knowledge", coreRoute(getKnowledgeSummary));
-  app.get(
-    "/api/v1/admin/work-items",
-    async (request) => {
-      try {
-        const { status, module, query } = request.query;
-        return getWorkItemsList(projectDir, { status, module, query });
-      } catch (err) {
-        if (err instanceof CoreError) {
-          return { error: { code: err.code, message: err.message } };
-        }
-        throw err;
-      }
-    }
-  );
-  app.get("/api/v1/admin/work-items/:workItemId", async (request, reply) => {
-    try {
-      return getWorkItemDetail(projectDir, request.params.workItemId);
-    } catch (err) {
-      if (err instanceof CoreError) {
-        const code = err.code === "WORK_ITEM_NOT_FOUND" ? 404 : err.code === "INVALID_WORK_ITEM_ID" ? 400 : 500;
-        return reply.code(code).send({ error: { code: err.code, message: err.message } });
-      }
-      throw err;
-    }
-  });
-  app.get("/api/v1/admin/modules", coreRoute(getModules));
-  app.get("/api/v1/admin/readiness", coreRoute(getProjectReadiness));
-  app.get("/api/v1/admin/route", coreRoute(getProjectRoute));
-  app.get("/api/v1/admin/findings", coreRoute(getFindings));
-  app.get("/api/v1/admin/knowledge/inventory", coreRoute(getKnowledgeInventory));
-  app.get("/api/v1/admin/knowledge/artifact/:artifactId", async (request) => {
-    try {
-      return getKnowledgeArtifactDetail(projectDir, request.params.artifactId);
-    } catch (err) {
-      if (err instanceof CoreError) {
-        return { error: { code: err.code, message: err.message } };
-      }
-      throw err;
-    }
-  });
-  if (staticDir) {
-    app.setNotFoundHandler(async (_request, reply) => {
-      return reply.sendFile("index.html");
-    });
-  }
-  return {
-    app,
-    sessionId,
-    sessionManager,
-    start: async () => {
-      await app.listen({ host, port });
-      return `http://${host}:${port}`;
-    },
-    stop: async () => {
-      sessionManager.invalidateAll();
-      await app.close();
-      await storage.close();
-    }
-  };
-}
-
-// src/storage/sqlite-storage.ts
-import { DatabaseSync } from "node:sqlite";
-var SQLiteAdminStorage = class {
-  constructor(dbPath) {
-    this.dbPath = dbPath;
-    this.db = new DatabaseSync(dbPath);
-    this.db.exec("PRAGMA journal_mode = WAL");
-    this.sessions = {
-      create: (session) => {
-        this.db.prepare(
-          "INSERT OR REPLACE INTO admin_sessions (id, created_at, expires_at) VALUES (?, ?, ?)"
-        ).run(session.id, session.createdAt, session.expiresAt);
-      },
-      findById: (id) => {
-        const row = this.db.prepare(
-          "SELECT id, created_at, expires_at FROM admin_sessions WHERE id = ?"
-        ).get(id);
-        if (!row) return void 0;
-        return { id: row.id, createdAt: row.created_at, expiresAt: row.expires_at };
-      },
-      deleteById: (id) => {
-        this.db.prepare("DELETE FROM admin_sessions WHERE id = ?").run(id);
-      },
-      deleteExpired: () => {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        this.db.prepare("DELETE FROM admin_sessions WHERE expires_at < ?").run(now);
-      }
-    };
-    this.preferences = {
-      get: (key) => {
-        const row = this.db.prepare(
-          "SELECT value FROM admin_preferences WHERE key = ?"
-        ).get(key);
-        return row?.value;
-      },
-      set: (key, value) => {
-        this.db.prepare(
-          "INSERT OR REPLACE INTO admin_preferences (key, value) VALUES (?, ?)"
-        ).run(key, value);
-      },
-      delete: (key) => {
-        this.db.prepare("DELETE FROM admin_preferences WHERE key = ?").run(key);
-      },
-      all: () => {
-        return this.db.prepare("SELECT key, value FROM admin_preferences").all();
-      }
-    };
-    this.cache = {
-      get: (key) => {
-        const row = this.db.prepare(
-          "SELECT value, expires_at FROM admin_cache WHERE key = ?"
-        ).get(key);
-        if (!row) return void 0;
-        if (row.expires_at && new Date(row.expires_at) < /* @__PURE__ */ new Date()) {
-          this.db.prepare("DELETE FROM admin_cache WHERE key = ?").run(key);
-          return void 0;
-        }
-        return row.value;
-      },
-      set: (key, value, ttlMs) => {
-        const expiresAt = ttlMs ? new Date(Date.now() + ttlMs).toISOString() : null;
-        this.db.prepare(
-          "INSERT OR REPLACE INTO admin_cache (key, value, expires_at) VALUES (?, ?, ?)"
-        ).run(key, value, expiresAt);
-      },
-      delete: (key) => {
-        this.db.prepare("DELETE FROM admin_cache WHERE key = ?").run(key);
-      },
-      clear: () => {
-        this.db.exec("DELETE FROM admin_cache");
-      }
-    };
-  }
-  dbPath;
-  db;
-  sessions;
-  preferences;
-  cache;
-  async initialize() {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS admin_sessions (
-        id TEXT PRIMARY KEY,
-        created_at TEXT NOT NULL,
-        expires_at TEXT NOT NULL
-      );
-      CREATE TABLE IF NOT EXISTS admin_preferences (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL
-      );
-      CREATE TABLE IF NOT EXISTS admin_cache (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL,
-        expires_at TEXT
-      );
-      CREATE TABLE IF NOT EXISTS audit_events (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        timestamp TEXT NOT NULL,
-        action TEXT NOT NULL,
-        detail TEXT
-      );
-    `);
-  }
-  async close() {
-    this.db.close();
-  }
-};
-
 // src/contracts/schemas.ts
 import { z } from "zod";
 var ProjectSummarySchema = z.object({
@@ -668,12 +509,676 @@ var WorkItemDetailSchema = WorkItemListItemSchema.extend({
   source: z.object({ type: z.string(), id: z.string().optional(), inferred: z.boolean() }).passthrough(),
   path: z.string()
 });
-var ErrorResponseSchema = z.object({
-  error: z.object({
-    code: z.string(),
-    message: z.string()
-  })
+var WorkItemInputSchema = z.object({
+  title: z.string(),
+  type: z.string(),
+  summary: z.string().optional(),
+  actor: z.string().optional(),
+  outcome: z.string().optional(),
+  currentBehavior: z.string().optional(),
+  targetBehavior: z.string().optional(),
+  entryPoints: z.string().optional(),
+  endToEndFlow: z.string().optional(),
+  scopeConfidence: z.object({ level: z.string(), reasons: z.array(z.string()) }).nullable(),
+  scopeUnknowns: z.array(z.string()),
+  affectedModules: z.array(z.string()),
+  moduleCoverage: z.array(z.object({ id: z.string(), status: z.string(), reason: z.string().optional() })),
+  impactAnalysis: z.array(z.object({ surface: z.string(), status: z.string(), reason: z.string().optional(), question: z.string().optional() })),
+  acceptanceCriteria: z.array(z.object({ text: z.string(), checked: z.boolean().nullable() })),
+  decisions: z.array(z.string()),
+  relatedKnowledge: z.array(z.string())
 });
+var WorkItemCreateSchema = z.object({
+  intent: z.string().min(1),
+  type: z.string().min(1)
+});
+var WorkItemUpdateSchema = z.object({
+  model: WorkItemInputSchema,
+  expectedRevision: z.string().min(1)
+});
+var WorkItemTransitionSchema = z.object({
+  expectedRevision: z.string().min(1)
+});
+var WorkItemEditModelSchema = WorkItemInputSchema.extend({
+  id: z.string(),
+  status: z.string(),
+  revision: z.string(),
+  path: z.string(),
+  editable: z.boolean(),
+  editableReason: z.string().optional()
+});
+var ValidationResultSchema = z.object({
+  findings: z.array(z.object({ level: z.enum(["blocking", "warning", "fyi"]), message: z.string() })),
+  canMarkReady: z.boolean()
+});
+var WorkItemWriteResultSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+  revision: z.string(),
+  status: z.string().optional()
+});
+var WorkItemCreateWithAnswersSchema = z.object({
+  intent: z.string().min(1),
+  type: z.string().min(1),
+  answers: z.record(z.string(), z.string()).optional()
+});
+var RefinementFeedbackSchema = z.object({
+  refinementId: z.string().min(1),
+  feedback: z.string().min(1)
+});
+var RefinementApplySchema = z.object({
+  refinementId: z.string().min(1),
+  expectedRevision: z.string().min(1)
+});
+var ErrorResponseSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string()
+  })
+});
+
+// src/refinement/service.ts
+import crypto from "crypto";
+import {
+  assembleRefinementContext,
+  getWorkItemAgentAssets,
+  normalizeAndValidateProposal,
+  applyRefinement,
+  WorkItemWriteError as WorkItemWriteError2
+} from "@kaddo/cli/core";
+
+// src/refinement/provider.ts
+var RefinementProviderError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RefinementProviderError";
+    this.code = code;
+  }
+};
+
+// src/refinement/service.ts
+var MAX_REPAIR_ATTEMPTS = 2;
+var DEFAULT_TIMEOUT_MS = 6e4;
+var RefinementService = class {
+  constructor(provider, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    this.provider = provider;
+    this.timeoutMs = timeoutMs;
+  }
+  provider;
+  timeoutMs;
+  sessions = /* @__PURE__ */ new Map();
+  view(s) {
+    return { ...s };
+  }
+  async run(dir, workItemId, feedback, previous) {
+    const context = assembleRefinementContext(dir, workItemId);
+    if (context.workItem.status !== "draft") {
+      throw new RefinementProviderError("WORK_ITEM_NOT_EDITABLE", `A ${context.workItem.status} Work Item cannot be refined. Reopen it as Draft first.`);
+    }
+    const assets = getWorkItemAgentAssets();
+    const request = { context, assets, intent: context.workItem.intent, previousProposal: previous, feedback };
+    let lastErr;
+    for (let attempt = 0; attempt <= MAX_REPAIR_ATTEMPTS; attempt++) {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+      try {
+        const result = await this.provider.refine(request, ac.signal);
+        const { validation } = normalizeAndValidateProposal(dir, workItemId, result.proposal);
+        const contextUsed = context.knowledge.map((k) => ({ id: k.id, title: k.title, layer: k.layer }));
+        return { context, proposal: result.proposal, validation, contextUsed, meta: { ...result.meta, repairAttempts: attempt } };
+      } catch (err) {
+        lastErr = err;
+        if (!(err instanceof RefinementProviderError && err.code === "INVALID_RESPONSE")) break;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new RefinementProviderError("PROVIDER_ERROR", "Refinement failed.");
+  }
+  async start(dir, workItemId) {
+    const { context, proposal, validation, contextUsed, meta } = await this.run(dir, workItemId);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const session = {
+      refinementId: `ref_${crypto.randomBytes(8).toString("hex")}`,
+      workItemId,
+      sourceRevision: context.revision,
+      status: "ready-for-review",
+      intent: context.workItem.intent,
+      proposal,
+      validation,
+      contextUsed,
+      meta,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.sessions.set(session.refinementId, session);
+    return this.view(session);
+  }
+  async feedback(dir, workItemId, refinementId, feedback) {
+    const session = this.get(refinementId, workItemId);
+    const { context, proposal, validation, contextUsed, meta } = await this.run(dir, workItemId, feedback, session.proposal);
+    session.sourceRevision = context.revision;
+    session.status = "ready-for-review";
+    session.proposal = proposal;
+    session.validation = validation;
+    session.contextUsed = contextUsed;
+    session.meta = meta;
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return this.view(session);
+  }
+  apply(dir, workItemId, refinementId, expectedRevision) {
+    const session = this.get(refinementId, workItemId);
+    const current = assembleRefinementContext(dir, workItemId);
+    if (current.revision !== session.sourceRevision || expectedRevision !== session.sourceRevision) {
+      session.status = "stale";
+      throw new RefinementProviderError("WORK_ITEM_CONFLICT", "This Work Item changed while the refinement was running. The proposal has not been applied.");
+    }
+    let res;
+    try {
+      res = applyRefinement(dir, workItemId, session.proposal, session.sourceRevision);
+    } catch (err) {
+      if (err instanceof WorkItemWriteError2) throw new RefinementProviderError(err.code, err.message);
+      throw err;
+    }
+    session.status = "applied";
+    session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return { id: workItemId, path: res.path, revision: res.revision, status: "draft" };
+  }
+  get(refinementId, workItemId) {
+    const s = this.sessions.get(refinementId);
+    if (!s || s.workItemId !== workItemId) throw new RefinementProviderError("REFINEMENT_NOT_FOUND", "Refinement session not found.");
+    return s;
+  }
+};
+
+// src/refinement/heuristic-provider.ts
+function firstSentence(s) {
+  const m = s.trim().match(/^(.*?[.!?])(\s|$)/);
+  return (m ? m[1] : s.trim()).trim();
+}
+function mentionsNegation(feedback, module) {
+  const re = new RegExp(`(not|no)\\b[^.]*\\b${module}\\b|\\b${module}\\b[^.]*(not affected|no afecta|reviewed)`, "i");
+  return re.test(feedback);
+}
+var HeuristicRefinementProvider = class {
+  name = "heuristic";
+  async refine(request) {
+    const start = Date.now();
+    const { context, intent, previousProposal, feedback } = request;
+    const modules = context.modules;
+    const affected = new Set(previousProposal?.affectedModules ?? ["core"]);
+    if (feedback) {
+      for (const m of modules) {
+        if (new RegExp(`\\b${m}\\b`, "i").test(feedback)) {
+          if (mentionsNegation(feedback, m)) affected.delete(m);
+          else affected.add(m);
+        }
+      }
+    }
+    const affectedModules = modules.filter((m) => affected.has(m));
+    const moduleCoverage = modules.map(
+      (m) => affected.has(m) ? { id: m, status: "affected", reason: m === "core" ? "Backend behavior changes." : "User-facing change identified." } : { id: m, status: "unknown" }
+    );
+    const frontendAffected = affected.has("frontend");
+    const impactAnalysis = [
+      { surface: "backend", status: "affected" },
+      { surface: "frontend", status: frontendAffected ? "affected" : "unknown", ...frontendAffected ? {} : { question: "Is a user-facing surface involved?" } },
+      { surface: "database", status: "reviewed-not-affected" },
+      { surface: "feature-flags", status: "unknown", question: "Is this behavior controlled by a feature flag?" }
+    ];
+    const summary = firstSentence(intent);
+    const proposal = {
+      outcome: {
+        actor: "User",
+        observableOutcome: summary,
+        currentBehavior: `Today: ${summary.toLowerCase()} is not yet supported as described.`,
+        targetBehavior: summary
+      },
+      journey: {
+        entryPoints: [frontendAffected ? "Public entry point" : "Application entry point"],
+        flow: ["Entry point", "Application logic", "Persistence", "Result"]
+      },
+      affectedModules,
+      moduleCoverage,
+      impactAnalysis,
+      scopeConfidence: {
+        level: "medium",
+        reasons: ["Primary behavior identified from the intent.", "Feature flag ownership not yet confirmed."]
+      },
+      scopeUnknowns: ["Is this behavior controlled by a feature flag?"],
+      acceptanceCriteria: [
+        `${summary}`,
+        "The change is covered by the affected modules above."
+      ],
+      linkedDecisions: [],
+      relatedKnowledge: []
+    };
+    return { proposal, meta: { provider: this.name, durationMs: Date.now() - start, repairAttempts: 0 } };
+  }
+};
+
+// src/refinement/anthropic-provider.ts
+var API_URL = "https://api.anthropic.com/v1/messages";
+var SCHEMA_HINT = `Return ONLY a JSON object (no prose, no code fences) with this shape \u2014 omit fields you cannot determine:
+{
+  "title"?: string,
+  "outcome"?: { "actor"?: string, "observableOutcome"?: string, "currentBehavior"?: string, "targetBehavior"?: string },
+  "journey"?: { "entryPoints"?: string[], "flow"?: string[] },
+  "affectedModules"?: string[],
+  "moduleCoverage"?: [{ "id": string, "status": "affected"|"reviewed-not-affected"|"unknown"|"not-applicable", "reason"?: string }],
+  "impactAnalysis"?: [{ "surface": string, "status": "affected"|"reviewed-not-affected"|"unknown"|"not-applicable", "reason"?: string, "question"?: string }],
+  "scopeConfidence"?: { "level": "high"|"medium"|"low", "reasons"?: string[] },
+  "scopeUnknowns"?: string[],
+  "acceptanceCriteria"?: string[],
+  "linkedDecisions"?: string[],
+  "relatedKnowledge"?: string[]
+}
+Only reference module ids, decision ids and knowledge ids that appear in the provided context. Prefer "unknown" over inventing facts.`;
+function extractJson(text) {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start < 0 || end <= start) throw new RefinementProviderError("INVALID_RESPONSE", "The model did not return a JSON proposal.");
+  try {
+    return JSON.parse(text.slice(start, end + 1));
+  } catch {
+    throw new RefinementProviderError("INVALID_RESPONSE", "The model returned a proposal that could not be parsed.");
+  }
+}
+var AnthropicRefinementProvider = class {
+  name = "anthropic";
+  apiKey;
+  model;
+  constructor(apiKey, model) {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+  async refine(request, signal) {
+    const start = Date.now();
+    const { context, assets, intent, previousProposal, feedback } = request;
+    const system = [
+      assets.agentPrompt,
+      assets.skill ?? "",
+      "# Output format",
+      SCHEMA_HINT
+    ].filter(Boolean).join("\n\n");
+    const userParts = [
+      `# Work Item intent
+${intent}`,
+      `# Project
+${JSON.stringify(context.project)}`,
+      `# Registered modules
+${context.modules.join(", ")}`,
+      `# Known decisions
+${context.decisions.map((d) => `${d.id} \u2014 ${d.title}`).join("\n") || "(none)"}`,
+      `# Knowledge
+${context.knowledge.map((k) => `${k.id} \u2014 ${k.title} (${k.layer})`).join("\n") || "(none)"}`,
+      `# Current Work Item model
+${JSON.stringify(context.workItem.current)}`
+    ];
+    if (previousProposal) userParts.push(`# Previous proposal
+${JSON.stringify(previousProposal)}`);
+    if (feedback) userParts.push(`# Human feedback (augments the original intent, does not replace it)
+${feedback}`);
+    let res;
+    try {
+      res = await fetch(API_URL, {
+        method: "POST",
+        signal,
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": "2023-06-01"
+        },
+        body: JSON.stringify({
+          model: this.model,
+          max_tokens: 2048,
+          system,
+          messages: [{ role: "user", content: userParts.join("\n\n") }]
+        })
+      });
+    } catch (err) {
+      if (err.name === "AbortError") throw new RefinementProviderError("TIMEOUT", "The refinement timed out.");
+      throw new RefinementProviderError("PROVIDER_ERROR", "The refinement provider could not be reached.");
+    }
+    if (!res.ok) {
+      throw new RefinementProviderError("PROVIDER_ERROR", `The refinement provider returned an error (${res.status}).`);
+    }
+    const body = await res.json();
+    const text = (body.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("");
+    const proposal = extractJson(text);
+    return {
+      proposal,
+      meta: {
+        provider: this.name,
+        model: this.model,
+        durationMs: Date.now() - start,
+        inputTokens: body.usage?.input_tokens,
+        outputTokens: body.usage?.output_tokens
+      }
+    };
+  }
+};
+
+// src/refinement/index.ts
+function createRefinementService() {
+  const key = process.env.ANTHROPIC_API_KEY;
+  const model = process.env.KADDO_REFINEMENT_MODEL || "claude-3-5-sonnet-latest";
+  const provider = key ? new AnthropicRefinementProvider(key, model) : new HeuristicRefinementProvider();
+  return new RefinementService(provider);
+}
+
+// src/server.ts
+var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+function statusForCode(code) {
+  switch (code) {
+    case "WORK_ITEM_NOT_FOUND":
+    case "REFINEMENT_NOT_FOUND":
+      return 404;
+    case "WORK_ITEM_CONFLICT":
+    case "WORK_ITEM_NOT_EDITABLE":
+      return 409;
+    case "INVALID_INPUT":
+    case "INVALID_WORK_ITEM_ID":
+    case "INVALID_TRANSITION":
+      return 400;
+    case "TIMEOUT":
+      return 504;
+    case "PROVIDER_ERROR":
+    case "INVALID_RESPONSE":
+      return 502;
+    default:
+      return 500;
+  }
+}
+async function createAdminServer(opts) {
+  const { projectDir, storage, staticDir, host = "127.0.0.1", port = 4173 } = opts;
+  const app = Fastify({ logger: false });
+  const sessionManager = new SessionManager(storage);
+  const refinement = createRefinementService();
+  await app.register(fastifyCookie);
+  await app.register(fastifyCors, {
+    origin: `http://${host}:${port}`,
+    credentials: true
+  });
+  if (staticDir) {
+    await app.register(fastifyStatic, {
+      root: path.resolve(staticDir),
+      prefix: "/",
+      wildcard: false
+    });
+  }
+  const sessionId = sessionManager.createSession();
+  app.addHook("onRequest", async (request, reply) => {
+    if (!request.url.startsWith("/api/")) return;
+    if (request.url.startsWith("/api/v1/admin/session")) return;
+    if (request.url.startsWith("/api/v1/admin/health")) return;
+    const cookieSession = request.cookies["kaddo-session"];
+    if (!sessionManager.validateSession(cookieSession)) {
+      reply.code(401).send({ error: { code: "SESSION_INVALID", message: "Invalid or expired session." } });
+    }
+  });
+  const allowedOrigin = `http://${host}:${port}`;
+  app.addHook("onRequest", async (request, reply) => {
+    if (!request.url.startsWith("/api/")) return;
+    if (!WRITE_METHODS.has(request.method)) return;
+    const origin = request.headers.origin;
+    if (!origin || origin !== allowedOrigin) {
+      reply.code(403).send({ error: { code: "FORBIDDEN_ORIGIN", message: "Cross-origin write requests are not allowed." } });
+    }
+  });
+  app.get("/api/v1/admin/health", async () => ({ status: "ok" }));
+  app.get("/api/v1/admin/session", async (_request, reply) => {
+    reply.setCookie("kaddo-session", sessionId, {
+      path: "/",
+      httpOnly: true,
+      sameSite: "strict",
+      maxAge: 86400
+    });
+    return { status: "active" };
+  });
+  const coreRoute = (handler) => {
+    return async () => {
+      try {
+        return handler(projectDir);
+      } catch (err) {
+        if (err instanceof CoreError) {
+          return { error: { code: err.code, message: err.message } };
+        }
+        throw err;
+      }
+    };
+  };
+  app.get("/api/v1/admin/overview", coreRoute(getProjectOverview));
+  app.get("/api/v1/admin/project", coreRoute(getProjectSummary));
+  app.get("/api/v1/admin/knowledge", coreRoute(getKnowledgeSummary));
+  app.get(
+    "/api/v1/admin/work-items",
+    async (request) => {
+      try {
+        const { status, module, query } = request.query;
+        return getWorkItemsList(projectDir, { status, module, query });
+      } catch (err) {
+        if (err instanceof CoreError) {
+          return { error: { code: err.code, message: err.message } };
+        }
+        throw err;
+      }
+    }
+  );
+  const writeHandler = (reply, fn) => {
+    try {
+      return fn();
+    } catch (err) {
+      if (err instanceof CoreError) {
+        return reply.code(statusForCode(err.code)).send({ error: { code: err.code, message: err.message } });
+      }
+      throw err;
+    }
+  };
+  app.get("/api/v1/admin/work-items-capture", coreRoute(() => getCaptureDefinition()));
+  app.post("/api/v1/admin/work-items", async (request, reply) => {
+    const parsed = WorkItemCreateWithAnswersSchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "Intent and type are required." } });
+    return writeHandler(reply, () => createWorkItemAdmin(projectDir, parsed.data));
+  });
+  app.get("/api/v1/admin/work-items/:workItemId/edit", async (request, reply) => {
+    return writeHandler(reply, () => getWorkItemEdit(projectDir, request.params.workItemId));
+  });
+  app.put("/api/v1/admin/work-items/:workItemId", async (request, reply) => {
+    const parsed = WorkItemUpdateSchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "A Work Item model and expectedRevision are required." } });
+    return writeHandler(reply, () => updateWorkItemAdmin(projectDir, request.params.workItemId, parsed.data));
+  });
+  app.post("/api/v1/admin/work-items/:workItemId/validate", async (request, reply) => {
+    return writeHandler(reply, () => validateWorkItemAdmin(projectDir, request.params.workItemId));
+  });
+  app.post("/api/v1/admin/work-items/:workItemId/transitions/ready", async (request, reply) => {
+    const parsed = WorkItemTransitionSchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "expectedRevision is required." } });
+    return writeHandler(reply, () => transitionWorkItemAdmin(projectDir, request.params.workItemId, "ready", parsed.data.expectedRevision));
+  });
+  app.post("/api/v1/admin/work-items/:workItemId/transitions/draft", async (request, reply) => {
+    const parsed = WorkItemTransitionSchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "expectedRevision is required." } });
+    return writeHandler(reply, () => transitionWorkItemAdmin(projectDir, request.params.workItemId, "draft", parsed.data.expectedRevision));
+  });
+  const refineHandler = async (reply, fn) => {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err instanceof RefinementProviderError || err instanceof CoreError) {
+        return reply.code(statusForCode(err.code)).send({ error: { code: err.code, message: err.message } });
+      }
+      throw err;
+    }
+  };
+  app.post("/api/v1/admin/work-items/:workItemId/refinement", async (request, reply) => {
+    return refineHandler(reply, () => refinement.start(projectDir, request.params.workItemId));
+  });
+  app.post("/api/v1/admin/work-items/:workItemId/refinement/feedback", async (request, reply) => {
+    const parsed = RefinementFeedbackSchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "refinementId and feedback are required." } });
+    return refineHandler(reply, () => refinement.feedback(projectDir, request.params.workItemId, parsed.data.refinementId, parsed.data.feedback));
+  });
+  app.post("/api/v1/admin/work-items/:workItemId/refinement/apply", async (request, reply) => {
+    const parsed = RefinementApplySchema.safeParse(request.body);
+    if (!parsed.success) return reply.code(400).send({ error: { code: "INVALID_INPUT", message: "refinementId and expectedRevision are required." } });
+    return refineHandler(reply, () => refinement.apply(projectDir, request.params.workItemId, parsed.data.refinementId, parsed.data.expectedRevision));
+  });
+  app.get("/api/v1/admin/work-items/:workItemId", async (request, reply) => {
+    try {
+      return getWorkItemDetail(projectDir, request.params.workItemId);
+    } catch (err) {
+      if (err instanceof CoreError) {
+        const code = err.code === "WORK_ITEM_NOT_FOUND" ? 404 : err.code === "INVALID_WORK_ITEM_ID" ? 400 : 500;
+        return reply.code(code).send({ error: { code: err.code, message: err.message } });
+      }
+      throw err;
+    }
+  });
+  app.get("/api/v1/admin/modules", coreRoute(getModules));
+  app.get("/api/v1/admin/readiness", coreRoute(getProjectReadiness));
+  app.get("/api/v1/admin/route", coreRoute(getProjectRoute));
+  app.get("/api/v1/admin/findings", coreRoute(getFindings));
+  app.get("/api/v1/admin/knowledge/inventory", coreRoute(getKnowledgeInventory));
+  app.get("/api/v1/admin/knowledge/artifact/:artifactId", async (request) => {
+    try {
+      return getKnowledgeArtifactDetail(projectDir, request.params.artifactId);
+    } catch (err) {
+      if (err instanceof CoreError) {
+        return { error: { code: err.code, message: err.message } };
+      }
+      throw err;
+    }
+  });
+  if (staticDir) {
+    app.setNotFoundHandler(async (_request, reply) => {
+      return reply.sendFile("index.html");
+    });
+  }
+  return {
+    app,
+    sessionId,
+    sessionManager,
+    start: async () => {
+      await app.listen({ host, port });
+      return `http://${host}:${port}`;
+    },
+    stop: async () => {
+      sessionManager.invalidateAll();
+      await app.close();
+      await storage.close();
+    }
+  };
+}
+
+// src/storage/sqlite-storage.ts
+import { DatabaseSync } from "node:sqlite";
+var SQLiteAdminStorage = class {
+  constructor(dbPath) {
+    this.dbPath = dbPath;
+    this.db = new DatabaseSync(dbPath);
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.sessions = {
+      create: (session) => {
+        this.db.prepare(
+          "INSERT OR REPLACE INTO admin_sessions (id, created_at, expires_at) VALUES (?, ?, ?)"
+        ).run(session.id, session.createdAt, session.expiresAt);
+      },
+      findById: (id) => {
+        const row = this.db.prepare(
+          "SELECT id, created_at, expires_at FROM admin_sessions WHERE id = ?"
+        ).get(id);
+        if (!row) return void 0;
+        return { id: row.id, createdAt: row.created_at, expiresAt: row.expires_at };
+      },
+      deleteById: (id) => {
+        this.db.prepare("DELETE FROM admin_sessions WHERE id = ?").run(id);
+      },
+      deleteExpired: () => {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        this.db.prepare("DELETE FROM admin_sessions WHERE expires_at < ?").run(now);
+      }
+    };
+    this.preferences = {
+      get: (key) => {
+        const row = this.db.prepare(
+          "SELECT value FROM admin_preferences WHERE key = ?"
+        ).get(key);
+        return row?.value;
+      },
+      set: (key, value) => {
+        this.db.prepare(
+          "INSERT OR REPLACE INTO admin_preferences (key, value) VALUES (?, ?)"
+        ).run(key, value);
+      },
+      delete: (key) => {
+        this.db.prepare("DELETE FROM admin_preferences WHERE key = ?").run(key);
+      },
+      all: () => {
+        return this.db.prepare("SELECT key, value FROM admin_preferences").all();
+      }
+    };
+    this.cache = {
+      get: (key) => {
+        const row = this.db.prepare(
+          "SELECT value, expires_at FROM admin_cache WHERE key = ?"
+        ).get(key);
+        if (!row) return void 0;
+        if (row.expires_at && new Date(row.expires_at) < /* @__PURE__ */ new Date()) {
+          this.db.prepare("DELETE FROM admin_cache WHERE key = ?").run(key);
+          return void 0;
+        }
+        return row.value;
+      },
+      set: (key, value, ttlMs) => {
+        const expiresAt = ttlMs ? new Date(Date.now() + ttlMs).toISOString() : null;
+        this.db.prepare(
+          "INSERT OR REPLACE INTO admin_cache (key, value, expires_at) VALUES (?, ?, ?)"
+        ).run(key, value, expiresAt);
+      },
+      delete: (key) => {
+        this.db.prepare("DELETE FROM admin_cache WHERE key = ?").run(key);
+      },
+      clear: () => {
+        this.db.exec("DELETE FROM admin_cache");
+      }
+    };
+  }
+  dbPath;
+  db;
+  sessions;
+  preferences;
+  cache;
+  async initialize() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS admin_sessions (
+        id TEXT PRIMARY KEY,
+        created_at TEXT NOT NULL,
+        expires_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS admin_preferences (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS admin_cache (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        expires_at TEXT
+      );
+      CREATE TABLE IF NOT EXISTS audit_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp TEXT NOT NULL,
+        action TEXT NOT NULL,
+        detail TEXT
+      );
+    `);
+  }
+  async close() {
+    this.db.close();
+  }
+};
 export {
   ErrorResponseSchema,
   FindingsSummarySchema,
@@ -687,12 +1192,22 @@ export {
   ProjectReadinessSchema,
   ProjectRouteSchema,
   ProjectSummarySchema,
+  RefinementApplySchema,
+  RefinementFeedbackSchema,
   RouteStepSchema,
   SQLiteAdminStorage,
   SessionManager,
+  ValidationResultSchema,
+  WorkItemCreateSchema,
+  WorkItemCreateWithAnswersSchema,
   WorkItemDetailSchema,
+  WorkItemEditModelSchema,
+  WorkItemInputSchema,
   WorkItemListItemSchema,
   WorkItemSummarySchema,
+  WorkItemTransitionSchema,
+  WorkItemUpdateSchema,
+  WorkItemWriteResultSchema,
   WorkItemsListSchema,
   WorkItemsSummaryStatsSchema,
   createAdminServer