Specification authority and embedded decisions

Platform spec feature

Specification authority and embedded decisions

Back to Spec maintenance ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (5)

1. 0001-language-law-in-language-meta Language law lives only in language-meta Accepted

   User-visible semantics are normative only under language-meta unless a documented cross-domain exception applies.

   Context

   Platform-spec domains multiplied without a single place for “what valid Beskid code means,” inviting duplicate type and evaluation tables in compiler and tooling chapters.

   Decision

   Language law — syntax, types, evaluation, contracts, memory, and cross-cutting language rules — must be defined only under Language meta, except where another domain page declares an explicit cross-domain exception and links to the owning language-meta chapter.

   Consequences

   New language semantics start in language-meta; implementation domains link back instead of redefining tables.

   Verification anchors

   packages/trudoc/src/verify/platform-spec-content.ts; cd site/website && bun run verify:trudoc -- --preset ci.

   Open full ADR page

2. 0002-implementation-domains-defer Implementation domains defer to language-meta Accepted

   Compiler, execution, core-library, and tooling realize language law without duplicating normative semantics.

   Context

   Pipeline and host details were written as if they owned user-visible meaning, overlapping language-meta chapters.

   Decision

   Compiler, Execution, Core library, and Tooling specify how the reference platform realizes language-meta. They must not redefine semantics already owned there; they must defer with relatedTopics (for example defers-to, implements) instead of duplicating normative key tables.

   Consequences

   Classification happens before authoring: “what does valid code mean?” → language-meta first; crates and phases link back.

   Verification anchors

   relatedTopics frontmatter validation in verify:trudoc --preset ci.

   Open full ADR page

3. 0003-spec-leads-code Specification leads implementation Accepted

   Observable behavior changes ship with normative spec updates; tests verify drift but do not replace missing contract text.

   Context

   README intent and crate behavior diverged when implementation shipped without a matching platform-spec change set.

   Decision

   Implementation that alters observable language or platform behavior must be preceded or accompanied by normative spec updates. The spec is the authority; tests and crates are verification anchors, not substitutes for missing contract text. Cross-cutting inception record: D-INC-0001.

   Consequences

   Contributors pair spec and code in one change set; CI content gates block Standard stubs.

   Verification anchors

   Project inception ADR 0001; verify:platform-spec-content.

   Open full ADR page

4. 0004-adr-per-decision-files One ADR file per closed decision Accepted

   Standard features publish adr/ with specLevel adr, stable adrId, and Context/Decision/Consequences sections.

   Context

   Monolithic decisions-record articles and hub prose duplicated the same choices without a stable identifier or reader ADRs tab.

   Decision

   Each Standard feature must publish closed choices under adr/ as one file per decision (specLevel: adr, stable adrId, adrStatus, adrDate). Body must include ## Context, ## Decision, ## Consequences; add ## Verification anchors when testable. Legacy decisions-record.mdx and hub ## Decisions summaries remain valid during migration; new work must use adr/. Inception cross-cutting ADRs stay under Project inception.

   Consequences

   Superseded ADRs set supersedesAdr or link replacements in Consequences with a Git revision note. Hub ## Decisions summarizes by adrId only—no full ADR prose duplication.

   Verification anchors

   checkAdrSections and checkStandardFeatureDecisions in packages/trudoc/src/verify/platform-spec-content.ts.

   Open full ADR page

5. 0005-proposed-vs-standard-maturity Proposed vs Standard maturity gates Accepted

   Standard pages are enforceable contracts; Proposed pages must not be cited as language law.

   Context

   Standard pages shipped with circular stubs or without decisions, while readers treated every platform-spec URL as enforceable law.

   Decision

   status	Meaning	Requirements
   Proposed	Incomplete or unstable	May omit full verification anchors; must not be cited as enforceable language law in conformance arguments
   Standard	Enforceable platform contract	Must include normative MUST/SHOULD/MAY prose, verification anchors, and hub ## Decisions (or linked decisions-record)

   Any Standard page failing content gates (circular canon stubs, placeholder-only bundles, missing decisions) must downgrade to Proposed until restored.

   Consequences

   Maturity is explicit in frontmatter; CI strict mode can fail scaffold Standard pages.

   Verification anchors

   verify:platform-spec-content with --strict; LANGUAGE_META_CIRCULAR_CANON_ALLOWLIST for tracked exceptions.

   Open full ADR page

Articles

• No directly attached article pages for this node.

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 0 SpecSection(s) · 7 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	no	no
implementation-anchors	no	no

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Spec maintenance

  Parent area

• Feature
  Feature Hub + Article Bundle template

  Authoring structure for hubs and bundles

• Feature
  Release and versioning policy

  Version axis and maturity bands

• Domain
  Language meta

  Canonical language law domain

Normative platform contract

1. Language law — User-visible semantics (syntax, types, evaluation, contracts, memory, and cross-cutting language rules) must be defined only under the Language meta domain, except where another domain page explicitly declares a cross-domain exception and links to the owning language-meta chapter.
2. Implementation law — The Compiler, Execution, Core library, and Tooling domains specify how the reference platform realizes language-meta. They must not redefine semantics already owned by language-meta; they must defer with relatedTopics (for example defers-to, implements) instead of duplicating normative key tables.
3. Spec leads code — Implementation changes that alter observable language or platform behavior must be preceded or accompanied by normative spec updates. The spec is the authority; tests and crates are verification anchors, not a substitute for missing contract text.
4. Architecture decision records (ADRs) — Each Standard feature must publish closed choices under adr/ as one file per decision (specLevel: adr, stable adrId). The feature reader exposes an ADRs tab with expandable Context / Decision / Consequences detail. Legacy decisions-record.mdx articles and hub ## Decisions summaries remain valid during migration but new work must use adr/. Cross-cutting inception decisions live under Project inception.

Language law vs implementation domains

Concern	Owning surface	Realization surfaces
What programs mean (types, control flow, contracts)	language-meta	compiler phases, execution runtime
Author-facing manifests and CLI	tooling (authoring)	compiler resolution (graph, cycles)
Standard library API shape	core-library	execution syscalls, compiler lowering
Diagnostics users see	language-meta + compiler registry	tooling/LSP presentation

When adding a feature, classify the topic before writing: if a reader asking “what does valid Beskid code mean?” would need the answer, it belongs in language-meta first; pipeline, crate, or host details belong in implementation domains with links back.

Maturity — Proposed vs Standard

status	Meaning	Requirements
Proposed	Incomplete, unstable, or under active design	May omit full verification anchors; must not be cited as enforceable language law in conformance arguments
Standard	Enforceable platform contract	Must include normative MUST/SHOULD/MAY prose, verification anchors (tests, crates, or explicit registry links), and ## Decisions on the feature hub (or a linked decisions-record article)

Any Standard page that fails content gates (circular “canonical chapter” stubs, placeholder-only article bundles, missing decisions) must be downgraded to Proposed until restored.

ADR file contract

Each ADR file at platform-spec/<domain>/<area>/<feature>/adr/<slug>.mdx must use:

Field	Rule
specLevel	adr
adrId	Stable identifier (for example D-INC-0001, D-CORE-CONC-0003)
adrStatus	Accepted, Superseded, or Proposed
adrDate	ISO date when the decision closed (inception ADRs should reflect historical dates)
Body	## Context, ## Decision, ## Consequences; ## Verification anchors when testable

Superseded ADRs must set supersedesAdr or link the replacement adrId in Consequences and note the Git revision (not a URL version segment).

Hub decisions summary

A Standard feature hub must include ## Decisions that either lists open items or states no open decisions and links the adr/ set (reader ADRs tab). Hub bullets must not duplicate full ADR prose—summarize and link by adrId.

Related maintenance policies

• Feature Hub + Article Bundle template — Required hub sections, anti-stub rules, and article minimums.
• Release and versioning policy — Git as version axis; v0.x delivery bands.
• Non-normative bridge docs policy — Legacy doc trees and mapping pages.

Decisions

No open decisions. Closed maintenance ADRs under adr/ — D-COMM-AUTH-0001 through D-COMM-AUTH-0005 (reader ADRs tab).