Non-normative bridge docs policy

Platform spec feature

Non-normative bridge docs policy

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 (3)

1. 0001-bridge-docs-non-normative Bridge documents are non-normative by default Accepted

   Migration and mapping pages are transitional navigation aids, not final behavior authority.

   Context

   Legacy Starlight paths and informal mapping tables were cited in reviews as if they were language law.

   Decision

   Bridge documents (migration guides, mapping tables, terminology crosswalks) are non-normative by default unless a Standard platform-spec feature page explicitly declares normative status. Migration mapping pages must not be the final authority for platform behavior.

   Consequences

   Legacy spec mapping stays informative; normative fixes land under platform-spec/.

   Verification anchors

   PSC005 legacy bridge checks on Standard pages linking /execution/ or /corelib/.

   Open full ADR page

2. 0002-canonical-destination-links Bridge pages must link canonical destinations Accepted

   Non-normative bridges label status near the top and link superseding normative feature hubs.

   Context

   Readers stopped at bridge pages without reaching the owning Standard feature contract.

   Decision

   Every non-normative bridge page must link to one or more canonical normative destinations and label those links as canonical. Near the top each bridge must state: non-normative status, why the page exists, and which normative page(s) own the behavior. Canonical links must be direct platform-spec URLs with human-readable relation labels; bi-directional discoverability is required during active migration windows when practical.

   Consequences

   Standard pages that link legacy prefixes must mark those links non-normative in prose or relatedTopics.

   Verification anchors

   checkStaleLegacyBridge in platform-spec-content.ts.

   Open full ADR page

3. 0003-migration-mapping-page-shape Migration mapping page required sections Accepted

   Mapping pages include scope, canonical destinations grouped by domain, and retirement notes.

   Context

   Ad-hoc mapping tables mixed partial coverage with implied normative scope.

   Decision

   Migration mapping pages must include: (1) a one-sentence non-normative notice; (2) a Canonical destinations section linking target feature hubs; (3) a Mapping scope section stating coverage and exclusions; (4) a maintenance note for retirement timing. Multi-domain mappings must group links by destination domain/area.

   Consequences

   Bridge pages become checklist-complete before merge; retirement removes the bridge when canonical nav suffices.

   Verification anchors

   Legacy spec mapping structure review in PR template.

   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) · 5 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

  Canonical authoring model

Normative platform contract

1. Bridge documents (migration guides, mapping tables, and terminology crosswalks) are non-normative by default unless a page explicitly declares normative status in a canonical platform-spec feature page.
2. Migration mapping pages must not be used as the final authority for platform behavior; they are transitional navigation aids.
3. Every non-normative bridge page must link to one or more canonical normative destination pages and clearly label those links as canonical.

Required labeling for bridge docs

Each bridge document must state all of the following near the top of the page:

• That the page is non-normative.
• Why the page exists (for example, migration from legacy organization).
• Which canonical normative page(s) supersede or own the described behavior.

Migration mapping page requirements

Migration mapping pages must include:

1. A one-sentence non-normative notice.
2. A “Canonical destinations” section that links to target Feature Hub and/or feature pages.
3. A “Mapping scope” section that states what is covered and what is intentionally excluded.
4. A maintenance note describing when the mapping can be retired.

When mappings span multiple domains or areas, pages must group links by destination domain/area so readers can reach canonical sources without interpretation.

Canonical link quality rules

Canonical destination links must satisfy:

• Direct links to canonical platform-spec pages (not only intermediate redirects).
• Human-readable relation labels (for example, “Canonical feature contract”).
• Bi-directional discoverability when practical (canonical pages should also link to major migration bridges during active transition windows).

Decisions

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