Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must define…

Error message

bounded fragment module must define PROJECT_INSTRUCTION_CANDIDATES

What it means

check_fragment_caps statically reads crates/core/src/fragments.rs and asserts the project-instruction import is a typed fragment. It requires the module to expose load_project_instruction_fragment and to define the PROJECT_INSTRUCTION_CANDIDATES list; missing the candidates constant fails the contract budget check with this RuntimeContractError. This guards the contract from issue #3978 that project instructions come from a known, typed candidate set.

Solutions

1. Open crates/core/src/fragments.rs and define `pub const PROJECT_INSTRUCTION_CANDIDATES: &[&str]` listing the required candidate files.
2. If the constant was renamed or moved, restore the original name in fragments.rs (or re-expose it there) since the check is a literal text match.
3. Run `python scripts/check-runtime-contract-budget.py` to confirm the fragment-cap section passes.

Example fix

// before (fragments.rs)
fn load_project_instruction_fragment() -> Option<...> { ... }

// after
pub const PROJECT_INSTRUCTION_CANDIDATES: &[&str] = &[
    ".cursorrules",
    ".clinerules",
    ".windsurf/rules",
    ".gemini",
    ".github/copilot-instructions.md",
];

fn load_project_instruction_fragment() -> Option<...> { ... }

from pathlib import Path
text = Path('crates/core/src/fragments.rs').read_text(encoding='utf-8')
assert 'PROJECT_INSTRUCTION_CANDIDATES' in text, 'define PROJECT_INSTRUCTION_CANDIDATES in fragments.rs'

def has_project_instruction_candidates(module_text: str) -> bool:
    return 'PROJECT_INSTRUCTION_CANDIDATES' in module_text

try:
    subprocess.run(['python', 'scripts/check-runtime-contract-budget.py'], check=True)
except subprocess.CalledProcessError as e:
    if 'PROJECT_INSTRUCTION_CANDIDATES' in e.stderr:
        add_candidates_constant_to_fragments_rs()

When it happens

Trigger: Running scripts/check-runtime-contract-budget.py when crates/core/src/fragments.rs exists and contains load_project_instruction_fragment but the literal string PROJECT_INSTRUCTION_CANDIDATES is absent from its text (e.g. renamed constant, moved to another module, or never implemented).

Common situations: A refactor renames PROJECT_INSTRUCTION_CANDIDATES to something like INSTRUCTION_FILES; the candidates list is moved out of fragments.rs into a helper module; a new fragment module is scaffolded without the project-instruction section; reverting a commit accidentally drops the constant.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• bounded fragment module must define a matches_text…
• bounded fragment module must define trait ContextFragment…
• bounded fragment module must enforce byte caps via…
• PROJECT_INSTRUCTION_CANDIDATES missing required entry
• TUI fragment module must include ProjectInstructions…

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/cb1fa1a65746fe17. Report an issue: GitHub.

Appendix: source

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

    # 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",
        ".github/copilot-instructions.md",
    ]
    for candidate in required_candidates:
        if candidate not in text:
            raise RuntimeContractError(
                f"PROJECT_INSTRUCTION_CANDIDATES missing required entry {candidate!r}"
            )

    # matches_text recognizer must exist on the fragment trait
    if "fn matches_text" not in text:

View on GitHub (pinned to 433685b202)