kc-beta 0.7.1 → 0.7.3

package/src/agent/tools/task-board.js

@@ -0,0 +1,194 @@
+import { BaseTool, ToolResult } from "./base.js";
+
+const TASKS_REL = "tasks.json";
+
+/**
+ * v0.7.3 — TaskCreate / TaskUpdate / TaskComplete tools.
+ *
+ * Completes the v0.7.0 "agent owns TaskBoard" design. The engine no longer
+ * auto-populates per-rule tasks on phase entry (PER_RULE_PHASES is empty by
+ * default — see task-manager.js); the agent reads the rule list via
+ * describeState, picks a decomposition (single / grouped / range / non-rule),
+ * and calls these tools to populate tasks.json. The Ralph loop in
+ * AgentEngine._runTaskLoopSerial then walks pending tasks one at a time.
+ *
+ * Skill teaching for these tools lives in
+ * template/skills/{en,zh}/meta-meta/work-decomposition/SKILL.md.
+ *
+ * tasks.json is a shared-coordination path (workspace.js
+ * SHARED_COORDINATION_PATHS) — every write goes through
+ * withSharedLockIfApplicable so two writers (main + subagent) serialize.
+ */
+
+export class TaskCreateTool extends BaseTool {
+  constructor(workspace, taskManager) {
+    super();
+    this._workspace = workspace;
+    this._taskManager = taskManager;
+  }
+
+  get name() { return "TaskCreate"; }
+
+  get description() {
+    return (
+      "Add a task to the session task board. Tasks gate the Ralph loop — " +
+      "after the current turn ends, the engine pulls the next pending task " +
+      "and runs it. Use one task per unit of work you want to iterate on " +
+      "(per-rule, per-group, per-document — your decomposition). " +
+      "Call this on phase entry after reading describeState."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique task ID within this session (e.g. 'R001-skill_authoring' or 'group-trust-1').",
+        },
+        title: {
+          type: "string",
+          description: "Short human-readable title for the task.",
+        },
+        phase: {
+          type: "string",
+          description: "Phase this task belongs to (e.g. 'skill_authoring', 'skill_testing', 'distillation').",
+        },
+        ruleId: {
+          type: "string",
+          description: "Optional rule_id if this is a per-rule task. Omit for grouped or non-rule tasks.",
+        },
+      },
+      required: ["id", "title", "phase"],
+    };
+  }
+
+  async execute(input) {
+    const id = input.id || "";
+    const title = input.title || "";
+    const phase = input.phase || "";
+    const ruleId = input.ruleId || null;
+
+    if (!id) return new ToolResult("id required", true);
+    if (!title) return new ToolResult("title required", true);
+    if (!phase) return new ToolResult("phase required", true);
+
+    return await this._workspace.withSharedLockIfApplicable(TASKS_REL, () => {
+      const before = this._taskManager.getAllTasks().some((t) => t.id === id);
+      this._taskManager.addTask({ id, title, phase, ruleId });
+      if (before) {
+        return new ToolResult(`Task ${id} already existed (no-op).`);
+      }
+      const p = this._taskManager.progress;
+      return new ToolResult(
+        `Task ${id} created. Board: ${p.pending} pending, ${p.inProgress} in_progress, ${p.completed} completed.`,
+      );
+    });
+  }
+}
+
+export class TaskUpdateTool extends BaseTool {
+  constructor(workspace, taskManager) {
+    super();
+    this._workspace = workspace;
+    this._taskManager = taskManager;
+  }
+
+  get name() { return "TaskUpdate"; }
+
+  get description() {
+    return (
+      "Update a task's status and optional summary. Status: 'pending', " +
+      "'in_progress', 'completed', or 'failed'. Use TaskComplete instead " +
+      "for the common case of marking a task done with a summary."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Task ID to update." },
+        status: {
+          type: "string",
+          enum: ["pending", "in_progress", "completed", "failed"],
+          description: "New status for the task.",
+        },
+        summary: {
+          type: "string",
+          description: "Optional short summary (e.g. why the task failed, what was produced).",
+        },
+      },
+      required: ["id"],
+    };
+  }
+
+  async execute(input) {
+    const id = input.id || "";
+    const status = input.status;
+    const summary = input.summary;
+
+    if (!id) return new ToolResult("id required", true);
+
+    return await this._workspace.withSharedLockIfApplicable(TASKS_REL, () => {
+      const exists = this._taskManager.getAllTasks().some((t) => t.id === id);
+      if (!exists) return new ToolResult(`Task ${id} not found.`, true);
+      this._taskManager.updateTask(id, { status, summary });
+      const p = this._taskManager.progress;
+      return new ToolResult(
+        `Task ${id} updated${status ? ` to ${status}` : ""}. ` +
+        `Board: ${p.pending} pending, ${p.inProgress} in_progress, ${p.completed} completed, ${p.failed} failed.`,
+      );
+    });
+  }
+}
+
+export class TaskCompleteTool extends BaseTool {
+  constructor(workspace, taskManager) {
+    super();
+    this._workspace = workspace;
+    this._taskManager = taskManager;
+  }
+
+  get name() { return "TaskComplete"; }
+
+  get description() {
+    return (
+      "Mark a task as completed with an optional summary. Sugar for " +
+      "TaskUpdate({id, status: 'completed', summary}). The Ralph loop " +
+      "advances to the next pending task after this returns."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Task ID to complete." },
+        summary: {
+          type: "string",
+          description: "Optional short summary of what was produced.",
+        },
+      },
+      required: ["id"],
+    };
+  }
+
+  async execute(input) {
+    const id = input.id || "";
+    const summary = input.summary;
+
+    if (!id) return new ToolResult("id required", true);
+
+    return await this._workspace.withSharedLockIfApplicable(TASKS_REL, () => {
+      const exists = this._taskManager.getAllTasks().some((t) => t.id === id);
+      if (!exists) return new ToolResult(`Task ${id} not found.`, true);
+      this._taskManager.markDone(id, summary);
+      const p = this._taskManager.progress;
+      return new ToolResult(
+        `Task ${id} completed. Board: ${p.pending} pending, ${p.inProgress} in_progress, ${p.completed} completed.`,
+      );
+    });
+  }
+}

package/src/agent/tools/workspace-file.js

@@ -30,7 +30,9 @@ export class WorkspaceFileTool extends BaseTool {
       "Read, write, or list files. " +
       "scope='workspace' (default): KC's working directory for rules, skills, workflows, results. " +
       "scope='project': the user's project folder where KC was launched — source regulations and samples live here. " +
-      "Operations: read (returns file content), write (creates/overwrites a file), list (shows directory contents)."
+      "Operations: read (returns file content), write (creates/overwrites a file), list (shows directory contents). " +
+      "read returns up to 50,000 chars per call; longer files are truncated. " +
+      "For full reads of regulation/rule documents (typically smaller than this cap), prefer this tool over sandbox_exec."
     );
   }
 
@@ -87,7 +89,7 @@ export class WorkspaceFileTool extends BaseTool {
 
     try {
       if (op === "read") return this._read(filePath, scope);
-      if (op === "write") return this._write(filePath, content, scope);
+      if (op === "write") return await this._write(filePath, content, scope);
       if (op === "list") return this._list(filePath, scope);
       return new ToolResult(`Unknown operation: ${op}`, true);
     } catch (err) {
@@ -107,56 +109,68 @@ export class WorkspaceFileTool extends BaseTool {
     return new ToolResult(text);
   }
 
-  _write(filePath, content, scope) {
+  async _write(filePath, content, scope) {
     if (!filePath || filePath === ".") {
       return new ToolResult("Path required for write operation", true);
     }
     const resolved = this._resolveForScope(filePath, scope);
-    fs.mkdirSync(path.dirname(resolved), { recursive: true });
-
-    // v0.7.0 Group M (#84 remainder): on case-insensitive filesystems
-    // (macOS/Windows defaults), warn when the target's basename collides
-    // with an existing sibling differing only in case. Write proceeds
-    // — agents may legitimately overwrite — but the agent gets visible
-    // signal so it doesn't end up confused like E2E #5 GLM ("SKILL.md
-    // disappeared" when the inode was shared with skill.md). Workspace-
-    // scope only; project-dir scope is the user's territory.
-    let collisionNote = "";
-    if (
-      scope === "workspace" &&
-      this._workspace.fsCaseSensitive === false
-    ) {
-      try {
-        const parent = path.dirname(resolved);
-        const targetBase = path.basename(resolved);
-        const targetLower = targetBase.toLowerCase();
-        const siblings = fs.readdirSync(parent);
-        const collision = siblings.find(
-          (s) => s !== targetBase && s.toLowerCase() === targetLower,
-        );
-        if (collision) {
-          collisionNote =
-            ` ⚠ case-collision: case-insensitive filesystem already has '${collision}'` +
-            ` at this path; both names resolve to the same inode. Pick one canonical case` +
-            ` (lowercase preferred for skill files) and use it consistently — otherwise` +
-            ` archive_file / Read on either name affects the other.`;
-        }
-      } catch { /* readdirSync may fail on a fresh dir; that's fine, no collision possible */ }
-    }
 
-    fs.writeFileSync(resolved, content, "utf-8");
+    const doWrite = () => {
+      fs.mkdirSync(path.dirname(resolved), { recursive: true });
+
+      // v0.7.0 Group M (#84 remainder): on case-insensitive filesystems
+      // (macOS/Windows defaults), warn when the target's basename collides
+      // with an existing sibling differing only in case. Write proceeds
+      // — agents may legitimately overwrite — but the agent gets visible
+      // signal so it doesn't end up confused like E2E #5 GLM ("SKILL.md
+      // disappeared" when the inode was shared with skill.md). Workspace-
+      // scope only; project-dir scope is the user's territory.
+      let collisionNote = "";
+      if (
+        scope === "workspace" &&
+        this._workspace.fsCaseSensitive === false
+      ) {
+        try {
+          const parent = path.dirname(resolved);
+          const targetBase = path.basename(resolved);
+          const targetLower = targetBase.toLowerCase();
+          const siblings = fs.readdirSync(parent);
+          const collision = siblings.find(
+            (s) => s !== targetBase && s.toLowerCase() === targetLower,
+          );
+          if (collision) {
+            collisionNote =
+              ` ⚠ case-collision: case-insensitive filesystem already has '${collision}'` +
+              ` at this path; both names resolve to the same inode. Pick one canonical case` +
+              ` (lowercase preferred for skill files) and use it consistently — otherwise` +
+              ` archive_file / Read on either name affects the other.`;
+          }
+        } catch { /* readdirSync may fail on a fresh dir; that's fine, no collision possible */ }
+      }
+
+      fs.writeFileSync(resolved, content, "utf-8");
+
+      // Auto-commit to git for workspace writes (silently no-ops if gitignored or git unavailable)
+      let traceId = null;
+      if (scope === "workspace") {
+        traceId = this._workspace.autoCommit(filePath, "update");
+      }
+
+      const label = scope === "project" ? `[project] ${filePath}` : filePath;
+      let msg = `Wrote ${content.length} chars to ${label}`;
+      if (traceId) msg += ` [trace: ${traceId}]`;
+      if (collisionNote) msg += collisionNote;
+      return new ToolResult(msg);
+    };
 
-    // Auto-commit to git for workspace writes (silently no-ops if gitignored or git unavailable)
-    let traceId = null;
+    // v0.7.3: route writes to shared coordination paths (rules/catalog.json,
+    // tasks.json, refs/manifest.json, etc.) through the workspace lock so
+    // concurrent writers serialize. No-op for non-shared paths and for
+    // project-scope writes (project dir is the user's, not shared engine state).
     if (scope === "workspace") {
-      traceId = this._workspace.autoCommit(filePath, "update");
+      return await this._workspace.withSharedLockIfApplicable(filePath, doWrite);
     }
-
-    const label = scope === "project" ? `[project] ${filePath}` : filePath;
-    let msg = `Wrote ${content.length} chars to ${label}`;
-    if (traceId) msg += ` [trace: ${traceId}]`;
-    if (collisionNote) msg += collisionNote;
-    return new ToolResult(msg);
+    return doWrite();
   }
 
   _list(filePath, scope) {

package/src/config.js

@@ -90,10 +90,12 @@ export function loadSettings(workspacePath) {
     tier3: env.TIER3 || gc.tiers?.tier3 || "",
     tier4: env.TIER4 || gc.tiers?.tier4 || "",
 
-    // VLM tiers (vision/OCR models)
-    vlmTier1: env.VLM_TIER1 || gc.vlm_tiers?.tier1 || "",
-    vlmTier2: env.VLM_TIER2 || gc.vlm_tiers?.tier2 || "",
-    vlmTier3: env.VLM_TIER3 || gc.vlm_tiers?.tier3 || "",
+    // VLM tiers (vision/OCR models). v0.7.3: accept OCR_MODEL_TIER* as
+    // alias since template/.env.template + initializer.js seed that name.
+    // VLM_TIER* takes precedence when both are set.
+    vlmTier1: env.VLM_TIER1 || env.OCR_MODEL_TIER1 || gc.vlm_tiers?.tier1 || "",
+    vlmTier2: env.VLM_TIER2 || env.OCR_MODEL_TIER2 || gc.vlm_tiers?.tier2 || "",
+    vlmTier3: env.VLM_TIER3 || env.OCR_MODEL_TIER3 || gc.vlm_tiers?.tier3 || "",
 
     // Worker LLM — optional, defaults to conductor config (process.env wins)
     workerProvider: penv.KC_WORKER_PROVIDER || gc.worker_provider || "",

package/src/util/kc-version.js

@@ -0,0 +1,27 @@
+// Single source of truth for the live KC CLI version string.
+//
+// Reads package.json once. Used by engine.js (passed to ReleaseTool so
+// release manifests stamp the correct version) and by
+// pipelines/finalization.js (anywhere it surfaces "Built by kc-beta X").
+//
+// Before v0.7.2, engine.js hardcoded `kcVersion: "0.5.2"` which leaked
+// into every release manifest's `kc_beta_version` field regardless of
+// the actual package version. Both v0.7.1 audit runs (DS + GLM)
+// surfaced this. Reading package.json closes the gap.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function readKcVersion() {
+  try {
+    const pkgPath = path.resolve(__dirname, "../../package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    return pkg.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}

package/template/CLAUDE.md

@@ -23,6 +23,13 @@ skills/      — Meta skills encoding verification methodology
 .env         — Configuration: API keys, model tiers, thresholds, language
 ```
 
+Note: KC's session workspace under `~/.kc_agent/workspaces/<sessionId>/`
+uses lowercase counterparts (`rules/`, `samples/`, `input/`, `output/`,
+`logs/`, `workflows/`, `rule_skills/`) — these are runtime-internal and
+separate from this project's user-facing folders above. The asymmetry
+is intentional: title-case for human-facing project dirs, lowercase for
+KC's working state.
+
 ## Your Mission
 
 Follow this lifecycle. Each step references the skill(s) to consult:
@@ -93,6 +100,12 @@ skills/      — 编码核查方法论的元技能
 .env         — 配置：API密钥、模型层级、阈值、语言
 ```
 
+注：KC 在 `~/.kc_agent/workspaces/<sessionId>/` 下的会话工作区使用
+小写对应目录（`rules/`、`samples/`、`input/`、`output/`、`logs/`、
+`workflows/`、`rule_skills/`）—— 这些是运行时内部目录，与本项目上面
+那些用户可见的目录是分开的。这种大小写不对称是有意的：项目里给人看
+的目录用首字母大写；KC 自己的工作状态用小写。
+
 ## 你的使命
 
 遵循以下生命周期。每一步标注了需要参考的技能：

package/template/skills/en/meta-meta/rule-extraction/SKILL.md

@@ -133,6 +133,65 @@ conversation or existing catalog. Therefore, when composing the brief:
   catalog.json.** rule_catalog uses workspace file locking;
   sandbox_exec bypasses it and races with other writers.
 
+## How to read regulation files (default: read whole)
+
+Regulations are the audit's authoritative basis. Every `source_ref`
+in your extracted rules must be verifiable against the source text.
+For typical regulation documents (a single file under ~50 KB / under
+~100 pages), **read each regulation file whole using `workspace_file`
+(operation=read) in a single call**:
+
+```js
+workspace_file({ operation: "read", scope: "project", path: "Rules/01_some_regulation.md" })
+```
+
+`workspace_file.read` is capped at 50,000 chars per call, which
+covers virtually every individual regulation document. This is the
+default. **Read every regulation file whole before you start
+extracting rules from any of them.**
+
+### Tool choice — `workspace_file` vs `sandbox_exec`
+
+| Tool | Per-call cap | Use for |
+|---|---:|---|
+| `workspace_file` (read) | 50,000 chars | **full reads of regulation / rule documents** |
+| `sandbox_exec` (cat/head/etc) | 10,000 chars | shell commands, **not** full file reads |
+
+`sandbox_exec` is designed for shell commands; its 10K cap is too
+small for most regulations. `cat rules/01_*.md` returns only the
+first ~10 KB followed by `\n[truncated]`. Re-issuing with `head -N` /
+`tail -M` to scroll the window loses positional precision and burns
+turns. **When you see truncation, don't fight the cap — switch
+tools.**
+
+### Asymmetry — regs read whole, samples sampled
+
+Regulations are limited (typically 1-10 files), authoritative, and
+read once. Read every regulation whole.
+
+Sample documents may number 30 to 1000+, are heterogeneous, and get
+read many times during testing. **Don't try to read every sample
+whole.** Use rule-applicability filters or sampled subsets to focus
+attention.
+
+### Escape valve — when a single reg exceeds ~200K chars
+
+Rare in practice. The largest regulation in `test_data_4` is 42 KB;
+typical Chinese banking regs (资管新规, 信披办法, etc.) all fit
+under 50 KB. But if you do encounter a single regulation so large
+that reading it whole would crowd the context window — heuristic:
+the file exceeds ~200,000 chars or ~25% of your context budget —
+use your own judgment:
+
+- Read by chapter (e.g., `第X章` / `Chapter X`) using `document_parse`
+  or paginated `workspace_file` reads
+- Or build an in-workspace index file pointing to chapter offsets and
+  read on-demand per rule being extracted
+
+The 50 KB cap is high enough that this almost never triggers. **The
+default is read whole; deviate only when the file genuinely doesn't
+fit.**
+
 ## Extraction Strategies
 
 ### Strategy 1: Structured Input (Developer User Provides Rules)
@@ -223,6 +282,24 @@ Regulations are often ambiguous. When you encounter ambiguity:
 
 Do not skip ambiguous rules. They are often the most important ones.
 
+## Sanity-check applicability against the sample corpus
+
+After extracting your rule catalog and before authoring skills, do this 5-minute check: project each rule's applicability filter against the sample corpus.
+
+For every rule:
+1. Walk `samples/`, classify each by product type / report type / document format
+2. For each rule, count how many samples it would apply to (per the rule's `applicability` field, scope filter, or whatever shape your catalog uses)
+3. Flag rules that apply to **0 samples** — they're either genuinely test-corpus-irrelevant (acceptable) or over-constrained (bug)
+
+E2E #7 GLM produced a 97-rule catalog where 36 rules (37%) had `PASS=0 FAIL=0 NOT_APPLICABLE=90` across all 90 documents — they never fired. Some were legit (rules for cash-management products with no cash-management samples in corpus), but 36 inactive of 97 was high enough to suggest scope-too-narrow drift.
+
+If many rules are 0-sample, either:
+- **Reframe their applicability** — broaden product types, look for evidence in headers/footers not just body, relax the scope filter
+- **Document them as "future scope"** and remove from this iteration's catalog (still capture them in a `rules/future_scope.md` so they're not forgotten)
+- **Update the test corpus** to include matching samples (work with the developer user)
+
+Catching this in `rule_extraction` is much cheaper than authoring 36 skills that then test as inactive in `skill_testing`. The cheap projection here is worth the time it saves later.
+
 ## When Rules Change
 
 Regulations evolve. When the developer user adds new or updated regulation documents:

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

@@ -45,6 +45,32 @@ If yes, design a worker LLM prompt. Use the smallest model tier that maintains a
 ### The hybrid approach (most common)
 Most rules are a mix: regex extracts the number, Python compares it to the threshold, LLM handles the exceptional cases. Design the workflow as a pipeline where cheap steps run first and expensive steps run only when needed.
 
+### When regex alone isn't enough — decision rubric
+
+Before declaring distillation complete, audit each rule's `verification_type` / `metric` / `evidence_type` (or equivalent fields in your catalog). For rules where the required verification is one of:
+
+- **Semantic** ("is this a positive guarantee or a disclaimer?")
+- **Contextual** ("interpret this in light of the document's product type")
+- **Counterfactual** ("what should this value be, given the other fields?")
+- **Cross-field arithmetic** ("does 期初 + 收益 - 分配 = 期末?")
+
+regex alone rarely suffices. Three acceptable forms:
+
+1. **Pure regex with documented limits** — write the regex check, include a comment explaining the fragility (e.g., "matches syntactic pattern only; cannot detect semantic guarantees")
+2. **Hybrid regex + LLM** — regex baseline catches obvious cases, `worker_llm_call` (tier1-2) handles ambiguous ones. The hybrid workflow declares which rule_ids escalate.
+3. **Pure LLM via `worker_llm_call`** — for fully semantic rules where no regex baseline is meaningful.
+
+Don't ship pure regex for a rule whose `verification_type` is `judgment` / `semantic` without the documented-limits note. Future-you or a colleague will assume the regex is sufficient and that bug will hide for months.
+
+### Worker LLM cost-aware tier choice
+
+If you do escalate to LLM:
+- **tier1** (most capable, ~¥0.001-0.002/doc): cross-field reasoning, ambiguity resolution, rules that benefit from chain-of-thought
+- **tier2-3**: bulk extraction with simple semantic checks
+- **tier4** (cheapest): high-volume keyword-spotting that regex can't handle. Note: tier4 models on SiliconFlow are Qwen3.5 thinking-mode — `content` can return empty if `reasoning_content` consumes max_tokens. Test with realistic prompts before relying. If you see empty responses, either bump max_tokens to ≥8192, shorten your prompt, or fall back to tier1-2.
+
+Both v0.7.1 audit conductors (DS and GLM) defaulted to all-regex distillation and only added LLM escalation when the human user explicitly asked for "V2 with worker LLM". If your rule catalog has any rules where the verification is genuinely semantic, you should reach for `worker_llm_call` yourself — don't wait to be asked.
+
 ## Workflow Structure
 
 A workflow is a Python file (or small set of files) in `workflows/`:

package/template/skills/en/meta-meta/work-decomposition/SKILL.md

@@ -85,7 +85,7 @@ Bundle multiple rules into a single task (and a single check_r###_r###.py file)
 - The judgment logic for one rule is a substring or close variant of the next
 - A single failure typically implies multiple failures (you can't pass R013 if R015 fails)
 
-Example: R013 / R015 / R017 all check that a specific table on page 3 of the report contains certain mandatory fields. Same chunk, same parse, same verdict shape. Bundle as `check_r013_r015_r017.py` and create a single TaskCreate task `R013/R015/R017 — required-fields table`. The engine's filesystem-derived milestones recognize the grouped check.py and credit all three rule_ids.
+Example: R013 / R015 / R017 all check that a specific table on page 3 of the report contains certain mandatory fields. Same chunk, same parse, same verdict shape. Bundle as `check_r013_r015_r017.py` and create a single task: `TaskCreate({id: "R013-R015-R017-skill_authoring", title: "R013/R015/R017 — required-fields table", phase: "skill_authoring"})`. The engine's filesystem-derived milestones recognize the grouped check.py and credit all three rule_ids.
 
 ### When to keep separate
 
@@ -147,6 +147,41 @@ E2E #6 v070 surfaced this pattern (DS bundled-skill check.py files
 all returned `{"pass": null, "method": "stub"}` deferring to
 workflows/). v0.7.1 added this anti-pattern explicitly.
 
+E2E #7 v071 showed the teaching prevented the stub anti-pattern in
+both conductors (no `{"pass": null}` patterns in either run), but
+**DS still inverted the canonical-vs-distilled relationship**: DS's
+6 thematic skill folders had SKILL.md only (no check.py), with the
+real verification code living in `workflows/<skill>/check.py`. The
+absence of stubs is good; the inversion is not — editing a rule then
+requires touching both SKILL.md (the doc) and the workflow check.py
+(the code). Single source of truth is lost.
+
+GLM v071 by contrast landed the canonical pattern: 97/97 skills had
+both SKILL.md AND a real `check.py` (median 143 LOC of regex +
+applicability logic), and `workflows/<id>/workflow_v1.py` was a
+50-line thin wrapper that imported and called it:
+
+```python
+# workflows/D01-01/workflow_v1.py — thin wrapper, 52 LOC
+import importlib.util, json
+from pathlib import Path
+
+def run(doc_text: str, meta: dict = None) -> dict:
+    check_path = Path(__file__).parent.parent.parent / "rule_skills" / "D01-01" / "check.py"
+    spec = importlib.util.spec_from_file_location("check", check_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    result = mod.check(doc_text, meta)
+    result["_workflow"] = "D01-01_v1"
+    return result
+```
+
+This is the v0.7.2+ canonical pattern: workflow is a shim that
+points at the skill's check.py. To iterate on a rule's verification,
+edit `rule_skills/<id>/check.py`. The workflow doesn't change. v0.7.2
+clarifies the teaching: avoid stubs AND keep the canonical
+relationship (skill is canonical, workflow is distilled wrapper).
+
 ### Naming convention for grouped checks
 
 When you do bundle, name the file with the explicit range:
@@ -309,18 +344,50 @@ When entering skill_authoring with an empty TaskBoard:
 5. **Pick the first task.** Work it to completion (skill + check + at least one local test). Update PATTERNS.md with whatever you learned. Move to the next task.
 6. **At task ~5 and task ~10:** stop and re-read PATTERNS.md. If patterns suggest a refactor of earlier work, do it now (cheap) rather than later (expensive).
 
-### Why PATTERNS.md FIRST, before any skill code
+### Calling TaskCreate / TaskUpdate / TaskComplete
+
+The engine registers three task-board tools (v0.7.3+):
+
+- `TaskCreate({id, title, phase, ruleId?})` — adds a task to `tasks.json`. `id` must be unique within the session; pick a stable shape like `<rule_id>-<phase>` for per-rule tasks or `<group-name>-<phase>` for grouped / non-rule tasks. `phase` is the phase the task belongs to (current phase or a future phase you're pre-populating). `ruleId` is optional — set it for per-rule tasks so the engine can credit the rule_id in milestone derivation.
+- `TaskUpdate({id, status?, summary?})` — updates a task's status to `pending` / `in_progress` / `completed` / `failed`, optionally with a short summary.
+- `TaskComplete({id, summary?})` — sugar for `TaskUpdate({id, status:"completed", summary})`. Use this for the common path after finishing a unit of work.
+
+After you call `TaskCreate` for your decomposition and exit the current turn, the Ralph loop pulls the next pending task and runs it. Finish the work, call `TaskComplete`, and the loop advances. If a task can't be completed (irrecoverable error), call `TaskUpdate({id, status:"failed", summary:"reason"})` so the queue moves on rather than blocking on the failed task.
+
+Examples:
+
+```
+TaskCreate({ id: "R001-skill_authoring", title: "Author skill for R001",
+             phase: "skill_authoring", ruleId: "R001" })
+
+TaskCreate({ id: "trust-bundle-skill_authoring",
+             title: "R013/R015/R017 — required-fields table",
+             phase: "skill_authoring" })
+
+TaskComplete({ id: "R001-skill_authoring",
+               summary: "regex check passes 89/90; R001 done" })
+```
+
+### Persisted methodology — PATTERNS.md OR phase logs OR AGENT.md decisions
+
+The principle: capture framework-level decisions to disk before each phase advance. The conversation will compact, agents will restart, the next phase will lose grounding. Whichever format you pick, write to disk — don't rely on conversation context that disappears.
+
+Three formats, each defensible. Pick one and stick with it:
+
+- **`rules/PATTERNS.md`** — concise, framework-only, updated as the project progresses. Best for greenfield projects with clear hypothesis-up-front structure. Capped at ~5 KB; entries are transferable shapes / project constraints / anti-patterns with rationale (see "What to write" above).
 
-If you start writing skill code (rule_skills/<id>/check.py) before PATTERNS.md exists, **stop**. Even a 200-byte initial PATTERNS.md ("decided Shannon-Huffman; first hard rule R028 will dictate verdict shape; sample corpus has bilingual table headings") sets the framework. You'll save 4× the time later not re-deriving the same shapes per rule.
+- **`logs/phase_<name>_complete.md` per phase** — incremental, captures what each phase produced + decisions made + what the next phase inherits. Best for iterative discovery work where the framework crystallizes mid-run. E2E #7 GLM used this pattern across 6 phase docs and an `evolution_summary_v1.2.md`; the methodology was captured even though PATTERNS.md was never written.
 
-❌ "I'll write the skills first, then PATTERNS.md when I have insights."
+- **`AGENT.md` decisions section + domain notes** — narrative-style, living document of "what we know" and "why". Best for projects with rich domain context to capture (regulations, edge cases, thresholds, sample format distributions). E2E #7 GLM's AGENT.md included regulation enforcement dates, product type taxonomies, threshold values, and sample format counts — this is fine; it's a different idiom for the same goal.
 
-By the time you have N skills, you've made N implicit decisions about verdict shape, chunker boundaries, worker tier — each rule re-derives from scratch. Refactoring requires touching N files instead of one.
+What you should NOT do: skip persistence and rely only on the live conversation context. By the time you have N skills authored without any persisted methodology, you've made N implicit decisions about verdict shape, chunker boundaries, and worker tier. Each rule re-derives from scratch. Refactoring requires touching N files instead of one.
 
-✅ "Write PATTERNS.md, even tentatively, then re-read it before each new rule. Update it when discoveries change the framework."
+❌ "I'll capture insights when I have time."
 
-PATTERNS.md is your project's index card. Build it before the work, update it during the work, harvest it after.
+✅ "Before each phase advance, write what I learned to whichever persistence file matches this project's idiom — even if it's tentative."
 
-E2E #6 v070 surfaced this: DS only wrote PATTERNS.md after a rollback intervention; the per-skill design decisions before that point were already locked in and had to be re-touched. v0.7.1 reinforced this guidance.
+E2E history:
+- E2E #6 v070 DS wrote PATTERNS.md only after a rollback. Per-skill decisions before that point had to be re-touched. v0.7.1 added "PATTERNS.md FIRST" reinforcement.
+- E2E #7 v071 neither DS nor GLM wrote PATTERNS.md, but GLM wrote 6 rich phase-completion logs and a comprehensive AGENT.md — the methodology WAS captured, just in different files. v0.7.2 blesses the broader principle: persist before you advance, format flexible.
 
-The engine's filesystem-derived milestones (Group A v0.7.0) verify coverage on disk regardless of how you split the work. The TaskBoard is your scratchpad; the disk is the contract.
+The engine's filesystem-derived milestones (Group A v0.7.0) verify coverage on disk regardless of how you split the work. The TaskBoard is your scratchpad; the disk is the contract; the persistence file is your project's memory.