Governance Checkers

Governance Checkers

The framework ships zero-dependency Bash checkers under scripts/, each with a matching test_*.sh negative-case suite and a constitution-*.yml workflow template that runs it in an adopting repository's CI. Every checker is governance tooling, so every checker is itself tested (TESTING.md, "Governance Tooling Must Be Tested").

Rollout contract

All checkers follow the same contract: warn by default, --strict to fail. A newly bootstrapped or newly updated repository should never go instantly red because it has not caught up to a new rule yet — adopters opt into --strict per checker, per repository, once they have confirmed compliance.

Two exceptions never merely warn: run_declared_tests.sh always fails when a declared test command fails (--strict only governs the "nothing declared yet" case), and check_secrets.sh always fails on a real secret-shaped hit (--strict only governs the separate .gitignore-coverage recommendation). check_architecture.sh runs the exception the other way: its structural signals never fail, because line count is a prompt to look, not a verdict — only its layer violations respond to --strict.

The contract is enforced, not just described: scripts/test_checker_contract.sh fails the build if any check_*.sh lacks --help, does not exit 2 on a bad option, ignores --strict where its usage documents it, is not committed executable, has no paired negative-case suite, or does not emit CI annotations. Under GitHub Actions every checker also prints ::warning:: / ::error:: workflow commands (via scripts/lib/ci_annotations.sh) so findings appear in the pull request UI rather than only in the job log.

The checkers

Script	What it verifies
check_compliance.sh	The repository carries the required, recommended, and product-facing governance files — including demo.html in the product-facing tier — and that recommended/product docs are not still template placeholders.
check_traceability.sh	Every requirement ID in docs/PRODUCT_REQUIREMENTS.md has a non-gap verifying-test row in docs/REQUIREMENTS_TRACEABILITY.md, matched by exact value so a layered ID never satisfies a system-layer ID.
run_declared_tests.sh	Runs the "Full suite" command declared in docs/TEST_PLAN.md, so "run all automated tests" is enforced in CI.
check_doc_freshness.sh	Flags a PR that changes source but never touches README.md/CHANGELOG.md. Blunt tripwire.
check_wiki_freshness.sh	Flags a PR that adds or removes source files without touching the wiki that catalogues them — a higher bar than doc-freshness (modifications do not trip it). See Home and docs/adr/0001-wiki-subsystem.md.
check_wiki_links.sh	Checks a wiki directory's internal integrity: dangling [[WikiLinks]] (targets with no page) and orphan pages (linked by nothing). Resolves links by GitHub wiki rules. See Home.
check_ots_inventory.sh	Cross-checks runtime dependencies in root manifests against docs/OTS_SOFTWARE.md, matched by exact name, so an undocumented dependency is flagged.
check_env_vars.sh	Cross-checks environment variables in root manifests against docs/ENV_VARS.md.
check_architecture.sh	Verifies every import points inward per the Dependency Rule, using layers a project declares in docs/ARCHITECTURE.md; also detects cycles and unknown layer references.
check_secrets.sh	Sweeps tracked and untracked-but-not-gitignored files for credential-shaped filenames and high-confidence secret patterns.
check_version_alignment.sh	Catches adopter-facing version references that drifted from the pinned constitution/VERSION.
check_constitution_freshness.sh	Warns at session start when the pinned constitution/ submodule is behind the latest release.
check_source_summaries.sh	Detects drift between dropped knowledge sources (sources/raw/) and their generated summaries.
check_instruction_templates.sh	Every agent instruction file present (AGENTS.md, CLAUDE.md, .cursorrules, the Solon agent, docs/HELP.md, ...) carries the same guidance anchors — session planning and project memory by default — so a rule added to one vendor file is not silently missing from the others.
check_demo_page.sh	demo.html makes no network requests (no CDN scripts, fonts, or stylesheets; no remote images or frames), keeps scripts and styles inline, references no build output, names no localhost or private-network URL, and is linked from README.md. No demo.html means nothing to verify.
check_next_steps.sh	The latest docs/AGENT_HANDOFF.md entry (or a pull request body, --file -) ends with a Next Steps procedure: a numbered checklist, every step tagged HUMAN, AGENT, or AUTOMATED, every HUMAN step saying why a person is needed and when it is done, and a "Human action required" line naming exactly those steps.
check_readme.sh	README.md (or --file docs/SETUP.md) names its supported platforms and mentions Windows and macOS wherever it hands the reader a fenced command block; every <details> block has a blank line after <summary> and before </details>, is not nested or left open, says what is inside, and holds no heading; a PowerShell or cmd Windows block uses no export/source (a Git Bash block is a bash block).
next_steps_hook.sh	Not a checker but a Claude Code hook: at Stop, a session that made commits is held (once) until docs/AGENT_HANDOFF.md is updated, its Next Steps procedure passes check_next_steps.sh, and the final reply ends with it.
check_skills.sh	Every skills/*/SKILL.md has front matter whose name matches its directory, a description, an H1 body, and references only scripts that exist.
run_all_tests.sh	The framework's own "Full suite": runs every scripts/test_*.sh and names each failing suite; run by .github/workflows/tests.yml.
bump_adopters.sh	Not a checker but a release step: re-pins every adopter's constitution/ submodule to a release commit, one branch and pull request per repository, idempotently. See RELEASES.md, "Cutting a Release", step 9.
measure_instruction_weight.sh	Reports the token weight of the agent required-reading order — bytes, words, and estimated tokens per document and in total, with an advisory HEAVY flag. Scoped bullets (TODO.md open items; CHANGELOG.md Unreleased + latest release) are measured as instructed and conditional bullets ("when the task touches …", "read on demand") as on demand, with the whole-file figure alongside and both totals at the end. A meter, not a gate: it fails only when the reading list names a file that does not exist.

Shared libraries (scripts/lib/)

The two largest scripts source their concerns from scripts/lib/ rather than carrying everything inline. These files are sourced, never executed, so they stay non-executable and are not checkers in their own right:

Library	Sourced by	Owns
bootstrap_readme.sh, bootstrap_migrate.sh, bootstrap_report.sh, bootstrap_dependabot.sh	bootstrap.sh	badge injection; seeding TODO.md/CHANGELOG.md from a project's existing backlog or release notes; the adoption report; one Dependabot entry per dependency manifest at the project root.
architecture_languages.sh, architecture_layers.sh, architecture_signals.sh	check_architecture.sh	how each language spells imports and what it resolves them against; the declared layer table as a graph; advisory heuristics that never fail a build.
ci_annotations.sh	every check_*.sh and run_all_tests.sh	the ci_annotate helper that prints GitHub Actions ::warning:: / ::error:: workflow commands when GITHUB_ACTIONS=true, and nothing otherwise.

Each split follows the SRP guardrail in ARCHITECTURE.md — a file is separated because it changes for its own reason, never merely because it is long. Both scripts verify their libraries are present at startup and exit with a remediation hint if the checkout is incomplete.

See also

• Standards Overview
• Bootstrap Script
• Templates and Examples