session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/validate/check-agents.mjs

@@ -451,6 +451,62 @@ if (existsSync(agentsDir)) {
   }
 }
 
+// ============================================================================
+// Check 10: PSA-007 git-write ban on repo-write agents (#724).
+//   Every agent that can write the repo (tools list contains an *Edit tool AND
+//   Write) MUST carry the subagent git-write prohibition in its BODY: a
+//   `PSA-007` reference plus the explicit `git stash` ban line. The git index
+//   and stash are shared working-copy resources — a dispatched agent that
+//   stages or stashes races its siblings and can silently discard their
+//   work-in-progress (.claude/rules/parallel-sessions.md § PSA-007).
+//   Structural invariant, so it lives in the gate rather than in a test
+//   (.claude/rules/test-value.md § TV-005). Bug it catches: a NEW repo-write
+//   agent ships with no ban — exactly the docs-writer gap #724 closed.
+//   Agents are discovered dynamically; no hardcoded roster to drift.
+// ============================================================================
+console.log('');
+console.log('--- Check 10: PSA-007 git-write ban (repo-write agents) ---');
+
+if (existsSync(agentsDir)) {
+  const psaMdFiles = readdirSync(agentsDir).filter(isAgentDefFile);
+  let repoWriteCount = 0;
+
+  for (const agentFile of psaMdFiles) {
+    const filePath = join(agentsDir, agentFile);
+    const content = readFileSync(filePath, 'utf8');
+    const fm = extractFrontmatter(content);
+    if (!fm) continue; // already caught by Check 6
+
+    const toolsArray = parseToolsValue(getField(fm, 'tools'));
+    // *Edit covers Edit / MultiEdit / NotebookEdit — all repo-mutating.
+    const canEdit = toolsArray.some((t) => /Edit$/.test(t));
+    if (!canEdit || !toolsArray.includes('Write')) continue;
+
+    repoWriteCount++;
+
+    // Body only: a `description:` that happens to mention PSA-007 must not
+    // satisfy the ban — the instruction has to reach the agent's rules.
+    const body = content.slice(content.indexOf(`\n---`, 3) + 4);
+    const missing = [];
+    if (!body.includes('PSA-007')) missing.push('a PSA-007 reference');
+    if (!body.includes('git stash')) missing.push('the `git stash` ban line');
+
+    if (missing.length > 0) {
+      fail(
+        `${agentFile}: repo-write agent (Edit+Write) is missing ${missing.join(' and ')} ` +
+          '— see .claude/rules/parallel-sessions.md § PSA-007 and agents/AGENTS.md § Authoring Convention',
+      );
+    } else {
+      pass(`${agentFile}: PSA-007 git-write ban present`);
+    }
+  }
+
+  if (repoWriteCount === 0) {
+    // No repo-write agents in this plugin root — nothing to enforce.
+    console.log('  (no repo-write agents found — check skipped)');
+  }
+}
+
 console.log('');
 console.log(`Results: ${passed} passed, ${failed} failed`);
 

package/scripts/lib/validate/check-hooks-symmetry.mjs

@@ -1,12 +1,31 @@
 #!/usr/bin/env node
 // scripts/lib/validate/check-hooks-symmetry.mjs
-// Verify event-key + handler-file symmetry across hooks/{hooks,hooks-codex,hooks-cursor,hooks-pi}.json
+// Verify event-key + handler-file + per-event handler-set symmetry across
+// hooks/{hooks,hooks-codex,hooks-cursor,hooks-pi}.json (Check 6: #942)
+// Check 6 projects platform-native event namespaces onto the logical Claude
+// events first, then refuses to report parity for any counterpart event that
+// lands on no hooks.json event — whether that is one dropped projection or the
+// whole namespace (a vacuum-true PASS — see Check 6).
 // Exit 0 = all checks pass, 1 = any check fails
 // Stdout: '  PASS: ...' / '  FAIL: ...' lines + 'Results: N passed, M failed'
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
+// The pi projection is IMPORTED, not copied: pi-hook-bridge.mjs is the runtime
+// that actually rewrites `hook_event_name` for every Pi event, so it is the one
+// source of truth for which pi event becomes which Claude event (#953). A local
+// literal here was a second copy of the same 5 pairs — it could drift silently,
+// and the validator would then certify a projection the runtime does not use.
+// Deliberately NOT the same for `cursorEventMap` below: nothing at runtime
+// projects Cursor events (Cursor calls the handlers directly), so the
+// validator's copy is the only witness there. Even if a runtime source existed,
+// reading Check 3's expectation from the artefact it checks would make the
+// check self-certifying — the "undocumented pi-native event" test at
+// tests/scripts/check-hooks-symmetry.test.mjs would become unreachable. Keep
+// cursorEventMap validator-owned; do not "helpfully" collapse it too.
+import { PI_TO_CANONICAL_EVENT } from '../pi-hook-bridge.mjs';
+
 const PLUGIN_ROOT = process.argv[2];
 if (!PLUGIN_ROOT) {
   console.error('Usage: check-hooks-symmetry.mjs <plugin-root>');
@@ -25,12 +44,125 @@ const DOCUMENTED_ASYMMETRIES = {
   // Claude/Codex events with no Pi-native v1 mapping yet.
   piMissingFromMain: ['PostToolUseFailure', 'PostToolBatch', 'SubagentStart', 'SubagentStop', 'CwdChanged'],
   // Pi-native extension events that map onto Claude/Codex hook events.
-  piEventMap: {
-    session_start: 'SessionStart',
-    session_shutdown: 'SessionEnd',
-    tool_call: 'PreToolUse',
-    tool_result: 'PostToolUse',
-    agent_end: 'Stop',
+  // Bound to the runtime constant (see the import comment): the projection this
+  // validator checks hooks-pi.json against is the SAME object pi-hook-bridge.mjs
+  // applies to live payloads, so the two cannot drift apart.
+  piEventMap: PI_TO_CANONICAL_EVENT,
+  // Cursor-IDE-native events projected onto the logical Claude events they
+  // correspond to. WITHOUT this projection Check 6 compared a FOREIGN event
+  // namespace against hooks.json: not one key matched, the per-event loop
+  // `continue`d on every iteration, and hooks-cursor.json reported
+  // "handler sets match hooks.json (documented asymmetries: 0)" while missing
+  // 20 of 22 handlers — a vacuum-true PASS. Check 6's projection guard now
+  // fails closed PER declared event (#946), so dropping a single entry from
+  // this map is caught too, not only the loss of every projection: the first
+  // version tested `sharedEvents.length === 0`, under which removing just
+  // `afterFileEdit` left the run green and merely moved cursor's documented-
+  // asymmetry count from 12 to 8.
+  // afterFileEdit fires AFTER the edit (hooks-cursor.json `note`,
+  // docs/cursor-setup.md) → it projects onto PostToolUse, never PreToolUse.
+  cursorEventMap: {
+    beforeShellExecution: 'PreToolUse',
+    afterFileEdit: 'PostToolUse',
+  },
+  // Check 6 (#942): handlers wired on a Claude event but intentionally absent
+  // from the SAME logical event on a counterpart manifest. Checks 1-3 compare
+  // event KEYS and Check 4 handler EXISTENCE — a handler wired on only one
+  // platform was structurally invisible to all four (the #942 blind spot:
+  // post-bash-write-verify.mjs shipped Claude-only and nothing flagged it).
+  // A handler missing on a shared event and NOT listed here → FAIL.
+  handlerAsymmetries: {
+    codex: {
+      // Codex 0.144.4 has no payload adapter (docs/codex-setup.md § Hook
+      // Surface and Trust): Edit/Write handlers expect Claude payload shapes,
+      // Bash guards expect tool_name === 'Bash'. Wiring them would be a silent
+      // no-op, not enforcement (#919-P2 class) — "pretending the payloads are
+      // compatible would create false enforcement".
+      PreToolUse: [
+        'skill-invocation-telemetry.mjs',
+        'enforce-scope.mjs',
+        'config-protection.mjs',
+        'pre-bash-destructive-guard.mjs',
+        'pre-bash-staging-fence.mjs',
+        'pre-bash-memory-propose-audit.mjs',
+        // pre-bash-sessions-ledger-guard (#958): same Bash-payload dependency
+        // as the guards above — it reads tool_name === 'Bash' and
+        // tool_input.command, neither of which any Codex bridge delivers
+        // (measured 2026-07-31: `grep -rn "tool_name" scripts/lib/codex/*.mjs`
+        // → 0 matches, exit 1). A manifest entry would be a silent no-op, not
+        // enforcement — #919-P2 class. Gap registered, not faked.
+        'pre-bash-sessions-ledger-guard.mjs',
+        'pre-bash-templates-first.mjs',
+        'pre-bash-issue-budget.mjs',
+        'enforce-commands.mjs',
+      ],
+      // post-bash-write-verify (#942): needs tool_name === 'Bash', which no
+      // Codex bridge delivers — documented exception until an adapter exists.
+      // Measured 2026-07-31: `grep -rn "tool_name" scripts/lib/codex/*.mjs`
+      // → 0 matches (exit 1), so a manifest entry here would be a silent
+      // no-op, not enforcement. Same #919-P2 class as the PreToolUse block.
+      PostToolUse: [
+        'post-edit-validate.mjs',
+        'post-tooluse-frontend-slop.mjs',
+        'post-bash-write-verify.mjs',
+      ],
+      SubagentStart: ['subagent-telemetry.mjs'],
+      SubagentStop: ['subagent-telemetry.mjs', 'post-subagent-discovery-validator.mjs'],
+    },
+    pi: {
+      // skill-invocation-telemetry: Pi has no Skill tool (pi-hook-bridge
+      // TOOL_NAME_MAP) — the matcher can never fire.
+      // pre-bash-templates-first + pre-bash-issue-budget (#946): status-quo
+      // gaps predating #942. Operator decision 2026-07-31 — NOT ported, gap
+      // registered instead; #946 tracks the port-or-justify follow-up.
+      // pre-bash-sessions-ledger-guard (#958): NOT ported. Pi has a payload
+      // adapter (pi-hook-bridge.mjs), so unlike codex/cursor this one is
+      // portable — but wiring it is a separate decision with its own test
+      // surface, and the operator's 2026-07-31 rule is that a gap gets
+      // registered rather than faked. #958 tracks the port-or-justify.
+      PreToolUse: [
+        'skill-invocation-telemetry.mjs',
+        'pre-bash-sessions-ledger-guard.mjs', // #958
+        'pre-bash-templates-first.mjs', // #946
+        'pre-bash-issue-budget.mjs',    // #946
+      ],
+    },
+    // Cursor is NOT wired (#919) and will not be: hooks-cursor.json is a
+    // mapping REFERENCE, not live enforcement. Every handler expects Claude
+    // Code payload shapes (tool_name === 'Bash', tool_input.command) and emits
+    // a Claude PreToolUse envelope; fed a Cursor payload enforce-commands.mjs
+    // short-circuits at gate G1 and writes 0 bytes to stdout AND stderr with
+    // exit 0, so the harness sees no decision and the command runs. Cursor
+    // needs an input/output adapter like scripts/lib/pi-hook-bridge.mjs; none
+    // exists. Operator decision 2026-07-31 — gap registered, not closed:
+    // #919 (Cursor no-op) tracks the adapter, #946 the allowlist-provenance
+    // rule that every entry here names its issue. These entries exist so the
+    // gap is MACHINE-readable (Check 6 counts them) rather than prose-only.
+    cursor: {
+      // #919: beforeShellExecution → PreToolUse. Only enforce-commands.mjs is
+      // mapped at all; the other eight PreToolUse handlers have no Cursor
+      // mapping whatsoever.
+      PreToolUse: [
+        'skill-invocation-telemetry.mjs',    // #919
+        'enforce-scope.mjs',                 // #919
+        'config-protection.mjs',             // #919
+        'pre-bash-destructive-guard.mjs',    // #919
+        'pre-bash-staging-fence.mjs',        // #919
+        'pre-bash-memory-propose-audit.mjs', // #919
+        'pre-bash-sessions-ledger-guard.mjs',// #919 (#958 — needs tool_name === 'Bash')
+        'pre-bash-templates-first.mjs',      // #919
+        'pre-bash-issue-budget.mjs',         // #919
+      ],
+      // #919: afterFileEdit → PostToolUse. Cursor maps enforce-scope.mjs here
+      // (post-hoc warning only); none of Claude's four PostToolUse handlers
+      // has a Cursor mapping.
+      PostToolUse: [
+        'post-edit-validate.mjs',          // #919
+        'post-tooluse-frontend-slop.mjs',  // #919
+        'post-bash-write-verify.mjs',      // #919 (#942 class — needs tool_name === 'Bash')
+        'loop-guard.mjs',                  // #919
+      ],
+    },
   },
 };
 
@@ -163,9 +295,10 @@ if (piJson) {
 // Handles two shapes:
 //   Claude/Codex: hooks[event] = Array<{ hooks: Array<{ command: "node \"$CLAUDE_PLUGIN_ROOT/hooks/foo.mjs\"" }> }>
 //   Cursor:       hooks[event] = { script: "hooks/foo.mjs" }
-function extractHandlers(json) {
-  const handlers = new Set();
-  for (const event of Object.values(json.hooks || {})) {
+function extractHandlersByEvent(json) {
+  const byEvent = {};
+  for (const [eventName, event] of Object.entries(json.hooks || {})) {
+    const handlers = new Set();
     const matchers = Array.isArray(event) ? event : [event];
     for (const m of matchers) {
       // Cursor shape: script field at matcher level
@@ -181,6 +314,15 @@ function extractHandlers(json) {
         if (match) handlers.add(match[1]);
       }
     }
+    byEvent[eventName] = handlers;
+  }
+  return byEvent;
+}
+
+function extractHandlers(json) {
+  const handlers = new Set();
+  for (const set of Object.values(extractHandlersByEvent(json))) {
+    for (const h of set) handlers.add(h);
   }
   return handlers;
 }
@@ -252,6 +394,98 @@ if (unreferenced.length === 0) {
   pass(`hooks/ has ${unreferenced.length} unreferenced .mjs files (allowed; they may be library helpers): ${unreferenced.join(', ')}`);
 }
 
+// Step 9 (#942): per-event handler-SET parity, Claude → counterpart.
+// Checks 1-3 compare event keys, Check 4 handler existence — neither sees a
+// handler wired on one platform only. For every logical event the counterpart
+// DECLARES (event-level absences stay governed by Checks 1-3), each Claude
+// handler must be present on the counterpart or listed in
+// DOCUMENTED_ASYMMETRIES.handlerAsymmetries. Undocumented gap → FAIL.
+console.log('');
+console.log('--- Check 6: per-event handler-set parity across manifests (#942) ---');
+const claudeHandlersByEvent = extractHandlersByEvent(claudeJson);
+
+// Pi and Cursor declare platform-native event names; project them onto the
+// logical main events before comparing, or the whole comparison is vacuous.
+// Native events with no mapping are carried through under their own name so
+// the projection guard below still sees them as declared.
+//
+// The merge is a UNION, not an assignment: two native events may project onto
+// the SAME logical event (a harness with `before_shell` AND `before_edit` both
+// mapping to PreToolUse, or — reachable today via the identity fallback — a
+// counterpart that declares the logical event alongside a native event that
+// projects onto it). Assignment let the second write silently discard the
+// first set, so its handlers resurfaced as a phantom "undocumented asymmetry"
+// or vanished from the comparison entirely.
+function handlersByMainEvent(json, eventMap) {
+  const byNativeEvent = extractHandlersByEvent(json);
+  const byMain = {};
+  for (const [nativeEvent, handlers] of Object.entries(byNativeEvent)) {
+    const target = eventMap[nativeEvent] || nativeEvent;
+    byMain[target] = new Set([...(byMain[target] ?? []), ...handlers]);
+  }
+  return byMain;
+}
+
+const HANDLER_PARITY_COUNTERPARTS = [
+  { file: 'hooks-codex.json', key: 'codex', byEvent: codexJson ? extractHandlersByEvent(codexJson) : null },
+  {
+    file: 'hooks-cursor.json',
+    key: 'cursor',
+    byEvent: cursorJson ? handlersByMainEvent(cursorJson, DOCUMENTED_ASYMMETRIES.cursorEventMap) : null,
+  },
+  {
+    file: 'hooks-pi.json',
+    key: 'pi',
+    byEvent: piJson ? handlersByMainEvent(piJson, DOCUMENTED_ASYMMETRIES.piEventMap) : null,
+  },
+];
+
+for (const { file, key, byEvent } of HANDLER_PARITY_COUNTERPARTS) {
+  if (!byEvent) {
+    pass(`${file} absent (optional config) — handler parity skipped`);
+    continue;
+  }
+  // Projection guard: every event a counterpart declares must land on a
+  // logical event hooks.json also declares. An unprojected event makes the
+  // per-event loop below `continue` on the logical event it was supposed to
+  // cover, so those handlers are never compared and Check 6 still reports
+  // PASS — only the `documented asymmetries:` count moves. Losing ALL
+  // projections is how hooks-cursor.json passed with 20 of 22 handlers
+  // missing; losing ONE is the same blindness at smaller scale, so the guard
+  // fails closed per event, not only on the empty intersection (#946).
+  const declaredEvents = Object.keys(byEvent);
+  const sharedEvents = declaredEvents.filter((e) => Object.hasOwn(claudeHandlersByEvent, e));
+  const unprojectedEvents = declaredEvents.filter((e) => !Object.hasOwn(claudeHandlersByEvent, e));
+  if (declaredEvents.length > 0 && sharedEvents.length === 0) {
+    // Whole-namespace loss keeps its own message: nothing at all was compared.
+    fail(`${file} shares ZERO logical events with hooks.json after projection (declares: ${declaredEvents.join(', ')}) — handler parity would pass vacuously; add an event projection to DOCUMENTED_ASYMMETRIES`);
+    continue;
+  }
+  if (unprojectedEvents.length > 0) {
+    fail(`${file} declares events with no logical counterpart in hooks.json after projection: ${unprojectedEvents.join(', ')} — handlers on the logical events they stand for are never compared; add a projection to DOCUMENTED_ASYMMETRIES.${key}EventMap`);
+    continue;
+  }
+
+  const allow = DOCUMENTED_ASYMMETRIES.handlerAsymmetries[key] || {};
+  const undocumented = [];
+  let documentedCount = 0;
+  for (const [event, claudeSet] of Object.entries(claudeHandlersByEvent)) {
+    const counterpartSet = byEvent[event];
+    if (!counterpartSet) continue; // event not declared on counterpart — Checks 1-3 govern
+    const allowed = new Set(allow[event] || []);
+    for (const handler of claudeSet) {
+      if (counterpartSet.has(handler)) continue;
+      if (allowed.has(handler)) { documentedCount++; continue; }
+      undocumented.push(`${event} → ${handler}`);
+    }
+  }
+  if (undocumented.length === 0) {
+    pass(`${file} per-event handler sets match hooks.json (documented asymmetries: ${documentedCount})`);
+  } else {
+    fail(`${file} missing UNDOCUMENTED handlers on shared events: ${undocumented.join(', ')}`);
+  }
+}
+
 // Final
 console.log('');
 console.log(`Results: ${passed} passed, ${failed} failed`);