work-kit-cli 0.2.8 → 0.4.0

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

@@ -0,0 +1,217 @@
+import { describe, it, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { initCommand } from "./init.js";
+import { learnCommand } from "./learn.js";
+import { extractCommand } from "./extract.js";
+import { KNOWLEDGE_DIR, AUTO_BLOCK_START, AUTO_BLOCK_END } from "../utils/knowledge.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `work-kit-test-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  tmpDirs = [];
+});
+
+function setupSession(tmp: string) {
+  initCommand({
+    mode: "full",
+    description: "Test feature",
+    worktreeRoot: tmp,
+  });
+}
+
+describe("learnCommand", () => {
+  it("rejects invalid type", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+    const r = learnCommand({ type: "garbage", text: "x", worktreeRoot: tmp });
+    assert.equal(r.action, "error");
+  });
+
+  it("rejects empty text", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+    const r = learnCommand({ type: "lesson", text: "   ", worktreeRoot: tmp });
+    assert.equal(r.action, "error");
+  });
+
+  it("appends a lesson and creates auto-block markers", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const r = learnCommand({
+      type: "lesson",
+      text: "Test fixtures must be reset between Playwright suites.",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(r.action, "learned");
+    assert.equal(r.file, "lessons.md");
+
+    const lessonsPath = path.join(tmp, KNOWLEDGE_DIR, "lessons.md");
+    assert.ok(fs.existsSync(lessonsPath));
+    const content = fs.readFileSync(lessonsPath, "utf-8");
+    assert.ok(content.includes(AUTO_BLOCK_START));
+    assert.ok(content.includes(AUTO_BLOCK_END));
+    assert.ok(content.includes("Test fixtures must be reset"));
+  });
+
+  it("routes each type to its own file", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    learnCommand({ type: "lesson", text: "L", worktreeRoot: tmp });
+    learnCommand({ type: "convention", text: "C", worktreeRoot: tmp });
+    learnCommand({ type: "risk", text: "R", worktreeRoot: tmp });
+    learnCommand({ type: "workflow", text: "W", worktreeRoot: tmp });
+
+    const dir = path.join(tmp, KNOWLEDGE_DIR);
+    assert.ok(fs.readFileSync(path.join(dir, "lessons.md"), "utf-8").includes("L"));
+    assert.ok(fs.readFileSync(path.join(dir, "conventions.md"), "utf-8").includes("C"));
+    assert.ok(fs.readFileSync(path.join(dir, "risks.md"), "utf-8").includes("R"));
+    assert.ok(fs.readFileSync(path.join(dir, "workflow.md"), "utf-8").includes("W"));
+  });
+
+  it("redacts secrets in text before writing", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const r = learnCommand({
+      type: "lesson",
+      text: "API key is sk-abc123def456ghi789jkl012mno345 leaked here",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(r.action, "learned");
+    assert.equal(r.redacted, true);
+    assert.ok((r.redactedKinds ?? []).includes("openai-style"));
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "lessons.md"),
+      "utf-8"
+    );
+    assert.ok(content.includes("[REDACTED]"));
+    assert.ok(!content.includes("sk-abc123def456ghi789"));
+  });
+
+  it("is idempotent on identical entries (returns duplicate)", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const first = learnCommand({ type: "risk", text: "Same text", worktreeRoot: tmp });
+    const second = learnCommand({ type: "risk", text: "Same text", worktreeRoot: tmp });
+
+    assert.equal(first.action, "learned");
+    assert.equal(second.action, "duplicate");
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "risks.md"),
+      "utf-8"
+    );
+    // Only one entry should exist
+    const matches = content.match(/Same text/g) ?? [];
+    assert.equal(matches.length, 1);
+  });
+
+  it("auto-fills phase and step from tracker.json", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    learnCommand({
+      type: "lesson",
+      text: "Phase auto-fill check",
+      worktreeRoot: tmp,
+    });
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "lessons.md"),
+      "utf-8"
+    );
+    // Init starts at plan/clarify
+    assert.ok(content.includes("plan/clarify"));
+  });
+
+  it("extracts typed bullets from state.md ## Observations", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    // Inject typed bullets into the existing ## Observations section
+    const stateMdPath = path.join(tmp, ".work-kit", "state.md");
+    const original = fs.readFileSync(stateMdPath, "utf-8");
+    const injected = original.replace(
+      "\n## Deviations",
+      "\n- [risk] foo.ts is fragile\n- [convention] All inputs validated via Zod\n- [workflow:test/e2e] e2e step needs server\n- [lesson] We discovered something useful\n\n## Deviations"
+    );
+    fs.writeFileSync(stateMdPath, injected);
+
+    const r = extractCommand({ worktreeRoot: tmp });
+    assert.equal(r.action, "extracted");
+    // 4 typed observation bullets, all should route
+    assert.equal(r.byType.risk, 1);
+    assert.equal(r.byType.convention, 1);
+    assert.equal(r.byType.workflow, 1, "workflow:test/e2e bullet should be routed (regression: digit in step name)");
+    assert.equal(r.byType.lesson, 1);
+
+    const workflowMd = fs.readFileSync(path.join(tmp, KNOWLEDGE_DIR, "workflow.md"), "utf-8");
+    assert.ok(workflowMd.includes("e2e step needs server"));
+  });
+
+  it("extract is idempotent (re-run produces only duplicates)", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const stateMdPath = path.join(tmp, ".work-kit", "state.md");
+    const original = fs.readFileSync(stateMdPath, "utf-8");
+    fs.writeFileSync(
+      stateMdPath,
+      original.replace("\n## Deviations", "\n- [risk] one\n- [risk] two\n\n## Deviations")
+    );
+
+    const first = extractCommand({ worktreeRoot: tmp });
+    const second = extractCommand({ worktreeRoot: tmp });
+
+    assert.equal(first.written, 2);
+    assert.equal(first.duplicates, 0);
+    assert.equal(second.written, 0);
+    assert.equal(second.duplicates, 2);
+  });
+
+  it("does not contaminate the Manual section", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    learnCommand({ type: "lesson", text: "Auto only", worktreeRoot: tmp });
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "lessons.md"),
+      "utf-8"
+    );
+    // Find the Manual section and ensure the entry isn't in it
+    const manualIdx = content.indexOf("## Manual");
+    assert.ok(manualIdx > -1);
+    const manualSection = content.slice(manualIdx);
+    assert.ok(!manualSection.includes("Auto only"));
+  });
+});

package/cli/src/commands/learn.ts

@@ -0,0 +1,104 @@
+import { findWorktreeRoot, readState, resolveMainRepoRoot, stateExists, gitHeadSha } from "../state/store.js";
+import {
+  appendAutoEntry,
+  ensureKnowledgeDir,
+  fileForType,
+  isKnowledgeType,
+  redact,
+  type KnowledgeEntry,
+  type KnowledgeType,
+} from "../utils/knowledge.js";
+import { skillFilePath } from "../config/workflow.js";
+import type { PhaseName } from "../state/schema.js";
+
+export interface LearnOptions {
+  type: string;
+  text: string;
+  scope?: string;
+  phase?: string;
+  step?: string;
+  source?: string;
+  worktreeRoot?: string;
+  /** When true, suppress the one-time commit warning. Used by extract. */
+  quiet?: boolean;
+}
+
+export interface LearnResult {
+  action: "learned" | "duplicate" | "error";
+  type?: KnowledgeType;
+  file?: string;
+  redacted?: boolean;
+  redactedKinds?: string[];
+  message?: string;
+}
+
+export function learnCommand(opts: LearnOptions): LearnResult {
+  if (!opts.type || !isKnowledgeType(opts.type)) {
+    return {
+      action: "error",
+      message: `Invalid --type "${opts.type}". Must be one of: lesson, convention, risk, workflow.`,
+    };
+  }
+  if (!opts.text || opts.text.trim().length === 0) {
+    return { action: "error", message: "--text is required and cannot be empty." };
+  }
+
+  const type = opts.type as KnowledgeType;
+
+  // Try to locate a session for auto-fill. Falls back to manual --phase/--step.
+  const root = opts.worktreeRoot || findWorktreeRoot();
+  let sessionSlug: string | undefined;
+  let phase: string | undefined = opts.phase;
+  let step: string | undefined = opts.step;
+  let mainRepoRoot: string | undefined;
+  let skillPath: string | undefined;
+
+  if (root && stateExists(root)) {
+    const state = readState(root);
+    sessionSlug = state.slug;
+    mainRepoRoot = state.metadata?.mainRepoRoot ?? resolveMainRepoRoot(root);
+    if (!phase) phase = state.currentPhase ?? undefined;
+    if (!step) step = state.currentStep ?? undefined;
+    if (phase && step) {
+      skillPath = skillFilePath(phase as PhaseName, step);
+    }
+  }
+
+  if (!mainRepoRoot) {
+    // No session — caller must be in a git repo we can resolve
+    mainRepoRoot = resolveMainRepoRoot(process.cwd());
+    if (!mainRepoRoot) {
+      return {
+        action: "error",
+        message: "No work-kit session found and not inside a git repo. Run from a project directory or provide --worktree-root.",
+      };
+    }
+  }
+
+  const { text, redacted, matches } = redact(opts.text);
+
+  ensureKnowledgeDir(mainRepoRoot);
+
+  const entry: KnowledgeEntry = {
+    ts: new Date().toISOString(),
+    sessionSlug,
+    phase,
+    step,
+    skillPath,
+    gitSha: gitHeadSha(mainRepoRoot),
+    source: opts.source ?? "explicit-cli",
+    text,
+    scope: opts.scope,
+  };
+
+  const file = fileForType(type);
+  const wrote = appendAutoEntry(mainRepoRoot, file, entry);
+
+  return {
+    action: wrote ? "learned" : "duplicate",
+    type,
+    file,
+    redacted,
+    redactedKinds: matches,
+  };
+}

package/cli/src/commands/loopback.ts

@@ -1,9 +1,9 @@
 import { readState, writeState, findWorktreeRoot } from "../state/store.js";
 import { parseLocation, resetToLocation } from "../state/helpers.js";
+import { countLoopbacksForRoute } from "../workflow/loopbacks.js";
+import { MAX_LOOPBACKS_PER_ROUTE } from "../config/constants.js";
 import type { Action } from "../state/schema.js";
 
-const MAX_LOOPBACKS_PER_ROUTE = 2;
-
 export function loopbackCommand(opts: {
   from: string;
   to: string;
@@ -19,23 +19,20 @@ export function loopbackCommand(opts: {
   const from = parseLocation(opts.from);
   const to = parseLocation(opts.to);
 
-  if (!state.phases[from.phase]?.subStages[from.subStage]) {
+  if (!state.phases[from.phase]?.steps[from.step]) {
     return { action: "error", message: `Invalid source: ${opts.from}` };
   }
-  if (!state.phases[to.phase]?.subStages[to.subStage]) {
+  if (!state.phases[to.phase]?.steps[to.step]) {
     return { action: "error", message: `Invalid target: ${opts.to}` };
   }
 
-  // Can't loop back to a skipped sub-stage
-  if (state.phases[to.phase].subStages[to.subStage].status === "skipped") {
+  // Can't loop back to a skipped step
+  if (state.phases[to.phase].steps[to.step].status === "skipped") {
     return { action: "error", message: `Cannot loop back to ${opts.to} — it is skipped.` };
   }
 
   // Enforce max loopback count per route
-  const sameRouteCount = state.loopbacks.filter(
-    (lb) => lb.from.phase === from.phase && lb.from.subStage === from.subStage
-      && lb.to.phase === to.phase && lb.to.subStage === to.subStage
-  ).length;
+  const sameRouteCount = countLoopbacksForRoute(state.loopbacks, from, to);
   if (sameRouteCount >= MAX_LOOPBACKS_PER_ROUTE) {
     return {
       action: "error",
@@ -52,7 +49,7 @@ export function loopbackCommand(opts: {
 
   resetToLocation(state, to);
   state.currentPhase = to.phase;
-  state.currentSubStage = to.subStage;
+  state.currentStep = to.step;
   writeState(root, state);
 
   return {

package/cli/src/commands/next.ts

@@ -1,9 +1,12 @@
-import { readState, writeState, findWorktreeRoot, readStateMd } from "../state/store.js";
-import { determineNextStep } from "../engine/transitions.js";
+import { readState, writeState, findWorktreeRoot, readStateMd, clearBlockingMarkers } from "../state/store.js";
+import { determineNextStep } from "../workflow/transitions.js";
 import { validatePhasePrerequisites } from "../state/validators.js";
 import { buildAgentPrompt } from "../context/prompt-builder.js";
-import { getParallelGroup } from "../engine/parallel.js";
-import { skillFilePath } from "../config/phases.js";
+import { getParallelGroup } from "../workflow/parallel.js";
+import { skillFilePath } from "../config/workflow.js";
+import { resolveModel } from "../config/model-routing.js";
+import { CLI_BINARY } from "../config/constants.js";
+
 import type { Action, PhaseName, WorkKitState } from "../state/schema.js";
 
 export function nextCommand(worktreeRoot?: string): Action {
@@ -12,6 +15,9 @@ export function nextCommand(worktreeRoot?: string): Action {
     return { action: "error", message: "No work-kit state found. Run `work-kit init` first." };
   }
 
+  // Forward state transition → clear any stale "blocked on user" markers
+  clearBlockingMarkers(root);
+
   const state = readState(root);
 
   if (state.status === "completed") {
@@ -22,17 +28,25 @@ export function nextCommand(worktreeRoot?: string): Action {
     return { action: "error", message: "Work-kit is in failed state.", suggestion: "Review the state and restart." };
   }
 
-  const step = determineNextStep(state);
+  if (state.status === "paused") {
+    return {
+      action: "error",
+      message: `Work-kit is paused (since ${state.pausedAt ?? "earlier"}).`,
+      suggestion: `Run \`${CLI_BINARY} resume\` to continue.`,
+    };
+  }
+
+  const nextStep = determineNextStep(state);
 
-  switch (step.type) {
+  switch (nextStep.type) {
     case "complete":
-      return { action: "complete", message: step.message! };
+      return { action: "complete", message: nextStep.message! };
 
     case "wait-for-user":
-      return { action: "wait_for_user", message: step.message! };
+      return { action: "wait_for_user", message: nextStep.message! };
 
     case "phase-boundary": {
-      const phase = step.phase!;
+      const phase = nextStep.phase!;
 
       const validation = validatePhasePrerequisites(state, phase);
       if (!validation.valid) {
@@ -47,105 +61,105 @@ export function nextCommand(worktreeRoot?: string): Action {
       state.phases[phase].status = "in-progress";
       state.phases[phase].startedAt = new Date().toISOString();
 
-      const subStages = Object.entries(state.phases[phase].subStages);
-      const firstActive = subStages.find(([_, ss]) => ss.status === "pending" || ss.status === "waiting");
+      const entries = Object.entries(state.phases[phase].steps);
+      const firstActive = entries.find(([_, s]) => s.status === "pending" || s.status === "waiting");
 
       if (!firstActive) {
-        return { action: "error", message: `No pending sub-stages in ${phase}` };
+        return { action: "error", message: `No pending steps in ${phase}` };
       }
 
-      const [subStage] = firstActive;
-      state.currentSubStage = subStage;
-      state.phases[phase].subStages[subStage].status = "in-progress";
-      state.phases[phase].subStages[subStage].startedAt = new Date().toISOString();
+      const [step] = firstActive;
+      state.currentStep = step;
+      state.phases[phase].steps[step].status = "in-progress";
+      state.phases[phase].steps[step].startedAt = new Date().toISOString();
       writeState(root, state);
 
-      return buildSpawnAction(root, state, phase, subStage);
+      return buildSpawnAction(root, state, phase, step);
     }
 
-    case "sub-stage": {
-      const phase = step.phase!;
-      const subStage = step.subStage!;
+    case "step": {
+      const phase = nextStep.phase!;
+      const step = nextStep.step!;
 
       state.currentPhase = phase;
-      state.currentSubStage = subStage;
+      state.currentStep = step;
       if (state.phases[phase].status === "pending") {
         state.phases[phase].status = "in-progress";
         state.phases[phase].startedAt = new Date().toISOString();
       }
-      state.phases[phase].subStages[subStage].status = "in-progress";
-      state.phases[phase].subStages[subStage].startedAt = new Date().toISOString();
+      state.phases[phase].steps[step].status = "in-progress";
+      state.phases[phase].steps[step].startedAt = new Date().toISOString();
       writeState(root, state);
 
-      return buildSpawnAction(root, state, phase, subStage);
+      return buildSpawnAction(root, state, phase, step);
     }
 
     default:
-      return { action: "error", message: `Unknown step type: ${step.type}` };
+      return { action: "error", message: `Unknown step type: ${nextStep.type}` };
   }
 }
 
-function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, subStage: string): Action {
+function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, step: string): Action {
   // Read state.md once for all prompt builds
   const stateMd = readStateMd(root);
-  const parallelGroup = getParallelGroup(phase, subStage, state);
+  const parallelGroup = getParallelGroup(phase, step, state);
 
   if (parallelGroup) {
     const agents = parallelGroup.parallel
-      .filter((ss) => {
-        const ssState = state.phases[phase].subStages[ss];
-        return ssState && ssState.status !== "skipped" && ssState.status !== "completed";
+      .filter((s) => {
+        const sState = state.phases[phase].steps[s];
+        return sState && sState.status !== "skipped" && sState.status !== "completed";
       })
-      .map((ss) => ({
+      .map((s) => withModel({
         phase,
-        subStage: ss,
-        skillFile: skillFilePath(phase, ss),
-        agentPrompt: buildAgentPrompt(root, state, phase, ss, stateMd),
-        outputFile: `.work-kit/${phase}-${ss}.md`,
-      }));
+        step: s,
+        skillFile: skillFilePath(phase, s),
+        agentPrompt: buildAgentPrompt(root, state, phase, s, stateMd),
+        outputFile: `.work-kit/${phase}-${s}.md`,
+      }, state));
 
     // If all parallel members were filtered out, fall through to single agent
     if (agents.length === 0) {
       // Skip to thenSequential if it exists, otherwise nothing to do
       if (parallelGroup.thenSequential) {
-        const seqSS = parallelGroup.thenSequential;
-        return {
+        const seqStep = parallelGroup.thenSequential;
+        return withModelAction({
           action: "spawn_agent",
           phase,
-          subStage: seqSS,
-          skillFile: skillFilePath(phase, seqSS),
-          agentPrompt: buildAgentPrompt(root, state, phase, seqSS, stateMd),
-          onComplete: `npx work-kit-cli complete ${phase}/${seqSS}`,
-        };
+          step: seqStep,
+          skillFile: skillFilePath(phase, seqStep),
+          agentPrompt: buildAgentPrompt(root, state, phase, seqStep, stateMd),
+          onComplete: `${CLI_BINARY} complete ${phase}/${seqStep}`,
+        }, state);
       }
-      return { action: "error", message: `No active sub-stages in parallel group for ${phase}` };
+      return { action: "error", message: `No active steps in parallel group for ${phase}` };
     }
 
     // If only 1 agent remains, run as single agent (no need for parallel)
     if (agents.length === 1 && !parallelGroup.thenSequential) {
       const agent = agents[0];
-      return {
+      return withModelAction({
         action: "spawn_agent",
         phase: agent.phase,
-        subStage: agent.subStage,
+        step: agent.step,
         skillFile: agent.skillFile,
         agentPrompt: agent.agentPrompt,
-        onComplete: `npx work-kit-cli complete ${agent.phase}/${agent.subStage}`,
-      };
+        onComplete: `${CLI_BINARY} complete ${agent.phase}/${agent.step}`,
+      }, state);
     }
 
     for (const agent of agents) {
-      state.phases[phase].subStages[agent.subStage].status = "in-progress";
-      state.phases[phase].subStages[agent.subStage].startedAt = new Date().toISOString();
+      state.phases[phase].steps[agent.step].status = "in-progress";
+      state.phases[phase].steps[agent.step].startedAt = new Date().toISOString();
     }
 
     const thenSequential = parallelGroup.thenSequential
-      ? {
+      ? withModel({
           phase,
-          subStage: parallelGroup.thenSequential,
+          step: parallelGroup.thenSequential,
           skillFile: skillFilePath(phase, parallelGroup.thenSequential),
           agentPrompt: buildAgentPrompt(root, state, phase, parallelGroup.thenSequential, stateMd),
-        }
+        }, state)
       : undefined;
 
     writeState(root, state);
@@ -154,19 +168,38 @@ function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, s
       action: "spawn_parallel_agents",
       agents,
       thenSequential,
-      onComplete: `npx work-kit-cli complete ${phase}/${parallelGroup.thenSequential || parallelGroup.parallel[parallelGroup.parallel.length - 1]}`,
+      onComplete: `${CLI_BINARY} complete ${phase}/${parallelGroup.thenSequential || parallelGroup.parallel[parallelGroup.parallel.length - 1]}`,
     };
   }
 
-  const skill = skillFilePath(phase, subStage);
-  const prompt = buildAgentPrompt(root, state, phase, subStage, stateMd);
+  const skill = skillFilePath(phase, step);
+  const prompt = buildAgentPrompt(root, state, phase, step, stateMd);
 
-  return {
+  return withModelAction({
     action: "spawn_agent",
     phase,
-    subStage,
+    step,
     skillFile: skill,
     agentPrompt: prompt,
-    onComplete: `npx work-kit-cli complete ${phase}/${subStage}`,
-  };
+    onComplete: `${CLI_BINARY} complete ${phase}/${step}`,
+  }, state);
+}
+
+/**
+ * Attach the resolved model tier to an AgentSpec. Omits the field entirely
+ * when resolveModel returns undefined (policy "inherit" or hard-default miss),
+ * keeping the action JSON compatible with skills that haven't yet been updated
+ * to forward a model parameter.
+ */
+function withModel<T extends { phase: PhaseName; step: string }>(spec: T, state: WorkKitState): T & { model?: ReturnType<typeof resolveModel> } {
+  const model = resolveModel(state, spec.phase, spec.step);
+  return model ? { ...spec, model } : spec;
+}
+
+function withModelAction(
+  action: Extract<Action, { action: "spawn_agent" }>,
+  state: WorkKitState
+): Extract<Action, { action: "spawn_agent" }> {
+  const model = resolveModel(state, action.phase, action.step);
+  return model ? { ...action, model } : action;
 }