Repository navigation
S24.25: "Tier" means three different things, one of them contractual #682
Description
Parent epic: #254
Purpose
Three separate axes in this repository are called tiers, and two of them use the
bare token "Tier 1" to mean incompatible things.
| Axis | Stated in | "Tier 1" is | Keyed by |
|---|---|---|---|
| Support / security | SECURITY.md, docs/security/triage-runbook.md, CLAUDE.md |
Core/ — "full treatment: CVE, advisory, fix, signed release, SBOM entry" |
directory |
| MISRA rigour | docs/NAMING.md, docs/misra-deviations.md |
Strict — named, not numbered | directory |
| Naming | docs/NAMING.md |
external linkage | linkage / scope |
The support axis is contractual. SECURITY.md binds it to CVE treatment, signed
releases and SBOM entries, and SECURITY.md, SUPPORT.md and CONTRIBUTING.md
tie it to the free-versus-commercial licence split. A reader who meets "Tier 1"
without a qualifier cannot tell which axis is meant, and one of the readings is a
commitment to a paying integrator.
The repository already relies on qualification to stay safe —
docs/misra-deviations.md says "the Tier 1 naming scheme in
docs/NAMING.md" at every mention. That convention is undocumented and holds
only while every author remembers it.
Agreed
- Exactly one axis keeps the numbered "Tier N" form. The other two are renamed to
terms that cannot be confused with it. - Whichever axis is renamed,
SECURITY.md,SUPPORT.mdandCONTRIBUTING.md
keep saying precisely what they say today about support and licensing. No
wording change may narrow or widen a stated commitment.
Open — settle when the story is picked up
- Which axis renames. The support axis has the fewest call sites but the highest
cost of error, being customer-facing and licence-linked. The naming axis has
more call sites (docs/NAMING.mdthroughout,.coderabbit.yaml,SKILL.md,
docs/README.md,docs/porting.md,docs/misra-deviations.mdx6) but is
entirely internal-facing. - Whether the MISRA rigour axis (Strict / Pragmatic / Consistency-only) is
already safe by being named rather than numbered, or should stop being called a
tier at all. docs/NAMING.md:80still heads its section## Tier 1 — External linkage (public API). The(public API)parenthetical is the root cause of the whole
confusion: it equates external linkage with public API. Dropping it is the one
concrete edit already identified, and is cheap regardless of which way the
rename decision goes.
Scope re-cut, 2026-08-17
Audited against the tree during the pre-0.1.0 issue review. Two of the four
findings originally rolled in here have moved on, and the mechanical remainder is
carved out so this story is a decision rather than a mixed bag.
Resolved differently than proposed. This story recommended deleting the
docs/NAMING.md paragraph that asserted two library-internal classes are Tier 1.
It was instead rewritten and is now correct: NAMING.md:137-146 explains that
Tier 1 is decided by linkage rather than audience, names SolidSyslogRecordStore
and SolidSyslogBlockSequence as the two cases, and gives the Path B
symbol-collision reason. Better than deletion. Only the section heading is left,
recorded above.
Stale finding, struck. This story claimed .coderabbit.yaml's citation of
BlockSequence.c::ScanForExistingBlocks was dead after the S33.04 rename.
BlockSequence_ScanForExistingBlocks exists at
Core/Source/SolidSyslogBlockSequence.c:141. The citation is loose on the
filename prefix; it is not the broken reference it was raised as.
Carved out to a chore, and delivered. The .coderabbit.yaml resync and the
stale-path CI gate were mechanical, carried no contractual risk, and did not need
this story's decision first. #773 landed all of it: .coderabbit.yaml's Tier 1
wording now states linkage rather than "public functions", the outX rule the
S23.22 audit deleted from NAMING.md is gone from the review config too, build
files have a path_instructions entry where they previously matched none, and
scripts/check_references.py asserts that a repo-relative path quoted in a .md,
.yaml or CMake file resolves.
That gate is structured so #740 — the same assertion for symbols rather than paths
— extends it rather than growing a second script; the seam is named in the script.
What is left on this story is the terminology decision alone, plus the
(public API) parenthetical recorded above. No mechanical work remains.
Acceptance
- "Tier 1" resolves to exactly one meaning wherever it appears unqualified, and
no document states or implies that a library-internal class carries a support
or security commitment. SECURITY.md,SUPPORT.mdandCONTRIBUTING.mdstate the same support and
licensing commitments after the change as before.
Activity