@bluewombat/slots 0.1.1 → 0.2.0

package/README.md

@@ -58,30 +58,32 @@ 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}}`                |
+| `assembly/validate.mjs`       | Builder   | Read-only review of the assembled feature: fill `{{task}}`; answers `MASON_VERDICT: VALIDATED` or `MASON_VERDICT: REFUSED: …` |
+| `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
 
 A vendor CLI is not a Builder. `agents/cursor.mjs` and `agents/claude.mjs` take
 a prompt that is **already filled**, run the vendor, write a transcript if asked,
-and print the serialized run on stdout. They do not know `--intention` or
-`--report`. A role slot after `--` is what names one:
+and print the serialized run on stdout with `writeContract` (so a large
+stream-json transcript survives `process.exit`). They do not know `--intention`
+or `--report`. A role slot after `--` is what names one:
 
 ```json
 "--",
@@ -92,18 +94,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 +179,12 @@ 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}}`                  |
+| `assembly/validate` | `{{task}}`, `{{rules}}`               | `{{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.
@@ -185,6 +206,27 @@ The units already passed. `assembly/fix.mjs` tells the agent to change what the
 refusal names and leave the rest. Same placeholders as repair except
 `{{done_when}}`, which an assembly has nothing to fill.
 
+### The validate prompt
+
+`assembly/validate.mjs` is a different kind of Builder: it never writes. It
+fills only `{{task}}` and `{{rules}}` — there is nothing to fix yet, so no
+`{{report}}` — and asks the agent to end its final message with one line:
+`MASON_VERDICT: VALIDATED` or `MASON_VERDICT: REFUSED: <one paragraph>`. Its
+own `{{rules}}` default is not `PROMPT_RULES`: a review has no work to leave
+uncommitted and nothing to push, so it says "read-only" instead of "do not
+commit, do not push".
+
+The slot does not trust the CLI's exit code alone — a review can complete
+cleanly and still find a problem. It reads the agent's own final answer
+(`readResult(run.stdout)?.result`) for the **last** line starting with
+`MASON_VERDICT:` — not a bare search for "VALIDATED" or "REFUSED" anywhere in
+the text, which a model's own reasoning can contain by accident ("the units
+were already validated on their own"). It maps a `REFUSED:` verdict through
+`emitFailure("fail-retryable", …)` itself, the report being what followed
+`REFUSED:` on that line. No `MASON_VERDICT:` line, or one that is neither
+form, is treated the same way, naming what the agent said: a review that did
+not answer as asked is not a silent pass.
+
 ### The rules
 
 `{{rules}}` holds the bounds of the slot: one directory, work left uncommitted,
@@ -206,9 +248,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 +388,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

@@ -11,7 +11,9 @@ import {
   serializeRun,
   textOption,
   transcriptFor,
+  writeContract,
 } 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 +21,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 +61,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,21 +83,27 @@ 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) {
-  process.stdout.write(`${JSON.stringify({ error: reason })}\n`);
+  writeContract(`${JSON.stringify({ error: reason })}\n`);
   process.exit(1);
 }
 
 /**
  * @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) {
+  writeContract(
+    `${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

@@ -11,7 +11,9 @@ import {
   serializeRun,
   textOption,
   transcriptFor,
+  writeContract,
 } 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 +21,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 +53,8 @@ if (bin === undefined) {
 }
 
 const model = textOption(options, "model");
+/** @type {string} */
+const outputFormat = /** @type {string} */ (options.outputFormat);
 const args = [
   "-p",
   "--force",
@@ -60,7 +64,7 @@ const args = [
   "--sandbox",
   "disabled",
   "--output-format",
-  /** @type {string} */ (options.outputFormat),
+  outputFormat,
   ...(model === undefined ? [] : ["--model", model]),
   ...listOption(options, "agentArg"),
   prompt,
@@ -73,21 +77,27 @@ 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) {
-  process.stdout.write(`${JSON.stringify({ error: reason })}\n`);
+  writeContract(`${JSON.stringify({ error: reason })}\n`);
   process.exit(1);
 }
 
 /**
  * @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) {
+  writeContract(
+    `${JSON.stringify(
+      serializeRun(run, { name: NAME, bin: binPath, skills: extras.skills, usage: extras.usage }),
+    )}\n`,
+  );
   process.exit(0);
 }

package/assembly/validate.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import {
+  BUILDER_FLAGS,
+  emitFailure,
+  failureOf,
+  fillPrompt,
+  loadPrompt,
+  loadRules,
+  parseRole,
+  readResult,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+import { attemptOf } from "../lib/fill.mjs";
+
+const NAME = "assembly validate";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+This directory is the assembled feature. Every unit of work that makes it up
+has already been validated on its own. Your job now is different: read the
+diff this feature carries against the work line it will land on, and judge
+whether the WHOLE meets what was asked. Do not redo the units. Do not change
+anything — this is a read-only review, not a repair.
+
+## What was asked
+
+{{task}}
+
+## Your answer
+
+End your final message with exactly one line in this form, and nothing after
+it:
+
+- \`MASON_VERDICT: VALIDATED\` — the assembled feature meets what was asked.
+- \`MASON_VERDICT: REFUSED: <one paragraph>\` — it does not, and the paragraph
+  says what is wrong, specifically enough for another agent to fix it without
+  redoing your review. Keep the whole paragraph on that one line.
+
+Nothing else may start a line with \`MASON_VERDICT:\`. You may explain your
+reasoning before it, but that line is what is read — write it last.
+
+## Rules of this run
+
+{{rules}}
+`;
+
+/**
+ * A reviewer's bounds: read-only, and answer in the one shape the caller
+ * parses. `PROMPT_RULES` tells a producer to leave work uncommitted and push
+ * nothing — obligations a Task that writes nothing does not have.
+ */
+const DEFAULT_RULES = [
+  "- Work only inside this directory. Do not read or edit anything outside it.",
+  "- This is a review, not a repair: do not change, stage, commit, or stash any file.",
+  "- Judge the diff against the intention above, not the style of the units that made it.",
+  "- Nobody is watching this run and nobody will answer a question. Where the intention is",
+  "  ambiguous, take the reading most consistent with the existing code, and say which one",
+  "  you took in your answer.",
+  "- End your final message with one line: MASON_VERDICT: VALIDATED, or",
+  "  MASON_VERDICT: REFUSED: <one paragraph, on that one line>.",
+].join("\n");
+
+const report = (take(process.argv, "--report") ?? "").trim();
+if (report.length > 0) {
+  emitFailure(
+    "fail-blocking",
+    "assembly.validate is a read-only review; it does not take --report — that is assembly.fix's job.",
+  );
+  process.exit(1);
+}
+
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (intention.length === 0) {
+  emitFailure("fail-blocking", "The Builder received no --intention.");
+  process.exit(1);
+}
+
+const parsed = parseRole(process.argv, BUILDER_FLAGS, NAME);
+if (!parsed.ok) {
+  emitFailure("fail-blocking", parsed.reason);
+  process.exit(1);
+}
+
+const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
+if (!template.ok) {
+  emitFailure("fail-blocking", template.reason);
+  process.exit(1);
+}
+const rules = loadRules(parsed.options, DEFAULT_RULES);
+if (!rules.ok) {
+  emitFailure("fail-blocking", rules.reason);
+  process.exit(1);
+}
+
+const rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    rules: rules.value.trim(),
+    id: take(process.argv, "--id") ?? "",
+    attempt: String(attemptOf(process.argv)),
+  },
+  ["task", "rules"],
+  textOption(parsed.options, "promptFile") ?? "built-in template",
+);
+if (!rendered.ok) {
+  emitFailure("fail-blocking", rendered.reason);
+  process.exit(1);
+}
+
+const spawned = await spawnFilled(parsed.runner, rendered.prompt, transcriptArgs(process.argv));
+if (!spawned.ok) {
+  emitFailure("fail-blocking", spawned.reason);
+  process.exit(1);
+}
+
+answer(spawned.run, spawned.about.bin, spawned.about.name);
+
+/**
+ * Read the agent's own verdict and map it through `emitFailure` — never
+ * through exit 0 alone. A review that completes cleanly still has to answer
+ * whether the work is right; the CLI exiting 0 only says the review ran.
+ *
+ * @param {import("@bluewombat/slot-kit").AgentRun} run
+ * @param {string} bin
+ * @param {string} name
+ * @returns {never}
+ */
+function answer(run, bin, name) {
+  if (run.error !== undefined || run.code !== 0) {
+    const failure = failureOf(run, bin, name);
+    emitFailure(failure.outcome, failure.report);
+    process.exit(1);
+  }
+  const result = readResult(run.stdout);
+  if (result?.is_error === true) {
+    const failure = failureOf(run, bin, name);
+    emitFailure(failure.outcome, failure.report);
+    process.exit(1);
+  }
+  const said = typeof result?.result === "string" ? result.result.trim() : "";
+  const verdict = lastVerdictLine(said);
+  if (verdict === undefined) {
+    // No `MASON_VERDICT:` line at all is not a pass on the strength of exit 0.
+    // Treated as retryable, the same as any other malformed Attempt — the
+    // next round gets the same prompt again.
+    emitFailure(
+      "fail-retryable",
+      `assembly.validate found no MASON_VERDICT: line in the answer: ${
+        said.length > 0 ? said.slice(0, 500) : "(no answer)"
+      }`,
+    );
+    process.exit(1);
+  }
+  const refused = /^REFUSED:?\s*/i.exec(verdict);
+  if (refused !== null) {
+    const why = verdict.slice(refused[0].length).trim();
+    emitFailure(
+      "fail-retryable",
+      why.length > 0
+        ? why
+        : "assembly.validate refused the assembled feature, with no reason given.",
+    );
+    process.exit(1);
+  }
+  if (/^VALIDATED\b/i.test(verdict)) {
+    process.exit(0);
+  }
+  emitFailure(
+    "fail-retryable",
+    `assembly.validate's MASON_VERDICT: line was neither VALIDATED nor REFUSED: ${verdict.slice(0, 500)}`,
+  );
+  process.exit(1);
+}
+
+/**
+ * The text after the last line that starts with `MASON_VERDICT:`, or
+ * `undefined` when no such line exists.
+ *
+ * A distinctive, unlikely-to-collide marker, anchored to the start of a line
+ * — not a bare search for "VALIDATED" or "REFUSED" anywhere in the answer,
+ * which a model's own reasoning can contain by accident ("the units were
+ * already validated on their own"). The *last* such line wins: a model that
+ * restates its conclusion, or that is shown an example in the prompt, still
+ * means its final one.
+ *
+ * @param {string} text
+ * @returns {string | undefined}
+ */
+function lastVerdictLine(text) {
+  const marker = /^MASON_VERDICT:\s*/i;
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = (lines[i] ?? "").trim();
+    const match = marker.exec(line);
+    if (match !== null) {
+      return line.slice(match[0].length).trim();
+    }
+  }
+  return undefined;
+}

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/messages/conventional.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { emitMessage, MESSAGE_FLAGS, ownArgv, take } from "@bluewombat/slot-kit";
+import { emitMessage, MESSAGE_FLAGS, ownArgv, take, writeDiagnostic } from "@bluewombat/slot-kit";
 
 // The feature's commit in the Conventional Commits shape, from the issue's
 // title and body and with no agent: `<type>: <title>`, the body as written.
@@ -27,7 +27,7 @@ const forcedType = take(own, "--type");
 const title = (take(process.argv, "--title") ?? "").trim();
 const intention = (take(process.argv, "--intention") ?? "").trim();
 if (title.length === 0) {
-  process.stderr.write("conventional: no --title.\n");
+  writeDiagnostic("conventional: no --title.\n");
   process.exit(1);
 }
 

package/messages/git-producer.mjs

@@ -13,6 +13,7 @@ import {
   take,
   textOption,
   transcriptArgs,
+  writeDiagnostic,
 } from "@bluewombat/slot-kit";
 
 // The feature's commit message — and the pull request's description with it
@@ -146,6 +147,6 @@ function readAnswer(path) {
 
 /** @param {string} reason @returns {never} */
 function fail(reason) {
-  process.stderr.write(`${reason}\n`);
+  writeDiagnostic(`${reason}\n`);
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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.2.0"
   }
 }

package/planners/producer.mjs

@@ -14,6 +14,7 @@ import {
   take,
   textOption,
   transcriptArgs,
+  writeDiagnostic,
 } from "@bluewombat/slot-kit";
 
 const NAME = "planner producer";
@@ -36,7 +37,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 +63,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.
 
@@ -221,6 +228,6 @@ function tail(output) {
 
 /** @param {string} reason @returns {never} */
 function fail(reason) {
-  process.stderr.write(`${reason}\n`);
+  writeDiagnostic(`${reason}\n`);
   process.exit(1);
 }

package/publishers/git.mjs

@@ -8,6 +8,7 @@ import {
   ownArgv,
   PUBLISHER_FLAGS,
   take,
+  writeDiagnostic,
 } from "@bluewombat/slot-kit";
 
 // Put the feature's work where the Authority can read it, by pushing the name
@@ -49,7 +50,7 @@ const pushed = spawnSync("git", ["-C", cwd, "push", remote, `${ref}:${ref}`], {
   encoding: "utf8",
 });
 if (pushed.error !== undefined) {
-  process.stderr.write(`git publisher cannot run git: ${pushed.error.message}\n`);
+  writeDiagnostic(`git publisher cannot run git: ${pushed.error.message}\n`);
   process.exit(1);
 }
 if (pushed.status !== 0) {