Cabloy Contract Loop

Cabloy Contract Loop

Use this skill when a backend contract change needs to be reflected in frontend consumers, when frontend-owned metadata or resources need to be reflected back into backend consumers, or when either side appears stale and you need to diagnose where drift actually lives.

Read the public Contract Loop Playbook for the canonical bidirectional model. This skill is the branching orchestration guide.

Important recovery note for stale local file consumers

When the generated .zova-rest artifacts or other generated consumer artifacts already contain the expected new keys or types but Vona still sees stale consumer types, treat that first as a local dependency drift problem rather than a source-editing problem.

This includes the reverse fullstack direction where newly added frontend resources such as custom renderers are later consumed by backend metadata.

In that situation:

1. run the normal sync or regeneration flow first
2. identify every affected flavor from the active repository’s root wrappers and lower-level Zova scripts, then run each matching paired SSR/REST build before npm run deps:vona
   • npm run build:zova:admin and npm run build:zova:web are representative default wrappers only
   • an independently named site must use its own source-confirmed paired root wrapper; do not relabel or assume a default wrapper refreshed it
3. do not treat build:rest:* alone as sufficient, because the SSR bundle and rest output must move together
4. run npm run deps:vona after the required flavor builds
5. if the generated .zova-rest artifacts already contain the expected changes but Vona still sees stale types, delete vona/node_modules and reinstall dependencies

Do not keep debugging source-level contract or renderer changes until the local file-package installation state is known to be healthy.

Current safeguard behavior in this repo

• there is no contract-loop pre-commit gate in the current repo workflow
• 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

Goals

1. detect whether the active repository is Cabloy Basic or Cabloy Start
2. classify whether the task truly crosses the backend/frontend contract boundary
3. route the task into one of four modes: forward chain, reverse chain, consumer drift diagnosis, or local dependency drift recovery
4. keep the workflow contract-first instead of hand-patching generated frontend types or services
5. prefer CLI-first regeneration paths on both Vona and Zova sides
6. finish with end-to-end verification guidance that checks both contract production and consumption

Step 1: Detect repo, edition, and branch

Check the repository root for these marker files:

• __CABLOY_BASIC__
• __CABLOY_START__

Interpretation:

• only __CABLOY_BASIC__ present → this is Cabloy Basic
• only __CABLOY_START__ present → this is Cabloy Start
• both markers present → treat the repository as ambiguous or invalid and stop before making edition-specific assumptions
• neither marker present → inspect the owning package scripts and nearby repository structure, then ask before making an edition-specific assumption

Then classify whether the task is really a contract-loop task.

These four modes are shared across Cabloy Basic and Cabloy Start. Edition detection chooses the operational branch, but does not change the core contract-loop model.

Use this skill in four common entry modes.

Mode A: forward chain

The user already changed or plans to change backend contract surfaces such as:

• controller request or response shape
• DTO shape
• entity field shape that feeds API-facing contracts
• validation rules
• OpenAPI metadata
• inferred DTO or ORM DTO output that affects API consumers

Mode B: reverse chain

The user changed or plans to change frontend-owned resources or metadata that backend-side tooling or metadata will later consume, such as:

• routes
• components
• icons
• custom form-field resources
• custom table-cell resources
• generated frontend metadata that backend ZovaRender.*(...) references depend on

Mode C: consumer drift diagnosis

The user reports symptoms on the frontend side such as:

• stale SDK types
• stale schema-driven UI behavior
• API/model consumers no longer matching backend reality
• hand-patched frontend types that seem to drift from backend truth

In this mode, first diagnose whether the visible stale behavior comes from skipped regeneration, a wrong source-of-truth edit, or a stale generated consumer.

Mode D: local dependency drift recovery

Use this mode when generated artifacts already contain the expected keys, types, or resources, but installed local file dependencies still behave stale after the normal sync flow.

Mode E: independent SSR flavor and site

Use this mode when the request adds a deployable Zova SSR surface that Vona must dispatch separately. This is more than a page or route inside an existing site.

Before proposing implementation, inspect the active repository rather than inferring names from Admin or Web:

1. edition marker and root package.json wrappers;
2. zova/package.json or its durable source for matching dev:ssr:*, build:ssr:*, and build:rest:* scripts;
3. flavor env/config and its SITE_ID, mount path, SSR profile, and artifact-copy targets;
4. a Vona @SsrSite(...) baseline and the owning site-module asset path;
5. the expected SSR release directory and flavor-specific zova-rest-* package.

The independent identity tuple—flavor, site ID, public path, bundle path, REST package, Vona site module, and root paired-build wrapper—must be selected together. The root wrapper must build both SSR and REST output before npm run deps:vona; build:rest:* alone is not enough. Default Basic or Start Admin/Web wrappers are validated specimens, not a command template for a differently named site.

Read Independent SSR Site and Flavor Setup for the canonical setup and evidence procedure.

If the task is only backend scaffolding or only frontend scaffolding, the more specialized scaffold skills may be the better primary choice.

Step 2: Start from the contract source of truth

Inspect these surfaces before proposing workflow:

• the repository or workspace package.json that owns the scripts
• backend contract-defining code in Vona
• npm run zova
• frontend generation or consumption path in Zova
• relevant docs in repo-docs/fullstack/, repo-docs/backend/, and repo-docs/frontend/

For deeper reference material, read:

• references/contract-loop-map.md
• references/verification-checklist.md
• references/resource-custom-state-pattern.md
• ../../../repo-docs/fullstack/admin-resource-and-web-self-service.md

Step 3: Identify the contract source of truth deliberately

In Cabloy, the backend is often the source of truth for the contract. Treat that as the default unless the codebase clearly shows a frontend-owned artifact that the reverse chain should hand back into backend consumers.

If this is the forward chain

Start with the backend side and update the contract deliberately.

Typical backend layers to inspect or change include:

• controller action signatures and annotations
• DTO classes
• entity field metadata
• validation rules and v helpers
• inferred DTO generation paths
• OpenAPI configuration or metadata annotations

The key rule is:

• do not patch frontend consumers first if the backend contract is the real source of truth

If this is the reverse chain

Start with the frontend-owned resource or metadata that backend consumers later depend on.

Typical frontend layers to inspect or change include:

• routes
• components
• icons
• custom form-field resources
• custom table-cell resources
• generated metadata that backend ZovaRender.*(...) references depend on

The key rule is:

• do not treat this as frontend-only cleanup if backend consumers depend on the generated handoff

If this is consumer drift diagnosis

Do not assume the visible stale behavior identifies the wrong layer automatically.

Instead:

1. inspect what artifact looks stale
2. identify whether that artifact is generated, schema-driven, or hand-authored
3. inspect the source layer that should feed it
4. only then decide whether the fix is regeneration, source correction, consumer alignment, or a genuine bug

If this is local dependency drift recovery

Only enter this branch after the source layer and generated handoff are already known to be correct.

Step 4: Verify backend contract output before touching frontend consumers

Before regenerating frontend artifacts, confirm the backend-side contract is actually correct.

That may include:

• reviewing controller return contracts
• confirming DTO and validation alignment
• checking Swagger/OpenAPI output
• confirming that the changed endpoint or schema now reflects the intended contract
• if local OpenAPI generation depends on a running Swagger source, starting the backend service first — in Cabloy Basic, npm run dev is the normal path and exposes http://localhost:7102/swagger/json?version=V31

If the backend contract output is wrong, frontend regeneration will only spread the mistake.

Step 5: Choose the right frontend regeneration path

Once the backend contract is correct, decide how the frontend should consume it.