Repository navigation
wiki definition
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.
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.
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.
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 testrunning the doctest examples in rustdoc comments and by the workspace's unit and integration tests. - Mathematical claims are verified by
lake buildrunning 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.
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:
- Creating the source directory under
src/<partition-key>/. - Adding a
scripts/render-<partition-key>.shthat mirrors therender-15288.shpandoc-pipeline pattern and follows reconciliation gap discipline (skip cleanly when the source dir is absent or empty). - Wiring the render script into
build.sh(Stage 3) andvalidate.sh(so V4/V5 see the rendered pages). - 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. - Updating
src/wiki/Sidebar.adocto surface the partition. - 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.
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:
-
Local build idempotence —
scripts/build.shStage 5 fails if a second build produces output differing from the first, catching non-determinism at the contributor's machine before any push. -
Post-push detection script —
scripts/check-wiki-state.sh, runnable by any wiki maintainer, clones the wiki repo into a scratch directory and runsscripts/build.shStage 4 only (re-staging from the committed source). It then compares every staged file against the wiki root usingcmp(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. -
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 inREADME.mdand 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.
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.
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.
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:
- Confirms the local file
src/arc42/adoc/NN_chapter_name.adocexists with the canonical filename matching the upstreamvendor/arc42-generator/arc42-template/EN/asciidoc/src/NN_chapter_name.adoc. - Parses both files and compares heading levels 1 and 2 only (deeper levels are workspace-authored detail and are not bound to upstream).
- Asserts the local file's H1 heading text is identical (byte-equal, after trimming surrounding whitespace) to the upstream chapter's H1.
- 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.
(Authority, implementation, and pass/fail conditions unchanged from
the bc7bf4d-pinned implementation. See scripts/v2-arc42-build.sh.)
(Authority, implementation, and pass/fail conditions unchanged from
the bc7bf4d-pinned implementation. See scripts/v3-structurizr.sh.)
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.)
(Unchanged from the bc7bf4d-pinned implementation.)
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.
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:
- Parses
opl.txtusing 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). - Walks the parse tree per the production mappings in
tools/iso-19450-opd-coherence.txtand 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 fromtools/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 itstext_value(whitespace-trimmed). - Parses
opd.svgas XML. From the SVG's<text>elements that carryclass="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 theopm-entityclass for V7 to recognise them. - The OPL entity set MUST equal the SVG
<text>content set. The equality is exact (whitespace-trimmed); no fuzzy matching. - 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.
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.
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).
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.
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.
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.ebnfis 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.
After scripts/build.sh runs successfully on a clean src/, the following
properties hold:
- Every
.mdfile at the wiki repo's root parses as valid CommonMark / GFM (V4). - Every
.mdfile at the wiki repo's root renders to non-empty HTML without raising viagithub-markup(V5). - The
src/arc42/adoc/chapter structure is a structural superset of the upstream chapter manifest (V1). - The
src/c4/workspace.dslfile parses as a valid Structurizr workspace (V3, validate phase). - Every C4 view defined in the workspace has a corresponding SVG file,
and every
image::{key}.svg[]reference resolves (V3). - A second clean run of
scripts/build.shproduces byte-identical output (Stage 5 idempotence check). - The wiki repo's root contains exactly the desired-state file set
(12 arc42 chapters,
Conceptual-Model.md, fourLifecycle-*.mdpages, the academic-partition pages rendered fromsrc/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: whensrc/scientific/is absent or empty, no academic-partition pages are staged and that absence is conformant. - Every
opl.txtfile undersrc/opm/<opd-name>/parses against the pinned EBNF (V6). - For every
src/opm/<opd-name>/subdirectory, the entity name set extracted fromopl.txtequals the entity name set extracted fromopd.svg(V7). - Every process named in
tools/iso-15288-processes.txtappears as a section heading in the correspondingsrc/15288/<process-group>.adocfile (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.
Generated from sources at UOR-Framework.wiki. Do not edit pages directly via the GitHub web UI — edits are overwritten by the next build. See README for the authoring workflow.