feat(agent): add post-load semantic validation for contracts/constants.json

[nizar-lahlali]

Enforce relational invariants (min > 0, default >= min, max >= default) on approval_timeout_s and approval_gate_cap at agent import time and in the CI-time sync check, preventing corrupted constants from silently degrading the approval-gate security posture.

Area

• cdk — infrastructure, handlers, constructs
• agent — Python runtime / Docker image
• cli — bgagent client
• docs — guides or design sources (docs/guides/, docs/design/)
• tooling — root mise.toml, scripts, CI workflows

Related

• Closes fix(agent): add post-load semantic validation for contracts/constants.json values #219

Changes

1. agent/src/policy.py — new _validate_constants() function invoked at module import time. Checks all six relational invariants on the two constant groups loaded from contracts/constants.json. Raises ValueError with a descriptive message on violation, crashing the agent container at startup rather than running with broken safety bounds (e.g. a zero-valued approval_timeout_s.min would make the floor clamp ineffective).

2. agent/tests/test_policy.py — new TestConstantsSemanticValidation class (8 tests) covering each invalid scenario via unittest.mock.patch on module-level constants, plus a sanity test confirming the real constants pass.

3. scripts/check-constants-sync.ts — semantic invariant checks added after the existing shape validation. Reports all violations in a single pass before exiting 1. Belt-and-suspenders: catches corruption at PR time before it reaches the agent runtime.

Test plan

• python -m pytest tests/test_policy.py -v — 47/47 passing (39 existing + 8 new)
• node --experimental-strip-types scripts/check-constants-sync.ts — exits 0 with valid constants
• Temporarily corrupted constants verified to raise ValueError at import and exit 1 in the sync script

[scottschreckengaust]

LGTM