@bluewombat/slots 0.1.0

package/planners/producer.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  checkPlan,
+  emitPlan,
+  emitRefusal,
+  fillPrompt,
+  loadPrompt,
+  PLANNER_FLAGS,
+  parseRole,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+
+const NAME = "planner producer";
+
+const DEFAULT_TEMPLATE = `You are splitting one piece of work into an ordered list of subtasks.
+
+You are not writing any of it. Do not modify anything in this directory. Read as
+much of it as you need first: the split has to fit the project as it is. Do not
+invent conventions you can discover from the repository.
+
+The work:
+{{intention}}
+
+Treat that as the source of truth for the desired outcome, not as a finished
+specification. Its wording may be incomplete. Separate what it explicitly
+requires from what the repository or ordinary engineering practice implies.
+Do not invent requirements to make the plan look complete.
+
+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.
+- 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",
+  then "add the tests" is wrong, because the first two leave the project broken.
+  Cut by thin slices that each work end to end. Tests belong in the subtask that
+  introduces or changes the behavior they verify.
+- Each subtask is given to an agent with no memory of you and no memory of the
+  others. Its intention has to stand alone: no "as discussed above", no knowledge
+  of this planning process, no requirement that lives only in the original work
+  description. Copy into the subtask everything its agent needs. A pointer at
+  existing code is fine if it names the behavior or location clearly enough to
+  investigate.
+- Write each intention the way a good commit message is written: one headline
+  of at most 72 characters in the imperative ("Add titleCase in
+  src/title-case.js"), a blank line, then everything the agent needs. The
+  headline is what people see: in the plan on the tracker, in the change list
+  of the submission, on the commit.
+- Its definition of done has to be checkable by someone who cannot read your
+  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.
+
+You are choosing between two costs, and both are real.
+
+Splitting too finely costs a full agent run per slice, and each slice pays the
+project's whole check sequence again. Do not create a subtask solely to read
+code, decide what to implement, create folders, rename things, add comments,
+write documentation (unless the work asked for it), clean up, or refactor
+speculatively.
+
+Not splitting enough costs more, and less visibly. One subtask is one agent run,
+with one budget of attempts and one clock: a subtask too large for that exhausts
+them and the whole piece of work stops. And a subtask that fails goes back to
+nothing, while a subtask that succeeded is never redone. Ten modules in one
+subtask means ten modules redone when the tenth goes wrong.
+
+Prefer adapting what the project already does over introducing a parallel
+mechanism. Do not propose an architectural change merely because it might be
+cleaner.
+
+So: as few subtasks as the work allows, and none larger than what one competent
+engineer would finish in a single sitting without losing the thread. At most
+{{max_units}}.
+
+Write your answer as JSON, and nothing else, to this file:
+
+{{out}}
+
+It looks like this:
+
+{
+  "subtasks": [
+    { "id": "s1", "intention": "Headline\\n\\nEverything the agent needs.", "definition_of_done": "...", "depends_on": [] },
+    { "id": "s2", "intention": "Headline\\n\\n...", "definition_of_done": "...", "depends_on": ["s1"] }
+  ]
+}
+
+If the work cannot be split as it is written — contradictory outcomes, a
+critical requirement so ambiguous that the implementation would change with
+the reading, or too little to determine what should be built — write this
+instead, and do not invent a plan to fill the silence. Do not refuse merely
+because some implementation details are unspecified; those come from the
+repository.
+
+{ "outcome": "refused", "reason": "..." }
+`;
+
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (intention.length === 0) {
+  fail("The Planner received no --intention.");
+}
+
+const parsed = parseRole(process.argv, PLANNER_FLAGS, NAME, { "--read": {} });
+if (!parsed.ok) {
+  fail(parsed.reason);
+}
+
+const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
+if (!template.ok) {
+  fail(template.reason);
+}
+
+const maxUnits = Number.parseInt(take(process.argv, "--max-units") ?? "", 10);
+const scratch = mkdtempSync(join(tmpdir(), "plan-"));
+const out = join(scratch, "plan.json");
+const cwd = textOption(parsed.options, "read") ?? process.cwd();
+
+try {
+  const rendered = fillPrompt(
+    template.value,
+    {
+      intention,
+      max_units: Number.isInteger(maxUnits) ? String(maxUnits) : "a handful",
+      out,
+    },
+    ["intention", "out"],
+    textOption(parsed.options, "promptFile") ?? "built-in template",
+  );
+  if (!rendered.ok) {
+    fail(rendered.reason);
+  }
+
+  const spawned = await spawnFilled(
+    parsed.runner,
+    rendered.prompt,
+    transcriptArgs(process.argv, {
+      id: "breakdown",
+      context: take(process.argv, "--key"),
+    }),
+    cwd,
+  );
+  if (!spawned.ok) {
+    fail(spawned.reason);
+  }
+  if (spawned.run.error !== undefined) {
+    fail(`Could not start the agent at ${spawned.about.bin}: ${spawned.run.error.message}`);
+  }
+
+  const answer = readAnswer(out);
+  if (answer === undefined) {
+    fail(`The agent wrote no usable plan to ${out}. ${tail(spawned.run.output)}`);
+  }
+  if (answer.outcome === "refused") {
+    const reason =
+      typeof answer.reason === "string" && answer.reason.trim().length > 0
+        ? answer.reason.trim()
+        : "The Planner refused without saying why.";
+    emitRefusal(reason);
+    process.exit(0);
+  }
+
+  const checked = checkPlan(answer.subtasks, maxUnits);
+  if (!checked.ok) {
+    fail(`The agent returned a plan that cannot be used: ${checked.reason}`);
+  }
+  emitPlan(
+    checked.subtasks.map((subtask) => ({
+      id: subtask.id,
+      intention: subtask.intention,
+      definition_of_done: subtask.definition_of_done,
+      depends_on: subtask.depends_on,
+    })),
+  );
+  process.exit(0);
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}
+
+/** @param {string} path @returns {Record<string, unknown> | undefined} */
+function readAnswer(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+  for (const candidate of [fenced?.[1], text]) {
+    if (candidate === undefined) {
+      continue;
+    }
+    try {
+      const value = JSON.parse(candidate);
+      if (value !== null && typeof value === "object") {
+        return value;
+      }
+    } catch {
+      // try the next reading
+    }
+  }
+  return undefined;
+}
+
+/** @param {string | undefined} output */
+function tail(output) {
+  const trimmed = (output ?? "").trim();
+  return trimmed.length === 0 ? "" : trimmed.slice(-1000);
+}
+
+/** @param {string} reason @returns {never} */
+function fail(reason) {
+  process.stderr.write(`${reason}\n`);
+  process.exit(1);
+}

package/publishers/git.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  emitPublication,
+  emitPublishRefusal,
+  ownArgv,
+  PUBLISHER_FLAGS,
+  take,
+} from "@bluewombat/slot-kit";
+
+// Put the feature's work where the Authority can read it, by pushing the name
+// Isolator gave it to the work line's own remote.
+//
+// A plain push, and no force of any kind. Integrator only ever adds history, so
+// republishing after a refusal is a fast-forward of what was already there. A
+// rejection therefore means the name moved under us — someone else's commit, or
+// a rewrite — and that is exactly the case worth refusing rather than
+// overwriting.
+//
+// The remote is `origin`, and there is no option for it: Host reads the work
+// line back from `origin` after the Authority folds, with no way to learn what
+// this slot was told. An option that publishes to one remote while the refresh
+// reads another is a trap, so it waits for that half to become a slot too.
+//
+// Runs in the work line. mason appends --id, --ref and --target.
+
+const cwd = process.cwd();
+const tokens = ownArgv(process.argv, PUBLISHER_FLAGS);
+if (tokens.length > 0) {
+  emitPublishRefusal(`git publisher takes no option, got "${tokens[0]}".`);
+  process.exit(0);
+}
+const remote = "origin";
+
+const ref = take(process.argv, "--ref");
+if (ref === undefined || ref.trim().length === 0) {
+  emitPublishRefusal("git publisher was given no --ref to publish.");
+  process.exit(0);
+}
+
+if (!existsSync(join(cwd, ".git"))) {
+  emitPublishRefusal("A Submission needs a git work line; this one has no .git.");
+  process.exit(0);
+}
+
+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`);
+  process.exit(1);
+}
+if (pushed.status !== 0) {
+  const detail = `${pushed.stderr ?? ""}${pushed.stdout ?? ""}`.trim().slice(-1000);
+  emitPublishRefusal(`Could not publish ${ref}: ${detail}`);
+  process.exit(0);
+}
+
+emitPublication(ref);

package/refreshers/git.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  emitRefreshed,
+  emitRefreshRefusal,
+  ownArgv,
+  REFRESHER_FLAGS,
+  take,
+} from "@bluewombat/slot-kit";
+
+// Bring the work line copy up to what the Authority holds.
+//
+// An accepted Submission moved the reference work line. A copy left behind
+// would make the next Isolation start from a version that no longer exists, so
+// this runs before anything else in a pass.
+//
+// Fast-forward only: this system never rewrites that line. A copy that cannot
+// fast-forward has been written to by somebody else, and that is a person's
+// problem, not a merge to attempt.
+//
+// The remote is `origin`, like the git Publisher's. Takes no option.
+
+const cwd = process.cwd();
+const tokens = ownArgv(process.argv, REFRESHER_FLAGS);
+if (tokens.length > 0) {
+  emitRefreshRefusal(`git refresher takes no option, got "${tokens[0]}".`);
+  process.exit(0);
+}
+
+const target = take(process.argv, "--target");
+if (target === undefined || target.trim().length === 0) {
+  emitRefreshRefusal("git refresher was given no --target work line.");
+  process.exit(0);
+}
+
+// A plain directory has no reference held anywhere else: it is the work line.
+if (!existsSync(join(cwd, ".git"))) {
+  emitRefreshed();
+  process.exit(0);
+}
+
+const fetched = git(["fetch", "origin", target]);
+if (fetched.status !== 0) {
+  emitRefreshRefusal(
+    `Cannot fetch origin/${target} from ${cwd}: ${fetched.stderr.trim().slice(-500)}`,
+  );
+  process.exit(0);
+}
+
+const merged = git(["merge", "--ff-only", `origin/${target}`]);
+if (merged.status !== 0) {
+  // The one way a copy stops fast-forwarding is a commit made into it that
+  // the reference does not have. The copy is the system's, not a person's:
+  // nothing in it is worth keeping, and the reader needs the way out more
+  // than git's own words.
+  emitRefreshRefusal(
+    [
+      `${cwd} has diverged from origin/${target}: it holds commits the reference does not.`,
+      "Nothing in this copy is worth keeping — it is the system's, refetched at every start.",
+      `Put it back with: git -C ${cwd} reset --hard origin/${target}`,
+      "or delete the directory and start again; it is fetched afresh.",
+      `git said: ${merged.stderr.trim().slice(-300)}`,
+    ].join("\n"),
+  );
+  process.exit(0);
+}
+
+emitRefreshed();
+
+/** @param {string[]} args */
+function git(args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}