bench.json

{
  "constitution": "bench-v1",
  "version": 5,
  "author": "Nuralyn LLC",
  "created": "2026-04-21T00:00:00Z",
  "description": "Constitutional constraints for the Bench governance pipeline",
  "constraints": [
    {
      "id": "C-001",
      "name": "No Silent Error Swallowing",
      "scope": "error-handling",
      "rule": "All catch blocks must log, re-throw, or return a typed error. Empty catch blocks and catch blocks that only contain comments are violations.",
      "severity": "veto",
      "rationale": "Silent failures compound into untraceable production bugs. A governed codebase must fail visibly."
    },
    {
      "id": "C-002",
      "name": "Scope Boundary Enforcement",
      "scope": "scope-control",
      "rule": "Changes must stay within one coherent scope, judged from the evidence the pipeline receives: the diff itself and the repository context it lands in. Bundling unrelated edits into a single change is a violation, and where the repository states a task boundary (for example in CLAUDE.md), edits outside it are a violation unless justified there. The absence of a stated task description is not itself a violation: the hook payload carries the tool input, not the prompt, so an author has no in-band way to supply one and must not be vetoed for its absence alone.",
      "severity": "veto",
      "rationale": "Scope creep in AI-generated code is the primary trust failure mode. Unbounded changes are ungovernable."
    },
    {
      "id": "C-003",
      "name": "Dependency Declaration",
      "scope": "dependencies",
      "rule": "Any new import or dependency must be explicitly declared. No silent additions to requirements.txt, package.json, or equivalent.",
      "severity": "veto",
      "rationale": "Undeclared dependencies are supply chain attack vectors and reproducibility failures."
    },
    {
      "id": "C-004",
      "name": "Type Safety Preservation",
      "scope": "type-safety",
      "rule": "Functions must not remove or weaken existing type annotations. The following are violations: replacing an annotation with a less precise one; deleting a parameter or return annotation; and introducing a bare 'Any' (x: Any, or -> Any) where the value's shape is known at that point and expressible in the type system. The following are permitted: parameterized generics that contain 'Any' for genuinely heterogeneous data, such as dict[str, Any] for a parsed JSON object, since they are strictly more precise than the bare 'dict' or 'Any' they would otherwise be; and a bare 'Any' where the value really is unconstrained. Prefer 'object' over a bare 'Any' for a value that is only stored or passed through, because 'object' forces an explicit narrowing check at the point of use. The operative test is whether precision that was available has been discarded, not whether the token 'Any' appears in the diff.",
      "severity": "veto",
      "rationale": "Type annotations are governance infrastructure. Weakening them degrades the ability to reason about correctness. This constraint targets discarded precision rather than the token 'Any'. An earlier phrasing read literally enough to veto dict[str, Any], an idiom this codebase uses in more than sixty places to describe parsed JSON accurately, which meant the rule condemned the correct construct and the codebase it governs. A constraint that fires on correct code trains authors to route around governance, and that costs more than the imprecision it was meant to prevent."
    },
    {
      "id": "C-005",
      "name": "Test Coverage for New Logic",
      "scope": "testing",
      "rule": "New functions or branches of logic must have corresponding test cases or an explicit justification for why testing is deferred.",
      "severity": "warning",
      "rationale": "Untested code is unverified code. Governance without verification is theater."
    },
    {
      "id": "C-006",
      "name": "No Hardcoded Secrets or Credentials",
      "scope": "security",
      "rule": "No API keys, passwords, tokens, or credentials may appear in source code. All secrets must be loaded from environment variables or a secrets manager.",
      "severity": "veto",
      "rationale": "Hardcoded credentials are the most common and most preventable security failure."
    },
    {
      "id": "C-007",
      "name": "Governance Pipeline Integrity",
      "scope": "self-governance",
      "rule": "Changes to the governance pipeline itself (challenger, defender, oracle, ledger, constitution) must not weaken enforcement, bypass verification, or disable logging.",
      "severity": "veto",
      "rationale": "A governance system that can silently weaken itself is not a governance system. This is the self-cannibalizing constraint."
    },
    {
      "id": "C-008",
      "name": "Ledger Immutability",
      "scope": "evidence",
      "rule": "No code may modify, delete, or overwrite existing ledger entries. New entries may only be appended. The hash chain must remain intact. Editing, reordering, or removing an individual entry is a violation under all circumstances, with no exception. A whole chain may be retired, and retirement is not deletion, but the sole permitted trigger is that the chain contains content which must not be published. Retirement requires ALL of the following: (a) an explicit human decision, never an automated or agent-initiated one, with the decision recorded in the anchor entry; (b) an archived copy that passes ledger.verify.verify_chain with valid=true BEFORE the original is moved; (c) an anchor entry opening the successor chain that records the retired chain's tip hash, genesis hash, entry count, first and last timestamps, the verbatim archive path, and the reason for retirement; (d) indefinite retention of the archive at that recorded path. An auditor confirms any retirement by running verify_chain against the archive and checking that its tip hash and entry count match the values recorded in the anchor entry. A retirement missing any of these elements is a violation of this constraint.",
      "severity": "veto",
      "rationale": "The ledger is the evidence chain. Tampering with evidence is the highest governance violation. Chain retirement is bounded rather than forbidden because the alternative is worse: a chain that has accumulated unpublishable third-party content would otherwise force entry-level edits, which are exactly what this constraint exists to prevent. Retirement preserves every entry, is triggered only by a human, and leaves a hash reference an auditor can independently check, so custody is documented rather than broken. The enumerated requirements make the exception verifiable instead of discretionary."
    }
  ]
}