cabloy 5.1.191 → 5.1.192

package/repo-docs/ai/verification.md

@@ -17,7 +17,8 @@ For skills and repo guidance:
 
 - confirm the workflow still points to real command entrypoints
 - confirm edition branches match the active repo markers and scripts
-- confirm public docs, skills, and root `CLAUDE.md` tell the same story
+- confirm public docs, canonical `repo-agent-governance/` assets, and generated platform adapters tell the same story
+- run the deterministic governance checker after changing shared rules, skills, tools, or adapter metadata
 - review edition-aware changes against [Edition Consistency Checklist](/ai/edition-consistency-checklist)
 
 ## Code-generation verification

package/repo-docs/fullstack/contract-loop-playbook.md

@@ -235,7 +235,7 @@ That means:
 
 For resource-bound custom endpoints, prefer `rest-resource.model.resource` as the state owner. A module-local model may still exist, but it should remain a semantic facade instead of becoming a second cache owner. When Admin Resource consumption and Web self-service consumption have genuinely different API, scope, projection, or SSR semantics, see [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service) for the boundary between Admin owner reuse and a dedicated Web model.
 
-See the downstream pattern in `.claude/skills/cabloy-contract-loop/references/resource-custom-state-pattern.md`.
+See the canonical downstream pattern in `repo-agent-governance/skills/cabloy-contract-loop/references/resource-custom-state-pattern.md`.
 
 ### Stage 5: Consumer verification
 

package/repo-docs/fullstack/quickstart.md

@@ -24,7 +24,7 @@ Before creating a new Cabloy project, make sure your environment has:
 npm create cabloy
 ```
 
-The generated project already includes `CLAUDE.md` and the `.claude/` workspace assets. This path creates a Cabloy Basic project baseline. Open this project in Claude Code and start coding immediately with project-specific guidance.
+The generated project includes `repo-agent-governance/` plus committed adapters for Claude Code, Codex, and Cursor. This path creates a Cabloy Basic project baseline. Open it in a supported coding agent and start with the project-specific guidance; regenerate adapters from the canonical governance source rather than editing generated files directly.
 
 `npm create cabloy` automatically runs `npm run init` after creating the project. If you later need to reinstall the project's frontend and backend dependencies, you can run `npm run init` directly.
 

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

@@ -7,11 +7,12 @@ This monorepo is organized around a small set of stable top-level areas.
 - `package.json` — shared scripts and release entrypoints
 - `lerna.json` — package topology
 - `repo-docs-internal/` — edition-local maintainer notes and ADRs
-- `.claude/` — Claude commands, skills, and local settings
+- `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
 - `repo-docs/` — unified public docs
 - `repo-specs/` — suite-local product, technical, delivery, ATP, progress, observed-evidence, and ADR authority
 
-`repo-specs/` is distinct from `repo-docs/`, which explains reusable public guidance, `.claude/`, which contains executable workflow behavior, and `repo-docs-internal/`, which preserves supporting maintainer rationale. For the public planning workflow, see [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation).
+`repo-specs/` is distinct from `repo-docs/`, which explains reusable public guidance, `repo-agent-governance/`, which owns portable executable workflow behavior and adapter generation, and `repo-docs-internal/`, which preserves supporting maintainer rationale. For the public planning workflow, see [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation).
 
 ## Backend side
 

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

@@ -60,7 +60,7 @@ npm run spec:charts -- <suite>
 npm run spec:charts:check -- <suite>
 ```
 
-`spec:charts` refreshes the generated Gantt and burndown SVG views for a chart-compatible `repo-specs/<suite>/` record. `spec:charts:check` validates the supported input contract and detects stale generated views; `test:spec-charts` runs the chart-tool test suite.
+`spec:charts` refreshes the generated Gantt and burndown SVG views for a chart-compatible `repo-specs/<suite>/` record. `spec:charts:check` validates the supported input contract and detects stale generated views; `test:spec-charts` runs the chart-tool test suite. The deterministic implementation lives in `repo-agent-governance/tools/spec-charts/`, not inside a provider-specific skill discovery directory.
 
 ### Chart input contract
 
@@ -75,6 +75,21 @@ A legacy suite with a different WBS or progress-table layout is not chart-compat
 
 These commands do not create planning authority, implement a WBS task, execute an ATP, produce acceptance evidence, or replace traceability/status review. Confirm the active root `package.json` and script input expectations before assuming equivalent behavior in Cabloy Start or another repository.
 
+## Agent-governance maintenance
+
+Use these Cabloy Basic maintenance commands when changing shared agent rules, root skill bundles, or adapter tooling:
+
+```bash
+npm run agent:governance:render
+npm run agent:governance:check
+npm run agent:governance:adopt
+npm run agent:governance:pack-check
+npm run test:agent-governance
+npm run contract:gate -- --file <source-path> --format json
+```
+
+The renderer updates committed Claude Code, Codex, and Cursor adapters from `repo-agent-governance/`. The checker is read-only. Adoption preserves locally modified or unowned adapter files as conflicts rather than overwriting them. The contract gate is advisory and does not run builds automatically; use the active edition's verified contract-loop workflow for completion evidence.
+
 ## Cabloy Start entrypoints
 
 Cabloy Start exposes the equivalent Start repository surface:
@@ -104,7 +119,7 @@ Cabloy Start does not expose Basic Commerce or root documentation wrappers.
 
 ## Upgrade
 
-Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect framework files and root manifest entries that an upgrade would synchronize.
+Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect framework files and root manifest entries that an upgrade would synchronize. The upgrader replaces the framework-owned `repo-agent-governance/` source, reconciles only its named package scripts, and uses ownership-aware adapter adoption. It preserves locally modified or legacy adapter outputs as conflicts for explicit review instead of blindly overwriting root Claude, Codex, or Cursor files.
 
 ### Cabloy Basic public projects
 

package/scripts/bootstrapAgentGovernance.mjs

@@ -0,0 +1,81 @@
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const UPGRADE_SOURCE_DIR = resolve(ROOT_DIR, 'node_modules/.cabloy-upgrade');
+const GOVERNANCE_SCRIPT_NAMES = [
+  'test:spec-charts',
+  'spec:charts',
+  'spec:charts:check',
+  'agent:governance:render',
+  'agent:governance:check',
+  'agent:governance:adopt',
+  'agent:governance:pack-check',
+  'test:agent-governance',
+  'contract:gate',
+];
+
+function reconcileGovernancePackageJson(sourceRoot) {
+  const sourcePackagePath = resolve(sourceRoot, 'package.json');
+  if (!existsSync(sourcePackagePath)) return;
+  const projectPackagePath = resolve(ROOT_DIR, 'package.json');
+  const sourcePackage = JSON.parse(readFileSync(sourcePackagePath, 'utf-8'));
+  const projectPackage = JSON.parse(readFileSync(projectPackagePath, 'utf-8'));
+  let changed = false;
+  for (const name of GOVERNANCE_SCRIPT_NAMES) {
+    const command = sourcePackage.scripts?.[name];
+    if (!command) {
+      throw new Error(`Expected governance script in ${sourcePackagePath}: ${name}`);
+    }
+    if (projectPackage.scripts?.[name] === command) continue;
+    projectPackage.scripts ??= {};
+    projectPackage.scripts[name] = command;
+    changed = true;
+  }
+  if (changed) {
+    writeFileSync(projectPackagePath, `${JSON.stringify(projectPackage, null, 2)}\n`);
+    // eslint-disable-next-line no-console
+    console.log('[init] Reconciled agent-governance package scripts');
+  }
+}
+
+function adoptAgentGovernance() {
+  const executable = resolve(ROOT_DIR, 'repo-agent-governance/scripts/governance.mjs');
+  if (!existsSync(executable)) return;
+  try {
+    execFileSync(process.execPath, [executable, 'adopt', '--apply'], {
+      cwd: ROOT_DIR,
+      env: {
+        ...process.env,
+        CABLOY_GOVERNANCE_ROOT: ROOT_DIR,
+      },
+      stdio: 'inherit',
+    });
+  } catch (error) {
+    if (error.status !== 2) throw error;
+    // eslint-disable-next-line no-console
+    console.log(
+      '[init] Agent-governance adoption preserved locally modified or legacy adapter outputs. Review the reported conflicts before explicitly forcing an individual managed target.',
+    );
+  }
+}
+
+export function bootstrapAgentGovernance() {
+  const sourceDir = resolve(UPGRADE_SOURCE_DIR, 'repo-agent-governance');
+  const targetDir = resolve(ROOT_DIR, 'repo-agent-governance');
+  if (existsSync(sourceDir)) {
+    // A pre-governance upgrader has already loaded its own upgrade.ts before it overwrites
+    // scripts/. Replace the canonical source here, before the current initializer adopts
+    // individual adapter outputs.
+    rmSync(targetDir, { recursive: true, force: true });
+    cpSync(sourceDir, targetDir, { recursive: true });
+    reconcileGovernancePackageJson(UPGRADE_SOURCE_DIR);
+  }
+  // The npm package deliberately excludes generated adapter outputs for the migration
+  // release. This also covers a fresh project, where no staged upgrade source exists.
+  adoptAgentGovernance();
+}
+
+bootstrapAgentGovernance();

package/scripts/init.ts

@@ -297,6 +297,7 @@ function initRepoDocs(): void {
 // --- Main ---
 
 checkPnpm();
+exec('node scripts/bootstrapAgentGovernance.mjs');
 pnpmInstall();
 setAppName();
 generateEnvProdLocal();

package/scripts/release.ts

@@ -107,6 +107,19 @@ function readPackageJson(): Record<string, any> {
   return readJson(PACKAGE_JSON_PATH);
 }
 
+function runGovernancePreflight(dryRun?: boolean): void {
+  const commands = [
+    'npm run test:agent-governance',
+    'npm run agent:governance:check',
+    'npm run agent:governance:pack-check',
+  ];
+  // eslint-disable-next-line
+  console.log('\n🔎 Validating agent-governance assets...');
+  for (const command of commands) {
+    execInherited(command, dryRun);
+  }
+}
+
 function assertPublicBasicReleaseSurface(): void {
   const edition = resolveEdition();
   if (edition !== 'basic') {
@@ -949,6 +962,8 @@ async function release(options: ReleaseOptions): Promise<void> {
     process.exit(1);
   }
 
+  runGovernancePreflight(options.dryRun);
+
   // Determine the version to use
   let version: string;
 

package/scripts/upgrade.ts

@@ -30,6 +30,7 @@ const OVERWRITE_DIRS: string[] = [
   '.husky',
   'repo-docs',
   'repo-observability',
+  'repo-agent-governance',
   // vona
   'vona/packages-vona',
   'vona/packages-cli',
@@ -72,10 +73,6 @@ const FRAMEWORK_E2E_SCRIPT_NAMES_CABLOY_BASIC: string[] = ['test:e2e', 'test:e2e
 const FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC = '@playwright/test';
 
 const MERGE_DIRS: string[] = [
-  // Claude project assets
-  '.claude/commands',
-  '.claude/hooks',
-  '.claude/skills',
   // Vona Claude project assets
   'vona/.claude/commands',
   'vona/.claude/skills',
@@ -91,8 +88,6 @@ const BLACKLIST_DIRS: string[] = [
 
 const WHITELIST_FILES: string[] = [
   // root
-  'CLAUDE.md',
-  '.claude/settings.json',
   'tsconfig.json',
   'tsconfig.base.json',
   'tsconfig.base.esm.json',
@@ -280,6 +275,64 @@ function mergeFrameworkE2eAssets(dryRun?: boolean): void {
   }
 }
 
+function reconcileGovernancePackageJson(dryRun?: boolean): void {
+  const projectPackagePath = resolve(ROOT_DIR, 'package.json');
+  const sourcePackagePath = resolve(TEMP_DIR, 'package.json');
+  const projectPackage = readPackageJson(projectPackagePath);
+  const sourcePackage = readPackageJson(sourcePackagePath);
+  const baselineScripts = ['test:spec-charts', 'spec:charts', 'spec:charts:check'];
+  const governanceScripts = [
+    'agent:governance:render',
+    'agent:governance:check',
+    'agent:governance:adopt',
+    'agent:governance:pack-check',
+    'test:agent-governance',
+    'contract:gate',
+  ];
+  const managedScripts = [...baselineScripts, ...governanceScripts];
+  let changed = false;
+  for (const name of managedScripts) {
+    const sourceValue = sourcePackage.scripts?.[name];
+    if (!sourceValue) {
+      if (
+        governanceScripts.includes(name) &&
+        !existsSync(resolve(TEMP_DIR, 'repo-agent-governance'))
+      ) {
+        continue;
+      }
+      throw new Error(`Expected agent-governance script in package.json: ${name}`);
+    }
+    if (projectPackage.scripts?.[name] === sourceValue) continue;
+    changed = true;
+    if (dryRun) {
+      log(`  [dry-run] Set package.json scripts.${name}`);
+    } else {
+      projectPackage.scripts ??= {};
+      projectPackage.scripts[name] = sourceValue;
+    }
+  }
+  if (changed && !dryRun) {
+    writeFileSync(projectPackagePath, `${JSON.stringify(projectPackage, null, 2)}\n`);
+  }
+}
+
+function reconcileGovernanceAssets(dryRun?: boolean): void {
+  const command = 'node repo-agent-governance/scripts/governance.mjs adopt --apply';
+  if (dryRun) {
+    log(`  [dry-run] Run non-destructive governance adoption: ${command}`);
+    return;
+  }
+  try {
+    execSync(command, { cwd: ROOT_DIR, stdio: 'inherit' });
+  } catch (error) {
+    const status = (error as { status?: number }).status;
+    if (status !== 2) throw error;
+    log(
+      '  Agent-governance adoption preserved locally modified or legacy adapter outputs. Review the reported conflicts before explicitly forcing an individual managed target.',
+    );
+  }
+}
+
 function reconcileFrameworkE2ePackageJson(dryRun?: boolean): void {
   if (!isCabloyBasic()) return;
 
@@ -545,7 +598,13 @@ async function main(): Promise<void> {
     selectiveOverwrite(dryRun);
     log('');
 
-    // 4. Reconcile Cabloy Basic framework E2E manifest entries
+    // 4. Reconcile agent-governance manifest entries and managed adapters
+    log('Reconciling agent-governance package entries and managed adapters...');
+    reconcileGovernancePackageJson(dryRun);
+    reconcileGovernanceAssets(dryRun);
+    log('');
+
+    // 5. Reconcile Cabloy Basic framework E2E manifest entries
     if (isCabloyBasic()) {
       log('Reconciling framework-owned E2E package entries...');
       reconcileFrameworkE2ePackageJson(dryRun);

package/zova/pnpm-lock.yaml

@@ -876,7 +876,7 @@ importers:
         specifier: ^5.1.92
         version: link:../zova-core
       zova-suite-a-zova:
-        specifier: ^5.1.165
+        specifier: ^5.1.166
         version: link:../../src/suite-vendor/a-zova
     devDependencies:
       clean-package:
@@ -1109,7 +1109,7 @@ importers:
         specifier: ^5.1.37
         version: link:modules/a-model
       zova-module-a-openapi:
-        specifier: ^5.1.54
+        specifier: ^5.1.55
         version: link:modules/a-openapi
       zova-module-a-router:
         specifier: ^5.1.41
@@ -1133,7 +1133,7 @@ importers:
         specifier: ^5.1.35
         version: link:modules/a-style
       zova-module-a-table:
-        specifier: ^5.1.43
+        specifier: ^5.1.44
         version: link:modules/a-table
       zova-module-a-zod:
         specifier: ^5.1.37