kc-beta 0.5.5 → 0.6.0

package/src/agent/llm-client.js

@@ -1,5 +1,20 @@
 import { withRetry } from "./retry.js";
 
+// A5: SSE accumulator safety cap. If a provider ever sends an abnormally
+// large `data: ...` line without a newline terminator, the parser's
+// `buffer += decoder.decode(chunk)` + `buffer.split("\n")` would grow
+// unbounded and trigger O(n²) splitting once it gets into the hundreds
+// of MB. 8 MB is multiple orders of magnitude above any legitimate single
+// SSE frame (largest seen in the wild: ~80 KB for multi-tool-call deltas).
+const SSE_BUFFER_CAP_BYTES = 8 * 1024 * 1024;
+
+class SseOverflowError extends Error {
+  constructor(bytes) {
+    super(`SSE buffer overflow (${bytes} bytes without newline) — aborting stream`);
+    this.code = "SSE_BUFFER_OVERFLOW";
+  }
+}
+
 /**
  * Multi-protocol LLM client using native fetch + SSE parsing.
  * Supports OpenAI-compatible APIs and Anthropic Messages API.
@@ -144,26 +159,56 @@ export class LLMClient {
   async *streamChat({ model, messages, tools, maxTokens }) {
     const body = this._buildStreamBody({ model, messages, tools, maxTokens });
 
-    const resp = await withRetry(async () => {
-      const r = await fetch(this._getEndpoint(), {
-        method: "POST",
-        headers: this._buildHeaders(),
-        body: JSON.stringify(body),
+    let resp;
+    try {
+      resp = await withRetry(async () => {
+        const r = await fetch(this._getEndpoint(), {
+          method: "POST",
+          headers: this._buildHeaders(),
+          body: JSON.stringify(body),
+        });
+        if (!r.ok) {
+          const text = await r.text();
+          const err = new Error(`LLM API error ${r.status}: ${text}`);
+          err.status = r.status;
+          err.retryAfter = r.headers.get("retry-after");
+          err.streamTermination = "http_error";
+          throw err;
+        }
+        return r;
       });
-      if (!r.ok) {
-        const text = await r.text();
-        const err = new Error(`LLM API error ${r.status}: ${text}`);
-        err.status = r.status;
-        err.retryAfter = r.headers.get("retry-after");
-        throw err;
-      }
-      return r;
-    });
+    } catch (err) {
+      // A8: Any pre-stream failure (network, auth, 4xx/5xx after retry) is
+      // tagged and re-thrown. Engine's outer catch sees exactly one tagged
+      // error event.
+      if (!err.streamTermination) err.streamTermination = "connect_error";
+      throw err;
+    }
 
-    if (this.apiFormat === "anthropic") {
-      yield* this._parseAnthropicSSE(resp.body);
-    } else {
-      yield* this._parseOpenaiSSE(resp.body);
+    // A8: Wrap the SSE consumption so ALL termination paths — clean EOS,
+    // mid-token abort, SSE overflow, provider disconnect — surface as a
+    // single tagged error the engine can report consistently. The inner
+    // parsers throw for overflow (A5) and return silently on clean EOS;
+    // mid-stream socket errors (undici "terminated") raise here.
+    try {
+      if (this.apiFormat === "anthropic") {
+        yield* this._parseAnthropicSSE(resp.body);
+      } else {
+        yield* this._parseOpenaiSSE(resp.body);
+      }
+    } catch (err) {
+      if (!err.streamTermination) {
+        if (err.code === "SSE_BUFFER_OVERFLOW") err.streamTermination = "sse_overflow";
+        else if (err.name === "AbortError") err.streamTermination = "aborted";
+        else if (/terminated|reset|ECONNRESET|UND_ERR_ABORTED/i.test(err.message || err.code || ""))
+          err.streamTermination = "stream_terminated";
+        else err.streamTermination = "stream_error";
+      }
+      throw err;
+    } finally {
+      // Best-effort: cancel the body so the underlying socket returns to the
+      // connection pool even if the consumer bailed mid-stream.
+      try { await resp.body?.cancel?.(); } catch { /* ignore */ }
     }
   }
 
@@ -261,6 +306,8 @@ export class LLMClient {
 
     for await (const chunk of body) {
       buffer += decoder.decode(chunk, { stream: true });
+      // A5: bail out before O(n²) split explodes on pathological input.
+      if (buffer.length > SSE_BUFFER_CAP_BYTES) throw new SseOverflowError(buffer.length);
       const lines = buffer.split("\n");
       buffer = lines.pop();
 
@@ -313,6 +360,8 @@ export class LLMClient {
 
     for await (const rawChunk of body) {
       buffer += decoder.decode(rawChunk, { stream: true });
+      // A5: cap applies to both SSE parsers.
+      if (buffer.length > SSE_BUFFER_CAP_BYTES) throw new SseOverflowError(buffer.length);
       const lines = buffer.split("\n");
       buffer = lines.pop();
 

package/src/agent/pipelines/finalization.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PipelineEvent } from "./index.js";
+import { Pipeline } from "./base.js";
+import { normalizeRuleCatalog } from "../rule-catalog-normalize.js";
+
+/**
+ * E1: FINALIZATION — the 7th phase. Runs after PRODUCTION_QC has shown
+ * the system working. Goal: turn the working system into a shippable
+ * deliverable.
+ *
+ * Responsibilities (observed via this pipeline's describeState + exit
+ * criteria; the agent does the actual work using workspace_file +
+ * sandbox_exec):
+ *   1. rule_skills/README.md  — inventory + how-to-run section.
+ *   2. rule_skills/coverage_report.md  — rule-id → skill-file mapping,
+ *      including which rules are "not_applicable" per D6 classification.
+ *   3. output/final_dashboard.html  — snapshot of the final metrics.
+ *   4. (Optional) Reorganized rule_skills/<rule_id>/ canonical layout:
+ *      when skills were written grouped (check_r002_r007.py), create
+ *      thin-link dirs for each constituent rule_id pointing at the
+ *      grouped file. Skipped if rule_skills/ is already per-rule.
+ *
+ * Exit criteria: all three deliverable files exist. The agent is free
+ * to produce more artifacts; these are the minimum-viable finalization
+ * set the pipeline requires before marking the release-ready.
+ *
+ * No successor phase — this is the terminal state. The agent can
+ * continue working in this phase (e.g. producing additional dashboards
+ * on request), but auto-advance stops here.
+ */
+export class FinalizationPipeline extends Pipeline {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this.readmeWritten = false;
+    this.coverageReportWritten = false;
+    this.finalDashboardWritten = false;
+    this.canonicalLayoutDone = false;
+    this._scanWorkspace();
+  }
+
+  _scanWorkspace() {
+    const cwd = this._workspace.cwd;
+    this.readmeWritten = fs.existsSync(path.join(cwd, "rule_skills", "README.md"));
+    this.coverageReportWritten = fs.existsSync(path.join(cwd, "rule_skills", "coverage_report.md"));
+    this.finalDashboardWritten = fs.existsSync(path.join(cwd, "output", "final_dashboard.html"));
+    // Canonical layout: every rule_id in the catalog has a dedicated
+    // directory OR a thin-link stub under rule_skills/<rule_id>/. When
+    // skills are already per-rule (every rule has its own dir) this is
+    // trivially true. When skills are grouped, the agent creates
+    // per-rule stub dirs that reference the grouped file. We approximate
+    // "canonical" by checking: does every catalog rule_id have a
+    // matching directory under rule_skills/?
+    this.canonicalLayoutDone = this._checkCanonicalLayout();
+  }
+
+  _checkCanonicalLayout() {
+    const cwd = this._workspace.cwd;
+    const catalogPath = path.join(cwd, "rules", "catalog.json");
+    const skillsDir = path.join(cwd, "rule_skills");
+    if (!fs.existsSync(catalogPath) || !fs.existsSync(skillsDir)) return false;
+    let rules;
+    try {
+      rules = normalizeRuleCatalog(JSON.parse(fs.readFileSync(catalogPath, "utf-8")));
+    } catch { return false; }
+    if (rules.length === 0) return false;
+
+    let existingDirs;
+    try {
+      existingDirs = new Set(
+        fs.readdirSync(skillsDir, { withFileTypes: true })
+          .filter((e) => e.isDirectory())
+          .map((e) => e.name),
+      );
+    } catch { return false; }
+
+    // Every rule id should have a matching directory. Directory name
+    // matches rule id (R014) OR falls inside a range dir (R078_R128).
+    const rangeDirs = [...existingDirs].map((name) => {
+      const m = name.match(/^R0*(\d+)[_-]R0*(\d+)$/i);
+      if (m) return { name, lo: parseInt(m[1], 10), hi: parseInt(m[2], 10) };
+      return null;
+    }).filter(Boolean);
+
+    for (const r of rules) {
+      if (!r.id) continue;
+      if (existingDirs.has(r.id)) continue;
+      const m = r.id.match(/^R0*(\d+)$/i);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (rangeDirs.some((rd) => rd.lo <= n && n <= rd.hi)) continue;
+      }
+      return false;
+    }
+    return true;
+  }
+
+  describeState() {
+    this._scanWorkspace();
+    const checklist = [
+      `- ${this.readmeWritten ? "✅" : "⏳"}  rule_skills/README.md`,
+      `- ${this.coverageReportWritten ? "✅" : "⏳"}  rule_skills/coverage_report.md`,
+      `- ${this.finalDashboardWritten ? "✅" : "⏳"}  output/final_dashboard.html`,
+      `- ${this.canonicalLayoutDone ? "✅" : "⏳"}  rule_skills/ canonical per-rule layout`,
+    ];
+    const parts = [
+      "## Phase: FINALIZATION\n" +
+      "Turn the working verification system into a shippable deliverable. The " +
+      "pipeline has completed end-to-end; now package it for handoff. This is " +
+      "the terminal phase — no successor. You can continue producing artifacts " +
+      "here on request.\n\n" +
+      "**Tasks to complete** (the pipeline considers the phase done when all " +
+      "four checkmarks are green):\n\n" +
+      checklist.join("\n") + "\n\n" +
+      "### What each artifact should contain\n\n" +
+      "- **README.md**: top of `rule_skills/` with file inventory, how to run " +
+      "  `run_all_checks.py` (if present), input format, expected output format, " +
+      "  dependencies, and a short 'what this does' for a reader who hasn't " +
+      "  seen the project.\n" +
+      "- **coverage_report.md**: one row per rule_id in catalog.json. Columns: " +
+      "  rule_id, source_ref, skill file (`check_r014.py` or `check_r002_r007.py`), " +
+      "  tested (Y/N), latest accuracy, retries, applicable-to-this-bundle " +
+      "  (Y/N from D6 classification). Rules marked not_applicable should be " +
+      "  grouped at the bottom with a note explaining which bundle-type " +
+      "  filtered them out.\n" +
+      "- **final_dashboard.html**: single-page snapshot. Reuse the " +
+      "  `dashboard_render` tool — it knows the metrics shape. This is the " +
+      "  hand-off artifact the developer user opens to see the final state.\n" +
+      "- **canonical layout**: the simplest check is `ls rule_skills/ | " +
+      "  wc -l` ≈ number of rules in the catalog. When grouped files exist " +
+      "  (`check_r002_r007.py`), create stub `rule_skills/R002/` through " +
+      "  `rule_skills/R007/` each containing a one-line SKILL.md that points " +
+      "  at the grouped file. This keeps downstream per-rule lookups simple.",
+    ];
+    return parts.join("\n\n");
+  }
+
+  onToolResult(toolName, toolInput, result) {
+    if (result.isError) return null;
+    const wasReady = this.exitCriteriaMet();
+    const touchedPath = String(
+      toolInput?.path || toolInput?.command || "",
+    );
+    // Re-scan when the agent writes to any relevant path
+    if (
+      touchedPath.includes("rule_skills/") ||
+      touchedPath.includes("output/final_dashboard") ||
+      touchedPath.includes("coverage_report")
+    ) {
+      this._scanWorkspace();
+    }
+    if (!wasReady && this.exitCriteriaMet()) {
+      // Terminal phase — no nextPhase. Pipeline event signals "done."
+      return new PipelineEvent({
+        type: "phase_ready",
+        message: "Finalization artifacts complete. Session deliverable is ready.",
+        nextPhase: null,
+      });
+    }
+    return null;
+  }
+
+  exitCriteriaMet() {
+    return this.readmeWritten &&
+      this.coverageReportWritten &&
+      this.finalDashboardWritten &&
+      this.canonicalLayoutDone;
+  }
+
+  exportState() {
+    return {
+      readmeWritten: this.readmeWritten,
+      coverageReportWritten: this.coverageReportWritten,
+      finalDashboardWritten: this.finalDashboardWritten,
+      canonicalLayoutDone: this.canonicalLayoutDone,
+    };
+  }
+
+  importState(data) {
+    if (typeof data?.readmeWritten === "boolean") this.readmeWritten = data.readmeWritten;
+    if (typeof data?.coverageReportWritten === "boolean") this.coverageReportWritten = data.coverageReportWritten;
+    if (typeof data?.finalDashboardWritten === "boolean") this.finalDashboardWritten = data.finalDashboardWritten;
+    if (typeof data?.canonicalLayoutDone === "boolean") this.canonicalLayoutDone = data.canonicalLayoutDone;
+  }
+}

package/src/agent/pipelines/index.js

@@ -1,5 +1,12 @@
 /**
  * Pipeline phases — sequential workflow of the KC Agent methodology.
+ *
+ * v0.6.0 E1: FINALIZATION added as the 7th phase. It's a cleanup /
+ * deliverable-packaging phase that runs after PRODUCTION_QC has
+ * established the system is operating correctly: reorganize
+ * rule_skills/ into a canonical layout, write README + coverage
+ * report, snapshot a final dashboard, archive stale retry outputs.
+ * Short phase, a handful of tasks, driven by a finalization skill.
  */
 export const Phase = Object.freeze({
   BOOTSTRAP: "bootstrap",
@@ -8,6 +15,7 @@ export const Phase = Object.freeze({
   SKILL_TESTING: "skill_testing",
   DISTILLATION: "distillation",
   PRODUCTION_QC: "production_qc",
+  FINALIZATION: "finalization",
 });
 
 /**

package/src/agent/pipelines/initializer.js

@@ -138,6 +138,31 @@ export class ProjectInitializer extends Pipeline {
     this.configReady = !!gc.api_key;
   }
 
+  /**
+   * F1b: Worker LLM health snapshot. Static check only — inspect whether
+   * TIER1-4 and OCR_MODEL_TIER1 are populated in .env. Does NOT make
+   * network calls — a live ping would be invasive for bootstrap (slow,
+   * charges money, and the worker LLM isn't actually used until
+   * DISTILLATION). Surfacing the config state is enough for bootstrap.
+   * The agent can then decide to validate via worker_llm_call later if
+   * warranted. Returns null when no .env exists yet.
+   */
+  _workerConfigSnapshot() {
+    const envPath = path.join(this._workspace.cwd, ".env");
+    if (!fs.existsSync(envPath)) return null;
+    const tiers = { TIER1: "", TIER2: "", TIER3: "", TIER4: "", OCR_MODEL_TIER1: "" };
+    try {
+      for (const line of fs.readFileSync(envPath, "utf-8").split("\n")) {
+        for (const k of Object.keys(tiers)) {
+          if (line.startsWith(`${k}=`)) {
+            tiers[k] = line.slice(k.length + 1).trim();
+          }
+        }
+      }
+    } catch { return null; }
+    return tiers;
+  }
+
   _loadGlobalConfig() {
     const p = path.join(os.homedir(), ".kc_agent", "config.json");
     if (fs.existsSync(p)) { try { return JSON.parse(fs.readFileSync(p, "utf-8")); } catch { /* skip */ } }
@@ -158,6 +183,21 @@ export class ProjectInitializer extends Pipeline {
     if (completed.length) parts.push("### Done\n" + completed.map((c) => `- [x] ${c}`).join("\n"));
     if (pending.length) parts.push("### Needed\n" + pending.map((p) => `- [ ] ${p}`).join("\n"));
 
+    // F1b: surface worker-LLM tier status as part of bootstrap state so
+    // the agent can flag missing tiers to the developer user upfront,
+    // rather than hitting "worker LLM unreachable" hours later during
+    // DISTILLATION. Static inspection only — no network calls.
+    const workerConfig = this._workerConfigSnapshot();
+    if (workerConfig) {
+      const tierLines = [];
+      for (const [k, v] of Object.entries(workerConfig)) {
+        if (v) tierLines.push(`- ${k}: ${v}`);
+        else tierLines.push(`- ${k}: ⚠️ (empty — set before DISTILLATION, or worker_llm_call tools will fail)`);
+      }
+      parts.push("### Worker LLM tiers (.env snapshot)\n" + tierLines.join("\n") +
+        "\n\nThese drive `worker_llm_call`, `workflow_run`, `document_parse` OCR, etc. Empty tiers don't block bootstrap — but DISTILLATION requires at least TIER1 to be live. Discuss with the developer user if any are missing.");
+    }
+
     if (this.exitCriteriaMet()) {
       parts.push("### Exit\nBootstrap requirements met. Proceed to EXTRACTION.");
     }

package/src/agent/pipelines/skill-authoring.js

@@ -34,6 +34,14 @@ export class SkillAuthoringPipeline extends Pipeline {
   _scanSkills() {
     this.skillsAuthored = [];
     this.skillsWithScripts = [];
+    // D2: rule_ids that are covered by some authored skill — whether that
+    // skill is single-rule (rule_skills/R014/) or grouped
+    // (rule_skills/SK02/check_r002_r007.py). Populated by _walkForRuleIds
+    // below so the exit criterion counts DISTINCT rule coverage rather
+    // than skill-directory count, which over-counts when skills are
+    // grouped (session 6304673afaa0's rule_skills/ had 289 rules packed
+    // into 23 skill files).
+    this.ruleIdsCovered = new Set();
     const dir = path.join(this._workspace.cwd, "rule_skills");
     if (!fs.existsSync(dir)) return;
     for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -46,19 +54,97 @@ export class SkillAuthoringPipeline extends Pipeline {
       if (fs.existsSync(scriptsDir) && fs.readdirSync(scriptsDir).length > 0) {
         this.skillsWithScripts.push(e.name);
       }
+      this._walkForRuleIds(skillPath);
     }
   }
 
+  /**
+   * D2: Find rule_ids referenced by any file under the skill directory.
+   * Recognizes three naming patterns from actual sessions:
+   *   - Directory name matches a rule: rule_skills/R014/
+   *   - Single-rule script: check_r014.py
+   *   - Grouped script: check_r002_r007.py → covers R002 through R007
+   */
+  _walkForRuleIds(skillDir) {
+    const dirName = path.basename(skillDir);
+    const dirMatch = dirName.match(/^R0*(\d+)$/i);
+    if (dirMatch) this.ruleIdsCovered.add(`R${String(parseInt(dirMatch[1], 10)).padStart(3, "0")}`);
+
+    const walk = (d) => {
+      let entries;
+      try { entries = fs.readdirSync(d, { withFileTypes: true }); }
+      catch { return; }
+      for (const e of entries) {
+        if (e.name.startsWith(".")) continue;
+        const p = path.join(d, e.name);
+        if (e.isDirectory()) { walk(p); continue; }
+        // Per-rule: check_r014.py
+        const single = e.name.match(/check_r0*(\d+)\.py$/i);
+        if (single) {
+          this.ruleIdsCovered.add(`R${String(parseInt(single[1], 10)).padStart(3, "0")}`);
+          continue;
+        }
+        // Grouped: check_r002_r007.py, check_r002-r007.py, check_r59_r77.py
+        const grouped = e.name.match(/check_r0*(\d+)[_-]+r0*(\d+)\.py$/i);
+        if (grouped) {
+          const lo = parseInt(grouped[1], 10);
+          const hi = parseInt(grouped[2], 10);
+          for (let n = lo; n <= hi; n++) {
+            this.ruleIdsCovered.add(`R${String(n).padStart(3, "0")}`);
+          }
+          continue;
+        }
+        // Directory names that encode ranges: R078_R128/
+        // handled by caller passing skillDir
+      }
+    };
+    // Also handle dirs named like R078_R128/
+    const rangeDir = dirName.match(/^R0*(\d+)[_-]R0*(\d+)$/i);
+    if (rangeDir) {
+      const lo = parseInt(rangeDir[1], 10);
+      const hi = parseInt(rangeDir[2], 10);
+      for (let n = lo; n <= hi; n++) {
+        this.ruleIdsCovered.add(`R${String(n).padStart(3, "0")}`);
+      }
+    }
+    walk(skillDir);
+  }
+
   describeState() {
     this._scanWorkspace();
     const total = this.totalRules.length;
-    const authored = this.skillsAuthored.length;
-    const remaining = this.totalRules.filter((r) => !this.skillsAuthored.includes(r));
-    const parts = ["## Phase: SKILL_AUTHORING\nWrite verification skills for each extracted rule. Skills are first-class deliverables — they may serve as the production solution when worker LLM workflows are insufficient. Follow Anthropic skill-creator format. This is BUILD mode."];
-    parts.push(`### Progress\n- Rules: ${total}\n- Skills authored: ${authored}\n- Skills with scripts/: ${this.skillsWithScripts.length}${remaining.length > 0 ? `\n- Remaining: ${remaining.slice(0, 10).join(", ")}` : ""}`);
+    const covered = this.ruleIdsCovered.size;
+    const uncovered = this.totalRules.filter((r) => !this.ruleIdsCovered.has(r));
+    const parts = [
+      "## Phase: SKILL_AUTHORING\n" +
+      "Write verification skills for each extracted rule. Skills are first-class " +
+      "deliverables — they may serve as the production solution when worker LLM " +
+      "workflows are insufficient. Follow Anthropic skill-creator format. This is " +
+      "BUILD mode.\n\n" +
+      // D2: soft granularity nudge
+      "**Granularity preference:** 1 rule = 1 skill directory. Group rules into " +
+      "the same file ONLY when they share evidence and fail together (e.g. " +
+      "siblings from the same required-fields table). When grouping, name the " +
+      "file with the range: `check_r002_r007.py`. Downstream consumers " +
+      "(workflow-run, dashboards) count rule coverage by parsing these names, " +
+      "so the file-naming matters.\n\n" +
+      "**Do not write to rules/catalog.json via sandbox_exec.** Use the " +
+      "`rule_catalog` tool for any catalog edits — sandbox_exec bypasses the " +
+      "workspace file lock and races with parallel workers."
+    ];
+    parts.push(
+      `### Progress (rule-id coverage, D2)\n` +
+      `- Total rules in catalog: ${total}\n` +
+      `- Rule ids covered by some skill: ${covered}\n` +
+      `- Skill directories authored: ${this.skillsAuthored.length}\n` +
+      `- Skills with scripts/: ${this.skillsWithScripts.length}` +
+      (uncovered.length > 0
+        ? `\n- Missing coverage (${uncovered.length}): ${uncovered.slice(0, 15).join(", ")}${uncovered.length > 15 ? "…" : ""}`
+        : ""),
+    );
 
     if (this.exitCriteriaMet()) {
-      parts.push("### Exit\nAll rules have skills. Proceed to SKILL_TESTING.");
+      parts.push("### Exit\nAll rule ids are covered by some skill. Proceed to SKILL_TESTING.");
     }
     return parts.join("\n\n");
   }
@@ -75,7 +161,15 @@ export class SkillAuthoringPipeline extends Pipeline {
 
   exitCriteriaMet() {
     if (!this.totalRules.length) return false;
-    return this.skillsAuthored.length >= this.totalRules.length && this.skillsWithScripts.length >= this.skillsAuthored.length * 0.5;
+    // D2: exit requires distinct rule-id coverage, not skill-dir count.
+    // Original heuristic (skillsAuthored >= totalRules) passed the phase
+    // even when KC grouped many rules into one file — a false signal when
+    // the user wants per-rule verification. Now every rule id in the
+    // catalog must appear in some skill name. The scripts/ heuristic is
+    // preserved as a secondary gate on skill depth.
+    const allCovered = this.totalRules.every((r) => this.ruleIdsCovered.has(r));
+    if (!allCovered) return false;
+    return this.skillsWithScripts.length >= Math.max(1, this.skillsAuthored.length * 0.5);
   }
 
   exportState() {

package/src/agent/skill-loader.js

@@ -5,6 +5,46 @@ import { fileURLToPath } from "node:url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLED_SKILLS_DIR = path.resolve(__dirname, "../../template/skills");
 
+// D3b: Phase-relevance map. Skills not listed here are always visible
+// (safe default for future additions). Skills listed here are only
+// included in the context index for the named phases — unrelated
+// phases save the system-prompt budget. This is a soft filter: the
+// agent can still `workspace_file` read any skill on-demand.
+//
+// Keep this close to the skill set it describes — one hardcoded table
+// per release, not spread across files. When adding a skill to
+// template/skills/, add it here if phase-specific, or leave it out
+// to default to always-visible.
+const PHASE_RELEVANT_SKILLS = {
+  "bootstrap-workspace": ["bootstrap"],
+  "rule-extraction":     ["bootstrap", "extraction"],
+  "rule-graph":          ["extraction", "skill_authoring"],
+  "task-decomposition":  ["extraction", "skill_authoring", "distillation"],
+  "skill-authoring":     ["skill_authoring", "skill_testing"],
+  "skill-to-workflow":   ["distillation"],
+  "evolution-loop":      ["skill_testing", "distillation", "production_qc"],
+  "version-control":     ["bootstrap", "extraction", "skill_authoring", "skill_testing", "distillation", "production_qc", "finalization"],
+  "quality-control":     ["production_qc", "finalization"],
+  "confidence-system":   ["distillation", "production_qc"],
+  "dashboard-reporting": ["production_qc", "finalization"],
+  "cross-document-verification": ["production_qc"],
+  "corner-case-management": ["skill_testing", "distillation", "production_qc"],
+  "data-sensibility":    ["extraction", "skill_authoring"],
+  "entity-extraction":   ["skill_authoring", "distillation"],
+  "document-parsing":    ["bootstrap", "extraction", "skill_authoring"],
+  "document-chunking":   ["bootstrap", "extraction"],
+  "tree-processing":     ["skill_authoring", "skill_testing"],
+  "compliance-judgment": ["skill_authoring", "skill_testing", "production_qc"],
+  "skill-creator":       ["skill_authoring"],
+};
+
+function isSkillRelevantToPhase(skillName, phase) {
+  const relevantPhases = PHASE_RELEVANT_SKILLS[skillName];
+  if (!relevantPhases) return true; // unknown skill → always visible
+  if (!phase) return true; // caller didn't pass phase → always visible
+  return relevantPhases.includes(phase);
+}
+
 /**
  * Discover and index meta skills from template/skills/.
  * Follows Claude Code's pattern: skills are NOT dumped into the system prompt.
@@ -79,15 +119,25 @@ export class SkillLoader {
   /**
    * Format the skill index for injection into agent context.
    * Brief listing — agent reads full content on demand.
+   *
+   * D3b: when `phase` is provided, filter out skills that aren't relevant
+   * to the phase (per PHASE_RELEVANT_SKILLS). Unknown skills stay visible
+   * so new additions to template/skills/ aren't accidentally hidden.
+   *
+   * @param {string} [phase] - Current engine phase for filtering
    * @returns {string}
    */
-  formatForContext() {
+  formatForContext(phase) {
     const index = this.getIndex();
     if (index.length === 0) return "";
 
-    const metaMeta = index.filter((s) => s.category === "meta-meta");
-    const meta = index.filter((s) => s.category === "meta");
-    const other = index.filter((s) => s.category !== "meta-meta" && s.category !== "meta");
+    const visible = phase
+      ? index.filter((s) => isSkillRelevantToPhase(s.name, phase))
+      : index;
+
+    const metaMeta = visible.filter((s) => s.category === "meta-meta");
+    const meta = visible.filter((s) => s.category === "meta");
+    const other = visible.filter((s) => s.category !== "meta-meta" && s.category !== "meta");
 
     const lines = ["## Available Methodology Skills",
       "Read full skill content from the skills/ directory when needed.\n"];