# 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. For standards bodies: https://steerspec.dev/standards.md

## 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](https://github.com/SteerSpec/strspc-CLI/blob/v1.40.0/docs/standards.md)). 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](https://github.com/SteerSpec/strspc-rules/releases/tag/v1.15.0) and are all Draft; the rule ids and text quoted here are from the [core rule set](https://github.com/SteerSpec/strspc-rules/releases/tag/v1.24.0). The commands were added to strspc in [1.32.0](https://github.com/SteerSpec/strspc-CLI/releases/tag/v1.32.0) (`standards coverage`) and [1.33.0](https://github.com/SteerSpec/strspc-CLI/releases/tag/v1.33.0) (`realm standards`, `entity standards`); this page follows the [CLI docs](https://github.com/SteerSpec/strspc-CLI/blob/v1.40.0/docs/standards.md) and the output below comes from a [real run](https://github.com/SteerSpec/strspc-CLI/releases/tag/v1.40.0). It starts from the realm and the rule DEMO-001 of SteerSpec 101 (https://steerspec.dev/how-to/101.md) 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](https://github.com/SteerSpec/strspc-manager/blob/v1.51.0/docs/SPEC.md)):
- RM018: a bad `standards` entry on the realm.
- RL031: a note whose `id` is declared nowhere it can resolve.

Diagnostic codes: https://steerspec.dev/docs/diagnostics.md

## 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:

```json
{
  "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:

```json
{
  "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:

```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: https://steerspec.dev/how-to/101.md). 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](https://steerspec.dev/standards.md) 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](https://github.com/SteerSpec/strspc-CLI/blob/v1.40.0/docs/standards.md) for the commands and their output. These rules are Draft, added in core [1.21.0](https://github.com/SteerSpec/strspc-rules/releases/tag/v1.21.0) and revised in [1.22.0](https://github.com/SteerSpec/strspc-rules/releases/tag/v1.22.0).

Gate CI on coverage, added in [1.40.0](https://github.com/SteerSpec/strspc-CLI/releases/tag/v1.40.0): `strspc standards coverage` exits 1 when a gate flag fails (`--fail-on`, `--require`, `--require-evaluator`, `--min-coverage`, `--baseline`; [CLI docs](https://github.com/SteerSpec/strspc-CLI/blob/v1.40.0/docs/standards.md#gate-ci-on-coverage)). 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: https://steerspec.dev/standards.md, https://steerspec.dev/concepts.md, https://steerspec.dev/spec.md, https://steerspec.dev/docs/diagnostics.md
