Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must define PROJECT_INSTRUCTION_CAND

Error message

bounded fragment module must define PROJECT_INSTRUCTION_CANDIDATES

What it means

Requires the const PROJECT_INSTRUCTION_CANDIDATES to be defined in crates/core/src/fragments.rs (plain substring check). This array enumerates the well-known instruction files scanned at startup; the gate keeps it a named, typed surface instead of inline literals scattered at call sites.

Source

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

    # 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 8880682c63)

Solutions

Restore 'pub const PROJECT_INSTRUCTION_CANDIDATES: &[&str] = &[...];' in crates/core/src/fragments.rs
Keep supplementary lists under separate names (ADDITIONAL_PROJECT_INSTRUCTION_CANDIDATES) - allowed, but the base const must stay
Verify: 'grep -n PROJECT_INSTRUCTION_CANDIDATES crates/core/src/fragments.rs'

Example fix

// before (crates/core/src/fragments.rs)
pub const INSTRUCTION_FILES: &[&str] = &[".cursorrules", ".clinerules"];

// after
pub const PROJECT_INSTRUCTION_CANDIDATES: &[&str] = &[".cursorrules", ".clinerules"];

Defensive patterns

Strategy: try-catch

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Keep the candidate list as the named const PROJECT_INSTRUCTION_CANDIDATES (extras may go in ADDITIONAL_...)
Do not inline candidate paths at call sites
Verify with a grep before pushing changes to fragments.rs

When it happens

Trigger: Renaming the const (e.g. INSTRUCTION_FILES); inlining the list at each call site; deleting it in favor of only ADDITIONAL_PROJECT_INSTRUCTION_CANDIDATES.

Common situations: Cleanup passes that 'simplify' the candidate list; merges restructuring candidate handling after #3978.

Related errors

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