kc-beta 0.7.2 → 0.7.5

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

@@ -0,0 +1,112 @@
+import { BaseTool, ToolResult } from "./base.js";
+
+/**
+ * v0.7.5: load a methodology skill's body into the agent's conversation
+ * history as a tool result. Pairs with the always-loaded body injection
+ * in SkillLoader.formatForContext — that handles the 1-2 architecturally-
+ * required skills per phase; consult_skill handles the rest on demand.
+ *
+ * Validation:
+ * - Skill name must be in the current phase's available set (per
+ *   template/skills/phase_skills.yaml).
+ * - Already-always-loaded skills return a hint pointing the agent at the
+ *   system prompt (don't double-load).
+ * - Missing bodies return an error result.
+ *
+ * Emits `skill_invoked` event with proper skill name on success — replaces
+ * the older path-matching regex at engine.js:1297-1313 that produced
+ * "(unknown)" spam from rule_skills/<id>/SKILL.md writes.
+ */
+export class ConsultSkillTool extends BaseTool {
+  /**
+   * @param {import('../workspace.js').Workspace} workspace
+   * @param {import('../skill-loader.js').SkillLoader} skillLoader
+   * @param {() => string} getCurrentPhase — returns the engine's current phase
+   * @param {import('../event-log.js').EventLog} [eventLog] — for skill_invoked emission
+   */
+  constructor(workspace, skillLoader, getCurrentPhase, eventLog) {
+    super();
+    this._workspace = workspace;
+    this._skillLoader = skillLoader;
+    this._getCurrentPhase = getCurrentPhase;
+    this._eventLog = eventLog;
+  }
+
+  get name() { return "consult_skill"; }
+
+  get description() {
+    return (
+      "Load the full body of a methodology skill into your context for the " +
+      "current turn. Use when the description tease in the system prompt's " +
+      "'Available Methodology Skills' section isn't enough detail to proceed. " +
+      "The body lands in your conversation history; subsequent turns can " +
+      "reference it via context, or you can re-consult if it ages out. " +
+      "Skills already in the 'Loaded Into Your Context' section don't need " +
+      "consulting — they're already in your prompt."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Skill name as listed in the system prompt (e.g., 'work-decomposition', 'evolution-loop').",
+        },
+      },
+      required: ["name"],
+    };
+  }
+
+  async execute(input) {
+    const name = (input?.name || "").trim();
+    if (!name) return new ToolResult("name required (e.g. consult_skill({name: 'work-decomposition'}))", true);
+
+    const phase = this._getCurrentPhase ? this._getCurrentPhase() : null;
+    const { alwaysLoaded, available } = this._skillLoader.getPhaseSkillSet(phase);
+
+    const alwaysSet = new Set(alwaysLoaded);
+    const availableSet = new Set(available);
+
+    if (alwaysSet.has(name)) {
+      return new ToolResult(
+        `Skill '${name}' is already always-loaded in your system prompt for phase '${phase}'. ` +
+        `Re-read the system prompt's 'Methodology Skills — Loaded Into Your Context' section ` +
+        `— the body is there. No separate consult needed.`,
+      );
+    }
+
+    if (!availableSet.has(name)) {
+      const sorted = [...availableSet].sort();
+      return new ToolResult(
+        `Skill '${name}' is not available in phase '${phase}'. ` +
+        `Available for this phase: ${sorted.join(", ")}. ` +
+        `If you genuinely need this skill, either advance/retreat to a phase ` +
+        `where it's available, or check the spelling.`,
+        true,
+      );
+    }
+
+    const body = this._skillLoader.loadSkillBody(name);
+    if (!body) {
+      return new ToolResult(
+        `Skill '${name}' is declared available for phase '${phase}' but its body could not be loaded. ` +
+        `This is an engine/template inconsistency — surface to the developer user.`,
+        true,
+      );
+    }
+
+    // Emit skill_invoked event with the real skill name (replaces the
+    // old path-matching regex that produced "(unknown)" spam).
+    try {
+      this._eventLog?.append?.("skill_invoked", {
+        skill: name,
+        via_tool: "consult_skill",
+        phase,
+      });
+    } catch { /* event logging is best-effort */ }
+
+    return new ToolResult(body);
+  }
+}

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,23 @@ 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.4 (re-applied from v0.7.3 G1a): 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/release.js

@@ -185,8 +185,23 @@ export class ReleaseTool extends BaseTool {
     // file through and emitted a stub on miss. We try to populate from
     // known QC artifact shapes here; if nothing matches, fall through
     // to the existing stub fallback.
+    // v0.7.5 G-H3: aggregator now runs if calibSrc is MISSING **or** has
+    // empty `historical_accuracy`. v0.7.4 audit (both 贷款 + 资管) shipped
+    // empty stubs despite QC data on disk — root cause was the v0.7.2
+    // gate only checked file existence; a stub written earlier (e.g., on
+    // finalization phase entry) kept the aggregator from firing later.
     const calibSrc = path.join(this._workspace.cwd, "confidence_calibration.json");
-    if (!fs.existsSync(calibSrc)) {
+    let shouldAggregate = !fs.existsSync(calibSrc);
+    if (!shouldAggregate) {
+      try {
+        const existing = JSON.parse(fs.readFileSync(calibSrc, "utf-8"));
+        const ha = existing?.historical_accuracy;
+        if (!ha || (typeof ha === "object" && Object.keys(ha).length === 0)) {
+          shouldAggregate = true;
+        }
+      } catch { shouldAggregate = true; } // corrupt → re-aggregate
+    }
+    if (shouldAggregate) {
       const aggregated = this._aggregateAccuracyFromOutput();
       if (aggregated && Object.keys(aggregated.historical_accuracy).length > 0) {
         fs.writeFileSync(calibSrc, JSON.stringify(aggregated, null, 2) + "\n", "utf-8");
@@ -247,6 +262,14 @@ export class ReleaseTool extends BaseTool {
       .replace(/\{RULES_LIST\}/g, rulesList);
     fs.writeFileSync(path.join(bundleAbs, "README.md"), readme, "utf-8");
 
+    // v0.7.5 G-H4: sweep any leftover `.tmpl` files from the bundle dir.
+    // template/release/v1/ contains manifest.json.tmpl, catalog.json.tmpl,
+    // README.md.tmpl. _copyDir's exclude list (line 119) only filters
+    // README.md.tmpl; the other two ride along and persist alongside their
+    // populated counterparts. Audit (v0.7.4 贷款) confirmed this regression
+    // of v0.7.2 G1d which only handled the v1/ scaffold case.
+    this._sweepTmplFiles(bundleAbs);
+
     // v0.7.2 1d: clean up the template scaffold dir if a customized
     // release was just written alongside it. Both v0.7.1 audit runs
     // shipped with `output/releases/v1/` (template-derived, .tmpl
@@ -303,6 +326,25 @@ export class ReleaseTool extends BaseTool {
     }
   }
 
+  /**
+   * v0.7.5 G-H4: recursively remove any `*.tmpl` files from a directory.
+   * Used after populating a release bundle to drop template stubs that
+   * weren't filtered by the initial copy's exclude list. Idempotent.
+   */
+  _sweepTmplFiles(dir) {
+    try {
+      if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return;
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          this._sweepTmplFiles(entryPath);
+        } else if (entry.isFile() && entry.name.endsWith(".tmpl")) {
+          try { fs.unlinkSync(entryPath); } catch { /* best-effort */ }
+        }
+      }
+    } catch { /* best-effort */ }
+  }
+
   _findLatestWorkflow(ruleId) {
     // Canonical: workflows/<ruleId>/workflow_v#.py (subdirectory layout)
     const wfDir = path.join(this._workspace.cwd, "workflows", ruleId);
@@ -338,10 +380,95 @@ export class ReleaseTool extends BaseTool {
           }
         } catch { /* manifest unreadable; skip */ }
       }
+
+      // v0.7.5 G-H2: master / grouped workflow pattern. Agent shipped a
+      // single workflow folder (e.g., workflows/master/ or workflows/
+      // bank_wm_compliance/) declaring `source_rules: [R001, R002, ...]`
+      // in its SKILL.md / workflow.md / config.json. The manifest writer
+      // should credit this rule_id as covered by that workflow.
+      //
+      // Walk workflows/ subdirs looking for a source_rules declaration
+      // that includes this ruleId. Return the first matching workflow file.
+      // Audit (v0.7.4 贷款 session) confirmed manifest under-counted:
+      // catalog had 15 rules; manifest only listed R001 because R002-R015
+      // weren't found as standalone workflows.
+      for (const entry of fs.readdirSync(flatRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === ruleId) continue; // already checked above
+        const subDir = path.join(flatRoot, entry.name);
+        const declaredRules = this._readWorkflowSourceRules(subDir);
+        if (declaredRules.includes(ruleId)) {
+          // Find the workflow entry file in this dir
+          const subFiles = fs.readdirSync(subDir);
+          const versioned = subFiles.filter((f) => /^workflow_v\d+\.py$/.test(f)).sort();
+          if (versioned.length > 0) return path.join(subDir, versioned[versioned.length - 1]);
+          const any = subFiles.find((f) => f.endsWith(".py"));
+          if (any) return path.join(subDir, any);
+        }
+      }
     }
     return null;
   }
 
+  /**
+   * v0.7.5 G-H2: read a workflow directory's source_rules declaration.
+   * Checks SKILL.md / workflow.md frontmatter (`source_rules: [...]`)
+   * and config.json (`source_rules`, `rules`, or `rule_ids` field).
+   * Returns array of canonical rule IDs.
+   */
+  _readWorkflowSourceRules(workflowDir) {
+    const ids = new Set();
+    try {
+      const files = fs.readdirSync(workflowDir);
+
+      // Frontmatter sources
+      for (const fname of files) {
+        if (!/^(skill|workflow)\.md$/i.test(fname)) continue;
+        let content;
+        try { content = fs.readFileSync(path.join(workflowDir, fname), "utf-8"); } catch { continue; }
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch) continue;
+        const fm = fmMatch[1];
+        // Inline form
+        const inlineMatch = fm.match(/^source_rules\s*:\s*\[([^\]]*)\]\s*$/m);
+        if (inlineMatch) {
+          inlineMatch[1].split(",").map(s => s.trim().replace(/^["']|["']$/g, ""))
+            .filter(Boolean).forEach(s => {
+              const m = s.match(/^R0*(\d+)$/i);
+              if (m) ids.add(`R${String(parseInt(m[1], 10)).padStart(3, "0")}`);
+            });
+        }
+        // Block form
+        const blockMatch = fm.match(/^source_rules\s*:\s*\n((?:[ \t]+-\s+\S+\s*\n?)+)/m);
+        if (blockMatch) {
+          blockMatch[1].split("\n").forEach(line => {
+            const m = line.match(/^[ \t]+-\s+["']?(R0*\d+)["']?\s*$/i);
+            if (m) {
+              const n = m[1].match(/R0*(\d+)/i);
+              if (n) ids.add(`R${String(parseInt(n[1], 10)).padStart(3, "0")}`);
+            }
+          });
+        }
+      }
+
+      // Config.json sources
+      const configPath = path.join(workflowDir, "config.json");
+      if (fs.existsSync(configPath)) {
+        try {
+          const data = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+          const rules = Array.isArray(data?.source_rules) ? data.source_rules :
+                        Array.isArray(data?.rules) ? data.rules :
+                        Array.isArray(data?.rule_ids) ? data.rule_ids : [];
+          for (const r of rules) {
+            const m = String(r).match(/^R0*(\d+)$/i);
+            if (m) ids.add(`R${String(parseInt(m[1], 10)).padStart(3, "0")}`);
+          }
+        } catch { /* ignore */ }
+      }
+    } catch { /* dir unreadable */ }
+    return [...ids];
+  }
+
   _resolveFixture(rel) {
     // Try samples/ first (workspace, then project), then plain workspace path
     const candidates = [];

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

@@ -87,7 +87,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 +107,70 @@ 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.4 (re-applied from v0.7.3 G1a): 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.4: 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 || "",