kc-beta 0.7.5 → 0.8.1

package/src/agent/pipelines/_advance-hints.js

@@ -0,0 +1,92 @@
+// v0.8 P0-E: prescriptive refusal hints for phase_advance gate failures.
+//
+// 资管 + 贷款 v0.7.5 audits both observed the force-bypass pattern:
+// engine refuses phase_advance with `engineCounts: workflowsTested: 0/14`,
+// agent does ~3 min of cleanup, then forces past anyway. Cleanup happens
+// (signal IS being consumed) but force always wins because the descriptive
+// "exit criteria not met" hint doesn't tell the agent WHAT to write.
+//
+// v0.8 P0-E replaces the descriptive hint with a prescriptive one. The
+// hint text below derives from the same artifact paths + filename patterns
+// that _milestone-derive.js walks, so the agent's instructions match what
+// the engine will check next turn.
+//
+// Design contract (matches v0.8 design doc Q20 user lean):
+//   - Single shared helper here; engine.js + phase-advance.js both call it.
+//   - Each hint is one or two concrete sentences naming a path, a filename
+//     pattern, and a script to run (where applicable).
+//   - Hint output is plain text, suitable to drop into a tool result.
+//
+// To extend: edit the per-phase hint generators below. Keep the artifact
+// paths in sync with the corresponding derive function in _milestone-derive.js.
+
+/**
+ * Build a prescriptive refusal hint for a phase_advance gate failure.
+ *
+ * @param {string} fromPhase — the phase the agent is trying to leave
+ * @param {object} engineCounts — raw engine counts (or null)
+ * @param {string} [engineCountsLine] — formatted summary string from _buildEngineCountsBlock
+ * @returns {string} a multi-line hint suitable for the LLM tool result
+ */
+export function getPrescriptiveHint(fromPhase, engineCounts, engineCountsLine = "") {
+  const header = engineCountsLine
+    ? `Engine telemetry: ${engineCountsLine}\n\n`
+    : "";
+
+  const hint = HINTS_BY_PHASE[fromPhase];
+  if (!hint) {
+    return header + "Check the system prompt's phase state block for missing milestones. The engine derives milestones from filesystem facts.";
+  }
+  return header + hint;
+}
+
+const HINTS_BY_PHASE = {
+  bootstrap:
+    "To advance to rule_extraction:\n" +
+    "  • Verify <workspace>/source_docs/ contains the regulation file(s) you're extracting rules from.\n" +
+    "  • Verify <workspace>/samples/ contains at least one sample document for testing.\n" +
+    "  • Ensure AGENT.md exists at workspace root with project context filled in.\n" +
+    "Engine reads filesystem facts; no need to call any 'mark bootstrap complete' tool — just produce the artifacts.",
+
+  rule_extraction:
+    "To advance to skill_authoring:\n" +
+    "  • For each rule in the source regulation, write an entry to rules/catalog.json with {id, source_ref, falsifiability_statement, applicable_sections}.\n" +
+    "  • Use rule_catalog tool (operation: 'write') for catalog entries; engine derives `rulesExtracted` from this file.\n" +
+    "  • For chunk traceability: each catalog entry should reference its source chunk via applicable_sections.\n" +
+    "  • Write rule_skills/coverage_report.md or rules/coverage_report.md to mark coverageAudited=true (a per-rule × per-section table).",
+
+  skill_authoring:
+    "To advance to skill_testing:\n" +
+    "  • For each rule_id in rules/catalog.json, create rule_skills/<rule_id>/SKILL.md (uppercase! engine path-match is case-sensitive on Linux).\n" +
+    "  • Each SKILL.md needs frontmatter (id, name, description) + a body describing verification logic.\n" +
+    "  • Pair each SKILL.md with rule_skills/<rule_id>/check.py — substantive logic, NOT a 'return NOT_APPLICABLE' stub. If logic lives in workflows/, check.py must import + call the workflow.\n" +
+    "  • For grouped skills covering multiple rules, frontmatter MUST include `source_rules: [R001, R005, ...]` so engine credits each rule_id.\n" +
+    "  • Engine counts `rulesCovered` from rule_skills/ walk; aim for catalog.json's full rule list.",
+
+  skill_testing:
+    "To advance to distillation:\n" +
+    "  • For each rule_id, write test results to output/results/skill_test_round<N>.json or output/results/<rule_id>_<sample>.json.\n" +
+    "  • Each test result needs `verdict` (PASS/FAIL/NOT_APPLICABLE) plus per-rule accuracy.\n" +
+    "  • Engine counts `skillsTested` from these files. Aim for ≥1 result per rule, with ≥90% accuracy on labeled samples.\n" +
+    "  • If a rule consistently fails, iterate the SKILL.md + check.py before advancing (this is the evolution-loop pattern).",
+
+  distillation:
+    "To advance to production_qc:\n" +
+    "  • For each rule_id, write workflows/<rule_id>/workflow_v1.py (regex-only or hybrid regex+worker_llm).\n" +
+    "  • Each workflow.py needs a `verify(document_text, config)` function returning {verdict, evidence, confidence, ...}.\n" +
+    "  • Engine counts `workflowsCreated` from workflows/<rule_id>/workflow_v*.py walk.\n" +
+    "  • Run scripts/v1_regression.py (or equivalent) to populate output/results/v1_regression.json — engine counts `workflowsTested` from this.\n" +
+    "  • For grouped workflows (one workflow covering multiple rules), declare `source_rules: [...]` in workflow's docstring or sidecar config.",
+
+  production_qc:
+    "To advance to finalization:\n" +
+    "  • Write output/results/production_qc_results.json (preferred shape: {results: {<rule_id>: {<doc_id>: {verdict, evidence, confidence}}}}).\n" +
+    "  • OR write output/qc/review_<batch>.json with `documents_reviewed: N` for each batch — engine sums across files.\n" +
+    "  • Engine counts `batchesProcessed` and `documentsReviewed`. Each batch should cover the full doc set OR a meaningful sample.\n" +
+    "  • If accuracy is below threshold, run evolution-loop on the failing rules before advancing.",
+
+  finalization:
+    "(Finalization is the terminal phase — no forward advance.)",
+};
+
+export default getPrescriptiveHint;

package/src/agent/pipelines/_milestone-derive.js

@@ -80,6 +80,22 @@ function readJsonSafe(p) {
   try { return JSON.parse(fs.readFileSync(p, "utf-8")); } catch { return null; }
 }
 
+// v0.8 P1-A: find the first existing file from a list of candidate relative
+// paths. Returns the absolute path of the first match, or null. Used for
+// "agent-might-have-written-it-anywhere" lookups where conventions vary.
+//
+// 资管 v0.7.5 wrote rule_skills/coverage_report.md; 贷款 v0.7.5 wrote
+// output/coverage_report.md or similar. Each derive function previously
+// hardcoded its own short list — extracting this helper keeps additions
+// centralized.
+function findFileAcrossKnownPaths(workspaceCwd, relPaths) {
+  for (const rel of relPaths) {
+    const abs = path.join(workspaceCwd, rel);
+    if (fileExists(abs)) return abs;
+  }
+  return null;
+}
+
 function readFileSafe(p) {
   try { return fs.readFileSync(p, "utf-8"); } catch { return ""; }
 }
@@ -197,15 +213,18 @@ export function deriveRuleExtractionMilestones(workspace) {
     }
   }
 
-  // coverageAudited: presence of rules/coverage_audit.{md,json} OR a
-  // rules/coverage_report.md / output/coverage_report.md. Loose criterion
-  // because agents pick different conventions; the spirit is "did the
+  // coverageAudited: presence of any coverage audit/report doc. Loose
+  // criterion — agents pick different conventions; the spirit is "did the
   // agent produce a coverage doc" not "did they put it in this exact file".
-  const coverageAudited =
-    fileExists(path.join(rulesDir, "coverage_audit.md")) ||
-    fileExists(path.join(rulesDir, "coverage_audit.json")) ||
-    fileExists(path.join(rulesDir, "coverage_report.md")) ||
-    fileExists(path.join(cwd, "output", "coverage_report.md"));
+  // v0.8 P1-A: use the same findFileAcrossKnownPaths helper as finalization.
+  const coverageAudited = !!findFileAcrossKnownPaths(cwd, [
+    path.join("rules", "coverage_audit.md"),
+    path.join("rules", "coverage_audit.json"),
+    path.join("rules", "coverage_report.md"),
+    path.join("output", "coverage_report.md"),
+    path.join("rule_skills", "coverage_report.md"),       // v0.8 P1-A
+    path.join("output", "qc", "coverage_report.md"),
+  ]);
 
   return {
     rulesExtracted,
@@ -314,13 +333,88 @@ export function deriveSkillAuthoringMilestones(workspace) {
     }
   }
 
+  // v0.8 P2-F (item 22): count stub-shaped check.py files. Pairs with
+  // v0.8 P2-A teaching about the inverse-stub anti-pattern. Surfaces
+  // a ratio that downstream code (skill-authoring exitCriteriaMet)
+  // can choose to enforce via env flag.
+  const checkPyAudit = _auditCheckPyShapes(skillsDir);
+
   return {
     skillsAuthored,
     skillsWithScripts,
     ruleIdsCovered: [...ruleIdsCovered],
+    checkPyTotal: checkPyAudit.total,
+    checkPyStubCount: checkPyAudit.stubFiles.length,
+    checkPyStubFiles: checkPyAudit.stubFiles,
+    checkPyStubRatio: checkPyAudit.total > 0
+      ? +(checkPyAudit.stubFiles.length / checkPyAudit.total).toFixed(3)
+      : 0,
   };
 }
 
+// v0.8 P2-F: walk rule_skills/<id>/ for check_*.py and check each for
+// stub-shape patterns. Returns {total, stubFiles}. Patterns recognized
+// as stubs (per v0.7.x audit findings):
+//   - returns literal `"verdict": "NOT_APPLICABLE"` (资管 v0.7.5 variant)
+//   - returns literal `"pass": null` (v0.7.0 legacy)
+//   - returns literal `"method": "stub"`
+//   - AND none of: workflow import, >20 non-comment lines.
+// Substantive signals override the stub-return signal (a check.py that
+// imports + delegates to a workflow but happens to return NOT_APPLICABLE
+// for some sub-path is not a stub).
+function _auditCheckPyShapes(skillsDir) {
+  const stubFiles = [];
+  let total = 0;
+  if (!dirExists(skillsDir)) return { total, stubFiles };
+
+  for (const dirEntry of listChildDirs(skillsDir)) {
+    if (dirEntry.name.startsWith("__")) continue;
+    const skillPath = path.join(skillsDir, dirEntry.name);
+    const scripts = findCheckScripts(skillPath);
+    for (const scriptPath of scripts) {
+      total++;
+      if (_isCheckPyStubShaped(scriptPath)) {
+        stubFiles.push(path.relative(skillsDir, scriptPath));
+      }
+    }
+  }
+  return { total, stubFiles };
+}
+
+function _isCheckPyStubShaped(scriptPath) {
+  let content;
+  try { content = fs.readFileSync(scriptPath, "utf-8"); }
+  catch { return false; }
+
+  // Substantive signal 1: imports a workflow (direct delegation)
+  if (/from\s+workflows[.\w]+\s+import|^import\s+workflows\./m.test(content)) {
+    return false;
+  }
+
+  // Stub return patterns. A check.py is a stub if it ALWAYS returns one
+  // of these regardless of input. We detect "always returns" by checking
+  // that the file has no other verdict literal — no PASS, FAIL, WARNING
+  // returns elsewhere. A scaffold with 30+ lines but a single
+  // NOT_APPLICABLE return path (like 资管 v0.7.5's 14 check.py files) is
+  // still a stub by behavior — line count is unreliable.
+  const stubReturn1 = /return\s+\{[^}]*["']verdict["']\s*:\s*["']NOT_APPLICABLE["']/m.test(content);
+  const stubReturn2 = /return\s+\{[^}]*["']pass["']\s*:\s*None/m.test(content);
+  const stubReturn3 = /return\s+\{[^}]*["']method["']\s*:\s*["']stub["']/m.test(content);
+  const hasStubReturn = stubReturn1 || stubReturn2 || stubReturn3;
+
+  if (!hasStubReturn) return false;
+
+  // If we find ANY other verdict (PASS, FAIL, WARNING), the file is doing
+  // real branching even if one path returns NOT_APPLICABLE — not a stub.
+  const hasOtherVerdict =
+    /["']verdict["']\s*:\s*["']PASS["']/m.test(content) ||
+    /["']verdict["']\s*:\s*["']FAIL["']/m.test(content) ||
+    /["']verdict["']\s*:\s*["']WARNING["']/m.test(content) ||
+    /\bmake_result\b/.test(content); // common helper that produces non-stub returns
+
+  return !hasOtherVerdict;
+}
+
 // ───────────────────────────────────────────────────────────────────
 // skill_testing
 // ───────────────────────────────────────────────────────────────────
@@ -613,10 +707,45 @@ export function deriveProductionQcMilestones(workspace) {
     }
   }
 
+  // v0.8 P1-A: per-doc QC review files at output/qc/reviews/doc_*.json
+  // (贷款 v0.7.5 shape). Each file is a single review object with
+  // {review_id, document, verdict}. Engine previously skipped these
+  // because they don't match the batch heuristic, causing
+  // `documents_reviewed: 0` despite 16 docs on disk.
+  const perDocReviewsDir = path.join(outputDir, "qc", "reviews");
+  if (dirExists(perDocReviewsDir)) {
+    for (const e of listChildFiles(perDocReviewsDir)) {
+      if (!e.name.endsWith(".json")) continue;
+      const data = readJsonSafe(path.join(perDocReviewsDir, e.name));
+      if (!data || typeof data !== "object" || !data.verdict) continue;
+      // Document identifier: prefer explicit fields, fall back to filename
+      const docKey = data.document || data.doc || data.file || data.path || e.name.replace(/\.json$/, "");
+      documentsReviewedSet.add(String(docKey));
+    }
+  }
+
+  // v0.8 P1-A: also read numeric `documents_reviewed: N` from any
+  // top-level batch file (贷款 review_001.json declares 16 directly).
+  // We use this only when the doc set is smaller than the claim — agents
+  // sometimes write summary batches without enumerating individual docs.
+  let declaredDocCount = 0;
+  for (const dir of candidateDirs) {
+    if (!dirExists(dir)) continue;
+    for (const e of listChildFiles(dir)) {
+      if (!e.name.endsWith(".json")) continue;
+      const data = readJsonSafe(path.join(dir, e.name));
+      if (!data || typeof data !== "object") continue;
+      const n = Number(data.documents_reviewed);
+      if (Number.isFinite(n) && n > declaredDocCount) declaredDocCount = n;
+    }
+  }
+  const documentsReviewed = Math.max(documentsReviewedSet.size, declaredDocCount);
+
   return {
     batchesProcessed,
-    documentsReviewed: documentsReviewedSet.size,
+    documentsReviewed,
     documentsReviewedKeys: [...documentsReviewedSet], // for describeState detail
+    documentsReviewedDeclared: declaredDocCount > documentsReviewedSet.size ? declaredDocCount : 0,
   };
 }
 
@@ -658,10 +787,18 @@ export function deriveFinalizationMilestones(workspace) {
     }
   }
 
-  // coverageReportWritten: rules/coverage_report.md OR output/coverage_report.md.
-  const coverageReportWritten =
-    fileExists(path.join(cwd, "rules", "coverage_report.md")) ||
-    fileExists(path.join(cwd, "output", "coverage_report.md"));
+  // coverageReportWritten: accept multiple known agent-write locations.
+  // v0.8 P1-A: added rule_skills/coverage_report.md (资管 v0.7.5 wrote here)
+  // and coverage_audit.md variants (贷款 v0.7.5 wrote rules/coverage_audit.md).
+  // The "coverage doc" concept covers both report-style + audit-style files.
+  const coverageReportWritten = !!findFileAcrossKnownPaths(cwd, [
+    path.join("rules", "coverage_report.md"),
+    path.join("rules", "coverage_audit.md"),                // 贷款 v0.7.5
+    path.join("rules", "coverage_audit.json"),
+    path.join("output", "coverage_report.md"),
+    path.join("rule_skills", "coverage_report.md"),         // 资管 v0.7.5
+    path.join("output", "qc", "coverage_report.md"),        // future-proofing
+  ]);
 
   // finalDashboardWritten: at least one dashboards/*.html that is NOT a
   // duplicate of any other. DS + GLM both shipped byte-identical
@@ -694,11 +831,108 @@ export function deriveFinalizationMilestones(workspace) {
     }
   }
 
+  // v0.8 P0-D: stale-release detection. SOFT gate — surfaces a warning,
+  // doesn't refuse phase advance. 资管 audit § 9.1 finding 11 found both
+  // release bundles snapped BEFORE the user's "更激进 worker LLM" prompt
+  // drove 14 hybrid workflow_v2.py builds, but neither was re-released.
+  // We detect by comparing the most-recent release manifest's created_at
+  // against the mtimes of workflows/ and rule_skills/.
+  const staleRelease = _detectStaleRelease(cwd);
+
   return {
     readmeWritten,
     coverageReportWritten,
     finalDashboardWritten,
     dashboardDuplicatesDetected,
+    releaseIsStale: staleRelease.isStale,
+    staleReleaseDetail: staleRelease.detail,
+  };
+}
+
+// v0.8 P0-D: detect whether workflows/ or rule_skills/ contain files
+// modified after the most-recent release manifest was written. Returns
+// {isStale: bool, detail: {releaseTs?, releasePath?, newerFiles?: [...]}}.
+// SOFT semantics — the milestone is informational; phase advance still
+// works. The agent + downstream tooling (e2e-audit) decides what to do.
+function _detectStaleRelease(cwd) {
+  const releasesRoot = path.join(cwd, "output", "releases");
+  if (!dirExists(releasesRoot)) return { isStale: false, detail: null };
+
+  // Find most-recent release manifest (by created_at OR fs mtime as fallback).
+  let latestRelease = null; // {path, createdAt: Date}
+  for (const e of listChildDirs(releasesRoot)) {
+    const manifestPath = path.join(releasesRoot, e.name, "manifest.json");
+    try {
+      const stat = fs.statSync(manifestPath);
+      if (!stat.isFile()) continue;
+      let createdAt = stat.mtime;
+      try {
+        const m = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+        if (m?.created_at) {
+          const parsed = new Date(m.created_at);
+          if (!Number.isNaN(parsed.getTime())) createdAt = parsed;
+        }
+      } catch { /* fall back to mtime */ }
+      if (!latestRelease || createdAt > latestRelease.createdAt) {
+        latestRelease = { path: manifestPath, createdAt, slug: e.name };
+      }
+    } catch { /* skip */ }
+  }
+
+  if (!latestRelease) return { isStale: false, detail: null };
+
+  // Walk workflows/ and rule_skills/ for files newer than latestRelease.createdAt.
+  // Cap to first 10 newer-than-release matches to bound report size.
+  const newerFiles = [];
+  const cutoff = latestRelease.createdAt.getTime();
+  const SCAN_DIRS = ["workflows", "rule_skills"];
+  for (const sub of SCAN_DIRS) {
+    const root = path.join(cwd, sub);
+    if (!dirExists(root)) continue;
+    const stack = [root];
+    while (stack.length && newerFiles.length < 10) {
+      const d = stack.pop();
+      let entries;
+      try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+      for (const ent of entries) {
+        if (ent.name.startsWith(".") || ent.name === "__pycache__" || ent.name === "node_modules") continue;
+        const p = path.join(d, ent.name);
+        if (ent.isDirectory()) { stack.push(p); continue; }
+        if (!ent.isFile()) continue;
+        // Care about workflow_v*.py + check.py + SKILL.md/skill.md only —
+        // not __pycache__, not test artifacts, not .json.
+        if (!/(workflow_v\d+\.py|check\.py|SKILL\.md|skill\.md)$/.test(ent.name)) continue;
+        try {
+          const st = fs.statSync(p);
+          if (st.mtimeMs > cutoff) {
+            newerFiles.push({
+              path: path.relative(cwd, p),
+              mtime: new Date(st.mtimeMs).toISOString(),
+            });
+            if (newerFiles.length >= 10) break;
+          }
+        } catch { /* skip */ }
+      }
+    }
+  }
+
+  if (newerFiles.length === 0) return { isStale: false, detail: null };
+
+  // SOFT: accept_stale_release marker bypasses the warning. Agents that
+  // intentionally accept the older release write this file.
+  const acceptPath = path.join(cwd, "output", "releases", latestRelease.slug, ".accept_stale_release");
+  if (fileExists(acceptPath)) return { isStale: false, detail: { acceptedAt: latestRelease.slug } };
+
+  return {
+    isStale: true,
+    detail: {
+      releasePath: path.relative(cwd, latestRelease.path),
+      releaseSlug: latestRelease.slug,
+      releaseCreatedAt: latestRelease.createdAt.toISOString(),
+      newerFiles,
+      totalNewerCount: newerFiles.length,
+      hint: "Workspace artifacts modified after release was built. Either re-run the release tool or write .accept_stale_release into the release dir to acknowledge.",
+    },
   };
 }
 

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

@@ -59,6 +59,10 @@ export class SkillAuthoringPipeline extends Pipeline {
     this.skillsAuthored = [...m.skillsAuthored];
     this.skillsWithScripts = [...m.skillsWithScripts];
     this.ruleIdsCovered = new Set(m.ruleIdsCovered);
+    // v0.8 P2-F (item 22): stub-shape audit for check.py files.
+    this._checkPyStubRatio = m.checkPyStubRatio || 0;
+    this._checkPyStubFiles = m.checkPyStubFiles || [];
+    this._checkPyTotal = m.checkPyTotal || 0;
   }
 
   // v0.7.0 A1: ruleId extraction moved to _milestone-derive.js
@@ -228,7 +232,32 @@ export class SkillAuthoringPipeline extends Pipeline {
     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);
+    if (this.skillsWithScripts.length < Math.max(1, this.skillsAuthored.length * 0.5)) {
+      return false;
+    }
+
+    // v0.8 P2-F (item 22): optional enforcement of check.py substantiveness.
+    // SOFT-by-default — the stub ratio is always computed (visible in
+    // describeState / events) but only blocks phase advance if
+    // KC_ENFORCE_CHECK_PY_SUBSTANTIVE=1 is set. Default-off because
+    // the heuristic may over-fire on legitimate scaffolds; v0.8 ships
+    // the detection + reporting, v0.8.x revisits enforcement after audit
+    // data shows whether the signal is reliable.
+    const enforce = process.env.KC_ENFORCE_CHECK_PY_SUBSTANTIVE === "1";
+    if (enforce && this._checkPyTotal > 0 && this._checkPyStubRatio > 0.5) {
+      this._validationFailures = this._validationFailures || [];
+      this._validationFailures.push({
+        file: "<check_py_substantiveness>",
+        reason:
+          `${this._checkPyStubCount || this._checkPyStubFiles.length}/${this._checkPyTotal} check.py files are stub-shaped ` +
+          `(return NOT_APPLICABLE / pass:null with no workflow import + ≤20 lines). ` +
+          `Examples: ${this._checkPyStubFiles.slice(0, 3).join(", ")}${this._checkPyStubFiles.length > 3 ? "..." : ""}. ` +
+          `See skill-authoring SKILL.md anti-pattern section. ` +
+          `Set KC_ENFORCE_CHECK_PY_SUBSTANTIVE=0 to bypass this gate if intentional.`,
+      });
+      return false;
+    }
+    return true;
   }
 
   /**

package/src/agent/tools/agent-tool.js

@@ -382,8 +382,8 @@ export class AgentTool extends BaseTool {
    * B8: List currently-running sub-agents. Called by engine's phase-advance
    * path to emit a `stale_subagents` pipeline event — the main agent's next
    * turn sees the list and decides whether to kill each. Soft signal, not
-   * an automated kill, because phase_advance can fire from _maybeAutoAdvance
-   * unexpectedly and coupling the lifecycle would amplify blast radius.
+   * an automated kill: coupling the subagent lifecycle to phase advance
+   * would amplify blast radius if a transition happened unexpectedly.
    */
   getRunningTaskIds() {
     return Array.from(this._runningTasks.keys());

package/src/agent/tools/consult-skill.js

@@ -63,6 +63,21 @@ export class ConsultSkillTool extends BaseTool {
     const name = (input?.name || "").trim();
     if (!name) return new ToolResult("name required (e.g. consult_skill({name: 'work-decomposition'}))", true);
 
+    // v0.8 P0-A: defensive null-check. v0.7.5 shipped with an init-order bug
+    // where ConsultSkillTool received undefined skillLoader and threw
+    // "Cannot read properties of undefined (reading 'getPhaseSkillSet')"
+    // on every invocation (资管 audit § 9.1, 5/5 failure rate). The init-order
+    // fix is in engine.js:238; this guard prevents an uncaught exception if
+    // the bug recurs from any future constructor reorder.
+    if (!this._skillLoader || typeof this._skillLoader.getPhaseSkillSet !== "function") {
+      return new ToolResult(
+        "consult_skill is misconfigured: skillLoader unavailable. This is an engine-side bug — " +
+        "surface to the developer user. The agent should fall back to reading skill bodies " +
+        "directly from <workspace>/skills/<name>/SKILL.md or the system prompt's always-loaded section.",
+        true,
+      );
+    }
+
     const phase = this._getCurrentPhase ? this._getCurrentPhase() : null;
     const { alwaysLoaded, available } = this._skillLoader.getPhaseSkillSet(phase);
 

package/src/agent/tools/dashboard-render.js

@@ -81,11 +81,57 @@ export class DashboardRenderTool extends BaseTool {
       metrics.evolution_iterations = fs.readdirSync(evoDir).filter((f) => f.endsWith(".json")).length;
     }
 
+    // v0.8 P1-G: QC counter now reads from multiple known agent-write
+    // locations + counts per-doc reviews. Pre-v0.8 read only output/qc/*.json
+    // top-level; 资管 v0.7.5 wrote output/results/production_qc_results.json
+    // so the dashboard showed `QC Batches: 0` despite 126 pairs of data.
+    let qcBatches = 0;
+    let qcDocsReviewed = 0;
+
+    // (a) Top-level batch files in output/qc/ (贷款 v0.7.5 shape)
     const qcDir = path.join(ws, "output", "qc");
     if (fs.existsSync(qcDir)) {
-      metrics.qc_batches = fs.readdirSync(qcDir).filter((f) => f.endsWith(".json")).length;
+      for (const f of fs.readdirSync(qcDir).filter((f) => f.endsWith(".json"))) {
+        qcBatches++;
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(qcDir, f), "utf-8"));
+          const n = Number(data?.documents_reviewed);
+          if (Number.isFinite(n) && n > qcDocsReviewed) qcDocsReviewed = n;
+        } catch { /* skip malformed */ }
+      }
     }
 
+    // (b) Per-doc reviews at output/qc/reviews/ (贷款 detail shape)
+    const reviewsDir = path.join(ws, "output", "qc", "reviews");
+    if (fs.existsSync(reviewsDir)) {
+      const reviewFiles = fs.readdirSync(reviewsDir).filter((f) => f.endsWith(".json"));
+      qcDocsReviewed = Math.max(qcDocsReviewed, reviewFiles.length);
+    }
+
+    // (c) production_qc_results.json shape (资管 v0.7.5)
+    const productionQc = path.join(ws, "output", "results", "production_qc_results.json");
+    if (fs.existsSync(productionQc)) {
+      qcBatches++;
+      try {
+        const data = JSON.parse(fs.readFileSync(productionQc, "utf-8"));
+        const totalDocs = Number(data?.total_docs);
+        if (Number.isFinite(totalDocs)) qcDocsReviewed = Math.max(qcDocsReviewed, totalDocs);
+        // Otherwise, dedup doc keys from nested results
+        if (!Number.isFinite(totalDocs) && data?.results && typeof data.results === "object") {
+          const docSet = new Set();
+          for (const docs of Object.values(data.results)) {
+            if (docs && typeof docs === "object") {
+              for (const k of Object.keys(docs)) docSet.add(k);
+            }
+          }
+          if (docSet.size > 0) qcDocsReviewed = Math.max(qcDocsReviewed, docSet.size);
+        }
+      } catch { /* skip */ }
+    }
+
+    metrics.qc_batches = qcBatches;
+    metrics.qc_docs_reviewed = qcDocsReviewed;
+
     return metrics;
   }
 
@@ -126,6 +172,7 @@ th { color: #737373; font-size: 0.85em; }
 <div class="metric"><span class="value">${total}</span><br><span class="label">Results</span></div>
 <div class="metric"><span class="value">${metrics.evolution_iterations}</span><br><span class="label">Evolution Cycles</span></div>
 <div class="metric"><span class="value">${metrics.qc_batches}</span><br><span class="label">QC Batches</span></div>
+<div class="metric"><span class="value">${metrics.qc_docs_reviewed || 0}</span><br><span class="label">Docs Reviewed</span></div>
 </div>
 <h2>Confidence Distribution</h2>
 <div class="card">

package/src/agent/tools/document-parse.js

@@ -12,14 +12,43 @@ const MIN_CHARS_PER_PAGE = 50;
  * Level 3: OCR models via SiliconFlow — fallback via vision models
  */
 export class DocumentParseTool extends BaseTool {
-  constructor(workspace, { mineruApiUrl, mineruApiKey, llmApiKey, llmBaseUrl, ocrModel } = {}) {
+  /**
+   * @param {object} workspace
+   * @param {object} opts
+   * @param {string} [opts.mineruApiUrl]
+   * @param {string} [opts.mineruApiKey]
+   * @param {string} [opts.llmApiKey]
+   * @param {string} [opts.llmBaseUrl]
+   * @param {string} [opts.ocrModel] — static fallback (legacy)
+   * @param {() => string} [opts.getOcrModel] — v0.8.1 P9-B: live-read
+   *   callback. If provided, takes precedence over `ocrModel`. The
+   *   constructor used to capture vlmTier1 once at engine startup, but
+   *   workspace_env_overlay (P1-B) fires AFTER tool construction in
+   *   some flows (e.g. agent edits .env mid-run, OR overlay applies on
+   *   a subagent's engine but parent already cached the gc default).
+   *   E2E #11 资管 v0.8 audit found document_parse errors quoting
+   *   Qwen3-VL-235B-A22B-Instruct (gc default) even though .env set
+   *   OCR_MODEL_TIER1=zai-org/GLM-4.6V — the overlay applied 5 min
+   *   after first failed call. Live-read fixes the race.
+   */
+  constructor(workspace, { mineruApiUrl, mineruApiKey, llmApiKey, llmBaseUrl, ocrModel, getOcrModel } = {}) {
     super();
     this._workspace = workspace;
     this._mineruApiUrl = mineruApiUrl || "";
     this._mineruApiKey = mineruApiKey || "";
     this._vlmApiKey = llmApiKey || "";
     this._vlmBaseUrl = (llmBaseUrl || "").replace(/\/+$/, "");
-    this._ocrModel = ocrModel || "";
+    this._ocrModelStatic = ocrModel || "";
+    this._getOcrModel = typeof getOcrModel === "function" ? getOcrModel : null;
+  }
+
+  /** Read ocrModel live (P9-B) or fall back to the static value captured at construction. */
+  get _ocrModel() {
+    if (this._getOcrModel) {
+      try { return this._getOcrModel() || this._ocrModelStatic; }
+      catch { return this._ocrModelStatic; }
+    }
+    return this._ocrModelStatic;
   }
 
   get name() { return "document_parse"; }

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

@@ -1,5 +1,6 @@
 import { BaseTool, ToolResult } from "./base.js";
 import { Phase } from "../pipelines/index.js";
+import { getPrescriptiveHint } from "../pipelines/_advance-hints.js";
 
 const VALID_PHASES = new Set(Object.values(Phase));
 
@@ -72,12 +73,12 @@ export class PhaseAdvanceTool extends BaseTool {
 
     const beforePhase = this._getCurrentPhase();
     // H1: short-circuit the "already in target" case with an informational
-    // message — the agent was trying to advance correctly, engine just
-    // auto-advanced ahead of it (common when _maybeAutoAdvance fires on a
-    // criteria flip). Treat as success, not refusal.
+    // message — agent was trying to advance correctly, engine was already
+    // there (from a prior pipeline_event-driven advance or an earlier
+    // explicit call). Treat as success, not refusal.
     if (beforePhase && beforePhase === to) {
       return new ToolResult(
-        `Already in phase ${to} (engine auto-advanced earlier via criteria flip or prior explicit call). Proceed with phase-appropriate work.`,
+        `Already in phase ${to} (engine was already there from a prior advance). Proceed with phase-appropriate work.`,
       );
     }
 
@@ -126,18 +127,21 @@ export class PhaseAdvanceTool extends BaseTool {
     // exactly which milestones the gate is reading and can satisfy them.
     // E2E #6 v070 showed the generic "check /status" hint wasn't concrete
     // enough — agents forced through. Naming the gap inline reduces that.
-    const engineCountsLine = advanceResult?.engineCounts
-      ? `\nEngine telemetry: ${advanceResult.engineCounts}`
-      : "";
+    // v0.8 P0-E: prescriptive refusal hint — name the artifacts the agent
+    // needs to produce, derived from the same paths _milestone-derive.js
+    // walks. Replaces the v0.7.x descriptive "check /status" message that
+    // 资管 + 贷款 v0.7.5 audits showed agents force-bypassing.
+    const prescriptive = getPrescriptiveHint(
+      beforePhase,
+      advanceResult?.engineCounts,
+      advanceResult?.engineCounts || "",
+    );
 
     return new ToolResult(
       `Did not advance to ${to} (currently in ${beforePhase || "?"}). ` +
-      `Likely cause: source-phase exit criteria not met.${engineCountsLine}\n\n` +
-      `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, ` +
+      `Likely cause: source-phase exit criteria not met.\n\n` +
+      prescriptive +
+      `\n\nIf 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,