contract-sync-check

mustflow_doc: skill.contract-sync-check locale: en canonical: true revision: 3 lifecycle: mustflow-owned authority: procedure name: contract-sync-check description: Apply this skill when a change affects a declared contract that must stay aligned across code, schemas, templates, tests, and documentation. metadata: mustflow_schema: "1" mustflow_kind: procedure pack_id: mustflow.core skill_id: mustflow.core.contract-sync-check command_intents: - changes_status - changes_diff_summary - docs_validate_fast - test_release - mustflow_check

Contract Sync Check

Purpose

Keep declared behavior, machine-readable contracts, installed templates, tests, and public documentation from drifting apart after a change.

Use When

• A command, option, JSON output, schema, template file, manifest, lock entry, preference, or public document changes.
• A change adds, removes, renames, or reclassifies a mustflow-owned file.
• Tests encode expected package, template, schema, command, dashboard, or documentation behavior.
• A user asks whether documentation, configuration, or installed template behavior should be updated together.

Do Not Use When

• The task is a private implementation refactor with no declared contract or public surface.
• The changed files are already covered by a narrower skill whose procedure explicitly checks every affected contract.
• The user explicitly asks for a local experiment that should not update published or installed surfaces.

Required Inputs

• Changed-file list and intended behavior change.
• The primary contract source, such as code, schema, config, template metadata, or documentation.
• Known derived surfaces: tests, README, docs site, localized templates, manifests, lock files, JSON Schemas, language-level marker constants, source scanners, and validator allowlists.
• Relevant command-intent contract entries.

Preconditions

• The task matches the Use When conditions and does not match the Do Not Use When exclusions.
• Required inputs are available, or missing inputs can be reported without guessing.
• Higher-priority instructions and .mustflow/config/commands.toml have been checked for the current scope.

Allowed Edits

• Update only the surfaces required to keep the contract consistent.
• Add or adjust tests only when they encode the changed contract or packaging surface.
• Mark translations or prose-heavy docs for review when exact wording cannot be confidently localized.
• Do not broaden command permissions, invent new contract files, or convert exploratory notes into binding policy.

Procedure

1. Name the contract being changed and identify its source of truth.
2. If multiple files appear to define the contract, resolve source authority before editing:
   • command behavior: current code and command contract first, then schemas, tests, and docs;
   • JSON or package contract: schema and package metadata first, then code, tests, and docs;
   • installed template contract: template manifest and template source files first, then lock files, i18n metadata, tests, and docs;
   • workflow authority: nearest AGENTS.md, .mustflow/config/*.toml, and skill/index metadata before explanatory docs;
   • prose examples: executable behavior and maintained docs before README snippets or fixtures. If no authority is clear, stop and report the competing sources instead of choosing silently.
3. List the expected synchronized surfaces for that contract: source code, schemas, command metadata, templates, manifests, lock files, tests, README, docs site, and localized copies.
4. Compare the changed files with that list and add any missing required surface.
5. Keep derived files mechanically aligned with the source of truth. If a surface is intentionally not updated, record the reason.
   • When a machine-readable contract defines policy, treat TypeScript constants, Rust or Go marker arrays, docs prose, fixtures, template copies, and linter allowlists as derived unless the repository explicitly declares otherwise.
   • If the same security, privacy, cost, tier, ownership, or boundary decision appears in more than one place, choose the canonical identity and value first, then validate duplicate copies for consistency instead of reading the most convenient duplicate.
   • Prefer removing duplicate constants or loading a shared contract over adding a second hand-maintained list. If duplication remains, add a drift check or name the remaining manual sync risk.
   • In cross-language skeletons, prefer the existing parser, source scan, or contract validator when it can prove the drift cheaply. Add a new runtime dependency solely for cross-language drift only when the lighter guard cannot cover the contract and the tradeoff is reported.
   • When the runtime is not implemented yet, add narrow first-line guards such as source-pattern tests only for forbidden paths that are observable now. Report that those guards prevent obvious drift but do not prove full runtime correctness.
6. Check that command intent names, schema ids, frontmatter revisions, template entries, version strings, documented examples, marker constants, and source-pattern guards match exactly where they are meant to match.
7. Use the narrowest configured verification that covers the contract and any packaging or documentation surface touched.
8. In the final report, separate synchronized surfaces from skipped or deferred surfaces.

Postconditions

• The contract source and every required derived surface agree.
• Duplicated policy constants, language markers, source scanners, and validator allowlists are synchronized with the canonical contract or explicitly reported as deferred drift risk.
• Any intentionally stale, deferred, or review-needed surface is explicitly named.
• The final report includes the command intents used to verify contract alignment.

Verification

Use configured oneshot command intents when available:

• changes_status
• changes_diff_summary
• docs_validate_fast
• test_release
• mustflow_check

Also run a narrower configured test or build intent if the contract affects executable behavior.

Failure Handling

• If validation finds drift, fix the first contract mismatch before adding new behavior.
• If the source of truth is unclear, stop and report the competing sources instead of picking one silently.
• If a required surface is too broad to verify in the current task, report the skipped surface and its risk.
• If localized surfaces cannot be confidently updated, keep source metadata accurate and mark those translations for review.

Output Format

• Contract changed
• Source of truth used
• Synchronized surfaces
• Deferred or review-needed surfaces
• Command intents run
• Skipped checks and reasons
• Remaining drift risk