work-kit-cli 0.2.8 → 0.4.0

package/cli/src/config/loopback-routes.ts

@@ -1,45 +1,45 @@
-import { PhaseName, Location } from "../state/schema.js";
+import { Location, StepOutcome } from "../state/schema.js";
 
 /**
- * Defines when a completed sub-stage should trigger a loop-back
+ * Defines when a completed step should trigger a loop-back
  * based on its outcome.
  */
 export interface LoopbackRoute {
   from: Location;
-  triggerOutcome: string;
+  triggerOutcome: StepOutcome;
   to: Location;
   reason: string;
 }
 
 export const LOOPBACK_ROUTES: LoopbackRoute[] = [
   {
-    from: { phase: "plan", subStage: "audit" },
+    from: { phase: "plan", step: "audit" },
     triggerOutcome: "revise",
-    to: { phase: "plan", subStage: "blueprint" },
+    to: { phase: "plan", step: "blueprint" },
     reason: "Audit found gaps — revising Blueprint",
   },
   {
-    from: { phase: "build", subStage: "refactor" },
+    from: { phase: "build", step: "refactor" },
     triggerOutcome: "broken",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Refactor broke tests — re-running Core to fix",
   },
   {
-    from: { phase: "review", subStage: "handoff" },
+    from: { phase: "review", step: "handoff" },
     triggerOutcome: "changes_requested",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Review requested changes — looping back to Build/Core",
   },
   {
-    from: { phase: "deploy", subStage: "merge" },
+    from: { phase: "deploy", step: "merge" },
     triggerOutcome: "fix_needed",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Merge blocked — fix needed in Build/Core",
   },
   {
-    from: { phase: "deploy", subStage: "remediate" },
+    from: { phase: "deploy", step: "remediate" },
     triggerOutcome: "fix_and_redeploy",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Deployment issue — fix and redeploy from Build/Core",
   },
 ];

package/cli/src/config/model-routing.test.ts

@@ -0,0 +1,190 @@
+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 { resolveModel, BY_PHASE, BY_STEP } from "./model-routing.js";
+import type { WorkKitState, ModelPolicy, Classification } from "../state/schema.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `wk-model-routing-${randomUUID()}`);
+  fs.mkdirSync(path.join(dir, ".work-kit"), { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+  tmpDirs = [];
+});
+
+function fakeState(opts: {
+  worktreeRoot: string;
+  policy?: ModelPolicy;
+  classification?: Classification;
+  mode?: "auto-kit" | "full-kit";
+}): Pick<WorkKitState, "modelPolicy" | "classification" | "mode"> & { metadata: { worktreeRoot: string } } {
+  return {
+    modelPolicy: opts.policy,
+    classification: opts.classification,
+    mode: (opts.mode ?? "full-kit") as any,
+    metadata: { worktreeRoot: opts.worktreeRoot },
+  };
+}
+
+describe("resolveModel — defaults", () => {
+  it("uses step default when no policy or override", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+    assert.equal(resolveModel(state, "build", "commit"), "haiku");
+    assert.equal(resolveModel(state, "review", "security"), "opus");
+  });
+
+  it("falls back to phase default for unknown step", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp });
+    // Pick a phase/step that isn't in BY_STEP
+    const key = "plan/__nonexistent__";
+    assert.ok(!(key in BY_STEP));
+    assert.equal(resolveModel(state, "plan", "__nonexistent__"), BY_PHASE.plan);
+  });
+});
+
+describe("resolveModel — session policy", () => {
+  it("policy=opus forces opus for every step, even mechanical ones", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp, policy: "opus" });
+    assert.equal(resolveModel(state, "build", "commit"), "opus");
+    assert.equal(resolveModel(state, "deploy", "monitor"), "opus");
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("policy=haiku forces haiku everywhere", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp, policy: "haiku" });
+    assert.equal(resolveModel(state, "plan", "investigate"), "haiku");
+    assert.equal(resolveModel(state, "review", "security"), "haiku");
+  });
+
+  it("policy=inherit returns undefined so no model is passed", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp, policy: "inherit" });
+    assert.equal(resolveModel(state, "plan", "investigate"), undefined);
+    assert.equal(resolveModel(state, "build", "core"), undefined);
+    assert.equal(resolveModel(state, "deploy", "merge"), undefined);
+  });
+
+  it("policy=auto is equivalent to omitting it", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const autoState = fakeState({ worktreeRoot: tmp, policy: "auto" });
+    const unsetState = fakeState({ worktreeRoot: tmp });
+    assert.equal(
+      resolveModel(autoState, "plan", "investigate"),
+      resolveModel(unsetState, "plan", "investigate")
+    );
+  });
+});
+
+describe("resolveModel — classification", () => {
+  it("small-change knocks plan/investigate down to haiku in auto-kit mode", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "small-change",
+      mode: "auto-kit",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "haiku");
+  });
+
+  it("bug-fix keeps plan/investigate on opus (not in its override map)", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "bug-fix",
+      mode: "auto-kit",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+    assert.equal(resolveModel(state, "plan", "blueprint"), "sonnet");
+  });
+
+  it("refactor promotes review/performance to opus", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "refactor",
+      mode: "auto-kit",
+    });
+    assert.equal(resolveModel(state, "review", "performance"), "opus");
+  });
+
+  it("classification overrides are ignored in full-kit mode", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "small-change",
+      mode: "full-kit",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("session policy beats classification override", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "small-change",
+      mode: "auto-kit",
+      policy: "opus",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+});
+
+describe("resolveModel — workspace JSON override", () => {
+  it("workspace model-config.json beats session policy", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      JSON.stringify({ "build/commit": "sonnet" })
+    );
+    const state = fakeState({ worktreeRoot: tmp, policy: "opus" });
+    assert.equal(resolveModel(state, "build", "commit"), "sonnet");
+    // Other steps still forced to opus by the policy
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("workspace JSON beats step default", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      JSON.stringify({ "plan/investigate": "haiku" })
+    );
+    const state = fakeState({ worktreeRoot: tmp });
+    assert.equal(resolveModel(state, "plan", "investigate"), "haiku");
+  });
+
+  it("malformed JSON falls back silently to defaults", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      "{not json"
+    );
+    const state = fakeState({ worktreeRoot: tmp });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("invalid tier values in JSON are ignored", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      JSON.stringify({ "plan/investigate": "turbo", "build/core": "opus" })
+    );
+    const state = fakeState({ worktreeRoot: tmp });
+    // Bad value ignored → falls back to step default
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+    // Good value applied
+    assert.equal(resolveModel(state, "build", "core"), "opus");
+  });
+});

package/cli/src/config/model-routing.ts

@@ -0,0 +1,208 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import {
+  ModelTier,
+  PhaseName,
+  WorkKitState,
+  Classification,
+  isModelTier,
+} from "../state/schema.js";
+import { STATE_DIR } from "../state/store.js";
+
+/**
+ * Per-phase/step model routing.
+ *
+ * Resolution order (highest precedence first):
+ *   1. Workspace override    .work-kit/model-config.json        (per-session, per-step map)
+ *   2. User global override  ~/.claude/work-kit/models.json     (per-user, all projects)
+ *   3. Session model policy  state.modelPolicy                  (set at init via skill flag)
+ *   4. Classification        BY_CLASSIFICATION (auto-kit only)
+ *   5. Step default          BY_STEP
+ *   6. Phase default         BY_PHASE
+ *   7. Hard default          "sonnet"
+ *
+ * When state.modelPolicy is "inherit" (or layered overrides have not set a
+ * value), resolveModel() returns `undefined` so the orchestrator skill omits
+ * the `model` parameter on the Agent tool — identical to pre-routing behavior.
+ */
+
+const HARD_DEFAULT: ModelTier = "sonnet";
+
+// ── Phase defaults ──────────────────────────────────────────────────
+
+export const BY_PHASE: Record<PhaseName, ModelTier> = {
+  plan: "sonnet",
+  build: "sonnet",
+  test: "sonnet",
+  review: "sonnet",
+  deploy: "haiku",
+  "wrap-up": "sonnet",
+};
+
+// ── Step-level overrides (phase/step keys) ──────────────────────────
+
+export const BY_STEP: Record<string, ModelTier> = {
+  // Plan — research/design-heavy steps benefit from opus
+  "plan/clarify": "sonnet",
+  "plan/investigate": "opus",
+  "plan/sketch": "sonnet",
+  "plan/scope": "sonnet",
+  "plan/ux-flow": "sonnet",
+  "plan/architecture": "opus",
+  "plan/blueprint": "opus",
+  "plan/audit": "opus",
+
+  // Build — mechanical steps drop to haiku, implementation stays sonnet
+  "build/setup": "haiku",
+  "build/migration": "sonnet",
+  "build/red": "sonnet",
+  "build/core": "sonnet",
+  "build/ui": "sonnet",
+  "build/refactor": "sonnet",
+  "build/integration": "sonnet",
+  "build/commit": "haiku",
+
+  // Test — verify is mechanical, e2e/validate need judgment
+  "test/verify": "haiku",
+  "test/e2e": "sonnet",
+  "test/validate": "sonnet",
+
+  // Review — security & compliance get opus; rest sonnet
+  "review/self-review": "sonnet",
+  "review/security": "opus",
+  "review/performance": "sonnet",
+  "review/compliance": "opus",
+  "review/handoff": "sonnet",
+
+  // Deploy — mostly mechanical
+  "deploy/merge": "haiku",
+  "deploy/monitor": "haiku",
+  "deploy/remediate": "sonnet",
+
+  // Wrap-up — synthesis
+  "wrap-up/summary": "sonnet",
+};
+
+// ── Classification overrides (auto-kit only) ────────────────────────
+
+export const BY_CLASSIFICATION: Record<Classification, Partial<Record<string, ModelTier>>> = {
+  "small-change": {
+    // Trivial work: knock plan and reviews down a tier
+    "plan/clarify": "haiku",
+    "plan/investigate": "haiku",
+    "plan/sketch": "haiku",
+    "plan/scope": "haiku",
+    "plan/ux-flow": "haiku",
+    "plan/architecture": "haiku",
+    "plan/blueprint": "haiku",
+    "plan/audit": "haiku",
+    "review/security": "sonnet",
+    "review/compliance": "sonnet",
+  },
+  "bug-fix": {
+    // Bug fixes still need opus for investigate; rest can relax
+    "plan/clarify": "sonnet",
+    "plan/sketch": "sonnet",
+    "plan/scope": "sonnet",
+    "plan/architecture": "sonnet",
+    "plan/blueprint": "sonnet",
+    "plan/audit": "sonnet",
+  },
+  refactor: {
+    // Perf review matters most for refactors — promote it
+    "review/performance": "opus",
+  },
+  feature: {},
+  "large-feature": {},
+};
+
+// ── JSON override loading ───────────────────────────────────────────
+
+type OverrideMap = Partial<Record<string, ModelTier>>;
+
+interface LoadedOverrides {
+  workspace: OverrideMap;
+  userGlobal: OverrideMap;
+}
+
+/**
+ * Read+validate the optional JSON override files. Silently returns empty
+ * maps on any read/parse/validation error — overrides are strictly opt-in
+ * and must never block the workflow.
+ */
+export function loadOverrides(worktreeRoot: string): LoadedOverrides {
+  return {
+    workspace: readJsonMap(path.join(worktreeRoot, STATE_DIR, "model-config.json")),
+    userGlobal: readJsonMap(path.join(os.homedir(), ".claude", "work-kit", "models.json")),
+  };
+}
+
+function readJsonMap(filePath: string): OverrideMap {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const out: OverrideMap = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string" && isModelTier(value)) {
+        out[key] = value;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// ── Resolution ──────────────────────────────────────────────────────
+
+/**
+ * Resolve the model tier for a given phase/step in a given session.
+ *
+ * Returns `undefined` when the session policy is "inherit" (or when an
+ * override file explicitly maps to inherit via a missing entry — this does
+ * not happen today but stays consistent with "no opinion" semantics).
+ *
+ * Callers treat `undefined` as "do not pass a model parameter to the Agent
+ * tool" — identical to pre-routing behavior.
+ */
+export function resolveModel(
+  state: Pick<WorkKitState, "modelPolicy" | "classification" | "mode"> & { metadata: { worktreeRoot: string } },
+  phase: PhaseName,
+  step: string
+): ModelTier | undefined {
+  const key = `${phase}/${step}`;
+  const policy = state.modelPolicy ?? "auto";
+
+  // Policy "inherit" short-circuits everything: no model override at all.
+  if (policy === "inherit") {
+    return undefined;
+  }
+
+  // Layers 1 & 2: JSON overrides win over everything else.
+  const overrides = loadOverrides(state.metadata.worktreeRoot);
+  if (overrides.workspace[key]) return overrides.workspace[key];
+  if (overrides.userGlobal[key]) return overrides.userGlobal[key];
+
+  // Layer 3: Forced policy (opus/sonnet/haiku) beats all routing.
+  if (policy !== "auto") {
+    return policy;
+  }
+
+  // Layer 4: Classification override (auto-kit only).
+  if (state.mode === "auto-kit" && state.classification) {
+    const classOverride = BY_CLASSIFICATION[state.classification][key];
+    if (classOverride) return classOverride;
+  }
+
+  // Layer 5: Step default.
+  if (BY_STEP[key]) return BY_STEP[key];
+
+  // Layer 6: Phase default.
+  if (BY_PHASE[phase]) return BY_PHASE[phase];
+
+  // Layer 7: Hard default.
+  return HARD_DEFAULT;
+}

package/cli/src/config/project-config.test.ts

@@ -0,0 +1,127 @@
+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 { loadProjectConfig } from "./project-config.js";
+import { resolveParallelGroups, DEFAULT_PARALLEL_GROUPS } from "../workflow/parallel.js";
+import { PROJECT_CONFIG_FILE } from "./constants.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `wk-config-${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 = [];
+});
+
+describe("loadProjectConfig", () => {
+  it("returns empty config when file is missing", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config, {});
+  });
+
+  it("loads valid defaults", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({ defaults: { mode: "auto", classification: "feature", gated: true } }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.equal(config.defaults?.mode, "auto");
+    assert.equal(config.defaults?.classification, "feature");
+    assert.equal(config.defaults?.gated, true);
+  });
+
+  it("ignores invalid mode and classification", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({ defaults: { mode: "wat", classification: "nope" } }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.equal(config.defaults?.mode, undefined);
+    assert.equal(config.defaults?.classification, undefined);
+  });
+
+  it("loads parallel group overrides", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        parallel: {
+          test: { parallel: ["verify"], thenSequential: "validate" },
+        },
+      }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config.parallel?.test, { parallel: ["verify"], thenSequential: "validate" });
+  });
+
+  it("filters invalid step names from parallel overrides", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        parallel: { test: { parallel: ["verify", "made-up"] } },
+      }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config.parallel?.test?.parallel, ["verify"]);
+  });
+
+  it("validates workflow include/exclude refs", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        workflow: { include: ["review/security", "bogus/step"], exclude: ["test/e2e"] },
+      }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config.workflow?.include, ["review/security"]);
+    assert.deepStrictEqual(config.workflow?.exclude, ["test/e2e"]);
+  });
+
+  it("survives invalid JSON", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(path.join(tmp, PROJECT_CONFIG_FILE), "not json");
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config, {});
+  });
+});
+
+describe("resolveParallelGroups", () => {
+  it("returns defaults with no project root", () => {
+    assert.deepStrictEqual(resolveParallelGroups(), DEFAULT_PARALLEL_GROUPS);
+  });
+
+  it("merges project overrides over defaults", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        parallel: { test: { parallel: ["verify"], thenSequential: "validate" } },
+      }),
+    );
+    const groups = resolveParallelGroups(tmp);
+    assert.deepStrictEqual(groups.test, { parallel: ["verify"], thenSequential: "validate" });
+    // review (not overridden) keeps default
+    assert.deepStrictEqual(groups.review, DEFAULT_PARALLEL_GROUPS.review);
+  });
+});

package/cli/src/config/project-config.ts

@@ -0,0 +1,106 @@
+import * as path from "node:path";
+import {
+  PHASE_NAMES,
+  STEPS_BY_PHASE,
+  isClassification,
+  type PhaseName,
+  type Classification,
+} from "../state/schema.js";
+import { readJsonFile } from "../utils/json.js";
+import { PROJECT_CONFIG_FILE } from "./constants.js";
+
+/**
+ * Optional `.work-kit-config.json` lives at the main repo root.
+ *
+ * Example:
+ *   {
+ *     "defaults": { "mode": "auto", "classification": "feature", "gated": false },
+ *     "parallel": {
+ *       "review": { "parallel": ["self-review", "security"], "thenSequential": "handoff" }
+ *     },
+ *     "workflow": {
+ *       "include": ["review/security"],
+ *       "exclude": ["review/performance"]
+ *     }
+ *   }
+ */
+export interface ProjectParallelGroup {
+  parallel: string[];
+  thenSequential?: string;
+}
+
+export interface ProjectConfig {
+  defaults?: {
+    mode?: "full" | "auto";
+    classification?: Classification;
+    gated?: boolean;
+  };
+  /** Override or extend the per-phase parallel groups. */
+  parallel?: Partial<Record<PhaseName, ProjectParallelGroup>>;
+  /** Force-include or force-exclude specific steps (phase/step). */
+  workflow?: {
+    include?: string[];
+    exclude?: string[];
+  };
+}
+
+const EMPTY_CONFIG: ProjectConfig = {};
+
+/** Load and validate the project config. Returns empty config when missing/invalid. */
+export function loadProjectConfig(mainRepoRoot: string): ProjectConfig {
+  const parsed = readJsonFile<unknown>(path.join(mainRepoRoot, PROJECT_CONFIG_FILE));
+  if (!parsed) return EMPTY_CONFIG;
+  return validateConfig(parsed);
+}
+
+function validateConfig(raw: any): ProjectConfig {
+  const out: ProjectConfig = {};
+
+  if (raw && typeof raw === "object") {
+    if (raw.defaults && typeof raw.defaults === "object") {
+      const d = raw.defaults;
+      out.defaults = {};
+      if (d.mode === "full" || d.mode === "auto") out.defaults.mode = d.mode;
+      if (typeof d.classification === "string" && isClassification(d.classification)) {
+        out.defaults.classification = d.classification;
+      }
+      if (typeof d.gated === "boolean") out.defaults.gated = d.gated;
+    }
+
+    if (raw.parallel && typeof raw.parallel === "object") {
+      out.parallel = {};
+      for (const [phase, group] of Object.entries(raw.parallel)) {
+        if (!(PHASE_NAMES as readonly string[]).includes(phase)) continue;
+        const g = group as any;
+        if (!g || !Array.isArray(g.parallel)) continue;
+        const validSteps = STEPS_BY_PHASE[phase as PhaseName];
+        const parallel = g.parallel.filter((s: any) => typeof s === "string" && validSteps.includes(s));
+        if (parallel.length === 0) continue;
+        const entry: ProjectParallelGroup = { parallel };
+        if (typeof g.thenSequential === "string" && validSteps.includes(g.thenSequential)) {
+          entry.thenSequential = g.thenSequential;
+        }
+        out.parallel[phase as PhaseName] = entry;
+      }
+    }
+
+    if (raw.workflow && typeof raw.workflow === "object") {
+      out.workflow = {};
+      for (const key of ["include", "exclude"] as const) {
+        if (Array.isArray(raw.workflow[key])) {
+          out.workflow[key] = raw.workflow[key].filter((s: any) => isValidStepRef(s));
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+function isValidStepRef(ref: any): boolean {
+  if (typeof ref !== "string") return false;
+  const [phase, step] = ref.split("/");
+  if (!phase || !step) return false;
+  if (!(PHASE_NAMES as readonly string[]).includes(phase)) return false;
+  return STEPS_BY_PHASE[phase as PhaseName].includes(step);
+}