@bluewombat/slots 0.8.0 → 0.10.0

package/lib/output-tail.mjs

@@ -0,0 +1,70 @@
+// The end of a command's output, for a Gate's report: what a person or an agent needs to read
+// to see why a check is red.
+//
+// Test runners and CLIs redraw a progress line (a spinner, "[✓] Pulling schema...") thousands of
+// times. Kept as bytes, those redraws push the real error out of the tail the report is cut from,
+// and the report says nothing but the spinner. So the output is cleaned line by line as it
+// arrives, before anything is dropped for size: escape codes removed, a line redrawn with "\r"
+// reduced to its last state, spinner and progress lines dropped.
+
+// CSI sequences (colors, erase line, cursor moves) and OSC sequences (titles, links).
+const ESC = String.fromCharCode(0x1b);
+const BEL = String.fromCharCode(0x07);
+const ESCAPES = new RegExp(
+  `${ESC}\\[[0-9;?]*[ -/]*[@-~]|${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`,
+  "g",
+);
+// A braille glyph is a spinner frame; "[✓] …..." is the line a spinner settles on.
+const SPINNER_FRAME = /[⠀-⣿]/;
+const SPINNER_DONE = /\[[✓✔]\].*\.\.\.\s*$/;
+
+/** One line, cleaned; null when it is only progress noise. */
+export function cleanLine(/** @type {string} */ raw) {
+  const redrawn = raw.split("\r").filter((part) => part.trim().length > 0);
+  const last = (redrawn.length > 0 ? redrawn[redrawn.length - 1] : "") ?? "";
+  const line = last.replace(ESCAPES, "").trimEnd();
+  if (SPINNER_FRAME.test(line) || SPINNER_DONE.test(line)) {
+    return null;
+  }
+  return line;
+}
+
+/**
+ * @param {number} maxChars what `text()` returns at most; older lines are dropped first.
+ */
+export function createOutputTail(maxChars) {
+  let kept = "";
+  /** @type {Map<string, string>} */
+  const partial = new Map();
+
+  const add = (/** @type {string} */ raw) => {
+    const line = cleanLine(raw);
+    if (line === null) {
+      return;
+    }
+    kept += `${line}\n`;
+    if (kept.length > maxChars * 2) {
+      kept = kept.slice(kept.length - maxChars);
+    }
+  };
+
+  return {
+    /** Feed a chunk of one stream; each stream keeps its own unfinished line. */
+    push(/** @type {string} */ stream, /** @type {Buffer | string} */ chunk) {
+      const lines = ((partial.get(stream) ?? "") + chunk.toString()).split("\n");
+      partial.set(stream, lines.pop() ?? "");
+      lines.forEach(add);
+    },
+    /** The cleaned end of the output, cut on a line boundary. */
+    text() {
+      for (const rest of partial.values()) {
+        if (rest.length > 0) {
+          add(rest);
+        }
+      }
+      partial.clear();
+      const cut = kept.length > maxChars ? kept.slice(kept.length - maxChars) : kept;
+      return (kept.length > maxChars ? cut.slice(cut.indexOf("\n") + 1) : cut).trim();
+    },
+  };
+}

package/messages/conventional.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { emitMessage, MESSAGE_FLAGS, ownArgv, take, writeDiagnostic } from "@bluewombat/slot-kit";
 
-// The feature's commit in the Conventional Commits shape, from the issue's
+// The ticket's commit in the Conventional Commits shape, from the issue's
 // title and body and with no agent: `<type>: <title>`, the body as written.
 //
 // The type is read off the title's first word — a Project that wants a

package/messages/git-producer.mjs

@@ -16,9 +16,9 @@ import {
   writeDiagnostic,
 } from "@bluewombat/slot-kit";
 
-// The feature's commit message — and the pull request's description with it
+// The ticket's commit message — and the pull request's description with it
 // — written by an agent that read the diff, under the Project's own rules.
-// Asked once per feature. A role slot like the builders: it fills a template
+// Asked once per ticket. A role slot like the builders: it fills a template
 // and hands it to the agent after `--`; the agent answers in a file this slot
 // reads back. `--prompt-file` replaces the template, `--rules-file` the rules
 // — that is where a team's commit guideline goes.

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
-  "description": "Shipped mason slots: Planners, Builders, Gates, publishers, and refreshers a Project names in its config.",
+  "description": "Shipped mason slots: Builders, Gates, publishers, and refreshers a Project names in its config.",
   "keywords": [
     "mason",
     "bluewombat",
     "gate",
-    "builder",
-    "planner"
+    "builder"
   ],
   "license": "MIT",
   "homepage": "https://github.com/tilap/bluewombat/tree/main/packages/plugins/slots#readme",
@@ -19,9 +18,9 @@
     "directory": "packages/plugins/slots"
   },
   "exports": {
-    "./planners/*": "./planners/*",
     "./builders/*": "./builders/*",
-    "./assembly/*": "./assembly/*",
+    "./ticket/*": "./ticket/*",
+    "./feature/*": "./feature/*",
     "./agents/*": "./agents/*",
     "./gates/*": "./gates/*",
     "./publishers/*": "./publishers/*",
@@ -29,9 +28,9 @@
     "./messages/*": "./messages/*"
   },
   "files": [
-    "planners",
     "builders",
-    "assembly",
+    "ticket",
+    "feature",
     "agents",
     "lib",
     "gates",
@@ -53,7 +52,7 @@
     "test": "tsx --test $(find test -name '*.test.ts')"
   },
   "dependencies": {
-    "@bluewombat/slot-kit": "^0.8.0",
-    "@pinkpuma/deck": "1.0.0"
+    "@bluewombat/slot-kit": "^0.10.0",
+    "@pinkpuma/deck": "1.1.0"
   }
 }

package/publishers/git.mjs

@@ -11,7 +11,7 @@ import {
   writeDiagnostic,
 } from "@bluewombat/slot-kit";
 
-// Put the feature's work where the Authority can read it, by pushing the name
+// Put the ticket'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

package/refreshers/git.mjs

@@ -16,10 +16,19 @@ import {
 // would make the next Isolation start from a version that no longer exists, so
 // this runs before anything else in a pass.
 //
+// The copy moves onto the target line first: a Feature's Tickets are cut from
+// and folded into that Feature's line, not the final branch.
+//
 // 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.
 //
+// A Feature's line cut from the final branch that has no commit of its own is
+// only a stale copy of it: when `--base` names that branch and the line is an
+// ancestor of it, the line is fast-forwarded to it, here and on the remote, so
+// a Ticket starts from the code as it now is. A line with commits of its own
+// is left alone.
+//
 // The remote is `origin`, like the git Publisher's. Takes no option.
 
 const cwd = process.cwd();
@@ -41,7 +50,8 @@ if (!existsSync(join(cwd, ".git"))) {
   process.exit(0);
 }
 
-const fetched = git(["fetch", "origin", target]);
+// An explicit refspec: a single-branch clone only knows its own branch.
+const fetched = git(["fetch", "origin", `+refs/heads/${target}:refs/remotes/origin/${target}`]);
 if (fetched.status !== 0) {
   emitRefreshRefusal(
     `Cannot fetch origin/${target} from ${cwd}: ${fetched.stderr.trim().slice(-500)}`,
@@ -49,7 +59,47 @@ if (fetched.status !== 0) {
   process.exit(0);
 }
 
-const merged = git(["merge", "--ff-only", `origin/${target}`]);
+const base = take(process.argv, "--base");
+let goal = `origin/${target}`;
+if (base !== undefined && base.trim().length > 0 && base !== target) {
+  const fetchedBase = git(["fetch", "origin", `+refs/heads/${base}:refs/remotes/origin/${base}`]);
+  if (fetchedBase.status !== 0) {
+    emitRefreshRefusal(
+      `Cannot fetch origin/${base} from ${cwd}: ${fetchedBase.stderr.trim().slice(-500)}`,
+    );
+    process.exit(0);
+  }
+  const behindBase =
+    git(["merge-base", "--is-ancestor", `origin/${target}`, `origin/${base}`]).status === 0;
+  if (
+    behindBase &&
+    git(["rev-parse", `origin/${target}`]).stdout !== git(["rev-parse", `origin/${base}`]).stdout
+  ) {
+    // A plain push: never forced, so it only ever adds history.
+    const pushed = git(["push", "origin", `refs/remotes/origin/${base}:refs/heads/${target}`]);
+    if (pushed.status !== 0) {
+      emitRefreshRefusal(
+        `Cannot move origin/${target} up to origin/${base}: ${pushed.stderr.trim().slice(-500)}`,
+      );
+      process.exit(0);
+    }
+    goal = `origin/${base}`;
+  }
+}
+
+const current = git(["symbolic-ref", "--short", "HEAD"]);
+if (current.status !== 0 || current.stdout.trim() !== target) {
+  const exists = git(["rev-parse", "--verify", "--quiet", `refs/heads/${target}`]).status === 0;
+  const switched = git(
+    exists ? ["checkout", target] : ["checkout", "-b", target, `origin/${target}`],
+  );
+  if (switched.status !== 0) {
+    emitRefreshRefusal(`Cannot move ${cwd} onto ${target}: ${switched.stderr.trim().slice(-500)}`);
+    process.exit(0);
+  }
+}
+
+const merged = git(["merge", "--ff-only", goal]);
 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:

package/{assembly → ticket}/fix.mjs

@@ -15,13 +15,13 @@ import {
 } from "@bluewombat/slot-kit";
 import { attemptOf } from "../lib/fill.mjs";
 
-const NAME = "assembly fix";
+const NAME = "ticket fix";
 
 const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
 
-This directory is the assembled feature. The units of work that made it have
-already been validated. An earlier judgement of the whole refused it. Do not
-redo those units. Fix what the refusal names.
+This directory is the assembled work. It passed the checks made on the unit
+itself. An earlier judgement of the whole refused it. Do not redo the work.
+Fix what the refusal names.
 
 Refused by: {{refused_by}}
 
@@ -60,7 +60,7 @@ A person reads that line and decides. It is a correct answer, not a failure.
 
 const report = (take(process.argv, "--report") ?? "").trim();
 if (report.length === 0) {
-  emitFailure("fail-blocking", "The assembly fix command needs --report.");
+  emitFailure("fail-blocking", "The ticket fix command needs --report.");
   process.exit(1);
 }
 

package/{assembly → ticket}/validate.mjs

@@ -15,15 +15,15 @@ import {
 } from "@bluewombat/slot-kit";
 import { attemptOf } from "../lib/fill.mjs";
 
-const NAME = "assembly validate";
+const NAME = "ticket 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.
+This directory is the assembled work. It has already passed the checks made on
+the unit itself. Your job now is different: read the diff it carries against
+the work line it will land on, and judge whether the WHOLE meets what was
+asked. Do not redo the work. Do not change anything — this is a
+read-only review, not a repair.
 
 ## What was asked
 
@@ -34,7 +34,7 @@ anything — this is a read-only review, not a repair.
 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: VALIDATED\` — the assembled ticket 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.
@@ -67,7 +67,7 @@ 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.",
+    "ticket.validate is a read-only review; it does not take --report — that is ticket.fix's job.",
   );
   process.exit(1);
 }
@@ -149,7 +149,7 @@ function answer(run, bin, name) {
     // next round gets the same prompt again.
     emitFailure(
       "fail-retryable",
-      `assembly.validate found no MASON_VERDICT: line in the answer: ${
+      `ticket.validate found no MASON_VERDICT: line in the answer: ${
         said.length > 0 ? said.slice(0, 500) : "(no answer)"
       }`,
     );
@@ -160,9 +160,7 @@ function answer(run, bin, name) {
     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.",
+      why.length > 0 ? why : "ticket.validate refused the assembled ticket, with no reason given.",
     );
     process.exit(1);
   }
@@ -171,7 +169,7 @@ function answer(run, bin, name) {
   }
   emitFailure(
     "fail-retryable",
-    `assembly.validate's MASON_VERDICT: line was neither VALIDATED nor REFUSED: ${verdict.slice(0, 500)}`,
+    `ticket.validate's MASON_VERDICT: line was neither VALIDATED nor REFUSED: ${verdict.slice(0, 500)}`,
   );
   process.exit(1);
 }

package/planners/one-subtask.mjs

@@ -1,21 +0,0 @@
-#!/usr/bin/env node
-/**
- * Bootstrap Planner: one Subtask that is the FeatureStandard itself.
- * FeatureBreakdown appends --intention, --key, --max-units.
- */
-import { emitPlan, emitRefusal, take } from "@bluewombat/slot-kit";
-
-const intention = (take(process.argv, "--intention") ?? "").trim();
-if (intention.length === 0) {
-  emitRefusal("The FeatureStandard has no intention to turn into a Subtask.");
-  process.exit(0);
-}
-
-emitPlan([
-  {
-    id: "A",
-    intention,
-    definition_of_done: "The intention is realized in the workspace.",
-    depends_on: [],
-  },
-]);

package/planners/producer.mjs

@@ -1,233 +0,0 @@
-#!/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,
-  writeDiagnostic,
-} 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. 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",
-  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.
-  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.
-
-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) {
-  writeDiagnostic(`${reason}\n`);
-  process.exit(1);
-}