karajan-code 2.7.3 → 2.8.0

package/src/plan/plan-reviewer.js

@@ -0,0 +1,199 @@
+/**
+ * Plan reviewer — third pass after `kj plan` (PR D of the v2.7.5
+ * tests-first roadmap). Asks the planner LLM five concrete
+ * questions about the plan it just produced. Returns structured
+ * findings, NOT free-form prose.
+ *
+ * The questions are intentionally closed-ended:
+ *
+ *   1. **Missing HUs** — sections of the SPEC the plan doesn't cover.
+ *      (Catches "the planner forgot module X".)
+ *   2. **Missing dependencies** — pairs of HUs that should have a
+ *      `blocked_by` edge but don't.
+ *      (Catches "HU 4 needs the schema HU 2 produces".)
+ *   3. **Scope overlap** — pairs of HUs that touch the same scope.
+ *      (Catches "the planner split one piece of work into two HUs
+ *      that step on each other".)
+ *   4. **Parallelisable** — sets of HUs that have no inter-deps and
+ *      could run side-by-side.
+ *      (Surface for the user, not auto-applied — `kj run --plan`
+ *      runs serially today.)
+ *   5. **Order issues** — HUs whose `blocked_by` chain is wrong or
+ *      circular.
+ *
+ * The output is purely advisory. The reviewer NEVER edits the plan.
+ * It reports findings; the user decides whether to apply them via
+ * the board's edit modal or another `kj plan` pass.
+ *
+ * Free-form "could we add logging?" suggestions are explicitly out
+ * of scope to avoid scope-creep noise — see the prompt rules.
+ */
+
+import { extractFirstJson } from "../utils/json-extract.js";
+
+/**
+ * Build the focused review prompt. Exported for unit-testing the
+ * shape without an LLM in the loop.
+ *
+ * @param {object} args
+ * @param {string} args.task
+ * @param {Array<object>} args.hus
+ * @returns {string}
+ */
+export function buildReviewerPrompt({ task, hus }) {
+  const huSummary = hus.map((h, i) => {
+    const deps = Array.isArray(h.blocked_by) && h.blocked_by.length > 0
+      ? ` ← blocked_by: ${h.blocked_by.join(", ")}`
+      : "";
+    const spec = h.spec_section ? ` [§${h.spec_section}]` : "";
+    return `${i + 1}. ${h.id}${spec}: ${h.title || "(untitled)"}${deps}\n   scope: ${h.scope || "(none)"}`;
+  }).join("\n\n");
+
+  return [
+    "You previously generated an implementation plan for the task below.",
+    "Your ONLY job in this call is to review it against five specific questions.",
+    "DO NOT propose new features, logging, monitoring, refactors, or anything",
+    "beyond what the SPEC explicitly requires. We're checking the plan for",
+    "completeness and correctness — NOT improving its scope.",
+    "",
+    "Output MUST be a JSON object with this exact shape:",
+    "",
+    "```json",
+    "{",
+    '  "missing_hus": [',
+    '    { "spec_section": "<section ref or short description>", "rationale": "<why it should exist>" }',
+    "  ],",
+    '  "missing_dependencies": [',
+    '    { "from": "<huId that should depend on>", "on": "<huId>", "rationale": "<why>" }',
+    "  ],",
+    '  "scope_overlaps": [',
+    '    { "between": ["<huId>", "<huId>"], "rationale": "<why they overlap>" }',
+    "  ],",
+    '  "parallelisable_groups": [',
+    '    { "his": ["<huId>", "<huId>"], "rationale": "<why these can run side-by-side>" }',
+    "  ],",
+    '  "order_issues": [',
+    '    { "hus": ["<huId>"], "issue": "<wrong order | circular | other>", "rationale": "<why>" }',
+    "  ],",
+    '  "summary": "<one sentence overall verdict>"',
+    "}",
+    "```",
+    "",
+    "Rules:",
+    "- Each array can be empty if there's nothing to flag for that question.",
+    "- Reference HUs by their EXACT id from the list below.",
+    "- Suggest at MOST 5 entries per array — only the most important ones.",
+    "- DO NOT propose tests / acceptance criteria — those are handled by other roles.",
+    "- DO NOT suggest renames / cosmetic changes — only structural issues.",
+    "- Return ONLY the JSON — no prose, no markdown fences around it.",
+    "",
+    "## Original Task",
+    task,
+    "",
+    "## Plan to review",
+    "",
+    huSummary,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Run the focused review pass.
+ *
+ * Pure-function side: parses the LLM JSON and normalises the shape
+ * (missing arrays default to `[]`, summary defaults to `""`). Junk
+ * entries (missing required fields) are dropped silently.
+ *
+ * @param {object} args
+ * @param {object} args.agent
+ * @param {string} args.task
+ * @param {Array<object>} args.hus
+ * @param {Function} [args.onOutput]
+ * @param {number} [args.silenceTimeoutMs]
+ * @param {number} [args.timeoutMs]
+ * @returns {Promise<{ ok: boolean, findings?: object, error?: string }>}
+ */
+export async function reviewPlan({ agent, task, hus, onOutput, silenceTimeoutMs, timeoutMs }) {
+  if (!Array.isArray(hus) || hus.length === 0) {
+    return { ok: true, findings: emptyFindings("Plan has no HUs to review.") };
+  }
+  const prompt = buildReviewerPrompt({ task, hus });
+  const runArgs = { prompt, role: "planner" };
+  if (onOutput) runArgs.onOutput = onOutput;
+  if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
+  if (timeoutMs) runArgs.timeoutMs = timeoutMs;
+
+  const result = await agent.runTask(runArgs);
+  if (!result.ok) {
+    return { ok: false, error: result.error || "reviewer agent failed" };
+  }
+  const parsed = extractFirstJson(result.output || "");
+  if (!parsed || typeof parsed !== "object") {
+    return { ok: false, error: "reviewer returned no JSON object" };
+  }
+  return { ok: true, findings: normaliseFindings(parsed) };
+}
+
+function emptyFindings(summary) {
+  return {
+    missing_hus: [],
+    missing_dependencies: [],
+    scope_overlaps: [],
+    parallelisable_groups: [],
+    order_issues: [],
+    summary: summary || "",
+  };
+}
+
+/**
+ * Coerce the raw LLM payload into the canonical shape. Each list is
+ * filtered to keep only entries with the required fields populated.
+ * @param {object} raw
+ */
+function normaliseFindings(raw) {
+  const f = emptyFindings(typeof raw.summary === "string" ? raw.summary : "");
+  if (Array.isArray(raw.missing_hus)) {
+    f.missing_hus = raw.missing_hus
+      .filter((m) => m && (m.spec_section || m.section || m.title) && m.rationale)
+      .map((m) => ({
+        spec_section: String(m.spec_section || m.section || m.title),
+        rationale: String(m.rationale),
+      }));
+  }
+  if (Array.isArray(raw.missing_dependencies)) {
+    f.missing_dependencies = raw.missing_dependencies
+      .filter((d) => d && d.from && d.on && d.rationale)
+      .map((d) => ({ from: String(d.from), on: String(d.on), rationale: String(d.rationale) }));
+  }
+  if (Array.isArray(raw.scope_overlaps)) {
+    f.scope_overlaps = raw.scope_overlaps
+      .filter((o) => o && Array.isArray(o.between) && o.between.length >= 2 && o.rationale)
+      .map((o) => ({ between: o.between.map(String), rationale: String(o.rationale) }));
+  }
+  if (Array.isArray(raw.parallelisable_groups)) {
+    f.parallelisable_groups = raw.parallelisable_groups
+      .filter((g) => g && Array.isArray(g.hus) && g.hus.length >= 2)
+      .map((g) => ({ hus: g.hus.map(String), rationale: g.rationale ? String(g.rationale) : "" }));
+  }
+  if (Array.isArray(raw.order_issues)) {
+    f.order_issues = raw.order_issues
+      .filter((o) => o && Array.isArray(o.hus) && o.hus.length >= 1 && o.issue)
+      .map((o) => ({ hus: o.hus.map(String), issue: String(o.issue), rationale: o.rationale ? String(o.rationale) : "" }));
+  }
+  return f;
+}
+
+/**
+ * Flatten findings into a count of actionable items (for the CLI
+ * banner: "Reviewer found 3 issues.").
+ */
+export function findingsCount(findings) {
+  if (!findings) return 0;
+  return (
+    (findings.missing_hus?.length || 0)
+    + (findings.missing_dependencies?.length || 0)
+    + (findings.scope_overlaps?.length || 0)
+    + (findings.order_issues?.length || 0)
+    // parallelisable_groups is informational, not an issue.
+  );
+}

package/src/plan/plan-schema.js

@@ -4,11 +4,58 @@
  * v2 = plans + executable HUs with acceptance tests
  */
 
-import { generatePlanId, generateHuId } from "./plan-id.js";
+import { generatePlanId } from "./plan-id.js";
 
 const VALID_PLAN_STATUSES = new Set(["draft", "ready", "running", "done", "failed"]);
 const VALID_HU_STATUSES = new Set(["pending", "certified", "coding", "reviewing", "done", "failed", "blocked"]);
 const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "nocode"]);
+const VALID_TEST_TYPES = new Set(["shell", "gherkin"]);
+
+/**
+ * Structured acceptance-test shape introduced in v2.7.5 (tests-first):
+ *
+ *   { type: "shell",   content: "<bash command>", file?: "<optional path>" }
+ *   { type: "gherkin", content: "Given …\nWhen …\nThen …", file?: "<optional path>" }
+ *
+ * Legacy entries (plain strings) are accepted by validatePlan and get
+ * normalised to `{ type: "shell", content: <string> }` at read time by
+ * `normaliseAcceptanceTest`. New plans MUST emit the structured form.
+ *
+ * Why two types: shell tests are executable as-is (a bash command that
+ * exits 0 on pass); gherkin tests are human-readable specs that the
+ * tester role translates into real code tests during `kj run` — they
+ * are the contract the coder is expected to satisfy.
+ *
+ * @param {unknown} entry
+ * @returns {{ type: string, content: string, file?: string } | null}
+ */
+export function normaliseAcceptanceTest(entry) {
+  if (entry == null) return null;
+  if (typeof entry === "string") {
+    const trimmed = entry.trim();
+    if (!trimmed) return null;
+    return { type: "shell", content: trimmed };
+  }
+  if (typeof entry === "object" && typeof entry.content === "string") {
+    const content = entry.content.trim();
+    if (!content) return null;
+    const type = VALID_TEST_TYPES.has(entry.type) ? entry.type : "shell";
+    const out = { type, content };
+    if (typeof entry.file === "string" && entry.file.trim()) out.file = entry.file.trim();
+    return out;
+  }
+  return null;
+}
+
+/**
+ * Normalise an array of raw acceptance_tests, dropping empties.
+ * @param {unknown[]} list
+ * @returns {{ type: string, content: string, file?: string }[]}
+ */
+export function normaliseAcceptanceTests(list) {
+  if (!Array.isArray(list)) return [];
+  return list.map(normaliseAcceptanceTest).filter(Boolean);
+}
 
 /**
  * Check if a plan uses v2 schema (has version field + hus array).
@@ -98,6 +145,27 @@ export function validatePlan(plan) {
     if (!hu.title) errors.push(`HU ${hu.id}: missing title`);
     if (!VALID_HU_STATUSES.has(hu.status)) errors.push(`HU ${hu.id}: invalid status ${hu.status}`);
     if (hu.task_type && !VALID_TASK_TYPES.has(hu.task_type)) errors.push(`HU ${hu.id}: invalid task_type ${hu.task_type}`);
+    // acceptance_tests: may be absent (legacy) or an array of either
+    // plain strings (legacy shell) or { type, content, file? } objects.
+    if (hu.acceptance_tests !== undefined) {
+      if (!Array.isArray(hu.acceptance_tests)) {
+        errors.push(`HU ${hu.id}: acceptance_tests must be an array`);
+      } else {
+        hu.acceptance_tests.forEach((entry, idx) => {
+          if (typeof entry === "string") return; // legacy form — OK
+          if (!entry || typeof entry !== "object") {
+            errors.push(`HU ${hu.id}: acceptance_tests[${idx}] must be a string or { type, content } object`);
+            return;
+          }
+          if (entry.type && !VALID_TEST_TYPES.has(entry.type)) {
+            errors.push(`HU ${hu.id}: acceptance_tests[${idx}].type must be one of ${[...VALID_TEST_TYPES].join("|")}`);
+          }
+          if (typeof entry.content !== "string" || !entry.content.trim()) {
+            errors.push(`HU ${hu.id}: acceptance_tests[${idx}].content must be a non-empty string`);
+          }
+        });
+      }
+    }
     // Check blocked_by references exist
     for (const dep of hu.blocked_by || []) {
       if (!huIds.has(dep) && !(plan.hus || []).some(h => h.id === dep)) {

package/src/plan/plan-store.js

@@ -10,11 +10,43 @@ import os from "node:os";
 import { generatePlanId } from "./plan-id.js";
 import { isPlanV2, migratePlanV1toV2 } from "./plan-schema.js";
 
-function getKjHome() {
-  return process.env.KJ_HOME || path.join(os.homedir(), ".kj");
+// Per-process tmp dir for VITEST runs that forget to set KJ_HOME. We
+// memoise across calls so every helper in the same test process sees
+// the same root (mirrors what setting KJ_HOME explicitly would do)
+// without racing. The trailing `.kj` segment keeps semantic parity
+// with non-VITEST defaults so existing path assertions don't break.
+let _vitestKjHome = null;
+function vitestTmpKjHome() {
+  if (_vitestKjHome) return _vitestKjHome;
+  _vitestKjHome = path.join(
+    os.tmpdir(),
+    `kj-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+    ".kj"
+  );
+  return _vitestKjHome;
 }
 
-function projectSlug(projectDir) {
+export function getKjHome() {
+  if (process.env.KJ_HOME) return process.env.KJ_HOME;
+  // VITEST guard — without this, a test that calls savePlan() drops
+  // fixture files into the developer's real `~/.kj/plans/` and the
+  // running HU Board's chokidar watcher ingests them as "real" plans
+  // (observed: 49 fake "Add auth" plans contaminating the user's
+  // board). Auto-isolate to a per-process tmp dir so accidental
+  // writes can't leak. Tests that NEED to assert against a known
+  // path should still set KJ_HOME explicitly.
+  if (process.env.VITEST) return vitestTmpKjHome();
+  return path.join(os.homedir(), ".kj");
+}
+
+/**
+ * Deterministic slug for a project path — stable across plan-store writes,
+ * HU-board syncs and board URL routing. Keep in lockstep with
+ * `packages/hu-board/src/sync.js::deriveProjectIdFromDir`.
+ * @param {string} projectDir - absolute project path
+ * @returns {string}
+ */
+export function projectSlug(projectDir) {
   return projectDir
     .replace(/^\//, "")
     .replace(/[/\\]/g, "_")
@@ -40,6 +72,11 @@ export async function savePlan(projectDir, planResult) {
   if (isPlanV2(planResult)) {
     const filePath = path.join(dir, `${planResult.planId}.json`);
     planResult.updatedAt = new Date().toISOString();
+    // TSK-0341 / garbage-collector: stamp the absolute projectDir on every
+    // plan so the GC can check `fs.exists(projectDir)` reliably. Reverse-
+    // engineering it from the slug is lossy (underscores in the original
+    // name collide with underscores introduced by slash-substitution).
+    if (!planResult.projectDir && projectDir) planResult.projectDir = projectDir;
     await fs.writeFile(filePath, JSON.stringify(planResult, null, 2), "utf8");
     return planResult.planId;
   }

package/src/plan/spec-detector.js

@@ -0,0 +1,61 @@
+/**
+ * Detect numbered/sectioned headings in a task description so the
+ * planner prompt can demand `spec_section` per HU instead of leaving
+ * it as a soft "preferred" hint that LLMs ignore.
+ *
+ * Recognises three common shapes (kept intentionally narrow — false
+ * positives turn the planner prompt into noise):
+ *
+ *   ## 1. Overview              → section "1",   title "Overview"
+ *   ### 2.1 add                 → section "2.1", title "add"
+ *   ## §5 Initial Scope         → section "5",   title "Initial Scope"
+ *
+ * The matcher is anchored to markdown heading lines (`^#+`) so prose
+ * mentions of a number ("see version 4.2") never trigger detection.
+ *
+ * Returns `{ hasSpec, sections, sectionList }`:
+ *   - `hasSpec`     boolean — true when at least one heading matched.
+ *                   Prompt builders use this to switch language from
+ *                   "preferred" to "MUST".
+ *   - `sections`    string[] — bare section refs, dedup, in document
+ *                   order. e.g. ["1", "2", "2.1", "2.2", "3"].
+ *   - `sectionList` Array<{section, title}> — full list with titles
+ *                   so the prompt can echo the checklist back at the
+ *                   LLM. Keeps order, dedup by section ref.
+ *
+ * @param {string} text
+ * @returns {{ hasSpec: boolean, sections: string[], sectionList: Array<{section: string, title: string}> }}
+ */
+export function detectSpecSections(text) {
+  const empty = { hasSpec: false, sections: [], sectionList: [] };
+  if (!text || typeof text !== "string") return empty;
+
+  // Anchored to heading lines. Two regex shapes — numbered sections
+  // and §-prefixed sections — are both common in the wild.
+  //
+  //   ^#{1,6}\s*               ← markdown heading marker (any depth)
+  //   §?\s*                    ← optional "§"
+  //   (\d+(?:\.\d+){0,4})      ← section number, up to 5 levels deep
+  //   [.)]?\s+                 ← optional trailing "." or ")", then space
+  //   (.+?)\s*$                ← title (lazy, trim trailing whitespace)
+  const headingRe = /^#{1,6}\s*§?\s*(\d+(?:\.\d+){0,4})[.)]?\s+(.+?)\s*$/;
+
+  const seen = new Set();
+  const sectionList = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trimEnd();
+    const m = headingRe.exec(line);
+    if (!m) continue;
+    const section = m[1];
+    if (seen.has(section)) continue;
+    seen.add(section);
+    sectionList.push({ section, title: m[2].trim() });
+  }
+
+  if (sectionList.length === 0) return empty;
+  return {
+    hasSpec: true,
+    sections: sectionList.map((s) => s.section),
+    sectionList,
+  };
+}

package/src/plan/tests-synthesizer.js

@@ -0,0 +1,116 @@
+/**
+ * Tests-first second pass for `kj plan` (v2.7.5).
+ *
+ * The first planner call asks for steps + acceptance_tests in one
+ * shot. Modern LLMs (Claude, Codex) reliably produce the steps but
+ * frequently skip the acceptance_tests sub-instruction when the
+ * surrounding spec is dense — a known weakness of long single-shot
+ * prompts. Pre-v2.7.5 we papered over this with a generic `npx
+ * vitest run` placeholder that wasn't actually a per-HU contract.
+ *
+ * This module runs a focused SECOND pass that asks the LLM ONLY to
+ * fill in tests for the HUs that came back without them. Because the
+ * prompt is shorter and has a single deliverable, the hit rate is
+ * effectively 100% on the HUs that slipped through the first time.
+ *
+ * Returns a map `{ huId → acceptance_tests[] }` so the caller can
+ * patch the plan in place. The patch always normalises through
+ * `plan-schema::normaliseAcceptanceTests`, so any malformed entries
+ * the LLM produces are silently dropped (better than corrupting the
+ * plan with junk).
+ */
+
+import { extractFirstJson } from "../utils/json-extract.js";
+import { normaliseAcceptanceTests } from "./plan-schema.js";
+
+/**
+ * Build the focused-pass prompt asking ONLY for tests for the given
+ * HUs. Exported for unit-testing the prompt shape without an LLM.
+ *
+ * @param {object} args
+ * @param {string} args.task
+ * @param {Array<{ id: string, title?: string, scope?: string }>} args.husNeedingTests
+ * @returns {string}
+ */
+export function buildSynthesizerPrompt({ task, husNeedingTests }) {
+  const lines = [
+    "You previously generated an implementation plan for the task below, but some HUs were left without acceptance_tests.",
+    "Your ONLY job in this call is to fill that gap.",
+    "",
+    "Output MUST be a JSON object with this exact shape:",
+    "",
+    "```json",
+    "{",
+    '  "tests": {',
+    '    "<huId>": [',
+    '      { "type": "gherkin", "content": "Given <ctx>\\nWhen <action>\\nThen <outcome>" },',
+    '      { "type": "shell", "content": "<bash command that must exit 0>" }',
+    "    ]",
+    "  }",
+    "}",
+    "```",
+    "",
+    "Rules:",
+    "- The keys of `tests` are the HU ids EXACTLY as listed below.",
+    "- 2-4 tests per HU. At least one happy-path and one edge case.",
+    "- gherkin = behaviour spec; shell = concrete bash command exiting 0 on pass.",
+    "- Tests must be specific to the HU. Do NOT use generic fallbacks like `npx vitest run`.",
+    "- Tests must be writable BEFORE the HU is implemented (they should fail until done).",
+    "- Return ONLY the JSON — no prose, no markdown fences around it.",
+    "",
+    "## Task",
+    task,
+    "",
+    "## HUs that need acceptance_tests",
+    "",
+  ];
+  for (const hu of husNeedingTests) {
+    lines.push(`### ${hu.id}: ${hu.title || ""}`);
+    lines.push(hu.scope ? `Scope: ${hu.scope}` : "(no scope)");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Run the focused second pass. Pass an `agent` with a `runTask`
+ * method (Claude / Codex / Gemini wrappers all expose it).
+ *
+ * @param {object} args
+ * @param {object} args.agent
+ * @param {string} args.task
+ * @param {Array<{ id: string, title?: string, scope?: string }>} args.husNeedingTests
+ * @param {Function} [args.onOutput]
+ * @param {number} [args.silenceTimeoutMs]
+ * @param {number} [args.timeoutMs]
+ * @returns {Promise<{ ok: boolean, tests?: Record<string, object[]>, error?: string }>}
+ */
+export async function synthesizeMissingTests({ agent, task, husNeedingTests, onOutput, silenceTimeoutMs, timeoutMs }) {
+  if (!Array.isArray(husNeedingTests) || husNeedingTests.length === 0) {
+    return { ok: true, tests: {} };
+  }
+  const prompt = buildSynthesizerPrompt({ task, husNeedingTests });
+  const runArgs = { prompt, role: "planner" };
+  if (onOutput) runArgs.onOutput = onOutput;
+  if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
+  if (timeoutMs) runArgs.timeoutMs = timeoutMs;
+
+  const result = await agent.runTask(runArgs);
+  if (!result.ok) {
+    return { ok: false, error: result.error || "synthesizer agent failed" };
+  }
+
+  const parsed = extractFirstJson(result.output || "");
+  const rawTests = parsed?.tests;
+  if (!rawTests || typeof rawTests !== "object") {
+    return { ok: false, error: "synthesizer returned no `tests` object" };
+  }
+
+  // Normalise per HU so junk entries don't slip into the plan.
+  const tests = {};
+  for (const [huId, list] of Object.entries(rawTests)) {
+    const cleaned = normaliseAcceptanceTests(list);
+    if (cleaned.length > 0) tests[huId] = cleaned;
+  }
+  return { ok: true, tests };
+}

package/src/planning-game/client.js

@@ -37,7 +37,7 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
       err.httpStatus = 408;
       throw err;
     }
-    throw new Error(`Planning Game network error: ${error?.message || "unknown error"}`);
+    throw new Error(`Planning Game network error: ${error?.message || "unknown error"}`, { cause: error });
   } finally {
     clearTimeout(timeoutId);
   }
@@ -54,7 +54,7 @@ async function parseJsonResponse(response) {
   try {
     return await response.json();
   } catch (error) {
-    throw new Error(`Planning Game invalid response: ${error?.message || "invalid JSON"}`);
+    throw new Error(`Planning Game invalid response: ${error?.message || "invalid JSON"}`, { cause: error });
   }
 }
 
@@ -65,18 +65,7 @@ export async function fetchCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT
   return data?.card || data;
 }
 
-async function getCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
-  return fetchCard({ projectId, cardId, timeoutMs });
-}
-
-async function listCards({ projectId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
-  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards`;
-  const response = await fetchWithRetry(url, {}, timeoutMs);
-  const data = await parseJsonResponse(response);
-  return data?.cards || data;
-}
-
-export async function updateCard({ projectId, cardId, firebaseId, updates, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+export async function updateCard({ projectId, cardId: _cardId, firebaseId, updates, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(firebaseId)}`;
   const response = await fetchWithRetry(
     url,

package/src/planning-game/decomposition.js

@@ -10,7 +10,7 @@ export async function createDecompositionSubtasks({
   client,
   projectId,
   parentCardId,
-  parentFirebaseId,
+  parentFirebaseId: _parentFirebaseId,
   subtasks,
   epic,
   sprint,

package/src/planning-game/pipeline-adapter.js

@@ -12,7 +12,8 @@
  */
 
 import { emitProgress, makeEvent } from "../utils/events.js";
-import { addCheckpoint, saveSession } from "../session-store.js";
+import { addCheckpoint } from "../session/store.js";
+import { appendPgCommits } from "../session/mutators.js";
 import { getLang } from "../utils/messages.js";
 
 /**
@@ -28,7 +29,7 @@ import { getLang } from "../utils/messages.js";
  * @param {string|null} opts.pgProject - Planning Game project ID
  * @returns {{ pgCard: object|null }} The fetched PG card (or null)
  */
-export async function initPgAdapter({ session, config, logger, pgTaskId, pgProject }) {
+export async function initPgAdapter({ session: _session, config, logger, pgTaskId, pgProject }) {
   if (!pgTaskId || !pgProject || config.planning_game?.enabled === false) {
     return { pgCard: null };
   }
@@ -183,13 +184,12 @@ export function buildHuStoriesFromPgCard(pgCard) {
  */
 export function accumulateCommit(session, commitInfo) {
   if (!session || !commitInfo?.hash) return;
-  if (!session.pg_commits) session.pg_commits = [];
-  session.pg_commits.push({
+  appendPgCommits(session, [{
     hash: commitInfo.hash,
     message: commitInfo.message || "",
     date: commitInfo.date || new Date().toISOString(),
     author: commitInfo.author || "Karajan"
-  });
+  }]);
 }
 
 // --- Internal helpers ---
@@ -218,3 +218,34 @@ async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
     return null;
   }
 }
+
+/**
+ * TSK-0339: integration adapter shape — the orchestrator consumes tracker
+ * hooks via this neutral interface, not via direct imports. `registerPgAdapter`
+ * is called once at bootstrap when `config.planning_game.enabled` is true,
+ * wiring these hooks into `src/orchestrator/integrations.js` under the
+ * "tracker" slot.
+ *
+ * Adding a new tracker (GitHub Projects, Jira, Linear, …) means creating
+ * a sibling `src/adapters/<name>/adapter.js` with the same hook surface,
+ * nothing else in the orchestrator changes.
+ */
+export const planningGameAdapter = {
+  name: "planning-game",
+  async onSessionStart(opts) { return initPgAdapter(opts); },
+  onCommit(session, commit) { accumulateCommit(session, commit); },
+  async onSessionApproved(opts) { return markPgCardToValidate(opts); },
+  buildHuStoriesFromCard(card) { return buildHuStoriesFromPgCard(card); },
+  async handleDecomposition(opts) { return handlePgDecomposition(opts); },
+  async createAdrsFromTradeoffs({ tradeoffs, pgTaskId, pgProject, taskTitle }) {
+    // Lazy-loaded to avoid pulling createArchitectADRs into every import.
+    const { createArchitectADRs } = await import("./architect-adrs.js");
+    const pgClient = await import("./client.js");
+    return createArchitectADRs({ tradeoffs, pgTaskId, pgProject, taskTitle, mcpClient: pgClient });
+  },
+};
+
+export async function registerPgAdapter() {
+  const { registerIntegration } = await import("../orchestrator/integrations.js");
+  registerIntegration("tracker", planningGameAdapter);
+}