@bluewombat/slots 0.8.0 → 0.10.0

package/agents/claude.mjs

@@ -30,7 +30,7 @@ import { extrasFromClaude } from "./claude-extras.mjs";
 //   --agent-home / --api-key-env   recognised, then refused. Claude is not
 //                         isolated yet; starting would keep the operator's config
 //   --plugin-dir DIR      a plugin folder, repeatable (see agent-plugins.mjs)
-//   --profile / --plugins-out / --deck-bin   recognised, then refused for the
+//   --app-deck-profile / --plugins-out / --deck-bin   recognised, then refused for the
 //                         same reason: Claude would also load the operator's
 //                         and the project's own plugins, so a role's profile
 //                         would not be what it gets
@@ -64,12 +64,12 @@ if (
   );
 }
 if (
-  textOption(options, "profile") !== undefined ||
+  textOption(options, "appDeckProfile") !== undefined ||
   textOption(options, "pluginsOut") !== undefined ||
   textOption(options, "deckBin") !== undefined
 ) {
   refuse(
-    "Claude Code does not isolate the operator home yet, so a deck profile would not be all it loads. Remove --profile; the vendor was not started.",
+    "Claude Code does not isolate the operator home yet, so a deck profile would not be all it loads. Remove --app-deck-profile; the vendor was not started.",
   );
 }
 

package/agents/cursor.mjs

@@ -36,7 +36,7 @@ import { extrasFromCursor } from "./cursor-extras.mjs";
 //   --deny-shell NAME     with --agent-home: also refuse this command to the
 //                         vendor (`gh`, `vercel`…). Repeatable. ssh and scp are
 //                         always refused
-//   --plugin-dir / --profile / --plugins-out / --deck-bin   plugin folders,
+//   --plugin-dir / --app-deck-profile / --plugins-out / --deck-bin   plugin folders,
 //                         see agent-plugins.mjs
 //   --id / --attempt / --context   how a transcript is filed
 

package/builders/e2e.mjs

@@ -0,0 +1,124 @@
+#!/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 e2e acceptance suite. One command for its first pass and for
+// a pass a Gate refused: the suite is written once from the scenarios of the task, and a refusal
+// is about its 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 e2e";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+You write the acceptance suite of a feature. The task below lists its scenarios, agreed with the
+operator before development, each with an id (E1, E2, ...).
+
+Task:
+{{task}}
+
+- Write one test per scenario, in the end-to-end framework this project already uses, and
+  start the name of each test with its scenario id ("E1 …"). Follow the scenario's steps and
+  expected result as written; do not add, merge or drop one.
+- List the ids in the manifest \`e2e/scenarios.json\`, a JSON array: ["E1", "E2"].
+- Write only inside the suite folder (\`e2e/\`). Touch no file of the application, and add no
+  dependency it does not already have.
+- The feature is not finished here and the application is not started: do not run the suite. Check
+  only that it compiles, with the project's own typecheck or build command.
+
+{{refusal}}
+
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (a scenario is ambiguous, the framework is missing,
+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 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

@@ -13,7 +13,7 @@ import {
   textOption,
   transcriptArgs,
 } from "@bluewombat/slot-kit";
-import { attemptOf, doneWhen } from "../lib/fill.mjs";
+import { attemptOf } from "../lib/fill.mjs";
 
 const NAME = "builder producer";
 
@@ -22,11 +22,12 @@ const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkou
 Task:
 {{task}}
 
-{{done_when}}
+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.
 
-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.
+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}}
 
@@ -82,7 +83,6 @@ const rendered = fillPrompt(
   {
     task: intention,
     history: (take(process.argv, "--history") ?? "").trim(),
-    done_when: doneWhen(take(process.argv, "--definition-of-done")),
     rules: rules.value.trim(),
     id: take(process.argv, "--id") ?? "",
     attempt: String(attemptOf(process.argv)),

package/builders/repair.mjs

@@ -13,7 +13,7 @@ import {
   textOption,
   transcriptArgs,
 } from "@bluewombat/slot-kit";
-import { attemptOf, doneWhen } from "../lib/fill.mjs";
+import { attemptOf } from "../lib/fill.mjs";
 
 const NAME = "builder repair";
 
@@ -38,7 +38,9 @@ This was asked in the first place, and still holds:
 
 {{task}}
 
-{{done_when}}
+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}}
 
@@ -96,7 +98,6 @@ const rendered = fillPrompt(
     report,
     refused_by:
       refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",
-    done_when: doneWhen(take(process.argv, "--definition-of-done")),
     rules: rules.value.trim(),
     id: take(process.argv, "--id") ?? "",
     attempt: String(attemptOf(process.argv)),

package/builders/tests.mjs

@@ -0,0 +1,139 @@
+#!/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 = "builder tests";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+Task:
+{{task}}
+
+YOUR WORK NOW IS TO WRITE THE TESTS OF THIS TASK, AND ONLY THE TESTS. Another agent
+writes the code afterwards and must make your tests pass without editing them. A test it
+cannot pass is not sent back to you: it stops the task and waits for a person. So a test
+you deliver must be one that a correct implementation of the task passes, and you prove
+it before you hand it over (see below).
+
+## The cases
+
+- The task has a "Tests" section: write one test per case of it, in the file and the
+  framework it names (or the ones this repository already uses), each named after the
+  case it covers. Test the behaviour at the seam the section names, not how it is built.
+- The task has no "Tests" section: do not look for one elsewhere. Derive the cases from
+  its acceptance criteria ("Done when" or the like), one case per criterion, and name each
+  test after the criterion and the identifiers it carries. A criterion that describes two
+  sets of data (sixty rows for a page, more than a cap for the cap) is two cases, never one
+  test with two batches of data.
+- Do not write the behaviour. If the interface under test does not exist yet, create the
+  minimal stub — the name and signature the task gives, a body that does nothing useful —
+  so that the tests compile and fail on what they check, not on a missing import.
+- Add or update no other test, and no production code beyond the stubs.
+
+## How a test stays passable
+
+- One data set per test, seeded at the top. Every expectation derives from that set: the
+  rows a filter keeps, the order they take, the page a limit and an offset cut out of it.
+  Write the expected count from the seeded data, not as a figure recounted by hand.
+- To observe a bound, seed past it: a cap of 200 is only visible with more than 200 rows
+  that the filters keep. "At most N" is asserted with \`<= N\`, or by seeding more than N;
+  never as exactly N when fewer exist.
+
+## Prove them: red, green, red
+
+A test you have only seen fail proves nothing about itself: a test no implementation
+could pass fails exactly the same way. The tests must FAIL now, because the behaviour is
+missing, and you prove every one of them passable before you finish:
+
+1. **Red.** Run the tests. Each fails on an assertion (not on an import, a type, a syntax
+   error).
+2. **Green.** In the stub bodies — the same files, no new file — write the shortest
+   implementation of the task that makes every test pass: naive, in memory, unoptimised;
+   it is thrown away. Run the tests. A test still red here is wrong, not the task: fix its
+   data or its expectation (never drop a case, never replace a value the task gives with a
+   looser one), and run again until all are green.
+3. **Red again.** Put every stub body back to no behaviour. Run the tests: each fails
+   again on an assertion. Leave the tree in this state.
+
+Leave no trace of the green step: no helper, no import, no comment. The only non-test
+lines you deliver are the stubs.
+
+{{history}}
+
+## When you cannot act
+
+If the cases are missing, or contradict the task or the code, do not invent them. 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}}
+`;
+
+// A retry carries the refusal in --history; the flags themselves are consumed so the
+// role options see only their own.
+take(process.argv, "--report");
+take(process.argv, "--report-from");
+
+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 rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
+    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/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 });