@bluewombat/slots 0.1.2 → 0.2.0

package/README.md

@@ -65,6 +65,7 @@ these all use it. How Host wires a slot into a run:
 | `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                                                        |
@@ -80,8 +81,9 @@ these all use it. How Host wires a slot into a run:
 
 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
 "--",
@@ -182,6 +184,7 @@ assembly, so `assembly/fix` does not fill it at all.
 | `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.
@@ -203,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,

package/agents/claude.mjs

@@ -11,6 +11,7 @@ import {
   serializeRun,
   textOption,
   transcriptFor,
+  writeContract,
 } from "@bluewombat/slot-kit";
 import { extrasFromClaude } from "./claude-extras.mjs";
 
@@ -88,7 +89,7 @@ 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);
 }
 
@@ -99,7 +100,7 @@ function refuse(reason) {
  * @returns {never}
  */
 function answer(run, binPath, extras) {
-  process.stdout.write(
+  writeContract(
     `${JSON.stringify(
       serializeRun(run, { name: NAME, bin: binPath, skills: extras.skills, usage: extras.usage }),
     )}\n`,

package/agents/cursor.mjs

@@ -11,6 +11,7 @@ import {
   serializeRun,
   textOption,
   transcriptFor,
+  writeContract,
 } from "@bluewombat/slot-kit";
 import { extrasFromCursor } from "./cursor-extras.mjs";
 
@@ -82,7 +83,7 @@ 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);
 }
 
@@ -93,7 +94,7 @@ function refuse(reason) {
  * @returns {never}
  */
 function answer(run, binPath, extras) {
-  process.stdout.write(
+  writeContract(
     `${JSON.stringify(
       serializeRun(run, { name: NAME, bin: binPath, skills: extras.skills, usage: extras.usage }),
     )}\n`,

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/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.2",
+  "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.2"
+    "@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";
@@ -227,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) {