Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module missing required marker {marker!r}

Error message

bounded fragment module missing required marker {marker!r}

What it means

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.

Source

Thrown at scripts/check-runtime-contract-budget.py:543

        "ProjectInstructions",
        "Constitution",
    ]
    for name in required_fragments:
        if f"Self::{name}" not in text and f"{name} =>" not in text and f'"{name.lower()}"' not in text.lower():
            # Fallback: search for enum variant declaration
            if not re.search(rf"\b{name}\b", text):
                raise RuntimeContractError(
                    f"FragmentId missing required variant {name}"
                )
    # Marker stability — these strings are pinned by tests / prefix cache
    required_markers = [
        "<!-- cw:ctx:workspace -->",
        "<!-- cw:ctx:project_instructions -->",
        "<!-- cw:ctx:constitution -->",
    ]
    for marker in required_markers:
        if marker not in text:
            raise RuntimeContractError(
                f"bounded fragment module missing required marker {marker!r}"
            )

    # Project-instruction import must be a typed fragment, not ad-hoc
    if "load_project_instruction_fragment" not in text:
        raise RuntimeContractError(
            "bounded fragment module must expose load_project_instruction_fragment (project-instruction import as typed fragment)"
        )
    if "PROJECT_INSTRUCTION_CANDIDATES" not in text:
        raise RuntimeContractError(
            "bounded fragment module must define PROJECT_INSTRUCTION_CANDIDATES"
        )
    # Required candidate files from #3978
    required_candidates = [
        ".cursorrules",
        ".clinerules",
        ".windsurf/rules",
        ".gemini",

View on GitHub (pinned to 8880682c63)

Solutions

1. Restore the exact marker strings in FragmentId::marker() in crates/core/src/fragments.rs (lines ~50-57)
2. 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
3. Diff against a green commit: 'git diff HEAD~1 -- crates/core/src/fragments.rs | grep cw:ctx'

Example fix

// before (crates/core/src/fragments.rs)
Self::Constitution => "<!-- codewhale:constitution -->",

// after
Self::Constitution => "<!-- cw:ctx:constitution -->",

from pathlib import Path
text = Path("crates/core/src/fragments.rs").read_text(encoding="utf-8")
for marker in ("<!-- cw:ctx:workspace -->", "<!-- cw:ctx:project_instructions -->", "<!-- cw:ctx:constitution -->"):
    assert marker in text, f"missing pinned marker {marker}"

def is_runtime_contract_error(exc: BaseException) -> bool:
    return isinstance(exc, ValueError) and type(exc).__name__ == "RuntimeContractError"

try:
    check_fragment_caps()
except RuntimeContractError as error:
    print(f"[gate] {error}", file=sys.stderr)
    raise SystemExit(2)

When it happens

Trigger: 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.

Common situations: Prompt-format cleanups; renaming the 'cw:' namespace; aligning markers with a new cache scheme without updating the pinned tests and the gate list together.

Related errors

• DEFAULT_FRAGMENT_MAX_BYTES ({default_bytes}) must not exceed
• DEFAULT_FRAGMENT_MAX_BYTES definition not found
• MAX_FRAGMENTS_PER_CONTEXT must be {FRAGMENT_MAX_COUNT_CEILIN
• MAX_FRAGMENTS_PER_CONTEXT ({max_count}) must not exceed {FRA
• FragmentId missing required variant {name}

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/201f2743401c8ea5. Report an issue: GitHub.