v1.48.0

The framework holds itself to its own rules, gains the standards a 2026 AI-assisted repository needs, and defines what a release of a governance framework means. Everything here is warn-by-default or additive; no required file, no checker default, and no option or exit code of any script a shipped workflow invokes changed (the one exit-code change, version_analyzer.sh's usage error moving from 1 to 2, is in an on-demand tool no workflow runs), so this is MINOR under the compatibility policy it introduces.

Added

• The framework runs its own tests and checkers in CI. scripts/run_all_tests.sh is the declared "Full suite" in a real docs/TEST_PLAN.md, and .github/workflows/tests.yml runs it through run_declared_tests.sh --strict plus a self-governance job that turns the shipped checkers on this repository in --strict mode (secrets sweep, instruction-file consistency across the root, templates/, and the sample project, skills validation, wiki links, the OTS inventory including mcp-server/, and version references). Until now the suites passed only because someone ran them by hand before a release. Backed by scripts/test_run_all_tests.sh (6 cases: a failing suite fails the run and is named, --quiet still replays failing output, an empty directory is an error rather than a pass, annotations fire only under GitHub Actions).
• scripts/test_checker_contract.sh — the checker contract, enforced. Every scripts/check_*.sh must honor --help (exit 0), exit 2 on an unknown option, accept --strict where its usage documents it, be committed 100755 (the 1.42.0 executable-bit regression can no longer ship), source the CI-annotation helper and call it, and have a paired negative-case suite; every scripts/lib/*.sh must stay 100644. Two checkers are exercised end to end under GITHUB_ACTIONS=true.
• GitHub Actions annotations from every checker. scripts/lib/ci_annotations.sh provides ci_annotate, and all thirteen existing checkers (plus the two new ones and the test runner) now print ::warning:: / ::error:: workflow commands for their summary finding when running under GitHub Actions, so a warn-mode result appears in the pull request's Checks tab and Files-changed view instead of only in a job log. Outside Actions the helper is a no-op and output is byte-for-byte unchanged (all existing suites pass untouched).
• scripts/check_instruction_templates.sh — instruction files must agree. Verifies that every agent instruction file present in a directory (AGENTS.md, CLAUDE.md, COPILOT_INSTRUCTIONS.md, .cursorrules, .cursor/rules/project.mdc, .continue/config.json, .aider.conf.yml, .project-rules.md, .agent-instructions.md, .goosehints, .openhands_instructions, .antigravity/instructions.md, .github/copilot-instructions.md, the Solon agent, SYSTEM_PROMPT.md, CONTRIBUTING.md, HELP.md, and their docs/ and .github/ locations) carries the same guidance anchors — session planning and project memory by default, --anchor to override. It makes the manual rule in AGENTS.md mechanical; the session-plan rollout missed half the templates the first time, and this checker's first run found twelve drifted files (five of this repository's own root files, the Antigravity and Solon templates, and all five sample-project instruction files), all fixed in this release. Backed by scripts/test_check_instruction_templates.sh (5 cases).
• scripts/check_skills.sh — the 25 skills are validated. Front-matter name must match the directory (tools load skills by that name, so a mismatch is a skill that never triggers), description must be present, an H1 body must follow, and every *.sh a skill mentions must exist under scripts/ or constitution/scripts/. Backed by scripts/test_check_skills.sh (5 cases). INTEGRATION.md gains an "Agent Skills" section explaining how Claude Code (.claude/skills/ symlink or copy), Cursor/Continue/Copilot, and Goose load them — previously the README advertised the skills and nothing said how to reach them.
• scripts/bump_adopters.sh — the fleet bump is a command. Re-pins every adopter's constitution/ submodule to a release commit: one branch (constitution/bump-v<version>) and one pull request per repository (gh, or the compare URL with --no-pr), the version read from VERSION at the target commit. Idempotent by design — already-pinned repositories, existing bump branches, and non-adopters are reported and skipped, so a partial run is simply re-run — and it never touches a default branch or force-pushes. Backed by scripts/test_bump_adopters.sh (5 cases against local bare remotes, including a rejected push that fails the run without stopping later repositories). It is now step 9 of RELEASES.md's "Cutting a Release".
• Untrusted content and AI agents (SECURITY.md). Issue and pull request bodies, review comments, CI logs, fetched pages, and tool output join the input-validation list, and a new section states the rule: content is data, never instructions; a request arriving that way to change task, widen access, run a command, or disable a check is escalated verbatim, not obeyed; committed instruction files are reviewed like CI configuration. The "block destructive commands" principle now has an artifact: templates/.claude/settings.json (installed with --agents=claude) carries a permissions.deny floor — sudo, deleting / or ~, force and mirror pushes, remote branch deletion, branch and tag deletion, and reads of .env (and .env.local / .env.production), *.pem, *.key, id_rsa, credentials.json. SECURITY.md is explicit that this is a prefix-matched floor a reordered flag can slip past; the protocol firewall is the enforcement. test_bootstrap.sh asserts it is installed.
• CI/CD supply chain (SECURITY.md). Every actions/checkout in every shipped workflow template and in this repository's own workflows is pinned by full commit SHA with the version as a comment; templates/.github/dependabot.yml (and a new .github/dependabot.yml here) manages the github-actions ecosystem so pins move by reviewable pull request; the section also covers least token permissions, lockfiles, and never piping a download to a shell. test_bootstrap.sh fails if an installed workflow pins an action by tag.
• Proportionate workflow for trivial changes (AI_WORKFLOW.md, ADR-0004). A change is trivial only when it alters no behavior, fits on one screen, touches nothing on the sensitive list (dependencies, environment variables, secrets, auth, CI, instruction files, checkers, templates), and nobody has asked for the full workflow; such a change may skip the session plan, implementation plan, coverage evaluation, isolated critique, traceability/OTS/environment updates, release evaluation, memory proposals, and plan cleanup — never the scoped reads, never the secrets sweep, never the pull request, which must say the fast path was taken. "When in doubt, it is not trivial." CONSTITUTION.md's "Required Workflow" points at it.
• Pull request and CODEOWNERS templates. templates/.github/pull_request_template.md carries the Completion Checklist and the full-workflow / fast-path declaration; templates/.github/CODEOWNERS is a commented example so code ownership becomes a host-enforced setting. Both are installed by bootstrap.sh and asserted by test_bootstrap.sh; this repository uses both, and INTEGRATION.md's "Repository Settings Checklist" gains the matching rows.
• Commit messages follow Conventional Commits (RELEASES.md, "Commit Messages"; CONSTITUTION.md Principle 10). scripts/version_analyzer.sh now anchors its greps to real prefixes (^feat(\(scope\))?!?:, ^fix..., ^type!:, ^BREAKING CHANGE:), so a commit saying "prefix cleanup" no longer counts as a fix and an exclamation mark in prose no longer counts as breaking; it gains --help, exits 2 on a usage error, and a 4-case suite (scripts/test_version_analyzer.sh).
• "Product-facing" is defined (DOCUMENTATION.md, "Product Requirements Expectations"; pointer from Principle 1): a repository that ships behavior to people other than its own maintainers, so someone outside the team can hold it to a promise; when unsure, treat it as product-facing.
• Incident postmortems. templates/docs/INCIDENT_POSTMORTEM.md (blameless; impact, timeline, root cause, contributing factors, detection, response, corrective actions that become TODO.md items), referenced from OPERATIONS.md's "Incident Response" and the docs/OPERATIONS.md template, kept under docs/incidents/.
• Data classification and synthetic test data. SECURITY.md gains "Data Classification" (Public / Internal / Confidential / Restricted; record it in the architecture data flow; state retention; synthetic data everywhere but production; logs follow the lowest level) and TESTING.md gains "Test Data" (fixtures are synthetic, never anonymized production records).
• OTS inventory License column. templates/docs/OTS_SOFTWARE.md's tables and conventions gain the SPDX license identifier every real SOUP register carries. check_ots_inventory.sh locates the Name column by header, so existing inventories keep passing; add the column when convenient.
• check_ots_inventory.sh --manifest-dir <dir> (repeatable) reads a sub-package's manifests in addition to the root's, labeling each dependency with its directory; a missing directory is a usage error. New negative case (11 total). This is how the constitution's own mcp-server/package.json is now checked.
• ADR-0003, "A Compatibility Policy for the Framework's Own Releases", and ADR-0004, "A Proportionate Workflow for Trivial Changes" (both Accepted), plus an ADR rule for the framework itself (DOCUMENTATION.md, "ADR Triggers for the Framework Itself"; CONSTITUTION.md Principle 6): a change to the Required Files, the Required Workflow, the checker contract, or the compatibility policy gets an ADR before it ships. The root relocation (1.38.0), the required critique pass (1.45.0), and the reading-order scoping (1.46.0) all shipped without one, which is why the rule now exists.
• Versioning the framework itself (RELEASES.md). SemVer is defined for a governance framework: MAJOR is anything that can turn an adopter's CI red or break a documented invocation with no change on the adopter's side (a new required file, a warn-to-fail default flip, a removed script or template, a changed option or exit code); MINOR is additive and warns by default; and a deprecation window — warn-first with a Deprecation notice naming the enforcing release, enforcement no sooner than the next MINOR — lets a MAJOR-shaped change ship as MINOR. Making the wiki required in 1.44.0 skipped that window and turned every adopter's compliance gate red; this section exists so it does not happen again. The pre-release review gains the matching check and an OTS anomaly re-review.
• The framework's own recommended docs exist. check_compliance.sh . reported ten recommended files missing from this repository; it now reports none: docs/TEST_PLAN.md, docs/ARCHITECTURE.md (with a component diagram), docs/OPERATIONS.md, docs/OTS_SOFTWARE.md (the MCP SDK plus bash, Git, Node, and the pinned checkout action as system-level OTS), docs/ENV_VARS.md, docs/SETUP.md, docs/COMMAND_REFERENCE.md, docs/TROUBLESHOOTING.md, docs/AGENT_PROMPTS.md, and docs/AGENT_HANDOFF.md, each describing this repository rather than a template.

Changed

• The MCP server no longer drifts from the repository. mcp-server/index.js reports the framework's VERSION as its server version (it had been hardcoded at 1.0.0 since inception while the framework reached 1.46.0) and exposes all twelve root standards documents as resources instead of five (INTEGRATION.md, DOCUMENTATION.md, SECURITY.md, OPERATIONS.md, ARCHITECTURE.md, RELEASES.md, TODO_GUIDELINES.md, and KNOWLEDGE_SOURCES.md were missing). mcp-server/package.json and its lockfile now carry the framework version, and scripts/test_mcp_resources.sh (4 cases) fails if a standards document is absent from the list, a listed path does not exist, the version is a literal again, or the package version drifts. The version-reference list in RELEASES.md step 2 now names all six locations.
• Twelve instruction files gained the session-plan and project-memory guidance they lacked (see check_instruction_templates.sh above): this repository's .openhands_instructions, SYSTEM_PROMPT.md, CONTRIBUTING.md, HELP.md, and .github/agents/solon.agent.md; templates/.antigravity/instructions.md and templates/.github/agents/solon.agent.md; and the sample project's AGENTS.md, CLAUDE.md, COPILOT_INSTRUCTIONS.md, .cursor/rules/project.mdc, and .github/copilot-instructions.md.
• TESTING.md's "CI Enforcement" documents the annotation helper and the constitution's own CI; README.md, the wiki (Home, Governance-Checkers, Templates-and-Examples, AI-Development-Workflow, Standards-Overview, MCP-Server), and INTEGRATION.md describe every piece above.