Build and publish OKF bundles consistently

Status: estate standard under implementation, 18 August 2026.

This methodology governs how an OKF repository turns reviewed source material into generated bundle projections, documentation and a public release. It is a lifecycle contract. It does not change OKF 0.2 or the semantic meaning of the Bundle Wiki YAML-LD profile.

The two contracts

Every governed OKF producer keeps two concerns separate:

The repository's own reviewed commands remain authoritative. A shared checker may validate or schedule them, but must not silently replace them with commands copied from Explorer or another producer.

Start with a publication-impact plan

Before editing publication-affecting material, record:

1. the authored source and source family;
2. the generated projections that depend on it;
3. the human documentation and CHANGELOG.md entry;
4. affected unit, conformance, browser and release checks;
5. the deployment target and immutable candidate identity; and
6. the exact post-deployment journey.

This plan is updated when investigation discovers another dependency. CI uses the same dependency graph to select checks. The plan is not permission to skip a required release gate: it is evidence for why a plane is affected or safely unaffected.

Standard publication planes

A change may invalidate more than one plane. Hash-bound SBOMs, manifests and receipts are regenerated whenever their bound bytes change, even if application tests still pass.

Documentation and changelog lockstep

When controlled source, generators, tests, workflows or publication contracts change, the same pull request must include:

• documentation explaining any user, operator or assurance effect; and
• a concise CHANGELOG.md entry describing the material change and validation or publication boundary.

The publication contract lists controlled paths and recognised documentation paths. CI checks the whole pull-request diff. Automated dependency changes do not receive a blanket exception when they can change generated or release-bound bytes.

Update documentation and the changelog while planning the change. The CI check is the final backstop, not the first reminder.

Dependency-routed validation

Run independent affected planes in parallel. A failure in one repository or plane blocks only its dependants; it must not stop unrelated repository audits, documentation work or tests.

Use these rules:

• fail closed when a changed path has no mapping;
• keep an explicit default for manual runs;
• build each deterministic artefact once, upload it and reuse its exact bytes;
• use content-addressed caches only for components whose inputs are completely declared;
• record job and expensive-step timings so the routing policy can be reviewed;
• bound network-dependent installation and acquisition steps; and
• never refresh mutable upstream data inside a candidate build unless that acquisition is the reviewed purpose of the run.

Browser policy

Ordinary Chromium acceptance uses a compatible browser already installed on the governed runner where possible. Do not run playwright install --with-deps chromium merely to obtain a browser that the runner already supplies.

Firefox, WebKit or a downloaded browser remain appropriate when a change affects cross-engine behaviour or a release gate explicitly requires them. Their installation must have a bounded timeout and should run only on the affected assurance path. A targeted installed-Chrome path does not replace the full matrix when the full matrix is genuinely required.

Source-family intake

Every input belongs to a declared source family. The contract records its paths, formats, authority, snapshot/inventory method, rights, sensitivity boundary, extraction constraints and the planes it can invalidate.

Folders of spreadsheets

A folder of Excel or OpenDocument workbooks is not one opaque source and is not semantic authority merely because cells can be read. Before building:

1. inventory every file with relative path, bytes and SHA-256;
2. record workbook format and whether macros are present;
3. inventory visible, hidden and very-hidden sheets where the format supports them;
4. preserve raw values separately from displayed values and formulas;
5. identify named ranges, tables, merged cells, comments, external links, connections and embedded objects;
6. define header, blank-row, multi-table and repeated-sheet rules;
7. detect formula errors and stale cached results without executing macros;
8. record date system, locale and number-format assumptions;
9. assess personal, sensitive, licensed and access-controlled content; and
10. create stable source-row or source-cell evidence identities before semantic normalisation.

Macro execution, external refresh and formula recalculation are separate, explicitly authorised acquisition operations. A safe default preserves the original workbook, does not execute active content and reports unsupported or ambiguous structures instead of guessing.

CSV companions are distinct representations. They do not preserve formulas, sheet visibility, types or workbook structure, so a CSV export must not silently replace its workbook as the evidence source.

Candidate, merge and deployment

1. Build and validate one immutable candidate.
2. Record exact generated identities and assurance receipts.
3. Merge through the repository's protected workflow.
4. Confirm that deployment uses the merged commit and expected candidate bytes.
5. Open the exact public URL in a real browser.
6. Check page identity, the intended navigation journey and browser console.
7. Only then publish or recommend the URL.

A failed URL check is not permission to trigger an unrelated release rebuild. Use the dependency graph to identify the smallest correction and repeat only the affected planes and their required downstream gates.

Estate registry

Explorer publishes two related registries:

• the semantic bundle registry lists public bundle descriptors, versions, profiles and routes; and
• the estate registry lists governed repositories, source families, declared tooling, lockstep status, CI/browser policy, publication mode and verification state.

The estate registry is generated from reviewed repository presets and bounded governance metadata. It is an operational discovery aid, not proof that every repository is currently conformant or deployed. Each entry reports its audit state and evidence date explicitly.

Open the browser-readable estate registry, or use its okf-estate-registry.json projection from another tool. The authored source is registry/okf-estate-registry.yaml; neither generated projection should be edited by hand.

Introducing another repository or source type

• add or review the repository reconciliation preset;
• declare okf.semantic.json and okf.publication.json independently;
• add the repository and any public bundle to the appropriate registry;
• define source-family intake before acquiring or transforming data;
• implement lockstep and affected-plane CI checks;
• prove a small deterministic fixture through the actual consumer;
• document unresolved formats and optimisation work in the estate backlog; and
• deploy only after repository-specific review and exact-route verification.

Do not copy a neighbouring repository's commands, scope claims or publication mode merely because its data looks similar.