kc-beta 0.7.2 → 0.7.3

package/README.md

@@ -216,28 +216,35 @@ Quality Thresholds, Language.
 
 ## Status
 
-**v0.6.0 — first architectural beta.** This release lands:
+**v0.7.3 — codex review patch release.** Latest line in the v0.7.x
+hardening track. Architectural payload from v0.6.0+ is still in place:
 
 - Parallel ralph-loop (up to 8 concurrent workers) with a heap-safety
   conformance gate
 - Native chunker + RAG (onion-peeler + CJK bigram keyword index +
   one-shot LLM bundle classifier, ported from the AMC verification app)
-- Source-context auto-attach on skill_authoring tasks (rule NL + evidence
-  chunks + sibling rules injected into the prompt, no manual search needed)
+- Agent-owned task board: the agent reads the rule list from
+  `describeState`, decides decomposition (per-rule / grouped / range),
+  and calls `TaskCreate` / `TaskUpdate` / `TaskComplete` to drive the
+  Ralph loop. Source-context auto-attach pulls rule NL + evidence chunks
+  + sibling rules into the prompt of each task as it runs.
 - Workspace file locking for shared coordination files (`rules/catalog.json`,
-  `rules/manifest.json`, `tasks.json`, etc.)
+  `rules/manifest.json`, `refs/manifest.json`, `tasks.json`,
+  `session-state.json`) — every writer goes through `withFileLock`.
 - `agent_tool` gets `wait` / `poll` / `list` / `kill` operations +
   `stale_subagents` phase-advance signal
-- New FINALIZATION phase packages the session into a shippable deliverable
+- FINALIZATION phase packages the session into a shippable deliverable
   (canonical `rule_skills/` layout + README + coverage report + final
   dashboard)
+- Filesystem-derived phase milestones (v0.7.0+): the engine reads disk
+  artifacts for advance criteria, never trusts tool-call assertions
 - Input stays active during streaming (type-ahead queue), arrow keys +
   history recall, CTX smoothing + peak, per-provider context-limit caps,
   `/tools`, `/parallelism`, and more
 
-See [DEV_LOG.md](./DEV_LOG.md) for the full v0.6.0 change breakdown and
-[docs/update_design_v5.md](./docs/update_design_v5.md) for the plan that
-drove it.
+See [DEV_LOG.md](./DEV_LOG.md) for the per-release change breakdowns and
+[docs/update_design_v7.md](./docs/update_design_v7.md) for the v0.7.x
+plan and patch notes.
 
 Bug reports and PRs welcome at <https://github.com/kitchen-engineer42/kc-cli>.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kc-beta",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "KC Agent — LLM document verification agent (pure Node.js CLI). Dual-licensed: PolyForm Noncommercial 1.0.0 for personal/noncommercial use; commercial license required for enterprise production. See LICENSE and LICENSE-COMMERCIAL.md.",
   "type": "module",
   "bin": {

package/src/agent/engine.js

@@ -37,6 +37,7 @@ import { EvolutionCycleTool } from "./tools/evolution-cycle.js";
 import { TierDowngradeTool } from "./tools/tier-downgrade.js";
 import { AgentTool } from "./tools/agent-tool.js";
 import { WebSearchTool } from "./tools/web-search.js";
+import { TaskCreateTool, TaskUpdateTool, TaskCompleteTool } from "./tools/task-board.js";
 import { SkillLoader } from "./skill-loader.js";
 import { TaskManager } from "./task-manager.js";
 import { Scheduler } from "./scheduler.js";
@@ -475,6 +476,16 @@ export class AgentEngine {
           () => this.currentPhase,
         ),
         new WebSearchTool(this.config.tavilyApiKey),
+        // v0.7.3: completes the v0.7.0 "agent owns TaskBoard" design.
+        // Skills already reference TaskCreate by name; these tools make
+        // that contract truthful. See task-board.js + work-decomposition
+        // SKILL.md. Skipped for subagents — they don't own a task board
+        // (taskManager is null in subagent scope, line 216).
+        ...(this.taskManager ? [
+          new TaskCreateTool(this.workspace, this.taskManager),
+          new TaskUpdateTool(this.workspace, this.taskManager),
+          new TaskCompleteTool(this.workspace, this.taskManager),
+        ] : []),
       ],
       // Distillation+ only (DISTILL mode)
       distill: [
@@ -1308,6 +1319,7 @@ export class AgentEngine {
           yield new AgentEvent({
             type: "tool_result",
             name: tc.name,
+            input: inputData,
             output: historyContent,
             isError: result.isError,
           });

package/src/agent/tools/copy-to-workspace.js

@@ -94,7 +94,7 @@ export class CopyToWorkspaceTool extends BaseTool {
       this._appendGitignore(`refs/${targetName}`);
     }
 
-    this._appendManifest({
+    await this._appendManifest({
       target: targetRel,
       source: sourcePath,
       size: stat.size,
@@ -113,17 +113,22 @@ export class CopyToWorkspaceTool extends BaseTool {
     );
   }
 
-  _appendManifest(entry) {
-    const manifestAbs = this._workspace.resolvePath(MANIFEST_REL);
-    fs.mkdirSync(path.dirname(manifestAbs), { recursive: true });
-    let entries = [];
-    if (fs.existsSync(manifestAbs)) {
-      try { entries = JSON.parse(fs.readFileSync(manifestAbs, "utf-8")); }
-      catch { entries = []; }
-    }
-    if (!Array.isArray(entries)) entries = [];
-    entries.push(entry);
-    fs.writeFileSync(manifestAbs, JSON.stringify(entries, null, 2), "utf-8");
+  async _appendManifest(entry) {
+    // v0.7.3: refs/manifest.json is a shared coordination path — wrap the
+    // whole read-modify-write under the workspace lock so two parallel
+    // copy_to_workspace calls (main agent + subagent) don't lose entries.
+    return await this._workspace.withSharedLockIfApplicable(MANIFEST_REL, () => {
+      const manifestAbs = this._workspace.resolvePath(MANIFEST_REL);
+      fs.mkdirSync(path.dirname(manifestAbs), { recursive: true });
+      let entries = [];
+      if (fs.existsSync(manifestAbs)) {
+        try { entries = JSON.parse(fs.readFileSync(manifestAbs, "utf-8")); }
+        catch { entries = []; }
+      }
+      if (!Array.isArray(entries)) entries = [];
+      entries.push(entry);
+      fs.writeFileSync(manifestAbs, JSON.stringify(entries, null, 2), "utf-8");
+    });
   }
 
   _appendGitignore(line) {

package/src/agent/tools/sandbox-exec.js

@@ -44,7 +44,10 @@ export class SandboxExecTool extends BaseTool {
       "Execute a shell command. " +
       "cwd='workspace' (default) runs in KC's workspace. " +
       "cwd='project' runs in the user's project directory. " +
-      "Pipes, redirects, and chained commands (&&) are supported."
+      "Pipes, redirects, and chained commands (&&) are supported. " +
+      "stdout + stderr combined are capped at 10,000 chars; longer output is truncated. " +
+      "For reading individual files larger than ~10 KB (e.g. regulation documents), " +
+      "prefer workspace_file (operation=read) which has a larger 50 KB cap."
     );
   }
 

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/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)

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
 
@@ -344,6 +344,30 @@ 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).
 
+### 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.

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

@@ -132,6 +132,53 @@ existing catalog. Therefore, when composing the brief:
   catalog.json.** rule_catalog uses workspace file locking (B9);
   sandbox_exec bypasses it and races with other writers.
 
+## 如何读取规则文件 (默认整本读取)
+
+法规文件是审核的权威依据。你为每条规则记录的 `source_ref` 都要能在
+原文中复核。对于绝大多数规则文件 (单个文件 < 50 KB / < ~100 页),
+**用 `workspace_file` (operation=read) 一次性整本读取**:
+
+```js
+workspace_file({ operation: "read", scope: "project", path: "Rules/01_某某办法.md" })
+```
+
+`workspace_file.read` 单次上限 50,000 字符, 足以覆盖几乎所有单个法规
+文件。这是默认行为: **在抽取规则之前, 把每一份法规文件都整本读一遍。**
+
+### 工具选择 — `workspace_file` 还是 `sandbox_exec`
+
+| 工具 | 单次上限 | 适用 |
+|---|---:|---|
+| `workspace_file` (read) | 50,000 字符 | **整本读取法规/规则文件** |
+| `sandbox_exec` (cat/head) | 10,000 字符 | 短命令, 不适合整文件读取 |
+
+`sandbox_exec` 是为执行 shell 命令设计的, 10K 上限对绝大多数法规太小。
+`cat rules/01_*.md` 只会返回前 ~10 KB, 后面被截断为 `\n[truncated]`。
+反复用 `head -N` / `tail -M` 滑动窗口会丢失行号位置信息, 也浪费交互
+回合。**遇到截断, 别和上限较劲——换工具。**
+
+### 法规与样本的不对称 — 法规整本读, 样本按需抽样
+
+法规通常只有 1–10 份, 权威性强, 只需读一次。每一份法规都整本读取,
+作为后续所有规则抽取与引用的基础。
+
+样本文档可能 30 份甚至 1000+ 份, 异质性强, 在测试阶段会被多次读取。
+**不要试图把每个样本都整本读一遍**——用规则适用性过滤、抽样子集来
+聚焦注意力。
+
+### 例外 — 单个法规超过 200K 字符时
+
+实践中极少见。test_data_4 中最大的法规 42 KB; 银行业 资管新规 +
+信披办法 等典型法规也都在 50 KB 以内。但如果你确实遇到一份超大法规,
+读取整本会挤压上下文窗口 (启发式: 单文件超过 ~200,000 字符 或超过你
+上下文预算的 ~25%), 此时由你判断:
+
+- 按章 (`第X章`) 分段读, 用 `document_parse` 或分页的 `workspace_file`
+- 或建立工作区内的索引文件, 标注每章的偏移位置, 抽取规则时按需读取
+
+50 KB 的上限已经足够高, 上述例外情形几乎不会触发。**默认就是整本读;
+只有当文件确实太大时才偏离这一默认。**
+
 ## Extraction Strategies
 
 ### Strategy 1: Structured Input (Developer User Provides Rules)

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

@@ -85,7 +85,7 @@ KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这
 - 一条规则的判断逻辑是另一条的子串或近似变体
 - 一次失败通常意味着多条规则同时失败（R013 不可能在 R015 失败的情况下通过）
 
-例：R013 / R015 / R017 都在检查报告第 3 页那张表是否包含某些必填字段。同一个 chunk、同一次 parse、同一种 verdict 形状。合并为 `check_r013_r015_r017.py`，并创建一个 TaskCreate 任务 `R013/R015/R017 — 必填字段表`。引擎从文件系统推导里程碑时会识别这个合并 check.py，给三个 rule_id 都计入覆盖。
+例：R013 / R015 / R017 都在检查报告第 3 页那张表是否包含某些必填字段。同一个 chunk、同一次 parse、同一种 verdict 形状。合并为 `check_r013_r015_r017.py`，并创建一个任务：`TaskCreate({id: "R013-R015-R017-skill_authoring", title: "R013/R015/R017 — 必填字段表", phase: "skill_authoring"})`。引擎从文件系统推导里程碑时会识别这个合并 check.py，给三个 rule_id 都计入覆盖。
 
 ### 何时保持独立
 
@@ -337,6 +337,30 @@ PATTERNS.md 全文控制在约 5 KB 之内。超过时，剪掉最不可执行
 5. **挑第一个任务**。做到完整（skill + check + 至少一次本地测试）。把学到的写进 PATTERNS.md。换下一个任务。
 6. **任务做到第 5 个、第 10 个时**：停下来重读 PATTERNS.md。如果新积累的 pattern 暗示要重构早期工作，**现在做**（便宜）而不是更晚（昂贵）。
 
+### 调用 TaskCreate / TaskUpdate / TaskComplete
+
+引擎注册了三个任务面板工具（v0.7.3+）：
+
+- `TaskCreate({id, title, phase, ruleId?})` —— 在 `tasks.json` 中新增一条任务。`id` 在本会话内必须唯一；per-rule 任务建议用 `<rule_id>-<phase>` 这种稳定形状，分组 / 非规则任务用 `<group-name>-<phase>`。`phase` 是该任务所属的阶段（当前阶段或你预先排好的未来阶段）。`ruleId` 可选 —— 设上之后，引擎在里程碑推导时能把这个 rule_id 计入覆盖。
+- `TaskUpdate({id, status?, summary?})` —— 把任务状态改为 `pending` / `in_progress` / `completed` / `failed`，可选附一行简要 summary。
+- `TaskComplete({id, summary?})` —— `TaskUpdate({id, status:"completed", summary})` 的语法糖。完成一个工作单元后走这条最常用的路径。
+
+调用 `TaskCreate` 把你的拆分写进面板、本回合结束之后，Ralph 循环会取下一条 pending 任务执行。完成工作、调 `TaskComplete`，循环再前进。如果一条任务无法完成（不可恢复的错误），调 `TaskUpdate({id, status:"failed", summary:"原因"})`，让队列继续推进而不是被堵在那里。
+
+示例：
+
+```
+TaskCreate({ id: "R001-skill_authoring", title: "为 R001 撰写 skill",
+             phase: "skill_authoring", ruleId: "R001" })
+
+TaskCreate({ id: "trust-bundle-skill_authoring",
+             title: "R013/R015/R017 — 必填字段表",
+             phase: "skill_authoring" })
+
+TaskComplete({ id: "R001-skill_authoring",
+               summary: "正则核查在 89/90 通过；R001 完成" })
+```
+
 ### 持久化方法论 —— PATTERNS.md 或 phase 日志 或 AGENT.md decisions
 
 原则：在每次 phase 推进之前，把框架级的决定写到磁盘。对话会被 compact、agent 会重启、下一个 phase 会失去上下文。不管你选哪种格式，**写到磁盘** —— 不要依赖会消失的对话上下文。