kc-beta 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kc-beta",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "KC Agent — LLM document verification agent (pure Node.js CLI)",
   "type": "module",
   "bin": {

package/src/agent/context.js

@@ -1,122 +1,92 @@
 const AGENT_IDENTITY = `\
-You are KC Agent, a document verification coding agent. You help users build \
-and manage document verification systems for financial institutions.
+KC Agent builds and manages document verification systems for financial institutions.
 
-You are direct and technical. You think step by step. When you don't know \
-something, you say so.
+## Architecture
 
-## Tools
+This system operates in two modes:
 
-You have the following tools:
+**BUILD mode** (Bootstrap → Extraction → Skill Authoring → Skill Testing): \
+Read regulations, extract rules, build verification skills, test them against samples. \
+All intellectual work — parsing, extracting, judging — is done directly. The results \
+produced in this mode serve as the accuracy baseline. Worker LLM tools are not available \
+in this mode.
 
-- **sandbox_exec**: Execute shell commands in your workspace directory. Use this \
-to run Python scripts, install packages, list files, etc. Pipes and redirects work.
+**DISTILL mode** (Distillation → Production QC): \
+Convert proven skills into workflows that run with cheaper worker LLMs at scale. \
+Test workflow results against the baseline established in BUILD mode. Monitor production \
+quality. Worker LLM tools become available in this mode.
 
-- **workspace_file**: Read, write, or list files in your workspace. Operations: \
-read (path), write (path + content), list (optional path).
+Skills are first-class deliverables, not just stepping stones to distillation. When a \
+verification task is too complex for worker LLMs, the skill itself — run by a capable \
+agent — is the production solution.
 
-- **document_parse**: Parse documents (PDF, DOCX, images) and extract text. \
-Internally uses an escalation chain: text extraction → API parser → OCR models. \
-Starts cheap, escalates if needed. You don't choose the method — the tool handles it. \
-Use force_method only for testing or if the developer user requests a specific parser.
-
-- **worker_llm_call**: Call a worker LLM at a specified tier (tier1=most capable, \
-tier4=cheapest). Use for distillation testing — check if cheaper models can handle \
-extraction/judgment steps. Returns response with model used and token counts.
-
-- **workflow_run**: Execute a distilled workflow against a document. Automatically \
-attaches confidence scores and trace IDs. Results saved to output/results/.
-
-- **tier_downgrade**: Test a workflow step at a lower tier. Compares accuracy at \
-target tier vs. current baseline. Recommends downgrade if accuracy stays above threshold.
+## Methodology
 
-- **evolution_cycle**: Run one diagnose-classify-fix iteration. Classifies failures \
-as systemic (>threshold) or corner case (<threshold). Routes corner cases to registry \
-automatically. Checks for repeated failure patterns across iterations.
+### Document Parsing
+Start with the simplest parser and escalate only when output is insufficient. Once a \
+parser works for a document type, lock it in. Tables and charts may need specific handling.
 
-- **document_search**: Search for text across workspace documents. Supports plain text \
-and regex. Returns matching passages with file path and line number.
+### Rule Extraction
+Decompose regulations top-down into atomic, testable rules. One rule = one pass/fail \
+outcome. Handle ambiguity explicitly — note it, ask the developer user. After extraction, \
+audit which regulation sections are not yet covered.
 
-- **rule_catalog**: CRUD on the rule registry. Enforces required fields (id, source_ref, \
-description). Operations: create, read, update, delete, list.
+### Entity Extraction
+Prefer regex/Python for predictable formats. Use LLM only when semantic understanding \
+is required. Every extraction captures: value, evidence, source location, confidence, \
+method used.
 
-- **qc_sample**: Draw adaptive sample from production results for review. Stratifies \
-by confidence band. All low-confidence reviewed, medium sampled, high spot-checked.
+### Skill Authoring
+Write each rule into a skill folder following the Anthropic skill-creator format. A \
+skill must be self-contained: business logic, scripts, references, sample data, and \
+corner cases. Skills capture methodology — when to use an approach, why it works, \
+what to watch for.
 
-- **dashboard_render**: Generate a self-contained HTML dashboard from project metrics. \
-Shows rules, confidence distribution, evolution history, QC results.
+### Evolution Loop
+Test → observe → diagnose root cause (parsing/extraction/judgment/scope) → classify \
+(systemic vs corner case) → fix → retest → log. Corner cases are recorded separately \
+and never patched into the main workflow.
 
-- **agent_tool**: Spawn a sub-agent for independent parallel work. Give it a complete \
-task description — it has no context from your conversation. Sub-agent writes results \
-to sub_agents/{task_id}/. Use for parallel rule testing, batch processing, etc.
+### Distillation
+Design workflows that replicate skill results using the cheapest viable model tier. \
+Test at each tier and present accuracy comparison data. The developer user decides \
+acceptable trade-offs between cost and accuracy.
 
-Use tools to do real work. Write code to files, then run it. Check results by \
-reading output. Don't guess — verify.
+## Structural Components
 
-## Methodology
+**Version control**: Every write to rules/, workflows/, or rule_skills/ gets a trace \
+ID in versions.json — an immutable audit trail linking results back to the exact \
+version of code that produced them.
 
-### Document Parsing
-- Start with the simplest parser (text extraction). Escalate to OCR/vision only \
-when output is empty or garbled (<50 chars/page). Simple parsers fail less.
-- Once a parser works for a document type, lock it in. Don't re-evaluate unless \
-downstream extraction fails.
-- Tables need special handling — extract cell-by-cell, reconstruct as markdown or JSON.
-
-### Data Sensibility
-- Read 3-5 complete documents end-to-end BEFORE writing extraction logic. Read raw \
-parsed text, not PDF viewer. This saves hours of debugging bad assumptions.
-- After extraction, spot-check 10 random fields (3 high-confidence, 4 medium, \
-3 low) against source. If >1 out of 10 is wrong, STOP — don't continue.
-- Save every processing stage to disk (raw text → sections → entities → judgments). \
-Disk is cheap; debugging without intermediates is guesswork.
+**Corner case registry**: Edge cases (<10% failure rate) are stored in \
+corner_cases.json with detection patterns and resolutions. They are handled separately \
+during execution with high-threshold matching, not patched into main workflows.
 
-### Rule Extraction
-- One rule = one pass/fail outcome. If a rule can produce two independent results, \
-split it. Rules must be self-contained and scoped to where in the document to look.
-- Work top-down (onion peeler): major areas → chapters → sections → atomic rules. \
-Stop when rules are atomic and testable.
-- Handle ambiguity explicitly. Extract as understood, note ambiguities, ask the \
-developer user. Ambiguous rules are often the most important — don't skip them.
-- After extraction, audit coverage: which regulation paragraphs are NOT covered?
+**Confidence scoring**: Each verification result gets a composite confidence score \
+based on extraction method, source text presence, historical accuracy, and corner \
+case proximity. Confidence bands (high/medium/low) drive QC sampling rates.
 
-### Entity Extraction
-- Method selection: regex/Python first (free, instant, predictable formats). LLM \
-only when semantic understanding is required. Hybrid: regex first, LLM fallback.
-- Every extraction must capture: value, evidence (raw text), source location, \
-confidence, method used.
-- Postprocessing is deterministic code: date standardization, unit conversion, \
-Chinese numeral conversion. Build as reusable Python functions.
+## Working with the Developer User
 
-### Evolution Loop
-- The cycle: test → observe → diagnose → classify → fix → retest → log.
-- Diagnose root cause into: parsing failure, extraction failure, judgment failure, \
-or scope failure. Each drives different fixes.
-- Systemic issue (>10% of docs) → rewrite code/prompts. Corner case (<10%) → \
-record in corner_cases.json with detection + resolution. Do NOT patch main \
-workflow for corner cases.
-- Stop when: accuracy meets threshold, or correction volume <5% and no new \
-failure patterns.
-
-### Reflection & Skill Writing
-- When you solve a hard problem (OCR approach, extraction pattern, edge case \
-handling), write it down as a reusable skill in rule_skills/. Future sessions \
-and rules benefit from your discoveries.
-- Skills capture methodology, not just code. Describe WHEN to use this approach, \
-WHY it works, and WHAT to watch out for.`;
+The developer user configures the project, provides regulations and samples, and \
+makes business decisions (accuracy thresholds, cost trade-offs, rule scope). Discuss \
+unclear regulations with them. Present results and let them judge.`;
 
 /**
  * Builds the system prompt from multiple context sources.
- * Combines: agent identity + methodology + pipeline state + workspace state.
+ * Combines: agent identity + skill index + pipeline state + workspace state.
  */
 export class ContextAssembler {
   /**
    * @param {object} [opts]
    * @param {string} [opts.pipelineState]
    * @param {string} [opts.workspaceState]
+   * @param {string} [opts.skillIndex] - Brief index of available meta skills
    * @returns {string}
    */
-  build({ pipelineState, workspaceState } = {}) {
+  build({ pipelineState, workspaceState, skillIndex } = {}) {
     const parts = [AGENT_IDENTITY];
+    if (skillIndex) parts.push(skillIndex);
     if (pipelineState) parts.push(pipelineState);
     if (workspaceState) parts.push(workspaceState);
     return parts.join("\n\n");

package/src/agent/engine.js

@@ -18,6 +18,7 @@ import { DashboardRenderTool } from "./tools/dashboard-render.js";
 import { EvolutionCycleTool } from "./tools/evolution-cycle.js";
 import { TierDowngradeTool } from "./tools/tier-downgrade.js";
 import { AgentTool } from "./tools/agent-tool.js";
+import { SkillLoader } from "./skill-loader.js";
 import { Phase } from "./pipelines/index.js";
 import { ProjectInitializer } from "./pipelines/initializer.js";
 import { RuleExtractionPipeline } from "./pipelines/extraction.js";
@@ -26,13 +27,16 @@ import { SkillTestingPipeline } from "./pipelines/skill-testing.js";
 import { DistillationEngine as DistillationPipeline } from "./pipelines/distillation.js";
 import { ProductionQCPipeline } from "./pipelines/production-qc.js";
 
+// Phases where worker LLM tools are available (DISTILL mode)
+const DISTILL_PHASES = new Set([Phase.DISTILLATION, Phase.PRODUCTION_QC]);
+
 /**
  * The KC Agent conversation engine.
  *
  * Core loop: user message -> context assembly -> LLM API (streaming) ->
  * tool execution (if any) -> repeat until no tool calls -> turn complete.
  *
- * Uses OpenAI-compatible API. Yields AgentEvent objects.
+ * Tools are phase-gated: worker LLM tools only available in DISTILL mode.
  */
 export class AgentEngine {
   /**
@@ -45,7 +49,6 @@ export class AgentEngine {
     this.client = client;
     this.config = config;
     this.context = new ContextAssembler();
-    this.toolRegistry = new ToolRegistry();
 
     // Workspace + structural components
     this.workspace = new Workspace(config.kcWorkspaceRoot, sessionId);
@@ -54,30 +57,8 @@ export class AgentEngine {
     this.cornerCases = new CornerCaseRegistry(this.workspace.cwd);
     this.confidence = new ConfidenceScorer(this.workspace.cwd, this.cornerCases);
 
-    // Register tools
-    this.toolRegistry.register(new SandboxExecTool(this.workspace, config.kcExecTimeout));
-    this.toolRegistry.register(new WorkspaceFileTool(this.workspace, this.versionManager));
-    this.toolRegistry.register(new DocumentParseTool(this.workspace, {
-      mineruApiUrl: config.mineruApiUrl,
-      mineruApiKey: config.mineruApiKey,
-      siliconflowApiKey: config.siliconflowApiKey,
-      siliconflowBaseUrl: config.siliconflowBaseUrl,
-      ocrModel: config.ocrModelTier1,
-    }));
-    this.toolRegistry.register(new DocumentSearchTool(this.workspace));
-
-    const workerLlm = new WorkerLLMCallTool(this.workspace, {
-      apiKey: config.siliconflowApiKey,
-      baseUrl: config.siliconflowBaseUrl,
-    });
-    this.toolRegistry.register(workerLlm);
-    this.toolRegistry.register(new WorkflowRunTool(this.workspace, this.versionManager, this.confidence));
-    this.toolRegistry.register(new TierDowngradeTool(this.workspace, workerLlm));
-    this.toolRegistry.register(new EvolutionCycleTool(this.workspace, this.cornerCases));
-    this.toolRegistry.register(new RuleCatalogTool(this.workspace));
-    this.toolRegistry.register(new QCSampleTool(this.workspace));
-    this.toolRegistry.register(new DashboardRenderTool(this.workspace));
-    this.toolRegistry.register(new AgentTool(this.workspace, (sid) => new AgentEngine({ client, config, sessionId: sid })));
+    // Build all tool instances (but register phase-appropriate ones)
+    this._buildTools = this._createAllTools();
 
     // Pipeline system (meta-meta skills as code)
     this.currentPhase = Phase.BOOTSTRAP;
@@ -89,14 +70,70 @@ export class AgentEngine {
       [Phase.DISTILLATION]: new DistillationPipeline(this.workspace),
       [Phase.PRODUCTION_QC]: new ProductionQCPipeline(this.workspace),
     };
+
+    // Skill discovery (Claude Code pattern: index in context, full content on demand)
+    this._skillLoader = new SkillLoader(config.language);
+
+    // Register tools for initial phase
+    this.toolRegistry = new ToolRegistry();
+    this._registerToolsForPhase(this.currentPhase);
   }
 
   /**
-   * Register additional tools (called after construction for tools that need extra deps).
-   * @param {import('./tools/base.js').BaseTool} tool
+   * Create all tool instances. Separated from registration so we can
+   * re-register per phase without recreating.
    */
-  registerTool(tool) {
-    this.toolRegistry.register(tool);
+  _createAllTools() {
+    const workerLlm = new WorkerLLMCallTool(this.workspace, {
+      apiKey: this.config.siliconflowApiKey,
+      baseUrl: this.config.siliconflowBaseUrl,
+    });
+
+    return {
+      // Always available (BUILD + DISTILL)
+      core: [
+        new SandboxExecTool(this.workspace, this.config.kcExecTimeout),
+        new WorkspaceFileTool(this.workspace, this.versionManager),
+        new DocumentParseTool(this.workspace, {
+          mineruApiUrl: this.config.mineruApiUrl,
+          mineruApiKey: this.config.mineruApiKey,
+          siliconflowApiKey: this.config.siliconflowApiKey,
+          siliconflowBaseUrl: this.config.siliconflowBaseUrl,
+          ocrModel: this.config.ocrModelTier1,
+        }),
+        new DocumentSearchTool(this.workspace),
+        new RuleCatalogTool(this.workspace),
+        new EvolutionCycleTool(this.workspace, this.cornerCases),
+        new DashboardRenderTool(this.workspace),
+        new AgentTool(this.workspace, (sid) => new AgentEngine({
+          client: this.client, config: this.config, sessionId: sid,
+        })),
+      ],
+      // Distillation+ only (DISTILL mode)
+      distill: [
+        workerLlm,
+        new WorkflowRunTool(this.workspace, this.versionManager, this.confidence),
+        new TierDowngradeTool(this.workspace, workerLlm),
+        new QCSampleTool(this.workspace),
+      ],
+    };
+  }
+
+  /**
+   * Register tools appropriate for the given phase.
+   * BUILD phases get core tools only.
+   * DISTILL phases get core + worker LLM tools.
+   */
+  _registerToolsForPhase(phase) {
+    this.toolRegistry = new ToolRegistry();
+    for (const tool of this._buildTools.core) {
+      this.toolRegistry.register(tool);
+    }
+    if (DISTILL_PHASES.has(phase)) {
+      for (const tool of this._buildTools.distill) {
+        this.toolRegistry.register(tool);
+      }
+    }
   }
 
   /**
@@ -113,6 +150,7 @@ export class AgentEngine {
     const pipelineState = pipeline?.describeState?.() || null;
 
     const systemPrompt = this.context.build({
+      skillIndex: this._skillLoader.formatForContext(),
       pipelineState,
       workspaceState: `Your workspace directory is: ${this.workspace.cwd}`,
     });
@@ -137,13 +175,11 @@ export class AgentEngine {
           const delta = chunk.choices?.[0]?.delta;
           if (!delta) continue;
 
-          // Stream text content
           if (delta.content) {
             yield new AgentEvent({ type: "text_delta", text: delta.content });
             collectedText += delta.content;
           }
 
-          // Accumulate tool calls from deltas
           if (delta.tool_calls) {
             for (const tcDelta of delta.tool_calls) {
               const idx = tcDelta.index;
@@ -158,7 +194,6 @@ export class AgentEngine {
           }
         }
 
-        // Build assistant message for history
         const assistantMsg = { role: "assistant", content: collectedText || null };
         if (toolCallsAcc.size > 0) {
           assistantMsg.tool_calls = Array.from(toolCallsAcc.values()).map((tc) => ({
@@ -169,7 +204,6 @@ export class AgentEngine {
         }
         this.history.addRaw(assistantMsg);
 
-        // No tool calls → turn complete
         if (toolCallsAcc.size === 0) {
           yield new AgentEvent({ type: "turn_complete" });
           return;
@@ -180,7 +214,7 @@ export class AgentEngine {
           let inputData = {};
           try {
             inputData = tc.arguments ? JSON.parse(tc.arguments) : {};
-          } catch { /* ignore parse errors */ }
+          } catch { /* ignore */ }
 
           yield new AgentEvent({ type: "tool_start", name: tc.name, input: inputData });
           const result = await this.toolRegistry.execute(tc.name, inputData);
@@ -191,19 +225,19 @@ export class AgentEngine {
             isError: result.isError,
           });
 
-          // Add tool result message
           this.history.addRaw({
             role: "tool",
             tool_call_id: tc.id,
             content: result.content,
           });
 
-          // Pipeline controller: update state after tool execution
+          // Pipeline controller: update state and re-register tools on phase change
           if (pipeline?.onToolResult) {
             const pEvent = pipeline.onToolResult(tc.name, inputData, result);
             if (pEvent) {
               if (pEvent.type === "phase_ready" && pEvent.nextPhase) {
                 this.currentPhase = pEvent.nextPhase;
+                this._registerToolsForPhase(this.currentPhase);
               }
               yield new AgentEvent({
                 type: "pipeline_event",
@@ -213,8 +247,6 @@ export class AgentEngine {
           }
         }
 
-        // Loop continues — send tool results back to LLM
-
       } catch (err) {
         yield new AgentEvent({ type: "error", message: err.message });
         return;

package/src/agent/pipelines/_archive_v1/distillation.js

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Phase, PipelineEvent } from "./index.js";
+import { Pipeline } from "./base.js";
+
+export class DistillationEngine extends Pipeline {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this.skillsToDistill = [];
+    this.workflowsCreated = {};
+    this.workflowsTested = {};
+    this.workflowsPassing = [];
+    this.tierAssignments = {};
+    this._workflowAccuracy = 0.9;
+    this._scanWorkspace();
+  }
+
+  _scanWorkspace() {
+    this._loadConfig();
+    this._loadSkills();
+    this._scanWorkflows();
+  }
+
+  _loadConfig() {
+    const envPath = path.join(this._workspace.cwd, ".env");
+    if (!fs.existsSync(envPath)) return;
+    for (const line of fs.readFileSync(envPath, "utf-8").split("\n")) {
+      if (line.startsWith("WORKFLOW_ACCURACY=")) try { this._workflowAccuracy = parseFloat(line.split("=")[1]); } catch { /* skip */ }
+    }
+  }
+
+  _loadSkills() {
+    this.skillsToDistill = [];
+    const dir = path.join(this._workspace.cwd, "rule_skills");
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory() && !e.name.startsWith("__")) this.skillsToDistill.push(e.name);
+    }
+  }
+
+  _scanWorkflows() {
+    this.workflowsCreated = {};
+    this.workflowsTested = {};
+    this.workflowsPassing = [];
+    this.tierAssignments = {};
+    const wfDir = path.join(this._workspace.cwd, "workflows");
+    if (!fs.existsSync(wfDir)) return;
+
+    for (const e of fs.readdirSync(wfDir, { withFileTypes: true })) {
+      if (e.isDirectory()) {
+        const ruleDir = path.join(wfDir, e.name);
+        const pyFiles = fs.readdirSync(ruleDir).filter((f) => f.endsWith(".py"));
+        if (pyFiles.length > 0) this.workflowsCreated[e.name] = pyFiles.length;
+        const cfgPath = path.join(ruleDir, "config.json");
+        if (fs.existsSync(cfgPath)) {
+          try {
+            const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
+            if (cfg.tier) this.tierAssignments[e.name] = cfg.tier;
+            if (cfg.accuracy != null) {
+              const acc = parseFloat(cfg.accuracy);
+              this.workflowsTested[e.name] = acc;
+              if (acc >= this._workflowAccuracy) this.workflowsPassing.push(e.name);
+            }
+          } catch { /* skip */ }
+        }
+      } else if (e.isFile() && e.name.endsWith(".py")) {
+        this.workflowsCreated[path.parse(e.name).name] = 1;
+      }
+    }
+  }
+
+  describeState() {
+    this._scanWorkspace();
+    const total = this.skillsToDistill.length;
+    const created = Object.keys(this.workflowsCreated).length;
+    const passing = this.workflowsPassing.length;
+    const parts = ["## Current Phase: DISTILLATION"];
+    parts.push(`### Progress\n- Skills to distill: ${total}\n- Workflows created: ${created}\n- Workflows passing (>=${this._workflowAccuracy}): ${passing}`);
+
+    if (this.exitCriteriaMet()) {
+      parts.push("### Ready\nAll workflows passing. Proceed to PRODUCTION_QC.");
+    } else if (created === 0) {
+      parts.push("### What to do now\nConvert proven skills into worker LLM workflows.\nFor each skill: write workflow script, write prompts, test vs ground truth, tier-downgrade test.");
+    } else {
+      const notCreated = this.skillsToDistill.filter((s) => !(s in this.workflowsCreated));
+      const notPassing = Object.keys(this.workflowsCreated).filter((s) => !this.workflowsPassing.includes(s));
+      let guidance = "### What to do now\n";
+      if (notCreated.length) guidance += `Create workflows for: ${notCreated.slice(0, 10).join(", ")}\n`;
+      if (notPassing.length) guidance += `Improve accuracy for: ${notPassing.slice(0, 10).join(", ")}\n`;
+      parts.push(guidance);
+    }
+    return parts.join("\n\n");
+  }
+
+  onToolResult(toolName, toolInput, result) {
+    if (result.isError) return null;
+    const wasReady = this.exitCriteriaMet();
+    if (toolName === "workspace_file" && ((toolInput.path || "").includes("workflows/") || (toolInput.path || "").includes("output/"))) {
+      this._scanWorkflows();
+    }
+    if (!wasReady && this.exitCriteriaMet()) {
+      return new PipelineEvent({ type: "phase_ready", message: "Distillation complete. Ready for PRODUCTION_QC.", nextPhase: Phase.PRODUCTION_QC });
+    }
+    return null;
+  }
+
+  exitCriteriaMet() {
+    const total = this.skillsToDistill.length;
+    if (!total) return false;
+    return Object.keys(this.workflowsCreated).length >= total && this.workflowsPassing.length >= total;
+  }
+}

package/src/agent/pipelines/_archive_v1/extraction.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Phase, PipelineEvent } from "./index.js";
+import { Pipeline } from "./base.js";
+
+export class RuleExtractionPipeline extends Pipeline {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this.regulationsScanned = false;
+    this.rulesExtracted = [];
+    this.rulesWithTests = [];
+    this.coverageAudited = false;
+    this._scanWorkspace();
+  }
+
+  _scanWorkspace() {
+    const rulesDir = path.join(this._workspace.cwd, "rules");
+    if (fs.existsSync(rulesDir)) {
+      const regFiles = fs.readdirSync(rulesDir).filter((f) => !f.endsWith(".json") && fs.statSync(path.join(rulesDir, f)).isFile());
+      this.regulationsScanned = regFiles.length > 0;
+    }
+    this._scanRules();
+    this._scanTests();
+    this.coverageAudited = fs.existsSync(path.join(this._workspace.cwd, "rules", "coverage_audit.md")) ||
+                           fs.existsSync(path.join(this._workspace.cwd, "rules", "coverage_audit.json"));
+  }
+
+  _scanRules() {
+    this.rulesExtracted = [];
+    const catalogPath = path.join(this._workspace.cwd, "rules", "catalog.json");
+    if (fs.existsSync(catalogPath)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+        if (Array.isArray(data)) this.rulesExtracted = data.map((r, i) => r.id || `rule_${i}`);
+      } catch { /* skip */ }
+    }
+    const skillsDir = path.join(this._workspace.cwd, "rule_skills");
+    if (fs.existsSync(skillsDir)) {
+      for (const e of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (e.isDirectory() && !e.name.startsWith("__") && !this.rulesExtracted.includes(e.name)) {
+          this.rulesExtracted.push(e.name);
+        }
+      }
+    }
+  }
+
+  _scanTests() {
+    this.rulesWithTests = [];
+    const skillsDir = path.join(this._workspace.cwd, "rule_skills");
+    if (!fs.existsSync(skillsDir)) return;
+    for (const e of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const testDir = path.join(skillsDir, e.name, "test_cases");
+      if (fs.existsSync(testDir) && fs.readdirSync(testDir).length > 0) {
+        this.rulesWithTests.push(e.name);
+      }
+    }
+  }
+
+  describeState() {
+    this._scanWorkspace();
+    const parts = ["## Current Phase: EXTRACTION"];
+    parts.push(`### Progress\n- Regulations scanned: ${this.regulationsScanned ? "yes" : "no"}\n- Rules extracted: ${this.rulesExtracted.length}\n- Rules with tests: ${this.rulesWithTests.length}\n- Coverage audit: ${this.coverageAudited ? "done" : "not yet"}`);
+
+    if (this.exitCriteriaMet()) {
+      parts.push("### Ready\nExtraction complete. Proceed to SKILL_AUTHORING phase.");
+    } else if (this.rulesExtracted.length === 0) {
+      parts.push("### What to do now\nDecompose regulations into atomic, testable rules.\n- One rule = one pass/fail outcome\n- Work top-down: major areas → chapters → sections → atomic rules\n- Save rules to rules/catalog.json via rule_catalog tool");
+    } else if (!this.coverageAudited) {
+      parts.push("### What to do now\nRun a coverage audit: which regulation sections are NOT covered? Save to rules/coverage_audit.md");
+    }
+    return parts.join("\n\n");
+  }
+
+  onToolResult(toolName, toolInput, result) {
+    if (result.isError) return null;
+    const wasReady = this.exitCriteriaMet();
+    if (toolName === "workspace_file" || toolName === "rule_catalog") {
+      this._scanWorkspace();
+    }
+    if (!wasReady && this.exitCriteriaMet()) {
+      return new PipelineEvent({ type: "phase_ready", message: "Extraction complete. Ready for SKILL_AUTHORING.", nextPhase: Phase.SKILL_AUTHORING });
+    }
+    return null;
+  }
+
+  exitCriteriaMet() {
+    return this.regulationsScanned && this.rulesExtracted.length > 0 &&
+      this.rulesWithTests.length >= Math.max(this.rulesExtracted.length * 0.8, 1) && this.coverageAudited;
+  }
+}