kc-beta 0.6.1 → 0.6.2

package/package.json

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

package/src/agent/engine.js

@@ -69,6 +69,19 @@ export const NEXT_PHASE = {
   [Phase.PRODUCTION_QC]: Phase.FINALIZATION, // E1: new 7th phase
 };
 
+// v0.6.2 J2: explicit linear order so `_advancePhase` can detect rollback
+// direction (target index < current index → rollback). Mirrors NEXT_PHASE
+// but ordered, plus FINALIZATION at the end as the terminal phase.
+export const PHASE_ORDER = [
+  Phase.BOOTSTRAP,
+  Phase.EXTRACTION,
+  Phase.SKILL_AUTHORING,
+  Phase.SKILL_TESTING,
+  Phase.DISTILLATION,
+  Phase.PRODUCTION_QC,
+  Phase.FINALIZATION,
+];
+
 /**
  * The KC Agent conversation engine.
  *
@@ -150,7 +163,7 @@ export class AgentEngine {
     });
 
     // Session state persistence
-    this.sessionState = new SessionState(this.workspace.cwd, { statePath });
+    this.sessionState = new SessionState(this.workspace.cwd, { statePath, workspace: this.workspace });
 
     // Task manager (ralph-loop) — sub-agents don't queue further sub-tasks,
     // so they don't get a TaskManager.
@@ -223,6 +236,11 @@ export class AgentEngine {
           historyLen: this.history?.messages?.length ?? 0,
           tasksPending: this.taskManager?.progress?.pending ?? 0,
           tasksInProgress: this.taskManager?.progress?.inProgress ?? 0,
+          // v0.6.2 K1: per-component breakdown so heap-analyze.js can
+          // attribute growth (history vs subagents vs event log vs cache).
+          // All values in MB. Failures inside _sampleComponents are caught
+          // and the row gets `componentsErr` instead.
+          components: this._sampleComponents(),
         };
         fs.mkdirSync(logDir, { recursive: true });
         fs.appendFileSync(logPath, JSON.stringify(row) + "\n", "utf-8");
@@ -240,6 +258,89 @@ export class AgentEngine {
     };
   }
 
+  /**
+   * v0.6.2 K1: per-component heap accounting. Each value is in MB,
+   * rounded. The whole function is wrapped in a single try/catch by the
+   * caller; failures are silently dropped to keep the sampler diagnostic
+   * (never load-bearing).
+   *
+   * Components measured (by source):
+   *  - history: in-memory `this.history.messages` content sizes (sum of
+   *    JSON-stringified content)
+   *  - eventLog: disk size of `logs/events.jsonl`
+   *  - toolResults: disk size of `logs/tool_results/` (offloaded tool
+   *    output, summed top-level files only — the dir is one level deep)
+   *  - subagents: disk size of `sub_agents/` (one level — each subagent
+   *    has its own directory tree but we just want the order of magnitude)
+   *  - bundleCache: disk size of `cache/bundles/`
+   */
+  _sampleComponents() {
+    const out = { historyMB: 0, eventLogMB: 0, toolResultsMB: 0, subagentsMB: 0, bundleCacheMB: 0 };
+    const cwd = this.workspace?.cwd;
+    if (!cwd) return out;
+    // history: walk messages, sum content string lengths (UTF-16 → bytes
+    // approx 2× length; we conservatively count length itself since most
+    // content is ASCII-heavy JSON tool output)
+    try {
+      const msgs = this.history?.messages || [];
+      let bytes = 0;
+      for (const m of msgs) {
+        const c = m?.content;
+        if (typeof c === "string") bytes += c.length;
+        else if (Array.isArray(c)) {
+          for (const part of c) {
+            if (typeof part === "string") bytes += part.length;
+            else if (part?.text) bytes += String(part.text).length;
+            else if (part?.content) bytes += String(part.content).length;
+            else if (part?.input) bytes += JSON.stringify(part.input).length;
+          }
+        } else if (c && typeof c === "object") {
+          bytes += JSON.stringify(c).length;
+        }
+      }
+      out.historyMB = Math.round(bytes / 1024 / 1024);
+    } catch { /* skip */ }
+    // events.jsonl — single file size
+    try {
+      const p = path.join(cwd, "logs", "events.jsonl");
+      out.eventLogMB = Math.round(fs.statSync(p).size / 1024 / 1024);
+    } catch { /* skip */ }
+    // logs/tool_results/ — sum file sizes one level deep (it's flat)
+    try {
+      const dir = path.join(cwd, "logs", "tool_results");
+      let total = 0;
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (e.isFile()) {
+          try { total += fs.statSync(path.join(dir, e.name)).size; } catch { /* skip */ }
+        }
+      }
+      out.toolResultsMB = Math.round(total / 1024 / 1024);
+    } catch { /* skip */ }
+    // sub_agents/ — sum top-level entries (each is a dir, statSync returns
+    // dir-block size, not contents — that's fine for an order-of-magnitude
+    // signal; recursive walk would be too expensive for the sampler)
+    try {
+      const dir = path.join(cwd, "sub_agents");
+      let total = 0;
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        try { total += fs.statSync(path.join(dir, e.name)).size; } catch { /* skip */ }
+      }
+      out.subagentsMB = Math.round(total / 1024 / 1024);
+    } catch { /* skip */ }
+    // cache/bundles/
+    try {
+      const dir = path.join(cwd, "cache", "bundles");
+      let total = 0;
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (e.isFile()) {
+          try { total += fs.statSync(path.join(dir, e.name)).size; } catch { /* skip */ }
+        }
+      }
+      out.bundleCacheMB = Math.round(total / 1024 / 1024);
+    } catch { /* skip */ }
+    return out;
+  }
+
   /** Stop background diagnostics. Call on graceful shutdown. */
   stop() {
     try { this._heapSamplerStop?.(); } catch { /* ignore */ }
@@ -280,6 +381,14 @@ export class AgentEngine {
         new PhaseAdvanceTool(
           (to, reason, opts) => this._advancePhase(to, reason, opts),
           () => this.currentPhase, // H1: tool reads phase BEFORE its own call
+          // v0.6.2 J1: surface running subagents so the tool can refuse
+          // advance until the agent explicitly acknowledges them.
+          () => {
+            try {
+              const agentTool = this._buildTools?.core?.find((t) => t?.name === "agent_tool");
+              return agentTool?.getRunningTaskIds?.() || [];
+            } catch { return []; }
+          },
         ),
         new DocumentParseTool(this.workspace, {
           mineruApiUrl: this.config.mineruApiUrl,
@@ -1061,14 +1170,23 @@ export class AgentEngine {
       return false;
     }
 
+    // v0.6.2 J2: detect rollback direction. PHASE_ORDER is a linear array
+    // of all phases; if target index < current index, this is a rollback
+    // (e.g., production_qc → skill_authoring after gates revealed gaps).
+    const fromIdx = PHASE_ORDER.indexOf(this.currentPhase);
+    const toIdx = PHASE_ORDER.indexOf(nextPhase);
+    const direction = (fromIdx >= 0 && toIdx >= 0 && toIdx < fromIdx)
+      ? "rollback" : "forward";
+
     // v0.6.1 B1: build engine-appended hard-counts block + heuristic mismatch
     // detection so the LLM-narrated reason can be cross-checked against
     // ground-truth telemetry. Phase summaries become diagnostic, not just
     // narrative.
     const engineCounts = this._buildEngineCountsBlock(this.currentPhase);
     const mismatchPrefix = this._detectSummaryMismatch(reason, this.currentPhase) ? "⚠️ POSSIBLE MISMATCH: " : "";
+    const directionTag = direction === "rollback" ? " [ROLLBACK]" : "";
     const phaseSummary =
-      `[${this.currentPhase.toUpperCase()} → ${nextPhase.toUpperCase()}]: ${mismatchPrefix}${reason}` +
+      `[${this.currentPhase.toUpperCase()} → ${nextPhase.toUpperCase()}]${directionTag}: ${mismatchPrefix}${reason}` +
       (force && nextPhase !== expected ? " (forced)" : "") +
       (engineCounts ? `\n  (engine) ${engineCounts}` : "");
     this._phaseSummaries.push(phaseSummary);
@@ -1076,6 +1194,7 @@ export class AgentEngine {
       from: this.currentPhase,
       to: nextPhase,
       reason,
+      direction,
       engineCounts: engineCounts || null,
       possibleMismatch: !!mismatchPrefix,
       forced: force && nextPhase !== expected,
@@ -1085,6 +1204,17 @@ export class AgentEngine {
     this._registerToolsForPhase(this.currentPhase);
     this.workspace.setPhase(this.currentPhase);
     this._createTasksForPhase(this.currentPhase);
+
+    // v0.6.2 J2: on rollback, reset the rolled-FROM phase's lastReady
+    // edge-trigger so that if the agent revisits it and re-flips
+    // exit-criteria true, _maybeAutoAdvance will fire correctly. Without
+    // this, the auto-advance edge trigger stays latched true and the
+    // moment the agent returns to fromPhase the engine immediately
+    // bounces them back out — defeating the rollback.
+    if (direction === "rollback" && this._lastReady) {
+      this._lastReady[fromPhase] = false;
+    }
+
     this.saveState();
 
     // B8: Soft signal — surface any sub-agents left running from the prior

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

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { Phase, PipelineEvent } from "./index.js";
 import { Pipeline } from "./base.js";
+import { SkillValidator } from "../skill-validator.js";
 
 export class SkillAuthoringPipeline extends Pipeline {
   /**
@@ -16,6 +17,13 @@ export class SkillAuthoringPipeline extends Pipeline {
     super();
     this._workspace = workspace;
     this._taskManager = taskManager;
+    // v0.6.2 I2: skill validator catches malformed check_r###.py at the
+    // skill_authoring exit boundary instead of silently passing the
+    // phase and breaking in production_qc (E2E #4 unified_qc.py
+    // SyntaxError went undiagnosed for hours).
+    this._validator = new SkillValidator();
+    this._validationFailures = [];
+    this._validationSkipped = false;
     this.totalRules = [];
     this.skillsAuthored = [];
     this.skillsWithScripts = [];
@@ -152,6 +160,18 @@ export class SkillAuthoringPipeline extends Pipeline {
           (failedT > 0 ? ` (+${failedT} failed)` : "");
       }
     }
+    // v0.6.2 I2: validation status (only meaningful after first
+    // exitCriteriaMet call populates _validationFailures)
+    let validationLine = "";
+    if (this._validationSkipped) {
+      validationLine = `\n- Skill validation: SKIPPED (python3 not on PATH — install to enable)`;
+    } else if (this._validationFailures.length > 0) {
+      const f = this._validationFailures.slice(0, 5).map(({ filePath, error }) =>
+        `\n  - ${path.relative(this._workspace.cwd, filePath)}: ${error.split("\n")[0]}`,
+      ).join("");
+      validationLine = `\n- Skills failing validation (${this._validationFailures.length}):${f}` +
+        (this._validationFailures.length > 5 ? `\n  - … and ${this._validationFailures.length - 5} more` : "");
+    }
     parts.push(
       `### Progress (rule-id coverage, D2)\n` +
       `- Total rules in catalog: ${total}\n` +
@@ -159,6 +179,7 @@ export class SkillAuthoringPipeline extends Pipeline {
       `- Skill directories authored: ${this.skillsAuthored.length}\n` +
       `- Skills with scripts/: ${this.skillsWithScripts.length}` +
       taskLine +
+      validationLine +
       (uncovered.length > 0
         ? `\n- Missing coverage (${uncovered.length}): ${uncovered.slice(0, 15).join(", ")}${uncovered.length > 15 ? "…" : ""}`
         : ""),
@@ -204,9 +225,43 @@ export class SkillAuthoringPipeline extends Pipeline {
         if (completed + failed < total) return false;
       }
     }
+    // v0.6.2 I2: skill validator — every check_r###.py must parse and
+    // expose an entry point. Catches the unified_qc.py-style monolith
+    // and other malformed scripts before they break in production_qc.
+    // mtime cache keeps this O(1) in steady state. Failures preserved
+    // in this._validationFailures for describeState rendering.
+    const checkFiles = this._collectCheckScripts();
+    const v = this._validator.validateAll(checkFiles);
+    this._validationFailures = v.failures;
+    this._validationSkipped = v.skipped;
+    if (!v.ok) return false;
     return this.skillsWithScripts.length >= Math.max(1, this.skillsAuthored.length * 0.5);
   }
 
+  /**
+   * v0.6.2 I2: gather every check_r###.py path under rule_skills/. Used by
+   * the skill validator. Walks one level into each skill directory.
+   */
+  _collectCheckScripts() {
+    const out = [];
+    const dir = path.join(this._workspace.cwd, "rule_skills");
+    if (!fs.existsSync(dir)) return out;
+    const walk = (d) => {
+      let entries;
+      try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+      for (const e of entries) {
+        if (e.name.startsWith(".") || e.name.startsWith("__")) continue;
+        const p = path.join(d, e.name);
+        if (e.isDirectory()) { walk(p); continue; }
+        if (e.isFile() && /^check_r[\d_-]+\.py$/i.test(e.name)) {
+          out.push(p);
+        }
+      }
+    };
+    walk(dir);
+    return out;
+  }
+
   exportState() {
     return {
       totalRules: this.totalRules,

package/src/agent/session-state.js

@@ -12,9 +12,14 @@ export class SessionState {
    * @param {string} workspacePath - Session workspace directory
    * @param {object} [opts]
    * @param {string} [opts.statePath] - Override absolute path (used for sub-agent isolation, Bug 2)
+   * @param {Workspace} [opts.workspace] - v0.6.2 J3: optional workspace ref so
+   *   save() can acquire a sync file lock on session-state.json. Without it
+   *   (subagents, tests), save() falls back to lock-free writes — same
+   *   behavior as pre-v0.6.2.
    */
   constructor(workspacePath, opts = {}) {
     this._path = opts.statePath || path.join(workspacePath, "session-state.json");
+    this._workspace = opts.workspace || null;
   }
 
   /**
@@ -46,7 +51,18 @@ export class SessionState {
       pipelineMilestones: this._extractMilestones(engine.pipelines),
     };
 
-    fs.writeFileSync(this._path, JSON.stringify(state, null, 2), "utf-8");
+    // v0.6.2 J3: acquire sync file lock if workspace ref available.
+    // session-state.json is in SHARED_COORDINATION_PATHS — concurrent
+    // writers (parallel ralph-loop workers + main saveState ticks)
+    // could otherwise interleave and corrupt the JSON.
+    const write = () => {
+      fs.writeFileSync(this._path, JSON.stringify(state, null, 2), "utf-8");
+    };
+    if (this._workspace?.withSyncFileLock) {
+      this._workspace.withSyncFileLock("session-state.json", write);
+    } else {
+      write();
+    }
   }
 
   /**

package/src/agent/skill-validator.js

@@ -0,0 +1,149 @@
+/**
+ * v0.6.2 I2: Skill validator (was D3c, deferred from v0.6.0/v0.6.1).
+ *
+ * E2E #4 demonstrated that broken `check_r###.py` contents go undetected
+ * until production_qc throws (e.g., `SyntaxError: unexpected character
+ * after line continuation character` from line 733 of unified_qc.py).
+ * This validator catches such breakage at the skill_authoring phase
+ * boundary instead of months later in production.
+ *
+ * Design constraints:
+ *  - exitCriteriaMet is sync, so validation is sync (execFileSync).
+ *  - 110 files × ~50ms subprocess = 5.5s worst case; caching by mtime
+ *    keeps steady-state cost at ~0 (only re-validate freshly modified
+ *    files).
+ *  - Failures are diagnostic, not punitive: `force: true` on phase_advance
+ *    still bypasses. The validator's job is to refuse the auto-advance,
+ *    not to trap the agent.
+ *
+ * Validation rules per `check_r###.py`:
+ *  1. File ≥ 100 bytes (smoke test for empty stubs).
+ *  2. Passes `python3 -c "import ast; ast.parse(open(F).read())"` (no
+ *     syntax errors).
+ *  3. Defines a function reachable by name `check_rule` or `verify`
+ *     (regex match on file content).
+ *
+ * Disable mechanism: if `python3` is not on PATH, validator silently
+ * passes everything and emits a one-time warning — we don't want the
+ * gate to block on missing tooling. Gate effectively no-ops.
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const ENTRY_POINT_REGEX = /^\s*(?:async\s+)?def\s+(check_rule|verify)\b/m;
+const MIN_BYTES = 100;
+
+export class SkillValidator {
+  constructor() {
+    /** @type {Map<string, { mtime: number, ok: boolean, error?: string }>} */
+    this._cache = new Map();
+    /** @type {boolean|null} - null = untested, true/false once probed */
+    this._pythonAvailable = null;
+    /** @type {boolean} - one-time warning suppression */
+    this._warned = false;
+  }
+
+  /**
+   * Probe whether python3 is available. Cached after first call.
+   * @returns {boolean}
+   */
+  _probePython() {
+    if (this._pythonAvailable !== null) return this._pythonAvailable;
+    try {
+      execFileSync("python3", ["-c", "import ast"], { stdio: "ignore", timeout: 5000 });
+      this._pythonAvailable = true;
+    } catch {
+      this._pythonAvailable = false;
+    }
+    return this._pythonAvailable;
+  }
+
+  /**
+   * Validate one file. Returns `{ ok, error? }`. Cached by mtime.
+   * @param {string} filePath - Absolute path to the .py file
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  validateFile(filePath) {
+    let mtime;
+    try {
+      mtime = fs.statSync(filePath).mtimeMs;
+    } catch {
+      return { ok: false, error: "file not found" };
+    }
+    const cached = this._cache.get(filePath);
+    if (cached && cached.mtime === mtime) {
+      return { ok: cached.ok, error: cached.error };
+    }
+    const result = this._runValidation(filePath);
+    this._cache.set(filePath, { mtime, ...result });
+    return result;
+  }
+
+  /**
+   * Validate all files in a list. Returns:
+   *  - ok: boolean — true iff every file passes
+   *  - failures: array of { filePath, error } for each failing file
+   *  - skipped: boolean — true if python3 unavailable (validator no-op'd)
+   *
+   * @param {string[]} filePaths
+   * @returns {{ ok: boolean, failures: Array<{filePath:string, error:string}>, skipped: boolean }}
+   */
+  validateAll(filePaths) {
+    if (!this._probePython()) {
+      if (!this._warned) {
+        // eslint-disable-next-line no-console
+        console.warn("[skill-validator] python3 not on PATH — skill validation skipped. " +
+          "Phase gate will not catch syntax errors. Install python3 to enable.");
+        this._warned = true;
+      }
+      return { ok: true, failures: [], skipped: true };
+    }
+    const failures = [];
+    for (const f of filePaths) {
+      const r = this.validateFile(f);
+      if (!r.ok) failures.push({ filePath: f, error: r.error || "unknown" });
+    }
+    return { ok: failures.length === 0, failures, skipped: false };
+  }
+
+  /**
+   * Manually invalidate cache for a path — used when the caller knows
+   * the file changed but mtime granularity might not have caught it.
+   */
+  invalidate(filePath) { this._cache.delete(filePath); }
+
+  // --- Internal ---
+
+  _runValidation(filePath) {
+    // Rule 1: size check (cheap)
+    let size;
+    try { size = fs.statSync(filePath).size; }
+    catch { return { ok: false, error: "stat failed" }; }
+    if (size < MIN_BYTES) {
+      return { ok: false, error: `file too small (${size} < ${MIN_BYTES} bytes)` };
+    }
+
+    // Rule 2: ast.parse smoke test via subprocess
+    try {
+      execFileSync("python3", [
+        "-c",
+        `import ast,sys\ntry:\n ast.parse(open(${JSON.stringify(filePath)}).read())\nexcept SyntaxError as e:\n print(f"SyntaxError: {e}", file=sys.stderr); sys.exit(1)\nexcept Exception as e:\n print(f"{type(e).__name__}: {e}", file=sys.stderr); sys.exit(1)\n`,
+      ], { stdio: ["ignore", "ignore", "pipe"], timeout: 10_000 });
+    } catch (e) {
+      const stderr = (e.stderr ? e.stderr.toString() : "") || e.message || "subprocess failed";
+      return { ok: false, error: stderr.trim().slice(0, 300) };
+    }
+
+    // Rule 3: entry-point regex (after parse OK so we know file is readable)
+    let content;
+    try { content = fs.readFileSync(filePath, "utf-8"); }
+    catch { return { ok: false, error: "read failed after parse OK" }; }
+    if (!ENTRY_POINT_REGEX.test(content)) {
+      return { ok: false, error: "no entry point: expected `def check_rule(...)` or `def verify(...)`" };
+    }
+
+    return { ok: true };
+  }
+}

package/src/agent/tools/_workflow-result-schema.js

@@ -0,0 +1,249 @@
+/**
+ * v0.6.2 I1: Shared workflow-result normalizer + ERROR classifier.
+ *
+ * E2E #4 produced 1,150 ERROR verdicts out of 6,930 (16.6%) and
+ * verdict_stats keys leaked Python dataclass repr() strings like
+ * "VerificationResult(rule_id='R049', verdict='NOT_APPLICABLE', ...)".
+ * The agent's batch aggregator was using repr(result) as a dict key
+ * because the workflow's Python output was a dataclass instance, not
+ * a dict.
+ *
+ * This module fixes the boundary: anything that comes out of a
+ * workflow_run tool gets normalized to a strict dict shape before being
+ * persisted or returned to the agent. Repr-strings get parsed back into
+ * structured fields. ERRORs get classified into typed buckets so we can
+ * tell "import failed" from "extraction returned wrong shape" without
+ * reading 1,150 stack traces.
+ */
+
+/**
+ * The required shape every workflow result must satisfy. Unknown extra
+ * keys are preserved.
+ */
+export const REQUIRED_KEYS = ["rule_id", "verdict"];
+
+/**
+ * Canonical verdict values. Anything outside this set is allowed (the
+ * worker LLM may extend) but generates a `nonstandard_verdict` warning
+ * in the result's `_warnings` array.
+ */
+export const STANDARD_VERDICTS = new Set([
+  "PASS", "FAIL", "NOT_APPLICABLE", "SUPPLEMENT_NEEDED", "ERROR", "UNKNOWN",
+]);
+
+/**
+ * Recognized error_type values used by classifyError(). Add to this set
+ * when adding a new pattern below.
+ */
+export const ERROR_TYPES = [
+  "import_error",
+  "attribute_error",
+  "keyword_not_found",
+  "sample_unparseable",
+  "schema_violation",
+  "syntax_error",
+  "timeout",
+  "permission_error",
+  "unknown",
+];
+
+/**
+ * Detect whether a string looks like a Python dataclass repr —
+ * `ClassName(field=value, field=value)`. Used both as a top-level
+ * detector and recursively inside dict keys.
+ */
+const REPR_PATTERN = /^([A-Za-z_]\w*)\((.*)\)$/s;
+
+/**
+ * Parse a Python-repr string into { class_name, fields: { ... } }.
+ * Field values are kept as strings (we don't try to re-type them — the
+ * downstream consumer can JSON.parse if needed). Returns null if the
+ * input doesn't look like a repr.
+ *
+ * Example:
+ *   parsePyRepr("VerificationResult(rule_id='R049', verdict='NOT_APPLICABLE')")
+ *   → { class_name: 'VerificationResult', fields: { rule_id: "'R049'", verdict: "'NOT_APPLICABLE'" } }
+ */
+export function parsePyRepr(s) {
+  if (typeof s !== "string") return null;
+  const m = s.match(REPR_PATTERN);
+  if (!m) return null;
+  const className = m[1];
+  const body = m[2];
+  // Tokenize on top-level commas (ignore commas inside brackets/quotes)
+  const fields = {};
+  let depth = 0;
+  let inQuote = null;
+  let buf = "";
+  let key = null;
+  const flush = () => {
+    if (!buf.trim()) return;
+    if (key == null) {
+      // No `=` seen — entry was positional, skip
+      buf = "";
+      return;
+    }
+    fields[key] = buf.trim();
+    key = null;
+    buf = "";
+  };
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (inQuote) {
+      buf += c;
+      if (c === inQuote && body[i - 1] !== "\\") inQuote = null;
+      continue;
+    }
+    if (c === "'" || c === '"') { inQuote = c; buf += c; continue; }
+    if (c === "(" || c === "[" || c === "{") { depth++; buf += c; continue; }
+    if (c === ")" || c === "]" || c === "}") { depth--; buf += c; continue; }
+    if (c === "=" && depth === 0 && key == null) {
+      key = buf.trim();
+      buf = "";
+      continue;
+    }
+    if (c === "," && depth === 0) { flush(); continue; }
+    buf += c;
+  }
+  flush();
+  return { class_name: className, fields };
+}
+
+/**
+ * Recursively replace any dict key that looks like a Python repr with
+ * a structured object. Also handles arrays. Mutates in place but also
+ * returns the input for chaining.
+ */
+export function normalizeReprKeys(obj) {
+  if (Array.isArray(obj)) {
+    obj.forEach((v, i) => { obj[i] = normalizeReprKeys(v); });
+    return obj;
+  }
+  if (obj && typeof obj === "object") {
+    const newObj = {};
+    for (const [k, v] of Object.entries(obj)) {
+      const parsed = parsePyRepr(k);
+      if (parsed) {
+        // Merge under a class-name bucket. Multiple repr keys for the
+        // same class collapse to a counter (because verdict_stats just
+        // wanted distinct buckets).
+        const bucket = newObj[parsed.class_name] || (newObj[parsed.class_name] = []);
+        bucket.push({ fields: parsed.fields, count: typeof v === "number" ? v : 1 });
+      } else {
+        newObj[k] = normalizeReprKeys(v);
+      }
+    }
+    return newObj;
+  }
+  return obj;
+}
+
+/**
+ * Classify an ERROR result by inferring `error_type` from the raw_output
+ * stack trace or message. Returns one of ERROR_TYPES.
+ *
+ * Conservative — when in doubt, return "unknown" rather than guess wrong.
+ */
+export function classifyError(rawOutput) {
+  if (!rawOutput || typeof rawOutput !== "string") return "unknown";
+  const s = rawOutput;
+  if (/ModuleNotFoundError|ImportError|No module named/i.test(s)) return "import_error";
+  if (/AttributeError/i.test(s)) return "attribute_error";
+  if (/SyntaxError|invalid syntax|unexpected character/i.test(s)) return "syntax_error";
+  if (/PermissionError|permission denied/i.test(s)) return "permission_error";
+  if (/timed out|timeout|Timeout/i.test(s)) return "timeout";
+  // sample parse failures usually mention pdfjs / docx / json
+  if (/pdfjs|docx|json\.decoder|JSONDecodeError|UnicodeDecodeError/i.test(s)) return "sample_unparseable";
+  // schema violations from our own normalizer would have a hint
+  if (/schema_violation|missing required key/i.test(s)) return "schema_violation";
+  // Common keyword-not-found signal: the workflow returned no match
+  if (/no match|not found|未找到|关键词未匹配/i.test(s)) return "keyword_not_found";
+  return "unknown";
+}
+
+/**
+ * Normalize a parsed workflow-output object to the canonical dict shape.
+ * - Ensures `rule_id` and `verdict` are present.
+ * - Strips repr-string keys (delegates to normalizeReprKeys).
+ * - If verdict is "ERROR" or the parse fell back to raw_output, attaches
+ *   `error_type` from classifyError().
+ * - Records issues in `_warnings: string[]` so the consumer (and the
+ *   agent reading the tool result) can see them.
+ *
+ * Inputs:
+ *   parsed      — what JSON.parse yielded (may already be a dict, or be
+ *                 the raw_output fallback object)
+ *   ruleId      — what the caller knows the rule_id should be
+ *   rawOutput   — the original stdout (used for ERROR classification)
+ *
+ * Returns the normalized result. Always returns a dict with `rule_id`
+ * and `verdict`. Never throws.
+ */
+export function normalizeWorkflowResult(parsed, ruleId, rawOutput) {
+  const warnings = [];
+  let result;
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    result = { ...parsed };
+  } else if (typeof parsed === "string") {
+    // Parsed yielded a string — could be a repr at top level
+    const repr = parsePyRepr(parsed);
+    if (repr) {
+      // Strip Python's surrounding quote chars from string values so
+      // STANDARD_VERDICTS comparisons work and downstream code doesn't
+      // see "'PASS'" instead of "PASS". Conservative: only unwrap when
+      // the entire value is wrapped in matching ' or " quotes.
+      const stripped = {};
+      for (const [k, v] of Object.entries(repr.fields)) {
+        if (typeof v === "string" && /^(['"]).*\1$/s.test(v) && v.length >= 2) {
+          stripped[k] = v.slice(1, -1);
+        } else {
+          stripped[k] = v;
+        }
+      }
+      result = stripped;
+      result._source_class = repr.class_name;
+      warnings.push("toplevel_repr_string");
+    } else {
+      result = { raw_output: parsed.slice(0, 5000) };
+      warnings.push("toplevel_string");
+    }
+  } else {
+    result = { raw_output: String(parsed ?? "").slice(0, 5000) };
+    warnings.push("toplevel_nonobject");
+  }
+
+  // Recursively normalize repr keys in nested dicts (verdict_stats, etc.)
+  normalizeReprKeys(result);
+
+  // rule_id: prefer the caller-supplied value (it's authoritative)
+  if (ruleId) result.rule_id = ruleId;
+  else if (typeof result.rule_id !== "string") {
+    result.rule_id = "unknown";
+    warnings.push("missing_rule_id");
+  }
+
+  // verdict: ensure present and canonical-or-warn
+  if (typeof result.verdict !== "string" || result.verdict === "") {
+    // If the workflow fell into raw_output fallback, mark as ERROR
+    if (result.raw_output) {
+      result.verdict = "ERROR";
+    } else {
+      result.verdict = "UNKNOWN";
+      warnings.push("missing_verdict");
+    }
+  } else if (!STANDARD_VERDICTS.has(result.verdict)) {
+    warnings.push("nonstandard_verdict");
+  }
+
+  // ERROR classification
+  if (result.verdict === "ERROR") {
+    const trace = rawOutput || result.raw_output || result.error || "";
+    result.error_type = classifyError(trace);
+  }
+
+  if (warnings.length > 0) {
+    result._warnings = (result._warnings || []).concat(warnings);
+  }
+
+  return result;
+}

package/src/agent/tools/phase-advance.js

@@ -19,13 +19,17 @@ export class PhaseAdvanceTool extends BaseTool {
    * @param {() => string} getCurrentPhaseFn - H1: lets the tool read the
    *   engine's phase BEFORE the call, so it can distinguish "already there"
    *   (silent no-op, informational) from "non-adjacent refusal" (actionable).
-   *   Before H1 both cases returned the same confusing "Either you're already
-   *   there, or transition is non-adjacent" message.
+   * @param {() => string[]} [getRunningSubagentsFn] - v0.6.2 J1: returns the
+   *   list of running subagent task_ids. When non-empty, phase_advance
+   *   refuses unless `acknowledge_stale_subagents: true` is set in input
+   *   (or `force: true`). Forces the agent to confront live work that
+   *   started in the prior phase before declaring the phase done.
    */
-  constructor(advanceFn, getCurrentPhaseFn) {
+  constructor(advanceFn, getCurrentPhaseFn, getRunningSubagentsFn) {
     super();
     this._advance = advanceFn;
     this._getCurrentPhase = getCurrentPhaseFn || (() => null);
+    this._getRunningSubagents = getRunningSubagentsFn || (() => []);
   }
 
   get name() { return "phase_advance"; }
@@ -48,6 +52,11 @@ export class PhaseAdvanceTool extends BaseTool {
           type: "boolean",
           description: "Allow non-adjacent or backward transitions. Default false.",
         },
+        acknowledge_stale_subagents: {
+          type: "boolean",
+          description:
+            "Set to true after using agent_tool(operation=list|poll|kill) to confirm you've handled any subagents still running from the prior phase. Required when subagents are live; otherwise advance is refused (use force:true to bypass entirely).",
+        },
       },
       required: ["to"],
     };
@@ -68,8 +77,30 @@ export class PhaseAdvanceTool extends BaseTool {
       );
     }
 
+    // v0.6.2 J1: stale-subagents acknowledgement gate. Refuses advance if
+    // any subagent is still running and the agent hasn't explicitly
+    // acknowledged. force:true bypasses (matches existing escape pattern).
+    const running = this._getRunningSubagents();
+    if (running.length > 0 && !input.acknowledge_stale_subagents && !input.force) {
+      return new ToolResult(
+        `Refusing to advance from ${beforePhase || "?"} to ${to}: ${running.length} subagent(s) still running from prior phase: ${running.join(", ")}. ` +
+        `Run agent_tool(operation="list") to see status, then either ` +
+        `agent_tool(operation="wait"|"kill") on each, OR pass acknowledge_stale_subagents:true ` +
+        `to advance while leaving them running (use only if they're legitimate background work).`,
+        true,
+      );
+    }
+
     const advanced = this._advance(to, input.reason || "agent request", { force: !!input.force });
     if (advanced) {
+      // Log the ack so post-mortems can find phase advances that proceeded
+      // with live subagents
+      if (running.length > 0 && input.acknowledge_stale_subagents) {
+        return new ToolResult(
+          `Advanced${beforePhase ? ` from ${beforePhase}` : ""} to ${to}${input.force ? " (forced)" : ""} — ` +
+          `acknowledged ${running.length} running subagent(s): ${running.join(", ")}.`,
+        );
+      }
       return new ToolResult(`Advanced${beforePhase ? ` from ${beforePhase}` : ""} to ${to}${input.force ? " (forced)" : ""}`);
     }
 

package/src/agent/tools/workflow-run.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { BaseTool, ToolResult } from "./base.js";
+import { normalizeWorkflowResult } from "./_workflow-result-schema.js";
 
 /**
  * Execute a distilled workflow script against a document.
@@ -89,14 +90,18 @@ export class WorkflowRunTool extends BaseTool {
       return new ToolResult(e.message, true);
     }
 
-    // Parse output
-    let resultData;
+    // Parse output (last stdout line as JSON)
+    let parsed;
     try {
       const lines = output.trim().split("\n");
-      resultData = JSON.parse(lines[lines.length - 1]);
+      parsed = JSON.parse(lines[lines.length - 1]);
     } catch {
-      resultData = { raw_output: output.slice(0, 5000) };
+      parsed = { raw_output: output.slice(0, 5000) };
     }
+    // v0.6.2 I1: normalize to canonical dict shape — strips Python
+    // dataclass repr() keys, classifies ERROR results, ensures rule_id
+    // and verdict are present.
+    const resultData = normalizeWorkflowResult(parsed, ruleId, output);
 
     // Attach confidence score
     const extractedValue = String(resultData.extracted_value || resultData.value || "");

package/src/agent/workspace.js

@@ -240,6 +240,19 @@ export class Workspace {
     return traceId;
   }
 
+  /**
+   * v0.6.2 J3: Synchronous lock mirror of `withFileLock`, for callers
+   * that can't go async (SessionState.save). Locks a sibling
+   * `<relPath>.lock` file via O_CREAT|O_EXCL, with 5s timeout and 30s
+   * stale-takeover. On failure to acquire, runs fn anyway — better to
+   * lose serialization than deadlock a save call. Use sparingly; prefer
+   * `withFileLock` (async) for all paths that allow it.
+   */
+  withSyncFileLock(relPath, fn, { timeoutMs = 5_000, staleMs = 30_000 } = {}) {
+    const lockPath = path.join(this.path, `${relPath}.lock`);
+    return this._withSyncLockAtPath(lockPath, fn, { timeoutMs, staleMs });
+  }
+
   /**
    * B5: Synchronous gitops lock. Mirror of withFileLock but sync to fit
    * autoCommit's existing call signature. Times out and proceeds anyway
@@ -247,6 +260,16 @@ export class Workspace {
    */
   _withGitSyncLock(fn, { timeoutMs = 5_000, staleMs = 30_000 } = {}) {
     const lockPath = path.join(this.path, ".git", "kc-commit.lock");
+    return this._withSyncLockAtPath(lockPath, fn, { timeoutMs, staleMs });
+  }
+
+  /**
+   * Shared sync-lock implementation. Used by `_withGitSyncLock` (B5) and
+   * `withSyncFileLock` (J3 / v0.6.2). Same semantics: O_CREAT|O_EXCL on
+   * a sibling `.lock` file, busy-spin retry with stale takeover, run fn
+   * anyway on timeout.
+   */
+  _withSyncLockAtPath(lockPath, fn, { timeoutMs = 5_000, staleMs = 30_000 } = {}) {
     const start = Date.now();
     let acquired = false;
     while (Date.now() - start < timeoutMs) {

package/src/model-tiers.json

@@ -123,6 +123,38 @@
     }
   },
 
+  "deepseek": {
+    "_comment": "DeepSeek v4 family — flagship pro + cheap flash. Native 1M context but KC caps to 200K.",
+    "conductor": "deepseek-v4-pro",
+    "llm": {
+      "tier1": "deepseek-v4-pro",
+      "tier2": "deepseek-v4-pro",
+      "tier3": "deepseek-v4-flash",
+      "tier4": "deepseek-v4-flash"
+    },
+    "vlm": {
+      "tier1": "",
+      "tier2": "",
+      "tier3": ""
+    }
+  },
+
+  "xiaomi": {
+    "_comment": "Xiaomi MiMo coding plan — flagship Pro + standard + multimodal Omni. Native 1M context but KC caps to 200K. TTS variants excluded (no KC use case).",
+    "conductor": "MiMo-V2.5-Pro",
+    "llm": {
+      "tier1": "MiMo-V2.5-Pro",
+      "tier2": "MiMo-V2.5",
+      "tier3": "MiMo-V2-Pro",
+      "tier4": "MiMo-V2-Pro"
+    },
+    "vlm": {
+      "tier1": "MiMo-V2-Omni",
+      "tier2": "MiMo-V2-Omni",
+      "tier3": ""
+    }
+  },
+
   "openrouter": {
     "conductor": "anthropic/claude-sonnet-4-20250514",
     "llm": {

package/src/providers.js

@@ -211,6 +211,51 @@ const PROVIDERS = [
       zh: "MiniMax",
     },
   },
+  {
+    id: "deepseek",
+    name: "DeepSeek",
+    baseUrl: "https://api.deepseek.com",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    contextLimit: 200000, // KC cap — DeepSeek v4 is native 1M; we cap to 200K
+    defaultModel: getTierConfig("deepseek").conductor || "deepseek-v4-pro",
+    defaultTiers: getTierConfig("deepseek").llm,
+    defaultVlm: getTierConfig("deepseek").vlm,
+    curatedModels: [
+      { id: "deepseek-v4-pro", ownedBy: "deepseek" },
+      { id: "deepseek-v4-flash", ownedBy: "deepseek" },
+    ],
+    labels: {
+      en: "DeepSeek (v4 family)",
+      zh: "DeepSeek（v4 系列）",
+    },
+  },
+  {
+    id: "xiaomi",
+    name: "Xiaomi MiMo",
+    baseUrl: "https://token-plan-cn.xiaomimimo.com/v1",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: null, // Xiaomi coding-plan endpoint, no /models — use curated list
+    supportsCodingPlanKey: true,
+    contextLimit: 200000, // KC cap — MiMo V2.5 is native 1M
+    defaultModel: getTierConfig("xiaomi").conductor || "MiMo-V2.5-Pro",
+    defaultTiers: getTierConfig("xiaomi").llm,
+    defaultVlm: getTierConfig("xiaomi").vlm,
+    curatedModels: [
+      { id: "MiMo-V2.5-Pro", ownedBy: "xiaomi" },
+      { id: "MiMo-V2.5", ownedBy: "xiaomi" },
+      { id: "MiMo-V2-Pro", ownedBy: "xiaomi" },
+      { id: "MiMo-V2-Omni", ownedBy: "xiaomi" }, // multimodal
+      // TTS variants (MiMo-V2.5-TTS, *-VoiceClone, *-VoiceDesign, MiMo-V2-TTS)
+      // intentionally excluded — KC has no TTS use case.
+    ],
+    labels: {
+      en: "Xiaomi MiMo (V2.5 family, coding plan)",
+      zh: "小米 MiMo（V2.5 系列，编程计划）",
+    },
+  },
   {
     id: "openrouter",
     name: "OpenRouter",

package/template/skills/en/meta-meta/skill-authoring/SKILL.md

@@ -27,6 +27,25 @@ rule-skills/
 
 Not every rule needs all of these. A simple threshold check might only need SKILL.md and a script. A complex semantic rule might need detailed references and many samples. Start minimal, add as needed during testing.
 
+## Granularity: 1 rule = 1 skill directory (default)
+
+Default to **one rule per skill directory**. Group rules into the same file ONLY when they meet BOTH:
+
+1. They share the same evidence (same section / same table / same field) — so locating one locates all.
+2. They fail together — when one fails, the others almost always fail too (e.g., siblings in a required-fields list where the table itself is missing).
+
+When grouping, name the file with the explicit range so downstream consumers (workflow-run, dashboards, finalization) can parse rule coverage by filename:
+- ✅ `check_r013_r017.py` (R013, R014, R015, R016, R017 — same disclosure table, fail together)
+- ❌ `check_r001_r050_r078.py` (different chapters, even if topically related — keep separate)
+
+### Anti-pattern: the unified runner
+
+If you find yourself writing a single `unified_qc.py` (or `batch_runner.py`, or `master_check.py`) that handles all 110 rules in one Python file, **stop**. That means your per-rule skills are wrong, not that the architecture is wrong. Fix the skills.
+
+E2E #4 demonstrated the cost: an agent wrote `unified_qc.py` to bypass 110 individual skills it didn't trust. Result was 1,150 errors out of 6,930 production checks (16.6%) and a phase counter stuck in `production_qc` while real work happened in skill_authoring. The unified runner felt productive locally and was a global mistake.
+
+If individual skills aren't running cleanly, the right response is to identify which ones break and fix them, not consolidate. The whole pipeline (extraction → skill_testing → distillation → production_qc) assumes one rule = one verifiable artifact.
+
 ## Writing SKILL.md
 
 ### Frontmatter

package/template/skills/zh/meta-meta/skill-authoring/SKILL.md

@@ -27,6 +27,25 @@ rule-skills/
 
 Not every rule needs all of these. A simple threshold check might only need SKILL.md and a script. A complex semantic rule might need detailed references and many samples. Start minimal, add as needed during testing.
 
+## 颗粒度：默认 1 条规则 = 1 个技能目录
+
+默认**每条规则一个独立技能目录**。仅当同时满足以下两个条件时，才能把多条规则合并到同一个文件：
+
+1. 共享同一证据（同一章节 / 同一表格 / 同一字段）——找到一条就找到了全部。
+2. 一同成败——一条失败，其他几乎必然失败（例如必填字段表中的同辈规则，表本身缺失则全部失败）。
+
+合并时，用显式范围命名文件，让下游消费者（workflow-run、dashboards、finalization）可以从文件名解析规则覆盖范围：
+- ✅ `check_r013_r017.py`（R013、R014、R015、R016、R017——同一披露表格，一同失败）
+- ❌ `check_r001_r050_r078.py`（不同章节，即使主题相关，也应分开）
+
+### 反模式：统一运行器（unified runner）
+
+如果你发现自己在写一个 `unified_qc.py`（或 `batch_runner.py`、`master_check.py`）把全部 110 条规则塞进一个 Python 文件里，**停下来**。这说明你的单条规则技能写错了，不是架构错了。请修复单条技能。
+
+E2E #4 给出了代价：智能体写了一个 `unified_qc.py` 绕过它不信任的 110 个独立技能。结果是 6,930 条生产检查里出了 1,150 个错误（16.6%），相位计数器卡在 `production_qc`，而真实工作还在 skill_authoring 里进行。统一运行器在局部看起来很高效，全局上是个错误。
+
+如果某些独立技能跑不通，正确的应对是定位并修复出问题的那几条，而不是合并所有技能。整个流水线（extraction → skill_testing → distillation → production_qc）的前提就是「一条规则 = 一个可独立验证的产物」。
+
 ## Writing SKILL.md
 
 ### Frontmatter