shapeup-sdlc 3.18.3 → 4.0.0

package/kernel/probe/leg.mjs

@@ -1,229 +0,0 @@
-// probe leg — "did this scope's work actually reach the board?"
-//
-// CONTRACT. A bounded, read-only query over one scope's orders, results and leg-completion rows for
-// one round. Prints `{closed, scope_id, round, orders: [...], unapplied: [...]}` on stdout; exits 0
-// when every order that produced a result has been ingested, 1 when at least one has not, 2 on a bad
-// argv. Writes nothing.
-//
-// WHY IT EXISTS. `probe t0` answers "is the T0 verdict green", and the BUILD round's confirm stage
-// asked only that. A green T0 says the worker's fixtures ran and passed; it says nothing about
-// whether the WorkResult was applied — and this is a state a real run reaches. A build leg can write
-// its code, a green T0 verdict, a kept trial row and its WorkResult to disk, and never run step 3 of
-// its own script, `reduce ingest`. It reports green; a confirm stage that re-verifies only the T0
-// artifact agrees, and the round walks on. That scope's task is left `pending` with zero acceptance
-// criteria ticked while its code sits finished on disk, beside a sibling scope whose task is `done`.
-//
-// Nothing has to be wrong with the order, the receipt or the result for this to happen — ingesting the
-// same file afterwards succeeds and ticks the criteria. The single writer of shared state simply never
-// ran, and the board GATE L2 reads as "100% ✅" silently disagrees with a scope that is genuinely
-// finished. Under fan-out it gets worse rather than better: N legs can each drop the step
-// independently, and the only symptom is a board that lags reality.
-//
-// WHY A LEG ROW IS THE RIGHT EVIDENCE. The row is appended BY `reduce ingest`. Its presence is
-// therefore proof the writer ran, and it is not something the leg can assert about itself — the same
-// reason the dispatch receipt is written by the hook layer rather than by the sub-agent making the
-// call. "The worker says it ingested" is exactly the class of claim this pipeline does not accept.
-
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { runArgs } from "../lib/argv.mjs";
-import { ordersDir, resultsDir, legLedger, dispatchReceipts, readRunId } from "../lib/paths.mjs";
-
-/** `<scope>-r<round>-a<attempt>.json` — the only address a build order is written under. */
-const BUILD_ORDER = /^(.+)-r(\d+)-a(\d+)\.json$/;
-
-/**
- * Every leg-completion row on disk, tolerant of a torn last line.
- * @param {string} path - The leg ledger.
- * @returns {object[]} Parsed rows; an unparsable line is skipped rather than fatal.
- */
-export function readLegs(path) {
-  if (!existsSync(path)) return [];
-  return readFileSync(path, "utf8").split("\n").filter(Boolean)
-    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
-    .filter(Boolean);
-}
-
-/**
- * Which of one scope's orders in one round produced a result, and which of those were applied.
- *
- * An order with no result has not finished and is not a finding — the leg may still be running, or
- * may have died, which the round already treats as a spent attempt. What this reports is the
- * narrower and stranger case: a result on disk that the single writer never applied.
- *
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @param {string} scopeId - Scope contract id.
- * @param {number} round - Build round.
- * @returns {{closed: boolean, orders: object[], unapplied: object[]}} `closed` is false only when a
- *   result exists that was never ingested; a scope with no results at all reports `closed: false`
- *   with an empty `orders` list, so a caller can tell "nothing ran" from "nothing was applied".
- */
-/**
- * Every order the run compiled, with whether its result landed and whether the single writer
- * applied it — planning orders (`analyze.json`) and build orders (`alpha-r1-a1.json`) alike.
- *
- * Why the generic form exists: the per-scope reading below was the only reader of the leg ledger
- * in the run loop, and it was asked in one place, behind the checks that decide a scope is green.
- * Measured on a live run: five dispatches, five results, three leg rows — and the planning phase
- * whose result nobody applied walked on, because its post-condition checked the artifact the
- * worker wrote directly and never asked whether the writer ran. This is the question, asked of any
- * order by name.
- *
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @returns {{order:string, name:string, order_id:(string|null), has_result:boolean, applied:boolean}[]}
- */
-export function legsOf(cwd, slug) {
-  const oDir = ordersDir(cwd, slug);
-  const rDir = resultsDir(cwd, slug);
-  const ingested = new Set(readLegs(legLedger(cwd, slug))
-    .filter((r) => r.ingested_at)
-    .map((r) => String(r.order_id)));
-  // Dispatch receipts are the hook layer's record that a Skill was invoked against an order —
-  // scoped to this run, since receipts over one slug accumulate across runs and order ids repeat.
-  const runId = readRunId(cwd, slug);
-  const receipted = new Set(readLegs(dispatchReceipts(cwd, slug))
-    .filter((r) => r?.order_id && (!runId || !r.run_id || r.run_id === runId))
-    .map((r) => String(r.order_id)));
-  const out = [];
-  for (const f of (existsSync(oDir) ? readdirSync(oDir) : []).filter((x) => x.endsWith(".json")).sort()) {
-    let orderId = null;
-    try { orderId = JSON.parse(readFileSync(join(oDir, f), "utf8")).order_id ?? null; } catch { /* unreadable — reported as unapplied */ }
-    out.push({
-      order: join(oDir, f),
-      name: f.replace(/\.json$/, ""),
-      order_id: orderId,
-      has_receipt: orderId !== null && receipted.has(orderId),
-      has_result: existsSync(join(rDir, f)),
-      applied: orderId !== null && ingested.has(orderId),
-    });
-  }
-  return out;
-}
-
-/**
- * One order by its file stem — `analyze`, `wire`, `alpha-r1-a1` — and whether its leg closed.
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @param {string} name - The order file's stem.
- * @returns {{closed:boolean, found:boolean, order:(string|null), order_id:(string|null), has_result:boolean, applied:boolean}}
- */
-export function orderLegState(cwd, slug, name) {
-  const o = legsOf(cwd, slug).find((x) => x.name === name);
-  if (!o) return { closed: false, found: false, order: null, order_id: null, has_receipt: false, has_result: false, applied: false };
-  return { closed: o.applied, found: true, ...o };
-}
-
-/**
- * Orders that were dispatched — a receipt says a Skill ran against them — and never answered:
- * no WorkResult on disk. Measured on a live run: the first dispatch wrote its four artifacts and
- * no envelope, every later phase read the artifacts, and the run closed `shipped` with the order
- * still open by construction — the export's own dispatch row said `answered: false` and nothing
- * upstream of it had noticed. Distinct from {@link openLegs}: that is work nobody applied; this is
- * a leg that never came back.
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @returns {{order:string, name:string, order_id:(string|null)}[]}
- */
-export function unansweredOrders(cwd, slug) {
-  return legsOf(cwd, slug).filter((o) => o.has_receipt && !o.has_result);
-}
-
-/**
- * The results on disk that no leg row applied — finished work the board never saw.
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @returns {{order:string, name:string, order_id:(string|null)}[]}
- */
-export function openLegs(cwd, slug) {
-  return legsOf(cwd, slug).filter((o) => o.has_result && !o.applied);
-}
-
-export function legState(cwd, slug, scopeId, round) {
-  const oDir = ordersDir(cwd, slug);
-  const rDir = resultsDir(cwd, slug);
-  const legs = readLegs(legLedger(cwd, slug));
-  const ingested = new Set(legs
-    .filter((r) => Number(r.round) === round && r.scope_id === scopeId && r.ingested_at)
-    .map((r) => String(r.order_id)));
-
-  const orders = [];
-  for (const f of (existsSync(oDir) ? readdirSync(oDir) : []).sort()) {
-    const m = f.match(BUILD_ORDER);
-    if (!m || m[1] !== scopeId || Number(m[2]) !== round) continue;
-    // The order id is read off the order rather than rebuilt from the filename: the filename is the
-    // path the round knows, and the id is the key every record joins on, and they are allowed to be
-    // written by different steps.
-    let orderId = null;
-    try { orderId = JSON.parse(readFileSync(join(oDir, f), "utf8")).order_id ?? null; } catch { /* unreadable — reported below */ }
-    orders.push({
-      order: join(oDir, f),
-      order_id: orderId,
-      attempt: Number(m[3]),
-      has_result: existsSync(join(rDir, f)),
-      applied: orderId !== null && ingested.has(orderId),
-    });
-  }
-  const unapplied = orders.filter((o) => o.has_result && !o.applied);
-  return { closed: orders.some((o) => o.applied) && unapplied.length === 0, orders, unapplied };
-}
-
-export const ARGV_SPEC = {
-  usage: "harness.mjs probe leg --slug <slug> (--scope <scope-id> --round N | --order <stem> | --open) [--cwd <dir>]",
-  _: { arity: 0, max: 0, name: "(no positional operands)" },
-  slug: { type: "str", required: true },
-  scope: { type: "str" },
-  round: { type: "int", min: 1 },
-  order: { type: "str" },
-  open: { type: "flag" },
-  cwd: { type: "path" },
-};
-
-/**
- * Report whether one scope's results for one round reached the board.
- *
- * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
- * @returns {void} Exits 0 when closed, 1 when a result was never applied — the shape a caller can
- *   branch on without parsing prose.
- */
-export function cli(rawArgv) {
-  const args = runArgs(ARGV_SPEC, rawArgv);
-  const cwd = resolve(args.cwd || process.cwd());
-  // `--open`: every result nothing applied, across the whole run, any phase. Exit 0 when none.
-  if (args.open) {
-    const open = openLegs(cwd, args.slug);
-    const unanswered = unansweredOrders(cwd, args.slug);
-    console.log(JSON.stringify({
-      closed: open.length === 0 && unanswered.length === 0,
-      open_total: open.length, open: open.map((o) => o.order), open_ids: open.map((o) => o.order_id),
-      unanswered_total: unanswered.length, unanswered: unanswered.map((o) => o.order), unanswered_ids: unanswered.map((o) => o.order_id),
-    }));
-    process.exit(open.length === 0 && unanswered.length === 0 ? 0 : 1);
-  }
-  // `--order <stem>`: one order by file stem (`analyze`, `alpha-r1-a1`). Exit 0 when its leg closed.
-  if (args.order) {
-    const s = orderLegState(cwd, args.slug, args.order);
-    console.log(JSON.stringify(s));
-    process.exit(s.closed ? 0 : 1);
-  }
-  if (!args.scope || !args.round) {
-    console.error("probe leg: pass --scope <id> --round N, or --order <stem>, or --open");
-    process.exit(2);
-  }
-  const s = legState(cwd, args.slug, args.scope, args.round);
-  console.log(JSON.stringify({
-    closed: s.closed,
-    scope_id: args.scope,
-    round: args.round,
-    // The counts travel with the verdict: `closed: false` over zero orders means the leg has not run,
-    // and over three orders means its work is on disk and unapplied. Those need different answers
-    // from the caller, so they must not read the same.
-    orders_total: s.orders.length,
-    results_total: s.orders.filter((o) => o.has_result).length,
-    applied_total: s.orders.filter((o) => o.applied).length,
-    orders: s.orders,
-    unapplied: s.unapplied.map((o) => o.order),
-  }));
-  process.exit(s.closed ? 0 : 1);
-}

package/kernel/probe/owner.mjs

@@ -1,142 +0,0 @@
-#!/usr/bin/env node
-// probe owner — which scope owns a path, derived from the contracts and nothing else.
-//
-// WHY THIS IS A QUERY AND NOT A SENTENCE. GATE H's census stated ownership facts without reading
-// the contracts: a ship report said no scope owned the app's page files, while the composition
-// root's committed substrate listed `pages/**` in plain sight. The real gap was elsewhere (a route
-// table naming files nobody had written), and the report pointed the PO at a scope cut that was
-// not the problem. A census that narrates ownership from memory is a census that can be wrong in
-// exactly the way that looks most authoritative.
-//
-// Ownership already has ONE mechanical definition in this plugin — the substrate the sandbox hook
-// enforces, and the election `harness compile` runs to address a cited bug to the scope that may
-// write the file (`electOwner`). This probe exposes that same answer on the command line, so a
-// worker that needs to say "no scope owns X" can cite the query instead of asserting it.
-//
-// With no `--path`, the input set is what a census would ask about anyway: every engine and
-// entry-point call site the wiring map names, plus the profile's entry point. A row with no
-// writers is an UNOWNED SEAM — the one kind of gap the disjointness lint cannot see, since DISJOINT
-// fails two owners and nothing fails zero.
-//
-// Usage:
-//   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe owner --slug <slug> [--path <p>]... [--format json|table] [--cwd <dir>]
-//
-// Exit code: 0 = answered, 2 = bad argv or no readable scope contracts.
-
-import { existsSync } from "node:fs";
-import { resolve, join } from "node:path";
-import { runArgs, isMain } from "../lib/argv.mjs";
-import { wiringMap, projectProfile } from "../lib/paths.mjs";
-import { readContract, WIRING_MAP, PROJECT_PROFILE } from "../lib/contract.mjs";
-import { scopeSubstrates, electOwner, bugLocations } from "../compile.mjs";
-import { matchesAny } from "../../hooks/sandbox-guard.mjs";
-
-/**
- * Ownership of one repo-relative path under a set of scope substrates.
- *
- * @param {string} path - Repo-relative POSIX path.
- * @param {Array<{scope_id:string, allowed:string[], shared:string[]}>} scopes - From
- *   {@link scopeSubstrates}.
- * @param {string} [cwd] - Project root; when given, `exists` says whether the path is on disk.
- * @returns {{path:string, owner:(string|null), writers:string[], shared_with:string[], exists:(boolean|null)}}
- *   `owner` is the elected fixer (exclusive first, lowest id among equals); `writers` every scope
- *   whose substrate admits the path; `shared_with` the writers that declare it shared. Empty
- *   `writers` means no scope may write the file — an unowned path. `exists` is the other half a
- *   census needs: a seam that is owned but not on disk is a route to a file nobody wrote.
- */
-export function ownership(path, scopes, cwd = null) {
-  const rel = String(path).replace(/^\.\//, "");
-  const shared = (scopes || []).filter((s) => matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
-  // `writers` is admits-the-path, the same union the sandbox fence composes (allowed ++ shared) —
-  // a path declared only in a contract's `shared` list is still a scope this path may write, and
-  // must read as owned rather than UNOWNED. `shared_with` (below) stays the narrower subset.
-  const writers = (scopes || []).filter((s) => matchesAny(rel, s.allowed) || matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
-  return { path: rel, owner: electOwner(rel, scopes), writers, shared_with: shared, exists: cwd ? existsSync(join(cwd, rel)) : null };
-}
-
-/**
- * The paths a census asks about when none are given: the wiring map's engines and entry call
- * sites, and the profile's entry point. Only tokens that look like files are kept — an entry call
- * site is prose around a path (`src/server.ts — POST /checkout route`), and the path is what the
- * substrate can answer for.
- *
- * @param {string} cwd - Project root.
- * @param {string} slug - Feature slug.
- * @returns {Array<{path:string, cited_by:string}>} Distinct paths with where each was named.
- */
-export function seamPaths(cwd, slug) {
-  const out = [];
-  const seen = new Set();
-  const add = (p, by) => { if (p && !seen.has(p)) { seen.add(p); out.push({ path: p, cited_by: by }); } };
-  const wm = wiringMap(cwd, slug);
-  if (existsSync(wm)) {
-    const entries = readContract(wm, WIRING_MAP)?.contract?.entries || [];
-    for (const e of entries) {
-      for (const p of bugLocations({ location: e.engine })) add(p, `${e.use_case || "?"} engine`);
-      for (const p of bugLocations({ location: e.entry_call_site })) add(p, `${e.use_case || "?"} entry_call_site`);
-    }
-  }
-  const pp = projectProfile(cwd, slug);
-  if (existsSync(pp)) {
-    const ep = readContract(pp, PROJECT_PROFILE)?.contract?.entry_point;
-    for (const p of bugLocations({ location: ep })) add(p, "project-profile entry_point");
-  }
-  return out;
-}
-
-/**
- * Render the report as a fixed-width table for a human reading a gate block.
- * @param {object} r - The report {@link cli} prints.
- * @returns {string} One header line and one row per path.
- */
-export function renderTable(r) {
-  const rows = r.paths.map((p) => [p.path, p.owner || "—", p.writers.join(",") || "UNOWNED", p.exists === null ? "?" : p.exists ? "yes" : "MISSING", p.cited_by || ""]);
-  const head = ["path", "owner", "writers", "on disk", "cited by"];
-  const w = head.map((h, i) => Math.max(h.length, ...rows.map((row) => String(row[i]).length)));
-  const line = (row) => row.map((c, i) => String(c).padEnd(w[i])).join("  ").trimEnd();
-  return [line(head), line(w.map((n) => "-".repeat(n))), ...rows.map(line),
-    "", `${r.scopes} scope(s) read · ${r.unowned.length} unowned path(s)${r.unowned.length ? `: ${r.unowned.join(", ")}` : ""}` +
-    ` · ${r.missing.length} not on disk${r.missing.length ? `: ${r.missing.join(", ")}` : ""}`].join("\n");
-}
-
-export const ARGV_SPEC = {
-  usage: "harness.mjs probe owner --slug <slug> [--path <p>]... [--format json|table] [--cwd <dir>]",
-  _: { arity: 0, max: 0, name: "(no positional operands)" },
-  slug: { type: "str", required: true },
-  path: { type: "str", multiple: true },
-  format: { type: "enum", values: ["json", "table"], default: "json" },
-  cwd: { type: "path" },
-};
-
-/**
- * Answer "which scope owns this path" from the committed contracts.
- *
- * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
- * @returns {Promise<void>} Exits 0 with the report, 2 when no scope contract can be read.
- */
-export async function cli(rawArgv) {
-  const args = runArgs(ARGV_SPEC, rawArgv);
-  const cwd = resolve(args.cwd || process.cwd());
-  const scopes = scopeSubstrates(cwd, args.slug);
-  if (!scopes.length) {
-    console.error(`probe owner: no readable scope contract for ${args.slug} — ownership is a property of the contracts, and there are none to read`);
-    process.exit(2);
-  }
-  const asked = (args.path || []).map((p) => ({ path: p, cited_by: "--path" }));
-  const inputs = asked.length ? asked : seamPaths(cwd, args.slug);
-  const paths = inputs.map((i) => ({ ...ownership(i.path, scopes, cwd), cited_by: i.cited_by }));
-  const report = {
-    slug: args.slug,
-    scopes: scopes.length,
-    source: asked.length ? "--path" : "wiring-map + project-profile",
-    paths,
-    unowned: paths.filter((p) => p.writers.length === 0).map((p) => p.path),
-    // Owned but absent: the wiring names a file nobody wrote — the gap a census reads as
-    // "unowned" when it does not check the disk.
-    missing: paths.filter((p) => p.exists === false).map((p) => p.path),
-  };
-  console.log(args.format === "table" ? renderTable(report) : JSON.stringify(report, null, 2));
-  process.exit(0);
-}
-
-if (isMain(import.meta.url)) cli(process.argv.slice(2));