b2c-app-builder 0.221.39

package/tooling/calibrate-utterance-router.ts

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * Calibrates ROUTE_CONFIDENCE_THRESHOLD / AMBIGUITY_BAND for the utterance router (U9; issue #26
+ * AC "Top-1 accuracy measured ... before release"; plan R5, KTD5, KTD11).
+ *
+ * WHY a standalone tool instead of hand-picking numbers: KTD5 deliberately left the threshold and
+ * band provisional ("U9 owns calibrating this against real founder utterances") rather than guessed
+ * once and frozen. This tool makes that calibration a repeatable, deterministic measurement instead
+ * of a one-time judgment call — re-run it after the corpus grows and it reproduces the same answer
+ * from the same inputs (no `Date.now`, no randomness anywhere in this file).
+ *
+ * WHAT it grid-searches: every (threshold, band) pair on threshold ∈ [1.0, 3.0] step 0.1 and
+ * band ∈ [0.0, 1.0] step 0.1 (231 pairs), scored against `verification/goldens/routing/
+ * utterance-calibration.json` — never the frozen `utterance-regression.json`, which exists only to
+ * grade whatever this tool recommends, not to help pick it (see that corpus's own metadata note).
+ *
+ * WHY it does not simply call `matchWorkflows`: that function reads `ROUTE_CONFIDENCE_THRESHOLD`/
+ * `AMBIGUITY_BAND` as module-level constants, not parameters — correct for production (the values
+ * are fixed once calibrated) but unusable for a sweep that needs to try 231 different values. This
+ * tool instead reuses the exact same scoring pipeline `matchWorkflows` calls (`terms` from
+ * `kernel/knowledge-service/service.ts`, then `route-scoring.ts`'s `routerQueryTerms`/`queryBigrams`/
+ * `routerMatchRank`/`combineTriggerWithFounderPhrasings` — issue #58's router-owned stopword/
+ * stemming/bigram generalizations (stage 1) plus authored founderPhrasings scored at trigger weight
+ * (stage 3) — feeding the same formula `route-utterance.ts` documents: matchedTermCount + boost/10,
+ * plus stage 2's lower-weight instructions addend) and re-implements
+ * only the small threshold/tie DECISION step with threshold and band as loop variables — see
+ * `decide()` below, which is a direct line-for-line mirror of `matchWorkflows`'s decision rule and
+ * must be kept that way if that rule ever changes.
+ *
+ * HOW a pair is scored: primary-subset top-1 accuracy (does the entry resolve to a primary AND does
+ * that primary's workflowId match the expected one), subject to a hard constraint — zero
+ * false-primaries across every candidates/insufficient_signal-labelled calibration entry (a
+ * calibration corpus has no product_mismatch entries: that outcome short-circuits on `cwd` before
+ * scoring and is therefore independent of threshold/band by construction — see
+ * `routeUtterance`'s decision order). A pair that produces even one false primary is infeasible
+ * regardless of its accuracy on the primary subset; among feasible pairs the highest accuracy wins;
+ * ties are broken deterministically (closest to the previously-recorded default, then lowest
+ * threshold, then lowest band) so re-running this tool never produces a different answer.
+ *
+ * Usage:
+ *   npm run routing:calibrate              print the grid summary and the recommended pair
+ *   npm run routing:calibrate -- --check   exit 1 unless the LIVE constants in route-utterance.ts
+ *                                          are feasible and on the accuracy-maximizing Pareto front
+ *                                          (or equal to the corpus's own recorded chosenThreshold/
+ *                                          chosenBand) — the PR gate for "did someone change the
+ *                                          constants without re-running calibration".
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { terms } from "../kernel/knowledge-service/service.js";
+import {
+  combineTriggerWithFounderPhrasings,
+  INSTRUCTIONS_MATCH_WEIGHT,
+  instructionsOnlyMatchedCount,
+  queryBigrams,
+  routerMatchRank,
+  routerQueryTerms,
+} from "../kernel/session/route-scoring.js";
+import { AMBIGUITY_BAND, ROUTE_CONFIDENCE_THRESHOLD } from "../kernel/session/route-utterance.js";
+import type { HostedKnowledgeBundle } from "../kernel/knowledge-service/types.js";
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// --- grid definition (KTD11: fixed, documented, reproducible) ------------------------------------
+
+const THRESHOLD_MIN = 1.0;
+const THRESHOLD_MAX = 3.0;
+const THRESHOLD_STEP = 0.1;
+const BAND_MIN = 0.0;
+const BAND_MAX = 1.0;
+const BAND_STEP = 0.1;
+
+// The default pair this tool's recommendation is compared against for tie-breaking and for the
+// recorded-choice equality check in --check. Kept in sync with route-utterance.ts by convention,
+// not by import, because importing it here would make a --check run against a MODIFIED constant
+// silently grade itself against its own new value; --check reads the live constants separately
+// (see main()) precisely so a drifted constant is caught rather than laundered through this default.
+const RECORDED_DEFAULT = { threshold: 1.7, band: 0.2 };
+
+// round to one decimal place to keep grid values exact under repeated 0.1 addition (floating point).
+function gridValues(min: number, max: number, step: number): number[] {
+  const count = Math.round((max - min) / step);
+  return Array.from({ length: count + 1 }, (_, index) => Math.round((min + index * step) * 10) / 10);
+}
+
+const THRESHOLDS = gridValues(THRESHOLD_MIN, THRESHOLD_MAX, THRESHOLD_STEP);
+const BANDS = gridValues(BAND_MIN, BAND_MAX, BAND_STEP);
+
+// --- corpus + catalog loading ----------------------------------------------------------------------
+
+interface ExpectedOutcome {
+  readonly kind: "primary" | "candidates" | "insufficient_signal" | "product_mismatch";
+  readonly workflowId?: string;
+}
+
+interface CorpusEntry {
+  readonly id: string;
+  readonly utterance: string;
+  readonly expected: ExpectedOutcome;
+  readonly note?: string;
+}
+
+interface Corpus {
+  readonly metadata: Record<string, unknown>;
+  readonly entries: readonly CorpusEntry[];
+}
+
+export function loadCorpus(filePath: string): Corpus {
+  return JSON.parse(readFileSync(filePath, "utf8")) as Corpus;
+}
+
+interface RoutableWorkflow {
+  readonly workflowId: string;
+  readonly title: string;
+  readonly trigger: string;
+  readonly instructions: string;
+  /** Issue #58 stage 3: authored founder-voiced trigger alternates, scored at trigger weight. */
+  readonly founderPhrasings: readonly string[];
+}
+
+export function loadCatalogWorkflows(root: string = skillRoot): readonly RoutableWorkflow[] {
+  const bundlePath = path.join(root, "catalog/generated/hosted-knowledge.json");
+  const bundle = JSON.parse(readFileSync(bundlePath, "utf8")) as HostedKnowledgeBundle;
+  return bundle.catalog.workflows.map((workflow) => ({
+    workflowId: workflow.id,
+    title: workflow.title,
+    trigger: workflow.trigger,
+    instructions: workflow.instructions,
+    founderPhrasings: workflow.founderPhrasings,
+  }));
+}
+
+// --- scoring (mirrors matchWorkflows's per-workflow score exactly; see route-utterance.ts) -------
+
+interface ScoredEntry {
+  readonly workflowId: string;
+  readonly matchConfidence: number;
+}
+
+/** Pre-scored, sorted candidates for one utterance — computed once, reused across all 231 grid cells. */
+interface PreparedEntry {
+  readonly expected: ExpectedOutcome;
+  /** Empty exactly when `terms(utterance)` is empty — insufficient_signal regardless of threshold/band. */
+  readonly scored: readonly ScoredEntry[];
+}
+
+function prepareEntry(entry: CorpusEntry, workflows: readonly RoutableWorkflow[]): PreparedEntry {
+  const queryTerms = terms(entry.utterance);
+  if (queryTerms.length === 0 || workflows.length === 0) return { expected: entry.expected, scored: [] };
+  // Mirrors matchWorkflows's issue #58 pipeline exactly (route-scoring.ts's routerQueryTerms/
+  // queryBigrams/routerMatchRank/combineTriggerWithFounderPhrasings) — see this file's header
+  // comment on why this is a hand-kept mirror rather than a shared helper.
+  const routerTerms = routerQueryTerms(queryTerms);
+  const bigrams = queryBigrams(queryTerms);
+  const scored = workflows
+    .map((workflow) => {
+      const triggerText = combineTriggerWithFounderPhrasings(workflow.trigger, workflow.founderPhrasings);
+      const searchText = `${triggerText}\n${workflow.title}`.toLowerCase();
+      const rank = routerMatchRank(searchText, workflow.title, triggerText, routerTerms, bigrams);
+      const instructionsMatches = instructionsOnlyMatchedCount(workflow.instructions.toLowerCase(), searchText, routerTerms);
+      return { workflowId: workflow.workflowId, matchConfidence: rank.matchedTermCount + rank.boost / 10 + instructionsMatches * INSTRUCTIONS_MATCH_WEIGHT };
+    })
+    .sort((left, right) => right.matchConfidence - left.matchConfidence || left.workflowId.localeCompare(right.workflowId));
+  return { expected: entry.expected, scored };
+}
+
+type Decision = { readonly kind: "insufficient_signal" } | { readonly kind: "primary"; readonly workflowId: string } | { readonly kind: "candidates" };
+
+/**
+ * Line-for-line mirror of matchWorkflows's decision rule (route-utterance.ts), with threshold and
+ * band as parameters instead of module constants. Keep this in sync with that function by hand if
+ * its rule ever changes — there is deliberately no shared helper (see this file's header comment).
+ */
+function decide(prepared: PreparedEntry, threshold: number, band: number): Decision {
+  if (prepared.scored.length === 0) return { kind: "insufficient_signal" };
+  const top = prepared.scored[0]!;
+  const tiedWithTop = prepared.scored.filter((candidate) => top.matchConfidence - candidate.matchConfidence <= band);
+  const tied = tiedWithTop.length > 1;
+  if (top.matchConfidence >= threshold && !tied) return { kind: "primary", workflowId: top.workflowId };
+  return { kind: "candidates" };
+}
+
+// --- grid evaluation ---------------------------------------------------------------------------
+
+export interface GridCellResult {
+  readonly threshold: number;
+  readonly band: number;
+  readonly primaryTotal: number;
+  readonly primaryCorrect: number;
+  readonly falsePrimaries: number;
+  readonly accuracy: number;
+  readonly feasible: boolean;
+}
+
+export function evaluateGridCell(prepared: readonly PreparedEntry[], threshold: number, band: number): GridCellResult {
+  let primaryTotal = 0;
+  let primaryCorrect = 0;
+  let falsePrimaries = 0;
+  for (const entry of prepared) {
+    const decision = decide(entry, threshold, band);
+    if (entry.expected.kind === "primary") {
+      primaryTotal += 1;
+      if (decision.kind === "primary" && decision.workflowId === entry.expected.workflowId) primaryCorrect += 1;
+    } else if (entry.expected.kind === "candidates" || entry.expected.kind === "insufficient_signal") {
+      if (decision.kind === "primary") falsePrimaries += 1;
+    }
+    // product_mismatch entries are grid-independent by construction (see header comment) and are
+    // excluded from both the accuracy numerator/denominator and the false-primary count.
+  }
+  const accuracy = primaryTotal > 0 ? primaryCorrect / primaryTotal : 0;
+  return { threshold, band, primaryTotal, primaryCorrect, falsePrimaries, accuracy, feasible: falsePrimaries === 0 };
+}
+
+export function runGrid(corpus: Corpus, workflows: readonly RoutableWorkflow[]): GridCellResult[] {
+  const prepared = corpus.entries.map((entry) => prepareEntry(entry, workflows));
+  const results: GridCellResult[] = [];
+  for (const threshold of THRESHOLDS) {
+    for (const band of BANDS) {
+      results.push(evaluateGridCell(prepared, threshold, band));
+    }
+  }
+  return results;
+}
+
+const FLOAT_EPSILON = 1e-9;
+
+/** The accuracy-maximizing feasible pairs — "the Pareto front" per this tool's --check contract. */
+export function paretoFront(results: readonly GridCellResult[]): GridCellResult[] {
+  const feasible = results.filter((result) => result.feasible);
+  if (feasible.length === 0) return [];
+  const best = Math.max(...feasible.map((result) => result.accuracy));
+  return feasible.filter((result) => result.accuracy >= best - FLOAT_EPSILON);
+}
+
+/** Deterministic pick among tied-for-best pairs: closest to the recorded default, then lowest threshold, then lowest band. */
+export function recommend(results: readonly GridCellResult[]): GridCellResult | undefined {
+  const front = paretoFront(results);
+  if (front.length === 0) return undefined;
+  const distance = (result: GridCellResult) => (result.threshold - RECORDED_DEFAULT.threshold) ** 2 + (result.band - RECORDED_DEFAULT.band) ** 2;
+  return [...front].sort((left, right) => distance(left) - distance(right) || left.threshold - right.threshold || left.band - right.band)[0];
+}
+
+// --- reporting -----------------------------------------------------------------------------------
+
+function formatPct(value: number): string {
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function printSummary(results: readonly GridCellResult[], recommended: GridCellResult | undefined): void {
+  console.log(`Grid: ${THRESHOLDS.length} thresholds x ${BANDS.length} bands = ${results.length} pairs`);
+  const feasibleCount = results.filter((result) => result.feasible).length;
+  console.log(`Feasible pairs (zero false-primaries): ${feasibleCount}/${results.length}`);
+  console.log("");
+  console.log("threshold  band  accuracy  primaryCorrect/Total  falsePrimaries  feasible");
+  for (const result of results) {
+    const marker = recommended && result.threshold === recommended.threshold && result.band === recommended.band ? " <= recommended" : "";
+    console.log(
+      `${result.threshold.toFixed(1).padStart(9)}  ${result.band.toFixed(1).padStart(4)}  ${formatPct(result.accuracy).padStart(8)}  ${String(result.primaryCorrect).padStart(2)}/${result.primaryTotal}                 ${String(result.falsePrimaries).padStart(2)}              ${result.feasible ? "yes" : "no"}${marker}`,
+    );
+  }
+  console.log("");
+  if (recommended) {
+    console.log(
+      `Recommended: threshold=${recommended.threshold} band=${recommended.band} -> ${formatPct(recommended.accuracy)} primary accuracy (${recommended.primaryCorrect}/${recommended.primaryTotal}), 0 false-primaries.`,
+    );
+  } else {
+    console.log("No feasible pair found on this grid (every pair produced at least one false primary).");
+  }
+}
+
+// --- orthogonal held-out corpus: reported (and floor-gated) under --check, never used to calibrate.
+//
+// verification/goldens/routing/utterance-regression.json's `orthogonal` array is a purpose-first
+// corpus authored from each target workflow's instructions, not its trigger/title text (see that
+// file's own metadata, and the ORTHOGONAL CORPUS doc comment in
+// checks/verification/fixtures/routing-accuracy.fixtures.ts, for the full measurement record — a confirmed
+// systemic shortfall pre-issue-#58 (42.9%), CLEARED by issue #58 stage 3's authored founderPhrasings
+// (91.4%, 32/35)). Calibration is chosen on `utterance-calibration.json` alone, per this tool's own
+// header comment — this corpus is graded under whatever the calibration grid picked, never fed back
+// into `recommend()`/`paretoFront()`, so a maintainer cannot (even by accident) tune the
+// threshold/band against held-out data.
+const ORTHOGONAL_TOP1_ASPIRATIONAL_TARGET = 0.8;
+const ORTHOGONAL_TOP1_CURRENT_FLOOR = 0.85; // kept in sync with routing-accuracy.fixtures.ts's own floor (measured 32/35 = 91.4%)
+
+function loadOrthogonalCorpus(root: string = skillRoot): readonly CorpusEntry[] {
+  const regressionPath = path.join(root, "checks/verification/goldens/routing/utterance-regression.json");
+  const regression = loadCorpus(regressionPath) as Corpus & { orthogonal?: { entries: readonly CorpusEntry[] } };
+  if (!regression.orthogonal)
+    throw new Error("utterance-regression.json is missing its `orthogonal` corpus (see routing-accuracy.fixtures.ts's ORTHOGONAL CORPUS doc comment).");
+  return regression.orthogonal.entries;
+}
+
+/** Reports (and floor-gates) the orthogonal corpus's accuracy under the LIVE constants — a held-out grade, never a calibration input. */
+function checkOrthogonalHeldOut(workflows: readonly RoutableWorkflow[]): boolean {
+  const entries = loadOrthogonalCorpus();
+  const prepared = entries.map((entry) => prepareEntry(entry, workflows)).filter((p) => p.expected.kind === "primary");
+  let correct = 0;
+  for (const p of prepared) {
+    const decision = decide(p, ROUTE_CONFIDENCE_THRESHOLD, AMBIGUITY_BAND);
+    if (decision.kind === "primary" && decision.workflowId === p.expected.workflowId) correct += 1;
+  }
+  const accuracy = prepared.length > 0 ? correct / prepared.length : 0;
+  console.log(
+    `Orthogonal held-out corpus (purpose-first, never used to calibrate): ${formatPct(accuracy)} primary accuracy (${correct}/${prepared.length}) under the live constants — ${accuracy >= ORTHOGONAL_TOP1_ASPIRATIONAL_TARGET ? "meets" : "below"} the ${formatPct(ORTHOGONAL_TOP1_ASPIRATIONAL_TARGET)} aspirational target (issue #58 stage 3 cleared this bar on 2026-09-01 — see utterance-regression.json's orthogonal.metadata for the full stage 1/2/3 record).`,
+  );
+  if (accuracy < ORTHOGONAL_TOP1_CURRENT_FLOOR) {
+    console.error(
+      `ERROR routing_calibration.orthogonal_regression: orthogonal held-out accuracy ${formatPct(accuracy)} has dropped below its recorded floor of ${formatPct(ORTHOGONAL_TOP1_CURRENT_FLOOR)} (issue #58 stage 3 measured ${formatPct(0.9143)}, 32/35) — investigate; this means some change made real founder-language routing worse.`,
+    );
+    return false;
+  }
+  return true;
+}
+
+// --- --check: does the LIVE route-utterance.ts pair still hold up? -------------------------------
+
+function checkLiveConstants(results: readonly GridCellResult[]): boolean {
+  const front = paretoFront(results);
+  const live = results.find((result) => result.threshold === ROUTE_CONFIDENCE_THRESHOLD && result.band === AMBIGUITY_BAND);
+  if (!live) {
+    console.error(
+      `ERROR routing_calibration.constants_off_grid: route-utterance.ts has threshold=${ROUTE_CONFIDENCE_THRESHOLD} band=${AMBIGUITY_BAND}, which is not on this tool's grid (threshold step ${THRESHOLD_STEP} in [${THRESHOLD_MIN},${THRESHOLD_MAX}], band step ${BAND_STEP} in [${BAND_MIN},${BAND_MAX}]).`,
+    );
+    return false;
+  }
+  const onFront = front.some((result) => result.threshold === live.threshold && result.band === live.band);
+  const equalsRecorded = live.threshold === RECORDED_DEFAULT.threshold && live.band === RECORDED_DEFAULT.band;
+  if (!live.feasible) {
+    console.error(
+      `ERROR routing_calibration.constants_infeasible: threshold=${live.threshold} band=${live.band} produces ${live.falsePrimaries} false-primary(ies) on the calibration corpus. Re-run "npm run routing:calibrate" and update route-utterance.ts.`,
+    );
+    return false;
+  }
+  if (!onFront && !equalsRecorded) {
+    const best = front[0]!;
+    console.error(
+      `ERROR routing_calibration.constants_stale: threshold=${live.threshold} band=${live.band} scores ${formatPct(live.accuracy)} primary accuracy, but the calibration grid's best feasible accuracy is ${formatPct(best.accuracy)} (e.g. threshold=${best.threshold} band=${best.band}). Re-run "npm run routing:calibrate", update route-utterance.ts's constants and doc comments, and re-freeze utterance-regression.json's recorded metadata if the pair changes.`,
+    );
+    return false;
+  }
+  console.log(
+    `route-utterance.ts constants (threshold=${live.threshold}, band=${live.band}) are ${onFront ? "on" : "pinned to the recorded choice, off"} the calibration Pareto front: ${formatPct(live.accuracy)} primary accuracy, 0 false-primaries.`,
+  );
+  return true;
+}
+
+// --- entry point -----------------------------------------------------------------------------
+
+function main(argv: string[]): number {
+  const check = argv.includes("--check");
+  const corpusPath = path.join(skillRoot, "checks/verification/goldens/routing/utterance-calibration.json");
+  const corpus = loadCorpus(corpusPath);
+  const workflows = loadCatalogWorkflows();
+  const results = runGrid(corpus, workflows);
+  const recommended = recommend(results);
+
+  if (check) {
+    const calibrationOk = checkLiveConstants(results);
+    const orthogonalOk = checkOrthogonalHeldOut(workflows);
+    return calibrationOk && orthogonalOk ? 0 : 1;
+  }
+  printSummary(results, recommended);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Utterance router calibration failed.");
+    process.exitCode = 1;
+  }
+}

package/tooling/catalog-scaffold.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * catalog:add-workflow — the workflow scaffolder (layering plan phase E, requirement R8).
+ *
+ * Authoring a workflow used to mean knowing five unwritten steps by heart: which
+ * catalog/workflows/*.ts file owns the area, the workflow() seed shape, the count fixture that
+ * pins the catalog's totals, the projection re-render, and — when the workflow carries a new
+ * gate — the whole validator registration chain. This tool does the mechanical steps itself and
+ * NAMES every remaining one with its exact location, so nothing is remembered and nothing is
+ * silent:
+ *
+ *   npm run catalog:add-workflow -- --id workflow.<domain>.<slug> --title "..." \
+ *     --domain domain.<x> --areas area.<a>[,area.<b>] --role role.<r> --trigger "..." \
+ *     --file <one of the six workflow files> [--action-class draft] [--gates check:x,...] \
+ *     [--outputs path,...] [--reads path,...] [--depends workflow.id,...] \
+ *     [--references reference.id,...] [--recurrence-days N] [--skill-root <dir>] [--no-render]
+ *
+ * What it writes: the workflow() seed appended to the chosen file, and the count fixture in
+ * checks/verification/fixtures/catalog.fixtures.ts bumped by one. What it deliberately does NOT do:
+ * write real instructions (the placeholder demands replacement), register a new gate script
+ * (five registration points, printed with paths), or bind knowledge (knowledge:add owns that).
+ * check:catalog is the arbiter afterwards — a scaffold with no outputs and no gates fails it by
+ * design (contract_empty), because an empty contract is not a workflow.
+ *
+ * --skill-root and --no-render exist for the fixture suite; consumers never need them.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { areas } from "../catalog/areas.js";
+import { domains } from "../catalog/domains.js";
+import { roles } from "../catalog/roles.js";
+import { resolveTsxCommand } from "./lib/tsx-bin.js";
+
+const realSkillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const WORKFLOW_FILES = ["build-release.ts", "growth-revenue.ts", "maintenance.ts", "operating-system.ts", "operations-trust.ts", "product-experience.ts"];
+const ACTION_CLASSES = ["observe", "draft", "mutate", "publish", "spend", "release", "destructive"];
+const PROTECTED_ACTION_CLASSES = new Set(["publish", "spend", "release", "destructive"]);
+
+function options(): Map<string, string> {
+  const map = new Map<string, string>();
+  const argv = process.argv;
+  for (let index = 3; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (flag?.startsWith("--")) map.set(flag.slice(2), value ?? "true");
+  }
+  return map;
+}
+
+function required(map: Map<string, string>, name: string): string {
+  const value = map.get(name)?.trim();
+  if (!value) throw new Error(`--${name} is required.`);
+  return value;
+}
+
+function csv(map: Map<string, string>, name: string): string[] {
+  return (map.get(name) ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function addWorkflow(): void {
+  const opts = options();
+  const skillRoot = opts.get("skill-root") ? path.resolve(opts.get("skill-root")!) : realSkillRoot;
+
+  const id = required(opts, "id");
+  if (!/^workflow\.[a-z0-9-]+\.[a-z0-9-]+$/.test(id)) throw new Error(`--id must look like workflow.<domain>.<slug> (lowercase, hyphens), got "${id}".`);
+  const title = required(opts, "title");
+  const domainId = required(opts, "domain");
+  if (!domains.some((domain) => domain.id === domainId))
+    throw new Error(`Unknown domain: ${domainId}. Known: ${domains.map((domain) => domain.id).join(", ")}`);
+  const areaIds = csv(opts, "areas");
+  if (areaIds.length === 0) throw new Error("--areas is required (comma-separated area ids).");
+  for (const areaId of areaIds) {
+    if (!areas.some((area) => area.id === areaId)) throw new Error(`Unknown area: ${areaId}. Known: ${areas.map((area) => area.id).join(", ")}`);
+  }
+  const roleId = required(opts, "role");
+  if (!roles.some((role) => role.id === roleId)) throw new Error(`Unknown role: ${roleId}. Known: ${roles.map((role) => role.id).join(", ")}`);
+  const trigger = required(opts, "trigger");
+  const file = required(opts, "file");
+  if (!WORKFLOW_FILES.includes(file)) throw new Error(`--file must be one of: ${WORKFLOW_FILES.join(", ")}`);
+  const actionClass = opts.get("action-class") ?? "draft";
+  if (!ACTION_CLASSES.includes(actionClass)) throw new Error(`--action-class must be one of: ${ACTION_CLASSES.join(", ")}`);
+
+  const gates = csv(opts, "gates");
+  const outputs = csv(opts, "outputs");
+  const reads = csv(opts, "reads");
+  const depends = csv(opts, "depends");
+  const references = csv(opts, "references");
+  const recurrenceDays = opts.get("recurrence-days");
+
+  // Duplicate check against the files on disk, not the compiled import — the import reflects
+  // process start, the disk reflects now.
+  const workflowsDir = path.join(skillRoot, "catalog", "workflows");
+  for (const candidate of WORKFLOW_FILES) {
+    const candidatePath = path.join(workflowsDir, candidate);
+    if (existsSync(candidatePath) && readFileSync(candidatePath, "utf8").includes(`"${id}"`)) {
+      throw new Error(`workflow.id_taken: "${id}" already exists in catalog/workflows/${candidate}.`);
+    }
+  }
+
+  const targetPath = path.join(workflowsDir, file);
+  const source = readFileSync(targetPath, "utf8");
+  const anchor = "] as const;";
+  if (!source.trimEnd().endsWith(anchor))
+    throw new Error(`catalog/workflows/${file} does not end with "${anchor}" — the insertion anchor moved; update this scaffolder.`);
+
+  const lines: string[] = [
+    "  workflow({",
+    `    id: ${JSON.stringify(id)},`,
+    `    title: ${JSON.stringify(title)},`,
+    `    domainId: ${JSON.stringify(domainId)},`,
+    `    areaIds: [${areaIds.map((entry) => JSON.stringify(entry)).join(", ")}],`,
+    `    trigger: ${JSON.stringify(trigger)},`,
+    // Empty is a valid "not participating yet" default (see CatalogWorkflowDef's own doc comment,
+    // issue #58) — a scaffolded workflow has no founder-facing history to phrase from until its real
+    // instructions are written; author 3-6 short founderPhrasings by hand once they are.
+    "    founderPhrasings: [],",
+    "    instructions:",
+    '      "SCAFFOLD PLACEHOLDER — replace with the real, checkable procedure for this workflow before merging; check:no-slop and review both read it.",',
+  ];
+  if (reads.length > 0) lines.push(`    reads: [${reads.map((entry) => JSON.stringify(entry)).join(", ")}],`);
+  lines.push(`    roleId: ${JSON.stringify(roleId)},`);
+  if (depends.length > 0) lines.push(`    dependencies: [${depends.map((entry) => JSON.stringify(entry)).join(", ")}],`);
+  if (outputs.length > 0) lines.push(`    outputPaths: [${outputs.map((entry) => JSON.stringify(entry)).join(", ")}],`);
+  if (gates.length > 0) lines.push(`    gates: [${gates.map((entry) => JSON.stringify(entry)).join(", ")}],`);
+  if (references.length > 0) lines.push(`    references: [${references.map((entry) => JSON.stringify(entry)).join(", ")}],`);
+  lines.push(`    actionClass: ${JSON.stringify(actionClass)},`);
+  if (PROTECTED_ACTION_CLASSES.has(actionClass)) {
+    lines.push('    protectedCategory: "spend", // SCAFFOLD PLACEHOLDER — pick the real ProtectedCategory for this action class.');
+  }
+  if (recurrenceDays) lines.push(`    recurrenceDays: ${Number(recurrenceDays)},`);
+  lines.push("    idempotent: true,");
+  lines.push("  }),");
+
+  const insertion = `${lines.join("\n")}\n${anchor}`;
+  writeFileSync(targetPath, `${source.trimEnd().slice(0, -anchor.length)}${insertion}\n`, "utf8");
+
+  // The count fixture: the one place the catalog's workflow total is pinned. Bumping it here is
+  // what makes the scaffold visible to the audit instead of silently failing it.
+  const fixturePath = path.join(skillRoot, "checks", "verification", "fixtures", "catalog.fixtures.ts");
+  const fixture = readFileSync(fixturePath, "utf8");
+  const countPattern = /composition\.base\.workflows === (\d+), `expected base (\d+) workflows/;
+  const match = fixture.match(countPattern);
+  if (!match) throw new Error(`the workflow-count assertion moved in ${fixturePath} — update this scaffolder's pattern.`);
+  const next = Number(match[1]) + 1;
+  writeFileSync(fixturePath, fixture.replace(countPattern, `composition.base.workflows === ${next}, \`expected base ${next} workflows`), "utf8");
+
+  if (!opts.has("no-render")) {
+    const command = resolveTsxCommand(skillRoot, [path.join(skillRoot, "catalog", "render-routing.ts")]);
+    const render = spawnSync(command.executable, command.args, { cwd: skillRoot, encoding: "utf8" });
+    if (render.status !== 0) throw new Error(`catalog render failed after the insert: ${(render.stderr ?? "").slice(-400)}`);
+  }
+
+  console.log(`Created workflow ${id} in catalog/workflows/${file}; count fixture now expects ${next}.`);
+  console.log("");
+  console.log("What this scaffold did NOT do — each is named so nothing rots silently:");
+  console.log("  1. instructions is a placeholder. Write the real, checkable procedure (>= 40 chars, not an echo of the title).");
+  if (outputs.length === 0 && gates.length === 0) {
+    console.log(
+      "  2. No outputs and no gates were given: check:catalog will fail with contract_empty until the workflow declares at least one — an empty contract is not a workflow.",
+    );
+  }
+  if (gates.length > 0) {
+    console.log("  2. Every gate must already be a registered gate command. A NEW gate script needs the full chain:");
+    console.log("     - the script under checks/validation/, plus a check:* entry in BOTH package.jsons (root + skill)");
+    console.log("     - a step in tooling/lib/audit-plan.ts");
+    console.log("     - a row in docs/validators.md");
+    console.log("     - knownValidators in the launchbench runner");
+    console.log("     - the port-ledger row and its Total line");
+  }
+  console.log(`  3. Knowledge bindings go through their own front door: npm run knowledge:add -- --id reference.<domain>.<name> --workflows ${id}`);
+  console.log("  4. Prove it: npm run check:catalog && npm run test:fixtures, then the full npm run audit from the repository root.");
+}
+
+const command = process.argv[2];
+if (command === "add-workflow") addWorkflow();
+else throw new Error("Use add-workflow.");

package/tooling/ci-aggregate.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * ci-aggregate.mjs — honest CI complete verdict.
+ *
+ * Distinguishes intentionally deferred jobs from failed, cancelled, or
+ * unexpectedly missing ones. A presubmit pass is not a full-audit pass.
+ * No package imports: the aggregator job has no npm ci.
+ */
+import { pathToFileURL } from "node:url";
+
+export const CI_SUITE_JOBS = ["presubmit", "audit-fast", "audit-heavy", "hosted-check", "app-check"];
+
+function isTrue(value) {
+  return value === true || value === "true";
+}
+
+/**
+ * @param {{ verification?: string, hosted?: string|boolean, app?: string|boolean, scopeResult?: string }} selection
+ */
+export function expectedDisposition({ verification = "", hosted = false, app = false, scopeResult = "success" } = {}) {
+  const expand = scopeResult !== "success";
+  const full = verification === "full" || expand;
+  return {
+    presubmit: full && !expand ? "deferred" : "required",
+    "audit-fast": full ? "required" : "deferred",
+    "audit-heavy": full ? "required" : "deferred",
+    "hosted-check": full || isTrue(hosted) ? "required" : "deferred",
+    "app-check": full || isTrue(app) ? "required" : "deferred",
+  };
+}
+
+/**
+ * @param {Record<string, string>} results GitHub `needs.*.result` values
+ * @param {{ verification?: string, hosted?: string|boolean, app?: string|boolean, scopeResult?: string }} selection
+ */
+export function aggregateCi(results, selection) {
+  const expected = expectedDisposition(selection);
+  const failed = [];
+  const cancelled = [];
+  const missing = [];
+  const deferred = [];
+  for (const job of CI_SUITE_JOBS) {
+    const got = results[job] ?? "missing";
+    const want = expected[job];
+    if (got === "cancelled") {
+      cancelled.push(job);
+      continue;
+    }
+    if (want === "required") {
+      if (got === "success") continue;
+      if (got === "failure") failed.push(job);
+      else missing.push(job);
+      continue;
+    }
+    if (got === "skipped" || got === "missing") {
+      deferred.push(job);
+      continue;
+    }
+    if (got === "failure") failed.push(job);
+  }
+  const full = selection.verification === "full" && selection.scopeResult === "success";
+  const kind = full ? "full" : "presubmit";
+  const ok = failed.length === 0 && cancelled.length === 0 && missing.length === 0;
+  return { ok, kind, failed, cancelled, missing, deferred, expected };
+}
+
+function main() {
+  const results = {
+    presubmit: process.env.JOB_PRESUBMIT ?? "missing",
+    "audit-fast": process.env.JOB_AUDIT_FAST ?? "missing",
+    "audit-heavy": process.env.JOB_AUDIT_HEAVY ?? "missing",
+    "hosted-check": process.env.JOB_HOSTED ?? "missing",
+    "app-check": process.env.JOB_APP ?? "missing",
+  };
+  const selection = {
+    verification: process.env.VERIFICATION ?? "",
+    hosted: process.env.HOSTED ?? "false",
+    app: process.env.APP ?? "false",
+    scopeResult: process.env.SCOPE_RESULT ?? "success",
+  };
+  const verdict = aggregateCi(results, selection);
+  console.log(JSON.stringify(verdict, null, 2));
+  if (!verdict.ok) {
+    if (verdict.failed.length) console.error(`Failed: ${verdict.failed.join(", ")}`);
+    if (verdict.cancelled.length) console.error(`Cancelled: ${verdict.cancelled.join(", ")}`);
+    if (verdict.missing.length) console.error(`Unexpectedly missing: ${verdict.missing.join(", ")}`);
+    process.exit(1);
+  }
+  if (verdict.kind === "full") {
+    console.log("Full verification passed.");
+    return;
+  }
+  console.log("Presubmit passed. This is not a full-audit pass.");
+  if (verdict.deferred.length) {
+    console.log(`Intentionally deferred: ${verdict.deferred.join(", ")}`);
+  }
+}
+
+function isMainModule() {
+  return process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+}
+
+if (isMainModule()) {
+  main();
+}