meta|doc=rules|truth=canonical|schema=base.v2|status=active|profile=core

project|name=workflow-cannon|type=module_development_contract|scope=repo
ref|id=principles|target=.ai/PRINCIPLES.md|type=file|status=active
ref|id=human_principles|target=docs/maintainers/PRINCIPLES.md|type=file|status=active
ref|id=module_contract|target=src/contracts/module-contract.ts|type=file|status=active
ref|id=module_registry|target=src/core/module-registry.ts|type=file|status=active
ref|id=module_layout|target=src/modules/README.md|type=file|status=active
ref|id=source_layout|target=src/README.md|type=file|status=active
truth|order=canonical_ai_docs>code_and_config_reality>generated_human_docs>narrative_docs

rule|id=R100|level=must|scope=new_module|directive=implement_workflowmodule_with_registration_contractversion_capabilities_dependencies_optionalPeers_enabledbydefault_config_stateschema_and_instructions|risk=high|approval=none|override=stop|status=active|refs=src/contracts/module-contract.ts|why=rationale_for_R100
rule|id=R101|level=must|scope=module_registration|directive=use_unique_stable_module_id_with_semver_version_explicit_dependson_optionalPeers_array_and_instruction_entries_with_existing_files|risk=high|approval=none|override=stop|status=active|refs=src/core/module-registry.ts|why=rationale_for_R101
rule|id=R112|level=must|scope=module_toggle_behavior|directive=support_runtime_enable_disable_and_reject_enabled_modules_with_disabled_required_dependencies|risk=high|approval=none|override=stop|status=active|refs=src/core/module-registry.ts|why=rationale_for_R112
rule|id=R113|level=must|scope=instruction_driven_modules|directive=define_explicit_function_contract_types_for_options_results_and_evidence_when_instructions_represent_callable_operations|risk=medium|approval=none|override=warn|status=active|refs=src/modules/documentation/types.ts|why=rationale_for_R113
rule|id=R114|level=must|scope=module_command_dispatch|directive=use_a_command_router_that_indexes_enabled_module_instruction_entries_and_dispatches_via_oncommand|risk=medium|approval=none|override=warn|status=active|refs=src/core/module-command-router.ts|why=rationale_for_R114
rule|id=R102|level=must|scope=module_boundaries|directive=depend_only_on_core_and_contracts_and_avoid_direct_imports_from_sibling_modules|risk=medium|approval=none|override=warn|status=active|refs=src/README.md,src/modules/README.md|why=rationale_for_R102
rule|id=R103|level=must|scope=module_behavior|directive=implement_optional_oncommand_dispatch_keep_handlers_deterministic_for_supported_inputs_no_legacy_lifecycle_hooks_unless_contract_adds_them|risk=high|approval=none|override=stop|status=active|refs=src/contracts/module-contract.ts|why=rationale_for_R103
rule|id=R104|level=must|scope=module_docs|directive=generate_and_maintain_human_docs_under_docs_and_ai_docs_under_ai_for_each_module_change|risk=medium|approval=none|override=warn|status=active|refs=docs/maintainers/module-build-guide.md|why=rationale_for_R104
rule|id=R105|level=must|scope=module_tests|directive=add_or_update_tests_that_cover_registration_validation_startup_order_and_primary_command_or_event_paths|risk=high|approval=none|override=stop|status=active|refs=test/module-registry.test.mjs|why=rationale_for_R105
rule|id=R106|level=must|scope=compatibility_changes|directive=preserve_compatibility_or_provide_documented_migration_guidance_when_module_behavior_or_contracts_change|risk=critical|approval=required|override=stop|status=active|refs=.ai/PRINCIPLES.md,docs/maintainers/CHANGELOG.md|why=rationale_for_R106
rule|id=R107|level=must|scope=release_actions|directive=require_human_approval_before_release_execution|risk=critical|approval=required|override=stop|status=active|refs=.ai/PRINCIPLES.md,docs/maintainers/RELEASING.md|why=rationale_for_R107
rule|id=R108|level=must|scope=migration_and_upgrade_path|directive=require_human_approval_before_migration_or_upgrade_path_changes|risk=critical|approval=required|override=stop|status=active|refs=.ai/PRINCIPLES.md|why=rationale_for_R108
rule|id=R109|level=must|scope=policy_and_approval_model|directive=require_human_approval_before_policy_or_approval_model_changes|risk=critical|approval=required|override=stop|status=active|refs=.ai/PRINCIPLES.md|why=rationale_for_R109
rule|id=R110|level=must|scope=principle_conflict|directive=state_conflict_and_request_confirmation_before_proceeding|risk=high|approval=prompt|override=prompt|status=active|refs=.ai/PRINCIPLES.md|why=rationale_for_R110
rule|id=R111|level=must|scope=build_scope|directive=prefer_incremental_reversible_module_slices_over_broad_unbounded_rewrites|risk=medium|approval=none|override=warn|status=active|refs=.ai/PRINCIPLES.md|why=rationale_for_R111

path|slot1=src/contracts/module-contract.ts|role=module_contract|has=WorkflowModule,ModuleRegistration,ModuleLifecycleContext,ModuleCommand|deps=src/core,module_files|check=contract_fields_present|status=active|refs=src/contracts/module-contract.ts
path|slot1=src/core/module-registry.ts|role=module_graph_validation|has=validateModuleSet,ModuleRegistry,topological_sort|deps=src/contracts/module-contract.ts|check=duplicate_missing_cycle_checks|status=active|refs=src/core/module-registry.ts
path|slot1=src/core/module-command-router.ts|role=module_command_dispatch|has=list_commands,alias_resolution,safe_dispatch,typed_router_errors|deps=src/core/module-registry.ts,src/contracts/module-contract.ts|check=enabled_module_dispatch_only|status=active|refs=src/core/module-command-router.ts
path|slot1=src/modules|role=module_implementations|has=registration,optional_oncommand|deps=src/core,src/contracts|xdeps=src/modules/*|check=explicit_dependson|status=active|refs=src/modules/README.md
path|slot1=src/modules/index.ts|role=module_barrel|has=defaultRegistryModules,selective_reexports|deps=module_packages|check=barrel_policy_in_module_build_guide|status=active|refs=docs/maintainers/module-build-guide.md
path|slot1=package.json|role=npm_exports_map|has=root_entry,contracts_subpaths,modules_barrel_subpath|deps=dist|check=semver_additive_exports|status=active|refs=package.json
path|slot1=src/modules/*/instructions|role=module_instruction_surface|has=function_like_instruction_markdown_files|deps=module_registration|check=instruction_entries_match_files|status=active|refs=src/contracts/module-contract.ts
path|slot1=test|role=module_validation_tests|has=module_registry_tests,module_behavior_tests|deps=dist|check=tests_pass|status=active|refs=test/module-registry.test.mjs
path|slot1=.ai|role=canonical_ai_docs|has=module_build_rules,module_specs|deps=repo_state|check=rules_match_implementation|status=active|refs=.ai/module-build.md
path|slot1=docs|role=human_docs|has=maintainer_guides,module_docs|deps=repo_state|check=human_and_ai_doc_parity|status=active|refs=docs/maintainers/module-build-guide.md

workflow|id=W100|name=create_module_slice|when=new_module_required|do=define_module_scope_and_capabilities>create_module_file_under_src_modules_with_registration>declare_dependson_and_implement_oncommand_as_needed>export_module_from_index_files|done=module_compiles+registry_validation_passes|forbid=direct_sibling_module_imports,implicit_dependencies|ask_if=multiple_capability_boundaries_fit|halt_if=contract_version_missing_or_dependency_graph_invalid|approval=none|risk=medium|status=active|refs=src/modules/README.md,src/contracts/module-contract.ts
workflow|id=W104|name=define_module_contract_docs|when=new_module_or_contract_change|do=add_config_md>add_instruction_files_under_instructions_directory>wire_instruction_entries_in_registration|done=config_and_instruction_contracts_present+registration_paths_valid|forbid=instruction_entries_without_backing_files|ask_if=instruction_name_or_scope_is_ambiguous|halt_if=missing_contract_docs_or_bad_paths|approval=none|risk=medium|status=active|refs=src/contracts/module-contract.ts
workflow|id=W101|name=validate_module_behavior|when=module_added_or_changed|do=add_or_update_unit_tests_for_registration_and_behavior>run_test_command>resolve_failures_until_green|done=tests_pass+behavior_paths_covered|forbid=untested_registration_changes|ask_if=acceptance_criteria_ambiguous|halt_if=determinism_break_or_missing_coverage_for_primary_path|approval=none|risk=high|status=active|refs=.workspace-kit/tasks/state.json,test/module-registry.test.mjs
workflow|id=W102|name=publish_module_docs|when=module_contract_or_behavior_changes|do=update_ai_doc_records_for_module_behavior>update_human_module_guide_with_same_decisions>link_generated_outputs_and_evidence_paths|done=ai_doc_and_human_doc_aligned+outputs_defined_for_ai_and_docs|forbid=doc_only_claims_without_code_or_test_evidence|ask_if=source_of_truth_conflict_detected|halt_if=principle_conflict_unresolved|approval=prompt|risk=medium|status=active|refs=.ai/PRINCIPLES.md,docs/maintainers/PRINCIPLES.md
workflow|id=W103|name=module_change_gate_review|when=before_merge_or_release_for_module_work|do=check_approval_requirements_for_release_migration_policy_changes>verify_migration_notes_if_compatibility_impact_exists>record_evidence_and_follow_up_tasks|done=required_approvals_recorded+gates_passed|forbid=release_or_migration_execution_without_required_approval|ask_if=approval_record_missing|halt_if=critical_risk_without_approval|approval=required|risk=critical|status=active|refs=.ai/PRINCIPLES.md,docs/maintainers/RELEASING.md,docs/maintainers/CHANGELOG.md

command|id=C100|name=test|use=pnpm run test|scope=repo|expectation=all_tests_pass|risk=low|status=active
command|id=C101|name=lint|use=pnpm run check|scope=repo|expectation=no_lint_or_type_errors|risk=low|status=active

check|id=K100|scope=module_registration|assertion=registration_includes_id_version_contractversion_capabilities_dependson_enabledbydefault_config_state_and_instructions|when=before_merge|on_fail=stop|status=active|refs=src/contracts/module-contract.ts
check|id=K108|scope=instruction_contract|assertion=instruction_entry_name_maps_to_markdown_file_and_follows_function_like_naming|when=before_merge|on_fail=stop|status=active|refs=src/contracts/module-contract.ts
check|id=K106|scope=module_contract_docs|assertion=config_state_and_instruction_files_exist_and_match_registration|when=before_merge|on_fail=stop|status=active|refs=src/contracts/module-contract.ts
check|id=K107|scope=module_toggle_integrity|assertion=enabled_module_set_has_all_required_dependencies_enabled|when=before_startup|on_fail=stop|status=active|refs=src/core/module-registry.ts
check|id=K109|scope=instruction_runtime_validation|assertion=module_registry_rejects_missing_or_invalid_instruction_files|when=before_startup|on_fail=stop|status=active|refs=src/core/module-registry.ts
check|id=K110|scope=instruction_function_contract|assertion=instruction_driven_modules_publish_typed_options_and_result_contracts_for_generation_operations|when=before_merge|on_fail=warn|status=active|refs=src/modules/documentation/types.ts
check|id=K111|scope=module_command_router|assertion=router_lists_commands_resolves_aliases_and_rejects_unknown_or_duplicate_command_routes|when=before_merge|on_fail=stop|status=active|refs=test/module-command-router.test.mjs
check|id=K101|scope=module_graph|assertion=module_registry_accepts_set_with_no_duplicate_missing_self_or_cycle_dependencies|when=before_merge|on_fail=stop|status=active|refs=src/core/module-registry.ts
check|id=K102|scope=module_testing|assertion=tests_cover_primary_command_or_event_paths_and_pass|when=before_merge|on_fail=stop|status=active|refs=test/module-registry.test.mjs
check|id=K103|scope=documentation_outputs|assertion=ai_documentation_updated_in_ai_and_human_documentation_updated_in_docs_for_module_changes|when=before_merge|on_fail=warn|status=active|refs=.ai/module-build.md,docs/maintainers/module-build-guide.md
check|id=K104|scope=approval_gates|assertion=required_human_approval_recorded_for_release_migration_or_policy_changes|when=before_execution|on_fail=stop|status=active|refs=.ai/PRINCIPLES.md
check|id=K105|scope=definition_of_done|assertion=code_tests_docs_and_evidence_complete_for_assigned_task_scope|when=before_task_close|on_fail=warn|status=active|refs=.workspace-kit/tasks/state.json
