cabloy 5.1.192 → 5.1.193

package/repo-agent-governance/tools/contract-loop/hook-runtime.mjs

@@ -0,0 +1,367 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  analyze,
+  analyzePath,
+  buildMessages,
+  isCodeFile,
+  isHighConfidenceReverseSource,
+  normalizePath,
+  resolveEdition,
+  toPosixPath,
+} from './core.mjs';
+
+const STATE_FILE = path.join(os.tmpdir(), 'cabloy-contract-loop-gate-state.json');
+const AUTO_SYNC_WINDOW_SECONDS = 300;
+
+function readText(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function isDirectory(filePath) {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function canonicalPath(filePath) {
+  let current = filePath;
+  const missingSegments = [];
+  for (;;) {
+    try {
+      return path.resolve(realpathSync(current), ...missingSegments);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return filePath;
+      missingSegments.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(canonicalPath(root), canonicalPath(candidate));
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..');
+}
+
+function loadState() {
+  if (!existsSync(STATE_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveState(state) {
+  try {
+    writeFileSync(STATE_FILE, JSON.stringify(state), 'utf8');
+  } catch {
+    // State prevents duplicate convenience syncs only; it must not block guidance.
+  }
+}
+
+function syncFingerprint(filePath) {
+  try {
+    const stats = statSync(filePath, { bigint: true });
+    return `${filePath}:${stats.mtimeNs.toString()}`;
+  } catch {
+    return filePath;
+  }
+}
+
+function shouldSkipAutoSync(root, filePath) {
+  const state = loadState();
+  const entry = state[toPosixPath(root)];
+  return Boolean(
+    entry &&
+    entry.fingerprint === syncFingerprint(filePath) &&
+    Date.now() - entry.timestamp <= AUTO_SYNC_WINDOW_SECONDS * 1000,
+  );
+}
+
+function markAutoSync(root, filePath) {
+  const state = loadState();
+  state[toPosixPath(root)] = { fingerprint: syncFingerprint(filePath), timestamp: Date.now() };
+  saveState(state);
+}
+
+function runNpm(root, args) {
+  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return spawnSync(command, [...args], { cwd: root, encoding: 'utf8' });
+}
+
+function summarizeProcess(result) {
+  if (result.error) return result.error.message;
+  const combined = [result.stdout?.trim(), result.stderr?.trim()].filter(Boolean).join('\n');
+  const exitCode = result.status ?? 1;
+  if (!combined) return `command exited with code ${exitCode}`;
+  return `exit ${exitCode}: ${combined
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(-3)
+    .join(' | ')}`;
+}
+
+function autoSyncReverse(root, filePath, edition) {
+  for (const command of edition.reverseAutoSyncCommands) {
+    const result = runNpm(root, command.args);
+    if (result.status !== 0) {
+      return {
+        kind: 'failure',
+        message: `Auto-sync failed during \`${command.display}\`: ${summarizeProcess(result)}`,
+      };
+    }
+  }
+  markAutoSync(root, filePath);
+  return {
+    kind: 'success',
+    message: `Auto-sync ran ${edition.reverseAutoSyncCommands
+      .map(command => `\`${command.display}\``)
+      .join(' and ')} for this ${edition.label} reverse-chain edit.`,
+  };
+}
+
+export function resolveReverseSyncOutcome(root, filePath, reverseReason) {
+  if (!reverseReason) return { kind: 'not-applicable', message: '' };
+  if (!isHighConfidenceReverseSource(filePath)) {
+    return {
+      kind: 'not-applicable',
+      message:
+        'Auto-sync did not run because this reverse-chain signal came from the consumer side rather than a high-confidence frontend source edit.',
+    };
+  }
+  const resolution = resolveEdition(root);
+  if (resolution.kind !== 'resolved') {
+    return {
+      kind: 'not-applicable',
+      message: `Auto-sync did not run because ${resolution.kind === 'ambiguous' ? 'both Cabloy edition markers are present' : 'no Cabloy edition marker is present'}.`,
+    };
+  }
+  if (shouldSkipAutoSync(root, filePath)) {
+    return {
+      kind: 'skipped',
+      message:
+        'Auto-sync skipped because the same reverse-source edit was already synced recently in this repo.',
+    };
+  }
+  return autoSyncReverse(root, filePath, resolution.edition);
+}
+
+export function readHookPayload() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function extractClaudeEditedFilePath(payload) {
+  const filePath = payload?.tool_input?.file_path;
+  return typeof filePath === 'string' && filePath ? filePath : null;
+}
+
+export function extractCodexEditedFiles(payload) {
+  const command = payload?.tool_input?.command;
+  if (typeof command !== 'string') return [];
+  const entries = [];
+  let pendingUpdate = null;
+  const headerPattern =
+    /^\*\*\* (Add|Update|Delete) File:\s*(.+?)\s*$|^\*\*\* Move to:\s*(.+?)\s*$/gm;
+
+  const flushUpdate = () => {
+    if (pendingUpdate) entries.push(pendingUpdate);
+    pendingUpdate = null;
+  };
+
+  for (const match of command.matchAll(headerPattern)) {
+    const [, verb, sourcePath, destinationPath] = match;
+    if (destinationPath !== undefined) {
+      if (pendingUpdate) pendingUpdate.filePath = destinationPath.trim();
+      continue;
+    }
+    flushUpdate();
+    const filePath = sourcePath.trim();
+    if (!filePath) continue;
+    const operation = verb.toLowerCase();
+    if (operation === 'update') {
+      pendingUpdate = { operation, filePath };
+    } else {
+      entries.push({ operation, filePath });
+    }
+  }
+  flushUpdate();
+  return entries;
+}
+
+// Retain the path-only export for callers that only need the historical view.
+export function extractCodexEditedFilePaths(payload) {
+  return extractCodexEditedFiles(payload).map(entry => entry.filePath);
+}
+
+export function extractCursorEditedFilePath(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  if (typeof payload.file_path === 'string' && payload.file_path) return payload.file_path;
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object') return null;
+  for (const key of ['path', 'file_path', 'target_file']) {
+    const value = input[key];
+    if (typeof value === 'string' && value) return value;
+  }
+  return null;
+}
+
+export function inferCursorHookEvent(payload) {
+  const eventName = payload?.hook_event_name;
+  if (
+    eventName === 'afterFileEdit' ||
+    eventName === 'afterTabFileEdit' ||
+    eventName === 'postToolUse'
+  ) {
+    return eventName;
+  }
+  if (typeof payload?.file_path === 'string' && payload.file_path && !payload.tool_name) {
+    return 'afterFileEdit';
+  }
+  return 'postToolUse';
+}
+
+export function formatClaudeHookOutput(message) {
+  return {
+    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
+    systemMessage: message,
+  };
+}
+
+export function formatCodexHookOutput(message) {
+  return {
+    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
+    systemMessage: message,
+  };
+}
+
+export function formatCursorHookOutput(message, eventName) {
+  if (eventName !== 'postToolUse') return null;
+  return { additional_context: message };
+}
+
+function resolvePathBase(root, candidate) {
+  if (typeof candidate !== 'string' || !candidate) return root;
+  const pathBase = normalizePath(root, candidate);
+  if (!pathBase || !isInside(root, pathBase) || !isDirectory(pathBase)) return root;
+  return pathBase;
+}
+
+function createInspectionFailure(root, filePath, operation) {
+  const relativePath = toPosixPath(path.relative(root, filePath));
+  return {
+    kind: 'failure',
+    filePath,
+    message: `Contract-loop gate: could not inspect edited source \`${relativePath}\` after this ${operation} patch; no contract-loop guidance or auto-sync ran.`,
+  };
+}
+
+function inspectEditedFile(root, rawPath, { operation = 'update', pathBase = root } = {}) {
+  const filePath = normalizePath(pathBase, rawPath);
+  if (!filePath || !isInside(root, filePath) || !isCodeFile(filePath)) return null;
+
+  const resolution = resolveEdition(root);
+  if (operation === 'delete') {
+    const result = analyzePath(filePath);
+    if (!result.forwardReason && !result.reverseReason) return null;
+    return { kind: 'signal', filePath, resolution, result };
+  }
+
+  const content = readText(filePath);
+  if (content === null) return createInspectionFailure(root, filePath, operation);
+  const result = analyze(
+    filePath,
+    content,
+    resolution.kind === 'resolved' ? resolution.edition : null,
+  );
+  if (!result.forwardReason && !result.reverseReason) return null;
+  return { kind: 'signal', filePath, resolution, result };
+}
+
+export function evaluateEditedFile(root, rawPath) {
+  const inspected = inspectEditedFile(root, rawPath);
+  if (!inspected || inspected.kind !== 'signal') return null;
+  const { filePath, resolution, result } = inspected;
+  const reverseSyncOutcome = resolveReverseSyncOutcome(root, filePath, result.reverseReason);
+  return {
+    filePath,
+    message: buildMessages(result, resolution, reverseSyncOutcome),
+  };
+}
+
+export function evaluateCodexEditedFiles(root, entries, payloadCwd) {
+  const pathBase = resolvePathBase(root, payloadCwd);
+  const seenEntries = new Set();
+  const inspected = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry.filePath !== 'string') continue;
+    const operation = ['add', 'update', 'delete'].includes(entry.operation)
+      ? entry.operation
+      : 'update';
+    const normalizedPath = normalizePath(pathBase, entry.filePath);
+    if (!normalizedPath || !isInside(root, normalizedPath)) continue;
+    const key = `${operation}:${normalizedPath}`;
+    if (seenEntries.has(key)) continue;
+    seenEntries.add(key);
+    const item = inspectEditedFile(root, entry.filePath, { operation, pathBase });
+    if (item) inspected.push(item);
+  }
+
+  const autoSyncItem = inspected.find(
+    item =>
+      item.kind === 'signal' &&
+      item.result.reverseReason &&
+      isHighConfidenceReverseSource(item.filePath),
+  );
+  const autoSyncOutcome = autoSyncItem
+    ? resolveReverseSyncOutcome(root, autoSyncItem.filePath, autoSyncItem.result.reverseReason)
+    : null;
+
+  return inspected.map(item => {
+    if (item.kind === 'failure') return { filePath: item.filePath, message: item.message };
+
+    let reverseSyncOutcome;
+    if (item === autoSyncItem) {
+      reverseSyncOutcome = autoSyncOutcome;
+    } else if (item.result.reverseReason && isHighConfidenceReverseSource(item.filePath)) {
+      reverseSyncOutcome = {
+        kind: 'skipped',
+        message:
+          'Auto-sync skipped because another high-confidence reverse-source file in this Codex edit was already handled.',
+      };
+    } else {
+      reverseSyncOutcome = resolveReverseSyncOutcome(
+        root,
+        item.filePath,
+        item.result.reverseReason,
+      );
+    }
+    return {
+      filePath: item.filePath,
+      message: buildMessages(item.result, item.resolution, reverseSyncOutcome),
+    };
+  });
+}
+
+// Keep the prior general API for direct callers. Codex now uses the operation-aware evaluator.
+export function evaluateEditedFiles(root, rawPaths) {
+  return evaluateCodexEditedFiles(
+    root,
+    rawPaths.map(filePath => ({ operation: 'update', filePath })),
+  );
+}

package/repo-docs/ai/agent-governance.md

@@ -15,14 +15,16 @@ npm run agent:governance:check
 
 The committed repository adapter outputs are:
 
-| Agent surface | Generated repository assets                                                                    |
-| ------------- | ---------------------------------------------------------------------------------------------- |
-| Claude Code   | `CLAUDE.md`, `.claude/skills/`, `.claude/commands/`, `.claude/settings.json`, `.claude/hooks/` |
-| Codex         | `AGENTS.md`, `.agents/skills/`                                                                 |
-| Cursor        | `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`                                       |
+| Agent surface | Generated repository assets                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| Claude Code   | `CLAUDE.md`, `.claude/skills/`, `.claude/commands/`, `.claude/settings.json`, `.claude/hooks/`   |
+| Codex         | `AGENTS.md`, `.agents/skills/`, `.codex/hooks.json`, `.codex/hooks/`                             |
+| Cursor        | `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/hooks/` |
 
 The same root rule and skill sources are copied to every listed adapter. Platform-specific discovery metadata is intentionally thin and lives in the adapter layer. The generated Codex and Cursor skill paths are configured adapter locations; their client discovery behavior requires a version-pinned external smoke check before it is claimed as supported.
 
+Codex requires the user to trust project-local hooks before it runs `.codex/hooks.json`; that local trust state is not generated or committed by this repository. The repository launcher resolves a hook from nested working directories without Git once Codex invokes it, but Codex discovery remains client-version behavior. For non-Git projects opened from nested directories, configure local Codex `project_root_markers` to include `__CABLOY_BASIC__` and `__CABLOY_START__` alongside `.git`; do not generate that user setting from this repository.
+
 ### Package migration bridge
 
 The transition package deliberately excludes generated root adapters because the immediately preceding upgrader overwrites those paths before it starts the incoming initializer. This prevents that legacy path from silently replacing customized adapters. The package still includes canonical governance and `scripts/init.ts`; `npm run init` performs ownership-aware adoption for both a staged upgrade and a fresh project. A source checkout retains its committed generated adapters. This bridge is package-transition behavior, not a claim that agents generate instructions at startup.
@@ -31,7 +33,7 @@ The transition package deliberately excludes generated root adapters because the
 
 Rules, procedural skills, references, eval fixtures, contract-loop analysis, and ordinary deterministic repository tools are portable.
 
-Hooks, tool permissions, local settings, credentials, MCP registration, slash-command discovery, confirmation UI, and automatic command execution are not portable contracts. Claude Code retains the repository `PostToolUse` contract-loop convenience hook. Codex and Cursor receive the same advisory contract-loop guidance but must not be described as running the Claude hook or its automatic commands.
+Hooks, tool permissions, local settings, credentials, MCP registration, slash-command discovery, confirmation UI, and automatic command execution are not portable contracts. Claude Code, Codex, and Cursor each have a platform-specific contract-loop convenience hook over the same portable classifier and reverse auto-sync runtime. Their hook payloads and stdout contracts differ, so each adapter must remain provider-specific even when it shares the same runtime.
 
 No adapter output owns `settings.local.json`, `CLAUDE.local.md`, worktree state, scheduled-task state, credentials, or arbitrary user-owned agent files.
 

package/repo-docs/ai/docs-skills-rules-mapping.md

@@ -81,6 +81,9 @@ Generated adapter locations include:
 
 - policy adapters: `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/`
 - Claude-specific command adapter: `.claude/commands/`
+- Claude-specific hook adapter: `.claude/settings.json`, `.claude/hooks/`
+- Codex-specific hook adapter: `.codex/hooks.json`, `.codex/hooks/`
+- Cursor-specific hook adapter: `.cursor/hooks.json`, `.cursor/hooks/`
 
 Codex and Cursor adapter paths are configured output locations; verify active-client discovery externally before claiming that behavior is supported.
 
@@ -98,7 +101,7 @@ Canonical location:
 
 - `repo-agent-governance/skills/`
 
-Generated adapter locations include `.claude/skills/`, `.agents/skills/`, and `.cursor/skills/`. The Codex and Cursor locations are configured output paths, not verified client-discovery claims; validate the active client version externally before relying on discovery.
+Generated adapter locations include `.claude/skills/`, `.agents/skills/`, `.codex/`, and `.cursor/skills/`. The Codex and Cursor locations are configured output paths, not verified client-discovery claims; validate the active client version externally before relying on discovery.
 
 Use skills for:
 

package/repo-docs/ai/edition-consistency-checklist.md

@@ -7,7 +7,7 @@ Use it whenever you add or revise:
 - edition-aware docs
 - `repo-agent-governance/` rules, commands, and skill bundles
 - generated Claude, Codex, or Cursor adapter outputs
-- platform-specific Claude commands, hooks, or settings when they are affected
+- platform-specific Claude, Codex, or Cursor commands, hooks, or settings when they are affected
 - AI workflow playbooks
 
 ## The baseline story that should stay consistent

package/repo-docs/ai/introduction.md

@@ -52,7 +52,7 @@ Use `repo-agent-governance/` as the authored source for portable repository rule
 
 ### Platform runtime integration
 
-`CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `AGENTS.md`, `.agents/skills/`, and `.cursor/` are adapter/runtime surfaces. Hooks, permissions, local settings, credentials, and provider-specific command discovery stay platform-specific rather than becoming shared framework facts.
+`CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `AGENTS.md`, `.agents/skills/`, `.codex/`, and `.cursor/` are adapter/runtime surfaces. Hooks, permissions, local settings, credentials, and provider-specific command discovery stay platform-specific rather than becoming shared framework facts.
 
 ## AI reading paths
 

package/repo-docs/ai/repo-guidance.md

@@ -11,7 +11,7 @@ Check the root repository signals first:
 - `repo-docs-internal/`
 - `repo-specs/` when the task concerns a suite plan, WBS increment, acceptance record, or evidence
 - `repo-agent-governance/` canonical rules, skill bundles, and deterministic tools
-- generated platform adapter assets such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, and `.cursor/`
+- generated platform adapter assets such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, and `.cursor/`
 
 These surfaces tell the agent which repo it is in, which scripts are canonical, and where shared agent instructions are authored. Treat platform directories as generated adapters; regenerate them from `repo-agent-governance/` rather than hand-editing them. Inspect relevant `repo-docs-internal/` records as supporting context rather than as a gate to workflow guidance.
 

package/repo-docs/ai/rules-and-config.md

@@ -21,10 +21,12 @@ npm run test:agent-governance
 The following are committed generated outputs, not parallel authored knowledge sources:
 
 - Claude Code: `CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `.claude/settings.json`, `.claude/hooks/`
-- Codex: `AGENTS.md`, `.agents/skills/`
-- Cursor: `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`
+- Codex: `AGENTS.md`, `.agents/skills/`, `.codex/hooks.json`, `.codex/hooks/`
+- Cursor: `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/hooks/`
 
-The Codex and Cursor skill paths are configured generated adapter locations; verify client discovery with a version-pinned external smoke check before presenting it as supported behavior. The adapter model shares rules and procedures, not platform runtime behavior. Claude Code's contract-loop hook is a Claude-specific convenience integration; Codex and Cursor receive advisory guidance but do not claim the same automatic after-edit action.
+The Codex and Cursor skill paths are configured generated adapter locations; verify client discovery with a version-pinned external smoke check before presenting it as supported behavior. The adapter model shares rules and procedures, not hook payload formats. Claude Code, Codex, and Cursor each register a platform-specific contract-loop convenience hook over the same portable runtime.
+
+Codex runs project-local `.codex/hooks.json` only after the user trusts that hook definition. Hook trust is local state and remains outside generated governance ownership. The generated launcher is Git-free once Codex invokes it, but non-Git project discovery from a nested directory remains client-controlled; configure local Codex `project_root_markers` with Cabloy edition markers when that scenario must be supported.
 
 ## Local configuration and permissions
 

package/repo-docs/reference/package-map.md

@@ -8,7 +8,7 @@ This monorepo is organized around a small set of stable top-level areas.
 - `lerna.json` — package topology
 - `repo-docs-internal/` — edition-local maintainer notes and ADRs
 - `repo-agent-governance/` — authored portable agent rules, root skill bundles, adapter definitions, and deterministic tools
-- `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.cursor/` — generated platform adapters plus platform-specific runtime integration
+- `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.cursor/` — generated platform adapters plus platform-specific runtime integration
 - `repo-docs/` — unified public docs
 - `repo-specs/` — suite-local product, technical, delivery, ATP, progress, observed-evidence, and ADR authority