# 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 `` 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//`. 2. Adding a `scripts/render-.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. │ │ └── / # 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//` 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//` 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: ` : ` (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 `` 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 `` elements with the `opm-entity` class for V7 to recognise them. 4. The OPL entity set MUST equal the SVG `` 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 `` content strings in `opd.svg`. **Failure mode.** Per-OPD: the symmetric difference, naming entities present in OPL but not SVG, and `` 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/.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/.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//` parses against the pinned EBNF (V6). 9. For every `src/opm//` 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/.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.