heyspex 0.1.0 → 0.2.0

package/dev-factory/lib/code-repo-root.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * lib/code-repo-root.mjs — resolves the CODE repo root (workflow-protocol), not the vault.
+ *
+ * Repo-split context (2026-08-31, [[repo-split-step16-specs-path-inventory-2026-08-31]]):
+ * the spec vault (specs/ + heyspex.yaml) moved out of this repo to a sibling checkout
+ * (C:\dev-projects\heyspex-specs). A family of dev-factory/lib modules used to find "the repo
+ * root" by walking UP from their own directory looking for heyspex.yaml — that marker is gone
+ * from this repo now, so that walk silently fell back to process.cwd(), fragmenting
+ * .heyspex/ state files (fleet-state.json, queues, progress, join-codes, etc.) into whatever
+ * directory the process happened to start in.
+ *
+ * KEY POINT: those modules manage CODE-REPO state, not vault state — the fix is NOT to chase
+ * the vault registry, it's to anchor on the code repo itself. The code repo is reliably
+ * identifiable (it contains dev-factory/ and package.json with name "heyspex"), and every
+ * caller of this helper lives inside it — so there is nothing to walk or discover: the repo
+ * root is simply two directories up from THIS file (dev-factory/lib/code-repo-root.mjs ->
+ * dev-factory -> repo root), resolved via import.meta.url rather than process.cwd().
+ *
+ *   node dev-factory/lib/code-repo-root.mjs        # prints the resolved root
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Returns the absolute path to the code repo root (the workflow-protocol checkout this file
+ * lives in). No walking, no markers — this file's own location fixes the answer. Throws loudly
+ * if the sanity check fails (would only happen if this file were copied/moved somewhere else).
+ */
+export function codeRepoRoot() {
+  const root = resolve(__dirname, "..", "..");
+
+  if (!existsSync(join(root, "dev-factory"))) {
+    throw new Error(
+      `code-repo-root: sanity check failed — no dev-factory/ found under "${root}". ` +
+        `codeRepoRoot() assumes this file stays at dev-factory/lib/code-repo-root.mjs.`,
+    );
+  }
+
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (pkg?.name && pkg.name !== "heyspex") {
+        throw new Error(
+          `code-repo-root: sanity check failed — "${root}"/package.json name is "${pkg.name}", expected "heyspex".`,
+        );
+      }
+    } catch (e) {
+      if (e instanceof SyntaxError) {
+        throw new Error(`code-repo-root: sanity check failed — could not parse "${pkgPath}": ${e.message}`);
+      }
+      throw e;
+    }
+  }
+
+  return root;
+}
+
+// ── CLI: print the resolved root ────────────────────────────────────────────────────────────
+if (import.meta.url.endsWith("/" + (process.argv[1]?.split(/[\\/]/).pop() ?? ""))) {
+  console.log(codeRepoRoot());
+}

package/dev-factory/lib/context-budget.mjs

@@ -0,0 +1,84 @@
+/**
+ * lib/context-budget.mjs — THE prompt-token budget formula, in one place.
+ *
+ * HS-6NFD defect 3: `builder.mjs`'s prompt assembler and `lib/pick-num-ctx.mjs`'s bucket
+ * picker each computed "does this fit?" with DIFFERENT arithmetic, and the picker's was the
+ * looser one:
+ *
+ *   picker:    estimatedTokens + maxOutputTokens <= numCtx          → "fits"
+ *   assembler: estimatedTokens <= floor(numCtx * 0.8) - maxOutputTokens → "fits"
+ *
+ * So the picker under-reserved by `0.2 * numCtx` on EVERY call. On HS-CHWJ (est 12000,
+ * recommended bucket 16384, output 4096) the picker said 16096 <= 16384 → fits, the
+ * assembler said 9011 < 12000 → drop every reference file, and the builder hallucinated a
+ * duplicate type because it never saw the enum it was extending.
+ *
+ * Both sides now import from here. The headroom exists because the estimate is a
+ * chars/4 approximation over the spec JSON + targets + reference files only — it does not
+ * count the system prompt, the instruction scaffolding, the chat template, or tokenizer
+ * variance, so the window must never be planned to the brim.
+ */
+
+/** Fraction of the context window the PROMPT may plan to occupy (the rest absorbs the
+ *  system prompt, scaffolding, chat template, and chars/4 estimation error). */
+export const PROMPT_WINDOW_FRACTION = 0.8;
+
+/** Chars-per-token used by every prompt-size estimate in the factory. */
+export const CHARS_PER_TOKEN = 4;
+
+/** Token budget available to PROMPT content at a given window + output reservation.
+ *  This is the authoritative definition — `builder.mjs` drops reference files until the
+ *  estimate fits under it. May go <= 0 for a tiny window with a large output reservation;
+ *  callers treat that as "nothing fits, size up". */
+export function promptBudgetTokens(numCtx, maxOutputTokens) {
+  return Math.floor(Number(numCtx) * PROMPT_WINDOW_FRACTION) - Number(maxOutputTokens);
+}
+
+/** Smallest context window whose {@link promptBudgetTokens} holds `promptTokens`.
+ *  The exact inverse of the above: `promptBudgetTokens(numCtxNeededFor(p, o), o) >= p`
+ *  holds for all non-negative integers p, o (pinned in the self-test). */
+export function numCtxNeededFor(promptTokens, maxOutputTokens) {
+  return Math.ceil((Number(promptTokens) + Number(maxOutputTokens)) / PROMPT_WINDOW_FRACTION);
+}
+
+/** Does `promptTokens` fit the prompt budget at this window? */
+export function promptFitsNumCtx(promptTokens, numCtx, maxOutputTokens) {
+  return Number(promptTokens) <= promptBudgetTokens(numCtx, maxOutputTokens);
+}
+
+/** Estimate tokens for a raw string (the chars/4 convention used repo-wide). */
+export function estimateTokens(text) {
+  return Math.ceil(String(text ?? "").length / CHARS_PER_TOKEN);
+}
+
+// ── self-test ────────────────────────────────────────────────────────────────
+if (process.argv.includes("--self-test")
+  && import.meta.url.endsWith("/" + (process.argv[1]?.split(/[\\/]/).pop() ?? ""))) {
+  let ok = true;
+  const check = (name, cond) => { console.log(`  ${cond ? "✓" : "✗"} ${name}`); if (!cond) ok = false; };
+  console.log("== lib/context-budget.mjs self-test ==\n");
+
+  check("promptBudgetTokens matches builder.mjs's historical formula (16384/4096 → 9011)",
+    promptBudgetTokens(16384, 4096) === 9011);
+
+  // THE HS-CHWJ regression: the picker used to accept 16384 for a 12000-token prompt.
+  check("HS-6NFD regression: 12000 prompt tokens do NOT fit 16384 with a 4096 output reserve",
+    promptFitsNumCtx(12000, 16384, 4096) === false);
+  check("HS-6NFD regression: the window that DOES hold 12000 + 4096 is 20120",
+    numCtxNeededFor(12000, 4096) === 20120);
+
+  // The inverse must hold everywhere, not just on the one motivating case — this is what
+  // stops the picker from ever again handing the assembler a window it will overflow.
+  let inverseHolds = true;
+  for (const p of [0, 1, 999, 9011, 12000, 65536, 250000]) {
+    for (const o of [0, 4096, 16384]) {
+      if (!promptFitsNumCtx(p, numCtxNeededFor(p, o), o)) { inverseHolds = false; console.log(`    ✗ p=${p} o=${o}`); }
+    }
+  }
+  check("numCtxNeededFor is a true inverse of promptBudgetTokens across the range", inverseHolds);
+
+  check("estimateTokens uses chars/4, rounding up", estimateTokens("abcde") === 2 && estimateTokens("") === 0);
+
+  console.log(`\n${ok ? "✓ self-test PASS" : "✗ self-test FAIL"}`);
+  process.exit(ok ? 0 : 1);
+}

package/dev-factory/lib/epic-detect.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * epic-detect.mjs — the ONE source of truth for "is this spec an epic / a
+ * parent-shaped spec / dispatchable as a single target?" (2026-07-11 consolidation).
+ *
+ * Before this module, the same predicate lived in THREE places with subtly different
+ * regexes — and one of them (the old `/-EPIC-/` in hs-auto-resolve.mjs) missed ids
+ * ENDING in `-EPIC`, which is exactly how the idle-fleet incident's epic slipped
+ * toward a single-target dispatch. Consolidating removes the drift risk.
+ *
+ * Callers pass a spec's raw text (+ optional path/id) to `specFacts`, then compose
+ * the decision they need from the pure predicates:
+ *   - isEpicSpec        — type: epic, id containing OR ending in `-EPIC`, or a file
+ *                         under specs/epics/.
+ *   - isMilestoneSpec   — type: milestone or a `-MIL` id.
+ *   - isParentShaped    — declares `children:` but the list is EMPTY and it has no
+ *                         `target:` of its own (nothing single-target about it).
+ *   - isDispatchableSingleTarget — none of the above (the controller's build loop
+ *                         and the dispatch gate use this).
+ *
+ * `frontmatterChildIds` is the shared child-id extractor (block-form `children:` +
+ * `[[wikilink]]` items) so the childless-epic routing in engine/breakdown.mjs reads
+ * children the same way everywhere.
+ *
+ * Pure string logic, no network, no fs. `--self-test` covers every predicate + the
+ * exact -EPIC-suffix regression that motivated the module.
+ */
+
+import { pathToFileURL } from "node:url";
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/** Extract the frontmatter block from raw spec text (empty string when absent). */
+export function extractFrontmatter(raw) {
+  return String(raw ?? "").match(FRONTMATTER)?.[1] ?? "";
+}
+
+function fmScalar(fm, key) {
+  const m = fm.match(new RegExp(`^${key}:[ \\t]*(.+)$`, "m"));
+  return m ? m[1].trim().replace(/^['"]|['"]$/g, "") : null;
+}
+
+/**
+ * Count entries of a frontmatter list key (`key: []`, `key:` + `- item` block, or
+ * inline `key: [a, b]`). Returns null when the key is absent entirely (so a caller
+ * can distinguish "no children: key" from "children: []").
+ */
+export function fmListCount(fm, key) {
+  const scalar = fm.match(new RegExp(`^${key}:[ \\t]*(.*)$`, "m"));
+  if (!scalar) return null; // key absent entirely
+  const inline = scalar[1].trim();
+  if (inline === "[]" || inline === "") {
+    const block = fm.match(new RegExp(`^${key}:[ \\t]*\\r?\\n((?:[ \\t]+-[ \\t]+.+\\r?\\n?)*)`, "m"));
+    if (!block || !block[1]) return 0;
+    return block[1].split(/\r?\n/).filter((l) => /^\s*-\s+\S/.test(l)).length;
+  }
+  if (inline.startsWith("[") && inline.endsWith("]")) {
+    const body = inline.slice(1, -1).trim();
+    return body ? body.split(",").filter((s) => s.trim()).length : 0;
+  }
+  return 1; // scalar value — treat as one entry
+}
+
+/**
+ * Extract the `[[wikilink]]` child basenames from a block-form `children:` key.
+ * Accepts either raw spec text (with `---` fences) or a bare frontmatter string.
+ * Matches engine/breakdown.mjs's original children reader exactly, so
+ * childless-epic routing has one implementation.
+ * @param {string} fmOrRaw
+ * @returns {string[]} child basenames (the inner text of each `[[…]]`)
+ */
+export function frontmatterChildIds(fmOrRaw) {
+  const fm = /^---\r?\n/.test(String(fmOrRaw ?? "")) ? extractFrontmatter(fmOrRaw) : String(fmOrRaw ?? "");
+  const re = /^children:[ \t]*\r?\n([\s\S]*?)(?=^[A-Za-z_]|(?![\s\S]))/m;
+  const m = fm.match(re);
+  if (!m) return [];
+  return [...m[1].matchAll(/\[\[([^\]]+)\]\]/g)].map((x) => x[1]);
+}
+
+/**
+ * Normalize a spec into the facts the predicates read. Pass raw text; optionally a
+ * resolved path (enables the specs/epics/ check) and a fallback id.
+ * @param {{ raw?: string, specPath?: string, specId?: string|null }} input
+ * @returns {{ id: string, type: string, path: string, hasChildrenKey: boolean, childCount: number, target: string|null }}
+ */
+export function specFacts({ raw = "", specPath = "", specId = null } = {}) {
+  const fm = extractFrontmatter(raw);
+  const id = fmScalar(fm, "id") ?? specId ?? "";
+  const type = (fmScalar(fm, "type") ?? "").toLowerCase();
+  const path = String(specPath).replace(/\\/g, "/");
+  const rawCount = fmListCount(fm, "children");
+  const target = fmScalar(fm, "target");
+  return {
+    id,
+    type,
+    path,
+    hasChildrenKey: rawCount !== null,
+    childCount: rawCount ?? 0,
+    target,
+  };
+}
+
+/** type: epic · id containing OR ending in `-EPIC` · a file under specs/epics/. */
+export function isEpicSpec(facts) {
+  const f = facts ?? {};
+  return (
+    f.type === "epic" ||
+    /-EPIC(?:-|$)/i.test(f.id ?? "") ||
+    /(^|\/)specs\/epics\//i.test(f.path ?? "")
+  );
+}
+
+/** type: milestone · a `-MIL` id. */
+export function isMilestoneSpec(facts) {
+  const f = facts ?? {};
+  return f.type === "milestone" || /-MIL(?:-|$)/i.test(f.id ?? "");
+}
+
+/** Declares `children:` but the list is EMPTY and it has no `target:` of its own. */
+export function isParentShaped(facts) {
+  const f = facts ?? {};
+  return Boolean(f.hasChildrenKey) && (f.childCount ?? 0) === 0 && !f.target;
+}
+
+/** None of epic / milestone / parent-shaped — safe for the single-target build loop. */
+export function isDispatchableSingleTarget(facts) {
+  return !isEpicSpec(facts) && !isMilestoneSpec(facts) && !isParentShaped(facts);
+}
+
+// ── Self-test (pure) ─────────────────────────────────────────────────────────────
+function runSelfTest() {
+  let ok = true;
+  const check = (name, cond) => { console.log(`  ${cond ? "✓" : "✗"} ${name}`); if (!cond) ok = false; };
+  console.log("== lib/epic-detect.mjs self-test ==\n");
+
+  const f = (raw, specPath = "", specId = null) => specFacts({ raw, specPath, specId });
+
+  const epicByType = f(`---\nid: HS-AAAA-EPIC\ntype: epic\nchildren: []\n---\n`);
+  const epicSuffix = f(`---\nid: HS-REM-EPIC\nstatus: open\n---\n`); // the regression: ends in -EPIC
+  const epicMid = f(`---\nid: HS-EPIC-legacy-1234\ntype: epic\n---\n`);
+  const epicByPath = f(`# bare\n`, "specs/epics/HS-Z.md");
+  const epicWithTarget = f(`---\nid: HS-BBBB-EPIC\ntype: epic\ntarget: a.ts\nchildren: []\n---\n`);
+  const milestone = f(`---\nid: HS-GGGG-MIL\ntype: milestone\n---\n`);
+  const parentShaped = f(`---\nid: HS-CCCC-TASK\ntype: task\nchildren: []\n---\n`);
+  const goodTask = f(`---\nid: HS-DDDD-TASK\ntype: task\ntarget: a.ts\n---\n`);
+  const taskWithChildrenAndTarget = f(`---\nid: HS-EEEE-TASK\ntype: task\ntarget: a.ts\nchildren:\n  - "[[HS-FFFF-TASK-x]]"\n---\n`);
+  const bare = f(`# nothing\n`);
+
+  check("isEpicSpec: type: epic", isEpicSpec(epicByType));
+  check("isEpicSpec: id ENDING in -EPIC (the /-EPIC-/ regression)", isEpicSpec(epicSuffix));
+  check("isEpicSpec: id CONTAINING -EPIC-", isEpicSpec(epicMid));
+  check("isEpicSpec: file under specs/epics/", isEpicSpec(epicByPath));
+  check("isEpicSpec: epic even when it carries a target:", isEpicSpec(epicWithTarget));
+  check("isEpicSpec: a plain task is NOT an epic", !isEpicSpec(goodTask));
+
+  check("isMilestoneSpec: -MIL id", isMilestoneSpec(milestone));
+  check("isMilestoneSpec: a task is not a milestone", !isMilestoneSpec(goodTask));
+
+  check("isParentShaped: children: [] and no target:", isParentShaped(parentShaped));
+  check("isParentShaped: NOT triggered by a task with a target: and no children key", !isParentShaped(goodTask));
+  check("isParentShaped: NOT triggered by non-empty children (real children present)", !isParentShaped(taskWithChildrenAndTarget));
+  check("isParentShaped: NOT triggered when children: [] BUT a target: exists", !isParentShaped(epicWithTarget) || isEpicSpec(epicWithTarget));
+
+  check("isDispatchableSingleTarget: plain task with target passes", isDispatchableSingleTarget(goodTask));
+  check("isDispatchableSingleTarget: task with children + target passes", isDispatchableSingleTarget(taskWithChildrenAndTarget));
+  check("isDispatchableSingleTarget: epic refused", !isDispatchableSingleTarget(epicByType));
+  check("isDispatchableSingleTarget: milestone refused", !isDispatchableSingleTarget(milestone));
+  check("isDispatchableSingleTarget: parent-shaped refused", !isDispatchableSingleTarget(parentShaped));
+  check("isDispatchableSingleTarget: frontmatter-less fixture passes", isDispatchableSingleTarget(bare));
+
+  check("hasChildrenKey: absent children key → false", bare.hasChildrenKey === false);
+  check("hasChildrenKey: children: [] → true, count 0", parentShaped.hasChildrenKey === true && parentShaped.childCount === 0);
+
+  check("frontmatterChildIds: block wikilinks extracted", (() => {
+    const ids = frontmatterChildIds(`---\nid: HS-X-EPIC\nchildren:\n  - "[[HS-A-TASK-a]]"\n  - "[[HS-B-TASK-b]]"\n---\n`);
+    return ids.length === 2 && ids[0] === "HS-A-TASK-a" && ids[1] === "HS-B-TASK-b";
+  })());
+  check("frontmatterChildIds: children: [] → empty array", frontmatterChildIds(`---\nid: HS-X-EPIC\nchildren: []\n---\n`).length === 0);
+  check("frontmatterChildIds: accepts a bare frontmatter string too", (() => {
+    const ids = frontmatterChildIds(`id: HS-X-EPIC\nchildren:\n  - [[HS-A-TASK-a]]\n`);
+    return ids.length === 1 && ids[0] === "HS-A-TASK-a";
+  })());
+
+  console.log(`\n${ok ? "✓ self-test PASS" : "✗ self-test FAIL"}`);
+  return ok ? 0 : 1;
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  if (process.argv.includes("--self-test")) process.exit(runSelfTest());
+}