Skip to content

wiki definition

Alex Flom edited this page May 9, 2026 · 5 revisions

UOR Framework Wiki — Definition

Status

In force. This document defines the structure, validation discipline, build pipeline, and authoring workflow for the wiki at https://github.com/UOR-Foundation/UOR-Framework/wiki. The wiki is the authoritative specification for Prism — the system defined by uor-foundation, with runtime in prism and replay surface in prism-verify (per ADR-017 in the wiki itself). The wiki specifies Prism along three coordinated standards: arc42 + C4 (architecture), OPM ISO 19450 (conceptual model), and ISO/IEC/IEEE 15288 (system lifecycle).

Validators V1–V5 are implemented and enforced by every build. Validators V6–V8 (OPL syntax, OPD/OPL bimodal coherence, ISO 15288 process structural superset) are declared by this specification and reconciled toward by subsequent commits.

This document lives in the wiki repository at the root, alongside the sources and infrastructure it specifies. The README.md is the contributor-facing workflow; this document is the normative specification that workflow implements.

What the wiki is

The wiki is a normative specification of Prism authored under three coordinated standards: arc42 + C4 for the architecture, OPM (ISO 19450) for the conceptual model, and ISO/IEC/IEEE 15288 for the system lifecycle. It is the source of truth for what Prism is. The three published Rust crates are accountable to the wiki, not the other way around.

The wiki is hosted in UOR-Framework.wiki.git — a git repository GitHub provisions for every project. Its committed .md files are what GitHub renders at the wiki URL. This document defines how those .md files are produced.

The wiki is not hand-edited. AsciiDoc sources under src/arc42/ are authored; Structurizr DSL under src/c4/ is authored; OPM sources under src/opm/ are authored; AsciiDoc sources under src/15288/ are authored; all render through canonical upstream tooling to GFM markdown and SVG, and the rendered output is committed at the wiki repo's root for GitHub to display. Manual edits via the GitHub web UI are technically possible but are overwritten by the next build, making the web UI useless for sustained authoring.

Authoritative specifications

Every aspect of the wiki's content and form delegates to a canonical external specification. The wiki authors none of these specifications; the wiki conforms to them.

Concern Authority Tool
arc42 structure (12 chapters, sub-headings) github.com/arc42/arc42-template (English; transitively pinned by arc42-generator's own submodule) Asciidoctor Ruby API + workspace-authored structural-comparison script
arc42 → Markdown rendering github.com/arc42/arc42-generator Groovy build (docker compose up) producing GFM markdown via AsciidoctorJ + Pandoc
C4 model semantics Structurizr DSL grammar (Simon Brown, C4 model author) structurizr.war (the consolidated Structurizr tooling, github.com/structurizr/structurizr); commands validate and export
Markdown well-formedness CommonMark Specification 0.31.2 + GitHub Flavored Markdown Spec cmark-gfm (the GFM reference parser; permissive — see V4 scope notes)
GitHub markup-stage rendering github.com/github/markup (the Ruby library GitHub itself uses) github-markup Ruby gem invoked via a wrapper script (covers the markup-to-HTML stage; does not cover GitHub's downstream sanitization, syntax highlighting, emoji, task list, or CDN-image filters)
OPL syntax ISO 19450:2015 Annex A (Object-Process Language EBNF specification) Workspace-authored EBNF parser; the EBNF itself is transcribed from the standard's Annex A and committed at tools/iso-19450-opl.ebnf
OPD/OPL bimodal coherence ISO 19450:2015 (Object-Process Diagram graph grammar; OPD/OPL semantic equivalence) Workspace-authored cross-reference validator; the coherence rule is transcribed from the standard and committed at tools/iso-19450-opd-coherence.txt
ISO 15288 process structure ISO/IEC/IEEE 15288:2023 Clause 6 (system lifecycle process catalog) Workspace-authored structural-superset validator; the process list is transcribed from Clause 6 and committed at tools/iso-15288-processes.txt

The arc42-template is the AsciiDoc golden master. The arc42-generator is the project's own conversion pipeline that already runs cmark validation on its markdown output. The consolidated Structurizr tooling at github.com/structurizr/structurizr is the C4 model's reference implementation, distributed as structurizr.war; it replaces the legacy structurizr-cli, structurizr-lite, and on-premises installation, all of which are end-of-life as of the consolidation announced January 2026. cmark-gfm is the parser GitHub itself uses for markdown. github-markup is the renderer GitHub itself uses for wiki pages. ISO 19450:2015 is the OPM standard; its Annex A specifies OPL syntax in EBNF and the standard specifies the OPD graph grammar and the OPD/OPL semantic-equivalence (bimodal coherence) rule. ISO/IEC/IEEE 15288:2023 is the system lifecycle standard; its Clause 6 specifies the catalog of system lifecycle processes the wiki's lifecycle chapters are organized under.

No workspace-authored correctness rules exist in the wiki suite. Every validator's authority comes from a pinned upstream specification or transcribed standard; comparison logic in workspace-authored scripts is restricted to mechanical operations (file enumeration, set equality, heading containment, log-pattern matching against pinned patterns) over the upstream-declared structure. Where a script imposes additional discipline beyond the upstream specification — V1's structural-superset rule for H2 headings, V2's fail-on-warning posture for the generator's non-fatal cmark/image scans, V7's rule that every SVG <text> element must correspond to an OPL-declared entity — that discipline is named in the relevant validator's specification below and is bounded to mechanical checks. For V6, V7, and V8, where the upstream authority is a printed standard rather than a machine-readable artifact, the wiki commits a workspace-authored transcription of the relevant portion of the standard at the path named in the table. The transcription's correctness against the standard is verifiable by reading the file against the published standard; the transcription is the third pin pattern (alongside git submodule and binary checksum) and is governed by the same maintainer- pushes-direct-with-justification discipline.

Wiki claims and their evidence

The wiki's normative claims are about Prism's architecture, behavior, and mathematical structure. Verification of those claims is the responsibility of the codebase, not the wiki:

  • Rust-level claims are verified by cargo test running the doctest examples in rustdoc comments and by the workspace's unit and integration tests.
  • Mathematical claims are verified by lake build running the UOR Lean 4 library, which carries a zero-sorry, no-unauthorized-axioms discipline.
  • Behavioral claims (end-to-end pipeline, certificate replay, etc.) are verified by the conformance suite at cargo run --bin uor-conformance.

Where wiki prose makes a claim that has a corresponding rustdoc test, Lean theorem, conformance entry, or other verifiable artifact, the wiki prose SHOULD reference the artifact by its source-side name. Examples:

  • "verified by the doctest in uor_foundation::triad::Triad::stratum"
  • "proven in UOR.Foundation.Triad.datum_stratum_eq_two_adic_valuation"
  • "exercised by conformance test pipeline-replay-equivalence"

These references are human-readable pointers, not build-time proof macros. The wiki's build pipeline does not resolve them; the codebase's own CI confirms the referenced artifacts hold. A reviewer reads the wiki and the codebase together to confirm that referenced artifacts exist and say what the wiki claims they say.

The wiki does not invent verification infrastructure. Rust doctests, Lean theorems, and the conformance suite are the mechanisms that exist; the wiki points at them.

Non-normative content partitions

In addition to the normative specification authored under the three coordinated standards (arc42 + C4, OPM ISO 19450, ISO/IEC/IEEE 15288), the wiki hosts non-normative content partitions for stakeholder-facing documentation that is not bound to a published external standard. These partitions go through the same source-edit / build.sh / staged-output discipline as the normative content; what distinguishes them is that no V1–V8 validator gates their structure (they are subject only to V4/V5, the well-formedness validators that gate any .md at the wiki root).

The current non-normative partitions:

Partition Source Authority Authoring stream
Scientific Methods and Results src/scientific/*.adoc Academic Documentation Working Group (Director of Research: Robin Wikoff) The working group submits content via GitHub issues against UOR-Foundation/UOR-Framework; a wiki maintainer authors the corresponding AsciiDoc under src/scientific/, runs ./scripts/build.sh, and pushes the regenerated wiki root.

A non-normative partition is added by:

  1. Creating the source directory under src/<partition-key>/.
  2. Adding a scripts/render-<partition-key>.sh that mirrors the render-15288.sh pandoc-pipeline pattern and follows reconciliation gap discipline (skip cleanly when the source dir is absent or empty).
  3. Wiring the render script into build.sh (Stage 3) and validate.sh (so V4/V5 see the rendered pages).
  4. Wiring a stage step into stage-to-wiki-root.sh (Stage 4) that copies the rendered pages to the wiki root with their canonical wiki-URL names.
  5. Updating src/wiki/Sidebar.adoc to surface the partition.
  6. Recording the partition in this section's table.

The architecture's substrate-extension lane (the typed verbs/axes/shapes declared by Layer-3 crates per ADR-030 and ADR-031 of the wiki itself) is unrelated to this partition mechanism — those are about Rust code that consumes the framework, not about wiki content.

Source repository layout

The wiki repo's top level (the post-Phase-4 desired state):

UOR-Framework.wiki/
├── src/                            # Authoring sources
│   ├── arc42/                      # AsciiDoc per arc42-template structure
│   │   ├── arc42-template.adoc     # Top-level include (mirrors upstream)
│   │   ├── version.properties      # Spec version (consumed by arc42-generator)
│   │   ├── adoc/
│   │   │   ├── 01_introduction_and_goals.adoc
│   │   │   ├── 02_architecture_constraints.adoc
│   │   │   ├── 03_system_scope_and_context.adoc
│   │   │   ├── 04_solution_strategy.adoc
│   │   │   ├── 05_building_block_view.adoc
│   │   │   ├── 06_runtime_view.adoc
│   │   │   ├── 07_deployment_view.adoc
│   │   │   ├── 08_concepts.adoc
│   │   │   ├── 09_architecture_decisions.adoc
│   │   │   ├── 10_quality_requirements.adoc
│   │   │   ├── 11_technical_risks.adoc
│   │   │   └── 12_glossary.adoc
│   │   └── images/                 # SVGs from Structurizr export land here
│   ├── c4/                         # Structurizr DSL
│   │   └── workspace.dsl           # Single canonical workspace
│   ├── opm/                        # OPM source files (per-OPD subdirectories)
│   │   ├── opd-order.txt           # Workspace-authored manifest: OPDs in
│   │   │                           # presentation order; SD/ first conventionally.
│   │   └── <opd-name>/             # One subdirectory per OPD; SD/ is the System Diagram
│   │       ├── opl.txt             # OPL prose text, conformant to ISO 19450 Annex A.
│   │       │                       # OPL is the canonical source for both modalities.
│   │       └── opd.svg             # SVG rendering of the OPD; verified by V7 against
│   │                               # what opl.txt declares. Produced by author's tool.
│   ├── 15288/                      # AsciiDoc per ISO 15288 process group
│   │   ├── agreement.adoc                       # Agreement Processes
│   │   ├── organizational-project-enabling.adoc # Organizational Project-Enabling Processes
│   │   ├── technical-management.adoc            # Technical Management Processes
│   │   └── technical.adoc                       # Technical Processes
│   ├── scientific/                 # Non-normative academic-documentation
│   │   │                           # partition (Director of Research stream).
│   │   │                           # AsciiDoc per page; filename = wiki-URL slug.
│   │   └── Scientific-Methods-and-Results.adoc  # Landing page (issue #7)
│   └── wiki/                       # Wiki-frame fragments (not arc42 chapters)
│       ├── Home.adoc
│       ├── Sidebar.adoc
│       └── Footer.adoc
├── build/                          # Local build output; gitignored
├── scripts/
│   ├── install-tools.sh            # Pin and install upstream tools
│   ├── validate.sh                 # Top-level: runs V1–V8
│   ├── build.sh                    # Top-level: render to wiki root
│   ├── v1-structural-alignment.rb  # V1 implementation (Ruby + Asciidoctor)
│   ├── v2-arc42-build.sh           # V2 wrapper around arc42-generator Docker build
│   ├── v3-structurizr.sh           # V3 wrapper around structurizr.war
│   ├── v4-cmark-gfm.sh             # V4 wrapper around cmark-gfm
│   ├── v5-github-markup.sh         # V5 shell wrapper
│   ├── v5-github-markup.rb         # V5 Ruby script invoked by the wrapper
│   ├── v6-opl-syntax.sh            # V6 wrapper around the OPL EBNF parser
│   ├── v6-opl-syntax.rb            # V6 Ruby implementation; parses .opl against pinned EBNF
│   ├── v7-opd-opl-coherence.sh     # V7 wrapper around bimodal-coherence checker
│   ├── v7-opd-opl-coherence.rb     # V7 Ruby implementation; cross-references SVG and OPL entities
│   ├── v8-iso-15288-superset.sh    # V8 wrapper around 15288 process structural-superset checker
│   ├── v8-iso-15288-superset.rb    # V8 Ruby implementation; checks process headings against pinned list
│   ├── render-opm-index.sh         # build.sh Stage 3c implementation; assembles Conceptual-Model.md
│   ├── render-scientific.sh        # build.sh Stage 3d implementation; renders src/scientific/*.adoc
│   ├── render-wiki-frame.sh        # Pandoc rendering for Home/Sidebar/Footer
│   ├── stage-to-wiki-root.sh       # build.sh Stage 4 implementation
│   └── check-wiki-state.sh         # Post-push detection script
├── tools/
│   ├── checksums.txt               # Pinned SHA-256 hashes
│   ├── versions.txt                # Resolved version strings, written by install-tools.sh,
│   │                               # read by build.sh Stage 1
│   ├── structurizr.war             # Downloaded by install-tools.sh; gitignored
│   ├── iso-19450-opl.ebnf          # OPL syntax in EBNF, transcribed from ISO 19450 Annex A
│   ├── iso-19450-opd-coherence.txt # OPD/OPL bimodal coherence rule, transcribed from ISO 19450
│   └── iso-15288-processes.txt     # ISO 15288 process catalog, transcribed from Clause 6
├── vendor/
│   └── arc42-generator/            # Submodule; transitively includes arc42-template
├── Gemfile                         # Ruby dependencies (Asciidoctor, github-markup, treetop)
├── Gemfile.lock                    # Pinned gem versions
├── Home.md                         # Rendered output (committed): wiki landing page
├── _Sidebar.md                     # Rendered output (committed): wiki sidebar
├── _Footer.md                      # Rendered output (committed): wiki footer
├── 01-Introduction-and-Goals.md    # Rendered output (committed): arc42 chapters
├── 02-Architecture-Constraints.md
├── 03-System-Scope-and-Context.md
├── 04-Solution-Strategy.md
├── 05-Building-Block-View.md
├── 06-Runtime-View.md
├── 07-Deployment-View.md
├── 08-Concepts.md
├── 09-Architecture-Decisions.md
├── 10-Quality-Requirements.md
├── 11-Technical-Risks.md
├── 12-Glossary.md
├── Conceptual-Model.md             # Rendered from src/opm/
├── Lifecycle-Agreement-Processes.md             # Rendered from src/15288/agreement.adoc
├── Lifecycle-Organizational-Project-Enabling-Processes.md  # Rendered from src/15288/organizational-project-enabling.adoc
├── Lifecycle-Technical-Management-Processes.md  # Rendered from src/15288/technical-management.adoc
├── Lifecycle-Technical-Processes.md             # Rendered from src/15288/technical.adoc
├── Scientific-Methods-and-Results.md            # Rendered from src/scientific/Scientific-Methods-and-Results.adoc (academic partition)
├── images/                         # Wiki-rendered SVGs (committed)
├── .gitignore
├── .gitmodules
├── README.md                       # Authoring workflow for contributors
└── wiki-definition.md              # This document; the normative specification

The src/, scripts/, tools/, vendor/, and README.md paths are wiki infrastructure. The committed .md files at the root are the rendered artifact GitHub displays.

The committed .md files MUST be byte-identical to the output of the most recent successful scripts/build.sh run from the corresponding sources. GitHub wiki repositories do not support pull requests, branches with review gates, or GitHub Actions; the wiki repo accepts direct pushes to its single branch. The discipline is therefore enforced through three mechanisms working together:

  1. Local build idempotence — scripts/build.sh Stage 5 fails if a second build produces output differing from the first, catching non-determinism at the contributor's machine before any push.
  2. Post-push detection script — scripts/check-wiki-state.sh, runnable by any wiki maintainer, clones the wiki repo into a scratch directory and runs scripts/build.sh Stage 4 only (re-staging from the committed source). It then compares every staged file against the wiki root using cmp(1). Any divergence is reported. The detection script is invoked manually by maintainers and is also suitable for invocation from a periodic cron job in any maintainer's environment.
  3. Repair procedure — when divergence is detected, the repair is to clone the wiki repo, run scripts/build.sh, commit the regenerated output, and push. This is documented in README.md and is the only sanctioned way to bring the wiki repo back into conformance.

A contributor who pushes mismatched output produces an incorrect commit that is detectable by the post-push script and repaired by the next maintainer who runs it.

Updating any pin (next section) is performed via direct push to the wiki repo, with scripts/build.sh re-run against the new pin and the regenerated output committed in the same commit. There is no PR review gate; the discipline is the build's own correctness contract.

Pinned external authorities

Every external tool is pinned. Updating a pin is a deliberate maintainer act performed by direct push to the wiki repo.

Tool Form Pin mechanism
arc42-generator Git submodule (transitively pins arc42-template via its own submodule) vendor/arc42-generator at a specific tagged commit
arc42-template Pinned transitively through arc42-generator/.gitmodules NOT pinned independently in this repo
structurizr.war Pre-built JAR distribution from github.com/structurizr/structurizr/releases tools/checksums.txt SHA-256 + version literal in install-tools.sh
Docker / Docker Compose System install Major version literal in install-tools.sh (Docker Engine ≥ 20.10, Compose v2)
cmark-gfm Built from source at pinned tag (used by V4 directly; arc42-generator ships its own copy in its Docker image for V2) Tag literal in install-tools.sh
github-markup Ruby gem Gemfile.lock (committed)
Asciidoctor (Ruby) Ruby gem (used by V1 directly and by V8 to parse src/15288/*.adoc ASTs) Gemfile.lock (committed)
treetop Ruby gem (PEG parser used by V6 to parse OPL against the pinned EBNF, and reused by V7 for OPL entity extraction) Gemfile.lock (committed)
JDK Required only by Structurizr; arc42-generator runs in Docker. OpenJDK 21. Major version literal 21 in install-tools.sh; minor version free
Ruby Required by V1, V6, V7, V8 implementations and by github-markup. Ruby ≥ 3.0. Major version literal 3 in install-tools.sh; minor version free
ISO 19450:2015 OPL EBNF Workspace-authored transcription of Annex A Committed at tools/iso-19450-opl.ebnf; correctness verifiable by reading the file against the published standard
ISO 19450:2015 OPD/OPL coherence rule Workspace-authored transcription of the standard's bimodal-coherence specification Committed at tools/iso-19450-opd-coherence.txt; correctness verifiable by reading the file against the published standard
ISO/IEC/IEEE 15288:2023 process catalog Workspace-authored transcription of Clause 6 process list Committed at tools/iso-15288-processes.txt; correctness verifiable by reading the file against the published standard

scripts/install-tools.sh is responsible for ensuring every pin is honored before any validation or build runs. Running validate.sh or build.sh against unpinned or wrong-version tooling MUST fail with a clear message.

The eight validators

Eight validators enforce structural, rendering, and conformance correctness. Each validator's authority is an upstream specification or pinned transcription thereof; workspace-authored components within validators are restricted to mechanical comparison logic and are explicitly named in each validator's specification below. V1–V5 cover arc42 + C4 architecture; V6–V7 cover OPM ISO 19450 conceptual modeling; V8 covers ISO 15288 system lifecycle process structure.

V1 — arc42 structural alignment

Authority. The chapter manifest at vendor/arc42-generator/arc42-template/EN/asciidoc/src/. The EN/asciidoc/src/ path is the canonical location of the per-chapter .adoc files in the upstream arc42-template repository; the arc42-template.adoc umbrella include sits one level up at EN/asciidoc/arc42-template.adoc. The arc42-template repository is reached as a nested submodule under arc42-generator (the generator pins a specific template revision in its own .gitmodules), guaranteeing that V1 reads from the same template version that V2's build pipeline consumes.

Implementation. A Ruby script at scripts/v1-structural-alignment.rb that loads both AsciiDoc trees using the Asciidoctor Ruby API (require 'asciidoctor'; Asciidoctor.load_file(path, safe: :safe, parse: true)). The script walks each parsed document's AST to extract its heading hierarchy. The script is the only workspace-authored component in V1; the structure being compared against comes exclusively from the upstream submodule.

What it does. For each of the 12 canonical chapters, the script:

  1. Confirms the local file src/arc42/adoc/NN_chapter_name.adoc exists with the canonical filename matching the upstream vendor/arc42-generator/arc42-template/EN/asciidoc/src/NN_chapter_name.adoc.
  2. Parses both files and compares heading levels 1 and 2 only (deeper levels are workspace-authored detail and are not bound to upstream).
  3. Asserts the local file's H1 heading text is identical (byte-equal, after trimming surrounding whitespace) to the upstream chapter's H1.
  4. Asserts the local file's set of H2 heading texts (likewise trimmed) is a structural superset of the upstream's H2 set: every upstream H2 text MUST appear as an H2 in the local file. The local file MAY add additional H2 sections beyond the upstream set; it MUST NOT omit any.

The "byte-equal trimmed" comparison is the only normalization applied. Heading text comparison is case-sensitive; punctuation and AsciiDoc inline markup are preserved verbatim.

Pass condition. All 12 chapters satisfy clauses 1, 2, 3, and 4.

Failure mode. For each violation, the script reports: the chapter file, the violation type (missing file / mismatched H1 / omitted H2), the offending heading text, and the line numbers in both upstream and local files. Exits non-zero on any violation.

V2 — arc42 build pipeline

(Authority, implementation, and pass/fail conditions unchanged from the bc7bf4d-pinned implementation. See scripts/v2-arc42-build.sh.)

V3 — Structurizr DSL validation and rendering

(Authority, implementation, and pass/fail conditions unchanged from the bc7bf4d-pinned implementation. See scripts/v3-structurizr.sh.)

V4 — CommonMark / GFM well-formedness

Authority. cmark-gfm (the GitHub-Flavored Markdown reference parser used by GitHub itself).

V4 covers all .md files at the wiki root: the 12 chapter files produced by V2 (renamed by build.sh Stage 4 to their canonical wiki page names), the three wiki-frame files (Home.md, _Sidebar.md, _Footer.md) produced by scripts/render-wiki-frame.sh, the four ISO 15288 lifecycle pages produced by Stage 3b, and the OPM conceptual model page produced by Stage 3c. The arc42-generator's umbrella file arc42-template-EN.md is NOT staged to the wiki root and therefore is NOT covered by V4.

(Other details unchanged from the bc7bf4d-pinned implementation.)

V5 — GitHub-markup rendering

(Unchanged from the bc7bf4d-pinned implementation.)

V6 — OPL syntax validation

Authority. ISO 19450:2015 Annex A, transcribed at tools/iso-19450-opl.ebnf. The transcribed EBNF is the pin; the published standard is the audit reference.

Implementation. scripts/v6-opl-syntax.sh invokes scripts/v6-opl-syntax.rb, a Ruby script that parses each opl.txt file under src/opm/ against the EBNF grammar at tools/iso-19450-opl.ebnf. The script uses the treetop Ruby gem (a PEG parser with explicit grammar-file support) loaded via the Gemfile; the parser is generic, the EBNF is the pinned authority. The script translates tools/iso-19450-opl.ebnf into a treetop grammar at load time (mechanical EBNF→PEG transcription, no rule rewriting); the grammar file is the pin, the translation is deterministic. Any parse failure — unexpected tokens, ambiguous productions, missing terminators — is reported with file path, line, column, and the failing grammar rule.

Pass condition. For every opl.txt file under any src/opm/<opd-name>/ subdirectory, the file parses against the EBNF without error.

Failure mode. Per-file: the parse error class, the line and column at which the parser rejected the input, and the EBNF rule that failed. Aggregated across files. Exits non-zero on any failure.

V7 — OPD/OPL bimodal coherence

Authority. ISO 19450:2015 OPD/OPL semantic-equivalence rule, transcribed at tools/iso-19450-opd-coherence.txt. The transcribed rule is the pin; the published standard is the audit reference. The rule, in summary: the OPD and OPL are semantically equivalent presentations of the same model. In the wiki, OPL is the canonical source for both modalities: every entity (object, process, state) the model defines is declared in opl.txt via the OPL productions specified in ISO 19450 Annex A. The companion opd.svg is a rendering of the OPD; V7 verifies that the rendering contains exactly the entities the OPL declares.

Implementation. scripts/v7-opd-opl-coherence.sh invokes scripts/v7-opd-opl-coherence.rb, a Ruby script that, for each src/opm/<opd-name>/ subdirectory:

  1. Parses opl.txt using the V6 EBNF parser (the V6 emitter tags every parse-tree node with the EBNF rule that produced it via a synthetic __rule__ method, so V7 can identify production-bearing nodes without re-parsing).
  2. Walks the parse tree per the production mappings in tools/iso-19450-opd-coherence.txt and collects entity names. The coherence file's format is one mapping per non-comment line: <entity-introducing-rule> : <name-bearing-rule> (both names are EBNF rule names from tools/iso-19450-opl.ebnf; hyphens are sanitized to underscores at load time). For each parse-tree node tagged with an entity-introducing rule, the implementation walks the subtree to find every descendant tagged with the corresponding name-bearing rule and collects its text_value (whitespace-trimmed).
  3. Parses opd.svg as XML. From the SVG's <text> elements that carry class="opm-entity" (multi-class membership accepted), extracts the text content of each. Edge-label text (relation phrases like "yields", "consists of") is deliberately untagged in tool-generated SVGs so it does not pollute the entity set; hand-authored SVGs MUST tag entity-name <text> elements with the opm-entity class for V7 to recognise them.
  4. The OPL entity set MUST equal the SVG <text> content set. The equality is exact (whitespace-trimmed); no fuzzy matching.
  5. Fails if the two sets are not equal.

Pass condition. For every per-OPD subdirectory under src/opm/, the set of entity names declared by opl.txt (per the production mappings in tools/iso-19450-opd-coherence.txt) equals the set of <text> content strings in opd.svg.

Failure mode. Per-OPD: the symmetric difference, naming entities present in OPL but not SVG, and <text> strings present in SVG but not declared by OPL. Exits non-zero on any failure.

V8 — ISO 15288 process structural superset

Authority. ISO/IEC/IEEE 15288:2023 Clause 6, transcribed at tools/iso-15288-processes.txt. The transcribed process catalog is the pin; the published standard is the audit reference. The catalog lists, per process group (Agreement, Organizational Project-Enabling, Technical Management, Technical), the names of every process the standard specifies.

Implementation. scripts/v8-iso-15288-superset.sh invokes scripts/v8-iso-15288-superset.rb, a Ruby script that uses the Asciidoctor parser to load each src/15288/*.adoc file, walks the AST to collect section headings, and confirms that for every process listed in tools/iso-15288-processes.txt, a section heading with the matching process name appears in the corresponding process-group .adoc file. The check is a structural superset (the wiki may add sub-sections beyond those the standard names; it must not omit any process the standard names).

Pass condition. For every process named in tools/iso-15288-processes.txt, a section heading with that name exists in the corresponding src/15288/<process-group>.adoc file.

Failure mode. Per-process: the missing process name and the file in which it was expected. Exits non-zero on any failure.

Validator dependency order

Validators run in strict order. Earlier failures stop later validators.

  Independent of all others       Architecture chain        OPM chain
  ---------------------------     ----------------------    -----------------
  V1 — arc42 structural           V3 — Structurizr DSL      V6 — OPL syntax
       alignment                       ↓                         ↓
                                  V2 — arc42 build          V7 — OPD/OPL
  V8 — ISO 15288 process               ↓                         bimodal
       structural superset        Stage 3 rendering              coherence
                                  (wiki-frame +
                                   15288 +
                                   OPM index)
                                       ↓
                                  V4 — CommonMark / GFM
                                       ↓
                                  V5 — GitHub-markup
                                       rendering

Each column is run-order-strict from top to bottom. Columns are independent of each other and may run in any order or in parallel.

V1 and V8 have no upstream dependencies (they read sources directly against pinned authorities) and no downstream consumers. V3 is the head of the architecture chain (V3 → V2 → V4 → V5, with Stage 3 rendering inserted between V2 and V4). V6 is the head of the OPM chain (V6 → V7). V3 must run before V2 because the AsciiDoc sources reference SVGs that V3 produces. V2 must run before V4 because V2 produces the chapter markdown V4 validates. Stage 3 rendering must run before V4 because V4 also validates the markdown those substages produce. V5 runs last because it validates the full set of .md files. V6 must run before V7 because V7 depends on V6's parser to extract entity names from OPL.

validate.sh runs all eight and aggregates results. A failure in any earlier validator skips remaining validators that depend on its output; the aggregated report notes which validators were skipped due to upstream failure. V1, V6, V8 have no upstream dependencies and run unconditionally (subject to Reconciliation gap handling for V6, V7, and V8 during the gap).

The build script

scripts/build.sh runs the full pipeline end-to-end and produces the artifacts that get committed:

Stage 1 — Pre-flight
  1a. Verify install-tools.sh has been run by checking each pinned tool's
      version against the value in tools/versions.txt. Mismatch exits
      non-zero with a message naming the tool and both versions.
  1b. Verify vendor/arc42-generator submodule is at its pinned commit.
  1c. Verify vendor/arc42-generator's own arc42-template submodule is
      initialized.
  1d. Verify transcribed-standard pin files exist and are non-empty
      (when their corresponding validator is enabled). During the
      reconciliation gap, individual pin files may be absent; in that
      case Stage 1d does not fail, and the corresponding validator
      reports skipped per **Reconciliation gap handling** below.
  1e. Verify Ruby gem dependencies are installed via `bundle check`.

Stage 2 — Validate
  2a. Run scripts/validate.sh; exit non-zero on any V1–V8 failure.

Stage 3 — Render wiki-frame fragments and OPM/15288/scientific pages
  3a. Build wiki-frame AsciiDoc files via pandoc.
  3b. Render the four ISO 15288 lifecycle chapters from src/15288/*.adoc
      to GFM markdown using pandoc. Skipped when src/15288/ is absent.
  3c. Render the OPM Conceptual Model index page via
      scripts/render-opm-index.sh. Skipped when src/opm/ is absent.
  3d. Render Scientific Methods and Results pages from
      src/scientific/*.adoc to GFM markdown via pandoc. Skipped when
      src/scientific/ is absent or empty.

Stage 4 — Stage to wiki root
  4a. Copy each chapter markdown file with the canonical wiki page name.
  4b. Copy the wiki-frame files to the wiki root.
  4c. Ensure the images/ directory exists; copy SVGs from
      src/arc42/images/ and per-OPD opd.svg files (with opm- prefix).
  4d. Rewrite image references in each staged wiki-root markdown file.
  4e. Copy the four 15288 lifecycle pages to the wiki root with
      canonical names (Lifecycle-Agreement-Processes.md etc.).
      Skipped when build/15288/ is absent.
  4f. Copy build/opm/Conceptual-Model.md to the wiki root as
      Conceptual-Model.md. Skipped when build/opm/ is absent.
  4g. Copy each build/scientific/<page>.md to the wiki root with the
      same filename (the source filename is already the wiki-URL slug).
      Skipped when build/scientific/ is absent.

Stage 5 — Idempotence check
  Re-run Stages 1 through 4 with build output redirected to a
  scratch directory; cmp(1) every staged file. Any diff exits
  non-zero, naming the divergent file.

Stage 5 makes the build deterministic-or-fail.

The validate script

scripts/validate.sh runs V1–V8 without producing committable artifacts.

Run V1, V3, V6, V8 (independent of each other; each reads its sources
                    against its pinned authority directly)
Run V7 (after V6; V7 reuses V6's parser to extract OPL entities)
Run V2 (after V3; consumes the SVGs V3 exports)
Run V4 (after V2; consumes V2's chapter markdown)
Run V5 (after V4; consumes the .md files at the wiki root)
Aggregate results into a single report:
  ✓ V1 — arc42 structural alignment
  ✓ V2 — arc42 build pipeline
  ✓ V3 — Structurizr DSL
  ✓ V4 — CommonMark / GFM
  ✓ V5 — GitHub-markup rendering
  - V6 — OPL syntax              (skipped: pin file or source absent)
  - V7 — OPD/OPL bimodal coherence (skipped: V6 skipped or source absent)
  - V8 — ISO 15288 process superset (skipped: pin file or source absent)
Exit non-zero if any V1–V8 failed. Skipped (gap-reason) does not fail.

The exit code is zero if and only if every validator either completed and reported success or was skipped for a reconciliation-gap reason (pin file absent or source directory absent or empty per Reconciliation gap handling). A validator skipped due to upstream-failure propagation (e.g., V4 skipped because V2 failed) does NOT permit exit code zero: the upstream failure itself causes exit non-zero.

Reconciliation gap discipline

All three coordinated standards are present in the wiki: arc42+C4 (the 12 arc42 chapters under src/arc42/ and the Structurizr workspace under src/c4/), OPM ISO 19450 (the per-OPD subdirectories under src/opm/ and the pinned EBNF + coherence rule under tools/), and ISO/IEC/IEEE 15288 (the four lifecycle chapters under src/15288/ and the pinned process catalog under tools/). V1–V8 all enforce.

The "reconciliation gap" discipline below is the safety property that governs the case where a pin file or its source directory becomes absent (e.g., during a pin-replacement transition). The discipline keeps the build green during such transitions; the maintainer restores the absent file before the transition's commit lands.

Discipline:

  • If tools/iso-19450-opl.ebnf is absent, V6 reports skip-gap with reason "pin file absent". Same for V7 (iso-19450-opd-coherence.txt) and V8 (iso-15288-processes.txt).
  • If a pin file exists but src/opm/ (resp. src/15288/) is absent or empty, V6/V7 (resp. V8) report skip-gap with reason "source directory absent or empty — no inputs to validate".
  • If a pin file exists AND its corresponding source directory has any content, the validator runs and enforces normally.
  • Stages 3b/3c skip when their source directories are absent or empty; Stages 4e/4f similarly skip when their stage-3 outputs are absent.

A pass and a skip-gap are both acceptable for validate.sh to exit zero. An skip-upstream (caused by an earlier validator's failure) is not.

Validation property

After scripts/build.sh runs successfully on a clean src/, the following properties hold:

  1. Every .md file at the wiki repo's root parses as valid CommonMark / GFM (V4).
  2. Every .md file at the wiki repo's root renders to non-empty HTML without raising via github-markup (V5).
  3. The src/arc42/adoc/ chapter structure is a structural superset of the upstream chapter manifest (V1).
  4. The src/c4/workspace.dsl file parses as a valid Structurizr workspace (V3, validate phase).
  5. Every C4 view defined in the workspace has a corresponding SVG file, and every image::{key}.svg[] reference resolves (V3).
  6. A second clean run of scripts/build.sh produces byte-identical output (Stage 5 idempotence check).
  7. The wiki repo's root contains exactly the desired-state file set (12 arc42 chapters, Conceptual-Model.md, four Lifecycle-*.md pages, the academic-partition pages rendered from src/scientific/*.adoc, three wiki-frame files, images/ directory, infrastructure files). If a transcribed-standard pin file or its corresponding source directory is transiently absent under the reconciliation gap discipline, the dependent root files (Conceptual-Model.md, Lifecycle-*.md) are absent and that absence is conformant. The academic partition follows the same gap discipline: when src/scientific/ is absent or empty, no academic-partition pages are staged and that absence is conformant.
  8. Every opl.txt file under src/opm/<opd-name>/ parses against the pinned EBNF (V6).
  9. For every src/opm/<opd-name>/ subdirectory, the entity name set extracted from opl.txt equals the entity name set extracted from opd.svg (V7).
  10. Every process named in tools/iso-15288-processes.txt appears as a section heading in the corresponding src/15288/<process-group>.adoc file (V8).

Properties 8, 9, 10 hold vacuously during a reconciliation gap (no inputs means no violations); they are enforced over non-empty inputs in the normal case.

These ten properties are the wiki's correctness contract.

Clone this wiki locally