kc-beta 0.7.3 → 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,75 @@ 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 ""; }
+}
+
+/**
+ * v0.7.5 G-H1: extract `source_rules: [...]` from YAML frontmatter.
+ *
+ * Supports both inline and block list forms:
+ *   source_rules: [R001, R005, R007]
+ *   source_rules:
+ *     - R001
+ *     - R005
+ *
+ * Used by milestone derivation to credit grouped/thematic skill folders
+ * + master workflows where the agent declares which rules are covered.
+ * Returns an array of canonical rule IDs (e.g., ["R001", "R005"]).
+ */
+function parseSourceRulesFromFrontmatter(content) {
+  if (!content || typeof content !== "string") return [];
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return [];
+  const fm = fmMatch[1];
+
+  // Inline form: source_rules: [R001, R005, "R007"]
+  const inlineMatch = fm.match(/^source_rules\s*:\s*\[([^\]]*)\]\s*$/m);
+  if (inlineMatch) {
+    return inlineMatch[1]
+      .split(",")
+      .map(s => s.trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean)
+      .map(s => canonicalRuleId(s) || s)
+      .filter(rid => /^R\d+$/i.test(rid))
+      .map(rid => rid.toUpperCase().replace(/^R0*(\d+)$/, (_, n) => `R${String(parseInt(n,10)).padStart(3,"0")}`));
+  }
+
+  // Block form: source_rules:\n  - R001\n  - R005
+  const blockMatch = fm.match(/^source_rules\s*:\s*\n((?:[ \t]+-\s+\S+\s*\n?)+)/m);
+  if (blockMatch) {
+    return blockMatch[1]
+      .split("\n")
+      .map(line => {
+        const m = line.match(/^[ \t]+-\s+["']?([^"'\s]+)["']?\s*$/);
+        return m ? m[1] : null;
+      })
+      .filter(Boolean)
+      .map(s => canonicalRuleId(s) || s)
+      .filter(rid => /^R\d+$/i.test(rid))
+      .map(rid => rid.toUpperCase().replace(/^R0*(\d+)$/, (_, n) => `R${String(parseInt(n,10)).padStart(3,"0")}`));
+  }
+
+  return [];
+}
+
 function sha256OfFile(p) {
   try {
     const buf = fs.readFileSync(p);
@@ -144,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,
@@ -239,15 +311,110 @@ export function deriveSkillAuthoringMilestones(workspace) {
         }
       }
     }
+
+    // v0.7.5 G-H1: also credit rule_ids declared in SKILL.md frontmatter
+    // `source_rules:` field. Agents using grouped/thematic skill folders
+    // (e.g., S01_compliance/, custodian_checks/) declare which rules
+    // their grouped check covers via frontmatter; engine derivation
+    // credits each declared rule_id. Audit found 资管 v0.7.4 session
+    // forced through skill_authoring → skill_testing because its 10 S*
+    // grouped folders weren't credited (rulesCovered=0/94).
+    if (hasSkillMd) {
+      try {
+        const skillMdFile = listChildFiles(skillPath).find(
+          (f) => f.name.toLowerCase() === "skill.md",
+        );
+        if (skillMdFile) {
+          const content = readFileSafe(path.join(skillPath, skillMdFile.name));
+          const sourceRules = parseSourceRulesFromFrontmatter(content);
+          for (const rid of sourceRules) ruleIdsCovered.add(rid);
+        }
+      } catch { /* best-effort */ }
+    }
   }
 
+  // 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
 // ───────────────────────────────────────────────────────────────────
@@ -362,6 +529,37 @@ export function deriveDistillationMilestones(workspace) {
   const cwd = cwdOf(workspace);
   const wfRoot = path.join(cwd, "workflows");
   const workflowsCreated = [];
+  // v0.7.5 G-H1: also track rule IDs covered by workflows. Grouped/master
+  // workflows (e.g., 贷款 v0.7.4's master + R001 template) cover multiple
+  // rules; declare them via SKILL.md frontmatter `source_rules: [...]`.
+  // Engine credits each declared rule_id so workflowsCovered milestone
+  // matches catalog reality.
+  const ruleIdsCovered = new Set();
+
+  const creditWorkflowSourceRules = (workflowDir) => {
+    // Check for a SKILL.md (or workflow.md) declaring source_rules
+    const candidates = listChildFiles(workflowDir).filter(
+      (f) => /^(skill|workflow)\.md$/i.test(f.name),
+    );
+    for (const c of candidates) {
+      const content = readFileSafe(path.join(workflowDir, c.name));
+      for (const rid of parseSourceRulesFromFrontmatter(content)) {
+        ruleIdsCovered.add(rid);
+      }
+    }
+    // Also: per-workflow config.json may declare rule coverage
+    const configPath = path.join(workflowDir, "config.json");
+    if (fileExists(configPath)) {
+      const data = readJsonSafe(configPath);
+      const rules = Array.isArray(data?.source_rules) ? data.source_rules :
+                    Array.isArray(data?.rules) ? data.rules :
+                    Array.isArray(data?.rule_ids) ? data.rule_ids : [];
+      for (const r of rules) {
+        const canon = canonicalRuleId(String(r));
+        if (canon) ruleIdsCovered.add(canon);
+      }
+    }
+  };
 
   if (dirExists(wfRoot)) {
     // Two layouts seen in E2E #5:
@@ -375,16 +573,39 @@ export function deriveDistillationMilestones(workspace) {
         const sub = path.join(wfRoot, e.name);
         const hasPy = listChildFiles(sub).some((f) =>
           /workflow.*\.py$/i.test(f.name) || /^check.*\.py$/i.test(f.name));
-        if (hasPy) workflowsCreated.push(e.name);
+        if (hasPy) {
+          workflowsCreated.push(e.name);
+          // Dir name might itself be a rule_id
+          const canon = canonicalRuleId(e.name);
+          if (canon) ruleIdsCovered.add(canon);
+          // Plus any frontmatter / config-declared source_rules
+          creditWorkflowSourceRules(sub);
+        }
         continue;
       }
       if (e.isFile()) {
         const m1 = e.name.match(/^(.+)_workflow\.py$/i);
-        if (m1) { workflowsCreated.push(m1[1]); continue; }
+        if (m1) {
+          workflowsCreated.push(m1[1]);
+          const canon = canonicalRuleId(m1[1]);
+          if (canon) ruleIdsCovered.add(canon);
+          continue;
+        }
         const m2 = e.name.match(/^(.+)\.json$/i);
         if (m2) {
           const data = readJsonSafe(path.join(wfRoot, e.name));
-          if (data && (data.rule_id || data.entry || data.type)) workflowsCreated.push(m2[1]);
+          if (data && (data.rule_id || data.entry || data.type)) {
+            workflowsCreated.push(m2[1]);
+            const canon = canonicalRuleId(data.rule_id || m2[1]);
+            if (canon) ruleIdsCovered.add(canon);
+            // Manifest-declared source_rules
+            const rules = Array.isArray(data.source_rules) ? data.source_rules :
+                          Array.isArray(data.rules) ? data.rules : [];
+            for (const r of rules) {
+              const c2 = canonicalRuleId(String(r));
+              if (c2) ruleIdsCovered.add(c2);
+            }
+          }
           continue;
         }
       }
@@ -408,7 +629,16 @@ export function deriveDistillationMilestones(workspace) {
     }
   }
 
-  return { workflowsCreated, workflowsTested };
+  return {
+    workflowsCreated,
+    workflowsTested,
+    // v0.7.5 G-H1: rule_ids the engine credits as having workflow coverage
+    // (either via dir name being a canonical rule_id, or via SKILL.md /
+    // workflow.md / config.json frontmatter declaring source_rules: [...]).
+    // Pipelines that check workflow coverage against the catalog should
+    // prefer ruleIdsCovered over workflowsCreated for grouped patterns.
+    ruleIdsCovered: [...ruleIdsCovered],
+  };
 }
 
 // ───────────────────────────────────────────────────────────────────
@@ -477,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,
   };
 }
 
@@ -522,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
@@ -558,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/initializer.js

@@ -9,7 +9,10 @@ import { deriveBootstrapMilestones } from "./_milestone-derive.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_MD_TEMPLATE = path.resolve(__dirname, "../../../template/AGENT.md");
 
-const REQUIRED_DIRS = ["rules", "samples", "input", "output", "logs", "workflows", "rule_skills"];
+// v0.7.5: `skills` added to required dirs. Populated by SkillLoader
+// .populateWorkspaceSkills() at bootstrap + on every phase transition
+// with the phase's `available` skill set (per phase_skills.yaml).
+const REQUIRED_DIRS = ["rules", "samples", "input", "output", "logs", "workflows", "rule_skills", "skills"];
 
 const DEFAULT_ENV = `# === KC Agent Project Configuration ===
 

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;
   }
 
   /**