kc-beta 0.6.1 → 0.7.0

package/src/agent/skill-validator.js

@@ -0,0 +1,163 @@
+/**
+ * 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_*.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 one of the names: `check_rule`,
+ *     `verify`, OR `check_r<digits>` (e.g. `check_r014`, `check_r013_r017`).
+ *     v0.7.0 A6 broadened the third pattern after E2E #5 audit found
+ *     three sessions independently chose `def check_r###` over the
+ *     canonical names — the validator was too strict.
+ *
+ * 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";
+
+// v0.7.0 A6: entry-point check is a sanity probe, not a style enforcer.
+// The validator's real signal comes from `≥ 100 bytes` + `ast.parse
+// passes`. Restricting to specific verb names rejected 27/28 GLM
+// scripts in E2E #5 — the cost outweighed the catch (every contestant
+// converged on a different naming convention).
+//
+// New rule: any top-level `def \w+(...)` counts. Rejects pure-imports
+// or comment-only stubs (which is what we actually wanted to catch),
+// accepts anything with real logic. The check_*.py *filename* (matched
+// by the path regex in `findCheckScripts`) carries the rule-id signal;
+// the function name doesn't need to.
+const ENTRY_POINT_REGEX = /^(?:async\s+)?def\s+\w+\s*\(/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 callable defined: file has imports/comments only, no top-level `def`" };
+    }
+
+    return { ok: true };
+  }
+}

package/src/agent/task-manager.js

@@ -139,12 +139,23 @@ export class TaskManager {
   // --- Bulk creation from rule catalog ---
 
   /**
-   * Phases where one-task-per-rule is the natural unit of work.
-   * For BOOTSTRAP / EXTRACTION the unit is a regulation (one PDF → many rules);
-   * ralph-loop shouldn't drive per-rule there because the rules don't exist yet
-   * (or are the *output*, not the input) — see E2E #3 coverage check.
+   * Phases where the engine auto-creates one-task-per-rule on phase entry.
+   *
+   * v0.7.0 B2: empty by default. Agent owns TaskBoard decisions per the
+   * work-decomposition meta-meta skill — engine no longer assumes per-rule
+   * granularity is right. The agent reads the rule list from describeState
+   * and calls TaskCreate with whatever shape (single, grouped, range,
+   * non-rule) makes sense for the corpus.
+   *
+   * Override `KC_AGENT_OWNS_TASKBOARD=0` to restore v0.6.x behavior
+   * (engine auto-populates per-rule for skill_authoring + skill_testing).
+   * The override is a staged-rollout safety valve, not a long-lived
+   * config — slated for removal in v0.8.0 after E2E #6 validates the
+   * agent-owned default.
    */
-  static PER_RULE_PHASES = new Set(["skill_authoring", "skill_testing"]);
+  static PER_RULE_PHASES = (process.env.KC_AGENT_OWNS_TASKBOARD === "0")
+    ? new Set(["skill_authoring", "skill_testing"])
+    : new Set();
 
   /**
    * Create one task per rule for a given phase — but only if the phase's unit
@@ -197,6 +208,51 @@ export class TaskManager {
     ).length;
   }
 
+  /**
+   * v0.7.0 A5: Reconcile per-rule tasks against disk artifacts.
+   *
+   * Background: E2E #5 DS audit found tasks.json showing 70/70 completed
+   * while only ~56 dirs / 36 with check_*.py existed on disk. The agent
+   * called markDone() optimistically but the artifacts didn't materialize
+   * (or were deleted later). The engine's phase gate trusted the count.
+   *
+   * Reconcile walks every "completed" task in PER_RULE_PHASES and checks
+   * whether the expected disk artifacts exist via a caller-supplied
+   * `expectsFn(task) -> boolean` predicate. Tasks whose artifacts are
+   * missing are flipped back to `pending` with a `reconcile_failed`
+   * note so the agent can re-do the work, and the gate can refuse
+   * advance if the per-rule artifact set is incomplete.
+   *
+   * Called from engine `_advancePhase` before `exitCriteriaMet()`.
+   *
+   * @param {(task: object) => boolean} expectsFn
+   * @returns {{ reconciled: number, flippedBack: string[] }}
+   *   Number of tasks inspected, plus the IDs of tasks flipped back to
+   *   pending. Caller logs to events.jsonl.
+   */
+  reconcileAgainstDisk(expectsFn) {
+    let reconciled = 0;
+    const flippedBack = [];
+    if (typeof expectsFn !== "function") return { reconciled, flippedBack };
+    for (const task of this._tasks) {
+      if (task.status !== "completed") continue;
+      if (!TaskManager.PER_RULE_PHASES.has(task.phase)) continue;
+      reconciled++;
+      let ok = false;
+      try { ok = !!expectsFn(task); }
+      catch { ok = false; }
+      if (!ok) {
+        task.status = "pending";
+        task.reconcile_failed = true;
+        task.summary = (task.summary ? task.summary + " | " : "") +
+          "v0.7.0 A5: artifacts missing on disk → flipped back to pending";
+        flippedBack.push(task.id);
+      }
+    }
+    if (flippedBack.length > 0) this.save();
+    return { reconciled, flippedBack };
+  }
+
   /**
    * Format task list for injection into system prompt context.
    * Compact checklist — not conversation history.

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/document-chunk.js

@@ -194,20 +194,32 @@ export class DocumentChunkTool extends BaseTool {
       };
     }
 
-    // For other formats (.docx, .xlsx, etc): read as UTF-8 best-effort.
-    // Upstream agent should call document_parse first and then document_chunk
-    // on the parsed output directly — current MVP keeps the tool surface small.
+    // v0.7.0 G (#91): route .docx / .doc / others through native parser
+    // dispatcher (mammoth / word-extractor / LibreOffice fallback).
+    // Replaces the prior "read as UTF-8" stub which produced binary
+    // garbage on .docx and forced agents to call document_parse + chunk
+    // separately. extractText() returns clean text or a structured
+    // failure that downstream can surface to the agent.
     try {
-      const txt = fs.readFileSync(absPath, "utf-8");
+      const { extractText } = await import("../document-parser.js");
+      const result = await extractText(absPath);
+      if (result.ok && result.text) {
+        return {
+          source_file: baseName,
+          total_pages: 1,
+          blocks: [{ page: 1, markdown: result.text }],
+          parse_via: result.via,
+        };
+      }
       return {
-        source_file: baseName,
-        total_pages: 1,
-        blocks: [{ page: 1, markdown: txt }],
+        source_file: baseName, total_pages: 0, blocks: [],
+        parse_error: result.error ||
+          `Unsupported format '${suffix}'. Install mammoth / word-extractor or rely on LibreOffice fallback.`,
       };
-    } catch {
+    } catch (e) {
       return {
         source_file: baseName, total_pages: 0, blocks: [],
-        parse_error: `Unsupported format '${suffix}'. Run document_parse first and use its output, or stick to .pdf / .md / .txt.`,
+        parse_error: `parse exception: ${e?.message || String(e)}`,
       };
     }
   }

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,15 +77,52 @@ 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)" : ""}`);
     }
 
-    // Truly refused — non-adjacent transition without force, or terminal-phase
-    // forward attempt. Give the actionable hint.
+    // Truly refused — possible reasons: non-adjacent transition,
+    // terminal-phase forward attempt, or hard-tracking gate (source phase's
+    // exit criteria not met by engine telemetry).
+    //
+    // v0.7.0 A3: refusal text no longer advertises `force:true`. E2E #5
+    // showed every conductor reading the old refusal hint and force-bypassing
+    // immediately (12/12 transitions). The escape valve remains in the input
+    // schema (discoverable) but isn't hand-fed to the LLM here. Instead,
+    // direct the agent at the missing milestones it can satisfy.
     return new ToolResult(
-      `Did not advance to ${to}. Transition is non-adjacent${beforePhase ? ` (currently in ${beforePhase})` : ""} — set force:true to override, or advance to the immediate-next phase first.`,
+      `Did not advance to ${to} (currently in ${beforePhase || "?"}). ` +
+      `Likely cause: source-phase exit criteria not met. ` +
+      `Run /status (or read the phase describeState block in this turn's system reminder) ` +
+      `to see which milestones are missing, then produce the disk artifacts that satisfy them — ` +
+      `the engine derives milestones from filesystem facts (rule_skills/<id>/SKILL.md, check.py, ` +
+      `workflows/<id>/*.py, output/results/*.json, etc.). ` +
+      `If the transition is non-adjacent or this phase truly is done despite the gate, ` +
+      `re-call with the documented schema flag. The engine logged the precise reason in ` +
+      `events.jsonl as 'phase_advance_refused'.`,
       false,
     );
   }