kc-beta 0.7.5 → 0.8.1

package/src/cli/index.js

@@ -59,6 +59,8 @@ function App({ engine, config }) {
   const [spinnerStatus, setSpinnerStatus] = useState(null);
   const [contextTokens, setContextTokens] = useState(0);
   const [contextLimit, setContextLimit] = useState(config.kcContextLimit || 200000);
+  // v0.8.1 P8-A: marathon-mode indicator for StatusBar.
+  const [marathonActive, setMarathonActive] = useState(false);
   const [taskList, setTaskList] = useState([]);
   const [taskProgress, setTaskProgress] = useState(null);
 
@@ -124,6 +126,11 @@ function App({ engine, config }) {
             setCurrentTool(null);
             setSpinnerStatus(null);
             updateContextStats();
+            // v0.8.1 P8-A: refresh marathon indicator. If the driver
+            // self-terminated (max_wallclock / finalization_settled),
+            // engine clears marathonDriver on next decideNext loop;
+            // we sync the TUI state here.
+            setMarathonActive(engineRef.current.isMarathonActive());
             break;
 
           case "tool_start":
@@ -221,6 +228,9 @@ function App({ engine, config }) {
             "  /sessions            List all sessions\n" +
             "  /resume <name>       Resume a previous session\n" +
             "  /rename <name>       Rename current session\n" +
+            "  /marathon <goal>     Activate marathon mode (chains turns automatically)\n" +
+            "  /marathon off        Deactivate marathon (return to interactive)\n" +
+            "  /marathon status     Show marathon driver state\n" +
             "  /exit                Quit",
         });
         return true;
@@ -593,6 +603,84 @@ function App({ engine, config }) {
         }
         return true;
 
+      case "/marathon": {
+        // v0.8.1 P8-A: inline marathon mode. `/marathon <goal>` activates;
+        // `/marathon off` deactivates; `/marathon status` shows snapshot.
+        const sub = arg.split(/\s+/)[0]?.toLowerCase();
+        if (sub === "off" || sub === "stop") {
+          const final = engineRef.current.exitMarathonMode("user_off");
+          setMarathonActive(false);
+          if (final) {
+            addMessage({
+              role: "system",
+              content: `Marathon mode OFF.\n  decisions: ${final.decisionCount}\n  runtime: ${Math.round(final.runtimeMs / 1000)}s\n  last phase: ${final.currentPhase}`,
+            });
+          } else {
+            addMessage({ role: "system", content: "Marathon was not active." });
+          }
+          return true;
+        }
+        if (sub === "status") {
+          if (!engineRef.current.isMarathonActive()) {
+            addMessage({ role: "system", content: "Marathon mode is OFF." });
+            return true;
+          }
+          const s = engineRef.current.marathonDriver.getStatus();
+          const lines = [
+            `Marathon mode ON`,
+            `  goal: ${s.goal.slice(0, 100)}${s.goal.length > 100 ? "..." : ""}`,
+            `  language: ${s.language}`,
+            `  started: ${s.startedAt}  (${Math.round(s.runtimeMs / 60000)} min ago)`,
+            `  current_phase: ${s.currentPhase}`,
+            `  turns this phase: ${s.turnsThisPhase}`,
+            `  total decisions: ${s.decisionCount}`,
+          ];
+          if (s.recentDecisions?.length) {
+            lines.push(`  recent decisions:`);
+            for (const d of s.recentDecisions.slice(-3)) {
+              lines.push(`    ${d.ts.slice(11, 19)} [${d.template}] ${d.reason}`);
+            }
+          }
+          addMessage({ role: "system", content: lines.join("\n") });
+          return true;
+        }
+        // `/marathon <goal>` — activate
+        if (!arg) {
+          addMessage({
+            role: "system",
+            content:
+              "Usage:\n" +
+              "  /marathon <goal description>   Activate marathon mode with the given goal\n" +
+              "  /marathon off                  Deactivate (return to interactive)\n" +
+              "  /marathon status               Show current driver state\n\n" +
+              "Marathon mode chains turns automatically using templated continuation prompts.\n" +
+              "F5 strict one-phase-per-prompt is bypassed while active. /resume after a crash\n" +
+              "does NOT auto-restore marathon — re-type /marathon to re-engage.",
+          });
+          return true;
+        }
+        try {
+          const status = engineRef.current.enterMarathonMode(arg);
+          setMarathonActive(true);
+          addMessage({
+            role: "system",
+            content:
+              `🏃 Marathon mode ON.\n` +
+              `  goal: ${arg.slice(0, 200)}${arg.length > 200 ? "..." : ""}\n` +
+              `  language: ${status.language}\n` +
+              `  stop conditions: ${Math.round(status.maxWallclockMs / 3600000)}h wall-clock OR 5 turns settled in finalization\n\n` +
+              `Next turn will use the marathon initial prompt. Type /marathon off to disengage.`,
+          });
+          // Immediately trigger a turn with the initial prompt
+          const initialPrompt = engineRef.current.marathonDriver.getInitialPrompt();
+          // Hand the initial prompt to the same runTurn path as a user message
+          runTurn(initialPrompt);
+        } catch (e) {
+          addMessage({ role: "system", content: `Marathon activation failed: ${e.message}` });
+        }
+        return true;
+      }
+
       case "/exit":
       case "/quit":
         // Save state + stop diagnostics before exit
@@ -752,7 +840,7 @@ function App({ engine, config }) {
       placeholderRight: queueSize > 0 ? `(${queueSize} queued)` : null,
     }),
     h(HRule),
-    h(StatusBar, { sessionId, phase, contextTokens, contextLimit }),
+    h(StatusBar, { sessionId, phase, contextTokens, contextLimit, marathonActive }),
   );
 }
 
@@ -821,6 +909,14 @@ export async function main({ languageOverride } = {}) {
   };
   process.on("SIGINT", saveOnExit);
   process.on("SIGTERM", saveOnExit);
+  // v0.8.1 P8-B: SIGHUP coverage. E2E #11 found macOS sends signals to
+  // descendant processes when a Terminal.app window closes or quits;
+  // nohup masks SIGHUP but not SIGTERM, and we already cover SIGTERM.
+  // Adding SIGHUP makes the kc-beta process robust against terminal
+  // teardown even if it's not nohup'd. Without this, a closed terminal
+  // can leave KC half-shut-down (events.jsonl flushed, but no
+  // marathon_detach event, no clean session-state save).
+  process.on("SIGHUP", saveOnExit);
 
   const instance = render(h(App, { engine, config }));
   await instance.waitUntilExit();

package/src/config.js

@@ -21,7 +21,11 @@ function loadGlobalConfig() {
  * Parse a .env file into a key-value object.
  * Handles KEY=VALUE lines, ignores comments and blank lines.
  */
-function loadEnvFile(envPath) {
+// v0.8 P1-B: exported so engine.js can re-overlay workspace .env after
+// the workspace directory is known (cli/index.js calls loadSettings()
+// without a workspace path because the path isn't known until the engine
+// constructs the Workspace object).
+export function loadEnvFile(envPath) {
   if (!fs.existsSync(envPath)) return {};
   // v0.7.0 H9: defend bootstrap against a .env that exists but isn't
   // readable (permission denied, unexpected directory, encoding error,
@@ -110,7 +114,20 @@ export function loadSettings(workspacePath) {
 
     // Workspace (process.env wins — for parallel benchmark runs)
     kcWorkspaceRoot: penv.KC_WORKSPACE_ROOT || gc.workspace_root || path.join(os.homedir(), ".kc_agent", "workspaces"),
-    kcExecTimeout: parseInt(env.KC_EXEC_TIMEOUT || "30", 10),
+    // v0.8 P1-F sandbox_exec timeout model. Default 120s (Claude Code parity),
+    // max 600s (10 min) ceiling. Agent can pass per-call timeout_ms up to max.
+    // Legacy KC_EXEC_TIMEOUT (seconds) accepted as deprecation alias for default.
+    kcExecDefaultTimeoutMs: parseInt(
+      env.KC_EXEC_DEFAULT_TIMEOUT_MS ||
+      (env.KC_EXEC_TIMEOUT ? String(parseInt(env.KC_EXEC_TIMEOUT, 10) * 1000) : "") ||
+      "120000",
+      10,
+    ),
+    kcExecMaxTimeoutMs: parseInt(env.KC_EXEC_MAX_TIMEOUT_MS || "600000", 10),
+    // Legacy alias kept for any consumer reading it directly. Computed
+    // from the new ms-based field for consistency. New code should read
+    // kcExecDefaultTimeoutMs / kcExecMaxTimeoutMs.
+    kcExecTimeout: parseInt(env.KC_EXEC_TIMEOUT || "120", 10),
 
     // Accuracy thresholds
     skillAccuracy: parseFloat(env.SKILL_ACCURACY || gc.accuracy_threshold?.toString() || "0.9"),

package/src/marathon/driver.js

@@ -0,0 +1,217 @@
+// v0.8.1 P8-A — marathon driver as inline state machine.
+//
+// v0.8.0 shipped this as a separate-process driver (bin/kc-marathon.js)
+// that tailed events.jsonl + wrote prompts to .kc_marathon/inbox.jsonl.
+// E2E #11 audits found both drivers died silently within 10 min when
+// the terminal closed or laptop slept (SIGHUP/SIGTERM unhandled). The
+// engine survived both deaths because it lives in a different process.
+//
+// v0.8.1 redesign per user proposal (2026-05-15):
+//   - Single process: driver runs inline as part of the engine
+//   - Activated via `/marathon <goal>` slash command in kc-beta TUI
+//   - Engine calls decideNext(state) after each turn_complete to get
+//     the next continuation prompt (or null if marathon should end)
+//   - No filesystem IPC (no inbox, no active marker, no state.json)
+//   - State persists via engine's existing session-state.json
+//
+// The state machine logic from v0.8.0 is preserved verbatim — only
+// the I/O wrapper changes. Templates (renderPrompt) unchanged.
+
+import { renderPrompt } from "./prompts.js";
+
+const DEFAULT_STUCK_AFTER_MS = 30 * 60 * 1000;        // 30 min
+const DEFAULT_MAX_WALLCLOCK_MS = 12 * 60 * 60 * 1000; // 12 h
+
+export class MarathonDriver {
+  /**
+   * @param {object} opts
+   * @param {string} opts.goal — the marathon goal-description prompt
+   * @param {string} [opts.language] — "en" or "zh"
+   * @param {number} [opts.maxWallclockMs] — stop after this much wall time
+   * @param {number} [opts.stuckAfterMs] — emit unstick prompt after idle
+   */
+  constructor(opts = {}) {
+    if (!opts.goal || typeof opts.goal !== "string") {
+      throw new Error("MarathonDriver requires a non-empty `goal` string");
+    }
+    this.goal = opts.goal;
+    this.language = opts.language === "zh" ? "zh" : "en";
+    this.maxWallclockMs = opts.maxWallclockMs ?? DEFAULT_MAX_WALLCLOCK_MS;
+    this.stuckAfterMs = opts.stuckAfterMs ?? DEFAULT_STUCK_AFTER_MS;
+
+    this.startedAt = Date.now();
+    this.lastDecisionAt = 0;
+    this.decisionCount = 0;
+    this.currentPhase = "bootstrap";
+    this.lastMilestones = {};
+    this.turnsThisPhase = 0;
+    this.lastEventTs = Date.now();
+    this.initialDelivered = false;
+    this.stopped = false;
+    this.stopReason = null;
+
+    // Decision history (kept in-memory; surfaced in /marathon status).
+    // Bounded to last 100 to cap memory.
+    this.decisions = [];
+  }
+
+  /**
+   * Engine calls this once BEFORE the initial turn after /marathon was
+   * typed. Returns the goal-description prompt to feed into runTurn.
+   */
+  getInitialPrompt() {
+    const out = renderPrompt(
+      "initial",
+      this._stateSnapshot(),
+      this.language,
+    );
+    this._recordDecision("initial", "marathon kickoff", out);
+    this.initialDelivered = true;
+    return out;
+  }
+
+  /**
+   * Engine calls decideNext(state) after each turn_complete event.
+   * Returns { prompt, template, reason } if marathon should continue,
+   * or null if a stop condition is met (engine will exit marathon mode).
+   *
+   * @param {object} state — engine snapshot:
+   *   {currentPhase, milestones, phaseChanged, errorSeen, turnsThisPhase}
+   */
+  decideNext(state = {}) {
+    if (this.stopped) return null;
+
+    // Update tracked state from engine
+    if (state.currentPhase && state.currentPhase !== this.currentPhase) {
+      this.currentPhase = state.currentPhase;
+      this.turnsThisPhase = 0;
+    }
+    if (state.milestones) this.lastMilestones = state.milestones;
+    if (typeof state.turnsThisPhase === "number") {
+      this.turnsThisPhase = state.turnsThisPhase;
+    } else {
+      this.turnsThisPhase += 1;
+    }
+    this.lastEventTs = Date.now();
+
+    // Stop conditions
+    if (this._shouldStop()) {
+      this.stopped = true;
+      // Emit one final "stop" prompt so the agent has a chance to wrap up.
+      const out = renderPrompt("stop", this._stateSnapshot(), this.language);
+      this._recordDecision("stop", this.stopReason, out);
+      return { prompt: out, template: "stop", reason: this.stopReason };
+    }
+
+    let template = "continue_phase";
+    let reason = "turn_complete in same phase";
+
+    if (state.errorSeen) {
+      template = "unstick";
+      reason = "engine emitted error event";
+    } else if (state.phaseChanged) {
+      if (this.currentPhase === "finalization") {
+        template = "finalize";
+        reason = "reached finalization";
+      } else {
+        template = "continue_phase";
+        reason = `entered ${this.currentPhase}`;
+      }
+    } else {
+      const idleMs = Date.now() - this.lastEventTs;
+      if (idleMs > this.stuckAfterMs) {
+        template = "unstick";
+        reason = `idle for ${Math.round(idleMs / 60000)} min`;
+      }
+    }
+
+    const out = renderPrompt(template, this._stateSnapshot(), this.language);
+    this._recordDecision(template, reason, out);
+    return { prompt: out, template, reason };
+  }
+
+  /** User-invoked manual stop (e.g., `/marathon off`). */
+  stop(reason = "user_off") {
+    this.stopped = true;
+    this.stopReason = reason;
+    this._recordDecision("manual_stop", reason, "");
+  }
+
+  /** Snapshot for /marathon status command + audit. */
+  getStatus() {
+    return {
+      active: !this.stopped,
+      goal: this.goal,
+      language: this.language,
+      startedAt: new Date(this.startedAt).toISOString(),
+      runtimeMs: Date.now() - this.startedAt,
+      currentPhase: this.currentPhase,
+      turnsThisPhase: this.turnsThisPhase,
+      decisionCount: this.decisionCount,
+      lastDecisionAt: this.lastDecisionAt ? new Date(this.lastDecisionAt).toISOString() : null,
+      stopReason: this.stopReason,
+      maxWallclockMs: this.maxWallclockMs,
+      stuckAfterMs: this.stuckAfterMs,
+      recentDecisions: this.decisions.slice(-5),
+    };
+  }
+
+  /** Serialize for session-state.json persistence (NOT used for auto-resume per user-locked decision; included for audit visibility only). */
+  toJSON() {
+    return {
+      goal: this.goal,
+      language: this.language,
+      maxWallclockMs: this.maxWallclockMs,
+      stuckAfterMs: this.stuckAfterMs,
+      startedAt: this.startedAt,
+      currentPhase: this.currentPhase,
+      turnsThisPhase: this.turnsThisPhase,
+      decisionCount: this.decisionCount,
+      initialDelivered: this.initialDelivered,
+      stopped: this.stopped,
+      stopReason: this.stopReason,
+      // Note: decisions array not persisted (memory-only)
+    };
+  }
+
+  // ─── internals ──────────────────────────────────────────────────
+
+  _stateSnapshot() {
+    return {
+      goal: this.goal,
+      currentPhase: this.currentPhase,
+      milestones: this.lastMilestones,
+      idleSec: Math.round((Date.now() - this.lastEventTs) / 1000),
+      lastEventType: this._lastEventType || null,
+    };
+  }
+
+  _shouldStop() {
+    if (this.stopped) return true;
+    if (Date.now() - this.startedAt > this.maxWallclockMs) {
+      this.stopReason = "max_wallclock";
+      return true;
+    }
+    if (
+      this.currentPhase === "finalization" &&
+      this.turnsThisPhase >= 5
+    ) {
+      this.stopReason = "finalization_settled";
+      return true;
+    }
+    return false;
+  }
+
+  _recordDecision(template, reason, prompt) {
+    this.decisionCount += 1;
+    this.lastDecisionAt = Date.now();
+    this.decisions.push({
+      ts: new Date().toISOString(),
+      template,
+      reason,
+      currentPhase: this.currentPhase,
+      promptPreview: (prompt || "").slice(0, 200),
+    });
+    if (this.decisions.length > 100) this.decisions.shift();
+  }
+}

package/src/marathon/prompts.js

@@ -0,0 +1,93 @@
+// v0.8 P4 — templated continuation prompts for the marathon driver.
+//
+// Driver state → prompt template mapping. Templates are deterministic
+// (no LLM in the driver), bilingual (en + zh per workspace LANGUAGE).
+// Goal: surface to KC's main conductor the smallest useful nudge to
+// keep the pipeline moving without leaking marathon-implementation
+// details into the agent's context.
+//
+// Each template is a function (engineState, goal) → string. State
+// fields used:
+//   currentPhase, milestones, idleSec, lastEventType, goal
+//
+// Add new templates here as the driver state machine grows.
+
+const TEMPLATES_EN = {
+  initial: (s) => `Goal: ${s.goal}\n\n` +
+    `You are running in marathon mode (no manual user check-ins). Advance the pipeline phase by phase. ` +
+    `Engine derives milestones from filesystem facts; produce real artifacts, then call phase_advance. ` +
+    `If you get stuck on a specific phase, surface the blocker in your next response and the driver will ` +
+    `inject a diagnostic prompt next turn.`,
+
+  continue_phase: (s) => `Continue with ${s.currentPhase} work. ` +
+    `Engine status: ${formatMilestones(s.milestones)}.`,
+
+  advance_phase: (s) => `${s.currentPhase} milestones look complete (${formatMilestones(s.milestones)}). ` +
+    `Verify the gate conditions then call \`phase_advance\` to the next phase.`,
+
+  unstick: (s) => `No phase progress in the last ${Math.round(s.idleSec / 60)} minutes. ` +
+    `Either (1) surface the blocker explicitly so the developer user can intervene, or (2) ` +
+    `consult the relevant meta-skill for the current phase and try a different approach. ` +
+    `If you've genuinely finished and the engine gate is wrong, force phase_advance with reason.`,
+
+  finalize: (s) => `You've reached finalization. Wrap the deliverable bundle: ` +
+    `verify rule_skills/coverage_report.md is substantive, output/releases/<slug>/ is current ` +
+    `(re-run release tool if workflows changed after the last snapshot), and final_dashboard.html ` +
+    `reflects the latest QC data. When done, just say so — the marathon will exit.`,
+
+  stop: () => `Marathon stop condition reached. Save state and summarize what was accomplished.`,
+};
+
+const TEMPLATES_ZH = {
+  initial: (s) => `目标：${s.goal}\n\n` +
+    `你正运行在 marathon 模式（无人工 check-in）。按阶段推进整条流水线。` +
+    `引擎从文件系统事实派生里程碑；先把真实交付物产出来，再调用 phase_advance。` +
+    `如果在某个阶段卡住了，直接在下一回合的回复里把阻塞点说清楚，驱动器会在下一回合注入诊断提示。`,
+
+  continue_phase: (s) => `继续 ${s.currentPhase} 阶段的工作。` +
+    `引擎状态：${formatMilestones(s.milestones)}。`,
+
+  advance_phase: (s) => `${s.currentPhase} 阶段的里程碑看起来已经完成（${formatMilestones(s.milestones)}）。` +
+    `核对一遍门控条件，然后调用 \`phase_advance\` 进入下一阶段。`,
+
+  unstick: (s) => `已经 ${Math.round(s.idleSec / 60)} 分钟没有阶段推进了。` +
+    `两条路：(1) 明确说出阻塞在哪里、让开发者用户介入；(2) 查阅当前阶段相关的 meta-skill 换个思路再试。` +
+    `如果你确实已经做完、但引擎门控判断错误，用 reason 强制 phase_advance。`,
+
+  finalize: (s) => `已经进入 finalization。收尾打包：` +
+    `确认 rule_skills/coverage_report.md 内容充实、output/releases/<slug>/ 是最新的（` +
+    `如果 workflows 在最近一次快照之后还有改动，重新跑 release 工具），final_dashboard.html 反映最新 QC 数据。` +
+    `做完之后直接说一声，marathon 会退出。`,
+
+  stop: () => `Marathon 停止条件已触发。保存状态、总结已完成的工作。`,
+};
+
+function formatMilestones(m) {
+  if (!m || typeof m !== "object") return "(unknown)";
+  const parts = [];
+  for (const [k, v] of Object.entries(m)) {
+    if (typeof v === "number") parts.push(`${k}:${v}`);
+    else if (typeof v === "boolean") parts.push(`${k}:${v ? "yes" : "no"}`);
+    else if (Array.isArray(v)) parts.push(`${k}:${v.length}`);
+  }
+  return parts.slice(0, 6).join(", ") || "(empty)";
+}
+
+/**
+ * Render a continuation prompt for the given driver state.
+ *
+ * @param {string} templateKey — one of: initial, continue_phase, advance_phase, unstick, finalize, stop
+ * @param {object} state — {goal, currentPhase, milestones, idleSec, lastEventType}
+ * @param {string} [language] — "en" or "zh" (defaults to "en")
+ * @returns {string}
+ */
+export function renderPrompt(templateKey, state, language = "en") {
+  const tmpls = language === "zh" ? TEMPLATES_ZH : TEMPLATES_EN;
+  const tmpl = tmpls[templateKey];
+  if (!tmpl) {
+    throw new Error(`Unknown marathon prompt template: ${templateKey}`);
+  }
+  return tmpl(state);
+}
+
+export const PROMPT_TEMPLATES = Object.freeze(Object.keys(TEMPLATES_EN));

package/template/.env.template

@@ -29,3 +29,19 @@ MONITOR_FREQUENCY=mid
 # === Evolution Control ===
 # Maximum evolution iterations per rule before escalating to developer user
 MAX_ITERATIONS=20
+
+# === sandbox_exec Timeout (v0.8 P1-F) ===
+# Default timeout when the agent doesn't pass timeout_ms (ms).
+# Claude Code parity = 120000 (2 min). Raise if your default workloads
+# routinely exceed 2 min (e.g., document-parsing benchmarks).
+# KC_EXEC_DEFAULT_TIMEOUT_MS=120000
+#
+# Hard ceiling — agent's timeout_ms is clamped to this (ms). Raise for
+# v0.9 jyppx integration where parser_building can take 10-30 min per
+# corpus. Don't go above 1800000 (30 min) without a specific reason.
+# KC_EXEC_MAX_TIMEOUT_MS=600000
+#
+# Legacy alias (seconds) for KC_EXEC_DEFAULT_TIMEOUT_MS. Deprecated as of
+# v0.8 — prefer the ms-based name. The seconds value is multiplied by
+# 1000 if KC_EXEC_DEFAULT_TIMEOUT_MS isn't set.
+# KC_EXEC_TIMEOUT=120

package/template/skills/en/bootstrap-workspace/SKILL.md

@@ -73,6 +73,20 @@ Once a project is past bootstrap and into production, fresh documents often arri
 
 Discuss the cadence with the developer user during bootstrap — knowing the production input rhythm shapes how skills and workflows should be written (batch vs streaming, idempotency requirements, etc.).
 
+## Per-project memory: keep AGENT.md alive
+
+`AGENT.md` at the workspace root has per-project memory sections (`Project`, `Decisions`, `Domain Notes`, `User Preferences`). These are intentionally placeholder comments at bootstrap — they're for YOU to fill in as the work surfaces things worth remembering across phases or future sessions.
+
+What belongs there:
+- **Project**: corpus identity (regulation name + scope), language, primary vs auxiliary rules, sample doc set composition.
+- **Decisions**: design choices that aren't obvious from code — "non-标 35% limit is bank-level not per-product, so single-doc reports get WARNING not FAIL", "季报 not applicable for R02-06/R02-08 per regulation §39", etc.
+- **Domain Notes**: regulatory or business-domain nuance worth surfacing — "PT/RT/LZ are three distinct product types with different disclosure templates", terminology disambiguation.
+- **User Preferences**: how the developer user wants you to operate on THIS project — verbosity, naming conventions, when to ask vs proceed.
+
+Update AGENT.md at natural checkpoints: after the developer user gives you a substantive clarification, after you finish a phase, after you discover a design constraint that affects subsequent phases. Don't wait for a `/remember` instruction — the memory is yours to maintain.
+
+A future session resumes by reading AGENT.md first. The richer it is, the less re-explanation the developer user has to do.
+
 ## When to Re-Bootstrap
 
 Return to this skill when:

package/template/skills/en/quality-control/SKILL.md

@@ -121,6 +121,15 @@ There are two distinct dashboards in this system:
 
 When a release is built, point end users at the bundled dashboard, not the workspace one. Workspace dashboard stays your developer surface.
 
+## Re-release after substantive changes
+
+A release bundle is a snapshot of `workflows/` and `rule_skills/` at the moment the `release` tool ran. If you modify any `workflows/<rule>/workflow_v*.py`, `rule_skills/<id>/SKILL.md`, or `check.py` AFTER the release was built, the shipped artifact no longer reflects your actual work. Engine's milestone derivation will surface `releaseIsStale: true` with the divergent file list.
+
+When this fires:
+- **Substantive change** (new hybrid path, fixed verdict logic, added rule): re-run the `release` tool to produce a fresh bundle.
+- **Cosmetic edit only** (typo, comment, formatting): write `.accept_stale_release` into the release directory to acknowledge — `touch output/releases/<slug>/.accept_stale_release`.
+- **DON'T** declare finalization done while a stale release ships. Downstream consumers (other agents, deployed verification systems) read the bundled `parser_v*.py` / `workflows/`, not the workspace.
+
 ## Developer User Involvement
 
 The developer user should see QC results through the dashboard (see `dashboard-reporting`). Key metrics to surface:

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

@@ -28,6 +28,8 @@ 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.
 
+**Filename case matters.** Use uppercase `SKILL.md` (matching the meta-skill convention you see in `template/skills/`). On Linux filesystems this is case-sensitive; engine path-matching, audit scripts, and downstream tooling all assume uppercase. Do not write `skill.md`, `Skill.md`, or any other case variant.
+
 ## 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:
@@ -47,6 +49,25 @@ E2E #4 demonstrated the cost: an agent wrote `unified_qc.py` to bypass 110 indiv
 
 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.
 
+### Anti-pattern: stub SKILL.md OR stub check.py
+
+Each rule_skill folder MUST have BOTH a substantive `SKILL.md` AND a substantive `check.py` (or `check.py` that imports + calls a workflow that does the real work). One side being a stub breaks the contract.
+
+**Variant 1 (v0.7.5 贷款 audit § 9.1)**: stub `SKILL.md` (templated 19 lines with `检查逻辑: N/A`) paired with real `check.py` (44-131 LOC of regex methodology). SKILL.md is supposed to be the human-readable methodology document. A reader scanning the rule folder for "what does this verify and why" gets nothing. The agent put all the methodology into `check.py` comments, which works for the engine but loses the deliverable framing.
+
+**Variant 2 (v0.7.5 资管 audit § 3.4)**: substantive `SKILL.md` (real methodology, PASS/FAIL criteria, regulation cross-refs) paired with stub `check.py` (29-line scaffold returning `{"verdict": "NOT_APPLICABLE", "evidence": "Check requires worker LLM execution"}`). The real check logic lives in `workflows/<rule_id>/workflow.py` — but `check.py` doesn't import or call it. A user running `python rule_skills/R01-01/check.py document.txt` gets `NOT_APPLICABLE` on every input, which is misleading.
+
+**Variant 3 (legacy v0.7.0)**: stub `check.py` returning `{"pass": null, "method": "stub"}` paired with otherwise-real SKILL.md. Methodology described but never executable.
+
+**The contract**:
+- ✓ DO: SKILL.md describes WHAT to check + WHY + WHEN to flag it. Substantive — typically 50-300 lines, not 19.
+- ✓ DO: check.py implements the check. EITHER substantive direct logic OR `from workflows.<rule_id>.workflow_v1 import verify` + delegate. Returns concrete verdicts.
+- ✗ DON'T: stub SKILL.md with methodology in check.py comments (variant 1).
+- ✗ DON'T: substantive SKILL.md with check.py that returns NOT_APPLICABLE without delegating to a workflow (variant 2).
+- ✗ DON'T: stub check.py returning null verdict (variant 3, legacy).
+
+A future engine milestone check (v0.8 P2-F) may refuse phase advance if too many check.py files are stub-shaped. Better to author them substantively now.
+
 ## Writing SKILL.md
 
 ### Frontmatter
@@ -102,6 +123,24 @@ Scripts should be self-contained Python files that can be imported or executed.
 
 Do not put LLM prompts in scripts. LLM interactions belong in the SKILL.md body or in the workflow (later phase).
 
+### Strip reviewer annotations before keyword matching
+
+Sample documents often carry reviewer-annotation footers (`预期命中点: ...`, `标注: ...`, `Expected: ...`) that mark the ground-truth verdict for testing. If your check.py uses keyword/regex matching against the document body, these annotations will leak into the match — producing false-positive PASS on violation samples (your rule "finds" the disclosure keyword inside the annotation itself, not the actual document content).
+
+The canonical helper ships at `workflows/common/utils.py` and is auto-populated into every workspace at engine init:
+
+```python
+from workflows.common.utils import strip_annotations
+
+def check(document_text):
+    text = strip_annotations(document_text)
+    # ... your real check logic against `text`, not document_text
+```
+
+Recognized prefixes (Chinese + English variants): 预期命中点, 预期结果, 预期判定, 预期验证, 标注, 审核标注, Expected, expected, EXPECTED, Annotation, annotation. Pass `extra_prefixes=("..."、"...")` if your project uses different labels.
+
+E2E #11 贷款 v0.8 audit: 4/14 rules had standalone check.py false-positive PASS on violation samples because they matched the `预期命中点: ...年化利率` footer instead of the document body. v0.8.1 ships the helper as a template file so this trap is one import away from being avoided.
+
 ## Writing References
 
 `references/` holds content that the coding agent reads on demand:

package/template/skills/en/skill-to-workflow/SKILL.md

@@ -187,3 +187,56 @@ Worker LLMs are accessed via SiliconFlow API. Connection details are in `.env`:
 - Model names in `TIER1` through `TIER4`
 
 See `references/worker-llm-catalog.md` for current model capabilities and context window sizes.
+
+## Two access paths: `worker_llm_call` tool (preferred) vs direct HTTP
+
+KC ships a `worker_llm_call` tool. Use it whenever possible — the engine sees every call, can track cost + token spend, applies rate limiting, and surfaces in audit. v0.8 P2-B added a batch mode:
+
+```
+worker_llm_call({
+  tier: "tier1",
+  prompts: ["check doc A...", "check doc B...", "check doc C..."],
+  system_prompt: "You are a compliance assistant. Reply with JSON {verdict, evidence, confidence}.",
+  concurrency: 5    // 1-10, default 5
+})
+```
+
+Returns a `{n_total, n_succeeded, n_failed, total_tokens_in, total_tokens_out, results: [...]}` summary. Partial failures don't fail the whole batch.
+
+### The canonical `workflows/common/llm_client.py` (v0.8.1 — ship from template)
+
+For a workflow that runs **standalone** (no KC session — e.g., a customer deploys the release bundle and runs `python run.py doc.pdf`), the workflow has no access to `worker_llm_call`. The canonical HTTP client shim ships as a template file and is auto-populated into every workspace's `workflows/common/llm_client.py` at engine init. **Do not write your own.** Use the file that's already there:
+
+```python
+from workflows.common.llm_client import call
+
+result = call(
+    tier="tier2",
+    prompt=user_prompt,
+    system_prompt="You are a compliance assistant. Reply with JSON.",
+    max_tokens=2048,
+)
+# result = {"response": "...", "model_used": "...", "tier": "tier2",
+#          "tokens_in": N, "tokens_out": N}
+```
+
+What the shim does:
+- Reads `LLM_API_KEY` + `LLM_BASE_URL` + `TIER1..4` from `.env` (provider-agnostic — works with SiliconFlow, OpenAI, Anthropic, Aliyun, etc.)
+- Sends OpenAI-format chat completions to the configured base URL
+- Writes a line to `output/llm_ledger.jsonl` per call so KC audits can reconstruct cost even when worker_llm_call wasn't used
+- Raises an explicit error if `LLM_BASE_URL` is missing (no silent fallback to a hardcoded vendor)
+
+**Don't write your own llm_client.py from scratch.** Three v0.7.x/v0.8 sessions in a row had agents roll their own shim — buggy (stale model IDs, hardcoded SiliconFlow URL, no ledger) and invisible to the engine. Use the canonical shim; if it's missing for some reason, copy it from `template/workflows/common/llm_client.py` in the kc-beta install (the engine also auto-populates at init — check `workflows_common_populated` event in events.jsonl).
+
+## sandbox_exec timeout for known-slow commands
+
+Default `sandbox_exec` timeout is 120 seconds. For commands you expect to take longer — LLM batch processing, large regression runs, document parsing — pass an explicit `timeout_ms` (up to 600000ms = 10 minutes). Don't fight the default by re-batching artificially small chunks; that wastes turns and obscures intent.
+
+```
+sandbox_exec({
+  command: "python scripts/v2_full_test.py",
+  timeout_ms: 480000   // 8 minutes for 14 rules × 6 docs through worker LLM
+})
+```
+
+If you're at the 10-minute ceiling and still timing out, split the work into multiple invocations OR delegate to a subagent (subagent timeouts are independent of the parent's).