@praxisflux/gates 0.21.0 → 0.22.0

package/codebase-to-course/lib/gate-runner.mjs

@@ -5,13 +5,16 @@
 // "run every applicable gate" happens naturally across plugins; within one plugin the runner
 // runs that plugin's gates additively over every root they resolve.
 //
-// A gate is: { name, resolveRoots(startDir) -> string[], check(root) -> string[] (problems),
-//             warn?(root) -> string[] (non-blocking notices) }.
+// A gate is: { name, resolveRoots(startDir, ctx) -> string[], check(root, ctx) -> string[]
+//             (problems), warn?(root, ctx) -> string[] (non-blocking notices) }.
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
+// falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
+// to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
 //
-// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, cwd, … };
+// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
@@ -32,17 +35,21 @@ export function readStdin() {
 export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
   const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const ctx = {
+    sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
+    input: input || {},
+  };
   const problems = [];
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
     for (const root of roots) {
-      try { problems.push(...(gate.check(root) || [])); } catch (e) {
+      try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);
       }
       if (typeof gate.warn === "function") {
-        try { warnings.push(...(gate.warn(root) || [])); } catch { /* warnings are best-effort */ }
+        try { warnings.push(...(gate.warn(root, ctx) || [])); } catch { /* warnings are best-effort */ }
       }
     }
   }
@@ -52,12 +59,17 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
 /**
  * Full harness: read stdin, evaluate the gates, exit 0 (allow) or 2 (block, message on stderr).
  * Blocking problems win; otherwise any non-blocking warnings are written to stderr and we still
- * allow the stop (exit 0).
+ * allow the stop (exit 0). Optional `before(input)` runs after parsing and before the gates —
+ * the hook point for a plugin's own writer to do session-owned upkeep (e.g. heartbeat a run
+ * record); it is best-effort and never blocks the stop.
  */
-export async function runStopHook({ gates, exit = process.exit } = {}) {
+export async function runStopHook({ gates, before, exit = process.exit } = {}) {
   const raw = await readStdin();
   let input = {};
   try { input = JSON.parse(raw || "{}"); } catch { input = {}; }
+  if (typeof before === "function") {
+    try { await before(input); } catch { /* upkeep is best-effort */ }
+  }
   const { block, message, warnings } = evaluate(input, gates);
   if (block) {
     process.stderr.write([message, warnings].filter(Boolean).join("\n") + "\n");

package/grounding-wiki/lib/gate-runner.mjs

@@ -5,13 +5,16 @@
 // "run every applicable gate" happens naturally across plugins; within one plugin the runner
 // runs that plugin's gates additively over every root they resolve.
 //
-// A gate is: { name, resolveRoots(startDir) -> string[], check(root) -> string[] (problems),
-//             warn?(root) -> string[] (non-blocking notices) }.
+// A gate is: { name, resolveRoots(startDir, ctx) -> string[], check(root, ctx) -> string[]
+//             (problems), warn?(root, ctx) -> string[] (non-blocking notices) }.
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
+// falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
+// to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
 //
-// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, cwd, … };
+// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
@@ -32,17 +35,21 @@ export function readStdin() {
 export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
   const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const ctx = {
+    sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
+    input: input || {},
+  };
   const problems = [];
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
     for (const root of roots) {
-      try { problems.push(...(gate.check(root) || [])); } catch (e) {
+      try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);
       }
       if (typeof gate.warn === "function") {
-        try { warnings.push(...(gate.warn(root) || [])); } catch { /* warnings are best-effort */ }
+        try { warnings.push(...(gate.warn(root, ctx) || [])); } catch { /* warnings are best-effort */ }
       }
     }
   }
@@ -52,12 +59,17 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
 /**
  * Full harness: read stdin, evaluate the gates, exit 0 (allow) or 2 (block, message on stderr).
  * Blocking problems win; otherwise any non-blocking warnings are written to stderr and we still
- * allow the stop (exit 0).
+ * allow the stop (exit 0). Optional `before(input)` runs after parsing and before the gates —
+ * the hook point for a plugin's own writer to do session-owned upkeep (e.g. heartbeat a run
+ * record); it is best-effort and never blocks the stop.
  */
-export async function runStopHook({ gates, exit = process.exit } = {}) {
+export async function runStopHook({ gates, before, exit = process.exit } = {}) {
   const raw = await readStdin();
   let input = {};
   try { input = JSON.parse(raw || "{}"); } catch { input = {}; }
+  if (typeof before === "function") {
+    try { await before(input); } catch { /* upkeep is best-effort */ }
+  }
   const { block, message, warnings } = evaluate(input, gates);
   if (block) {
     process.stderr.write([message, warnings].filter(Boolean).join("\n") + "\n");

package/lib/gate-runner.mjs

@@ -5,13 +5,16 @@
 // "run every applicable gate" happens naturally across plugins; within one plugin the runner
 // runs that plugin's gates additively over every root they resolve.
 //
-// A gate is: { name, resolveRoots(startDir) -> string[], check(root) -> string[] (problems),
-//             warn?(root) -> string[] (non-blocking notices) }.
+// A gate is: { name, resolveRoots(startDir, ctx) -> string[], check(root, ctx) -> string[]
+//             (problems), warn?(root, ctx) -> string[] (non-blocking notices) }.
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
+// falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
+// to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
 //
-// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, cwd, … };
+// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
@@ -32,17 +35,21 @@ export function readStdin() {
 export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
   const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const ctx = {
+    sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
+    input: input || {},
+  };
   const problems = [];
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
     for (const root of roots) {
-      try { problems.push(...(gate.check(root) || [])); } catch (e) {
+      try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);
       }
       if (typeof gate.warn === "function") {
-        try { warnings.push(...(gate.warn(root) || [])); } catch { /* warnings are best-effort */ }
+        try { warnings.push(...(gate.warn(root, ctx) || [])); } catch { /* warnings are best-effort */ }
       }
     }
   }
@@ -52,12 +59,17 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
 /**
  * Full harness: read stdin, evaluate the gates, exit 0 (allow) or 2 (block, message on stderr).
  * Blocking problems win; otherwise any non-blocking warnings are written to stderr and we still
- * allow the stop (exit 0).
+ * allow the stop (exit 0). Optional `before(input)` runs after parsing and before the gates —
+ * the hook point for a plugin's own writer to do session-owned upkeep (e.g. heartbeat a run
+ * record); it is best-effort and never blocks the stop.
  */
-export async function runStopHook({ gates, exit = process.exit } = {}) {
+export async function runStopHook({ gates, before, exit = process.exit } = {}) {
   const raw = await readStdin();
   let input = {};
   try { input = JSON.parse(raw || "{}"); } catch { input = {}; }
+  if (typeof before === "function") {
+    try { await before(input); } catch { /* upkeep is best-effort */ }
+  }
   const { block, message, warnings } = evaluate(input, gates);
   if (block) {
     process.stderr.write([message, warnings].filter(Boolean).join("\n") + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisflux/gates",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "praxisflux gate checks as a zero-dependency CLI (spec-bridge, wiki-freshness, course) — status can't exceed proven artifacts",
   "license": "MIT",
   "repository": {

package/spec-bridge/lib/gate-runner.mjs

@@ -5,13 +5,16 @@
 // "run every applicable gate" happens naturally across plugins; within one plugin the runner
 // runs that plugin's gates additively over every root they resolve.
 //
-// A gate is: { name, resolveRoots(startDir) -> string[], check(root) -> string[] (problems),
-//             warn?(root) -> string[] (non-blocking notices) }.
+// A gate is: { name, resolveRoots(startDir, ctx) -> string[], check(root, ctx) -> string[]
+//             (problems), warn?(root, ctx) -> string[] (non-blocking notices) }.
 // A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
 // block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
 // — for freshness reminders and the like that shouldn't refuse to let the model finish.
+// `ctx` is { sessionId, input }: the invoking session's identity (hook input `session_id`,
+// falling back to $CLAUDE_CODE_SESSION_ID) plus the raw hook input — gates that scope state
+// to its owning session (e.g. reorient run records) key off it; every existing gate ignores it.
 //
-// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, cwd, … };
+// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, session_id, cwd, … };
 // exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
 
 /** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
@@ -32,17 +35,21 @@ export function readStdin() {
 export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
   if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
   const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const ctx = {
+    sessionId: (input && input.session_id) || process.env.CLAUDE_CODE_SESSION_ID || null,
+    input: input || {},
+  };
   const problems = [];
   const warnings = [];
   for (const gate of gates) {
     let roots = [];
-    try { roots = gate.resolveRoots(start) || []; } catch { roots = []; }
+    try { roots = gate.resolveRoots(start, ctx) || []; } catch { roots = []; }
     for (const root of roots) {
-      try { problems.push(...(gate.check(root) || [])); } catch (e) {
+      try { problems.push(...(gate.check(root, ctx) || [])); } catch (e) {
         problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);
       }
       if (typeof gate.warn === "function") {
-        try { warnings.push(...(gate.warn(root) || [])); } catch { /* warnings are best-effort */ }
+        try { warnings.push(...(gate.warn(root, ctx) || [])); } catch { /* warnings are best-effort */ }
       }
     }
   }
@@ -52,12 +59,17 @@ export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
 /**
  * Full harness: read stdin, evaluate the gates, exit 0 (allow) or 2 (block, message on stderr).
  * Blocking problems win; otherwise any non-blocking warnings are written to stderr and we still
- * allow the stop (exit 0).
+ * allow the stop (exit 0). Optional `before(input)` runs after parsing and before the gates —
+ * the hook point for a plugin's own writer to do session-owned upkeep (e.g. heartbeat a run
+ * record); it is best-effort and never blocks the stop.
  */
-export async function runStopHook({ gates, exit = process.exit } = {}) {
+export async function runStopHook({ gates, before, exit = process.exit } = {}) {
   const raw = await readStdin();
   let input = {};
   try { input = JSON.parse(raw || "{}"); } catch { input = {}; }
+  if (typeof before === "function") {
+    try { await before(input); } catch { /* upkeep is best-effort */ }
+  }
   const { block, message, warnings } = evaluate(input, gates);
   if (block) {
     process.stderr.write([message, warnings].filter(Boolean).join("\n") + "\n");