Map rules to a standard

For engineers and compliance leads who already have a realm: record which external standard your rules cite, and which rule maps which clause. A few short steps with the strspc CLI.

Declare a standard ↓

TL;DR

  • A mapping is a reference you declare. SteerSpec does not read the standard, assess your rules against it or certify anything.
  • Declare the standard once in a standards array, with relation implements or derived_from.
  • Map a rule to one clause with a standard note: <id>:<clause>.
  • strspc lint and strspc realm validate check the form of both. strspc standards coverage lists each mapped clause as covered, mapped, lapsed or cited; covered means an Implemented rule maps the clause, not that the clause is met.
  • The rules behind this (STDREF, NTE-013 to NTE-017) are Draft: their text may still change.

// 1. What a mapping says, and what it does not

A Standard Reference (STDREF) is a citation of an external standard, declared by a realm or an entity. Its relation is implements, which the core rules define as your claim of coverage of the standard (STDREF-005), or derived_from, which cites it as a source with no claim of coverage (STDREF-006). Either way the claim is yours: SteerSpec records it and does not check it against the standard's text, which it does not hold (CLI docs). The ids and clauses below (example.std, 4.2) are made up to show the commands; they name no real standard.

The rules are in the core rule set from 1.15.0 and are all Draft; the rule ids and text quoted here are from the core rule set. The commands were added to strspc in 1.32.0 (standards coverage) and 1.33.0 (realm standards, entity standards); this page follows the CLI docs and the output below comes from a real run. It starts from the realm and the rule DEMO-001 of SteerSpec 101 as committed in its step 6, before the hand edit. Uncomment the local source in .strspc/config.yaml (- source: ./rules/ and its scope: local line), which strspc init leaves commented out; step 5 needs it.

// 2. Declare the standard

Declare it on the realm, so every entity can map to it, or on one entity. The id is lowercase and dot-separated (STDREF-002) and is declared once per array (STDREF-003). --version is a free string naming the edition (STDREF-007) and --url an absolute http or https link (STDREF-008). add is refused while the realm pins dev.steerspec.core older than 1.15.0; the error names the command that moves the pin.

$ strspc realm standards add --id example.std --relation implements --version "2024" --dir rules
Declared standard example.std 2024 (implements) on Realm com.example.demo

$ strspc entity standards add DEMO --id example.src --relation derived_from --url https://example.org/src --dir rules
Declared standard example.src (derived_from) on DEMO
  Entity version: 0.2.0 → 0.2.1

update changes the relation, version or url in place, and list shows what is declared. A new version names another edition, so the same clause under it is a different clause (STDREF-011).

// 3. Map a rule to a clause

A standard note maps its rule to one clause (NTE-013). Its content is the standard's id, a colon and the clause (NTE-014). The id resolves in the rule's entity, its containing entities, its realm, then the parent realm (NTE-016); inherits passes on no references (STDREF-009). You can add a standard note to a rule in any state, Published included (NTE-017).

$ strspc note add DEMO-001 --type standard --body "example.std:4.2" --added-by github:alice --dir rules
Added note DEMO-001/01 (standard)
  Entity version: 0.2.1 → 0.2.2

// 4. Check the mapping

Two commands check the form of the declarations and notes, not what the standard says. strspc lint rules reads the entity files:

$ strspc lint rules
No errors or warnings found

$ strspc realm validate rules
No errors or warnings found
  • RL028: a bad standards entry on an entity.
  • RL029: a standard note that is not <id>:<clause>.
  • RL030: two identical standard notes on one rule.

strspc realm validate rules also reads realm.json, so it checks what needs the manifest (SPEC):

  • RM018: a bad standards entry on the realm.
  • RL031: a note whose id is declared nowhere it can resolve.

// 5. List the mapped clauses

strspc standards coverage lists each mapped clause per standard and entity, over the local sources in .strspc/config.yaml that have a realm.json; --all-sources adds the remote ones and --json prints one document. It exits 0 when it prints the report, 1 when a gate flag fails (see the end of this page) and 2 when a source or dependency does not resolve, since the report would then understate the mappings.

$ strspc standards coverage
Evaluator: claude, runs on Implemented rules

example.src (derived_from)
  https://example.org/src
  no clause mapped

example.std 2024 (implements)
  4.2  DEMO  mapped  com.example.demo:DEMO-001 (Published)

covered: an Implemented rule maps the clause. mapped: only a rule in another state does.
lapsed: the rule mapping it was retired or replaced. cited: the standard is a source, with no claim.
SteerSpec holds no clause lists, so a clause no rule maps isn't shown.

Here DEMO-001 is Published, so the clause reads mapped, not covered. The footer line says a clause no rule maps is not shown: that is the case without a linked Standard Realm.

  • covered: an Implemented rule maps the clause. Implemented is a rule state; the evaluator setting on the report's first line decides whether anything checks those rules.
  • mapped: a rule in another state maps it, and no Implemented rule does.
  • lapsed: the rule that mapped it was retired or replaced, and nothing maps it now.
  • cited: the standard is derived_from, so no coverage is claimed.

covered means a rule you mapped is Implemented, not that the clause is met. Without a linked Standard Realm the report holds no clause list, so a clause no rule maps is not shown and there is no percentage. To withdraw a mapping, retype the note to reference, content unchanged, with strspc note update <note_id> --type reference; strspc diff reports any other retype, or a withdrawal that changes the content, as RD022.

// 6. The data on disk

The commands that change the rules (realm standards add, entity standards add, note add) edit plain JSON files in rules/, validated against a published schema; lint, realm validate and standards coverage only read them (strspc init writes .strspc/config.yaml). Nothing is hidden in a database: you can read, diff and review the result in a pull request, and other tools can read it too. Excerpts from the run above, with the $schema field and the rule_set timestamp and hash left out, so these are not complete, schema-valid files:

rules/realm.json, the standard declared on the realm:

{
  "realm": {
    "id": "com.example.demo",
    "title": "Demo realm",
    "version": "0.1.0",
    "standards": [
      { "id": "example.std", "relation": "implements", "version": "2024" }
    ]
  },
  "dependencies": []
}

rules/DEMO.json, the entity declaration, the rule and the mapping note:

{
  "entity": {
    "id": "DEMO",
    "title": "Demo entity",
    "standards": [
      { "id": "example.src", "relation": "derived_from", "url": "https://example.org/src" }
    ]
  },
  "rules": [
    {
      "id": "DEMO-001",
      "revision": 0,
      "state": "P",
      "body": "The system MUST log every login attempt.",
      "added_by": "github:alice",
      "added_at": "2026-11-09",
      "supersedes": null
    }
  ],
  "rule_set": { "version": "0.2.2" },
  "notes": [
    {
      "id": "DEMO-001/01",
      "rule_ref": "DEMO-001",
      "type": "standard",
      "content": "example.std:4.2",
      "added_by": "github:alice",
      "added_at": "2026-11-09",
      "revision": 0
    }
  ]
}

The mapping is one note: the rule it belongs to in rule_ref and <id>:<clause> in content. strspc standards coverage --json prints the report as one document for scripts and CI:

$ strspc standards coverage --json
{
  "evaluator": { "provider": "claude", "usable": true, "runs_on_implemented": true },
  "declared": [
    { "id": "example.src", "relation": "derived_from", "url": "https://example.org/src" },
    { "id": "example.std", "relation": "implements", "version": "2024" }
  ],
  "clauses": [
    {
      "standard": "example.std",
      "version": "2024",
      "clause": "4.2",
      "realm": "com.example.demo",
      "entity": "DEMO",
      "status": "mapped",
      "rules": [
        { "rule": "com.example.demo:DEMO-001", "state": "P", "note": "DEMO-001/01" }
      ]
    }
  ],
  "figures": [],
  "unresolved": [],
  "warnings": []
}

The files are the source of truth and the report is computed from them. Edit them through the CLI: a hand edit of a Published rule is rejected by strspc diff (SteerSpec 101, step 6). The JSON is compacted here for reading; the files on disk are indented. figures is empty because no Standard Realm is linked.

// Linking a Standard Realm, and what is not built yet

strspc can link a reference to a Standard Realm the realm tree depends on (strspc realm standards add --id <id> --relation implements --version <edition> --realm <realm_id> [--profile <name>], STDREF-017 to STDREF-019), exclude a clause with a Realm Note (strspc realm note add --type exclusion --ref <id>:<clause> --body "<justification>" --added-by github:<login>, NTE-033, NTE-034), and report coverage against that realm's clause list, with unmapped and excluded statuses and a figure (STDREF-023 to STDREF-025). The steps above do not use them, because they need a published Standard Realm and SteerSpec has not published one yet, so none is used on this page; see the CLI docs for the commands and their output. These rules are Draft, added in core 1.21.0 and revised in 1.22.0.

Gate CI on coverage, added in 1.40.0: strspc standards coverage exits 1 when a gate flag fails (--fail-on, --require, --require-evaluator, --min-coverage, --baseline; CLI docs). Exit 2 still wins, so a gate never passes on a report that understates the mappings. The steps on this page run no gate. Not built yet, per the same docs: the crosswalk between editions of a standard.

Where next: standards as realms, concepts, the STDREF rules and the diagnostic codes.