| name | sync-contracts |
| description | Verify and reconcile the frozen public-surface contracts under contracts/MANUL_*_CONTRACT.md against the current code. Invoke when the user says "check contracts", "are contracts up to date", "sync contracts", or after any change that touches the DSL grammar, CLI flags, ManulEngine/ManulSession ctor, EngineConfig fields, hooks, reporter JSON, or scoring weights. |
sync-contracts
The eight files under contracts/ describe the frozen public surface of ManulEngine. They are the single source of truth that AI assistants, downstream users, and CI consult. Code drift away from these contracts is a silent regression.
| Contract | Covers |
|---|
MANUL_API_CONTRACT.md | ManulSession, ManulEngine ctor kwargs, public methods, __all__ exports |
MANUL_CLI_CONTRACT.md | manul CLI subcommands and flags |
MANUL_CONFIG_CONTRACT.md | EngineConfig fields, env vars, manul_engine_configuration.json schema |
MANUL_DEBUG_CONTRACT.md | Debug protocol (markers, tokens, extension JSON shape) |
MANUL_DSL_CONTRACT.md | .hunt file grammar — keywords, headers, blocks |
MANUL_HOOKS_CONTRACT.md | @before_all / @after_group / CALL PYTHON |
MANUL_REPORTING_CONTRACT.md | MissionResult / BlockResult / StepResult JSON shape |
MANUL_SCORING_CONTRACT.md | Heuristic scoring channels and weights |
When to invoke
- User says "check contracts", "sync contracts", "are docs in sync", "перевір контракти".
- After any of these code changes:
- Adding/removing/renaming a kwarg on
ManulEngine.__init__ or ManulSession.__init__.
- Adding/removing an entry in
manul_engine/__init__.py:__all__.
- Adding/removing/renaming an
EngineConfig field.
- Adding/removing a CLI flag in
manul_engine/cli.py.
- Adding/removing/renaming a step kind (combine with the
add-step-kind skill).
- Editing
manul_engine/scoring.py weights or thresholds.
- Editing
manul_engine/reporting.py dataclasses.
- Editing the debug-protocol markers in
manul_engine/debug.py.
Execution order
- Detect what changed.
git diff --name-only main…HEAD (or vs the branch the user names). Map each changed file to the contract(s) it potentially impacts using the table above.
- For each impacted contract, read the contract and the corresponding source. Diff the list of names (kwargs, fields, keywords, flags) — not implementation. Surface every addition/removal/rename to the user.
- Update the contract to mirror the code. Keep the contract style — these files use a tight reference-doc tone, not tutorials. Don't add narrative.
- Cross-file mirrors.
.github/copilot-instructions.md and custom-instructions/repo/.github/copilot-instructions.md reference contract names; spot-check them with grep.
- Version bump. Any contract change is a public-surface change → invoke the
bump-version skill before the PR is opened.
- Report. Output a short table:
<contract> | <change> | <line> so the user can verify nothing slipped in.
What is NOT a contract change
- Internal helpers in
helpers.py, scoring.py private functions, _DebugMixin private methods (anything _underscore-prefixed).
- Refactors that preserve public names and behavior.
- Bug fixes that align code with what the contract already says — the contract was right, the code was wrong.
Common mistakes to avoid
- "Updating the contract to match a bug" — if the contract is correct and the code drifted, fix the code, not the contract.
- Skipping the version bump after a contract change. Public surface change without a version bump is invisible to downstream users.
- Editing only one of the mirrored copilot-instructions files. Always touch both, or use
bump_version.py which knows about both.
- Adding marketing prose. These contracts are reference material — terse, factual, exhaustive.
Reference
- Contracts:
contracts/MANUL_*_CONTRACT.md (repo-root relative)
- Public API mirror:
manul_engine/__init__.py:__all__
- Mirrored AI instructions:
.github/copilot-instructions.md, custom-instructions/repo/.github/copilot-instructions.md
