work-kit-cli 0.3.0 → 0.4.1

package/README.md

@@ -55,9 +55,20 @@ Best for: bug fixes, small changes, refactors, well-understood tasks.
 | `validate` | Validate state integrity and phase prerequisites |
 | `loopback` | Route back to a previous stage (max 2 per route) |
 | `workflow` | Display the full workflow plan |
+| `pause` | Pause the active session (state preserved on disk) |
+| `resume [--slug <slug>]` | Without `--slug`: list resumable sessions in this repo. With `--slug`: resume the named session |
+| `observe [--all]` | Live TUI dashboard of active/paused/completed sessions. `--all` watches every work-kit project on the system |
 | `doctor` | Run environment health checks (supports `--json`) |
 | `setup` | Install work-kit skills into a Claude Code project |
 
+### Picking up where you left off
+
+`work-kit resume` (or `/resume-kit` in Claude Code) scans every worktree of the current repo for `.work-kit/tracker.json` files in `paused` or `in-progress` state and lets you pick one. It works from the main repo root — no need to `cd` into a worktree first. In-progress sessions are listed too, so a terminal you closed without pausing can be recovered: just look for the row with a stale `lastUpdatedAgoMs`.
+
+### Watching multiple projects
+
+`work-kit observe --all` discovers every work-kit-enabled repo from your `~/.claude/projects/` history and watches them all in one dashboard. Each row shows the project name, work item slug, mode, type, current state, and worktree.
+
 ## Phases
 
 | Phase | Steps | Agent |

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

@@ -6,6 +6,7 @@ import * as os from "node:os";
 import { randomUUID } from "node:crypto";
 import { bootstrapCommand } from "./bootstrap.js";
 import { initCommand } from "./init.js";
+import { learnCommand } from "./learn.js";
 
 function makeTmpDir(): string {
   const dir = path.join(os.tmpdir(), `work-kit-test-${randomUUID()}`);
@@ -94,6 +95,45 @@ describe("bootstrapCommand", () => {
     assert.ok(result.nextAction?.includes("complete"));
   });
 
+  it("injects knowledge field when knowledge files exist", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Knowledge test",
+      worktreeRoot: tmp,
+    });
+
+    // Write entries to lessons, conventions, risks, and workflow
+    learnCommand({ type: "lesson", text: "A useful lesson", worktreeRoot: tmp });
+    learnCommand({ type: "convention", text: "A coding convention", worktreeRoot: tmp });
+    learnCommand({ type: "risk", text: "A fragile area", worktreeRoot: tmp });
+    learnCommand({ type: "workflow", text: "Workflow feedback", worktreeRoot: tmp });
+
+    const result = bootstrapCommand(tmp);
+    assert.ok(result.knowledge, "knowledge field should be present");
+    assert.ok(result.knowledge?.lessons?.includes("A useful lesson"));
+    assert.ok(result.knowledge?.conventions?.includes("A coding convention"));
+    assert.ok(result.knowledge?.risks?.includes("A fragile area"));
+    // workflow.md is intentionally NOT injected
+    assert.equal((result.knowledge as any).workflow, undefined);
+  });
+
+  it("does not inject knowledge field when no knowledge files exist", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "No knowledge test",
+      worktreeRoot: tmp,
+    });
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.knowledge, undefined);
+  });
+
   it("reports failed state", () => {
     const tmp = makeTmpDir();
     tmpDirs.push(tmp);

package/cli/src/commands/bootstrap.ts

@@ -2,6 +2,13 @@ import fs from "node:fs";
 import { findWorktreeRoot, readState, writeState, statePath } from "../state/store.js";
 import { unpause } from "../state/helpers.js";
 import { CLI_BINARY, STALE_THRESHOLD_MS } from "../config/constants.js";
+import { fileForType, readKnowledgeFile } from "../utils/knowledge.js";
+
+export interface BootstrapKnowledge {
+  lessons?: string;
+  conventions?: string;
+  risks?: string;
+}
 
 export interface BootstrapResult {
   active: boolean;
@@ -16,6 +23,13 @@ export interface BootstrapResult {
   resumeReason?: string;
   nextAction?: string;
   recovery?: string | null;
+  /**
+   * Project-level knowledge files (lessons/conventions/risks) read from
+   * <mainRepoRoot>/.work-kit-knowledge/. Capped at 200 lines per file.
+   * workflow.md is intentionally excluded — it's a write-only artifact for
+   * human curators, not session context.
+   */
+  knowledge?: BootstrapKnowledge;
 }
 
 export interface BootstrapOptions {
@@ -75,6 +89,29 @@ export function bootstrapCommand(startDir?: string, options: BootstrapOptions =
     nextAction = `Continue ${state.currentPhase ?? "next phase"}${state.currentStep ? "/" + state.currentStep : ""}. Run \`${CLI_BINARY} next\` to get the agent prompt.`;
   }
 
+  // Load project-level knowledge files (best effort, never breaks bootstrap).
+  // workflow.md is intentionally excluded — it's a write-only artifact for
+  // human curators, not session context.
+  let knowledge: BootstrapKnowledge | undefined;
+  try {
+    const mainRepoRoot = state.metadata?.mainRepoRoot;
+    if (mainRepoRoot) {
+      const lessons = readKnowledgeFile(mainRepoRoot, fileForType("lesson"));
+      const conventions = readKnowledgeFile(mainRepoRoot, fileForType("convention"));
+      const risks = readKnowledgeFile(mainRepoRoot, fileForType("risk"));
+      if (lessons || conventions || risks) {
+        knowledge = {
+          ...(lessons && { lessons }),
+          ...(conventions && { conventions }),
+          ...(risks && { risks }),
+        };
+      }
+    }
+  } catch (err: any) {
+    // Non-fatal: log to stderr but don't break bootstrap
+    process.stderr.write(`work-kit: failed to load knowledge files: ${err.message}\n`);
+  }
+
   return {
     active: true,
     slug: state.slug,
@@ -87,5 +124,6 @@ export function bootstrapCommand(startDir?: string, options: BootstrapOptions =
     ...(resumed && { resumed: true, resumeReason }),
     nextAction,
     recovery,
+    ...(knowledge && { knowledge }),
   };
 }

package/cli/src/commands/extract.ts

@@ -0,0 +1,207 @@
+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;
+
+  // Only `## Observations` is auto-harvested. `## Decisions` and `## Deviations`
+  // are agent scratch space during normal phase work — they routinely contain
+  // test plans, acceptance-criteria checklists, and self-review dumps. Auto-
+  // routing them floods workflow.md with noise. Agents opt into harvesting by
+  // writing typed bullets (`- [lesson|convention|risk|workflow] text`) under
+  // `## Observations`.
+  let inObservations = false;
+
+  for (const rawLine of stateMd.split("\n")) {
+    const trimmed = rawLine.trim();
+
+    if (trimmed.startsWith("## ")) {
+      inObservations = trimmed.slice(3).trim().toLowerCase() === "observations";
+      continue;
+    }
+
+    if (!inObservations) continue;
+    if (!trimmed.startsWith("-") || trimmed.startsWith("<!--")) continue;
+
+    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);
+  }
+
+  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,10 +1,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { WorkKitState, PhaseState, PhaseName, PHASE_NAMES, STEPS_BY_PHASE, WorkflowStep, Classification, MODE_FULL, MODE_AUTO } from "../state/schema.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 {
@@ -85,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> -->
@@ -93,9 +103,12 @@ ${description}
   return md;
 }
 
-function ensureGitignored(worktreeRoot: string): void {
-  const gitignorePath = path.join(worktreeRoot, ".gitignore");
-  const entry = `${STATE_DIR}/`;
+/**
+ * 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");
@@ -111,6 +124,7 @@ export function initCommand(options: {
   description: string;
   classification?: Classification;
   gated?: boolean;
+  modelPolicy?: ModelPolicy;
   worktreeRoot?: string;
 }): Action {
   const worktreeRoot = options.worktreeRoot || process.cwd();
@@ -120,8 +134,17 @@ export function initCommand(options: {
   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)) {
     return {
@@ -180,6 +203,7 @@ export function initCommand(options: {
     mode: modeLabel,
     ...(gated && { gated: true }),
     ...(classification && { classification }),
+    ...(modelPolicy !== "auto" && { modelPolicy }),
     status: "in-progress",
     currentPhase: firstPhase,
     currentStep: firstStep,
@@ -193,12 +217,14 @@ export function initCommand(options: {
   };
 
   // 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,
@@ -206,5 +232,6 @@ export function initCommand(options: {
     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 }),
   };
 }