{"record":{"id":"201f2743401c8ea5","repo":"Hmbown/CodeWhale","slug":"bounded-fragment-module-missing-required-marker-m","errorCode":null,"errorMessage":"bounded fragment module missing required marker {marker!r}","messagePattern":"bounded fragment module missing required marker (.+?)","errorType":"exception","errorClass":"RuntimeContractError","httpStatus":null,"severity":"error","filePath":"scripts/check-runtime-contract-budget.py","lineNumber":543,"sourceCode":"        \"ProjectInstructions\",\n        \"Constitution\",\n    ]\n    for name in required_fragments:\n        if f\"Self::{name}\" not in text and f\"{name} =>\" not in text and f'\"{name.lower()}\"' not in text.lower():\n            # Fallback: search for enum variant declaration\n            if not re.search(rf\"\\b{name}\\b\", text):\n                raise RuntimeContractError(\n                    f\"FragmentId missing required variant {name}\"\n                )\n    # Marker stability — these strings are pinned by tests / prefix cache\n    required_markers = [\n        \"<!-- cw:ctx:workspace -->\",\n        \"<!-- cw:ctx:project_instructions -->\",\n        \"<!-- cw:ctx:constitution -->\",\n    ]\n    for marker in required_markers:\n        if marker not in text:\n            raise RuntimeContractError(\n                f\"bounded fragment module missing required marker {marker!r}\"\n            )\n\n    # Project-instruction import must be a typed fragment, not ad-hoc\n    if \"load_project_instruction_fragment\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must expose load_project_instruction_fragment (project-instruction import as typed fragment)\"\n        )\n    if \"PROJECT_INSTRUCTION_CANDIDATES\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must define PROJECT_INSTRUCTION_CANDIDATES\"\n        )\n    # Required candidate files from #3978\n    required_candidates = [\n        \".cursorrules\",\n        \".clinerules\",\n        \".windsurf/rules\",\n        \".gemini\",","sourceCodeStart":525,"sourceCodeEnd":561,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/scripts/check-runtime-contract-budget.py#L525-L561","documentation":"Three HTML comment markers ('<!-- cw:ctx:workspace -->', '<!-- cw:ctx:project_instructions -->', '<!-- cw:ctx:constitution -->') are pinned by unit tests and the KV prefix cache (docs/CACHE.md): they delimit fragment boundaries inside the session-pinned prompt prefix, so changing them invalidates cached prefixes. The gate does an exact substring match over fragments.rs and fails if any marker is missing or altered.","triggerScenarios":"Editing the strings returned by FragmentId::marker(); restyling markers ('<!-- cw:ctx:Workspace -->', extra spaces); switching from HTML comments to another delimiter during a prompt-format change.","commonSituations":"Prompt-format cleanups; renaming the 'cw:' namespace; aligning markers with a new cache scheme without updating the pinned tests and the gate list together.","solutions":["Restore the exact marker strings in FragmentId::marker() in crates/core/src/fragments.rs (lines ~50-57)","If markers must change, update required_markers in scripts/check-runtime-contract-budget.py:536-540 AND the tests pinning them in the same commit, treating it as a cache-invalidating release decision","Diff against a green commit: 'git diff HEAD~1 -- crates/core/src/fragments.rs | grep cw:ctx'"],"exampleFix":"// before (crates/core/src/fragments.rs)\nSelf::Constitution => \"<!-- codewhale:constitution -->\",\n\n// after\nSelf::Constitution => \"<!-- cw:ctx:constitution -->\",","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\ntext = Path(\"crates/core/src/fragments.rs\").read_text(encoding=\"utf-8\")\nfor marker in (\"<!-- cw:ctx:workspace -->\", \"<!-- cw:ctx:project_instructions -->\", \"<!-- cw:ctx:constitution -->\"):\n    assert marker in text, f\"missing pinned marker {marker}\"","typeGuard":"def is_runtime_contract_error(exc: BaseException) -> bool:\n    return isinstance(exc, ValueError) and type(exc).__name__ == \"RuntimeContractError\"","tryCatchPattern":"try:\n    check_fragment_caps()\nexcept RuntimeContractError as error:\n    print(f\"[gate] {error}\", file=sys.stderr)\n    raise SystemExit(2)","preventionTips":["Treat marker strings as cache-compatibility tokens - changing them invalidates KV prefixes (docs/CACHE.md)","Update required_markers in the checker and the pinning unit tests together in one commit","Grep 'cw:ctx:' in any prompt-format diff before pushing"],"tags":["python","ci","static-analysis","rust","prompt-cache","markers"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}