shapeup-sdlc 1.6.3 → 3.0.0

package/hooks/lib/decision.mjs

@@ -6,43 +6,50 @@
 // input, every gate in this repo answered the same way:
 //
 //     $ echo 'NOT JSON AT ALL {{{' | node hooks/<gate>.mjs
-//     gate-l2            exit=0   stdout_len=0
 //     gate-zerowork      exit=0   stdout_len=0
 //     sandbox-guard      exit=0   stdout_len=0
 //     safety-spine       exit=0   stdout_len=0
-//     gate-deadline      exit=0   stdout_len=0
 //     gate-intake        exit=0   stdout_len=0
-//     validate-envelope  exit=0   stdout_len=0
+//     verify envelope    exit=0   stdout_len=0
 //
 // exit 0 + silence = allow. But that is ALSO what "inspected the board and deferred" looks like,
-// and what "no rule matched" looks like, and what a thrown exception looks like, and what F-16
-// looked like — a hook whose entire body silently never ran. Four states, one signature. No test,
-// orchestrator or auditor could tell them apart, which is how 26 enforcement points sat inert
-// behind 610 green checks while every one of them reported success.
+// and what "no rule matched" looks like, and what a thrown exception looks like, and what an inert
+// hook looks like — one whose entire body silently never ran. Four states, one signature. No test,
+// orchestrator or auditor can tell them apart, which is how a whole enforcement layer can sit
+// inert while every one of its checks reports success.
 //
-// FAIL-OPEN IS RETAINED, DELIBERATELY. `gate-l2.mjs` argues for it correctly in its own header: a
-// gate that breaks legitimate or standalone runs just gets disabled, and a disabled gate enforces
+// FAIL-OPEN IS RETAINED, DELIBERATELY, and every hook here argues for it in its own header: a gate
+// that breaks legitimate or standalone runs just gets disabled, and a disabled gate enforces
 // nothing. The defect was never the direction. It is that `allow` carried NO EVIDENCE.
 //
-// THE PREDICATE IS ALREADY INVENTED IN THIS REPO. `tests/structural/11-is-main.mjs` calls its
-// helper `spoke()` — did the script produce output? That is exactly the right question. It existed
-// only in the test harness, applied to entry points. This promotes it to runtime and applies it to
-// hooks, which closes F-16's whole CLASS rather than its instance:
+// THE PREDICATE IS ALREADY INVENTED IN THIS REPO. The structural suite calls its helper `spoke()`
+// — did the script produce output? That is exactly the right question. It existed only in the test
+// harness, applied to entry points. This promotes it to runtime and applies it to
+// hooks, which closes the whole CLASS rather than one instance of it:
 //
 //     inspected-and-permitted · no-rule-matched · threw · never ran
 //
-// all four become distinguishable facts in `.shapeup-sdlc/decisions.jsonl`.
+// all four become distinguishable facts in the decisions ledger.
 //
 // TIER: LOCAL, and checkout-wide rather than per-slug — hooks fire outside any run, so there is
 // frequently no `<slug>` to file under. Pure run-trace; the durable cross-machine record is the
 // committed metrics shard, which `stats --hooks` aggregates into.
 //
+// THE PATH IS RESOLVED, NEVER SPELLED. It comes from `lib/paths.mjs` — the same resolver
+// ``harness probe stats` --hooks` reads through. This file used to hardcode the pre-ADR-0001 root, so every
+// hook wrote its receipts to `.shapeup-sdlc/` while the only reader looked in `.shapeup/`:
+// `stats --hooks` reported zero hook activity on every project, which is indistinguishable from
+// the inert-enforcement-layer failure this file exists to make visible. A telemetry channel with
+// a hardcoded root is a telemetry channel with a silent disconnect in it.
+//
 // THE RECEIPT IS BEST-EFFORT BY DESIGN. An unwritable `decisions.jsonl` must never turn into a
 // failed tool call: a receipt that can break a run would get the whole layer disabled, which is
 // the exact outcome this file exists to prevent. Every write here is inside a try/catch.
 
 import { appendFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { dirname } from "node:path";
+import { decisions } from "../../kernel/lib/paths.mjs";
+import { resolveRunId } from "../../kernel/lib/paths.mjs";
 
 /**
  * Where the receipts land.
@@ -54,11 +61,11 @@ import { join, dirname } from "node:path";
  * contaminates is not an instrument.
  *
  * @param {string} [cwd] - Project root; defaults to the process cwd.
- * @returns {string} The ledger path — `SHAPEUP_DECISIONS_PATH` when set, else
- *   `<cwd>/.shapeup-sdlc/decisions.jsonl`.
+ * @returns {string} The ledger path — `SHAPEUP_DECISIONS_PATH` when set, else the LOCAL root's
+ *   `decisions.jsonl`, resolved through `lib/paths.mjs`.
  */
 export function decisionsPath(cwd) {
-  return process.env.SHAPEUP_DECISIONS_PATH || join(cwd || process.cwd(), ".shapeup-sdlc", "decisions.jsonl");
+  return process.env.SHAPEUP_DECISIONS_PATH || decisions(cwd || process.cwd());
 }
 
 /**
@@ -160,6 +167,18 @@ export async function runHook(name, fn) {
     at: new Date().toISOString(),
     hook: name,
     pid: process.pid,
+    // WHICH RUN THIS DECISION BELONGS TO — resolved from the active-scope pointer, best-effort.
+    //
+    // The ledger is checkout-wide by design (a hook frequently fires with no `<slug>` to file
+    // under), which is exactly why the row needs the key: without it, "the enforcement layer denied
+    // 4 writes" cannot be attributed to a run, so a denial rate cannot be compared between runs and
+    // an inert layer in ONE run is invisible inside a healthy checkout-wide total.
+    //
+    // `null` is a real answer, not a failure: a hook firing outside any run genuinely belongs to no
+    // run, and recording that is what lets the export tier partition ambient decisions from run
+    // ones. Resolution reads two small files and swallows every error — a receipt must never be
+    // able to fail a tool call.
+    run_id: (() => { try { return resolveRunId(d.cwd || process.cwd()); } catch { return null; } })(),
     event: d.event ?? null,
     tool: d.tool ?? null,
     subject: d.subject ?? null,
@@ -168,7 +187,7 @@ export async function runHook(name, fn) {
     rule: d.rule ?? null,
   }, d.cwd);
   // Deny/block/warn payloads are emitted by definition. `emit: true` covers the hooks whose whole
-  // job is to SAY something on an allow — session-rehydrate's additionalContext, for instance — so
+  // job is to SAY something on an allow — an injected context hint, for instance — so
   // a permitting hook can still write to stdout without pretending to be a denial.
   //
   // WHY `warn` IS ITS OWN VERDICT (ADR-0001). An advisory gate permits the call, so the obvious

package/hooks/safety-spine.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Safety spine — PreToolUse hook (v1.2, absorb-audit P1).
+// Safety spine — PreToolUse hook (v1.2).
 //
 // The three older hooks guard the PIPELINE (gate order, envelopes, substrates); this one
 // guards the MACHINE and the git remote — the substrate everything else sits on. It denies
@@ -17,7 +17,7 @@
 //                        the model must never widen its own safety envelope (same principle
 //                        as sandbox-guard's active-scope pointer rule)
 //
-// Deliberately conservative, mirrors gate-l2/sandbox-guard: fail-OPEN on unparseable input
+// Deliberately conservative, mirrors the GATE L2 block/sandbox-guard: fail-OPEN on unparseable input
 // or an unmatched command (precision over reach — a spine that broke `rm -rf ./build` would
 // just get disabled), fail-CLOSED the moment a rule provably matches.
 //
@@ -33,8 +33,8 @@
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, join, basename } from "node:path";
 import { globToRegExp, logPathology } from "./sandbox-guard.mjs";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
-import { LOCAL, safetyOverrides, metricsShard } from "../skills/tech-lead/scripts/lib/paths.mjs";
+import { isMain } from "../kernel/lib/argv.mjs";
+import { LOCAL, safetyOverrides, metricsShard } from "../kernel/lib/paths.mjs";
 
 import { runHook, readStdin, settle } from "./lib/decision.mjs";
 

package/hooks/sandbox-guard.mjs

@@ -1,36 +1,59 @@
 #!/usr/bin/env node
-// Sandbox guard — PreToolUse hook (design spec v1.1 §4.5/Blueprint E, PA3 countermeasure).
+// Sandbox guard — PreToolUse hook (the PA3 countermeasure: writes outside the order's substrate).
 //
-// Blocks Edit/Write/MultiEdit calls that touch a file outside the active scope's
-// `allowed_file_substrate` (+ declared `shared_substrate`). Turns "generator only edits its
-// own scope" from prose into a precondition the model cannot talk past — the same pattern as
-// hooks/gate-l2.mjs for GATE L2.
+// Blocks Edit/Write/MultiEdit calls that no LIVE ORDER's `substrate` block permits. Turns "a worker
+// only writes what the run authorised" from prose into a precondition the model cannot talk past.
 //
-// Design (deliberately conservative, mirrors gate-l2.mjs):
-//   • Fail-OPEN whenever there is nothing to enforce: no active-scope pointer (not running
-//     inside a scoped harness round), pointer names a scope contract that doesn't exist or is
-//     unparsable, or the tool call carries no resolvable file path. A guard that breaks
-//     legitimate non-harness edits would just get disabled.
-//   • Fail-CLOSED the moment an active scope IS declared and the target path matches none of
-//     its globs — deny, naming the substrate so the model can self-correct.
+// IT ENFORCES THE ORDER, NOT THE SCOPE CONTRACT, and that is the whole design. ``harness compile``
+// already stamps a write contract onto every order from `substrateFor(operation)` — allowed,
+// shared, append_only, frozen. Resolving the scope contract instead covered exactly one operation,
+// the build, because only build orders carry a scope; every other dispatch (`analyze`, `wire`,
+// `evaluate`, `hunt`, `coach` …) ran unfenced, and the `frozen`/`append_only` surfaces the
+// compiler emits had no enforcer at all. Reading the order makes the contract the compiler writes
+// and the contract the hook enforces the same object, for every operation, with no per-operation
+// code here.
+//
+// IT READS EVERY LIVE ORDER, NOT A POINTER TO ONE. `.shapeup/active-order` still names the run and
+// seeds the search — `harness compile` publishes it as it writes each order, which is what fences
+// the lanes that never reach the workflow (`--tiny`, the prose round loop, a standalone `/build`).
+// But a single pointer cannot survive concurrency: with scopes building side by side the last
+// compile wins the pointer, and a write from scope A is then judged against scope B's contract —
+// a false block or a false permit depending on which way the race fell. So the candidate set is
+// every order under `orders/` with no matching file under `results/` (compiled, not yet ingested),
+// and a write is permitted when SOME live contract covers it.
+//
+// That is the same question as "the writer's own contract" because scope substrates are disjoint by
+// construction — `harness verify spec`'s DISJOINT rule fails a spec where two scopes claim the same
+// path, and it runs at GATE L1b before any build starts. `frozen` is checked across all of them, so
+// a path one scope froze stays frozen while another scope is in flight.
+//
+// Design (deliberately conservative, mirrors the GATE L2 block):
+//   • Fail-OPEN whenever there is nothing to enforce: no active-order pointer (not running inside
+//     a harness dispatch), pointer names an order that doesn't exist or is unparsable, the order
+//     declares no boundaries at all, or the tool call carries no resolvable file path. A guard
+//     that breaks legitimate non-harness edits would just get disabled.
+//   • Fail-CLOSED the moment an order IS live and the target is outside what it permits — deny,
+//     naming the reason so the model can self-correct. `frozen` outranks everything, including
+//     an `allowed` glob that would otherwise match; `append_only` permits Edit and denies Write,
+//     because Write overwrites what the append was supposed to preserve.
 //   • Run-trace carve-out — writes under the ACTIVE feature's LOCAL gitignored root
 //     (`.shapeup/<slug>/`) are always allowed: that root is harness bookkeeping the doer
 //     is REQUIRED to write (task-executor P3 status/AC ticks + tasks/_index.md, run-state,
 //     execution logs, the P3.7 discovery ledger). Substrate globs whitelist product code and
-//     never list the run-trace, so without the carve-out every scoped round strands its own
-//     board (island-escape shipped 16/20 task files stale this way). Deliberately narrow:
-//     only the active slug's root — `.shapeup/active-scope` (this guard's own pointer)
-//     and other features' roots remain subject to the substrate whitelist.
+//     never list the run-trace, so without the carve-out a scoped round leaves its own task files
+//     stale. Deliberately narrow: only the active slug's root. The pointers at the `.shapeup/`
+//     root — `active-order` (this guard's own) and `active-scope` (the run pointer) — sit OUTSIDE
+//     the carve-out by construction, so a worker cannot widen its own sandbox by rewriting the
+//     thing that defines it.
 //   • Every denial is also appended to the metrics pathology log (telemetry, not just defense).
 //
 // Contract: PreToolUse stdin JSON { tool_name, tool_input:{file_path | edits[].file_path}, cwd }.
 // Deny via { hookSpecificOutput: { hookEventName, permissionDecision:"deny", permissionDecisionReason } }.
 
-import { readFileSync, existsSync, appendFileSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, appendFileSync, mkdirSync, readdirSync } from "node:fs";
 import { resolve, join, relative, dirname, sep } from "node:path";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
-import { LOCAL, activeScope, scopeContract, metricsShard } from "../skills/tech-lead/scripts/lib/paths.mjs";
-import { readContract, SCOPE_CONTRACT } from "../skills/tech-lead/scripts/lib/contract-md.mjs";
+import { isMain } from "../kernel/lib/argv.mjs";
+import { LOCAL, activeOrder, ordersDir, resultsDir, metricsShard } from "../kernel/lib/paths.mjs";
 import { runHook, readStdin, settle } from "./lib/decision.mjs";
 
 // --- tiny glob matcher: supports *, **, ? — enough for substrate globs, zero dependencies ---
@@ -65,6 +88,31 @@ function readJSON(p) {
   try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
 }
 
+/**
+ * Every order for this run that has been compiled and not yet ingested.
+ *
+ * "Not yet ingested" is read off the filesystem — an order with a same-named file under `results/`
+ * has finished — because that is the only signal that survives a killed session. The pointer's own
+ * order is always included, even when its result has landed, so the single-order lane behaves
+ * exactly as it did before concurrency existed.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - The active run's slug.
+ * @param {string} pointerOrder - Absolute path of the order the pointer names.
+ * @returns {object[]} Parsed orders; unreadable files are skipped, never treated as permissive.
+ */
+function liveOrders(cwd, slug, pointerOrder) {
+  const dir = ordersDir(cwd, slug);
+  const done = new Set(existsSync(resultsDir(cwd, slug)) ? readdirSync(resultsDir(cwd, slug)) : []);
+  const paths = new Set(existsSync(pointerOrder) ? [pointerOrder] : []);
+  if (existsSync(dir)) {
+    for (const f of readdirSync(dir)) {
+      if (f.endsWith(".json") && !done.has(f)) paths.add(join(dir, f));
+    }
+  }
+  return [...paths].map(readJSON).filter(Boolean);
+}
+
 function extractPaths(toolInput) {
   const paths = [];
   if (toolInput?.file_path) paths.push(toolInput.file_path);
@@ -97,46 +145,78 @@ async function main() {
   }
 
   const cwd = p.cwd || process.cwd();
-  const activeScopePath = activeScope(cwd);
-  // no harness round in progress → don't enforce
-  if (!existsSync(activeScopePath)) defer("no active-scope pointer — no harness round in progress", "no-round");
-
-  const active = readJSON(activeScopePath);
-  if (!active?.slug || !active?.scope_id) defer("active-scope pointer is unreadable or incomplete", "bad-pointer");
-
-  // Markdown first, legacy JSON second (ADR-0001) — a project mid-migration must stay sandboxed.
-  let found = null;
-  try { found = readContract(scopeContract(cwd, active.slug, active.scope_id), SCOPE_CONTRACT); }
-  catch (e) { defer(`scope contract is unparseable (${e.message})`, "bad-contract"); }
-  // pointer stale / contract not committed yet → don't break the run
-  if (!found) defer(`no contract for ${active.scope_id} — pointer stale or not committed yet`, "no-contract");
-  const contract = found.contract;
-  if (!contract) defer("scope contract is unparseable", "bad-contract");
-
-  const allowed = [...(contract.allowed_file_substrate || []), ...(contract.shared_substrate || [])];
-  // no whitelist declared → nothing to enforce
-  if (allowed.length === 0) defer(`scope ${active.scope_id} declares no write whitelist`, "no-whitelist");
+  const activeOrderPath = activeOrder(cwd);
+  if (!existsSync(activeOrderPath)) defer("no active-order pointer — no tracked task running", "no-round");
+
+  const active = readJSON(activeOrderPath);
+  if (!active?.slug || !active?.order_path) defer("active-order pointer is unreadable or incomplete", "bad-pointer");
+
+  // EVERY LIVE ORDER, not just the pointer's. The pointer names one order, and with scopes building
+  // CONCURRENTLY the last compile wins it — so a write from scope A would be judged against scope
+  // B's contract, which is either a false block or a false permit depending on which way the race
+  // fell. Scope substrates are disjoint by construction (spec-lint's DISJOINT rule fails a spec
+  // where they are not), so "is this write inside SOME live contract" and "is it inside the
+  // writer's own contract" are the same question — and only the first can be asked without a
+  // shared mutable pointer.
+  //
+  // Live = compiled and not yet ingested. An order whose result is on disk has finished; leaving it
+  // in the candidate set would keep a finished scope's substrate open for the rest of the run.
+  const orders = liveOrders(cwd, active.slug, resolve(cwd, active.order_path));
+  if (orders.length === 0) defer(`no live order for ${active.slug}`, "no-order");
+
+  const withSubstrate = orders.filter((o) => o.substrate);
+  if (withSubstrate.length === 0) defer("no live order declares a substrate block", "no-substrate");
+
+  const contracts = withSubstrate.map((o) => ({
+    order_id: o.order_id,
+    allowed: [...(o.substrate.allowed || []), ...(o.substrate.shared || [])],
+    appendOnly: o.substrate.append_only || [],
+    frozen: o.substrate.frozen || [],
+  })).filter((c) => c.allowed.length || c.appendOnly.length || c.frozen.length);
+
+  if (contracts.length === 0) defer("no live order declares write/append/frozen boundaries", "no-whitelist");
 
   const targetPaths = extractPaths(p.tool_input);
   if (targetPaths.length === 0) defer("no writable path in the tool input", "no-target");
 
   const metricsPath = metricsShard(cwd);
-  // Run-trace carve-out (see header): the active feature's LOCAL root only. The prefix ends
-  // with a separator so a sibling `<local>/<slug>-other/` can't ride along, and the active-scope
-  // pointer sits outside it by construction.
   const runTracePrefix = join(LOCAL, active.slug) + sep;
   const violations = [];
+  const blockReasons = [];
+
   for (const raw of targetPaths) {
     const abs = resolve(cwd, raw);
     const rel = relative(cwd, abs);
     if (rel.startsWith(runTracePrefix)) continue;
-    if (!matchesAny(rel, allowed)) violations.push(rel);
+
+    // Frozen takes absolute precedence, and it is checked across EVERY live contract: a path one
+    // scope froze stays frozen while another scope is in flight, which is the whole point of
+    // declaring it.
+    const freezer = contracts.find((c) => matchesAny(rel, c.frozen));
+    if (freezer) {
+      violations.push(rel);
+      blockReasons.push(`${rel} is frozen by ${freezer.order_id}`);
+      continue;
+    }
+
+    if (contracts.some((c) => matchesAny(rel, c.allowed))) continue;      // inside a live contract
+
+    if (contracts.some((c) => matchesAny(rel, c.appendOnly))) {
+      if (p.tool_name === "Write") {
+        violations.push(rel);
+        blockReasons.push(`${rel} is append-only (Write overwrites, use Edit)`);
+      }
+      continue;
+    }
+
+    violations.push(rel);
+    blockReasons.push(`${rel} is outside every live order's allowed scopes`);
   }
 
   // Inside the substrate — the "inspected and permitted" row. Previously byte-identical to
   // "this hook never ran", which is how 26 enforcement points sat inert behind 610 green checks.
   if (violations.length === 0) {
-    defer(`${targetPaths.length} path(s) inside scope ${active.scope_id} substrate — permitted`, "in-substrate");
+    defer(`${targetPaths.length} path(s) inside a live order's substrate (${contracts.length} live) — permitted`, "in-substrate");
   }
 
   logPathology(metricsPath, {
@@ -144,23 +224,23 @@ async function main() {
     at: new Date().toISOString(),
     kind: "pathology",
     pathology: "PA3",
-    scope_id: active.scope_id,
+    order: active.order_path,
     slug: active.slug,
     blocked_paths: violations,
   });
 
   return {
-    verdict: "deny", event: "PreToolUse", tool: p.tool_name, subject: active.scope_id, cwd,
+    verdict: "deny", event: "PreToolUse", tool: p.tool_name, subject: active.order_path, cwd,
     rule: "outside-substrate",
-    reason: `${violations.length} write(s) outside the scope substrate: ${violations.join(", ")}`,
+    reason: `${violations.length} write(s) rejected by substrate boundaries: ${blockReasons.join("; ")}`,
     payload: {
       hookSpecificOutput: {
         hookEventName: "PreToolUse",
         permissionDecision: "deny",
         permissionDecisionReason:
-          `Sandbox guard (PA3) — scope "${active.scope_id}" may only write ${JSON.stringify(allowed)}. ` +
-          `Blocked: ${violations.join(", ")}. If this write legitimately crosses scopes, add the path to ` +
-          `the contract's shared_substrate (via ba --remap) rather than editing outside the substrate.`,
+          `Sandbox guard (PA3) — no live order's substrate covers these writes:\n` +
+          `${blockReasons.join("\n")}\n` +
+          `If this write legitimately crosses scopes, the order's substrate needs to be expanded (e.g. via ba --remap).`,
       },
     },
   };