Guard CII formula protocol docs

[koala73]

Summary

• Add a version-keyed CII protocol snapshot guard for shared country weights, default weights, strategic-risk constants, conflict curve constants, and getScoreLevel cutoffs.
• Pin canonical CII UI bands at 81/66/51/31 across the cached adapter and browser fallback.
• Document existing CII methodology details for unrest severityBoost, conflict civilianBoost, Israel OREF alert pressure, and Information severity handling without bumping CII_FORMULA_VERSION.

Coordination

This intentionally does not bump CII_FORMULA_VERSION; the separate codex/cii-v6-score-attribution-climate branch should own the v5-to-v6 formula bump and score-shifting narrative. When that branch lands, update the version-keyed protocol snapshot for the new formula version.

Validation

• npm_config_cache=/tmp/worldmonitor-npm-cache npx tsx --test tests/cii-scoring.test.mts
• npm run typecheck
• git diff --check
• pre-push hook passed on git push -u origin codex/cii-version-doc-guardrails, including npm run typecheck, npm run typecheck:api, changed CII tests, markdown lint, MDX lint, architectural boundary checks, safe HTML guard, and version sync.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
WorldMonitor	🟢 Ready	View Preview	Jun 6, 2026, 9:56 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
worldmonitor	Ignored	Preview	Jun 6, 2026 12:49pm

[greptile-apps]

Greptile Summary

This PR adds a version-keyed snapshot guard that hashes CII formula coefficients (country weights, default weights, strategic-risk constants, conflict-curve constants, and getScoreLevel cutoffs) against a per-CII_FORMULA_VERSION expected hash, failing if any constant drifts without a version bump. A second test pins the 81/66/51/31 UI bands across both the cached adapter and browser fallback. The MDX methodology doc gains an inline breakdown of the unrest severity boost, conflict civilian boost, Israel OREF alert pressure formula, and Information severity weights.

• The snapshot hash mechanism is sound; the v5 hash is consistent with the unchanged constants in _risk-config.ts, cii-weights.ts, and cached-risk-scores.ts.
• The MDX additions accurately reflect the server-side scoring logic in get-risk-scores.ts (verified formulas, caps, and weights).
• Two test helper utilities (extractFunctionBody via naive brace-counting, evaluateScoreLevel via new Function) work for the current simple function shapes but have documented fragility edge cases.

Confidence Score: 4/5

Safe to merge; the snapshot guard and band-alignment tests are correct for the current codebase, and the documentation additions accurately reflect existing server-side logic.

Both new tests exercise real constants from the live source files and would catch coefficient drift or cutoff divergence immediately. The two helpers (brace-counting body extractor and new Function executor) are fragile if getScoreLevel or getLevel are ever given TypeScript-specific body syntax or a return-type annotation containing '{', but pose no risk today. The MDX additions are factually accurate against the server implementation.

The test helpers in tests/cii-scoring.test.mts deserve a second look — specifically extractFunctionBody and evaluateScoreLevel; the rest of the change is low-risk.

Important Files Changed

Filename	Overview
tests/cii-scoring.test.mts	Adds helper utilities (extractFunctionBody, extractScoreLevelCutoffs, evaluateScoreLevel, hashJson) and two new test cases: a version-keyed snapshot guard for CII coefficients/cutoffs and a canonical band-alignment check (81/66/51/31). The helpers use naive text-parsing that works today but is brittle if the target functions are ever refactored.
docs/methodology/cii-risk-scores.mdx	Expands Unrest and Conflict component descriptions with OREF, civilian-boost, and severity-boost details; adds an Information severity-weight table. Verified against server-side scoring in get-risk-scores.ts — all formulas, caps, and weights are accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[cii-scoring.test.mts] -->|reads source text| B[cached-risk-scores.ts]
    A -->|reads source text| C[country-instability.ts]
    A -->|imports constants| D[_risk-config.ts]
    A -->|imports constants| E[cii-weights.ts]

    B -->|extractScoreLevelCutoffs| F[Snapshot Object]
    D -->|STRATEGIC_RISK + CONFLICT constants| F
    E -->|CII_COUNTRY_WEIGHTS + DEFAULT values| F
    F -->|hashJson + compare| G[v5 stored hash]

    B -->|extractScoreLevelCutoffs| H[Band Alignment Check]
    C -->|extractScoreLevelCutoffs| H
    H -->|assert 81 / 66 / 51 / 31| I[Pass / Fail]

    B -->|evaluateScoreLevel via new Function| J[Score to Level Mapping]
    C -->|evaluateScoreLevel via new Function| J
    J -->|assert score equals level| I

Loading

_{Reviews (1): Last reviewed commit: "test(cii): guard formula protocol docs" | Re-trigger Greptile}