@sienklogic/plan-build-run 2.0.0 → 2.0.1

package/plugins/pbr/scripts/pre-bash-dispatch.js

@@ -1,56 +1,86 @@
-#!/usr/bin/env node
-
-/**
- * PreToolUse dispatcher for Bash hooks.
- *
- * Consolidates check-dangerous-commands.js and validate-commit.js
- * into a single process, reading stdin once and routing to both
- * checks sequentially. This halves the process spawns per Bash call.
- *
- * Check order:
- *   1. Dangerous commands check (can block destructive operations)
- *   2. Commit validation (can block badly-formatted commits)
- *
- * Exit codes:
- *   0 = allowed or warning only
- *   2 = blocked (dangerous command or invalid commit format)
- */
-
-const { logHook } = require('./hook-logger');
-const { checkDangerous } = require('./check-dangerous-commands');
-const { checkCommit } = require('./validate-commit');
-
-function main() {
-  let input = '';
-
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', (chunk) => { input += chunk; });
-  process.stdin.on('end', () => {
-    try {
-      const data = JSON.parse(input);
-
-      // Dangerous commands check first — can block
-      const dangerousResult = checkDangerous(data);
-      if (dangerousResult) {
-        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'check-dangerous-commands' });
-        process.stdout.write(JSON.stringify(dangerousResult.output));
-        process.exit(dangerousResult.exitCode);
-      }
-
-      // Commit validation check — can block
-      const commitResult = checkCommit(data);
-      if (commitResult) {
-        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'validate-commit' });
-        process.stdout.write(JSON.stringify(commitResult.output));
-        process.exit(commitResult.exitCode);
-      }
-
-      process.exit(0);
-    } catch (_e) {
-      // Don't block on errors
-      process.exit(0);
-    }
-  });
-}
-
-if (require.main === module) { main(); }
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Bash hooks.
+ *
+ * Consolidates check-dangerous-commands.js and validate-commit.js
+ * into a single process, reading stdin once and routing to both
+ * checks sequentially. This halves the process spawns per Bash call.
+ *
+ * ── Dispatch Order & Rationale ──────────────────────────────────
+ *
+ *   1. check-dangerous-commands — Blocks destructive shell operations
+ *      (rm -rf, git push --force, etc.). Runs first because safety
+ *      takes priority: if a command is dangerous, we must reject it
+ *      before even considering whether its commit message is valid.
+ *      Can block (exit 2).
+ *
+ *   2. validate-commit          — Enforces conventional commit format
+ *      ({type}({scope}): {desc}) on git commit commands. Runs second
+ *      because commit format validation is only relevant for git
+ *      commit operations, a narrow subset of all Bash calls. There's
+ *      no benefit to checking format if the command was already
+ *      blocked as dangerous. Can block (exit 2).
+ *
+ * ── Short-Circuit Behavior ──────────────────────────────────────
+ *
+ *   If an earlier check returns a result (blocking with exit 2),
+ *   later checks are skipped entirely. The first failure is the
+ *   most relevant — a dangerous command should be blocked regardless
+ *   of whether it also has a valid commit message.
+ *
+ * ── Adding New Checks ───────────────────────────────────────────
+ *
+ *   1. Create a new check module exporting a function that takes
+ *      the parsed hook data and returns null (pass) or
+ *      { output: {...}, exitCode: N }.
+ *   2. require() it at the top of this file.
+ *   3. Add the call in sequence below, following the pattern:
+ *        const result = checkFoo(data);
+ *        if (result) { log; write output; exit with code; }
+ *   4. Position the check based on severity: safety-critical checks
+ *      should run earlier; format/style checks should run later.
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (dangerous command or invalid commit format)
+ */
+
+const { logHook } = require('./hook-logger');
+const { checkDangerous } = require('./check-dangerous-commands');
+const { checkCommit } = require('./validate-commit');
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+
+      // Dangerous commands check first — can block
+      const dangerousResult = checkDangerous(data);
+      if (dangerousResult) {
+        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'check-dangerous-commands' });
+        process.stdout.write(JSON.stringify(dangerousResult.output));
+        process.exit(dangerousResult.exitCode);
+      }
+
+      // Commit validation check — can block
+      const commitResult = checkCommit(data);
+      if (commitResult) {
+        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'validate-commit' });
+        process.stdout.write(JSON.stringify(commitResult.output));
+        process.exit(commitResult.exitCode);
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/pre-write-dispatch.js

@@ -1,62 +1,97 @@
-#!/usr/bin/env node
-
-/**
- * PreToolUse dispatcher for Write|Edit hooks.
- *
- * Consolidates check-skill-workflow.js, check-phase-boundary.js,
- * and check-doc-sprawl.js into a single process, reading stdin once
- * and running all checks sequentially.
- *
- * Check order matters: skill workflow runs first (can block writes
- * that violate planning rules), then phase boundary (can block or
- * warn about cross-phase writes), then doc sprawl (blocks new .md/.txt
- * files outside the allowlist when enabled).
- *
- * Exit codes:
- *   0 = allowed or warning only
- *   2 = blocked (workflow violation or phase boundary enforcement)
- */
-
-const { checkWorkflow } = require('./check-skill-workflow');
-const { checkBoundary } = require('./check-phase-boundary');
-const { checkDocSprawl } = require('./check-doc-sprawl');
-
-function main() {
-  let input = '';
-
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', (chunk) => { input += chunk; });
-  process.stdin.on('end', () => {
-    try {
-      const data = JSON.parse(input);
-
-      // Skill workflow check first — can block
-      const workflowResult = checkWorkflow(data);
-      if (workflowResult) {
-        process.stdout.write(JSON.stringify(workflowResult.output));
-        process.exit(workflowResult.exitCode || 0);
-      }
-
-      // Phase boundary check — can block or warn
-      const boundaryResult = checkBoundary(data);
-      if (boundaryResult) {
-        process.stdout.write(JSON.stringify(boundaryResult.output));
-        process.exit(boundaryResult.exitCode || 0);
-      }
-
-      // Doc sprawl check — blocks new .md/.txt outside allowlist
-      const sprawlResult = checkDocSprawl(data);
-      if (sprawlResult) {
-        process.stdout.write(JSON.stringify(sprawlResult.output));
-        process.exit(sprawlResult.exitCode || 0);
-      }
-
-      process.exit(0);
-    } catch (_e) {
-      // Don't block on errors
-      process.exit(0);
-    }
-  });
-}
-
-if (require.main === module) { main(); }
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Write|Edit hooks.
+ *
+ * Consolidates check-skill-workflow.js, check-phase-boundary.js,
+ * and check-doc-sprawl.js into a single process, reading stdin once
+ * and running all checks sequentially.
+ *
+ * ── Dispatch Order & Rationale ──────────────────────────────────
+ *
+ *   1. check-skill-workflow  — Enforces planning-phase rules (e.g. no
+ *      code writes during the plan phase). Runs first because workflow
+ *      violations are the most fundamental: if the write shouldn't
+ *      happen at all in the current workflow state, there's no point
+ *      evaluating boundary or sprawl rules. Can block (exit 2).
+ *
+ *   2. check-phase-boundary  — Guards against writes that target files
+ *      outside the current phase directory. Runs second because once
+ *      we know the write is allowed by workflow rules, we need to
+ *      verify it's scoped to the correct phase. Can block (exit 2)
+ *      or warn (exit 0 with message).
+ *
+ *   3. check-doc-sprawl      — Prevents creation of new .md/.txt files
+ *      outside a known allowlist (when enabled in config). Runs last
+ *      because it's the most granular check — only relevant for new
+ *      documentation files, not all writes. Can block (exit 2).
+ *
+ * ── Short-Circuit Behavior ──────────────────────────────────────
+ *
+ *   If an earlier check returns a result (blocking or warning with
+ *   output), later checks are skipped entirely. For blocking results
+ *   (exit 2), this means the write is rejected without evaluating
+ *   remaining checks. This is intentional: the first failure is the
+ *   most relevant, and running further checks would be wasteful.
+ *
+ * ── Adding New Checks ───────────────────────────────────────────
+ *
+ *   1. Create a new check module exporting a function that takes
+ *      the parsed hook data and returns null (pass) or
+ *      { output: {...}, exitCode: N }.
+ *   2. require() it at the top of this file.
+ *   3. Add the call in sequence below, following the pattern:
+ *        const result = checkFoo(data);
+ *        if (result) { write output; exit with code; }
+ *   4. Position the check based on severity: more fundamental /
+ *      broader checks should run earlier; narrow / granular checks
+ *      should run later.
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (workflow violation or phase boundary enforcement)
+ */
+
+const { checkWorkflow } = require('./check-skill-workflow');
+const { checkBoundary } = require('./check-phase-boundary');
+const { checkDocSprawl } = require('./check-doc-sprawl');
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+
+      // Skill workflow check first — can block
+      const workflowResult = checkWorkflow(data);
+      if (workflowResult) {
+        process.stdout.write(JSON.stringify(workflowResult.output));
+        process.exit(workflowResult.exitCode || 0);
+      }
+
+      // Phase boundary check — can block or warn
+      const boundaryResult = checkBoundary(data);
+      if (boundaryResult) {
+        process.stdout.write(JSON.stringify(boundaryResult.output));
+        process.exit(boundaryResult.exitCode || 0);
+      }
+
+      // Doc sprawl check — blocks new .md/.txt outside allowlist
+      const sprawlResult = checkDocSprawl(data);
+      if (sprawlResult) {
+        process.stdout.write(JSON.stringify(sprawlResult.output));
+        process.exit(sprawlResult.exitCode || 0);
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) { main(); }