shapeup-sdlc 1.7.0 → 3.0.0

package/kernel/probe/t0.mjs

@@ -0,0 +1,66 @@
+// probe t0 — "has this scope already reached T0-green in this round?"
+//
+// CONTRACT. A bounded, read-only query over the verdict artifacts on disk. Prints
+// `{green, path, round, scope_id}` on stdout; exits 0 when green, 1 when not, 2 on a bad argv.
+// Writes nothing.
+//
+// WHY IT IS A SUBCOMMAND AND NOT AN INLINE SNIPPET. The control plane has no filesystem of its
+// own, so the alternative is a `node -e` blob assembled inside the workflow script. Such a blob is
+// untestable (a workflow script cannot be imported), and it is the one command shape no permission
+// rule can match — the grant covers this entry point, not arbitrary evaluated source.
+//
+// WHY IT READS ARTIFACTS AND NOT A LEDGER. It answers the question a RESUMED round asks: an
+// attempt loop that was killed mid-round must not re-do a scope whose T0 already went green, and
+// the only durable evidence of that is the verdict artifact the evaluator is required to cite.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { verdictsDir } from "../lib/paths.mjs";
+
+/**
+ * The newest green T0 verdict for one scope in one round.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} scopeId - Scope contract id.
+ * @param {number} round - Build round.
+ * @returns {{green: boolean, path: (string|null)}} `path` is the artifact a later EVAL can cite.
+ */
+export function greenVerdict(cwd, slug, scopeId, round) {
+  const dir = verdictsDir(cwd, slug);
+  if (!existsSync(dir)) return { green: false, path: null };
+  // Newest first: an attempt retried after a red one writes a higher trial ordinal at the same
+  // (round, attempt) address, and the LAST verdict is the one that stands.
+  for (const f of readdirSync(dir).filter((x) => x.endsWith(".json")).sort().reverse()) {
+    const p = join(dir, f);
+    try {
+      const b = JSON.parse(readFileSync(p, "utf8"));
+      if (b.scope_id === scopeId && b.round === round && b.overall === "green") return { green: true, path: p };
+    } catch { /* a torn artifact proves nothing; keep looking */ }
+  }
+  return { green: false, path: null };
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe t0 --slug <slug> --scope <scope-id> --round N [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  scope: { type: "str", required: true },
+  round: { type: "int", min: 1, required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Report whether one scope is already T0-green for one round.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when green, 1 when not — the shape a caller can branch on without parsing.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const { green, path } = greenVerdict(cwd, args.slug, args.scope, args.round);
+  console.log(JSON.stringify({ green, path, scope_id: args.scope, round: args.round }));
+  process.exit(green ? 0 : 1);
+}

package/{skills/ba-pitch-analyzer/scripts/board-derive.mjs → kernel/reduce/board.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Board derivation (pure-skill architecture v1.0, plan §8.2).
+// Board derivation — the planner's graph math, as code a model never re-derives.
 //
 // The mechanical half of the old ba-pitch-analyzer Phase 7b + v3.3 link-field rules — pure
 // graph math a model should never re-derive (and gets wrong: hand-authored inverses drift asymmetric
@@ -11,25 +11,27 @@
 //   • Appetite Guard arithmetic (--appetite-hours N → overflow flag; the HAMMER *pause* on
 //     overflow is an orchestrator gate, never resolved here)
 //   • board-vs-T0 drift check (a FINISHED scope whose tasks still read `ready`) when scope
-//     contracts name their tasks — flag, never fix
+//     contracts anchor use cases the board's tasks name back — flag, never fix
+//   • board-vs-dispatch reconciliation (BOARD-UNDISPATCHED, Phase 3.5 / S6): a scope with a
+//     done-marked task but no dispatched-and-answered order anywhere for it — a cut, never
+//     dispatched scope cannot read `done` — flag, never fix
 //
 // Zero dependencies. Usage:
-//   node skills/ba-pitch-analyzer/scripts/board-derive.mjs --slug <slug> [--cwd <dir>] [--write]
+//   node kernel/harness.mjs reduce board --slug <slug> [--cwd <dir>] [--write]
 //        [--appetite-hours N]
 // Prints a JSON report; exit 0 (drift/overflow are flags for the caller's gate, not errors).
 
 import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { isMain } from "../../tech-lead/scripts/lib/is-main.mjs";
-import { runArgs } from "../../tech-lead/scripts/lib/argv.mjs";
-import { tasksDir, scopesDir, hillDir } from "../../tech-lead/scripts/lib/paths.mjs";
-import { readAllContracts, splitFrontmatter, SCOPE_CONTRACT } from "../../tech-lead/scripts/lib/contract-md.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { tasksDir, scopesDir, hillDir, ordersDir, resultsDir } from "../lib/paths.mjs";
+import { readAllContracts, splitFrontmatter, tasksForScope, SCOPE_CONTRACT } from "../lib/contract.mjs";
 
 /**
  * Read a list field from a frontmatter string, inline `[a, b]` or YAML block sequence alike.
  *
  * The SECOND instance of the same defect, in a second parser. This repo had two hand-rolled
- * frontmatter readers: `contract-md.mjs` for the committed contracts, and this one for the board.
+ * frontmatter readers: `lib/contract.mjs` for the committed contracts, and this one for the board.
  * It was fixed in the first, and this one still silently dropped a block sequence — so a board
  * written as
  *   use_case_refs:
@@ -61,7 +63,7 @@ const listField = (fm, key) => {
  * Parse every TASK-*.md in a board directory into structured task records.
  * @param {string} tasksDir - Absolute path to the LOCAL tasks directory.
  * @returns {Array<{file:string, id:string, type:string, status:string, hours:number, pkg:string,
- *   depends_on:string[], unlocks:string[], use_case_refs:string[], body:string}>} One record per
+ *   depends_on:string[], unlocks:string[], use_case_refs:string[], scope_id:string, body:string}>} One record per
  *   task file; [] when the directory does not exist.
  */
 export function parseBoard(tasksDir) {
@@ -81,6 +83,7 @@ export function parseBoard(tasksDir) {
         depends_on: listField(fm, "depends_on"),
         unlocks: listField(fm, "unlocks"),
         use_case_refs: listField(fm, "use_case_refs"),
+        scope_id: (fm.match(/^scope_id:\s*(\S+)/im) || [, ""])[1].trim(),
         body,
       };
     });
@@ -136,24 +139,89 @@ export function criticalPath(tasks) {
 }
 
 /**
- * Flag board-vs-T0 drift: FINISHED scopes whose named tasks are not yet done (flag only, never fix).
- * @param {Array<{id:string, status:string}>} tasks - The parsed board.
- * @param {Array<{scope_id:string, tasks?:string[], finished?:boolean}>} scopes - Scope facts.
+ * Flag board-vs-T0 drift: FINISHED scopes whose tasks are not yet done (flag only, never fix).
+ *
+ * The scope's tasks are joined through its committed `use_cases`, not read off a task-id list the
+ * contract used to carry — see {@link tasksForScope}. A scope that anchors no use case contributes
+ * nothing here rather than a false clean bill: "no anchor" is SCOPE-ANCHOR's finding to report.
+ *
+ * @param {Array<{id:string, status:string, use_case_refs?:string[]}>} tasks - The parsed board.
+ * @param {Array<{scope_id:string, use_cases?:string[], finished?:boolean}>} scopes - Scope facts.
  * @returns {Array<{scope_id:string, task_id:string, status:string}>} One entry per drifting task; [] when none.
  */
 export function driftCheck(tasks, scopes) {
-  const byId = Object.fromEntries(tasks.map((t) => [t.id, t]));
   const drift = [];
   for (const s of scopes) {
-    if (!Array.isArray(s.tasks) || !s.finished) continue;
-    for (const id of s.tasks) {
-      const t = byId[id];
-      if (t && t.status !== "done") drift.push({ scope_id: s.scope_id, task_id: id, status: t.status });
+    if (!s.finished) continue;
+    for (const t of tasksForScope(tasks, s)) {
+      if (t.status !== "done") drift.push({ scope_id: s.scope_id, task_id: t.id, status: t.status });
     }
   }
   return drift;
 }
 
+/**
+ * Read every dispatched-and-answered order's scope id (Phase 3.5 / S6).
+ *
+ * "Dispatched and answered" is filename presence in both directories, the same completion signal
+ * `sandbox-guard`'s `liveOrders()` already uses — a result join on content would let a malformed
+ * result count as an answer. The scope an order belongs to comes from `payload.scope_contract.
+ * scope_id`, not the filename: a non-BUILD order's suffix puts the operation before the scope id
+ * (`compileOrder`'s `scopedRoundSuffix`), so filename-prefix matching would miss it.
+ *
+ * @param {string} orders - Absolute path to the run's `orders/` directory.
+ * @param {string} results - Absolute path to the run's `results/` directory.
+ * @returns {Set<string>} scope_ids with at least one dispatched order answered by a same-named
+ *   result file; empty when neither directory has anything to read.
+ */
+function answeredScopeIds(orders, results) {
+  const answered = new Set();
+  if (!existsSync(orders)) return answered;
+  const done = new Set(existsSync(results) ? readdirSync(results) : []);
+  for (const f of readdirSync(orders)) {
+    if (!f.endsWith(".json") || !done.has(f)) continue;
+    try {
+      const sid = JSON.parse(readFileSync(join(orders, f), "utf8"))?.payload?.scope_contract?.scope_id;
+      if (sid) answered.add(sid);
+    } catch { /* an unreadable order answers nothing — spec-lint reports unreadable contracts, not this */ }
+  }
+  return answered;
+}
+
+/**
+ * Flag a scope whose board tasks read done but has no dispatched-and-answered order on disk
+ * (Phase 3.5 / S6) — the defect that motivated this phase: a scope cut before it was ever
+ * dispatched can still read `done` on the board because nothing compared the board's rows to what
+ * was actually dispatched, though both the scope contract and the order/result trail already exist
+ * on disk. A sibling to {@link driftCheck} (a FINISHED scope whose tasks are NOT done) — this is
+ * the opposite direction (done tasks, no dispatch trail) and both must keep running.
+ *
+ * @param {Array<{id:string, status:string, use_case_refs?:string[]}>} tasks - The parsed board.
+ * @param {Array<{scope_id:string, use_cases?:string[]}>} scopes - Scope contracts.
+ * @param {string} orders - Absolute path to the run's `orders/` directory.
+ * @param {string} results - Absolute path to the run's `results/` directory.
+ * @returns {Array<{rule:string, level:string, scope_id:string, detail:string}>} One finding per
+ *   undispatched-but-done scope, in this codebase's `{rule, level, detail}` finding shape
+ *   (`kernel/verify/spec.mjs`); [] when every done-marked scope has a dispatch trail.
+ */
+export function undispatchedCheck(tasks, scopes, orders, results) {
+  const answered = answeredScopeIds(orders, results);
+  const findings = [];
+  for (const s of scopes) {
+    // Joined through the contract's committed `use_cases`, same as driftCheck — the two read the
+    // scope↔task relation from one function so they cannot disagree about which tasks a scope owns.
+    const doneTaskId = tasksForScope(tasks, s).find((t) => t.status === "done")?.id;
+    if (doneTaskId && !answered.has(s.scope_id)) {
+      findings.push({
+        rule: "BOARD-UNDISPATCHED", level: "red", scope_id: s.scope_id,
+        detail: `${doneTaskId} reads done for scope ${s.scope_id}, but no order under orders/ has a ` +
+          `matching result under results/ for this scope — a cut, never-dispatched scope cannot read done`,
+      });
+    }
+  }
+  return findings;
+}
+
 /**
  * Derive the full board report (unlocks, hours, packages, critical path, appetite overflow, drift).
  * @param {{cwd:string, slug:string, appetiteHours?:(number|null)}} opts - Working root, feature
@@ -170,7 +238,8 @@ export function derive({ cwd, slug, appetiteHours = null }) {
   const packages = {};
   for (const t of tasks) packages[t.pkg || "(none)"] = (packages[t.pkg || "(none)"] || 0) + 1;
 
-  // Scope facts for the drift check: contract `tasks` list + committed hill shard phase.
+  // Scope facts for the drift check: the contract (its `use_cases` carry the task join)
+  // + the committed hill shard's phase.
   const hillRoot = hillDir(cwd, slug);
   const scopes = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT).map(({ contract }) => {
     const shard = join(hillRoot, `${contract.scope_id}.yml`);
@@ -194,6 +263,7 @@ export function derive({ cwd, slug, appetiteHours = null }) {
     unlocks,
     unlocks_stale: tasks.filter((t) => JSON.stringify([...t.unlocks].sort()) !== JSON.stringify(unlocks[t.id])).map((t) => t.id),
     drift: driftCheck(tasks, scopes),
+    undispatched: undispatchedCheck(tasks, scopes, ordersDir(cwd, slug), resultsDir(cwd, slug)),
     _tasks: tasks,
   };
 }
@@ -220,9 +290,9 @@ export function writeUnlocks(report) {
   return written;
 }
 
-/** The typed argv contract (see `skills/tech-lead/scripts/lib/argv.mjs`). */
+/** The typed argv contract (see `kernel/lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "board-derive.mjs --slug <slug> [--cwd <dir>] [--write] [--appetite-hours N]",
+  usage: "harness.mjs reduce board --slug <slug> [--cwd <dir>] [--write] [--appetite-hours N]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   cwd: { type: "path" },
@@ -230,9 +300,15 @@ export const ARGV_SPEC = {
   "appetite-hours": { type: "num", min: 0 },
 };
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Derive the task board from the scope contracts, and optionally write it.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
   const report = derive({ cwd, slug: args.slug, appetiteHours: args.appetiteHours ?? null });
   if (args.write) report.unlocks_written = writeUnlocks(report);