README

UOR-Framework wiki — authoring workflow

This repository is the source for https://github.com/UOR-Foundation/UOR-Framework/wiki. The committed .md files at the wiki root are GitHub-rendered output, not hand-edited content. The wiki is authored under three coordinated standards: arc42 + C4 (architecture, in src/arc42/ and src/c4/), OPM ISO 19450 (conceptual model, in src/opm/), and ISO/IEC/IEEE 15288 (system lifecycle, in src/15288/).

The full structural specification is wiki-definition.md at this repository's root. This README covers the day-to-day workflow.

One-time setup

git clone --recurse-submodules https://github.com/UOR-Foundation/UOR-Framework.wiki.git
cd UOR-Framework.wiki
./scripts/install-tools.sh

install-tools.sh downloads tools/structurizr.war and tools/pandoc.deb (both verified against tools/checksums.txt), extracts pandoc to tools/pandoc-prefix/ and symlinks it at tools/bin/pandoc, builds tools/bin/cmark-gfm from source at the pinned tag, checks out arc42-template at the SHA in tools/arc42-template-pin.txt, runs bundle install into vendor/bundle/, installs Playwright system libraries via apt-get so V3's SVG export can launch headless Chromium, verifies host tool versions match tools/versions.txt, and re-writes tools/versions.txt from observed values. The script needs sudo for the apt step only.

Editing

Standard	Sources
arc42	src/arc42/adoc/NN_*.adoc (12 chapters); src/arc42/arc42-template.adoc (umbrella include)
C4	src/c4/workspace.dsl (single Structurizr workspace)
OPM (ISO 19450)	src/opm/<opd-name>/opl.txt + opd.svg per OPD; src/opm/opd-order.txt lists OPDs in presentation order
ISO/IEC/IEEE 15288	src/15288/{agreement,organizational-project-enabling,technical-management,technical}.adoc
Wiki frame	src/wiki/{Home,Sidebar,Footer}.adoc
Scientific Methods and Results (academic partition, non-normative)	src/scientific/<Wiki-URL-Slug>.adoc per page

Validate (fast feedback, no committable output)

./scripts/validate.sh

Runs V1–V8 in dependency order and prints an aggregated report. V1–V5 cover arc42+C4 architecture; V6/V7 cover OPM (ISO 19450); V8 covers ISO 15288 process structural superset. See wiki-definition.md for what each validator enforces.

V6/V7/V8 follow reconciliation gap discipline: when their pin file (tools/iso-19450-opl.ebnf, tools/iso-19450-opd-coherence.txt, tools/iso-15288-processes.txt) or source directory (src/opm/, src/15288/) is absent, they report skip-gap rather than failing. The build remains green throughout the gap. A pass and a skip-gap are both acceptable for exit-zero; an upstream-failure-skip (skip-upstream) is not.

Build (validate + render + stage to wiki root)

./scripts/build.sh

Runs Stage 1 (pre-flight pin verification, including bundle check and transcribed-pin presence), Stage 2 (validate), Stage 3 (render wiki-frame, ISO 15288 lifecycle pages, and OPM Conceptual Model index), Stage 4 (stage to wiki root with chapter rename + image-path rewrite + lifecycle page rename + Conceptual-Model copy), and Stage 5 (idempotence check — re-runs Stage 4 to a scratch dir and cmps every output, failing on any byte-level divergence).

Commit and push

git status                                 # confirm src/ AND rendered .md files changed
git add src/ images/ Home.md _Sidebar.md _Footer.md \
        [0-9][0-9]-*.md
git commit -m "..."
git push

The commit MUST include the source change AND the corresponding rendered output AND any SVG that V3 produced.

Detect drift between source and committed output

./scripts/check-wiki-state.sh

Clones the live wiki repo, re-runs Stage 4 against the committed sources, and cmps each staged file against the wiki root. Detects commits where source and rendered output drifted (e.g., a contributor edited src/... but forgot to re-run build.sh before pushing). Repair: clone, run ./scripts/build.sh, commit the regenerated output, push.

Pin updates

Each external tool is pinned. The pin authorities:

Pin	Authority
arc42-generator	submodule SHA recorded by git add vendor/arc42-generator
arc42-template	tools/arc42-template-pin.txt (overrides the generator's transitive pin)
structurizr.war	version literal + SHA-256 in scripts/install-tools.sh and tools/checksums.txt
pandoc.deb	version literal + SHA-256 in scripts/install-tools.sh and tools/checksums.txt
cmark-gfm	git tag literal in scripts/install-tools.sh
Ruby gems	Gemfile.lock
ISO 19450 OPL EBNF	tools/iso-19450-opl.ebnf (workspace-authored transcription of Annex A)
ISO 19450 OPD/OPL coherence rule	tools/iso-19450-opd-coherence.txt (workspace-authored transcription)
ISO 15288 process catalog	tools/iso-15288-processes.txt (workspace-authored transcription of Clause 6)

General update procedure (any tool pin):

1. Edit the pin literal in scripts/install-tools.sh (and tools/checksums.txt for structurizr.war / pandoc.deb, or tools/arc42-template-pin.txt for the template).
2. Run ./scripts/install-tools.sh to download/build at the new pin and rewrite tools/versions.txt.
3. Run ./scripts/build.sh to confirm the new pin produces equivalent output.
4. Commit the pin literal change, the new tools/versions.txt, and any rendered output churn in a single commit.

For the arc42-generator submodule specifically, also cd vendor/arc42-generator && git checkout <new-sha> then cd .. && git add vendor/arc42-generator before running install-tools.sh. Reconsider tools/arc42-template-pin.txt at the same time — a newer generator may expect a different template layout.

Transcribed-standard pins (tools/iso-*.{ebnf,txt}) are workspace-authored; updates are direct edits to the file followed by re-reading against the published standard. The commit message MUST name the standard's clause/annex and the publication year of the transcription source.

Authoring the Scientific Methods and Results partition

The wiki hosts a non-normative academic-documentation partition called Scientific Methods and Results (per wiki-definition.md's Non-normative content partitions section). The Director of Research and the Academic Documentation Working Group own its content; the wiki maintainer owns the authoring mechanics.

Standing operating procedure:

1. Author submits an issue. The Director of Research (or another working-group member) opens an issue at https://github.com/UOR-Foundation/UOR-Framework/issues describing the page to add or the change to make. Content can be in the issue body or attached.
2. Maintainer authors AsciiDoc. A wiki maintainer creates or edits the corresponding source file under src/scientific/. The source filename is the wiki-URL slug verbatim (e.g., Scientific-Methods-and-Results.adoc becomes Scientific-Methods-and-Results.md at the wiki root, accessible at https://github.com/UOR-Foundation/UOR-Framework/wiki/Scientific-Methods-and-Results). The first heading in each file should match the page title (use the [[section-<slug>]] anchor + == Title pattern modeled by the arc42 chapters and the existing landing page).
3. Maintainer runs the build. ./scripts/build.sh renders the AsciiDoc to GFM markdown via the pandoc pipeline (Stage 3d) and stages each src/scientific/<page>.adoc to <page>.md at the wiki root (Stage 4g). All eight validators (V1–V8) and the Stage 5 idempotence check apply unchanged; V4/V5 cover the well-formedness of the new pages.
4. Maintainer commits and pushes. A single commit includes the src/scientific/... source change, the regenerated <page>.md at the wiki root, and the regenerated _Sidebar.md if the sidebar changed. The push lands at the wiki repo's master.
5. Maintainer closes the issue, referencing the commit.

Working-group members may also propose edits via the GitHub web UI's Suggested change mechanism on the source file; the maintainer applies the suggestion the same way (edit src/..., run build.sh, commit). Direct edits via the GitHub wiki web UI are still forbidden — the standing rule against hand-editing rendered .md at the wiki root applies to academic-partition pages too.

The partition's structure (number of pages, their sidebar grouping, their inter-page links) is operational policy of the working group; the partition's existence is a wiki commitment recorded in wiki-definition.md.

What lives where

Path	Role
wiki-definition.md	The normative specification of wiki structure, validators, build pipeline, pin authorities, and reconciliation discipline
src/arc42/adoc/NN_*.adoc	Per-chapter AsciiDoc sources (arc42)
src/arc42/arc42-template.adoc	Top-level include (for direct asciidoctor use)
src/arc42/version.properties	Spec revision metadata
src/arc42/images/*.svg	Output of V3 (Structurizr → SVG); gitignored
src/c4/workspace.dsl	Single canonical Structurizr workspace
src/opm/<opd>/	Per-OPD: opl.txt (canonical OPL) + opd.svg (rendering); V7 verifies they agree
src/opm/opd-order.txt	Manifest listing OPDs in presentation order
src/15288/{group}.adoc	Per-process-group lifecycle chapters (Agreement / Organizational Project-Enabling / Technical Management / Technical)
src/scientific/<slug>.adoc	Scientific Methods and Results partition (non-normative academic documentation, per the SOP above). One AsciiDoc file per wiki page; filename = wiki-URL slug.
src/wiki/{Home,Sidebar,Footer}.adoc	Wiki-frame fragments
vendor/arc42-generator/	Pinned submodule. V1 reads upstream chapter manifest from vendor/arc42-generator/arc42-template/EN/adoc/. arc42-template's SHA is overridden by tools/arc42-template-pin.txt, not by the generator's recorded pin.
tools/arc42-template-pin.txt	SHA we want arc42-template checked out at; enforced by install-tools.sh after submodule init
tools/checksums.txt	SHA-256 pins for downloaded binaries (structurizr.war, pandoc.deb)
tools/versions.txt	Resolved version strings; written by install-tools.sh, read by build.sh Stage 1
tools/iso-*.{ebnf,txt}	Transcribed-standard pin files (V6/V7/V8 authority)
tools/opl-to-svg.rb	One-time bootstrap helper that generates an OPM-style SVG from an OPL file. NOT a build step — opd.svg is a source artifact that V7 polices
scripts/	All build, validate, and helper scripts (V1–V8 implementations + render-* + stage-to-wiki-root + check-wiki-state)
scripts/lib/	Shared Ruby library code: ebnf_to_treetop.rb (V6's mechanical EBNF→PEG translator) and opl_entity_extractor.rb (V7's parse-tree walker)
tests/	Unit tests for the library code, run via ./tests/run-all.sh. Exercise V6/V7 against synthetic mini-grammars; no dependency on the transcribed-standard pin files
Gemfile, Gemfile.lock	Ruby gem pins (Asciidoctor for V1/V8, github-markup + commonmarker for V5, treetop + rexml for V6/V7)
*.md at the root	GitHub-rendered output (committed). 12 arc42 chapters, 3 wiki-frame files, Conceptual-Model.md, 4 Lifecycle-*.md pages
images/ at the root	SVGs referenced by rendered chapters (committed). 12 C4 SVGs + 6 per-OPD opm-*.svg

What NOT to do

• Do not edit *.md at the wiki root by hand. They are regenerated by build.sh. Edit src/... instead.
• Do not edit pages via the GitHub web UI. Web-UI edits are overwritten by the next push from a build.sh run.
• Do not skip the build. A commit that updates src/... without updating the corresponding rendered file is detected by scripts/check-wiki-state.sh.
• Do not pin an arc42-template submodule directly in this repo's .gitmodules. The active pin lives in tools/arc42-template-pin.txt and is applied by install-tools.sh after submodule init. The arc42-generator submodule has its own recorded pin for arc42-template, but that pin is too old for the generator's current Templates.groovy layout expectations — we deliberately override it.