Skip to content

The High-Integrity Systems Standard (HISS)

HISS establishes formal engineering determinism across polyglot repositories. It defines 21 invariants, HISS-01 through HISS-21; HISS-Matrix lists every one with its enforcement. HISS-16 is one of them, the context-integrity invariant, not the name of the standard.

Gated Invariants

This repository's AGENTS.md gates the invariants below. praetorctl forge sync-wiki copies them from its "Core Directives & Invariants" table each time it regenerates this page.

Invariant Scope Rule Verification On fail
HISS-01 control flow recursion prohibited; call graph = DAG build immediate build failure
HISS-02 loops, I/O scalar upper bound on every loop; explicit context.Context timeout on every I/O Semgrep / AST error
HISS-04 complexity McCabe cyclomatic <= 10, cognitive <= 15, func LOC <= 60, statements <= 50 AST sweep blocker
HISS-07 errors zero .unwrap() / .expect(); every error handled or wrapped with context linter / compiler error
HISS-10 warnings zero warnings: compiler, linter, format sweeps sweep exit code 1
HISS-15 3D testing positive + negative + boundary tests mandatory, every public interface CI coverage gate blocker
HISS-16 context integrity single canonical AGENTS.md; vendor files compiled via standardsctl compile-context; AGENTS.md passes caveman lint pre-commit blocker
HISS-17 state ledger turn start: praetorctl state status + .workingdir/OPEN.md, never whole .workingdir/STATE.md; tasks via standardsctl state task; turn end: standardsctl state sync . pre-commit / CI gate
HISS-18 CI efficiency diff-aware gating; docs/state-only change skips heavy race + security gates via standardsctl ci filter CI optimization gate
HISS-19 reuse before writing one behavior = one implementation; extend or call existing, config formats included dedupe scan in verify-all gate fail
HISS-20 replayable evidence every rule has fixtures replayed both directions; coverage claim reproducible, never asserted hiss coverage --verify in verify-all gate fail
HISS-21 platform neutrality gates, hooks, emitted templates run on Linux, macOS, Windows, or skip with stated reason; gate that cannot run != passing gate Platform Neutrality matrix in CI gate fail

Verification Ladder

Four verification tiers from editor LSP to git hooks, local gate stages, and CI PR admission re-checking Exit-0 receipts.
Verification ladder
Text description
  • Local Workstation: 1. Editor LSP (cmd/standards-lsp), Blocked locally (commit or push refused), 2. Git Hooks (lefthook pre-commit & pre-push), Signing Key (env var or key file), 3. Gate Pipeline (6 stages in internal/gating), .standards-receipt.json (Exit-0 receipt).
  • Remote CI & Admission: Pull Request (checklist & ```receipt block), 4. CI Re-check (standardsctl forge validate-pr), Admitted (PR check passes), Rejected (validate-pr exits 1).
  • 1. Editor LSP → 2. Git Hooks (save / stage) → 3. Gate Pipeline (commit / push).
  • Signing Key → 3. Gate Pipeline (LoadSigningKey) → .standards-receipt.json (signed v2) → Pull Request (fenced in body) → 4. CI Re-check (validate-pr) → Admitted (valid receipt).
  • 2. Git Hooks → Blocked locally (hook exit 1).
  • 4. CI Re-check → Rejected (receipt invalid).
  • Scenario 1, clean change -> admitted: A clean change passes all four tiers and is admitted by CI. Editor LSP reports zero diagnostics as code is written. Pre-commit and pre-push hooks run local checks and linters. Gate runs 6 stages; Ed25519 signing key is loaded. Stage output signed; .standards-receipt.json minted for HEAD commit. PR is opened with checked HISS boxes and fenced receipt block. CI runs standardsctl forge validate-pr on the PR description. Signature, clean worktree, and head SHA match: PR is admitted.
  • Scenario 2, a hook blocks locally: A local hook blocks commit or push before CI runs. Change introduces an error or invariant violation. Lefthook pre-commit or pre-push hook rejects the change locally.
  • Scenario 3, CI rejects invalid receipt: CI rejects a pull request with a missing or invalid receipt. Code is edited and committed. Local checks pass. PR submitted with missing, unpinned, or mismatched receipt. CI step runs standardsctl forge validate-pr. Receipt verification fails: commit mismatch, dirty tree, or missing block.
  • Verification escalates through four tiers: real-time editor diagnostics, local git hooks, the six-stage gate pipeline, and CI PR admission.

A change climbs four tiers: diagnostics from standards-lsp in the editor, the lefthook pre-commit and pre-push hooks, the six-stage gate pipeline that signs the Exit-0 receipt, and pull request admission, where CI re-checks that receipt with standardsctl forge validate-pr. A failing hook blocks the change locally; a missing or invalid receipt fails admission. HISS-Matrix states the admission rules.