Skip to content

docs: documentatie-coverage voor accepted RFC's en engine-features#828

Draft
anneschuth wants to merge 1 commit into
mainfrom
docs/rfc-coverage-traceability
Draft

docs: documentatie-coverage voor accepted RFC's en engine-features#828
anneschuth wants to merge 1 commit into
mainfrom
docs/rfc-coverage-traceability

Conversation

@anneschuth

Copy link
Copy Markdown
Member

Waarom

Een audit van alle RFC's tegenover de prose-documentatie liet zien dat de accepted RFC's en een aantal gebouwde engine-features dun of niet gedekt waren buiten de RFC's zelf. Aanleiding was traceability: dat concept had vijf regels in how-it-works en geen eigen pagina, terwijl de engine een rijk trace-mechanisme heeft met echte voorbeelden.

Deze PR dicht de grootste gaten en zet de rest op een getrackte backlog. Draft- en proposed-RFC's blijven buiten scope; hun eigen pagina's zijn daarvoor de bron.

Wat

Vijf nieuwe concept-/referentiepagina's plus een coveragematrix:

Pagina RFC('s) Inhoud
concepts/traceability engine / RFC-007 Hoe je een trace leest: node-types, de box-drawing-boom, en een echte zorgtoeslag-trace met cross-law-keten, IoC-delegatie, gecachet resultaat en twee Awb-hooks. Plus hoe je er zelf een genereert.
concepts/competent-authority RFC-002 Bevoegd gezag op artikelniveau: name + type (INSTANCE/CATEGORY) en de #-referentievorm.
concepts/temporal-and-dates RFC-019, RFC-021 Versieselectie met valid_to en eerlijke afhandeling van verlopen referenties; datumvergelijking en DATE_DIFF.
concepts/notes-and-annotations RFC-005, RFC-018 Stand-off notes, TextQuoteSelector, fuzzy matching en afgeleide autoriteit.
reference/conformance RFC-014 De taal-agnostische conformance-suite en wat er vandaag wordt afgedwongen.
reference/documentation-coverage alle accepted Per-RFC coveragematrix en de backlog.

Daarnaast: de Traceability-sectie in how-it-works ingekort tot een verwijzing, en de nieuwe pagina's in de sidebar gezet.

Grondslag van de voorbeelden

Alle voorbeelden komen uit artefacten die in deze repo staan en via tests in sync blijven, niet uit de externe corpus-repo:

  • de trace-snapshot packages/engine/tests/expected_zorgtoeslag_trace.txt (gepind door een snapshot-test);
  • de BDD-features features/einddatum.feature, features/date_operations.feature, features/notes.feature;
  • de conformance-manifests onder conformance/;
  • een echte annotatie in corpus/annotations/wet_op_de_zorgtoeslag/annotations.yaml.

De geciteerde trace- en gherkin-fragmenten zijn karakter-voor-karakter tegen de bron geverifieerd.

Checks

  • npm run build bouwt schoon (82 pagina's).
  • check-links.mjs: geen kapotte interne links.
  • check-heading-order.mjs: geen rang-sprongen.
  • Pre-commit hooks groen.

Backlog (apart, niet in deze PR)

reference/documentation-coverage legt vast wat nog mist: de "waarom Rust" (RFC-006) en "waarom YAML" (RFC-011) rationale, en kleinere ongedocumenteerde features (traject-samenwerking, law-graph, WASM-API, data-sources, TUI, CLI-binaries, CVDR-harvesting, LLM-provider).

Vult de grootste gaten tussen de accepted RFC's en de prose-documentatie,
gegrond op gecommitte engine-testfixtures (trace-snapshots, BDD-features,
conformance-manifests), niet op de externe corpus-repo.

Nieuwe pagina's:
- concepts/traceability: hoe je een trace leest, met de echte
  zorgtoeslag-trace (cross-law-keten, IoC-delegatie, gecachet resultaat,
  twee Awb-hooks) en hoe je er zelf een genereert (engine-trace).
- concepts/competent-authority (RFC-002): bevoegd gezag op artikelniveau,
  INSTANCE/CATEGORY en de #-referentievorm.
- concepts/temporal-and-dates (RFC-019 + RFC-021): versieselectie met
  valid_to en eerlijke afhandeling van verlopen referenties;
  datumvergelijking en DATE_DIFF.
- concepts/notes-and-annotations (RFC-005 + RFC-018): stand-off notes,
  TextQuoteSelector, fuzzy matching en afgeleide autoriteit.
- reference/conformance (RFC-014): de taal-agnostische conformance-suite
  en wat er vandaag wordt afgedwongen.
- reference/documentation-coverage: per-RFC coveragematrix en de backlog
  van nog te schrijven onderwerpen.

Verkort de Traceability-sectie in how-it-works tot een verwijzing en zet de
nieuwe pagina's in de sidebar.
@github-actions

Copy link
Copy Markdown

Preview Deployment — docs — docs

Your changes have been deployed to a preview environment:

URL: https://docs.pr828.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant