ADR-030 + ADR-031 + Scientific Methods and Results partition (issue #7)
ADR-030 — `axis!` SDK macro: universal substrate-extension declaration
mechanism. Generalizes Hasher to one axis among many; introduces
AxisExtension, AxisTuple, MAX_AXIS_TUPLE_ARITY, AXIS_OUTPUT_BYTES_CEILING.
Term::HasherProjection becomes Term::AxisInvocation (Term enum stays at
ten variants). Catamorphism's per-variant fold-rule dispatches through
A::dispatch(axis_index, kernel_id, &evaluated_inputs).
ADR-031 — `prism` is the standard library: a façade over `uor-foundation`
plus standard-library Layer-3 sub-crates (prism-numerics, prism-crypto,
prism-tensor, prism-fhe) published from the Prism repository. Inclusion
criteria, layered consumption pattern, content-addressing invariance,
conformance vetting. Repository allocation made explicit: architecture in
UOR-Framework, standard library in Prism. Drops prior "blessed" framing.
Cross-references: ADR-007 third-position generalization to A: AxisTuple;
ADR-013 Consequences extension; ADR-024 axis-declaration mechanism alongside
verb-declaration; ADR-026 G19 generalization to axis-trait method calls;
ADR-029 fold-rule + Substitution-axis-realized verbs paragraph rewritten
for AxisTuple. Section 4 strategic decision row + composition paragraph;
Section 8 Closure Across Layers paragraph. Glossary: 11 new/updated entries
(axis!, AxisExtension, AxisTuple, AXIS_ADDRESS, AXIS_OUTPUT_BYTES_CEILING,
MAX_AXIS_TUPLE_ARITY, Standard-library Layer-3 sub-crate, prism-numerics,
prism-crypto, prism-tensor, prism-fhe, Term::AxisInvocation rename).
Scientific Methods and Results — new non-normative academic-documentation
partition (Director of Research stream per issue #7). Adds
src/scientific/Scientific-Methods-and-Results.adoc with the landing-page
content; scripts/render-scientific.sh (Stage 3d, mirrors render-15288.sh
with reconciliation-gap discipline); Stage 3d wiring in build.sh + Stage 4g
in stage-to-wiki-root.sh + render_scientific in validate.sh; sidebar entry
in src/wiki/Sidebar.adoc; partition specification in wiki-definition.md
(Non-normative content partitions section, source-tree, build-stages,
correctness-contract Property 7); SOP in README.md (Robin issues -> wiki
maintainer authors AsciiDoc -> build.sh -> commit).
Pin refresh: tools/versions.txt java line refreshed from openjdk 21.0.11
to openjdk 21.0.10 (the JDK 21.x actually installed on the build host).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Cleanup: drop \"Phase 4 not yet landed\" framing, tighten OPL fenced blocks
Phase 4 reconciliation landed in 368326f. The wiki state now matches
its defined state: V1–V8 all enforce, no skip-gaps remain in the
normal build. The references to Phase 4 as a pending future event are
stale.
This commit reframes the prose without altering the underlying
discipline. The reconciliation gap discipline itself stays — it is the
safety property that keeps the build green during pin-replacement
transitions where a pin file or its source dir is transiently absent.
What changes is the framing: Phase 4 is no longer described as
\"upcoming\" or \"not yet landed.\"
Changes:
- wiki-definition.md: \"Bootstrapping order\" / \"Phase 4 — V6/V7/V8
reconciliation\" sections replaced with \"Reconciliation gap
discipline,\" preserving the discipline rules. Property 7 reworded
to make the discipline (rather than Phase 4 specifically) the
conditional that admits absence.
- README.md: dropped \"Absent during Phase 4 reconciliation\" notes
from the three pin-file authorities, the OPM and 15288 source dirs,
and the wiki-root .md/images entries. Added rows for
src/opm/opd-order.txt and tools/opl-to-svg.rb.
- scripts/v6-opl-syntax.sh, v7-opd-opl-coherence.sh,
v8-iso-15288-superset.sh: skip-gap reason strings now read
\"pin file absent: <path>\" rather than referencing Phase 4.
- scripts/render-opm-index.sh: dropped the leading \\n from the
fence-close printf so the closing ``` sits directly after the
last OPL line, not after a blank line.
Conceptual-Model.md regenerated with the tightened fenced blocks.
12 C4 SVGs re-rendered (Structurizr exporter timestamp churn).
Verification: ./scripts/build.sh complete (V1–V8 PASS, Stage 5
idempotence holds). ./tests/run-all.sh PASS (55 tests).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Complete V6 EBNF→PEG translator and V7 OPL entity extractor
Removes the two NotImplementedError stubs that gated Phase 4 source
content. The wiki infrastructure is now complete: every committed
.rb/.sh script in scripts/ runs end-to-end, and the only remaining
Phase 4 work is authoring transcribed-standard pin files and OPM/15288
source content.
V6 (scripts/lib/ebnf_to_treetop.rb):
- Mechanical ISO/IEC 14977 EBNF → treetop PEG translator. Lexer,
recursive-descent parser, and treetop emitter. Handles:
lhs = rhs ; → rule lhs<sanitized>; rhs ; end
a , b → a b (juxtaposition)
a | b → a / b (PEG ordered choice)
[ a ] / { a } / ( a ) (postfix ?, *, parens)
a - b → (!b a) (PEG negative lookahead, warn)
"..." / '...' (passthrough)
(* comment *) (stripped at lex)
identifier with hyphens (sanitised to underscores)
? special ? (raises — author rewrites)
- Every emitted rule wraps its body in __body__:(...) labeling so
treetop preserves the rule's syntax-node identity (without it,
treetop inlines a rule whose body is a single nonterminal reference,
losing the outer rule's __rule__ tag).
- Every emitted rule defines def __rule__; '<rulename>'; end via an
inline extension block, so V7 can identify which production produced
any node by walking the parse tree.
V7 (scripts/lib/opl_entity_extractor.rb):
- parse_coherence: reads tools/iso-19450-opd-coherence.txt as a list
of "<entity-introducing-rule> : <name-bearing-rule>" mappings. Both
rule names sanitized (hyphens → underscores). Comments and blank
lines ignored.
- entity_names: walks the V6 parse tree, finds nodes whose __rule__
matches an entity-introducing rule, and within each finds every
descendant whose __rule__ matches the corresponding name-bearing
rule. Collects text_value (whitespace-trimmed) into a Set.
Tests (tests/):
- test-v6-translator.rb: 44 unit tests over the lexer, parser, and
emitter (constructs from the translation table; hyphenated identifier
handling; precedence preservation; end-to-end load + parse with three
synthetic mini-grammars).
- test-v7-extractor.rb: 11 tests over coherence-file parsing, entity
extraction (object/process/state declarations, dedup, nested
structures), and a full subprocess invocation of v7-opd-opl-coherence.rb
against a synthetic fixture set with both coherent and drifted OPDs.
- run-all.sh: simple test runner. Both test files exit 0.
Other changes:
- scripts/v6-opl-syntax.rb: slim wrapper that requires the library and
invokes the translator + parser. Same CLI as before.
- scripts/v7-opd-opl-coherence.rb: rewritten to load V6's parser via
the shared library, parse the coherence pin via the extractor, and
cross-reference against opd.svg <text> elements.
- Gemfile: added rexml ~> 3.2 (Ruby 3.4 removed it from defaults; V7
needs it to parse opd.svg).
- wiki-definition.md V7 section: clarified the coherence file's mapping
format and the parse-tree walking algorithm. Phase 4 reduced to three
remaining steps (pin files + OPM sources + 15288 sources); the
validator implementations and pipeline integration are now complete.
- README.md: added scripts/lib/ and tests/ to the "What lives where"
table.
Verification: ./tests/run-all.sh PASS. ./scripts/build.sh PASS (V1–V5
PASS, V6/V7/V8 SKIP-GAP, Stage 5 idempotence holds). End-to-end smoke
test of v6-opl-syntax.rb and v7-opd-opl-coherence.rb against synthetic
pin files confirms both report PASS on coherent inputs and FAIL with
symmetric difference on drifted inputs.
C4 SVGs re-rendered (Structurizr exporter timestamps differ across
build runs; the 12 affected files are byte-different from 738d368).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Audit cleanup: factor render-15288, refresh check-wiki-state and README
Three real issues surfaced by audit of a3927ef:
1. scripts/check-wiki-state.sh only re-ran render-wiki-frame +
stage-to-wiki-root. Missed Stage 3b (15288) and 3c (OPM). Once
Phase 4 source content lands, the post-push detector would have
produced false DRIFT alerts for Lifecycle-*.md and Conceptual-Model.md.
Now invokes render-15288.sh and render-opm-index.sh as well.
2. README.md said "Runs V1–V5" and "wiki-definition.md is in the parent
UOR-Framework repository" — both stale after the V6/V7/V8 + spec-
relocation work. Updated to reflect:
- V1–V8 with reconciliation-gap discipline
- wiki-definition.md is at this repo's root
- OPM (src/opm/) and ISO 15288 (src/15288/) source paths
- Three transcribed-standard pin authorities (tools/iso-*)
- Phase-4-content-absent line for the "What lives where" table
3. Stage 3b was inline in build.sh and duplicated as the render_15288
function in validate.sh. Factored into scripts/render-15288.sh; both
build.sh and validate.sh now delegate. check-wiki-state.sh also uses
it. Skip-on-empty discipline preserved.
Other audit findings:
- wiki-definition.md is a faithfully-condensed version of the user's
source text (V2/V3/V5 sections refer to the bc7bf4d-pinned scripts
rather than carrying verbatim text). Acceptable as in-repo spec; the
committed scripts ARE the canonical behavior.
- Sidebar.adoc lists 13 entries (Home + 12 chapters). Conceptual-Model
and Lifecycle-* pages are deliberately not listed yet — adding them
now would create broken links until Phase 4 source content lands.
- Empty src/opm/ and src/15288/ directories not created. The
reconciliation gap discipline allows source dirs to be absent.
- C4 SVGs re-renderered (Structurizr exporter is non-deterministic
across runs; the 12 affected files are byte-different from those in
a3927ef).
V1–V5 PASS, V6/V7/V8 SKIP-GAP. Build green. Stage 5 idempotence holds.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pin pandoc, install Playwright deps, document arc42-template-pin.txt
Closes the three pre-Phase-3 fit/trim items.
1. Pin pandoc 3.9.0.2 with SHA-256 in tools/checksums.txt; install-tools.sh
downloads pandoc.deb and extracts it via dpkg-deb to tools/pandoc-prefix/
(no sudo, no system pollution). render-wiki-frame.sh now uses
tools/bin/pandoc, not whatever is on $PATH — pandoc minor-version
differences could otherwise shift the docbook→GFM output and break
cross-developer build.sh idempotence. build.sh Stage 1 verifies the
reported pandoc version against tools/versions.txt.
2. Install Playwright system libraries via `npx playwright install-deps
chromium` in install-tools.sh and the devcontainer postCreateCommand.
structurizr.war's SVG exporter launches headless Chromium that needs
~30 system libs; the canonical list shifts with Chromium versions, so
delegating to Playwright's own installer beats hand-maintaining apt
package names. Without this, V3 SVG export would have died on the
first real view added in Phase 3 with libgbm.so.1 errors.
3. README's "Pin updates" section now explicitly enumerates all five pin
authorities, including tools/arc42-template-pin.txt. The pin update
procedure tells maintainers to reconsider the template pin whenever
they bump arc42-generator (newer generator may want different layout).
V3 incidentally refactored: stop parsing the DSL for view keys (fragile
across DSL idioms — `key` is positional, not a property) and instead
derive view keys from exported SVG filenames, which the parser produces
authoritatively.
Manually verified V3 export with a temporary L1 SystemContext view —
2 SVGs produced (the view + auto-generated -key.svg legend), workspace
reverted to empty before commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 0 + Phase 1 + Phase 2 bootstrap
Adds the full validation, build, and authoring infrastructure defined in
the parent UOR-Framework repo's wiki-definition.md, plus skeleton chapter
sources and the first end-to-end-passing rendered output.
Phase 0 (tooling):
- 12 scripts under scripts/ (V1..V5 validators, install-tools, validate,
build, render-wiki-frame, stage-to-wiki-root, check-wiki-state)
- vendor/arc42-generator submodule pinned at 46bd7ce (Feb 2026)
- arc42-template pinned at b29e08 via tools/arc42-template-pin.txt
(overrides the generator's own stale submodule pin)
- structurizr.war v2026.04.19 (Playwright variant) pinned in
tools/checksums.txt by SHA-256
- cmark-gfm 0.29.0.gfm.13, built from source by install-tools.sh
- Gemfile pins asciidoctor ~> 2.0, github-markup ~> 5.0,
commonmarker ~> 0.23 (5.0.x github-markup needs the 0.x API)
- tools/versions.txt as build.sh Stage 1's pin authority
Phase 1 (skeleton sources):
- src/arc42/adoc/NN_*.adoc — 12 chapter skeletons matching upstream H1+H2
- src/arc42/arc42-template.adoc — top-level include for direct asciidoctor
- src/arc42/version.properties
- src/c4/workspace.dsl — empty workspace (V3 PASS / 0 views)
- src/wiki/{Home,Sidebar,Footer}.adoc
Phase 2 (rendered artifacts at the wiki root):
- 12 chapter files NN-Title-Case-Name.md
- Home.md, _Sidebar.md, _Footer.md
- images/ (placeholder .gitkeep until the C4 model gains views)
Validators:
- V1 — structural alignment with upstream arc42-template
- V2 — drives the arc42-generator Docker pipeline (gitHubMarkdownMP /
plain), bypassing build-arc42.sh's destructive submodule reset
- V3 — Structurizr DSL validate + SVG export (skips export when no views,
avoiding Playwright Chromium dependency on empty workspaces)
- V4 — cmark-gfm with GitHub's wiki extension set
- V5 — github-markup gem to catch markup-stage rendering failures
build.sh runs the five-stage pipeline (pre-flight pin check, validate,
render wiki-frame, stage to wiki root, idempotence check via cmp).
Spec deviations (vs wiki-definition.md):
- Chapter 3 filename is 03_context_and_scope.adoc (upstream-actual),
not 03_system_scope_and_context.adoc; rendered as 03-Context-and-Scope.md
- arc42-template pinned at our level (separate file) rather than relying
on the generator's transitive pin, because arc42-generator's
Templates.groovy expects a layout newer than its own pinned submodule
- v2-arc42-build.sh invokes `groovy build.groovy` directly, skipping the
generator's build-arc42.sh wrapper (which wipes our staged edits and
fails inside our nested-submodule git layout)
- V2's chosen output format is gitHubMarkdownMP (Multi-Page GFM) for
per-chapter files, not the spec's unspecified default
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>