08. Specifications — 11 SPEC types¶
Part of the RENAR Standard v1.0 · ← Table of contents
8.1 Why a separate specification axis¶
Take the requirement "the system creates an order." It says what must happen — but it is silent about how the system is built to do it: what its API contract is, in which table the order lives, under which access rules, on which screen. Cramming all of that into the requirement itself does not work — it turns into mush. So RENAR splits the description into two axes: behavior (BR / SR / TR, chapter 6) and structure — specifications, SPEC.
A specification is not a "more detailed SR" and not its child. A single "create order" requirement typically rests on five to seven specifications at once (architecture, API, data, process, security, screen), so the link between the axes is a graph of typed edges (constrained-by[], implements-spec[]), not a tree. There are exactly eleven specification types, and the list is closed: SPEC-ARCH, API, DATA, INT, PROC, UI, AI, SEC, OPS, TEST, DOC — a new type is introduced only through the formal change procedure of the standard (chapter 13).
A specification describes three different subjects, and they MUST NOT be conflated. Nine types describe how the system is built. SPEC-TEST describes the construction of the proof of its conformance: the test bench of an integration system is not an installation but an engineering product (emulators, datasets on both sides of every integration, rules for reconciling results against the data of foreign systems). SPEC-DOC describes the composition of the delivered result: the documentation the client receives as part of the delivery.
8.2 Architectural decision: SPEC is a parallel axis, not children of SR¶
8.2.1 Two axes of describing the system¶
Requirements and specifications answer different questions:
| Axis | Artifacts | Question |
|---|---|---|
| Behavioral | BR / SR / TR (chapter 6) | What the system must do |
| Structural | SPEC-* (9 types) | How the system is structurally built to fulfill those requirements |
| Evidential | SPEC-TEST |
On what bench and on what data conformance is proven (§8.3.2) |
| Delivery | SPEC-DOC |
What enters the delivery to the client besides the system itself |
8.2.2 SPEC as a parallel axis: links through a typed graph¶
The links between the requirements axis (BR / SR / TR) and the SPEC axis are organized as a dependency graph, not a tree of parents. An SR has exactly one parent in the requirements tree (BR), but many typed constrained-by[] edges to SPEC. A single SR MUST reference every SPEC that constrains its behavior on the API / data / UI / process / security / ops axes; conversely, one SPEC MAY constrain many SR.
Example: the SR "create order" rests on SPEC-ARCH (where the orders component lives), SPEC-API (the endpoint contract), SPEC-DATA (the table schema), SPEC-PROC (workflow), SPEC-SEC (access rules), SPEC-UI (the form).
Normatively: every SR.constrained-by[] and TR.implements-spec[] edge MUST reference one of the closed SPEC categories listed in §8.3; ad-hoc categories are not allowed (see §1.7 closed-list policy).
Requirements tree (behavioral axis): Parallel specification axis:
BR SPEC-ARCH SPEC-API
└── SR ←──── constrained-by[] ────► SPEC-DATA SPEC-INT
└── TR ─── implements-spec[] ────► SPEC-PROC SPEC-UI
SPEC-AI SPEC-SEC
SPEC-OPS SPEC-TEST
SPEC-DOC
Requirements tree:
SR.parent → BR (single parent)
TR.parent → SR (single parent)
Link graph (typed edges):
SR.constrained-by[] → SPEC-*
TR.implements-spec[] → SPEC-*
SPEC-*.depends-on[] → SPEC-* (between specifications)
SPEC-*.referenced-by[] → SR / TR (auto-derived inverse)
8.2.3 Rationale¶
| Argument | Consequence |
|---|---|
| SPEC and SR answer different questions | SPEC does not refine an SR at a deeper level — it is a separate category of description |
| One SR rests on 5–7 SPEC | A "SPEC as parent of SR" tree leads to multiple parenthood |
| Industry standards (arc42, C4, OpenAPI, BPMN, ERD) live in parallel with requirements | RENAR follows this proven practice |
| An AI agent can parallelize SR and SPEC generation | Without one type blocking the other |
8.3 The closed list of eleven SPEC types¶
| Type | Purpose | Industry reference |
|---|---|---|
SPEC-ARCH |
System / subsystem architecture: contexts, containers, components, deployment view, quality attributes | arc42, C4 model (Brown), ISO/IEC/IEEE 42010 |
SPEC-API |
API contracts: REST / GraphQL / gRPC / async events; versioning, error model, rate limits | OpenAPI 3.x, AsyncAPI 2.x, gRPC IDL |
SPEC-DATA |
Data model: schema, ERD, indices, migrations, retention, PII classification | ISO/IEC 11179, JSON Schema |
SPEC-INT |
Integration: interaction between subsystems and external systems; protocols, contracts, SLA | Enterprise Integration Patterns (Hohpe) |
SPEC-PROC |
Process / workflow: business processes, state machines, saga, choreography, orchestration | BPMN 2.0, ISO/IEC 19510 |
SPEC-UI |
UI / UX: screens, navigation, user journeys, accessibility, i18n, baseline images | Material Design / Apple HIG, WCAG 2.2 |
SPEC-AI |
AI / ML: model cards, RAG, prompt engineering, eval strategy, cost budget | ISO/IEC 23894, NIST AI RMF |
SPEC-SEC |
Security: authn / authz, threat model, secrets management, data classification | STRIDE, OWASP ASVS, ISO/IEC 27001 |
SPEC-OPS |
Operations: deployment, observability, SLO / SLA, runbook, disaster recovery | Google SRE, ITIL v4, ISO/IEC 20000 |
SPEC-TEST |
Test benches and data: topology, emulators and sandbox instances of external systems, run configuration (what is mocked, what is live), datasets on both sides of every integration, rules for reconciling results against the data of foreign systems, volume and anonymization | ISO/IEC/IEEE 29119-4 (test techniques), Testcontainers, Pact |
SPEC-DOC |
Delivered project documentation: composition (user manual, administrator manual, training materials), the structure of each document (mandatory sections), the checkable requirements on it (completeness across roles and scenarios, version currency, format) | ISO/IEC/IEEE 26511, ISO/IEC/IEEE 26514 |
8.3.1 What did NOT make it into v1.0 (with rationale)¶
| Candidate | Decision | Rationale |
|---|---|---|
SPEC-EVENT |
Not a separate type | Events / queues — part of SPEC-API (asynchronous APIs) |
SPEC-CONFIG |
Not a separate type | Feature flags / env vars / secrets — part of SPEC-OPS |
SPEC-PERF |
Not a separate type | Performance / NFR — part of SPEC-ARCH (quality attributes) or SPEC-OPS (SLO) |
SPEC-TEST-ENV |
Decision reversed in v1.0 | The former decision ("test environments — part of SPEC-OPS") is reversed: see §8.3.2. The test bench is introduced as a separate type, SPEC-TEST |
SPEC-DOMAIN |
Not a separate type | Domain model — absorbed into SPEC-ARCH (decomposition) + SPEC-DATA (entities) |
SPEC-MIGRATION |
Not a separate type | Migration — part of SPEC-DATA (lifecycle) |
SPEC-COMPLIANCE |
Not a separate type | Compliance — links between SR/SPEC and regulations through compliance-refs[], not a separate artifact |
A reversed decision is kept in the table struck through rather than deleted: the history of decisions is part of the standard, and the reader is entitled to see what was revised and why.
8.3.2 Revision of the test-bench decision¶
The former decision identified the test bench with a deployment environment and sent it to SPEC-OPS (the environments[] field: dev / staging / prod). For a simple system that is correct: the bench there is staging plus a dataset. The decision is reversed for three reasons.
1. The bench of an integration-heavy system is a different object. It is not an installation of the system but the construction of the proof: emulators and sandbox instances of external systems; agreed datasets on both sides of every integration; rules for reconciling results against the data of foreign systems — the expected result lives not in our system; the run configuration (what is mocked, what is live). The standard already sensed this: §9.6.3 requires, for SPEC-INT, a run "against a real or sandbox counterparty — a mocked contract is not enough," yet it gave no carrier for describing that counterparty.
2. False invalidations — the decisive argument. §10.5.4 invalidates verified on any version increment of an artifact, automatically and without inspecting the cause. If a TC referenced the bench through SPEC-OPS, then an edit to the deployment procedure — unrelated to the bench — would drop every TC referencing that SPEC-OPS back into approved. Deployment is edited more often than the bench, and the body of evidence would be devalued regularly and falsely. A separate SPEC-TEST makes invalidation precise: TC are invalidated if and only if what they are valid against has changed.
3. An alien signature. Sensitive test data (volume, anonymization, the use of the client's real data) is agreed by the client. A client signature on a section of an operations document is alien; on a separate artifact it is natural.
The boundaries of the new types:
| Type | Answers the question |
|---|---|
SPEC-OPS |
How the system lives in operation (deployment, observability, SLO, runbook) |
SPEC-TEST |
How its conformance is proven (benches, data, run configuration) |
SPEC-DOC |
What enters the delivery to the client (documents as a subject of the contract) |
The SPEC-DOC ↔ SPEC-OPS boundary. The criterion is inclusion in the composition of the delivered result, and that composition is set by the contract before acceptance rather than settled during it:
- The administrator manual is always
SPEC-DOC: if the client operates the system, the manual for the client's administrators enters the composition of the delivery. No "internal version" of this genre exists. - The runbook is always
SPEC-OPS: it is the internal operational regulation of the contractor's operating team; it is not presented to the client and is not a subject of acceptance.
Dual membership of a document is excluded by construction — the TR.implements-spec[] edge is always unambiguous.
Closed-list policy: if subsequent work reveals that one of the excluded types is genuinely needed — it is added through the formal change procedure of the standard with rationale.
8.4 Common schema (shared frontmatter fields)¶
All 11 SPEC types share a common set of frontmatter fields. Type-specific fields are added as extensions on top (§8.5). The full machine-readable data model — in reference/02-schemas.md.
---
# === Identity (mandatory) ===
id: SPEC-<TYPE>-NN[.N] # immutable; TYPE ∈ {ARCH,API,DATA,INT,PROC,UI,AI,SEC,OPS,TEST,DOC}
title: "<short, descriptive>"
type: SPEC-ARCH | SPEC-API | SPEC-DATA | SPEC-INT | SPEC-PROC | SPEC-UI | SPEC-AI | SPEC-SEC | SPEC-OPS | SPEC-TEST | SPEC-DOC
slug: "<kebab-case>" # auto-derived
# === Scope (mandatory) ===
level: system | subsystem | module
scope:
system: "<system-id>"
subsystem: "<subsystem-id>" # null if level=system
# === Lifecycle (mandatory) ===
status: draft | review | approved | verified | obsolete
priority: must | should | could # not all types use; mostly SPEC-SEC / SPEC-OPS
# === Source: provenance (conditional, see chapter 7 §7.4.1) ===
# source.adapt — conditional (present when an ADAPT was created; §7.4.1.1).
# source.tz-section — always mandatory.
# source.adversarial-review-ref — mandatory when source.adapt is omitted.
source:
adapt: ADAPT-NNN # conditional
adapt-section: "Forward §N" # mandatory if adapt is present
tz-section: "§N.N" # always mandatory
adversarial-review-ref: AR-NNN # mandatory if adapt is omitted (§7.4.6)
# === Link graph (auto-managed except mandatory ones) ===
referenced-by: [] # auto-derived; SR/TR/SPEC referencing here
depends-on: [] # mandatory if present; SPEC-* this SPEC rests on
verified-by: [] # auto-derived; list of verifying TC IDs
# === AI provenance (mandatory at RENAR-4+; canonical schema — §4.10.1) ===
ai-provenance:
generated-by: "<vendor>-<model>@<date>"
generated-at: "<ISO-8601>"
prompt-template: "<template-path>@<version>"
context-tokens: integer
output-tokens: integer
human-edits: boolean
generation-time-ms: integer # optional; see §4.10.1
# optional at RENAR-4, mandatory at RENAR-5:
# cost-budget, cost-actual
# === Replacement (mandatory if applicable) ===
replaces: "<old-id>"
replaced-by: "<new-id>"
deprecated-date: "<ISO date>"
# === Compliance (optional) ===
compliance-refs: [] # references to ISO/GDPR/AI Act/NIST AI RMF
---
8.4.1 Mandatory body sections¶
The body of any SPEC MUST contain:
- Purpose — 1–3 paragraphs.
- Scope — what is in, what is out.
- Type-specific sections — see §8.5.
- Link to requirements — which SR/BR reference it.
- Link to other SPEC —
depends-on[]. - Verification — which TC verify this SPEC.
8.5 Schema extensions by SPEC type¶
A brief description of type-specific fields and mandatory body sections. The full machine-readable extension schema — in reference/02-schemas.md. Industry references in detail — in the listed standards.
8.5.1 SPEC-ARCH¶
Type-specific frontmatter: arch-style, deployment-model, tech-stack, quality-attributes.
Mandatory body: system context (C4 L1), containers (C4 L2), components (C4 L3) for critical containers, quality attributes (latency / throughput / availability), ADR log.
Spec-specific TC (chapter 9): architecture conformance tests (zoning), reference tests of quality attributes.
8.5.2 SPEC-API¶
Type-specific frontmatter: api-style (rest / graphql / grpc / async-events), api-version, versioning-strategy, authentication, rate-limits, contract-file (location of machine-readable contract).
Mandatory body: endpoints / operations with payload / response / errors, versioning rules (breaking vs non-breaking), error model, authn/authz reference to SPEC-SEC, rate limits, 2–3 example requests per endpoint.
Spec-specific TC: contract tests, authentication negative, rate limit tests.
8.5.3 SPEC-DATA¶
Type-specific frontmatter: data-style (relational / document / graph / columnar), storage-engine, schema-version, pii-classification[], retention-policies[], migration-strategy.
Mandatory body: domain entities, ERD (text / Mermaid / link), entity fields (type / constraints / indices / defaults), relationships (FK / cardinality / cascade), PII / sensitive data classification + encryption at-rest + retention, migration approach, index strategy.
Spec-specific TC: migration tests, constraint tests (FK / NOT NULL / unique), PII handling tests, data retention tests.
8.5.4 SPEC-INT¶
Type-specific frontmatter: integration-pattern (request-response / event-driven / message-queue / webhook / file-transfer), direction, counterparty, sla, idempotency.
Mandatory body: integrated systems, exchange contract, failure modes + retry strategy, idempotency + dedup, security between systems, observability (correlation IDs).
Spec-specific TC: contract tests with a counterparty mock, failure injection, idempotency, end-to-end TC tc-type: contract.
Note: SPEC-INT replaces the existing INT-SR (§8.7 migration).
8.5.5 SPEC-PROC¶
Type-specific frontmatter: process-style (bpmn / state-machine / saga / choreography / orchestration), state-count, participants[], sla end-to-end and per step, compensation (defined / not-applicable / manual).
Mandatory body: process diagram (BPMN-flavor / Mermaid / link), states and transitions (for a state machine), participants and their roles, happy path, alternative scenarios and exceptions, timeouts and compensation (for saga), SLA.
Spec-specific TC: happy path E2E, alternative paths, compensation tests (for saga), SLA tests.
8.5.6 SPEC-UI¶
Type-specific frontmatter: ui-platform, target-users[] (with references to ADAPT persona sections), design-system, accessibility-level (WCAG-A / AA / AAA), i18n, mockup-links[], baseline-images[] for VLM-judge tests.
Mandatory body: overall interface structure, key screens, user journeys without technical details, cross-cutting elements (access rights / notifications / error / empty states), tone and style, accessibility, i18n.
Spec-specific TC: VLM-judge against a baseline (judge ≠ production isolation), accessibility (axe-core / Pa11y), i18n (string overflow / RTL), user journey E2E.
Note: SPEC-UI replaces the existing UIC (§8.7 migration).
8.5.7 SPEC-AI¶
Type-specific frontmatter: ai-pattern (rag / fine-tuning / prompt-engineering / tool-use / multi-agent), production-model (vendor / model / version), judge-model (MUST differ from production), context-strategy, eval-strategy (metric / threshold / baseline-dataset), cost-budget.
Mandatory body: AI component architecture (pipeline / orchestration / fallback), model card (capabilities / limits / known failure modes), context strategy, eval strategy with judge ≠ production isolation, cost management, hallucination mitigation, adversarial aspects.
Spec-specific TC: eval against a baseline (judge isolated), adversarial (prompt injection as a negative TC), cost regression, hallucination tests.
Note: SPEC-AI replaces the existing AIC. Isolation judge ≠ production model is a mandatory requirement of the standard for all eval-TC.
8.5.8 SPEC-SEC¶
Type-specific frontmatter: security-domains[], auth-model (authn / authz strategies), data-classification[] (PII-high / PCI / internal), threat-model-method (STRIDE / PASTA / OCTAVE), compliance[], incident-response reference in SPEC-OPS.
Mandatory body: auth model (authn flow / authz rules), data classification with protection, threat model (STRIDE table with a mitigation for each threat), secrets management, audit (what is logged / retention / access), encryption (at-rest / in-transit / key management), compliance mapping (references to specific clauses).
Spec-specific TC: authn (pos + neg), authz (RBAC matrix), threat-test (each STRIDE threat → at least 1 negative TC), audit log, secrets leakage.
8.5.9 SPEC-OPS¶
Type-specific frontmatter: deployment-style, environments[] (dev / staging / prod with purpose and scale), slo, observability (logs / metrics / traces / alerting), runbook-link, disaster-recovery (rto / rpo / backup-strategy).
Mandatory body: environments, deployment process (CI/CD pipeline / gating / rollout strategy), SLO (availability / latency / error budget), observability, alerting (critical alerts / escalation), runbook, capacity planning, disaster recovery.
Spec-specific TC: deployment tests (smoke), SLO regression (load testing), failover (DR drills), observability (alerts fire when expected).
8.5.10 SPEC-TEST¶
Type-specific frontmatter: benches[] (bench topology: nodes, versions, what is live / what is emulated), counterparties[] (emulators and sandbox instances of external systems — one entry per integration), datasets[] (a dataset on both sides of the integration: volume, provenance, anonymized: boolean, contains-real-client-data: boolean), reconciliation-rules[] (rules for reconciling results against the data of foreign systems), run-config (what is mocked, what is live, the run order), client-signature (mandatory if at least one dataset carries the client's real or personal data).
Mandatory body: bench topology; the list of external systems and the way each is represented (real / sandbox / emulator — with rationale); datasets on both sides of every integration; reconciliation rules (where the expected result lives, if it is not in our system); run configuration; the data policy (volume, anonymization, retention period).
Spec-specific TC: reproducibility (a repeated run on the same bench yields the same result); counterparty validity (the sandbox answers like the real system — otherwise the proof is fictitious); dataset integrity (the data conforms to the declared schema and volume).
Link to TC. Every TC with automation.kind: dynamic MUST carry an environment-ref to a SPEC-TEST (§9.3): "the test passed" is meaningful only against a concrete bench and concrete data. Static checks (the doc-lint of §9.8, the structural TC of §9.8.1) require no bench — the analyzer works over artifacts — and the field does not apply to them. A change of bench or dataset increments the SPEC-TEST version and, per §10.5.4, invalidates verified on the dependent TC — precisely, without touching anything else.
The client signature. Volume, anonymization, and the admissibility of using the client's real data are a matter for the client's decision, not the contractor's. When contains-real-client-data: true or anonymization is incomplete, client-signature is mandatory.
8.5.11 SPEC-DOC¶
Type-specific frontmatter: deliverables[] (one entry per document: kind — user manual / administrator manual / training materials / other; audience; format; language), required-sections[] (the mandatory sections of each document — set as a requirement, not left to the contractor's discretion), traces-to[] (the BR / SR / SPEC whose behavior the document describes), version-binding (the rule matching the document version to the system version), acceptance-criteria[] (against what the document is accepted).
Mandatory body: the composition of the delivery (which documents and for which audience); the structure of each document; the requirements on it (completeness across the roles and scenarios declared in the requirements; version currency; language and format); the readiness criteria.
Spec-specific TC: a doc lint (§9.8) — mandatory.
Why the doc lint is mandatory. A non-verifiable SPEC does not pass QG-2 (§9.7, MVR-5 requires coverage of every normative statement). A SPEC-DOC without a machine check would either block the delivery or force a hole in MVR-5 for the sake of a single type. Its statements are therefore normed checkably: the presence of the mandatory sections, coverage of all roles and scenarios from the linked BR / SR, the match of the document version to the system version, format and language — all of this is checked mechanically (automation.kind: static). Substantive conformance to the implemented behavior ("the text does not lie about the system") is checked optionally by a judge agent through the already existing P7 / eval mechanism — no new entities are required.
8.6 Link to requirements and tasks¶
8.6.1 SR.constrained-by[]¶
An SR receives a constrained-by[] field in its frontmatter — typed references to SPEC. This is a graph, not a tree of parents. The SR's parent in the requirements tree is single (BR).
# SR frontmatter (example)
id: SR-05
parent:
id: BR-02
constrained-by:
- SPEC-UI-01
- SPEC-API-02
- SPEC-DATA-03
- SPEC-PROC-01
- SPEC-SEC-01
verified-by:
- TC-12
- TC-13
source:
adapt: ADAPT-001
adapt-section: "Forward §3" # see canonical identifier §8.4
8.6.2 TR.implements-spec[]¶
A TR (task) references its SR (parent in the tree) + one or more SPEC through implements-spec[]:
id: TR-42
title: "Implement endpoint POST /orders"
parent:
id: SR-05
implements-spec:
- SPEC-API-02
- SPEC-DATA-03
verified-by:
- TC-14
8.6.3 SPEC.depends-on[]¶
A SPEC MAY rest on another SPEC:
id: SPEC-API-02
title: "Orders REST API"
type: SPEC-API
depends-on:
- SPEC-DATA-03 # stable data schema
- SPEC-SEC-01 # auth model for endpoints
When an upstream SPEC changes (for example SPEC-DATA-03), all downstream artifacts (SPEC-API-02 and the SR linked through it) MUST be reviewed: either verified is reconfirmed (the change is compatible), or the downstream artifact passes re-verification through its own state machine (§10.7) and, until that completes, is not considered verified with respect to the new upstream version.
8.6.4 Auto-derived inverse edges¶
SPEC.referenced-by[] is recomputed by a substrate hook after each change to SR / TR / SPEC. An orphan SPEC (without referenced-by[] and without an active status) is a warning in the quality report.
8.7 Migration UIC / AIC / INT-SR / TS → SPEC-*¶
8.7.1 Mapping table¶
| Old type | New type | Migration kind |
|---|---|---|
UIC-NN |
SPEC-UI-NN |
Rename ID + move to specs/ui/ |
AIC-NN |
SPEC-AI-NN |
Rename ID + move to specs/ai/ |
INT-SR-NN |
SPEC-INT-NN |
Rename ID + move to specs/int/ |
TS-NN |
SPEC-<TYPE>-NN (distribution) |
Manual review of each TS; an AI agent classifies the content, the architect approves in one click |
8.7.2 Atomic migration¶
Migration is one atomic change unit (V2) at the project level. Parallel existence of the old types (UIC / AIC / INT-SR / TS) and SPEC-* as the source of truth is prohibited.
Procedure (substrate-independent):
- Preparation: an AI agent classifies each existing TS-NN into one of the 11 SPEC types.
- The architect approves the classification.
- Atomic change: rename IDs (UIC→SPEC-UI; AIC→SPEC-AI; INT-SR→SPEC-INT; TS→SPEC-*), move files to
specs/<type>/, update all references in BR / SR / TR / TC frontmatter (parent: UIC-NN→constrained-by: [SPEC-UI-NN]). - Regeneration of auto-derived files (REQUIREMENTS.md, SPECS.md, inverse edges).
- CI check: absence of orphan references and old IDs.
8.7.3 ID immutability¶
After migration, SPEC IDs are immutable (see V1, §3.3.1). Renaming SPEC-API-02 → SPEC-API-08 is prohibited. Replacement is through deprecated + a new ID with replaces[].
8.8 Quality gates for SPEC¶
A SPEC has a dedicated state machine (chapter 10 §10.7):
| State | Transition condition |
|---|---|
draft |
Created; mandatory frontmatter fields are being filled |
review |
Ready for review; mandatory body sections (§8.4.1) and type-specific ones (§8.5) are present |
approved |
The architect confirmed; depends-on[] consistency checked |
verified |
All mandatory spec-specific TC (chapter 9 §9.7) are green |
obsolete |
Replaced or no longer relevant; replaced-by is mandatory |
Link to QG-0 / QG-2 of SENAR:
- QG-0 (the task has a goal/AC) is extended: for tasks implementing a SPEC,
implements-spec[]in the TR frontmatter is mandatory. - QG-2 (a
donetask has evidence) is extended: for tasks implementing a SPEC, a TC of the corresponding spec-specific kind (chapter 9 §9.7) is mandatory.
8.9 Storage layout¶
8.9.1 At the system level¶
[requirements-substrate]/ # root of the requirements substrate (layout — guide/03 or guide/04)
br/
sr/
specs/
arch/ SPEC-ARCH-NN-*.md
api/ SPEC-API-NN-*.md
data/ SPEC-DATA-NN-*.md
ui/ SPEC-UI-NN-*.md
ai/ SPEC-AI-NN-*.md
int/ SPEC-INT-NN-*.md
proc/ SPEC-PROC-NN-*.md
sec/ SPEC-SEC-NN-*.md
ops/ SPEC-OPS-NN-*.md
test/ SPEC-TEST-NN-*.md
doc/ SPEC-DOC-NN-*.md
adapt/
tz/
SPECS.md # auto-generated index
All 11 SPEC types (§8.3) are allowed at any
level; thespecs/<type>/subfolders are created as needed — not all are mandatory at the system level.
8.9.2 At the subsystem level¶
[subsystem-substrate]/ # subsystem scope
br/ # if it has its own business side
sr/
specs/
arch/ SPEC-ARCH-NN-*.md # subsystem architecture
api/ SPEC-API-NN-*.md
data/ SPEC-DATA-NN-*.md
ui/ SPEC-UI-NN-*.md
ai/ SPEC-AI-NN-*.md
int/ SPEC-INT-NN-*.md
proc/ SPEC-PROC-NN-*.md
sec/ SPEC-SEC-NN-*.md
ops/ SPEC-OPS-NN-*.md
test/ SPEC-TEST-NN-*.md
doc/ SPEC-DOC-NN-*.md
adapt/
SPECS.md
The substrate-native storage implementation is substrate-specific (see guide/03, guide/04).
8.9.3 SPECS.md — auto-generated index¶
SPECS.md is an auto-generated registry of all SPEC: ID, type, title, status, link to the verifiable requirement, link to the file. Marked linguist-generated=true. Regeneration triggers — every change to SPEC frontmatter or every approve / verify gate.
8.10 Links to other chapters¶
| Chapter | Link |
|---|---|
| 02 Methodology positioning | SPEC as a parallel axis — a consequence of the Source-of-Truth inversion |
| 06 Requirements hierarchy | SR.constrained-by[], TR.implements-spec[] |
| 07 ADAPT | SPEC references ADAPT through source.adapt |
| 09 Test cases | Spec-specific TC types (the table of mandatory TC kinds for each SPEC type) |
| 10 Lifecycle and QG | SPEC state machine + QG extensions for SPEC |
| 03 Substrate versioning | SPEC IDs are immutable (V1); migration is atomic (V2) |
| 11 Maturity model | RENAR-3+: all 11 SPEC types where applicable |
| reference/02 — schemas | Full machine-readable schema for each type-specific extension |
| reference/05 — knowledge graph schema | constrained-by[], implements-spec[], depends-on[] as edge types in the graph |