strspc-rules

SteerSpec Core Rules — the canonical rule format specification for the SteerSpec ecosystem.

This repository contains the foundational rule definitions that govern how all SteerSpec specifications are structured, versioned, and interpreted. The rules are written using the format they themselves define (self-referential by design).

Contents

rules/
└── core/
    ├── _schema/
    │   ├── bootstrap.schema.json   Minimal schema for CI validation
    │   ├── config.v1.schema.json   Config schema (generated from SPCFG rules)
    │   ├── entity.v1.schema.json   Full entity schema (generated by build-schema.py)
    │   └── realm.v1.schema.json   Realm manifest schema (hand-maintained axiom)
    ├── realm.json         Realm manifest (namespace metadata, not an entity)
    ├── ENT.json           Entity rules
    ├── KWRD.json          Keyword rules (RFC-2119-derived: MUST, SHOULD, MAY, …)
    ├── NTE.json           Note rules
    ├── RLM.json           Realm rules (namespace definition, cross-realm references)
    ├── RLIFRMT.json       Rule-identifier format rules
    ├── RST.json           Rule-set rules
    ├── RUL.json           Rule and rule-state rules
    ├── SPCFG.json         SteerSpec configuration rules (consumer .strspc/ directory)
    └── (no Markdown — JSON is the source of truth)

tools/
├── build-manifest.py     Generates index.json manifest for published rules
├── build-schema.py       Generates entity.v1 and config.v1 schemas from the rules themselves
├── compute-hash.py       Computes Blake3 content hashes for rule-set integrity
└── hash_util.py          Shared Blake3 canonicalization and hashing utilities

Schema System

JSON is the source of truth. Rules are structured data; Markdown is a rendered view generated by the CLI (strspc-CLI). The JSON files reference a schema in _schema/ that is self-recursive — tools/build-schema.py reads the rules to generate entity.v1.schema.json, which then validates those same JSON rule files. A minimal bootstrap.schema.json is checked into the repo so CI can validate without running the generator.

Realms

A Realm is a namespace in which Entity Unique Identifiers (EUIDs) are unique. Each Realm is a directory containing entity JSON files, a _schema/ directory, and a realm.json manifest that declares the Realm's identity, version, and dependencies.

• Realm IDs use reverse domain notation (e.g., dev.steerspec.core) for global uniqueness
• Cross-realm entity references use the qualified form <realm-id>:<EUID>
• The core Realm (dev.steerspec.core) defines the foundational rules in this repository

The RLM.json entity formalizes these rules (RLM-001 through RLM-009), and realm.v1.schema.json validates the manifest format. Both are hand-maintained axioms.

Development

Prerequisites: Python 3.12+, pre-commit.

pip install -r requirements.txt
pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg

Pre-commit hooks run automatically on each commit:

Hook	What it checks
actionlint	GitHub Actions workflow syntax
yamllint	YAML formatting
markdownlint	Markdown style
editorconfig-checker	EditorConfig compliance
ruff	Python lint (pycodestyle, pyflakes, isort, bugbear, …)
ruff-format	Python formatting
commitlint	Conventional Commits message format

Run validation manually:

python3 tools/build-schema.py --check      # JSON schema
ruff check . && ruff format --check .      # Python lint + format

CI

Every PR is gated by these jobs (.github/workflows/ci.yml):

Job	Description
validate-json	JSON entity files against bootstrap schema
lint-python	Ruff lint + format check
lint-commits	Conventional Commits enforcement (PR only)
lint	actionlint, yamllint, markdownlint, editorconfig-checker

Published at steerspec.dev

Every release automatically publishes schemas and rules to steerspec.dev (GitHub Pages). This makes schema $id URLs resolvable and provides stable endpoints for CLI and tooling consumers.

URL	Description
https://steerspec.dev/schemas/entity/v1.json	Full entity schema (matches $id)
https://steerspec.dev/schemas/entity/bootstrap.json	Bootstrap schema (matches $id)
https://steerspec.dev/schemas/realm/v1.json	Realm manifest schema (matches $id)
https://steerspec.dev/schemas/config/v1.json	Config schema (matches $id)
https://steerspec.dev/rules/latest/index.json	Manifest with filenames, versions, blake3 hashes
https://steerspec.dev/rules/latest/<ENTITY>.json	Latest rule files
https://steerspec.dev/rules/v<version>/	Versioned snapshots

The publish step runs as a job in the Release workflow (.github/workflows/release.yml) and pushes to the strspc-www repository.

Versioning

Releases follow semantic versioning and are published as Git tags in the format v<MAJOR>.<MINOR>.<PATCH> (e.g., v1.1.1).

Each release includes:

• The full rules/ directory
• LICENSE and NOTICE files
• Archives: strspc-rules-<version>.tar.gz and strspc-rules-<version>.zip
• Auto-publish to steerspec.dev (schemas, rules, manifest)

Referencing a Specific Version

Use steerspec.dev for stable, versioned access:

https://steerspec.dev/rules/v1.1.1/RUL.json

Or download the archive for offline use:

https://github.com/SteerSpec/strspc-rules/releases/download/v1.1.1/strspc-rules-1.1.1.tar.gz

License

Apache 2.0 — see LICENSE and NOTICE.