work-kit-cli 0.2.8 → 0.4.0

package/cli/src/commands/extract.ts

@@ -0,0 +1,217 @@
+import { findWorktreeRoot, readState, readStateMd, resolveMainRepoRoot, gitHeadSha } from "../state/store.js";
+import {
+  appendAutoEntries,
+  ensureKnowledgeDir,
+  fileForType,
+  isKnowledgeType,
+  KNOWLEDGE_TYPES,
+  redact,
+  type KnowledgeEntry,
+  type KnowledgeType,
+} from "../utils/knowledge.js";
+import { skillFilePath } from "../config/workflow.js";
+import type { PhaseName, WorkKitState } from "../state/schema.js";
+
+export interface ExtractOptions {
+  worktreeRoot?: string;
+}
+
+export interface ExtractResult {
+  action: "extracted" | "error";
+  written: number;
+  duplicates: number;
+  byType: Record<KnowledgeType, number>;
+  message?: string;
+}
+
+interface RawEntry {
+  type: KnowledgeType;
+  text: string;
+  phase?: string;
+  step?: string;
+  source: string;
+}
+
+function emptyByType(): Record<KnowledgeType, number> {
+  const out = {} as Record<KnowledgeType, number>;
+  for (const t of KNOWLEDGE_TYPES) out[t] = 0;
+  return out;
+}
+
+// ── Single-pass state.md parser ─────────────────────────────────────
+
+const OBSERVATION_RE = /^-\s*\[([a-z]+)(?::([a-z0-9-]+\/[a-z0-9-]+))?\]\s*(.+)$/i;
+
+/**
+ * Walk state.md once and emit raw entries from the three sections we know:
+ * Observations (typed bullets), Decisions (any bullet → convention),
+ * Deviations (any bullet → workflow with [deviation] prefix).
+ */
+function parseStateMd(stateMd: string): RawEntry[] {
+  const out: RawEntry[] = [];
+  if (!stateMd) return out;
+
+  let section: "observations" | "decisions" | "deviations" | null = null;
+
+  for (const rawLine of stateMd.split("\n")) {
+    const trimmed = rawLine.trim();
+
+    if (trimmed.startsWith("## ")) {
+      const header = trimmed.slice(3).trim().toLowerCase();
+      if (header === "observations") section = "observations";
+      else if (header === "decisions") section = "decisions";
+      else if (header === "deviations") section = "deviations";
+      else section = null;
+      continue;
+    }
+
+    if (section === null) continue;
+    if (!trimmed.startsWith("-") || trimmed.startsWith("<!--")) continue;
+
+    if (section === "observations") {
+      const m = trimmed.match(OBSERVATION_RE);
+      if (!m) continue;
+      const tag = m[1].toLowerCase();
+      if (!isKnowledgeType(tag)) continue;
+      const phaseStep = m[2];
+      const text = m[3].trim();
+      if (text.length === 0) continue;
+      const entry: RawEntry = { type: tag, text, source: "auto-state-md" };
+      if (phaseStep) {
+        const [p, s] = phaseStep.split("/");
+        entry.phase = p;
+        entry.step = s;
+      }
+      out.push(entry);
+      continue;
+    }
+
+    const text = trimmed.replace(/^-\s*/, "").trim();
+    if (text.length === 0) continue;
+
+    if (section === "decisions") {
+      out.push({ type: "convention", text, source: "auto-state-md" });
+    } else if (section === "deviations") {
+      out.push({ type: "workflow", text: `[deviation] ${text}`, source: "auto-state-md" });
+    }
+  }
+
+  return out;
+}
+
+// ── Tracker.json extraction ─────────────────────────────────────────
+
+function fromLoopbacks(state: WorkKitState): RawEntry[] {
+  return (state.loopbacks ?? []).map((lb) => ({
+    type: "workflow" as const,
+    text: `[loopback] ${lb.from.phase}/${lb.from.step} → ${lb.to.phase}/${lb.to.step}: ${lb.reason}`,
+    phase: lb.from.phase,
+    step: lb.from.step,
+    source: "auto-tracker",
+  }));
+}
+
+function fromSkippedAndFailed(state: WorkKitState): RawEntry[] {
+  const out: RawEntry[] = [];
+  for (const [phaseName, phaseState] of Object.entries(state.phases)) {
+    for (const [stepName, stepState] of Object.entries(phaseState.steps)) {
+      if (stepState.status === "skipped") {
+        out.push({
+          type: "workflow",
+          text: `[skipped] ${phaseName}/${stepName} was skipped during this session.`,
+          phase: phaseName,
+          step: stepName,
+          source: "auto-tracker",
+        });
+      }
+      if (stepState.outcome === "broken" || stepState.outcome === "fix_needed") {
+        out.push({
+          type: "workflow",
+          text: `[failure] ${phaseName}/${stepName} reported outcome=${stepState.outcome}.`,
+          phase: phaseName,
+          step: stepName,
+          source: "auto-tracker",
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+export function extractCommand(opts: ExtractOptions = {}): ExtractResult {
+  const root = opts.worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return {
+      action: "error",
+      written: 0,
+      duplicates: 0,
+      byType: emptyByType(),
+      message: "No work-kit session found. Run from inside a worktree.",
+    };
+  }
+
+  let state: WorkKitState;
+  try {
+    state = readState(root);
+  } catch (e: any) {
+    return {
+      action: "error",
+      written: 0,
+      duplicates: 0,
+      byType: emptyByType(),
+      message: `Could not read state: ${e.message}`,
+    };
+  }
+
+  const mainRepoRoot = state.metadata?.mainRepoRoot ?? resolveMainRepoRoot(root);
+  ensureKnowledgeDir(mainRepoRoot);
+
+  const stateMd = readStateMd(root) ?? "";
+
+  const raw: RawEntry[] = [
+    ...parseStateMd(stateMd),
+    ...fromLoopbacks(state),
+    ...fromSkippedAndFailed(state),
+  ];
+
+  const ts = new Date().toISOString();
+  const sha = gitHeadSha(mainRepoRoot);
+
+  // Group entries by destination file for a single read-modify-write per file.
+  const grouped = new Map<string, KnowledgeEntry[]>();
+  for (const r of raw) {
+    const phase = r.phase ?? state.currentPhase ?? undefined;
+    const step = r.step ?? state.currentStep ?? undefined;
+    const skillPath = phase && step ? skillFilePath(phase as PhaseName, step) : undefined;
+    const { text } = redact(r.text);
+
+    const entry: KnowledgeEntry = {
+      ts,
+      sessionSlug: state.slug,
+      phase,
+      step,
+      skillPath,
+      gitSha: sha,
+      source: r.source,
+      text,
+    };
+
+    const file = fileForType(r.type);
+    const bucket = grouped.get(file);
+    if (bucket) bucket.push(entry);
+    else grouped.set(file, [entry]);
+  }
+
+  const result = appendAutoEntries(mainRepoRoot, grouped);
+
+  // Map per-file write counts back to per-type counts. Each KnowledgeType
+  // routes to exactly one file, so the lookup is unambiguous.
+  const byType = emptyByType();
+  for (const t of KNOWLEDGE_TYPES) {
+    byType[t] = result.perFile.get(fileForType(t))?.written ?? 0;
+  }
+
+  return { action: "extracted", written: result.written, duplicates: result.duplicates, byType };
+}

package/cli/src/commands/init.test.ts

@@ -94,6 +94,56 @@ describe("initCommand", () => {
     }
   });
 
+  it("persists model policy when provided", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Ship the avatar feature",
+      modelPolicy: "opus",
+      worktreeRoot: tmp,
+    });
+
+    const state = JSON.parse(
+      fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8")
+    );
+    assert.equal(state.modelPolicy, "opus");
+  });
+
+  it("omits modelPolicy from state when defaulting to auto", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Some default task",
+      worktreeRoot: tmp,
+    });
+
+    const state = JSON.parse(
+      fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8")
+    );
+    assert.equal(state.modelPolicy, undefined);
+  });
+
+  it("rejects invalid model policy", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    const result = initCommand({
+      mode: "full",
+      description: "Task with bad policy",
+      modelPolicy: "turbo" as any,
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(result.action, "error");
+    if (result.action === "error") {
+      assert.ok(result.message.includes("model-policy"));
+    }
+  });
+
   it("auto mode with classification succeeds", () => {
     const tmp = makeTmpDir();
     tmpDirs.push(tmp);

package/cli/src/commands/init.ts

@@ -1,8 +1,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { WorkKitState, PhaseState, PhaseName, PHASE_NAMES, SUBSTAGES_BY_PHASE, WorkflowStep, Classification } from "../state/schema.js";
-import { writeState, writeStateMd, stateExists } from "../state/store.js";
-import { buildFullWorkflow, buildDefaultWorkflow, skillFilePath } from "../config/phases.js";
+import { WorkKitState, PhaseState, PhaseName, PHASE_NAMES, STEPS_BY_PHASE, WorkflowStep, Classification, MODE_FULL, MODE_AUTO, ModelPolicy, isModelPolicy } from "../state/schema.js";
+import { writeState, writeStateMd, stateExists, STATE_DIR, resolveMainRepoRoot } from "../state/store.js";
+import { buildFullWorkflow, buildDefaultWorkflow, skillFilePath } from "../config/workflow.js";
+import { BRANCH_PREFIX, CLI_BINARY } from "../config/constants.js";
+import { loadProjectConfig } from "../config/project-config.js";
+import { resolveModel } from "../config/model-routing.js";
 import type { Action } from "../state/schema.js";
 
 function toSlug(description: string): string {
@@ -18,23 +21,23 @@ function buildPhases(workflow?: WorkflowStep[]): Record<PhaseName, PhaseState> {
   const phases = {} as Record<PhaseName, PhaseState>;
 
   for (const phase of PHASE_NAMES) {
-    const subStages: Record<string, { status: "pending" | "skipped" }> = {};
-    const allSubStages = SUBSTAGES_BY_PHASE[phase];
+    const steps: Record<string, { status: "pending" | "skipped" }> = {};
+    const allSteps = STEPS_BY_PHASE[phase];
 
-    for (const ss of allSubStages) {
+    for (const s of allSteps) {
       if (workflow) {
-        const step = workflow.find((s) => s.phase === phase && s.subStage === ss);
-        subStages[ss] = { status: step?.included ? "pending" : "skipped" };
+        const ws = workflow.find((w) => w.phase === phase && w.step === s);
+        steps[s] = { status: ws?.included ? "pending" : "skipped" };
       } else {
-        subStages[ss] = { status: "pending" };
+        steps[s] = { status: "pending" };
       }
     }
 
-    // Check if entire phase is skipped (all sub-stages skipped)
-    const allSkipped = Object.values(subStages).every((s) => s.status === "skipped");
+    // Check if entire phase is skipped (all steps skipped)
+    const allSkipped = Object.values(steps).every((s) => s.status === "skipped");
     phases[phase] = {
       status: allSkipped ? "skipped" : "pending",
-      subStages,
+      steps,
     };
   }
 
@@ -58,7 +61,7 @@ function generateStateMd(slug: string, branch: string, mode: string, description
   }
 
   md += `**Phase:** plan
-**Sub-stage:** clarify
+**Step:** clarify
 **Status:** in-progress
 
 ## Description
@@ -67,9 +70,9 @@ ${description}
 
   if (workflow) {
     md += `\n## Workflow\n`;
-    for (const step of workflow) {
-      if (step.included) {
-        const label = `${step.phase.charAt(0).toUpperCase() + step.phase.slice(1)}: ${step.subStage.charAt(0).toUpperCase() + step.subStage.slice(1)}`;
+    for (const ws of workflow) {
+      if (ws.included) {
+        const label = `${ws.phase.charAt(0).toUpperCase() + ws.phase.slice(1)}: ${ws.step.charAt(0).toUpperCase() + ws.step.slice(1)}`;
         md += `- [ ] ${label}\n`;
       }
     }
@@ -83,6 +86,15 @@ ${description}
 <!-- Append here whenever you choose between real alternatives -->
 <!-- Format: **<context>**: chose <X> over <Y> — <why> -->
 
+## Observations
+<!-- Append typed bullets as you notice things worth preserving across sessions. -->
+<!-- wrap-up/knowledge routes these to .work-kit-knowledge/. -->
+<!-- Grammar: - [lesson|convention|risk|workflow] text  (workflow tag may include :phase/step) -->
+<!-- Examples: -->
+<!--   - [risk] auth.middleware.ts breaks if SESSION_SECRET is unset. -->
+<!--   - [convention] All API errors must use createApiError() helper. -->
+<!--   - [workflow:test/e2e] The e2e step doesn't tell agents to start the dev server first. -->
+
 ## Deviations
 <!-- Append here whenever implementation diverges from the Blueprint -->
 <!-- Format: **<Blueprint step>**: <what changed> — <why> -->
@@ -91,9 +103,12 @@ ${description}
   return md;
 }
 
-function ensureGitignored(worktreeRoot: string): void {
-  const gitignorePath = path.join(worktreeRoot, ".gitignore");
-  const entry = ".work-kit/";
+/**
+ * Append `entry` to `<root>/.gitignore` if it isn't already present.
+ * Idempotent. Creates the file if missing. Reused by setup.ts.
+ */
+export function ensureGitignored(root: string, entry: string): void {
+  const gitignorePath = path.join(root, ".gitignore");
 
   if (fs.existsSync(gitignorePath)) {
     const content = fs.readFileSync(gitignorePath, "utf-8");
@@ -105,14 +120,30 @@ function ensureGitignored(worktreeRoot: string): void {
 }
 
 export function initCommand(options: {
-  mode: "full" | "auto";
+  mode?: "full" | "auto";
   description: string;
   classification?: Classification;
   gated?: boolean;
+  modelPolicy?: ModelPolicy;
   worktreeRoot?: string;
 }): Action {
-  const { mode, description, classification, gated } = options;
   const worktreeRoot = options.worktreeRoot || process.cwd();
+  const mainRepoRoot = resolveMainRepoRoot(worktreeRoot);
+  const projectConfig = loadProjectConfig(mainRepoRoot);
+
+  const mode = options.mode ?? projectConfig.defaults?.mode ?? "full";
+  const classification = options.classification ?? projectConfig.defaults?.classification;
+  const gated = options.gated ?? projectConfig.defaults?.gated ?? false;
+  const modelPolicy: ModelPolicy = options.modelPolicy ?? "auto";
+  const { description } = options;
+
+  // Validate model policy (guards against CLI callers that bypass the commander layer)
+  if (!isModelPolicy(modelPolicy)) {
+    return {
+      action: "error",
+      message: `Invalid --model-policy "${modelPolicy}". Use one of: auto, opus, sonnet, haiku, inherit.`,
+    };
+  }
 
   // Guard: don't overwrite existing state
   if (stateExists(worktreeRoot)) {
@@ -140,63 +171,67 @@ export function initCommand(options: {
   }
 
   const slug = toSlug(description);
-  const branch = `feature/${slug}`;
-  const modeLabel = mode === "full" ? "full-kit" : "auto-kit";
+  const branch = `${BRANCH_PREFIX}${slug}`;
+  const modeLabel = mode === "full" ? MODE_FULL : MODE_AUTO;
 
   // Build workflow
   let workflow: WorkflowStep[] | undefined;
   if (mode === "auto" && classification) {
-    workflow = buildDefaultWorkflow(classification);
+    workflow = buildDefaultWorkflow(classification, projectConfig.workflow);
   } else if (mode === "full") {
     workflow = buildFullWorkflow();
   }
 
-  // Find first active sub-stage
+  // Find first active step
   let firstPhase: PhaseName = "plan";
-  let firstSubStage = "clarify";
+  let firstStep = "clarify";
 
   if (workflow) {
     const first = workflow.find((s) => s.included);
     if (first) {
       firstPhase = first.phase;
-      firstSubStage = first.subStage;
+      firstStep = first.step;
     }
   }
 
   // Build state
   const state: WorkKitState = {
-    version: 1,
+    version: 2,
     slug,
     branch,
     started: new Date().toISOString(),
     mode: modeLabel,
     ...(gated && { gated: true }),
     ...(classification && { classification }),
+    ...(modelPolicy !== "auto" && { modelPolicy }),
     status: "in-progress",
     currentPhase: firstPhase,
-    currentSubStage: firstSubStage,
+    currentStep: firstStep,
     phases: buildPhases(workflow),
     ...(mode === "auto" && workflow && { workflow }),
     loopbacks: [],
     metadata: {
       worktreeRoot,
-      mainRepoRoot: worktreeRoot, // will be set properly by caller
+      mainRepoRoot,
     },
   };
 
   // Ensure .work-kit/ is gitignored (temp working state, not for commits)
-  ensureGitignored(worktreeRoot);
+  ensureGitignored(worktreeRoot, `${STATE_DIR}/`);
 
   // Write state files
   writeState(worktreeRoot, state);
   writeStateMd(worktreeRoot, generateStateMd(slug, branch, modeLabel, description, classification, workflow));
 
+  const model = resolveModel(state, firstPhase, firstStep);
+
   return {
     action: "spawn_agent",
     phase: firstPhase,
-    subStage: firstSubStage,
-    skillFile: skillFilePath(firstPhase, firstSubStage),
-    agentPrompt: `You are starting the ${firstPhase} phase. Begin with the ${firstSubStage} sub-stage. Read the skill file and follow its instructions. Write outputs to .work-kit/state.md.`,
-    onComplete: `npx work-kit-cli complete ${firstPhase}/${firstSubStage}`,
+    step: firstStep,
+    skillFile: skillFilePath(firstPhase, firstStep),
+    agentPrompt: `You are starting the ${firstPhase} phase. Begin with the ${firstStep} step. Read the skill file and follow its instructions. Write outputs to .work-kit/state.md.`,
+    onComplete: `${CLI_BINARY} complete ${firstPhase}/${firstStep}`,
+    ...(model && { model }),
   };
 }