cabloy 5.1.190 → 5.1.192

package/{.claude/skills/cabloy-spec-generation/scripts → repo-agent-governance/tools/spec-charts}/generate-implementation-charts.test.mjs

@@ -1,8 +1,9 @@
+import assert from 'node:assert/strict';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { resolve } from 'node:path';
 import { test } from 'node:test';
-import assert from 'node:assert/strict';
+
 import {
   createChartModel,
   generateCharts,
@@ -92,6 +93,51 @@ test('requires formal ATP definitions rather than prose mentions', () => {
   assert.deepEqual([...parseAtpIds('A prose mention of ATP-DEMO-99.')], []);
 });
 
+test('parses progress rows by formal WBS and Status header columns', () => {
+  const progress = parseProgress(
+    [
+      '# Progress',
+      '',
+      '> 最后审查日期： 2026-09-01',
+      '',
+      '| WBS ID | Work item | Status |',
+      '| --- | --- | --- |',
+      '| `WBS-DEMO-01` | Implementation title | `verified` |',
+      '',
+    ].join('\r\n'),
+  );
+  assert.equal(progress.reviewed, '2026-09-01');
+  assert.deepEqual([...progress.rows], [['WBS-DEMO-01', 'verified']]);
+});
+
+test('does not parse prose wildcard ATP references as concrete IDs', () => {
+  const model = parseWbs(
+    [
+      '# Delivery Plan',
+      '',
+      '### Phase 10: Baseline',
+      '',
+      '#### WBS-DEMO-01: Freeze the baseline',
+      '',
+      '- Track every `ATP-DEMO-*` after planning.',
+      '',
+    ].join('\n'),
+  );
+  assert.deepEqual(model.tasks[0].atps, []);
+});
+
+test('rejects malformed WBS headings with a trailing hyphen', () => {
+  assert.throws(
+    () =>
+      parseWbs(
+        ['# Delivery Plan', '', '### Phase 10: Baseline', '', '#### WBS-DEMO-01-: Freeze', ''].join(
+          '\n',
+        ),
+      ),
+    /No formal `#### WBS-…:` tasks/,
+  );
+});
+
 test('creates a mixed-status model with deferred scope separated', () => {
   const model = createChartModel({
     readme: files['README.md'],
@@ -126,8 +172,14 @@ test('renders a phase description directly beneath its phase label', async t =>
   });
   t.after(() => removeFixture(directory));
   const gantt = (await generateCharts(directory)).artifacts.get('implementation-gantt.svg');
-  assert.match(gantt, /<text class="phase" x="72" y="270">Phase 10<\/text><text class="small" x="72" y="283">A deliberately extended<\/text><text class="small" x="72" y="295">&lt;phase&gt; &amp; description that<\/text><text class="small" x="72" y="307">wraps safely<\/text><text class="num" x="265" y="329">WBS-10-01<\/text>/);
-  assert.match(gantt, /<text class="phase" x="72" y="363">Phase 20<\/text><text class="small" x="72" y="376">Delivery<\/text><text class="num" x="265" y="398">WBS-20-01<\/text>/);
+  assert.match(
+    gantt,
+    /<text class="phase" x="72" y="270">Phase 10<\/text><text class="small" x="72" y="283">A deliberately extended<\/text><text class="small" x="72" y="295">&lt;phase&gt; &amp; description that<\/text><text class="small" x="72" y="307">wraps safely<\/text><text class="num" x="265" y="329">WBS-10-01<\/text>/,
+  );
+  assert.match(
+    gantt,
+    /<text class="phase" x="72" y="363">Phase 20<\/text><text class="small" x="72" y="376">Delivery<\/text><text class="num" x="265" y="398">WBS-20-01<\/text>/,
+  );
   assert.doesNotMatch(gantt, /y="432">Delivery<\/text>/);
 });
 
@@ -141,7 +193,10 @@ test('widens and wraps the Dependencies column without covering status', async t
   t.after(() => removeFixture(directory));
   const gantt = (await generateCharts(directory)).artifacts.get('implementation-gantt.svg');
   assert.match(gantt, /<text class="small" x="680" y="246">Dependencies<\/text>/);
-  assert.match(gantt, /<text class="small" x="680" y="\d+"><tspan x="680" dy="0">[^<]+<\/tspan><tspan x="680" dy="12">[^<]+<\/tspan><\/text><circle cx="905" cy="\d+"/);
+  assert.match(
+    gantt,
+    /<text class="small" x="680" y="\d+"><tspan x="680" dy="0">[^<]+<\/tspan><tspan x="680" dy="12">[^<]+<\/tspan><\/text><circle cx="905" cy="\d+"/,
+  );
 });
 
 test('selects Chinese chart copy from a Chinese README', () => {
@@ -156,18 +211,26 @@ test('selects Chinese chart copy from a Chinese README', () => {
 });
 
 test('rejects missing progress rows and dangling ATP references', () => {
-  assert.throws(() => createChartModel({
-    readme: files['README.md'],
-    wbs: files['pdp-wbs.md'],
-    progress: files['progress.md'].replace('| `WBS-20-01` | `in-progress` |\n', ''),
-    testPlan: files['test-plan.md'],
-  }), /WBS-20-01 has no corresponding progress/);
-  assert.throws(() => createChartModel({
-    readme: files['README.md'],
-    wbs: files['pdp-wbs.md'].replace('ATP-DEMO-01', 'ATP-MISSING-01'),
-    progress: files['progress.md'],
-    testPlan: files['test-plan.md'],
-  }), /references undefined ATP-MISSING-01/);
+  assert.throws(
+    () =>
+      createChartModel({
+        readme: files['README.md'],
+        wbs: files['pdp-wbs.md'],
+        progress: files['progress.md'].replace('| `WBS-20-01` | `in-progress` |\n', ''),
+        testPlan: files['test-plan.md'],
+      }),
+    /WBS-20-01 has no corresponding progress/,
+  );
+  assert.throws(
+    () =>
+      createChartModel({
+        readme: files['README.md'],
+        wbs: files['pdp-wbs.md'].replace('ATP-DEMO-01', 'ATP-MISSING-01'),
+        progress: files['progress.md'],
+        testPlan: files['test-plan.md'],
+      }),
+    /references undefined ATP-MISSING-01/,
+  );
 });
 
 test('renders partial burndown progress at its remaining-count position', async t => {
@@ -180,8 +243,14 @@ test('renders partial burndown progress at its remaining-count position', async
   assert.match(burndown, />1 remaining · 1 verified</);
   assert.match(burndown, />2 remaining</);
   assert.doesNotMatch(burndown, />0 \/ 2</);
-  assert.match(burndown, /<line x1="190" y1="410" x2="550\.0" y2="530\.0" stroke="var\(--blue\)" stroke-width="2"\/>/);
-  assert.match(burndown, /<line x1="550\.0" y1="530\.0" x2="910" y2="650" stroke="var\(--blue\)" stroke-width="2" stroke-dasharray="6 5"/);
+  assert.match(
+    burndown,
+    /<line x1="190" y1="410" x2="550\.0" y2="530\.0" stroke="var\(--blue\)" stroke-width="2"\/>/,
+  );
+  assert.match(
+    burndown,
+    /<line x1="550\.0" y1="530\.0" x2="910" y2="650" stroke="var\(--blue\)" stroke-width="2" stroke-dasharray="6 5"/,
+  );
   assert.match(burndown, /<circle cx="550\.0" cy="530\.0" r="8"/);
   assert.doesNotMatch(burndown, /r="14" fill="var\(--aqua\)"/);
 });
@@ -209,7 +278,13 @@ test('writes deterministic XML-escaped artifacts and detects stale output', asyn
   assert.match(first.artifacts.get('implementation-burndown.svg'), /role="img"/);
   assert.equal((await generateCharts(directory, { check: true })).stale.length, 0);
   await writeFile(resolve(directory, 'implementation-gantt.svg'), 'stale');
-  await assert.rejects(() => generateCharts(directory, { check: true }), /implementation-gantt\.svg/);
+  await assert.rejects(
+    () => generateCharts(directory, { check: true }),
+    /implementation-gantt\.svg/,
+  );
   const second = await generateCharts(directory);
-  assert.equal(second.artifacts.get('implementation-gantt.svg'), first.artifacts.get('implementation-gantt.svg'));
+  assert.equal(
+    second.artifacts.get('implementation-gantt.svg'),
+    first.artifacts.get('implementation-gantt.svg'),
+  );
 });

package/repo-docs/.vitepress/config.mjs

@@ -21,6 +21,7 @@ const aiItems = [
     collapsed: true,
     items: [
       { text: 'Repo Guidance', link: '/ai/repo-guidance' },
+      { text: 'Agent Governance', link: '/ai/agent-governance' },
       { text: 'Skills', link: '/ai/skills' },
       { text: 'Docs / Skills Mapping', link: '/ai/docs-skills-rules-mapping' },
       { text: 'CLI to Skill Map', link: '/ai/cli-to-skill-map' },
@@ -245,6 +246,7 @@ export default defineConfig({
           { text: 'Frontend (Zova)', link: '/frontend/introduction', activeMatch: '^/frontend/' },
         ],
       },
+      { text: 'Demo', link: '/demo' },
       { text: 'Blogs', link: '/blogs/', activeMatch: '^/blogs/' },
       { text: 'Editions', link: '/editions/overview', activeMatch: '^/editions/' },
       { text: 'AI Development', link: '/ai/introduction', activeMatch: '^/ai/' },

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

@@ -0,0 +1,80 @@
+# Agent Governance
+
+Cabloy keeps shared AI-development guidance in one authored repository surface while providing adapters for the coding agents used in this repository.
+
+## Canonical source and generated adapters
+
+`repo-agent-governance/` is the canonical source for portable repository rules, root workflow skill bundles, bundled references, deterministic tools, and adapter metadata.
+
+Do not hand-edit generated adapter output. Regenerate it instead:
+
+```bash
+npm run agent:governance:render
+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/`                                       |
+
+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.
+
+### 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.
+
+## Capability boundary
+
+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.
+
+No adapter output owns `settings.local.json`, `CLAUDE.local.md`, worktree state, scheduled-task state, credentials, or arbitrary user-owned agent files.
+
+## Maintain and verify governance assets
+
+Use these commands during repository maintenance:
+
+```bash
+npm run agent:governance:render
+npm run agent:governance:check
+npm run test:agent-governance
+npm run agent:governance:pack-check
+```
+
+`agent:governance:check` is read-only and fails when a committed adapter output or `managed-assets.json` is stale. `agent:governance:pack-check` verifies that the npm package includes the canonical and adapter assets but excludes local state.
+
+For an existing project whose adapter files predate governance ownership, inspect adoption first:
+
+```bash
+npm run agent:governance:adopt
+npm run agent:governance:adopt -- --apply
+```
+
+Adoption creates missing assets and records byte-identical assets. It preserves differing legacy or locally changed managed files as conflicts. Only an explicit path-specific `--force <target>` can replace a conflict.
+
+## Contract-loop tooling
+
+The portable advisory checker accepts a reviewed source path and never starts a build by default:
+
+```bash
+npm run contract:gate -- --file zova/src/suite/<suite>/modules/<module>/src/.metadata/index.ts --format json
+```
+
+Follow [Contract Loop Playbook](/fullstack/contract-loop-playbook) for the full forward, reverse, consumer-drift, and local-dependency-drift workflow. The checker provides a signal and command guidance; it is not proof that generation, build, or dependency refresh has completed.
+
+## Placement rules
+
+Keep the existing Cabloy knowledge boundary:
+
+- `repo-docs/` explains durable workflows for people and agents.
+- `repo-docs-internal/` records supporting maintainer rationale and ADRs.
+- `repo-specs/<suite>/` remains authority for suite product, delivery, acceptance, and evidence records.
+- `repo-agent-governance/` owns portable agent rules, root skill workflows, adapters, and deterministic governance tooling.
+- platform directories are generated runtime/discovery adapters, not a second authored source.
+
+For a broader placement decision, see [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping).

package/repo-docs/ai/cli-to-skill-map.md

@@ -189,10 +189,10 @@ Avoid these mistakes in skills:
 
 ## Current root skill example
 
-The root-level skill:
+The canonical root-level skill:
 
-- `.claude/skills/cabloy-workflow/SKILL.md`
+- `repo-agent-governance/skills/cabloy-workflow/SKILL.md`
 
-already follows this philosophy: detect edition, classify layer, prefer CLI, then verify.
+is rendered to the Claude adapter path and already follows this philosophy: detect edition, classify layer, prefer CLI, then verify.
 
 Future skills should follow the same mapping pattern.

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

@@ -71,49 +71,50 @@ Relevant internal records answer questions like:
 - why is AI enablement structured this way?
 - what invariants should future contributors preserve?
 
-### 4. Rules and commands
+### 4. Agent governance, rules, and commands
 
-Locations:
+Canonical location:
 
-- `CLAUDE.md`
-- `.claude/commands/`
+- `repo-agent-governance/`
 
-Use rules for:
+Generated adapter locations include:
 
-- concise repo-wide operational guidance
-- default behavior Claude should follow in this repo
-- short durable constraints such as edition detection and CLI-first preference
+- policy adapters: `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/`
+- Claude-specific command adapter: `.claude/commands/`
 
-Use commands for:
+Codex and Cursor adapter paths are configured output locations; verify active-client discovery externally before claiming that behavior is supported.
 
-- named recurring operator workflows
-- shorter, explicit actions such as release or future migration helpers
+Use the canonical repository policy for concise repo-wide operational guidance and durable constraints such as edition detection and CLI-first preference. Use canonical commands for named recurring operator workflows such as release.
 
 These layers answer questions like:
 
-- what should Claude check first in this repo?
+- what should an agent check first in this repo?
 - when should CLI be preferred over manual scaffolding?
 - what recurring workflow deserves a named command?
 
 ### 5. Skills
 
-Location:
+Canonical location:
+
+- `repo-agent-governance/skills/`
 
-- `.claude/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.
 
 Use skills for:
 
 - procedural decision trees
 - reusable workflows with branching logic
-- tasks that benefit from bundled references, evals, or future deterministic helpers
+- tasks that benefit from bundled references, evals, or deterministic helpers
 - repo-specific orchestration over CLI and source inspection
 
 Skills answer questions like:
 
-- how should Claude choose the right Cabloy workflow?
+- how should an agent choose the right Cabloy workflow?
 - when should it branch between Basic and Start?
 - what is the right verification path after generation or refactor work?
 
+Do not treat provider hooks, permissions, local settings, or command discovery as portable skill capabilities. These remain platform-specific adapters.
+
 ## Decision rule for authors: where should a new piece of knowledge go?
 
 Use this quick rule:
@@ -121,7 +122,7 @@ Use this quick rule:
 - if people and agents both need to read and understand it, put it in **public docs**
 - if it is product, contract, delivery, ATP, decision, or observed-evidence authority for one suite, use `repo-specs/<suite>/`
 - if it is maintainer rationale or long-lived design history, use `repo-docs-internal/`; shared guidance remains complete without any particular internal record
-- if it is short repo-wide behavioral guidance, put it in **CLAUDE.md**
+- if it is short portable repo-wide behavioral guidance, put it in **`repo-agent-governance/policies/`** and render its adapters
 - if it is a named repeatable operator action, put it in a **command**
 - if it is a reusable procedural workflow with branching, put it in a **skill**
 
@@ -131,26 +132,26 @@ Use this quick rule:
 
 - public explanation → [Cabloy Editions: For AI Development](/editions/overview#for-ai-development)
 - consistency review surface → [Edition Consistency Checklist](/ai/edition-consistency-checklist)
-- repo-wide behavior rule → `CLAUDE.md`
+- repo-wide behavior rule → `repo-agent-governance/policies/`, rendered to generated policy adapters
 - procedural enforcement → `cabloy-workflow` skill
 
 ### Example: “Use Zova CLI refactors before hand-editing page params/query/component props”
 
 - conceptual explanation → public docs in frontend and AI sections
-- default agent behavior → `CLAUDE.md`
+- default agent behavior → `repo-agent-governance/policies/`, rendered to generated policy adapters
 - step-by-step orchestration → `cabloy-workflow` skill or future specialized skills
 
 ### Example: “How should a backend base class be placed?”
 
 - public operational explanation → [Class Placement Rule](/ai/class-placement-rule)
 - maintainer rationale and invariants → `repo-docs-internal/`
-- default repo-wide behavior → `CLAUDE.md`
+- default repo-wide behavior → `repo-agent-governance/policies/`, rendered to generated policy adapters
 - procedural decision workflow → `cabloy-workflow` skill
 
 ### Example: “How should AI look up a backend global bean?”
 
 - public lookup explanation → [Global Bean Lookup](/ai/global-bean-lookup)
-- default repo-wide behavior → `CLAUDE.md`
+- default repo-wide behavior → `repo-agent-governance/policies/`, rendered to generated policy adapters
 - procedural lookup sequence → `cabloy-workflow` skill
 
 ### Example: “How backend OpenAPI becomes frontend SDK”
@@ -161,7 +162,7 @@ Use this quick rule:
 ### Example: “How should one persisted resource serve Admin and Web users?”
 
 - full architecture explanation → [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service)
-- concise repo-wide default → `CLAUDE.md`
+- concise repo-wide default → `repo-agent-governance/policies/repository.md`, rendered to policy adapters
 - contract regeneration, consumer-boundary choice, and verification routing → `cabloy-contract-loop`
 - extend the existing contract-loop skill references and evals; do not create an Order-specific skill
 
@@ -169,7 +170,7 @@ Use this quick rule:
 
 - public operational explanation → [Playbook: Module Removal](/ai/playbook-module-removal)
 - maintainer rationale and pitfalls → `repo-docs-internal/`
-- avoid putting the full workflow in `CLAUDE.md` because the task needs branching, cleanup order, generated-runtime recovery, and verification
+- avoid putting the full workflow in the concise canonical policy because the task needs branching, cleanup order, generated-runtime recovery, and verification
 - procedural decision workflow → `cabloy-module-removal` skill
 
 ### Example: “How should AI plan a new business domain name and structure?”
@@ -177,7 +178,7 @@ Use this quick rule:
 - public naming and suite-first explanation → [Suites and Modules](/fullstack/suites-and-modules)
 - frontend-side naming companion → [Modules and Suites](/frontend/modules-and-suites)
 - keep the durable naming rules in docs instead of duplicating them in repo rules
-- avoid putting the full branching workflow in `CLAUDE.md` because the task needs proposal, validation, confirmation, and CLI handoff
+- avoid putting the full branching workflow in the concise canonical policy because the task needs proposal, validation, confirmation, and CLI handoff
 - procedural decision workflow → `cabloy-domain-planning` skill
 
 ### Example: “How should AI create or maintain a repository-native suite specification?”
@@ -202,13 +203,13 @@ Use this quick rule:
 - full explanation → [Entity Guide](/backend/entity-guide) and [DTO Guide](/backend/dto-guide)
 - AI workflow reminder → [Playbook: Add a Backend Module](/ai/playbook-backend-module)
 - procedural checklist reminder → backend scaffold skill references
-- avoid putting the full explanation only in `CLAUDE.md` because this is a framework-specific authoring rule, not a short global behavior rule
+- avoid putting the full explanation only in the concise canonical policy because this is a framework-specific authoring rule, not a short global behavior rule
 
 ## Anti-patterns to avoid
 
 Avoid these mistakes:
 
-- putting large conceptual explanations in `CLAUDE.md`
+- putting large conceptual explanations in the concise canonical policy
 - using a skill as the only place where an important architectural rule is explained
 - duplicating the same workflow prose across docs and skills without giving each a distinct role
 - creating a command for something that actually needs a branching decision tree

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

@@ -5,9 +5,9 @@ This checklist helps maintainers keep docs, rules, commands, and skills aligned
 Use it whenever you add or revise:
 
 - edition-aware docs
-- `CLAUDE.md` guidance
-- `.claude/commands/`
-- `.claude/skills/`
+- `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
 - AI workflow playbooks
 
 ## The baseline story that should stay consistent
@@ -98,14 +98,15 @@ For scripts, flavors, paths, and examples, confirm that:
 Confirm that the same guidance is distributed correctly:
 
 - **docs** explain the workflow in durable prose
-- **`CLAUDE.md`** captures short repo-wide behavioral rules
+- **`repo-agent-governance/`** owns short portable repo-wide behavioral rules, commands, and root skills
+- **generated adapters** expose that shared guidance to Claude Code, Codex, and Cursor without becoming a second authored source
 - **skills** encode procedural branching and follow-up logic
 - **commands** are used only for named operator workflows, not as the only home for conceptual guidance
 
 Avoid these drifts:
 
 - a skill contains the only explanation of an edition rule
-- `CLAUDE.md` grows into a long architectural essay
+- the concise canonical repository policy grows into a long architectural essay
 - docs duplicate every procedural branch that belongs in a skill
 
 ## Checklist 7: verification guidance matches the edition model
@@ -138,7 +139,8 @@ Before you finish an edition-aware change, ask:
 2. Did I preserve the correct Basic vs Start creation path?
 3. Did I avoid turning UI difference into the whole story?
 4. Did I point Start-specific operational truth back to the active Start repository where needed?
-5. Do docs, rules, and skills each play their proper role?
+5. Do docs, canonical governance, generated adapters, and skills each play their proper role?
+6. Did I regenerate and check every affected adapter without claiming platform-specific automation is portable?
 
 ## Read together with
 

package/repo-docs/ai/future-skill-roadmap.md

@@ -92,9 +92,9 @@ The purpose of the roadmap is not to create many skills.
 The purpose is to create a small number of high-leverage skills that directly reuse the knowledge system now being built in:
 
 - `repo-docs/`
-- `CLAUDE.md`
+- `repo-agent-governance/policies/`
 - `repo-docs-internal/`
-- `.claude/skills/`
+- `repo-agent-governance/skills/`
 - the Vona and Zova CLIs
 
 That is how Cabloy gets long-term value from the documentation work.

package/repo-docs/ai/introduction.md

@@ -11,7 +11,7 @@ The Cabloy monorepo is a good fit for AI vibe coding because the source tree alr
 - Zova CLI source and command groups
 - archived docs that still capture valuable concepts
 - `repo-docs-internal/` engineering docs for maintainers
-- Claude commands and skills
+- agent-neutral repository governance, generated adapters, and deterministic tools
 
 ## The main design goal
 
@@ -32,7 +32,7 @@ For contributor and automation workflows in this repository, prefer this order:
 1. inspect the active edition and repo markers before making UI-sensitive or workflow-sensitive assumptions
 2. inspect root scripts, Vona CLI, and Zova CLI before inventing manual scaffolding or custom workflow steps
 3. use public docs for durable user-facing and agent-facing guidance; consult relevant `repo-docs-internal/` records for supporting maintainer rationale
-4. encode repeatable behavior in Claude rules, commands, or skills instead of relying on unstated habits
+4. encode repeatable behavior in the canonical agent-governance rules, commands, or skills instead of relying on unstated habits
 
 ## The knowledge layers
 
@@ -46,13 +46,13 @@ For normal project usage, prefer the user-facing entry docs such as [Fullstack Q
 
 Use `repo-docs-internal/` for architecture notes, ADRs, and maintainer rationale that should not be mixed into public how-to documentation. Relevant records support a shared workflow without being prerequisites; an unavailable or irrelevant individual record must not cause its rationale to be moved into public how-to documentation automatically.
 
-### Claude rules and commands
+### Agent governance and adapters
 
-Use root `CLAUDE.md` and `.claude/commands/` for concise operational behavior and repeatable workflows.
+Use `repo-agent-governance/` as the authored source for portable repository rules, root workflow skills, bundled references, and deterministic tools. It generates committed adapter outputs for Claude Code, Codex, and Cursor. See [Agent Governance](/ai/agent-governance) for the ownership and capability boundary.
 
-### Skills
+### Platform runtime integration
 
-Use `.claude/skills/` for procedural workflows that benefit from reusable instructions, bundled references, or future deterministic scripts.
+`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.
 
 ## AI reading paths
 
@@ -63,6 +63,7 @@ Use this page as the main AI-development hub, then choose the path that matches
 Start here when the task is about choosing the right repo surface, docs location, or automation boundary:
 
 - [Repo Guidance](/ai/repo-guidance)
+- [Agent Governance](/ai/agent-governance)
 - [Docs / Skills Mapping](/ai/docs-skills-rules-mapping)
 - [CLI to Skill Map](/ai/cli-to-skill-map)
 - [Skills](/ai/skills)

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

@@ -10,9 +10,10 @@ Check the root repository signals first:
 - edition marker files such as `__CABLOY_BASIC__` or `__CABLOY_START__`
 - `repo-docs-internal/`
 - `repo-specs/` when the task concerns a suite plan, WBS increment, acceptance record, or evidence
-- root `.claude/` assets
+- `repo-agent-governance/` canonical rules, skill bundles, and deterministic tools
+- generated platform adapter assets such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, and `.cursor/`
 
-These surfaces tell the agent which repo it is in and which scripts are canonical. Inspect relevant `repo-docs-internal/` records as supporting context rather than as a gate to workflow guidance.
+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.
 
 ## 2. Prefer framework entrypoints over scattered examples
 

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

@@ -1,29 +1,37 @@
 # Rules and Config
 
-Cabloy’s AI behavior should be organized into a few clear layers instead of one oversized instruction file.
+Cabloy’s AI behavior is organized into authored governance, generated platform adapters, and platform-local runtime configuration. This prevents the same repository knowledge from drifting across agent-specific directories.
 
-## Root `CLAUDE.md`
+## `repo-agent-governance/`
 
-Use the root `CLAUDE.md` for concise, durable operational guidance such as:
+Use `repo-agent-governance/` as the only authored source for portable repository rules, root procedural skill bundles, bundled references, deterministic tools, and adapter definitions.
 
-- how the monorepo is organized
-- where public docs live
-- where `repo-docs-internal/` holds supporting maintainer rationale
-- which command entrypoints are preferred
-- why edition detection is mandatory before UI-sensitive guidance or project-creation assumptions
+It contains the concise repository policy that adapters render to `CLAUDE.md`, `AGENTS.md`, and Cursor MDC rules. It also owns the source bundles rendered to Claude, Codex, and Cursor skill locations.
 
-## `.claude/commands/`
+Run these maintenance checks after changing governance assets:
 
-Use commands for reusable operator workflows that are naturally invoked as a named action, such as release or future docs migration helpers.
+```bash
+npm run agent:governance:render
+npm run agent:governance:check
+npm run test:agent-governance
+```
 
-## `.claude/skills/`
+## Generated platform adapters
 
-Use skills for workflows that need more procedural context, bundled references, or iterative selection logic.
+The following are committed generated outputs, not parallel authored knowledge sources:
 
-## `settings.json` and `settings.local.json`
+- 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/`
 
-Use Claude settings for permissions and execution environment, not as the primary place to explain framework concepts.
+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.
+
+## Local configuration and permissions
+
+Keep local settings, credentials, worktree state, scheduled-task state, and user-owned agent configuration out of the generated ownership surface. In particular, do not overwrite or adopt `settings.local.json`, `CLAUDE.local.md`, or unregistered files merely because they are near an adapter directory.
+
+Use agent settings for permissions and execution environment, not as the primary place to explain framework concepts.
 
 ## Documentation boundary
 
-If a rule is important for people and agents to understand, it probably belongs in public docs too. `repo-docs-internal/` holds supporting maintainer rationale rather than user-facing workflow; individual records may vary by edition.
+If a rule is important for people and agents to understand, it belongs in public docs as well. `repo-docs-internal/` holds supporting maintainer rationale rather than user-facing workflow; individual records may vary by edition. See [Agent Governance](/ai/agent-governance) for the complete ownership, adoption, and package-distribution model.