shapeup-sdlc 3.18.2 → 4.0.0

package/hooks/hooks.json

@@ -1,15 +1,5 @@
 {
   "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "echo \"shapeup-sdlc-plugin loaded from ${CLAUDE_PLUGIN_ROOT}\""
-          }
-        ]
-      }
-    ],
     "PreToolUse": [
       {
         "matcher": "Bash|Read|Write|Edit|MultiEdit",
@@ -21,16 +11,6 @@
           }
         ]
       },
-      {
-        "matcher": "Skill",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gate-intake.mjs\"",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "Skill|Agent",
         "hooks": [
@@ -50,16 +30,6 @@
             "timeout": 10
           }
         ]
-      },
-      {
-        "matcher": "Edit|Write|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/tier-guard.mjs\"",
-            "timeout": 10
-          }
-        ]
       }
     ],
     "PostToolUse": [
@@ -73,17 +43,6 @@
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gate-zerowork.mjs\"",
-            "timeout": 10
-          }
-        ]
-      }
     ]
   }
 }

package/hooks/lib/decision.mjs

@@ -6,10 +6,8 @@
 // input, every gate in this repo answered the same way:
 //
 //     $ echo 'NOT JSON AT ALL {{{' | node hooks/<gate>.mjs
-//     gate-zerowork      exit=0   stdout_len=0
 //     sandbox-guard      exit=0   stdout_len=0
 //     safety-spine       exit=0   stdout_len=0
-//     gate-intake        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,
@@ -32,13 +30,12 @@
 // 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.
+// frequently no `<slug>` to file under. Pure run-trace: one JSON object per line, read directly.
 //
 // 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
+// every reader goes through. This file used to hardcode the earlier 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 ledger showed 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.
 //
@@ -97,7 +94,7 @@ export function projectRoot(cwd) {
  *
  * `SHAPEUP_DECISIONS_PATH` redirects the ledger. It exists because this project's OWN test suite
  * executes the real hooks, and without a redirect every `npm test` appended ~21 rows to the
- * developer's live `decisions.jsonl` — which would then be read back by `stats --hooks` as if
+ * developer's live `decisions.jsonl` — which would then be read back as if
  * they were evaluations from a real run. A measurement instrument that its own test suite
  * contaminates is not an instrument.
  *
@@ -241,11 +238,11 @@ export async function runHook(name, fn) {
   // 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
+  // WHY `warn` IS ITS OWN VERDICT. An advisory gate permits the call, so the obvious
   // encoding is `verdict: "allow"`. That would make "permitted because the rule was satisfied"
   // byte-identical to "permitted DESPITE the rule being broken" — the exact indistinguishability
   // this file exists to eliminate, reintroduced one level up. A gate that downgrades from deny to
-  // advisory must stay countable, or `stats --hooks` silently loses the measurement.
+  // advisory must stay countable, or the ledger silently loses the measurement.
   if (d.payload && (d.verdict === "deny" || d.verdict === "block" || d.verdict === "warn" || d.emit)) {
     process.stdout.write(JSON.stringify(d.payload));
   }

package/hooks/lib/tier.mjs

@@ -0,0 +1,50 @@
+// The tier-direction rule, on a string: a committed file cannot carry a reference that only resolves
+// on the machine that wrote it. Two forms — a board id (`TASK-NNN`, renumbered per machine) and a path
+// into the gitignored run tier. The substrate fence calls this at the moment a tool writes the text,
+// while the writer still holds the context to rephrase it.
+
+import { LOCAL } from "../../kernel/lib/paths.mjs";
+
+/** Text forms worth scanning; anything else in a committed tree is not a reference carrier. */
+export const SCANNED = /\.(md|markdown|yml|yaml|json|txt)$/i;
+
+/** A machine-local board id. Strict on purpose: a committed tree has no reason to carry one at all. */
+const TASK_ID = /\bTASK-[A-Za-z0-9][\w.-]*/;
+
+/**
+ * The tier-direction violations one piece of text carries — the whole rule, on a string.
+ *
+ * The detail strings are the message the writer reads, so they carry the remedy, not just the
+ * verdict: a board id resolves on the machine that wrote it and nowhere else, and a path into the
+ * gitignored tier dangles on every clone.
+ *
+ * @param {string} text - The file body, or the fragment a tool is about to write.
+ * @returns {Array<{kind:("board-id"|"local-path"), token:string, line:number, detail:string}>}
+ *   One entry per offending line and form, in file order; [] when clean.
+ */
+export function tierLeaks(text) {
+  // Built from the LOCAL constant, never a literal — the storage roots have exactly one home.
+  const esc = LOCAL.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // `\S+` where the walk's own rule is `\S`: the same LINES match either way (a path with one
+  // non-space character after the slash has at least one), and the longer form yields the token to
+  // quote back at the writer. Trailing punctuation the prose wrapped it in is trimmed off the
+  // quote only — never off the test.
+  const localPath = new RegExp(`${esc}/\\S+`);
+  const leaks = [];
+  String(text ?? "").split(/\r?\n/).forEach((line, i) => {
+    const task = line.match(TASK_ID);
+    if (task) {
+      leaks.push({ kind: "board-id", token: task[0], line: i + 1, detail:
+        `names ${task[0]} — a committed file cannot carry a board id. Boards live in ${LOCAL}/ ` +
+        "(gitignored) and renumber on every regeneration, so this resolves on the machine that wrote it " +
+        "and nowhere else. Cite the use case or the scope_id, which are stable." });
+    }
+    const path = line.match(localPath);
+    if (path) {
+      leaks.push({ kind: "local-path", token: path[0].replace(/[`)\]},.;:'"]+$/, ""), line: i + 1, detail:
+        `points into ${LOCAL}/ — a committed file cannot reference the gitignored tier; the path ` +
+        "dangles on every other clone. Name the committed artifact, or describe the tier without a path." });
+    }
+  });
+  return leaks;
+}

package/hooks/sandbox-guard.mjs

@@ -1,68 +1,50 @@
 #!/usr/bin/env node
-// Sandbox guard — PreToolUse hook (the PA3 countermeasure: writes outside the order's substrate).
+// Sandbox guard — PreToolUse hook: writes outside the live order's substrate are refused.
 //
 // 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.
+// It also refuses, at the write, a committed-tier file whose text names a run-trace path or a board id
+// (`committedTierLeaks` below) — the tier-direction rule, asked where the writer can still rephrase.
 //
-// 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 ENFORCES THE ORDER, NOT THE SCOPE CONTRACT. The loop stamps a write contract onto every order
+// it writes — allowed, shared, append_only, frozen, own — and reading the order makes that contract
+// and the one this hook enforces the same object, for every operation, with no per-operation code
+// here. Resolving the scope contract instead would cover only the build, because only build orders
+// carry a scope.
 //
-// IT READS EVERY LIVE ORDER, NOT A POINTER TO ONE. `.shapeup/active-order` names the run and
-// nothing more — `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`).
-// A single pointer cannot survive concurrency: with scopes building side by side the last compile
-// wins the pointer, and a write from scope A would be 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/` that is not yet ANSWERED, and a write is permitted when SOME live contract
-// covers it.
+// IT READS EVERY LIVE ORDER, NOT A POINTER TO ONE. `.shapeup/active-order` names the run and nothing
+// more; the loop sets it with `harness order open` and `harness order close` retires it. A single
+// pointer cannot survive concurrency: with scopes building side by side the last order opened wins
+// it, and a write from scope A would be 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/`
+// that is not yet ANSWERED, and a write is permitted when SOME live contract covers it.
 //
-// THE POINTER IS NOT A LIVENESS SIGNAL, and it used to be one: the order it names was counted live
-// unconditionally, "so the single-order lane behaves as it did before concurrency existed". The arm
-// bought nothing — an order that is genuinely in flight has no result yet and is already live by
-// the rule below — and it cost the checkout permanently. The pointer has one writer and no eraser,
-// so the LAST dispatch of a FINISHED run stayed live for good and fenced everything to that one
-// substrate: after a ship, an ordinary edit anywhere in the repo was denied, and the next feature
-// could not write even its own run trace, because the carve-out below is keyed to the slug the
-// stale pointer names. The documented fail-open state ("no pointer — not inside a dispatch") became
-// unreachable after the first run, and the only way out was to delete a file nothing documents.
-// The arm is gone; `reduce ship` and ``harness init run --force`` retire the pointer as well, so a
-// leftover one is untidy rather than load-bearing.
+// THE POINTER IS NOT A LIVENESS SIGNAL. It arms the fence — with no pointer every write is allowed —
+// but liveness is "written, no result yet", read off the order set, so a run that ended and retired
+// its pointer fences nothing and a leftover pointer is untidy rather than load-bearing.
 //
-// ANSWERED IS A COMPARISON, NOT A PRESENCE TEST, and the difference is a hole the removal above
-// would otherwise open. Order filenames for the run-level operations carry no round (`hammer.json`,
-// `wire.json`, `analyze.json`), so re-dispatching one inside the same run rewrites the order beside
-// the PREVIOUS dispatch's result — and a presence test reads that as finished and runs the new
-// dispatch unfenced. An order counts as answered only when its result file is at least as new as
-// the order's own `compiled_at`, the stamp the compiler writes INTO the order, which a copy or a
-// touch cannot perturb. An order carrying no stamp falls back to presence, which is all it ever had.
+// ANSWERED IS A COMPARISON, NOT A PRESENCE TEST. Order filenames for the run-level operations carry
+// no round, so re-dispatching one inside the same run rewrites the order beside the PREVIOUS
+// dispatch's result — and a presence test would read that as finished and run the new dispatch
+// unfenced. An order counts as answered only when its result file is at least as new as the order's
+// own `compiled_at`, the stamp the loop writes INTO the order, which a copy or a touch cannot
+// perturb. An order carrying no stamp falls back to presence.
 //
-// A RUN-LEVEL ORDER RETIRES AT ITS PHASE BOUNDARY, which is the other half of that same question.
-// Liveness is "compiled, no result yet", so a PHASE dispatch whose worker never returned — a killed
-// evaluation, a QA leg that escalated without a result, a failed scope mapping — would stay live for
-// the rest of the run, and everything its `frozen` list names (the board, the spec tree) would be
-// fenced from then on. The board is the one that bites: the next round's doer cannot tick its own
-// acceptance criteria, and the run wedges with no dispatch actually in flight. The orchestrator has
-// long since moved on by the time that matters, and the move itself is the signal: the next phase
-// compiles its own order. So an order for a RUN-LEVEL operation stops being live once an order for a
-// DIFFERENT operation has been compiled after it — the window the committed tier already has, a
-// phase boundary rather than the middle of somebody else's dispatch. Build legs are exempt: they run
-// concurrently, finish out of order, and an abandoned one is resolved by ``harness init run --force``
-// rather than by a sibling's compile stamp. Two concurrent legs of the SAME operation never retire
-// each other, for that same reason. An order carrying no operation or no `compiled_at` keeps
+// A RUN-LEVEL ORDER RETIRES AT ITS PHASE BOUNDARY. A phase dispatch whose worker never returned — a
+// killed evaluation, a QA leg that escalated without a result — would otherwise stay live for the rest
+// of the run and fence everything its `frozen` list names. The next phase writing its own order is
+// the signal: an order for a RUN-LEVEL operation stops being live once an order for a DIFFERENT
+// operation has been written after it. Build legs are exempt: they run concurrently, finish out of
+// order, and an abandoned one is resolved by `harness init run --force`. Two concurrent legs of the
+// SAME operation never retire each other. An order carrying no operation or no `compiled_at` keeps
 // fencing — an unreadable claim is not a retired one.
 //
-// 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.
+// "The writer's own contract" and "some live contract" are the same question because scope
+// substrates are disjoint by construction: the loop reads the contracts for overlap before it
+// releases scopes together. `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):
+// Design (deliberately conservative):
 //   • 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
@@ -72,14 +54,11 @@
 //     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 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.
+//     (`.shapeup/<slug>/`) are allowed unless a live order freezes them: that root is bookkeeping
+//     the doer is REQUIRED to write. 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 }.
@@ -90,6 +69,7 @@ import { resolve, join, relative, dirname, basename, sep } from "node:path";
 import { isMain } from "../kernel/lib/argv.mjs";
 import { LOCAL, SHARED, activeOrder, ordersDir, resultsDir, metricsShard, dispatchReceipts } from "../kernel/lib/paths.mjs";
 import { runHook, readStdin, settle, projectRoot } from "./lib/decision.mjs";
+import { SCANNED, tierLeaks } from "./lib/tier.mjs";
 
 // --- tiny glob matcher: supports *, **, ? — enough for substrate globs, zero dependencies ---
 export function globToRegExp(glob) {
@@ -313,6 +293,77 @@ export function logPathology(metricsPath, event) {
   } catch { /* telemetry is best-effort; never block on a logging failure */ }
 }
 
+/** Committed-tier trees that hold instructions rather than references — outside the lint's walk. */
+const NOT_A_SLUG = new Set(["knowledge-base"]);
+
+/**
+ * The (path, content) pairs one write tool call is about to commit to disk.
+ *
+ * THE THREE WRITE TOOLS SPELL CONTENT THREE WAYS, and a check that reads only `content` is blind to
+ * the Edit that adds the same line — which is the form the measured recurrence took, since the file
+ * already existed by then.
+ *
+ * @param {object} toolInput - The PreToolUse `tool_input` block.
+ * @returns {Array<{path:string, content:string}>} Pairs with a usable path and string content.
+ */
+export function extractWrites(toolInput) {
+  const out = [];
+  const base = toolInput?.file_path;
+  if (typeof toolInput?.content === "string" && base) out.push({ path: base, content: toolInput.content });
+  if (typeof toolInput?.new_string === "string" && base) out.push({ path: base, content: toolInput.new_string });
+  if (Array.isArray(toolInput?.edits)) {
+    for (const e of toolInput.edits) {
+      const p = e?.file_path || base;
+      if (p && typeof e?.new_string === "string") out.push({ path: p, content: e.new_string });
+    }
+  }
+  return out;
+}
+
+/**
+ * Is this path inside the committed tier the lint walks — `shapeup/<slug>/…`, scanned form?
+ *
+ * @param {string} rel - Path relative to the project root, as the lint would name it.
+ * @returns {boolean} True when a leak here is a leak the lint would red.
+ */
+export function inCommittedTier(rel) {
+  if (!rel || rel.startsWith("..") || rel.startsWith(sep)) return false;
+  const parts = rel.split(/[\\/]/);
+  // `shapeup/<slug>/<file>` — the lint walks a slug's tree, so a file at the tier root belongs to
+  // no run and is left alone, and `knowledge-base` is a sibling of the slugs, not one of them.
+  if (parts[0] !== SHARED || parts.length < 3 || NOT_A_SLUG.has(parts[1])) return false;
+  return SCANNED.test(rel);
+}
+
+/**
+ * The committed tier's write boundary: the tier-direction leaks this call would commit.
+ *
+ * It is the tier-direction rule, asked at the write — the one
+ * moment the writer still knows what it meant to say, because a worker carries no lesson across a
+ * dispatch and the lint reds the same file a phase later. The predicate is the lint's own scanner
+ * (`tierLeaks`), imported and never restated, so this cannot become narrower or wider than the rule.
+ * `shapeup/knowledge-base/` is outside, exactly as it is outside the lint's walk. Fail-OPEN on
+ * everything it cannot positively prove: no path, no content, a path outside `shapeup/<slug>/`, a
+ * file form the lint does not scan.
+ *
+ * @param {object} toolInput - The PreToolUse `tool_input` block.
+ * @param {string} cwd - The shell's working directory, against which a raw tool path resolves.
+ * @param {string} root - The project root the committed tier lives under.
+ * @returns {{rel:string, blocked:string[]}} The first in-tier path and one line per leak; `blocked`
+ *   is empty when the write carries none.
+ */
+export function committedTierLeaks(toolInput, cwd, root) {
+  const inTier = extractWrites(toolInput)
+    .map((w) => ({ ...w, rel: relative(root, resolve(cwd, w.path)) }))
+    .filter((w) => inCommittedTier(w.rel));
+  const blocked = [];
+  // THE TOKEN IS QUOTED BACK, which the lint's own message does not need to do — it reports against a
+  // file on disk the reader can open at that line. Here the line does not exist yet, so naming the
+  // exact string is the difference between a denial that is acted on and one that is retried verbatim.
+  for (const w of inTier) for (const leak of tierLeaks(w.content)) blocked.push(`${w.rel}:${leak.line} — \`${leak.token}\` ${leak.detail}`);
+  return { rel: inTier[0]?.rel ?? "", blocked };
+}
+
 async function main() {
   await runHook("sandbox-guard", async () => {
   const raw = await readStdin();
@@ -336,6 +387,31 @@ async function main() {
   // the shell's own cwd, because that is what a relative path in the tool input means.
   const cwd = p.cwd || process.cwd();
   const root = projectRoot(cwd);
+
+  // THE COMMITTED TIER FIRST, and before every "no live order" exit below: the tier-direction rule
+  // holds with no run in flight, and a write that is clean here falls through to the substrate fence.
+  const tier = committedTierLeaks(p.tool_input, cwd, root);
+  if (tier.blocked.length) {
+    return {
+      verdict: "deny", event: "PreToolUse", tool: p.tool_name, subject: tier.rel, cwd: root,
+      rule: "tier-direction",
+      reason: `${tier.blocked.length} tier-direction leak(s) refused at the write boundary: ${tier.blocked.join("; ")}`,
+      payload: {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason:
+            "Tier guard (TIER-DIRECTION) — this write would put a reference into the committed tier that " +
+            "cannot survive the trip to another machine:\n" +
+            `${tier.blocked.join("\n")}\n` +
+            "Refused here, while the writer still knows what it meant to say. " +
+            "Rephrase the line now: cite the committed artifact, the use case or the scope_id, or describe " +
+            "the tier without naming a path.",
+        },
+      },
+    };
+  }
+
   const activeOrderPath = activeOrder(root);
   if (!existsSync(activeOrderPath)) defer("no active-order pointer — no tracked task running", "no-round");
 
@@ -343,9 +419,9 @@ async function main() {
   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
+  // CONCURRENTLY the last order opened 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
+  // fell. Scope substrates are disjoint by construction (the loop's planning read-back 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.
@@ -364,7 +440,7 @@ async function main() {
     allowed: [...(o.substrate.allowed || []), ...(o.substrate.shared || [])],
     appendOnly: o.substrate.append_only || [],
     frozen: o.substrate.frozen || [],
-    // The one exception to "frozen outranks everything", and it is the compiler's to grant, never
+    // The one exception to "frozen outranks everything", and it is the loop's to grant, never
     // the worker's to request: the paths THIS order authors, named from its own identity. A build
     // leg's substrate freezes the whole run trace, so without this its own WorkResult — its
     // documented last step — would be denied along with every channel it must not touch.