cabloy 5.1.192 → 5.1.193

package/repo-agent-governance/skills/cabloy-contract-loop/SKILL.md

@@ -30,7 +30,14 @@ Do not keep debugging source-level contract or renderer changes until the local
 ## Current safeguard behavior in this repo
 
 - there is no contract-loop pre-commit gate in the current repo workflow
-- the active safeguard lives in the Claude `PostToolUse` hook configured in `.claude/settings.json`
+- the active safeguards are platform-specific adapters over the same portable classifier and reverse auto-sync runtime in `repo-agent-governance/tools/contract-loop/`
+- Claude Code uses the `PostToolUse` hook in `.claude/settings.json`
+- Codex uses the `PostToolUse` hook in `.codex/hooks.json`; it matches `apply_patch` / `Edit` / `Write`, resolves the project-local bridge without requiring Git, preserves Add/Update/Delete patch operations, and returns model-visible context through the Codex hook contract
+- Codex project-hook discovery and trust remain client-local. In a non-Git project opened from a nested directory, configure the local Codex `project_root_markers` to include `__CABLOY_BASIC__` and `__CABLOY_START__` alongside `.git`; the repository must not write that user setting
+- Cursor uses native `postToolUse` for Agent `Write` context plus `afterTabFileEdit` for Tab `TabWrite` side effects in `.cursor/hooks.json`; the native `afterFileEdit` route is intentionally absent so one Agent write does not run the gate twice
+- Cursor payloads are not Claude hook payloads. When Cursor imports `.claude/settings.json`, the Claude bridge recognizes Cursor and returns without work, leaving the native Cursor adapter as the single Agent gate
+- `postToolUse` injects `additional_context` into the agent turn; `afterTabFileEdit` is side-effect only and still runs the shared reverse auto-sync when the edited file matches
+- Codex handles every matching entry in one `apply_patch` call and runs at most one high-confidence reverse auto-sync for that patch. Explicit Delete entries use path-only evidence; an unreadable Add or Update target is reported as an inspection failure, never reinterpreted as a delete
 - for high-confidence reverse-chain source edits on the Zova side, the hook auto-runs `npm run build:zova:admin` and then `npm run deps:vona`
 - forward-chain detections remain reminder-only, so backend contract changes still require deliberate regeneration and verification
 - consumer-side reverse signals remain reminder-only, so do not assume every reverse-chain case auto-syncs itself
@@ -238,7 +245,7 @@ Important Cabloy Basic reverse-sync rule:
 - run `npm run build:zova:admin` from the repo root instead, then run `npm run deps:vona`
 - treat this as a JS-bundle-plus-rest-output handoff, not a rest-types-only refresh
 - the current repo safeguard may auto-run those two commands for high-confidence Zova reverse-source edits, but only as a convenience layer on top of the contract-loop model
-- if the change was consumer-side, low-confidence, cross-edition, or happened outside the Claude hook path, run the reverse sync flow deliberately yourself
+- if the change was consumer-side, low-confidence, cross-edition, happened outside a supported platform hook path, or used an untrusted/discovery-disabled hook, run the reverse sync flow deliberately yourself
 - prefer visible proof under `zova/src/**/.metadata/**` when it is available; if the effective handoff only appears in `.zova-rest`, treat the safeguard as conservative reminder/auto-sync assistance rather than strict proof
 
 For Cabloy Start, verify the exact Start-specific flavor names, paths, SSR site baselines, project assets, and source-confirmed root wrappers in the active Start repository. If the work affects an independent SSR site, follow Mode E: build that site’s paired wrapper rather than assuming an Admin/Web command covers it.

package/repo-agent-governance/skills/cabloy-contract-loop/references/verification-checklist.md

@@ -42,9 +42,11 @@ When one persisted domain has both Admin Resource and Web self-service consumers
 - `build:rest:*` was not treated as the only Vona SSR handoff
 - backend consumers can resolve the refreshed frontend-generated handoff
 - prefer visible proof under `zova/src/**/.metadata/**` when it is available
-- this repo does not rely on a contract-loop pre-commit gate; the active safeguard is the Claude hook layer
-- if the change was a high-confidence Zova reverse-source edit through the Claude hook path, confirm whether the hook already auto-ran `npm run build:zova:admin` and `npm run deps:vona`
-- if the change was consumer-side, low-confidence, outside the Claude hook path, or in another edition branch, run the reverse sync flow manually instead of assuming it already happened
+- this repo does not rely on a contract-loop pre-commit gate; Claude Code, Codex, and Cursor each use a provider-specific adapter over the same classifier
+- if the change was a high-confidence Zova reverse-source edit through a supported hook path, confirm whether the hook already auto-ran `npm run build:zova:admin` and `npm run deps:vona`
+- Codex evaluates an `apply_patch` batch as operation-aware entries: an explicit Delete is classified from reliable path evidence only; an unreadable Add or Update target is an inspection failure rather than a synthetic delete
+- Cursor Agent writes use native `postToolUse` context and Cursor Tab writes use native `afterTabFileEdit` side effects; the imported Claude bridge is intentionally inactive in Cursor to avoid duplicate work
+- if the change was consumer-side, low-confidence, outside a supported hook path, affected an untrusted/discovery-disabled hook, or was in another edition branch, run the reverse sync flow manually instead of assuming it already happened
 - if the real handoff only appears in `.zova-rest`, treat the safeguard as conservative reminder/auto-sync assistance rather than strict proof
 - `npm run tsc:zova`
 - relevant flavor-specific or route-specific checks

package/repo-agent-governance/tests/governance.test.mjs

@@ -20,6 +20,10 @@ import {
   isCodeFile,
   resolveEdition,
 } from '../tools/contract-loop/core.mjs';
+import {
+  extractCodexEditedFiles,
+  extractCodexEditedFilePaths,
+} from '../tools/contract-loop/hook-runtime.mjs';
 
 function createFixture() {
   const root = mkdtempSync(resolve(tmpdir(), 'cabloy-agent-governance-'));
@@ -47,6 +51,40 @@ function runGovernance(root, ...args) {
   return runNode(root, resolve(root, 'repo-agent-governance/scripts/governance.mjs'), ...args);
 }
 
+function runHook(root, executable, payload, { cwd = root, env = {} } = {}) {
+  const result = spawnSync(process.execPath, [executable], {
+    cwd,
+    encoding: 'utf8',
+    input: JSON.stringify(payload),
+    env: {
+      ...process.env,
+      CABLOY_GOVERNANCE_ROOT: root,
+      ...env,
+    },
+  });
+  return {
+    status: result.status,
+    output: `${result.stdout}${result.stderr}`,
+  };
+}
+
+function runShellHook(root, command, payload, cwd = root) {
+  const result = spawnSync(command, {
+    shell: true,
+    cwd,
+    encoding: 'utf8',
+    input: JSON.stringify(payload),
+    env: {
+      ...process.env,
+      CABLOY_GOVERNANCE_ROOT: root,
+    },
+  });
+  return {
+    status: result.status,
+    output: `${result.stdout}${result.stderr}`,
+  };
+}
+
 function readState(root) {
   return JSON.parse(readFileSync(resolve(root, '.cabloy-agent-governance-state.json'), 'utf8'));
 }
@@ -63,6 +101,13 @@ function removePolicyTarget(root, target) {
   writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 
+function setCursorHookTarget(root, target) {
+  const manifestPath = resolve(root, 'repo-agent-governance/manifest.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  manifest.cursor.hooks[0].target = target;
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
 function withFixture(callback) {
   const root = createFixture();
   try {
@@ -215,6 +260,34 @@ test('governance adoption deletes only unchanged retired outputs', () => {
   });
 });
 
+test('governance rendering removes unchanged retired outputs', () => {
+  withFixture(root => {
+    const legacyTarget = '.cursor/hooks/contract-loop-gate.ts';
+    setCursorHookTarget(root, legacyTarget);
+    assert.equal(runGovernance(root, 'render').status, 0);
+    assert.ok(existsSync(resolve(root, legacyTarget)));
+
+    setCursorHookTarget(root, '.cursor/hooks/contract-loop-gate.mjs');
+    assert.equal(runGovernance(root, 'render').status, 0);
+    assert.equal(existsSync(resolve(root, legacyTarget)), false);
+    assert.ok(existsSync(resolve(root, '.cursor/hooks/contract-loop-gate.mjs')));
+  });
+});
+
+test('governance rendering preserves modified retired outputs', () => {
+  withFixture(root => {
+    const legacyTarget = '.cursor/hooks/contract-loop-gate.ts';
+    setCursorHookTarget(root, legacyTarget);
+    assert.equal(runGovernance(root, 'render').status, 0);
+    const legacyPath = resolve(root, legacyTarget);
+    writeFileSync(legacyPath, 'project-owned legacy hook\n');
+
+    setCursorHookTarget(root, '.cursor/hooks/contract-loop-gate.mjs');
+    assert.equal(runGovernance(root, 'render').status, 0);
+    assert.equal(readFileSync(legacyPath, 'utf8'), 'project-owned legacy hook\n');
+  });
+});
+
 test('governance adoption preserves modified retired outputs', () => {
   withFixture(root => {
     assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
@@ -293,3 +366,204 @@ test('contract-loop recognizes supported vendor and suite source paths', () => {
   assert.equal(isCodeFile('/repo/vona/src/module/demo/src/service/demo.ts'), true);
   assert.equal(isCodeFile('/repo/repo-docs/ai/agent-governance.md'), false);
 });
+
+test('Codex contract-loop adapter evaluates operation-aware apply_patch paths', () => {
+  withFixture(root => {
+    const sourcePath = resolve(root, 'vona/src/module/demo/src/controller/demo.ts');
+    mkdirSync(dirname(sourcePath), { recursive: true });
+    writeFileSync(sourcePath, '@Api.field()\n');
+    assert.equal(runGovernance(root, 'render').status, 0);
+
+    const command = [
+      '*** Begin Patch',
+      '*** Update File: vona/src/module/demo/src/controller/demo.ts',
+      '@@',
+      '-@Api.field()',
+      '+@Api.field()',
+      '*** Update File: repo-docs/ai/agent-governance.md',
+      '@@',
+      '*** End Patch',
+    ].join('\n');
+    assert.deepEqual(extractCodexEditedFilePaths({ tool_input: { command } }), [
+      'vona/src/module/demo/src/controller/demo.ts',
+      'repo-docs/ai/agent-governance.md',
+    ]);
+    assert.deepEqual(extractCodexEditedFiles({ tool_input: { command } }), [
+      { operation: 'update', filePath: 'vona/src/module/demo/src/controller/demo.ts' },
+      { operation: 'update', filePath: 'repo-docs/ai/agent-governance.md' },
+    ]);
+
+    const result = runHook(root, resolve(root, '.codex/hooks/contract-loop-gate.mjs'), {
+      hook_event_name: 'PostToolUse',
+      tool_name: 'apply_patch',
+      tool_input: { command },
+    });
+    assert.equal(result.status, 0, result.output);
+    const output = JSON.parse(result.output);
+    assert.equal(output.hookSpecificOutput.hookEventName, 'PostToolUse');
+    assert.match(output.hookSpecificOutput.additionalContext, /Forward chain:/);
+  });
+});
+
+test('Codex launch command finds a non-Git project from nested cwd', () => {
+  withFixture(root => {
+    const sourcePath = resolve(root, 'vona/src/module/demo/src/controller/demo.ts');
+    mkdirSync(dirname(sourcePath), { recursive: true });
+    writeFileSync(sourcePath, '@Api.field()\n');
+    assert.equal(runGovernance(root, 'render').status, 0);
+
+    const hook = JSON.parse(readFileSync(resolve(root, '.codex/hooks.json'), 'utf8')).hooks
+      .PostToolUse[0].hooks[0];
+    assert.doesNotMatch(hook.command, /git rev-parse|\$\(/);
+    assert.equal(hook.commandWindows, hook.command);
+
+    const command = [
+      '*** Begin Patch',
+      '*** Update File: src/controller/demo.ts',
+      '@@',
+      '-@Api.field()',
+      '+@Api.field()',
+      '*** End Patch',
+    ].join('\n');
+    const nestedCwd = resolve(root, 'vona/src/module/demo');
+    const result = runShellHook(
+      root,
+      hook.command,
+      {
+        hook_event_name: 'PostToolUse',
+        tool_name: 'apply_patch',
+        cwd: nestedCwd,
+        tool_input: { command },
+      },
+      nestedCwd,
+    );
+    assert.equal(result.status, 0, result.output);
+    assert.match(JSON.parse(result.output).hookSpecificOutput.additionalContext, /Forward chain:/);
+  });
+});
+
+test('Codex delete paths are classified without reading removed sources', () => {
+  withFixture(root => {
+    assert.equal(runGovernance(root, 'render').status, 0);
+    const command = [
+      '*** Begin Patch',
+      '*** Delete File: vona/src/module/demo/src/controller/demo.ts',
+      '*** Delete File: zova/src/module/demo/src/bean/demo.ts',
+      '*** Delete File: repo-docs/ai/agent-governance.md',
+      '*** End Patch',
+    ].join('\n');
+    const result = runHook(root, resolve(root, '.codex/hooks/contract-loop-gate.mjs'), {
+      hook_event_name: 'PostToolUse',
+      tool_name: 'apply_patch',
+      tool_input: { command },
+    });
+    assert.equal(result.status, 0, result.output);
+    const output = JSON.parse(result.output).hookSpecificOutput.additionalContext;
+    assert.match(output, /Forward chain:/);
+    assert.match(output, /Reverse chain:/);
+    assert.match(output, /Auto-sync failed during `npm run build:zova:admin`/);
+    assert.doesNotMatch(output, /agent-governance\.md/);
+  });
+});
+
+test('Codex missing update does not become a delete and does not conceal a delete', () => {
+  withFixture(root => {
+    assert.equal(runGovernance(root, 'render').status, 0);
+    const command = [
+      '*** Begin Patch',
+      '*** Update File: vona/src/module/demo/src/controller/missing.ts',
+      '@@',
+      '*** Delete File: vona/src/module/demo/src/dto/deleted.ts',
+      '*** End Patch',
+    ].join('\n');
+    const result = runHook(root, resolve(root, '.codex/hooks/contract-loop-gate.mjs'), {
+      hook_event_name: 'PostToolUse',
+      tool_name: 'apply_patch',
+      tool_input: { command },
+    });
+    assert.equal(result.status, 0, result.output);
+    const output = JSON.parse(result.output).hookSpecificOutput.additionalContext;
+    assert.match(output, /could not inspect edited source/);
+    assert.match(output, /Forward chain:/);
+    assert.doesNotMatch(output, /Reverse chain:/);
+  });
+});
+
+test('Codex move paths inspect the destination', () => {
+  withFixture(root => {
+    const destinationPath = resolve(root, 'vona/src/module/demo/src/controller/moved.ts');
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    writeFileSync(destinationPath, '@Api.field()\n');
+    assert.equal(runGovernance(root, 'render').status, 0);
+    const command = [
+      '*** Begin Patch',
+      '*** Update File: vona/src/module/demo/src/service/old.ts',
+      '*** Move to: vona/src/module/demo/src/controller/moved.ts',
+      '@@',
+      '*** End Patch',
+    ].join('\n');
+    assert.deepEqual(extractCodexEditedFiles({ tool_input: { command } }), [
+      { operation: 'update', filePath: 'vona/src/module/demo/src/controller/moved.ts' },
+    ]);
+    const result = runHook(root, resolve(root, '.codex/hooks/contract-loop-gate.mjs'), {
+      hook_event_name: 'PostToolUse',
+      tool_name: 'apply_patch',
+      tool_input: { command },
+    });
+    assert.equal(result.status, 0, result.output);
+    assert.match(JSON.parse(result.output).hookSpecificOutput.additionalContext, /Forward chain:/);
+  });
+});
+
+test('Cursor contract-loop adapter handles Agent and Tab edit events once each', () => {
+  withFixture(root => {
+    const sourcePath = resolve(root, 'vona/src/module/demo/src/controller/demo.ts');
+    mkdirSync(dirname(sourcePath), { recursive: true });
+    writeFileSync(sourcePath, '@Api.field()\n');
+    assert.equal(runGovernance(root, 'render').status, 0);
+
+    const hooks = JSON.parse(readFileSync(resolve(root, '.cursor/hooks.json'), 'utf8'));
+    assert.equal(hooks.hooks.postToolUse[0].matcher, 'Write');
+    assert.equal(hooks.hooks.afterFileEdit, undefined);
+    assert.equal(hooks.hooks.afterTabFileEdit[0].matcher, 'TabWrite');
+
+    const script = resolve(root, '.cursor/hooks/contract-loop-gate.mjs');
+    const tabResult = runHook(root, script, {
+      hook_event_name: 'afterTabFileEdit',
+      file_path: sourcePath,
+    });
+    assert.equal(tabResult.status, 0, tabResult.output);
+    assert.equal(tabResult.output, '');
+
+    const result = runHook(root, script, {
+      hook_event_name: 'postToolUse',
+      tool_input: { file_path: sourcePath },
+    });
+    assert.equal(result.status, 0, result.output);
+    assert.match(JSON.parse(result.output).additional_context, /Forward chain:/);
+  });
+});
+
+test('Claude contract-loop adapter stays inert when imported by Cursor', () => {
+  withFixture(root => {
+    const sourcePath = resolve(root, 'vona/src/module/demo/src/controller/demo.ts');
+    mkdirSync(dirname(sourcePath), { recursive: true });
+    writeFileSync(sourcePath, '@Api.field()\n');
+    assert.equal(runGovernance(root, 'render').status, 0);
+    const script = resolve(root, '.claude/hooks/contract-loop-gate.ts');
+    const payload = { hook_event_name: 'PostToolUse', tool_input: { file_path: sourcePath } };
+
+    const claudeResult = runHook(root, script, payload);
+    assert.equal(claudeResult.status, 0, claudeResult.output);
+    assert.match(
+      JSON.parse(claudeResult.output).hookSpecificOutput.additionalContext,
+      /Forward chain:/,
+    );
+
+    const cursorResult = runHook(root, script, payload, {
+      env: { CURSOR_PROJECT_DIR: root },
+    });
+    assert.equal(cursorResult.status, 0, cursorResult.output);
+    assert.equal(cursorResult.output, '');
+  });
+});

package/repo-agent-governance/tools/contract-loop/core.mjs

@@ -100,35 +100,51 @@ export function isCodeFile(filePath) {
   );
 }
 
-function detectForward(filePath, content) {
-  if (!filePath.includes('/vona/src/')) return null;
-  if (
-    pathContainsAny(filePath, FORWARD_PATH_MARKERS) ||
-    containsAny(content, FORWARD_CONTENT_MARKERS)
-  ) {
+function detectForwardPath(filePath) {
+  if (filePath.includes('/vona/src/') && pathContainsAny(filePath, FORWARD_PATH_MARKERS)) {
     return 'Backend contract source may have changed.';
   }
   return null;
 }
 
-function detectReverse(filePath, content, reverseVonaContentMarkers) {
+function detectForwardContent(filePath, content) {
+  if (filePath.includes('/vona/src/') && containsAny(content, FORWARD_CONTENT_MARKERS)) {
+    return 'Backend contract source may have changed.';
+  }
+  return null;
+}
+
+function detectReversePath(filePath) {
+  if (filePath.includes('/zova/src/') && pathContainsAny(filePath, REVERSE_ZOVA_PATH_MARKERS)) {
+    return 'Frontend-owned resources or metadata may affect backend consumers.';
+  }
+  return null;
+}
+
+function detectReverseContent(filePath, content, reverseVonaContentMarkers) {
   if (filePath.includes('/vona/src/') && containsAny(content, reverseVonaContentMarkers)) {
     return 'Vona code is consuming frontend metadata or render resources.';
   }
-  if (
-    filePath.includes('/zova/src/') &&
-    (pathContainsAny(filePath, REVERSE_ZOVA_PATH_MARKERS) ||
-      containsAny(content, REVERSE_ZOVA_CONTENT_MARKERS))
-  ) {
+  if (filePath.includes('/zova/src/') && containsAny(content, REVERSE_ZOVA_CONTENT_MARKERS)) {
     return 'Frontend-owned resources or metadata may affect backend consumers.';
   }
   return null;
 }
 
+export function analyzePath(filePath) {
+  return {
+    forwardReason: detectForwardPath(filePath),
+    reverseReason: detectReversePath(filePath),
+  };
+}
+
 export function analyze(filePath, content, edition) {
+  const pathResult = analyzePath(filePath);
   return {
-    forwardReason: detectForward(filePath, content),
-    reverseReason: detectReverse(filePath, content, getReverseVonaContentMarkers(edition)),
+    forwardReason: pathResult.forwardReason ?? detectForwardContent(filePath, content),
+    reverseReason:
+      pathResult.reverseReason ??
+      detectReverseContent(filePath, content, getReverseVonaContentMarkers(edition)),
   };
 }