cabloy 5.1.190 → 5.1.192

package/.cabloy-version

@@ -1 +1 @@
-5.1.190
+5.1.192

package/.github/workflows/agent-governance.yml

@@ -0,0 +1,39 @@
+name: agent-governance
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v5
+        with:
+          version: 11.5.2
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+      - name: install root dependencies
+        run: pnpm install --frozen-lockfile
+      - name: install docs dependencies
+        run: pnpm --dir repo-docs install --frozen-lockfile
+      - name: verify agent-governance assets
+        run: |
+          npm run test:agent-governance
+          npm run agent:governance:check
+          npm run agent:governance:pack-check
+          npm run test:spec-charts
+          npm run spec:charts:check -- a-commerce
+      - name: build documentation
+        run: npm run docs:build

package/.github/workflows/docs-pages.yml

@@ -5,6 +5,7 @@ on:
       - main
     paths:
       - 'repo-docs/**'
+      - 'repo-agent-governance/**'
       - 'repo-e2e/docs/**'
       - 'package.json'
       - 'pnpm-lock.yaml'

package/.gitignore

@@ -78,3 +78,6 @@ vona/docker-compose.yml
 !/zova/packages-utils/quasar-app-extension-zova/dist
 
 **/assets/site
+
+**/.claude/scheduled_tasks.lock
+.cabloy-agent-governance-state.json

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 5.1.192
+
+### Features
+
+- Update core functionality.
+- Add agents for Claude Code, Codex, and Cursor.
+
+## 5.1.191
+
+### Features
+
+- Update functionality with the latest enhancements.
+
+### Improvements
+
+- Refresh the demo and documentation in the README and index pages.
+
 ## 5.1.190
 
 ### Features

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/cabloy.svg?style=flat-square&label=cabloy)](https://www.npmjs.com/package/cabloy)
 [![npm downloads](https://img.shields.io/npm/dm/cabloy?color=orange&label=downloads)](https://www.npmjs.com/package/cabloy)
 [![Docs](https://img.shields.io/badge/docs-cabloy-4f46e5.svg?style=flat-square)](https://cabloy.com)
-[![Demo](https://img.shields.io/badge/demo-cabloy.com-059669.svg?style=flat-square)](https://cabloy.com)
+[![Demo](https://img.shields.io/badge/demo-cabloy.com-059669.svg?style=flat-square)](https://cabloy.com/demo)
 
 Cabloy is a Node.js fullstack framework for AI vibe coding, with AI Spec-Driven Development for traceable, evidence-backed delivery.
 
@@ -12,7 +12,7 @@ Cabloy is a Node.js fullstack framework for AI vibe coding, with AI Spec-Driven
 
 Instead of stitching separate backend and frontend stacks together, Cabloy keeps their contracts, tooling, and guidance connected in one repository. [AI Spec-Driven Development](https://cabloy.com/ai/ai-spec-driven-development) provides the disciplined path from confirmed Specs to evidence-backed delivery; its precise engineering method is Traceable Spec Delivery. Vona is its backend framework and runtime layer, and Zova is its frontend framework and application layer. Cabloy Basic and Cabloy Start are related, complete edition baselines built on that shared architecture; see [Editions Overview](https://cabloy.com/editions/overview) for their deliberate differences.
 
-[Documentation](https://cabloy.com) · [npm](https://www.npmjs.com/package/cabloy) · [Web Demo](https://cabloy.com) · [Admin Demo](https://cabloy.com/admin) · [GitHub](https://github.com/cabloy/cabloy)
+[Documentation](https://cabloy.com) · [npm](https://www.npmjs.com/package/cabloy) · [Demo](https://cabloy.com/demo) · [GitHub](https://github.com/cabloy/cabloy)
 
 ## Fullstack Principles
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.190",
+  "version": "5.1.192",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -57,9 +57,9 @@
     "format:fix": "oxfmt --write",
     "lint": "oxlint --disable-nested-config",
     "lint:fix": "oxlint --disable-nested-config --fix",
-    "test:spec-charts": "node --test .claude/skills/cabloy-spec-generation/scripts/generate-implementation-charts.test.mjs",
-    "spec:charts": "node ./.claude/skills/cabloy-spec-generation/scripts/generate-implementation-charts.mjs",
-    "spec:charts:check": "node ./.claude/skills/cabloy-spec-generation/scripts/generate-implementation-charts.mjs --check",
+    "test:spec-charts": "node --test repo-agent-governance/tools/spec-charts/generate-implementation-charts.test.mjs",
+    "spec:charts": "node ./repo-agent-governance/tools/spec-charts/generate-implementation-charts.mjs",
+    "spec:charts:check": "node ./repo-agent-governance/tools/spec-charts/generate-implementation-charts.mjs --check",
     "docs:dev": "pnpm --dir repo-docs docs:dev",
     "docs:build": "pnpm --dir repo-docs docs:build",
     "docs:preview": "pnpm --dir repo-docs docs:preview",
@@ -72,7 +72,13 @@
     "release:changelog": "node scripts/release.ts --changelog-only",
     "release:publish": "node scripts/release.ts --publish-only",
     "release:github": "node scripts/release.ts --release-only",
-    "prepare": "husky"
+    "prepare": "husky",
+    "agent:governance:render": "node repo-agent-governance/scripts/governance.mjs render",
+    "agent:governance:check": "node repo-agent-governance/scripts/governance.mjs check",
+    "agent:governance:adopt": "node repo-agent-governance/scripts/governance.mjs adopt",
+    "test:agent-governance": "node --test repo-agent-governance/tests/*.test.mjs",
+    "contract:gate": "node repo-agent-governance/tools/contract-loop/check.mjs",
+    "agent:governance:pack-check": "node repo-agent-governance/scripts/pack-check.mjs"
   },
   "devDependencies": {
     "@cabloy/dotenv": "^1.2.8",

package/repo-agent-governance/adapters/claude/contract-loop-gate.ts

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import type { SpawnSyncReturns } from 'node:child_process';
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync, writeFileSync, existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  analyze,
+  buildMessages,
+  isCodeFile,
+  isHighConfidenceReverseSource,
+  normalizePath,
+  resolveEdition,
+  toPosixPath,
+} from '../../repo-agent-governance/tools/contract-loop/core.mjs';
+
+interface EditionConfig {
+  id: 'basic' | 'start';
+  label: string;
+  reverseAutoSyncCommands: ReadonlyArray<{ args: readonly string[]; display: string }>;
+}
+
+interface HookPayload {
+  tool_input?: {
+    file_path?: string;
+  };
+}
+
+interface SyncStateEntry {
+  fingerprint: string;
+  timestamp: number;
+}
+
+type ReverseSyncOutcome =
+  | { kind: 'not-applicable'; message: string }
+  | { kind: 'skipped'; message: string }
+  | { kind: 'success'; message: string }
+  | { kind: 'failure'; message: string };
+
+type SyncState = Record<string, SyncStateEntry>;
+
+const SCRIPT_FILE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(SCRIPT_FILE), '../..');
+const ROOT_KEY = toPosixPath(ROOT);
+const STATE_FILE = path.join(os.tmpdir(), 'cabloy-contract-loop-gate-state.json');
+const AUTO_SYNC_WINDOW_SECONDS = 300;
+
+function readText(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function loadState(): SyncState {
+  if (!existsSync(STATE_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, 'utf8')) as SyncState;
+  } catch {
+    return {};
+  }
+}
+
+function saveState(state: SyncState): void {
+  try {
+    writeFileSync(STATE_FILE, JSON.stringify(state), 'utf8');
+  } catch {
+    // State prevents duplicate convenience syncs only; it must not block guidance.
+  }
+}
+
+function syncFingerprint(filePath: string): string {
+  try {
+    const stats = statSync(filePath, { bigint: true });
+    return `${filePath}:${stats.mtimeNs.toString()}`;
+  } catch {
+    return filePath;
+  }
+}
+
+function shouldSkipAutoSync(filePath: string): boolean {
+  const state = loadState();
+  const entry = state[ROOT_KEY];
+  return Boolean(
+    entry &&
+    entry.fingerprint === syncFingerprint(filePath) &&
+    Date.now() - entry.timestamp <= AUTO_SYNC_WINDOW_SECONDS * 1000,
+  );
+}
+
+function markAutoSync(filePath: string): void {
+  const state = loadState();
+  state[ROOT_KEY] = { fingerprint: syncFingerprint(filePath), timestamp: Date.now() };
+  saveState(state);
+}
+
+function runNpm(args: readonly string[]): SpawnSyncReturns<string> {
+  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return spawnSync(command, [...args], { cwd: ROOT, encoding: 'utf8' });
+}
+
+function summarizeProcess(result: SpawnSyncReturns<string>): string {
+  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(filePath: string, edition: EditionConfig): ReverseSyncOutcome {
+  for (const command of edition.reverseAutoSyncCommands) {
+    const result = runNpm(command.args);
+    if (result.status !== 0) {
+      return {
+        kind: 'failure',
+        message: `Auto-sync failed during \`${command.display}\`: ${summarizeProcess(result)}`,
+      };
+    }
+  }
+  markAutoSync(filePath);
+  return {
+    kind: 'success',
+    message: `Auto-sync ran ${edition.reverseAutoSyncCommands
+      .map(command => `\`${command.display}\``)
+      .join(' and ')} for this ${edition.label} reverse-chain edit.`,
+  };
+}
+
+function resolveReverseSyncOutcome(
+  filePath: string,
+  reverseReason: string | null,
+): ReverseSyncOutcome {
+  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(filePath)) {
+    return {
+      kind: 'skipped',
+      message:
+        'Auto-sync skipped because the same reverse-source edit was already synced recently in this repo.',
+    };
+  }
+  return autoSyncReverse(filePath, resolution.edition);
+}
+
+function runClaudeHook(): number {
+  let payload: HookPayload;
+  try {
+    payload = JSON.parse(readFileSync(0, 'utf8')) as HookPayload;
+  } catch {
+    return 0;
+  }
+  const filePath = normalizePath(ROOT, payload.tool_input?.file_path);
+  if (!filePath || !isCodeFile(filePath)) return 0;
+  const content = readText(filePath);
+  if (content === null) return 0;
+
+  const resolution = resolveEdition(ROOT);
+  const result = analyze(
+    filePath,
+    content,
+    resolution.kind === 'resolved' ? resolution.edition : null,
+  );
+  if (!result.forwardReason && !result.reverseReason) return 0;
+
+  const reverseSyncOutcome = resolveReverseSyncOutcome(filePath, result.reverseReason);
+  const message = buildMessages(result, resolution, reverseSyncOutcome);
+  // eslint-disable-next-line
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
+      systemMessage: message,
+    }),
+  );
+  return 0;
+}
+
+process.exit(runClaudeHook());

package/{.claude → repo-agent-governance}/commands/release.md

@@ -24,31 +24,31 @@ The release script at `scripts/release.ts` performs 4 steps for the public `cabl
 
 Only after the Basic preflight above succeeds, use the matching script that exists in the active root `package.json`:
 
-| Command | Description |
-|---------|-------------|
-| `pnpm release-patch` | Full release with patch version bump |
-| `pnpm release-minor` | Full release with minor version bump |
-| `pnpm release-major` | Full release with major version bump |
-| `pnpm release` | Full release with default patch bump |
-| `pnpm release:dry-run` | Preview what would happen without executing |
-| `pnpm release:changelog` | Only generate changelog (no version bump) |
-| `pnpm release:publish` | Only publish to npm |
-| `pnpm release:github` | Only create GitHub release |
+| Command                  | Description                                 |
+| ------------------------ | ------------------------------------------- |
+| `pnpm release-patch`     | Full release with patch version bump        |
+| `pnpm release-minor`     | Full release with minor version bump        |
+| `pnpm release-major`     | Full release with major version bump        |
+| `pnpm release`           | Full release with default patch bump        |
+| `pnpm release:dry-run`   | Preview what would happen without executing |
+| `pnpm release:changelog` | Only generate changelog (no version bump)   |
+| `pnpm release:publish`   | Only publish to npm                         |
+| `pnpm release:github`    | Only create GitHub release                  |
 
 Do not infer equivalent commands in Cabloy Start when this table is absent from its package scripts.
 
 ## CLI Options
 
-| Option | Description |
-|--------|-------------|
-| `--dry-run` | Show what would happen without executing |
-| `--changelog-only` | Only generate changelog (no version bump) |
-| `--publish-only` | Only publish to npm |
-| `--release-only` | Only create GitHub release |
-| `--skip-changelog` | Skip changelog generation |
-| `--skip-publish` | Skip npm publish |
-| `--skip-release` | Skip GitHub release |
-| `--no-ai` | Use raw commit list instead of AI for changelog |
+| Option             | Description                                     |
+| ------------------ | ----------------------------------------------- |
+| `--dry-run`        | Show what would happen without executing        |
+| `--changelog-only` | Only generate changelog (no version bump)       |
+| `--publish-only`   | Only publish to npm                             |
+| `--release-only`   | Only create GitHub release                      |
+| `--skip-changelog` | Skip changelog generation                       |
+| `--skip-publish`   | Skip npm publish                                |
+| `--skip-release`   | Skip GitHub release                             |
+| `--no-ai`          | Use raw commit list instead of AI for changelog |
 
 ## Execution