shapeup-sdlc 1.7.0 → 3.0.0

package/hooks/dispatch-receipt.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Dispatch receipt — PostToolUse hook. The attestation that the SHIPPED skill ran.
+//
+// WHAT IT DEFENDS AGAINST, measured live rather than imagined. A worker dispatch that fails —
+// plugin absent, disabled, or the wrong version loaded — comes back as `<tool_use_error>Unknown
+// skill</tool_use_error>`, and the sub-agent then does the craft ITSELF from the prose in its own
+// prompt. Everything downstream accepts the result: the artifacts are on disk, in exactly the right
+// place, so the phase post-condition passes and the run advances. Both existing walls fire correctly
+// and neither can help — the order gate validates the ORDER, the sandbox guard validates WHERE
+// writes land, and an improvised write satisfies both. Nothing in the system attested WHICH SKILL
+// produced an artifact, so a green run was consistent with zero shipped craft having been applied.
+// That is not a failure, it is a FALSE GREEN, and it defeats "measured, not claimed" at the root:
+// the measurement was "is the artifact on disk", which cannot distinguish skill-produced from
+// improvised.
+//
+// WHY PostToolUse AND NOT PreToolUse. `PreToolUse` fires BEFORE the tool runs, so it cannot separate
+// "the Skill returned" from "the Skill errored and the sub-agent improvised". It appears to catch the
+// observed instance only by coupling — the plugin was not loaded, so these hooks were not registered
+// either, so there was no receipt. The moment the environment is repaired, a dispatch that errors
+// still gets a `PreToolUse` receipt written before it fails, and the fix expires exactly when the
+// thing it guards starts working.
+//
+// WHAT WAS MEASURED, in a real session with the plugin loaded and a SUB-AGENT making the calls
+// (every dispatch in this pipeline is a `Skill(...)` call made by a workflow leg, never by the main
+// session, so a hook that is blind there is blind exactly where it is needed):
+//
+//   skill resolves and completes  →  PostToolUse fires, tool_response = {success, commandName}
+//   skill name unknown            →  NO hook fires at all; the host rejects the name upstream
+//   order missing → gate denies   →  PreToolUse deny, then nothing; a denied call never runs
+//
+// So the discriminator is stronger than a status field: A FAILED DISPATCH LEAVES NO ROW. The mere
+// existence of a matching receipt is the wall; `dispatch_ok` is corroboration on top of it, recorded
+// because a future host that reports failures through this event must not be able to satisfy the
+// wall by firing at all.
+//
+// WHAT IT WILL NOT ATTEST. A receipt is written only when the tool result NAMES the skill that ran
+// (`tool_response.commandName`). An `Agent` dispatch whose prompt merely mentions `--order` gets no
+// receipt: the prompt is a plan to dispatch, not evidence of one, and minting attestation from it
+// would forge the exact fact this file exists to establish.
+//
+// EVERY WRITE IS INSIDE try/catch AND THIS HOOK NEVER DENIES (`lib/decision.mjs`). An unguarded
+// `writeFileSync` in a hook body becomes `verdict:"error"` → exit 0 → the dispatch proceeds WITHOUT
+// a receipt, and the phase then dies at ingest instead — a receipt channel that can break a run
+// gets the whole layer disabled, which is the outcome this file exists to prevent.
+//
+// Contract: PostToolUse stdin JSON { tool_name, tool_input:{skill,args}, tool_response, cwd }.
+
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { isMain } from "../kernel/lib/argv.mjs";
+import { dispatchReceipts } from "../kernel/lib/paths.mjs";
+import { runHook, readStdin, settle } from "./lib/decision.mjs";
+
+/**
+ * The `--order` matcher, character-for-character the one the PreToolUse order gate uses
+ * (`kernel/verify/envelope.mjs`). Two dispatch hooks that disagree about what an order path IS
+ * would gate one set of calls and attest another.
+ */
+export const ORDER_RE = /--order(?:\s+|=)(?:"([^"]+)"|'([^']+)'|(\S+))/;
+
+/**
+ * Pull the order path out of a dispatch's tool input.
+ * @param {object} toolInput - The `tool_input` block from the hook payload.
+ * @returns {string|null} The path as written, or null when no `--order` was threaded.
+ */
+export function orderPathFrom(toolInput) {
+  const haystack = [toolInput?.skill_args, toolInput?.args, toolInput?.prompt].filter(Boolean).join(" ");
+  const m = haystack.match(ORDER_RE);
+  return m ? (m[1] || m[2] || m[3]) : null;
+}
+
+/**
+ * Which skill actually ran, from the tool result.
+ *
+ * The host reports it NAMESPACED (`shapeup-sdlc-plugin:orient`) while a WorkOrder's `worker` field
+ * carries the bare skill name (`orient`), so the comparison the ingest gate performs is only
+ * meaningful against the segment after the last `:`.
+ *
+ * @param {object} toolResponse - The `tool_response` block from the hook payload.
+ * @returns {string|null} The bare skill name, or null when the result names no command — which is
+ *   the case for every dispatch that did not resolve to a skill.
+ */
+export function skillInvokedFrom(toolResponse) {
+  const name = toolResponse?.commandName;
+  if (typeof name !== "string" || !name) return null;
+  return name.slice(name.lastIndexOf(":") + 1) || null;
+}
+
+/**
+ * Build the receipt row for one dispatch.
+ *
+ * Exported so the suite can assert the row's SHAPE without a live session — the hook body is
+ * otherwise reachable only through stdin.
+ *
+ * @param {object} order - The parsed WorkOrder the dispatch was aimed by.
+ * @param {string} skillInvoked - The bare skill name the host reported running.
+ * @param {object} payload - The whole hook payload, for the sub-agent provenance fields.
+ * @returns {object} The row appended to the run's dispatch ledger.
+ */
+export function receiptRow(order, skillInvoked, payload) {
+  return {
+    at: new Date().toISOString(),
+    order_id: order.order_id ?? null,
+    run_id: order.run_id ?? null,
+    worker_declared: order.worker ?? null,
+    skill_invoked: skillInvoked,
+    // Corroboration, not the wall — see the header. `success` is absent on hosts that do not
+    // report one, and an absent field must not read as a successful dispatch.
+    dispatch_ok: payload?.tool_response?.success === true,
+    tool: payload?.tool_name ?? null,
+    // Present when the dispatch came from a sub-agent, absent when the operator called it directly.
+    // That is the difference between an orchestrated leg and someone driving a skill by hand.
+    agent_id: payload?.agent_id ?? null,
+    agent_type: payload?.agent_type ?? null,
+  };
+}
+
+/**
+ * Append one receipt to the run's dispatch ledger. Never throws.
+ * @param {object} row - A {@link receiptRow}.
+ * @param {string} cwd - Project root the LOCAL root resolves against.
+ * @returns {string|null} The ledger path when the row reached disk, else null.
+ */
+export function writeReceipt(row, cwd) {
+  try {
+    const slug = String(row.order_id).split("/")[0];
+    if (!slug) return null;
+    const path = dispatchReceipts(cwd, slug);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(row) + "\n");
+    return path;
+  } catch { return null; }
+}
+
+/**
+ * The hook body — attest a completed dispatch, defer on everything else.
+ * @returns {Promise<void>} Settles through {@link runHook}, which always exits 0.
+ */
+export async function main() {
+  await runHook("dispatch-receipt", async () => {
+    /**
+     * Permit with the reason on the record. This hook has no deny path at all.
+     *
+     * THE SKILL NAME TRAVELS ON EVERY ROW, including the defers, and that is load-bearing rather
+     * than decorative. A dispatch whose skill name does not resolve fires no hook at all — measured,
+     * not assumed — so a row naming a skill is itself proof that THIS SESSION resolved THAT skill.
+     * That is the one question a file-existence check cannot answer, and `verify dispatch` answers
+     * it by reading these rows. Without the name here, the evidence exists and is unattributable.
+     *
+     * @param {string} reason - Why no receipt was written.
+     * @param {string} [rule] - Which defer condition matched.
+     * @returns {never} Does not return — settles the hook.
+     */
+    const defer = (reason, rule) => settle({
+      verdict: "allow", event: "PostToolUse", tool: p?.tool_name ?? null, cwd: p?.cwd, reason, rule,
+      subject: p?.tool_input?.skill ?? null,
+    });
+    const raw = await readStdin();
+    let p;
+    try { p = JSON.parse(raw || "{}"); }
+    catch (e) { settle({ verdict: "error", event: "PostToolUse", reason: `unparseable payload: ${e.message}` }); }
+
+    if (p.tool_name !== "Skill" && p.tool_name !== "Agent") {
+      defer(`${p.tool_name ?? "no tool_name"} is not a dispatch tool — out of scope`, "not-a-dispatch");
+    }
+    const cited = orderPathFrom(p.tool_input);
+    if (!cited) defer("no --order threaded — not an orchestrated dispatch", "no-order");
+
+    const skillInvoked = skillInvokedFrom(p.tool_response);
+    if (!skillInvoked) {
+      // The `Agent` case, and any host result that does not name what ran. Attesting here would
+      // mint the fact rather than record it.
+      defer("dispatch result names no resolved skill — nothing to attest", "no-skill-named");
+    }
+
+    const cwd = p.cwd || process.cwd();
+    const orderPath = resolve(cwd, cited);
+    let order;
+    try { order = JSON.parse(readFileSync(orderPath, "utf8")); }
+    catch (e) { defer(`order not readable (${e.message}) — cannot attest a dispatch it cannot identify`, "order-unreadable"); }
+    if (!order?.order_id) defer("order carries no order_id — nothing to key a receipt by", "order-unkeyed");
+
+    const row = receiptRow(order, skillInvoked, p);
+    const written = writeReceipt(row, cwd);
+    return {
+      verdict: "allow", event: "PostToolUse", tool: p.tool_name, cwd, subject: row.order_id,
+      rule: written ? "receipt-written" : "receipt-write-failed",
+      reason: written
+        ? `dispatch receipt: ${row.order_id} ran ${skillInvoked} (declared ${row.worker_declared}, ok=${row.dispatch_ok})`
+        : `dispatch receipt could not be written for ${row.order_id} — ingest will refuse this result unless --no-receipt-check`,
+    };
+  });
+}
+
+if (isMain(import.meta.url)) main();

package/hooks/gate-intake.mjs

@@ -17,7 +17,7 @@
 // was living in a prompt, and a prompt is exactly what gets dropped on a hand-off. So it becomes a
 // hook, like GATE L2.
 //
-// Design mirrors gate-l2.mjs deliberately:
+// Design mirrors the GATE L2 block deliberately:
 //   • Scope — only `Skill` → tech-lead. Anything else defers instantly.
 //   • Fail-CLOSED only on a provably empty intake, with an actionable re-invocation in the reason.
 //   • Fail-OPEN on anything ambiguous (unparseable payload, unknown arg shape, an envelope
@@ -55,7 +55,7 @@ const args = String(p.tool_input?.skill_args ?? p.tool_input?.args ?? "");
 const skill = String(skillRaw).split(":").pop();
 if (skill !== "tech-lead") defer(`Skill(${skill}) is not the orchestrator — out of scope`);
 
-// The envelope port supplies its own intake; validate-envelope.mjs owns that path.
+// The envelope port supplies its own intake; `harness verify envelope` owns that path.
 if (/--order\b/.test(args)) defer("envelope dispatch — validate-envelope owns this path", "--order");
 
 // Intake is satisfied by ANY of: a pitch path, a spec folder, or free requirement text.
@@ -73,7 +73,7 @@ const hasResume = /--from\s+\S/.test(args); // resuming an existing run has its
 // the spec.
 // Adding a valued flag anywhere in the harness means adding it here, and structural test §39
 // enforces exactly that against commands/ship.md.
-const VALUED_FLAGS = /--(pitch|spec|from|lens|rounds|attempts|orch-model|exec-model|eval-model|qa-model|feature|task|gate-answers|wall-clock-budget|slug|auto-level|max-rounds|intake-file|intake-text|spec-folder|cwd|out|by|preset|file|order)\s+\S+/g;
+const VALUED_FLAGS = /--(pitch|spec|from|lens|rounds|attempts|parallel-scopes|orch-model|exec-model|eval-model|qa-model|feature|task|gate-answers|wall-clock-budget|slug|auto-level|max-rounds|intake-file|intake-text|spec-folder|cwd|out|by|preset|file|order)\s+\S+/g;
 const BARE_FLAGS = /--[a-z0-9-]+/g;
 const freeText = args.replace(VALUED_FLAGS, " ").replace(BARE_FLAGS, " ").trim();
 

package/hooks/gate-zerowork.mjs

@@ -13,7 +13,7 @@
 // That is the "agent claims done" pathology this project exists to prevent, reproduced by the
 // project, at its own front door.
 //
-// THE TWO STRUCTURAL MISSES IT EXPOSED. `anti-rationalization.mjs` is the guard for exactly
+// THE TWO STRUCTURAL MISSES IT EXPOSED. the ship report's census is the guard for exactly
 // this class of failure, and it could not see this one for two independent reasons:
 //
 //   1. SCOPE. It defers unless a run is active (`activeSlug()` → `.shapeup/<slug>/`).
@@ -29,10 +29,10 @@
 //
 //     the session dispatched the orchestrator   AND   the run left no receipt
 //
-// `init-run.mjs` writes that receipt as the orchestrator's first tool call. Its absence is the
+// ``harness init run`` writes that receipt as the orchestrator's first tool call. Its absence is the
 // fact. Nothing here parses intent, so nothing here can be talked past.
 //
-// WHY THIS ONE BLOCKS, WHEN anti-rationalization DOES NOT. The invariant is "QA is a level-up,
+// WHY THIS ONE BLOCKS, WHEN the ship report's census DOES NOT. The invariant is "QA is a level-up,
 // not a gate" — no second judge behind `spec-evaluator`. That governs quality JUDGMENTS. This
 // hook makes no judgment: it reports that no work exists to judge. Blocking is also uniquely
 // safe here, because a session with no artifacts has nothing to lose by continuing, and a
@@ -55,8 +55,8 @@
 
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
-import { localDir, globLocal } from "../skills/tech-lead/scripts/lib/paths.mjs";
+import { isMain } from "../kernel/lib/argv.mjs";
+import { localDir, globLocal } from "../kernel/lib/paths.mjs";
 import { runHook, readStdin, settle, decisionsPath } from "./lib/decision.mjs";
 
 const MAX_TRANSCRIPT_BYTES = 20 * 1024 * 1024;
@@ -74,11 +74,11 @@ const WORK_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit", "Bash"
 /**
  * Is this block a launch of the orchestrator's own workflow script, by either surface?
  *
- * TWO SURFACES, ONE INVARIANT. `Workflow({scriptPath})` is the tool form. The shipped
- * front door is a Bash call — `node "…/scripts/run-workflow.mjs" "…/workflows/shapeup-run.js"` —
- * because the tool form cannot be granted and is denied in every headless session. A gate that
- * knew only the tool form would go blind on the lane users actually run, which is the same
- * "the emptier the failure, the less of it there is to detect" hole the banner above describes.
+ * The shipped front door is `Workflow({scriptPath})`; `npx shapeup-sdlc init` writes the grant it
+ * needs. The Bash arm below is kept because a project that declined that grant, or one still on a
+ * v1 install, launches the same script through a Bash runtime — a gate that knew only one surface
+ * would go blind on the lane those users actually run, which is the same "the emptier the failure,
+ * the less of it there is to detect" hole the banner above describes.
  *
  * Matched on the BASENAME, anchored. `CLAUDE_PLUGIN_ROOT` itself ends in `shapeup-sdlc-plugin/` on
  * a normal install — so a substring match on the whole path would count EVERY workflow script that
@@ -91,10 +91,10 @@ const WORK_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit", "Bash"
 function launchedShapeupWorkflow(block) {
   if (block.name === "Bash") {
     const cmd = String(block.input?.command ?? "");
-    // Both halves required: the launcher AND an orchestrator script. `run-workflow.mjs` carrying
+    // Both halves required: a node launcher AND an orchestrator script. A launcher carrying
     // somebody else's workflow is not a harness dispatch, and neither is a bare mention of the
     // script in an unrelated command (`ls`, `cat`).
-    return /\brun-workflow\.mjs\b/.test(cmd) && /[\\/]shapeup-[\w.-]*\.[cm]?js\b/.test(cmd);
+    return /\bnode\b/.test(cmd) && /[\\/]shapeup-[\w.-]*\.[cm]?js\b/.test(cmd);
   }
   if (block.name !== "Workflow") return false;
   const scriptPath = String(block.input?.scriptPath ?? "");
@@ -161,7 +161,7 @@ export function workCensus(events) {
   return census;
 }
 
-/** Any run receipt on disk, from any run. Written by init-run.mjs as the run's first act. */
+/** Any run receipt on disk, from any run. Written by `harness init run` as the run's first act. */
 export function findReceipts(cwd) {
   const root = localDir(cwd);
   if (!existsSync(root)) return [];
@@ -236,7 +236,7 @@ export function buildReason({ narration, census, enforcement }) {
       : null,
     enforcement && enforcement.readable && enforcement.rows === 0
       ? "AND the enforcement layer left zero decision rows — the gates did not merely permit this run, they never ran. " +
-        "Check the plugin install — a symlinked or spaced path is the usual cause; see lib/is-main.mjs."
+        "Check the plugin install — a symlinked path or a path with a space is the usual cause."
       : null,
     "",
     "A run that describes its own pipeline and stops is the exact failure this harness exists to",
@@ -247,20 +247,21 @@ export function buildReason({ narration, census, enforcement }) {
     "",
     "  # write the requirement to a file first — inlining multi-line text into a shell",
     "  # argument is where this step goes wrong",
-    "  node \"${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/init-run.mjs\" \\",
+    "  node \"${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs\" init run \\",
     "       --slug <slug> --intake-file <path/to/requirement.md> \\",
     "       --auto-level <interactive|auto|unattended> [--gate-answers <preset|path>]",
     "",
-    "Then launch the lane itself — a BACKGROUND Bash call, never the `Workflow` tool, which cannot be",
-    "granted and is denied outright in a headless session:",
+    "Then launch the lane itself with the Workflow tool (`npx shapeup-sdlc init` writes the grant",
+    "it needs, unless --no-native-workflow was given, in which case approve the launch once):",
     "",
-    "  node \"${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/run-workflow.mjs\" \\",
-    "       \"${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js\" \\",
-    "       --args-file <.shapeup/<slug>/run-args.json> --run-dir <.shapeup/<slug>/workflow-run>",
+    "  Workflow({",
+    "    scriptPath: \"${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js\",",
+    "    args: <the RunArgs object>",
+    "  })",
     "",
     "Resolve each gate the run pauses at with:",
     "",
-    "  node \"${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/gate-answers.mjs\" --resolve <gate-id> …",
+    "  node \"${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs\" gate --resolve <gate-id> …",
     "",
     "If the command comes back \"requires approval\", say so and stop — the harness's scripts ship with",
     "the plugin and need a one-time permission grant (`npx shapeup-sdlc init` writes it). Do NOT route",
@@ -294,7 +295,7 @@ async function main() {
   // not a harness session → not our business
   if (!dispatchedOrchestrator(events)) defer("session never dispatched the orchestrator — not a harness run", "no-dispatch");
 
-  // A receipt means the run started. What happens after that is anti-rationalization's job and
+  // A receipt means the run started. What happens after that is the ship report's census's job and
   // the evaluator's; this hook only asks whether anything started at all.
   const receipts = findReceipts(cwd);
   if (receipts.length > 0) defer(`${receipts.length} run receipt(s) on disk — the run started`, "receipt-present");
@@ -315,9 +316,9 @@ async function main() {
   // was from the gate watching for exactly that.
   //
   // BOTH HALVES OF THE RATIONALE FAIL ON INSPECTION. Running the harness steps by hand starts with
-  // `init-run.mjs`, which writes the receipt — such a session already deferred at `receipt-present`
+  // ``harness init run``, which writes the receipt — such a session already deferred at `receipt-present`
   // two lines up and never reached here. And a pre-receipt plugin cannot be the one executing this
-  // hook: `init-run.mjs` ships in the same install, beside the `lib/` this file imports from.
+  // hook: ``harness init run`` ships in the same install, beside the `lib/` this file imports from.
   // Neither case needs an escape, so no replacement escape is added — an escape that cannot fire
   // is the "row that cannot fail" this project keeps catching.
   //

package/hooks/hooks.json

@@ -8,27 +8,6 @@
             "command": "echo \"shapeup-sdlc-plugin loaded from ${CLAUDE_PLUGIN_ROOT}\""
           }
         ]
-      },
-      {
-        "matcher": "startup|compact|resume|clear",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-rehydrate.mjs\"",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
-    "PreCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/compact-snapshot.mjs\"",
-            "timeout": 10
-          }
-        ]
       }
     ],
     "PreToolUse": [
@@ -42,16 +21,6 @@
           }
         ]
       },
-      {
-        "matcher": "Skill",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gate-l2.mjs\"",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "Skill",
         "hooks": [
@@ -63,31 +32,33 @@
         ]
       },
       {
-        "matcher": "Skill",
+        "matcher": "Skill|Agent",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gate-deadline.mjs\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs\" verify envelope",
             "timeout": 10
           }
         ]
       },
       {
-        "matcher": "Skill|Agent",
+        "matcher": "Edit|Write|MultiEdit",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/validate-envelope.mjs\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-guard.mjs\"",
             "timeout": 10
           }
         ]
-      },
+      }
+    ],
+    "PostToolUse": [
       {
-        "matcher": "Edit|Write|MultiEdit",
+        "matcher": "Skill|Agent",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-guard.mjs\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/dispatch-receipt.mjs\"",
             "timeout": 10
           }
         ]
@@ -100,16 +71,6 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gate-zerowork.mjs\"",
             "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/anti-rationalization.mjs\"",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/slop-cleaner.mjs\"",
-            "timeout": 15
           }
         ]
       }

package/hooks/lib/decision.mjs

@@ -6,13 +6,11 @@
 // 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 an inert
@@ -20,8 +18,8 @@
 // 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. The structural suite calls its helper `spoke()`
@@ -38,7 +36,7 @@
 // committed metrics shard, which `stats --hooks` aggregates into.
 //
 // THE PATH IS RESOLVED, NEVER SPELLED. It comes from `lib/paths.mjs` — the same resolver
-// `stats.mjs --hooks` reads through. This file used to hardcode the pre-ADR-0001 root, so every
+// ``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
@@ -50,7 +48,8 @@
 
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { decisions } from "../../skills/tech-lead/scripts/lib/paths.mjs";
+import { decisions } from "../../kernel/lib/paths.mjs";
+import { resolveRunId } from "../../kernel/lib/paths.mjs";
 
 /**
  * Where the receipts land.
@@ -168,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,
@@ -176,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

@@ -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";