@bluewombat/slots 0.9.0 → 0.11.0

package/builders/feature-test.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import {
+  BUILDER_FLAGS,
+  emitFailure,
+  fillPrompt,
+  finishRun,
+  loadPrompt,
+  loadRules,
+  PROMPT_RULES,
+  parseRole,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+import { attemptOf } from "../lib/fill.mjs";
+
+// The Ticket that holds a Feature's tests. One command for its first pass and for a pass a Gate
+// refused: the tests are written once from the scenarios of the task, and a refusal is about their
+// form, so there is no second command to tell apart. `{{report}}` and `{{refused_by}}` are empty
+// on a first pass; `{{refusal}}` is a ready-made paragraph about them.
+
+const NAME = "builder feature-test";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+You write the tests of a feature. The task below lists its scenarios, agreed with the operator
+before development, each with an id (S1, S2, ...). The feature is built: this checkout holds every
+other Ticket of it.
+
+Task:
+{{task}}
+
+- Write one test per scenario, in the test framework this project already uses, at the level the
+  scenario describes (through the feature's public interfaces: routes, services, pages), and start
+  the name of each test with its scenario id ("S1 …"). Follow the scenario's steps and expected
+  result as written; do not add, merge, drop or weaken one. If a scenario changes a behaviour that
+  existing tests describe, update those tests to the new behaviour, and only those.
+- List the ids of the scenarios in the manifest \`feature-tests/scenarios.json\`, a JSON array:
+  ["S1", "S2"]. Only the scenarios of this feature, never the project's other tests.
+- Write only tests, their helpers and the manifest. Touch no file of the application, and add no
+  dependency it does not already have.
+- A Gate runs your tests against the built feature after every attempt and gives you its report
+  (the refusal below). Read it: a test that fails for its own reasons (a wrong selector or wait, a
+  wrong data setup, a misread expectation) is yours to fix. Check only that your tests compile
+  before you finish, with the project's own typecheck or build command.
+- If a test stays red because the feature does not do what the scenario says, do not change the
+  application and do not weaken the test: that is a finding. Change nothing more and end with
+  MASON_BLOCKED, naming the scenario, what the feature does instead and where.
+
+{{refusal}}
+
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (a scenario is ambiguous, cannot be written without
+changing the application or without a weaker result than asked, the framework is missing, the
+feature is wrong, the cause is outside this directory), do not invent a change and do not lower
+the scenario. Change nothing and end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
+Rules of this run:
+{{rules}}
+`;
+
+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, PROMPT_RULES);
+if (!rules.ok) {
+  emitFailure("fail-blocking", rules.reason);
+  process.exit(1);
+}
+
+const report = (take(process.argv, "--report") ?? "").trim();
+const refusedBy = (take(process.argv, "--report-from") ?? "").trim();
+const refusal =
+  report.length === 0
+    ? ""
+    : [
+        "What is in this directory is what an earlier attempt left. It was refused",
+        `${refusedBy.length > 0 ? `by ${refusedBy}` : "by a check"}:`,
+        "",
+        "```raw",
+        report,
+        "```",
+        "",
+        "Resolve that, change what it takes and nothing more.",
+      ].join("\n");
+
+const rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
+    refusal,
+    report,
+    refused_by: refusedBy,
+    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);
+}
+finishRun({ run: spawned.run, bin: spawned.about.bin, name: spawned.about.name });

package/builders/producer.mjs

@@ -25,6 +25,10 @@ Task:
 This checkout is the project as it stands. Add or change only what this task
 names, and leave the project's own checks green on the whole tree.
 
+When the latest commit of this checkout is titled "Tests: …", the tests of this task were
+written before the code and committed. They are the specification: make them pass as they
+are. Do not edit, delete or rename them.
+
 {{history}}
 
 ## When you cannot act

package/builders/repair.mjs

@@ -38,6 +38,10 @@ This was asked in the first place, and still holds:
 
 {{task}}
 
+When the latest commit of this checkout is titled "Tests: …", the tests of this task were
+written before the code and committed. They are the specification: make them pass as they
+are. Do not edit, delete or rename them.
+
 {{history}}
 
 ## When you cannot act

package/feature/fix.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import {
+  BUILDER_FLAGS,
+  emitFailure,
+  fillPrompt,
+  finishRun,
+  loadPrompt,
+  loadRules,
+  PROMPT_RULES,
+  parseRole,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+import { attemptOf } from "../lib/fill.mjs";
+
+const NAME = "feature fix";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+This directory is a whole feature: the work of all its tickets, already
+assembled and checked ticket by ticket. It was then brought up to date with the
+branch it will be merged into, and checked again as a whole. Something refused
+it after that: a merge conflict while bringing it up to date, a check that fails
+on the result, or the project's CI. Do not redo the feature, or any ticket of
+it. Fix what the refusal names.
+
+Refused by: {{refused_by}}
+
+What it said:
+
+\`\`\`raw
+{{report}}
+\`\`\`
+
+YOUR WORK NOW IS TO RESOLVE THAT. Change what it takes and nothing more; what is
+already here and passes is not to be redone.
+
+## According to who refused
+
+- **A merge conflict** (refused by \`align\`): the report names the branch the
+  feature is merged into. Look at what that branch changed since this feature
+  started (compare the two with git), then edit the files in conflict so that
+  both sets of changes hold: what the branch added stays, and the feature still
+  does what it asks. Do not drop the branch's changes to keep yours. Leave the
+  result uncommitted.
+- **A check** (a gate named by its id, such as the typecheck or the tests): run
+  the failing command here the way the gate ran it, see the error, fix the
+  cause. The error often comes from what the target branch brought in, or from
+  two tickets that were each fine alone: adapt the feature's code to it.
+- **The CI**: reproduce the failing job's command here, then fix it. Change the
+  work, not the CI definition.
+
+## Original request
+
+This was asked in the first place, and still holds:
+
+{{task}}
+
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
+## Rules of this run
+
+{{rules}}
+`;
+
+const report = (take(process.argv, "--report") ?? "").trim();
+if (report.length === 0) {
+  emitFailure("fail-blocking", "The feature fix command needs --report.");
+  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, PROMPT_RULES);
+if (!rules.ok) {
+  emitFailure("fail-blocking", rules.reason);
+  process.exit(1);
+}
+
+const refusedBy = (take(process.argv, "--report-from") ?? "").trim();
+const rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
+    report,
+    refused_by:
+      refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",
+    rules: rules.value.trim(),
+    id: take(process.argv, "--id") ?? "",
+    attempt: String(attemptOf(process.argv)),
+  },
+  ["task", "report", "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);
+}
+finishRun({ run: spawned.run, bin: spawned.about.bin, name: spawned.about.name });

package/feature/validate.mjs

@@ -0,0 +1,205 @@
+#!/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 = "feature validate";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+This directory is a whole feature: the work of all its tickets, already
+assembled, and brought up to date with the branch it will be merged into. Each
+ticket was checked and reviewed on its own. Your job now is different: read the
+diff it carries against that branch, and judge whether the WHOLE feature meets
+what was asked of the feature. Look for what no ticket covers, for what two
+tickets contradict or leave half-connected, and for what the merge with the
+branch broke. Do not re-judge each ticket. Do not redo the work. Do not change
+anything — this is a read-only review, not a repair.
+
+## What was asked of the feature
+
+{{task}}
+
+## Your answer
+
+End your final message with exactly one line in this form, and nothing after
+it:
+
+- \`MASON_VERDICT: VALIDATED\` — the feature meets what was asked.
+- \`MASON_VERDICT: REFUSED: <one paragraph>\` — it does not, and the paragraph
+  says what is missing or 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 what was asked of the feature, not the style of the tickets 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",
+    "feature.validate is a read-only review; it does not take --report — that is feature.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",
+      `feature.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 : "feature.validate refused the feature, with no reason given.",
+    );
+    process.exit(1);
+  }
+  if (/^VALIDATED\b/i.test(verdict)) {
+    process.exit(0);
+  }
+  emitFailure(
+    "fail-retryable",
+    `feature.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;
+}