Skip to content

Add shared decision-record front matter to the four records under Documentation/decisions #247

Description

@woksin

Summary

Add the shared decision-record front matter (id, status, decided, decider, enforced-by, and the two-way supersession fields) to the four records under Documentation/decisions/, keeping the Starlight keys, so this repository's decisions can be checked mechanically and cited by id from other Cratis repositories.

Current behaviour

  • Documentation/decisions/ holds 0001-dom-coupled-contract.md, 0002-component-classification.md, 0003-kernel-boundary.md, 0004-stable-presentation-renderer-profile.md, index.md and toc.yml.
  • Front matter is Starlight-only, for example 0003-kernel-boundary.md lines 1-7: title, description, sidebar: { order: 3, badge: { text: Accepted, variant: tip } }. The status lives in body prose (**Status:** Accepted, line 9) and in the badge text, so it is stated twice and readable by neither a schema nor a checker. There is no id (identity is the filename ordinal), no decided date, no decider, no supersedes / superseded-by.
  • ESLint/lib/noReactInKernel.js:22 points at Documentation/decisions/0003-kernel-boundary.md as the rule's url, and ESLint/README.md:67,71 names the same path. The pointer runs only from the check to the decision: nothing in the record names ESLint/lib/noReactInKernel.js or ESLint/lib/kernelBoundary.js, so deleting or renaming the rule leaves the decision claiming an enforcement that no longer exists.

Desired behaviour

Each record gains, above the Starlight keys:

id: COMP-0003
status: accepted            # proposed · returned · accepted · rejected · deferred · superseded
stage: verified             # none · implemented · verified
class: contract             # strategy · contract · product · working
decided: 2026-MM-DD
decider: <named maintainer>
supersedes: []
superseded-by: []
applies-to: [Source/**, ESLint/**]
enforced-by: [ESLint/lib/noReactInKernel.js, ESLint/lib/kernelBoundary.js]
review-trigger: <what reopens this>

The Starlight title, description and sidebar keys stay; the sidebar badge is derived from status at build time or kept in sync by a check; the body **Status:** line is dropped in favour of the front matter. index.md gains a census line (4 records: 4 accepted) that a checker can compare with the files.

Acceptance

Done when:

  • All four records carry the fields; enforced-by on 0003 names the two ESLint files and each path resolves; status and the badge agree.
  • The Starlight site builds and renders the four pages unchanged apart from the badge source.
  • When the shared verify-decisions reusable workflow exists in Cratis/Workflows, this repository adds the wrapper and it runs green; until then a small script in Documentation/ (or a test) asserts the fields and the enforced-by paths.

Verify by:

for f in Documentation/decisions/000*.md; do head -20 "$f" | grep -q '^id: COMP-' || { echo "missing id: $f"; exit 1; }; done
node -e "for (const p of ['ESLint/lib/noReactInKernel.js','ESLint/lib/kernelBoundary.js']) require('fs').accessSync(p)"
<the repository's documentation build command>   # site builds, four decision pages render

Mutation proof: rename ESLint/lib/kernelBoundary.js in a scratch branch; the enforced-by check fails naming COMP-0003.

Out of scope

Writing new decisions; changing the ESLint rule; the shared checker itself (Cratis/Workflows).

Dependencies

Source: AI-Learning F-87. Depends on: D-0002 (one record format; the field names above follow it). Related: the verify-decisions reusable workflow issue in Cratis/Workflows.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions