@bluewombat/slots 0.1.1 → 0.1.2

package/README.md

@@ -58,23 +58,23 @@ these all use it. How Host wires a slot into a run:
 
 ## Catalogue
 
-| Slot                              | Kind    | Answers                                                              |
-| --------------------------------- | ------- | -------------------------------------------------------------------- |
-| `agents/cursor.mjs`               | Agent   | Runs Cursor CLI with a filled prompt                                 |
-| `agents/claude.mjs`               | Agent   | Runs Claude Code with a filled prompt                                |
-| `builders/producer.mjs`           | Builder | First pass of a Subtask: fill `{{task}}`, then spawn the agent       |
-| `builders/repair.mjs`             | Builder | A Gate refused the Subtask: fill `{{task}}` and `{{report}}`         |
-| `assembly/fix.mjs`                | Builder | A judgement refused the assembled feature: fill `{{task}}` and `{{report}}` |
-| `gates/workspace-changed.mjs`     | Gate    | The Attempt left an uncommitted change                               |
-| `gates/parent-clean.mjs`          | Gate    | Isolator's Parent working files did not move                         |
-| `gates/sensitive-path.mjs`        | Gate    | No path matching a glob was touched                                  |
-| `gates/ci-green.mjs`              | Gate    | The work line's own checks came back green                           |
-| `planners/one-subtask.mjs`        | Planner | Bootstrap: one Subtask that is the FeatureStandard itself            |
-| `publishers/git.mjs`              | Publisher | Pushes the feature's branch to the work line's own remote          |
-| `refreshers/git.mjs`              | Refresher | Fast-forwards the work line copy onto what the Authority holds     |
-| `planners/producer.mjs`           | Planner | An agent CLI splits the FeatureStandard                              |
-| `messages/conventional.mjs`       | Message | `<type>: <title>` for the feature's fold, no agent; `--scope`, `--type`   |
-| `messages/git-producer.mjs`       | Describer | An agent reads the git diff and writes the feature's subject and body under `--rules-file` |
+| Slot                          | Kind      | Answers                                                                                    |
+| ----------------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| `agents/cursor.mjs`           | Agent     | Runs Cursor CLI with a filled prompt                                                       |
+| `agents/claude.mjs`           | Agent     | Runs Claude Code with a filled prompt                                                      |
+| `builders/producer.mjs`       | Builder   | First pass of a Subtask: fill `{{task}}`, then spawn the agent                             |
+| `builders/repair.mjs`         | Builder   | A Gate refused the Subtask: fill `{{task}}` and `{{report}}`                               |
+| `assembly/fix.mjs`            | Builder   | A judgement refused the assembled feature: fill `{{task}}` and `{{report}}`                |
+| `gates/workspace-changed.mjs` | Gate      | The Attempt left an uncommitted change                                                     |
+| `gates/parent-clean.mjs`      | Gate      | Isolator's Parent working files did not move                                               |
+| `gates/sensitive-path.mjs`    | Gate      | No path matching a glob was touched                                                        |
+| `gates/ci-green.mjs`          | Gate      | The work line's own checks came back green                                                 |
+| `planners/one-subtask.mjs`    | Planner   | Bootstrap: one Subtask that is the FeatureStandard itself                                  |
+| `publishers/git.mjs`          | Publisher | Pushes the feature's branch to the work line's own remote                                  |
+| `refreshers/git.mjs`          | Refresher | Fast-forwards the work line copy onto what the Authority holds                             |
+| `planners/producer.mjs`       | Planner   | An agent CLI splits the FeatureStandard                                                    |
+| `messages/conventional.mjs`   | Message   | `<type>: <title>` for the feature's fold, no agent; `--scope`, `--type`                    |
+| `messages/git-producer.mjs`   | Describer | An agent reads the git diff and writes the feature's subject and body under `--rules-file` |
 
 ## Agents
 
@@ -92,18 +92,36 @@ and print the serialized run on stdout. They do not know `--intention` or
 `cursor.mjs` needs `cursor-agent` on PATH (`cursor-agent login`); `claude.mjs`
 needs `claude`, signed in once.
 
-| Option                      | Meaning                                                            |
-| --------------------------- | ------------------------------------------------------------------ |
-| `--prompt TEXT`             | The filled prompt. Mutually exclusive with `--prompt-file`         |
-| `--prompt-file PATH`        | The same text, from a file. No interpolation                       |
-| `--bin PATH`                | The CLI to run. Default: the vendor's own name, on PATH            |
-| `--model NAME`              | Model for that run                                                 |
-| `--output-format FMT`       | `json` (default), `text`, or `stream-json`                         |
-| `--permission-mode MODE`    | `claude.mjs` only. Default `bypassPermissions`                     |
-| `--transcript-dir PATH`     | Write one file per turn under here. Off unless given               |
-| `--transcript-part NAME`    | `prompt`, `stdout`, `stderr`, `timing`. Repeatable. Default: all   |
-| `--agent-arg VALUE`         | Appended to the CLI argv, before the prompt. Repeatable            |
-| `--id` / `--attempt` / `--context` | How a transcript is filed. Forwarded by the role             |
+| Option                             | Meaning                                                                          |
+| ---------------------------------- | -------------------------------------------------------------------------------- |
+| `--prompt TEXT`                    | The filled prompt. Mutually exclusive with `--prompt-file`                       |
+| `--prompt-file PATH`               | The same text, from a file. No interpolation                                     |
+| `--bin PATH`                       | The CLI to run. Default: the vendor's own name, on PATH                          |
+| `--model NAME`                     | Model for that run                                                               |
+| `--output-format FMT`              | `stream-json` (default), `json`, or `text`. Skill extraction needs `stream-json` |
+| `--permission-mode MODE`           | `claude.mjs` only. Default `bypassPermissions`                                   |
+| `--transcript-dir PATH`            | Write one file per turn under here. Off unless given                             |
+| `--transcript-part NAME`           | `prompt`, `stdout`, `stderr`, `timing`. Repeatable. Default: all                 |
+| `--agent-arg VALUE`                | Appended to the CLI argv, before the prompt. Repeatable                          |
+| `--id` / `--attempt` / `--context` | How a transcript is filed. Forwarded by the role                                 |
+
+The agent CLI prints **one JSON line** — a `SerializedRun` from
+`@bluewombat/slot-kit` — with the vendor's raw streams plus two extras the
+wrapper fills when it can:
+
+| Field    | Meaning                                                                                                                                              |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `skills` | `null` = unknown (not stream-json, or unparseable). `[]` = looked, none used. Otherwise skill names in order                                         |
+| `usage`  | `null` = unknown. Otherwise token counts (`input`, `output`, `cacheRead`, `cacheWrite`) and `costUsd` (`null` when the vendor did not report a cost) |
+
+Cursor extracts skills from `stream-json` `readToolCall` paths ending in
+`/skills/<name>/SKILL.md`. Claude extracts them from `tool_use` blocks named
+`Skill` (`input.skill`), and adds `--verbose` whenever the format is
+`stream-json`. A future vendor agent (`codex.mjs`, …) uses the same fields:
+leave them `null` when it cannot tell.
+
+When `--transcript-dir` is set, the transcript header repeats `skills` and
+`usage` (`unknown`, `(none)`, or the values).
 
 A global npm install belongs to one Node version: after `nvm use`, a `claude`
 installed under another version is off PATH. Give `--bin` the absolute path, or
@@ -159,11 +177,11 @@ never places, is `fail-blocking`. `{{done_when}}` is `Done when:` plus the
 definition of done, and vanishes whole when there is none — which is every
 assembly, so `assembly/fix` does not fill it at all.
 
-| Role                    | Required                 | Also fills                                                         |
-| ----------------------- | ------------------------ | ------------------------------------------------------------------ |
-| `builders/producer`     | `{{task}}`, `{{rules}}`               | `{{done_when}}`, `{{id}}`, `{{attempt}}`                 |
-| `builders/repair`       | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}` |
-| `assembly/fix`          | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{id}}`, `{{attempt}}`                |
+| Role                | Required                              | Also fills                                                 |
+| ------------------- | ------------------------------------- | ---------------------------------------------------------- |
+| `builders/producer` | `{{task}}`, `{{rules}}`               | `{{done_when}}`, `{{id}}`, `{{attempt}}`                   |
+| `builders/repair`   | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}` |
+| `assembly/fix`      | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{id}}`, `{{attempt}}`                  |
 
 A first-pass command that receives `--report` is `fail-blocking`: that report
 belongs to the repair command. A repair or fix command without `--report` is the same.
@@ -206,9 +224,10 @@ but inside the slot, and by the time a result reaches Host it is one word. So a
 loop that misbehaves cannot be read back, only guessed at.
 
 `--transcript-dir` writes one Markdown file per turn: the invocation, the prompt
-as sent, stdout, stderr, and how long it took. Files are filed under the Feature
-the Task belongs to, named for the Subtask and the Attempt. It belongs on the
-**agent** command, after `--`.
+as sent, stdout, stderr, how long it took, and — when the agent wrapper passed
+them — `skills` and `usage` (`unknown`, `(none)`, or the values). Files are
+filed under the Feature the Task belongs to, named for the Subtask and the
+Attempt. It belongs on the **agent** command, after `--`.
 
 ```json
 "builder": {
@@ -345,10 +364,10 @@ on the role; the vendor is named after `--`, the same way a Builder names it.
 }
 ```
 
-| Option                   | Meaning                                                          |
-| ------------------------ | ---------------------------------------------------------------- |
-| `--read PATH`            | The project the agent may read before splitting. Default: cwd    |
-| `--prompt-file PATH`     | Prompt template. Must place `{{intention}}` and `{{out}}`        |
+| Option               | Meaning                                                       |
+| -------------------- | ------------------------------------------------------------- |
+| `--read PATH`        | The project the agent may read before splitting. Default: cwd |
+| `--prompt-file PATH` | Prompt template. Must place `{{intention}}` and `{{out}}`     |
 
 `--bin`, `--model`, `--transcript-dir` and `--agent-arg` are the agent's, after
 `--`. Optional placeholder: `{{max_units}}`.

package/agents/claude-extras.mjs

@@ -0,0 +1,113 @@
+/**
+ * Extract mason AgentExtras from a Claude Code CLI stdout blob.
+ *
+ * Skills: stream-json assistant messages whose content has a `tool_use` named
+ * `Skill` (Claude tools reference). The skill id is `input.skill` as emitted
+ * by Claude Code (e.g. `planner:thin-slice`). Ignore `system/init.skills`
+ * (available catalogue, not used).
+ *
+ * Usage: terminal `result` documents `usage` (`input_tokens`, …) and
+ * `total_cost_usd`.
+ *
+ * `skills` is `null` when stdout is not NDJSON we can parse; `[]` when parsed
+ * with no Skill tool_use.
+ */
+
+import { readResult } from "@bluewombat/slot-kit";
+
+/**
+ * @param {string} stdout
+ * @param {string} outputFormat
+ * @returns {{ skills: string[] | null, usage: import("@bluewombat/slot-kit").AgentUsage | null }}
+ */
+export function extrasFromClaude(stdout, outputFormat) {
+  return {
+    skills: outputFormat === "stream-json" ? skillsFromClaude(stdout) : null,
+    usage: usageFromClaude(stdout),
+  };
+}
+
+/**
+ * @param {string} stdout
+ * @returns {string[] | null}
+ */
+export function skillsFromClaude(stdout) {
+  const lines = stdout.split("\n").filter((line) => line.trim().length > 0);
+  if (lines.length === 0) {
+    return null;
+  }
+  /** @type {string[]} */
+  const skills = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  let parsedAny = false;
+  for (const line of lines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event === null || typeof event !== "object" || Array.isArray(event)) {
+      continue;
+    }
+    parsedAny = true;
+    if (event.type !== "assistant") {
+      continue;
+    }
+    const content = event.message?.content;
+    if (!Array.isArray(content)) {
+      continue;
+    }
+    for (const block of content) {
+      if (block === null || typeof block !== "object" || Array.isArray(block)) {
+        continue;
+      }
+      if (block.type !== "tool_use" || block.name !== "Skill") {
+        continue;
+      }
+      const input = block.input;
+      if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        continue;
+      }
+      const name = /** @type {Record<string, unknown>} */ (input).skill;
+      if (typeof name !== "string" || name.length === 0 || seen.has(name)) {
+        continue;
+      }
+      seen.add(name);
+      skills.push(name);
+    }
+  }
+  return parsedAny ? skills : null;
+}
+
+/**
+ * @param {string} stdout
+ * @returns {import("@bluewombat/slot-kit").AgentUsage | null}
+ */
+export function usageFromClaude(stdout) {
+  const result = readResult(stdout);
+  if (result === undefined) {
+    return null;
+  }
+  const usage = result.usage;
+  if (usage === null || typeof usage !== "object" || Array.isArray(usage)) {
+    return null;
+  }
+  const record = /** @type {Record<string, unknown>} */ (usage);
+  if (
+    typeof record.input_tokens !== "number" ||
+    typeof record.output_tokens !== "number" ||
+    typeof record.cache_creation_input_tokens !== "number" ||
+    typeof record.cache_read_input_tokens !== "number"
+  ) {
+    return null;
+  }
+  return {
+    input: record.input_tokens,
+    output: record.output_tokens,
+    cacheRead: record.cache_read_input_tokens,
+    cacheWrite: record.cache_creation_input_tokens,
+    costUsd: typeof result.total_cost_usd === "number" ? result.total_cost_usd : null,
+  };
+}

package/agents/claude.mjs

@@ -12,6 +12,7 @@ import {
   textOption,
   transcriptFor,
 } from "@bluewombat/slot-kit";
+import { extrasFromClaude } from "./claude-extras.mjs";
 
 // Claude Code as a vendor agent. The prompt is already filled: this command
 // does not interpolate. Own options only — a role slot strips Implementer's
@@ -19,7 +20,7 @@ import {
 //   --prompt TEXT / --prompt-file PATH   the filled prompt. One of the two
 //   --bin PATH             the Claude CLI. Default: claude, found on PATH
 //   --model NAME           alias (opus, sonnet) or full name
-//   --output-format FMT    json (default), text, or stream-json
+//   --output-format FMT    stream-json (default), json, or text
 //   --permission-mode MODE bypassPermissions (default), acceptEdits, …
 //   --transcript-dir PATH  write one file per turn. Off by default
 //   --transcript-part NAME prompt, stdout, stderr, timing. Repeatable
@@ -59,12 +60,16 @@ if (bin === undefined) {
 }
 
 const model = textOption(options, "model");
+/** @type {string} */
+const outputFormat = /** @type {string} */ (options.outputFormat);
 const args = [
   "-p",
   "--permission-mode",
   /** @type {string} */ (options.permissionMode),
   "--output-format",
-  /** @type {string} */ (options.outputFormat),
+  outputFormat,
+  // Claude's stream-json only emits tool events with --verbose (headless docs).
+  ...(outputFormat === "stream-json" ? ["--verbose"] : []),
   ...(model === undefined ? [] : ["--model", model]),
   ...listOption(options, "agentArg"),
   prompt,
@@ -77,8 +82,9 @@ const transcript = transcriptFor(process.argv, options, {
   prompt,
 });
 const run = await runAgent({ file: bin, args, cwd });
-transcript.write(run);
-answer(run, bin);
+const extras = extrasFromClaude(run.stdout, outputFormat);
+transcript.write(run, extras);
+answer(run, bin, extras);
 
 /** @param {string} reason @returns {never} */
 function refuse(reason) {
@@ -89,9 +95,14 @@ function refuse(reason) {
 /**
  * @param {import("@bluewombat/slot-kit").AgentRun} run
  * @param {string} binPath
+ * @param {import("@bluewombat/slot-kit").AgentExtras} extras
  * @returns {never}
  */
-function answer(run, binPath) {
-  process.stdout.write(`${JSON.stringify(serializeRun(run, { name: NAME, bin: binPath }))}\n`);
+function answer(run, binPath, extras) {
+  process.stdout.write(
+    `${JSON.stringify(
+      serializeRun(run, { name: NAME, bin: binPath, skills: extras.skills, usage: extras.usage }),
+    )}\n`,
+  );
   process.exit(0);
 }

package/agents/cursor-extras.mjs

@@ -0,0 +1,142 @@
+/**
+ * Extract mason AgentExtras from a Cursor CLI stdout blob.
+ *
+ * Skills: documented stream-json `tool_call` / `readToolCall` with a path that
+ * ends in `/skills/<name>/SKILL.md` (Cursor skills are SKILL.md files the
+ * agent reads). Count each `call_id` once, on `started`.
+ *
+ * Usage: last JSON object (the terminal `result`) may carry a `usage` object
+ * with camelCase token fields (observed; not in the published json schema).
+ * No cost field is documented for Cursor — `costUsd` stays null.
+ *
+ * `skills` is `null` when the stdout is not NDJSON we can parse (unknown),
+ * `[]` when we parsed and found no skill reads.
+ */
+
+import { readResult } from "@bluewombat/slot-kit";
+
+/**
+ * @param {string} stdout
+ * @param {string} outputFormat
+ * @returns {{ skills: string[] | null, usage: import("@bluewombat/slot-kit").AgentUsage | null }}
+ */
+export function extrasFromCursor(stdout, outputFormat) {
+  return {
+    skills: outputFormat === "stream-json" ? skillsFromCursor(stdout) : null,
+    usage: usageFromCursor(stdout),
+  };
+}
+
+/**
+ * @param {string} stdout
+ * @returns {string[] | null}
+ */
+export function skillsFromCursor(stdout) {
+  const lines = stdout.split("\n").filter((line) => line.trim().length > 0);
+  if (lines.length === 0) {
+    return null;
+  }
+  /** @type {string[]} */
+  const skills = [];
+  /** @type {Set<string>} */
+  const seenCalls = new Set();
+  /** @type {Set<string>} */
+  const seenNames = new Set();
+  let parsedAny = false;
+  for (const line of lines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event === null || typeof event !== "object" || Array.isArray(event)) {
+      continue;
+    }
+    parsedAny = true;
+    if (event.type !== "tool_call" || event.subtype !== "started") {
+      continue;
+    }
+    const callId = typeof event.call_id === "string" ? event.call_id : "";
+    if (callId.length > 0 && seenCalls.has(callId)) {
+      continue;
+    }
+    const path = readToolPath(event.tool_call);
+    const name = skillNameFromPath(path);
+    if (name === undefined) {
+      continue;
+    }
+    if (callId.length > 0) {
+      seenCalls.add(callId);
+    }
+    if (seenNames.has(name)) {
+      continue;
+    }
+    seenNames.add(name);
+    skills.push(name);
+  }
+  return parsedAny ? skills : null;
+}
+
+/**
+ * @param {unknown} toolCall
+ * @returns {string | undefined}
+ */
+function readToolPath(toolCall) {
+  if (toolCall === null || typeof toolCall !== "object" || Array.isArray(toolCall)) {
+    return undefined;
+  }
+  const read = /** @type {Record<string, unknown>} */ (toolCall).readToolCall;
+  if (read === null || typeof read !== "object" || Array.isArray(read)) {
+    return undefined;
+  }
+  const args = /** @type {Record<string, unknown>} */ (read).args;
+  if (args === null || typeof args !== "object" || Array.isArray(args)) {
+    return undefined;
+  }
+  const path = /** @type {Record<string, unknown>} */ (args).path;
+  return typeof path === "string" ? path : undefined;
+}
+
+/**
+ * @param {string | undefined} path
+ * @returns {string | undefined}
+ */
+export function skillNameFromPath(path) {
+  if (path === undefined) {
+    return undefined;
+  }
+  const match = path.match(/(?:^|[/\\])skills[/\\]([^/\\]+)[/\\]SKILL\.md$/i);
+  return match?.[1];
+}
+
+/**
+ * @param {string} stdout
+ * @returns {import("@bluewombat/slot-kit").AgentUsage | null}
+ */
+export function usageFromCursor(stdout) {
+  const result = readResult(stdout);
+  if (result === undefined) {
+    return null;
+  }
+  const usage = result.usage;
+  if (usage === null || typeof usage !== "object" || Array.isArray(usage)) {
+    return null;
+  }
+  const record = /** @type {Record<string, unknown>} */ (usage);
+  if (
+    typeof record.inputTokens !== "number" ||
+    typeof record.outputTokens !== "number" ||
+    typeof record.cacheReadTokens !== "number" ||
+    typeof record.cacheWriteTokens !== "number"
+  ) {
+    return null;
+  }
+  return {
+    input: record.inputTokens,
+    output: record.outputTokens,
+    cacheRead: record.cacheReadTokens,
+    cacheWrite: record.cacheWriteTokens,
+    costUsd: null,
+  };
+}

package/agents/cursor.mjs

@@ -12,6 +12,7 @@ import {
   textOption,
   transcriptFor,
 } from "@bluewombat/slot-kit";
+import { extrasFromCursor } from "./cursor-extras.mjs";
 
 // Cursor CLI as a vendor agent. The prompt is already filled: this command
 // does not interpolate. Own options only — a role slot strips Implementer's
@@ -19,7 +20,7 @@ import {
 //   --prompt TEXT / --prompt-file PATH   the filled prompt. One of the two
 //   --bin PATH            the Cursor CLI. Default: cursor-agent, found
 //   --model NAME
-//   --output-format FMT   json (default), text, or stream-json
+//   --output-format FMT   stream-json (default), json, or text
 //   --transcript-dir PATH write one file per turn. Off by default
 //   --transcript-part NAME prompt, stdout, stderr, timing. Repeatable
 //   --agent-arg VALUE     appended before the prompt. Repeatable
@@ -51,6 +52,8 @@ if (bin === undefined) {
 }
 
 const model = textOption(options, "model");
+/** @type {string} */
+const outputFormat = /** @type {string} */ (options.outputFormat);
 const args = [
   "-p",
   "--force",
@@ -60,7 +63,7 @@ const args = [
   "--sandbox",
   "disabled",
   "--output-format",
-  /** @type {string} */ (options.outputFormat),
+  outputFormat,
   ...(model === undefined ? [] : ["--model", model]),
   ...listOption(options, "agentArg"),
   prompt,
@@ -73,8 +76,9 @@ const transcript = transcriptFor(process.argv, options, {
   prompt,
 });
 const run = await runAgent({ file: bin, args, cwd });
-transcript.write(run);
-answer(run, bin);
+const extras = extrasFromCursor(run.stdout, outputFormat);
+transcript.write(run, extras);
+answer(run, bin, extras);
 
 /** @param {string} reason @returns {never} */
 function refuse(reason) {
@@ -85,9 +89,14 @@ function refuse(reason) {
 /**
  * @param {import("@bluewombat/slot-kit").AgentRun} run
  * @param {string} binPath
+ * @param {import("@bluewombat/slot-kit").AgentExtras} extras
  * @returns {never}
  */
-function answer(run, binPath) {
-  process.stdout.write(`${JSON.stringify(serializeRun(run, { name: NAME, bin: binPath }))}\n`);
+function answer(run, binPath, extras) {
+  process.stdout.write(
+    `${JSON.stringify(
+      serializeRun(run, { name: NAME, bin: binPath, skills: extras.skills, usage: extras.usage }),
+    )}\n`,
+  );
   process.exit(0);
 }

package/builders/producer.mjs

@@ -24,6 +24,10 @@ Task:
 
 {{done_when}}
 
+This checkout already includes any earlier subtasks that were folded into the
+feature. Do not rewrite that work. Add or change only what this task names, and
+leave the project's own checks green on the whole tree.
+
 Rules of this run:
 {{rules}}
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Shipped mason slots: Planners, Builders, Gates, publishers, and refreshers a Project names in its config.",
   "keywords": [
@@ -53,6 +53,6 @@
     "test": "tsx --test $(find test -name '*.test.ts')"
   },
   "dependencies": {
-    "@bluewombat/slot-kit": "^0.1.1"
+    "@bluewombat/slot-kit": "^0.1.2"
   }
 }

package/planners/producer.mjs

@@ -36,7 +36,11 @@ How the subtasks will be run, which is what makes a good split:
 
 - One at a time, never in parallel. Each runs in its own copy of this project,
   and its result is folded back before the next one starts. So a later subtask
-  sees the earlier ones' work.
+  sees the earlier ones' work. If two slices would both change the same path
+  (a README, an index or barrel file, a changelog, package.json, or any other
+  shared file), make them **one** subtask, or give the second a \`depends_on\` on
+  the first and let **only** that second one write the shared path. Do not invent
+  a docs-only subtask unless the work asked for documentation.
 - Every subtask is checked by the project's own checks — its tests, its lint —
   on its own. **A subtask must leave the project working.** This is the rule that
   decides your split: never cut by layer. "Add the types", then "add the code",
@@ -58,9 +62,11 @@ How the subtasks will be run, which is what makes a good split:
   mind, and preferably by a test. It describes this subtask's observable result,
   not the whole feature and not an intention.
 - \`depends_on\` means "cannot start before this one is done", and nothing else.
-  List only what a subtask genuinely cannot begin without. Chaining every
-  subtask to the one before it, out of habit, describes an order you were never
-  asked for and hides which ones were actually independent.
+  Sharing a file is a reason not to start side by side: pack those slices into
+  one subtask, or make the later one depend on the earlier. The graph describes
+  what must land before a merge is safe, not the order you happened to think in.
+  Chaining every subtask to the one before it when their files do not overlap
+  hides which ones were actually independent.
 
 You are choosing between two costs, and both are real.