Website SOP

Opplet Systems: The Official Website SOP

Version 1.0 · DRAFT (reconciles to Constitution v12.8) · Tier 3 — Tier 3 — Operations & Learning · not yet released · effective 2026-07-03

You're reading the public edition of Website SOP. The working source — drafts, change discussion, and member resources — lives in the community library.

Join-Community:/

Purpose and Scope

This SOP is the how for opplet.com. Its companion, the Official Website Strategy (opplet-website), is the why — it explains what the site is and why it is governed. This document explains how to operate it: how a page becomes a governed document, how a content page declares what it is based on, how drift is read and reconciled, and how the site is built and deployed.

It does not define the release procedure. Cutting a Charter Release — re-pinning the set so it certifies coherent again — is the Custodian’s responsibility under SOP §11, recorded in RELEASE.md. This SOP references that procedure; it does not restate it.

1. Two Kinds of Page

Every page on the site is one of three things, and the difference is declared in front matter:

  • a governed document — a charter document (Constitution, a Doctrine, an SOP, a manifest, a course). It carries a doc_id, a doc_version, and a tier. It appears in the compatibility matrix and is pinned in releases.
  • a derived page — ordinary content whose description of Opplet’s approved state is based on one or more governed documents. It carries charter_refs (see §3). It does not appear in the matrix; instead it reports which documents it draws on, and whether they have moved since it was written.
  • an editorial page — everything else (history, the actors, rationale, comparisons). It carries neither. It is not governed and makes no coherence claim.

A page is never both a governed document and a derived page: one publishes the approved state, the other describes it.

2. Governed Documents

A page becomes a governed charter document by declaring, in front matter:

  • doc_id — a stable, unique identifier (e.g. software-stack). This is the key everything else references. It never changes casually; changing it silently breaks every reference that names it (see §6).
  • doc_version — the document’s own version. Bump it whenever the document’s substance changes. This is the value the matrix compares against the release pin, and the value derived pages track.
  • tier — an integer placing the document in the governance hierarchy. Tier labels live once in hugo.toml under params.charterTiers (array position = tier number), shared by the matrix and the manifest so the two never disagree. A tier with no label falls into “Unfiled” rather than breaking the build — a signal to add the label, not a place to leave documents.

Optional meta fields — doc_name (full formal name), status, effective_date — render in the document’s meta band if present.

A new governed document is not automatically part of a release. Until it is pinned, it shows in the matrix as Not yet released and appears in the drift report’s no pin yet list. That is correct: the review queue is telling you a decision is pending. It enters the certified set at the next reconciliation, per SOP §11.

3. Charter References (charter_refs)

A derived page declares its sources with a charter_refs list in front matter. Each entry names one governed document and, optionally, the version the page was written against:

1
2
3
4

charter_refs:
  - doc: software-stack
    at: "1.6"
  - doc: enclave-doctrine
  • doc (required) — the doc_id of a governed document.
  • at (optional) — the doc_version the page’s approved-state content was written against, as a string.

The optional at is the whole distinction between two modes:

  • Baseline-tracked (at present) — the page pins the version it was reconciled to. The system compares that baseline against the document’s current doc_version and reports current (they match) or review (they differ). This is a live coherence check.
  • Cross-link only (at absent) — the page asserts a relationship but no baseline. It renders as a plain back-link, is never flagged as drifted (there is nothing to compare), and must be reviewed by hand when its source changes.

The expectation

Both modes are supported, but they are not equivalent, and the site should not drift into the cheaper one by default:

  • A page whose approved-state content reflects a specific version of a document SHOULD pin at:. This is most derived pages.
  • A page that only relates to a document without tracking a particular version MAY omit at:.

Omitting at: because it is less work is how the coherence machinery quietly stops doing anything. Pin the baseline unless there is a real reason not to.

Note that the comparison is symmetric: the system flags any mismatch between baseline and live version, not only a document that has moved ahead. If a baseline reads higher than the live document, that is also an incoherence worth surfacing.

4. Where Coherence Is Reported

The system computes coherence on two axes and never stores the result — every status is derived at build time from the live front matter.

  • Axis 1 — document vs. release. Has a governed document moved ahead of the version pinned in the active release? Reported by the drift summary and the compatibility matrix.
  • Axis 2 — derived page vs. source document. Has a page’s baseline fallen behind the document it was written against? Reported on each page’s sources band, on each document’s derived-pages list, and aggregated in the content-coherence rollup.

All of it converges on the Charter Status report (/charter-status/), which carries both axes on one page: the drift summary, the full matrix, and the content-coherence rollup. That page is the single pane for “is everything coherent?” A derived page also shows its own status inline; a governed document shows the pages that depend on it. The derived-pages list is computed, never hand-maintained — adding charter_refs to a page makes it appear on its sources’ pages automatically.

5. The Review Workflow

The point of the machinery is that a document changing tells you exactly what to re-check. When a governed document’s doc_version is bumped:

  1. Open the document’s page (or the Charter Status report). Its derived-pages list — and the content-coherence rollup — now show every page whose baseline no longer matches, marked review.
  2. For each flagged page, do one of:
    • Reconcile: update the page’s approved-state content to reflect the new document version, then bump the page’s at: to that version.
    • Confirm: if the page’s content was already correct for the new version, bump at: alone. The content did not need changing; the baseline did. In both cases the outcome is the same: at: again equals the document’s current version, and the page returns to current.
  3. For cross-link-only pages (no at:), the report cannot tell you whether they are stale — it lists them as linked without a baseline. Review them by hand when their source changes; that manual step is the price of omitting the baseline.
  4. If a page shows Unknown source (a charter_refs entry naming a doc_id with no matching document), fix the doc_id or remove the reference. The reference is pointing at nothing.

Reconciling pages is content maintenance and does not require a Charter Release. Releases pin the governed documents (Axis 1); page baselines (Axis 2) are tracked independently and reconciled as content changes.

6. Housekeeping That Preserves Coherence

Structural changes are where coherence silently breaks. The rules:

  • Renaming a page’s URL — add an aliases: entry in the page’s front matter for the old path. Governed-document URLs are linked from the footer, the breadcrumbs, and the meta band’s “part of {release}” link; renaming without an alias 404s all of them.
  • Removing a governed document — remove its pin from the release lockfile under data/releases/. A pin whose document no longer exists is surfaced in the matrix as Pinned, missing from content rather than silently vanishing — that flag is telling you to clear the stale pin (or restore the page).
  • Changing a doc_id — update every charter_refs entry that names the old id in the same change. A reference to a renamed id renders as Unknown source.
  • Adding a tier — add its label to params.charterTiers in hugo.toml. Documents in an unlabelled tier fall into “Unfiled” until you do.

7. Build and Deploy

The site is a Hugo static build published by the Kitchen production GitLab pipeline. The deploy is designed so that no failed or interrupted build can take the live site down.

  • The runner triggers; the server builds. The pipeline job carries GIT_STRATEGY: none and does not build on the runner. It opens an SSH session to the production server, which fetches origin/main, builds with Hugo, and publishes. A green pipeline therefore means “the trigger ran,” not “the site is verified” — always confirm the live URL after a deploy.
  • Build to staging, swap on success. Hugo builds into a staging directory (public_html.new); only a successful build is swapped into the live public_html, and the previous live copy is retained as public_html.bak. The live directory is untouched until a complete build is ready. An SSH drop, a hung build, or a killed runner leaves the live site serving the previous version.
  • One deploy at a time. The pipeline is interruptible with auto_cancel.on_new_commit, so a new push cancels an in-flight deploy rather than letting two builds race over the same output.
  • A hung build fails fast. The job carries a short timeout so a stalled build errors quickly instead of occupying the runner until the global timeout.
  • Do not upgrade modules in the deploy. The deploy builds what is committed; it does not run hugo mod get -u. Chasing upstream module updates mid-deploy makes builds non-reproducible and can hang on a network call.

To deploy: push to main, or run a new pipeline on main. Watch the job to completion, then load the site to confirm.

To roll back: the previous build is preserved as public_html.bak on the server. Restoring it is the fast recovery if a build is green but wrong. A clean rebuild from a known-good commit is the alternative.

8. The Site Reports on Itself

Because the site publishes the governance, its own governed documents must not drift from the corpus they carry, and its derived pages must not fall behind the documents they describe. Both are visible on the Charter Status report. This SOP, opplet-website, and every other governed document are pinned in releases like any other; this page’s own doc_version moves when these procedures change materially, the matrix flags it, and it is reconciled into the next release.

Changelog

v1.0 (2026-07-03) — Initial

  • First issue. Documents the mechanics of running opplet.com as a governed system: the governed/derived/editorial page distinction, the charter_refs schema and the baseline-vs-cross-link expectation, the two coherence axes and where they are reported, the review workflow, structural housekeeping, and the hardened build/deploy procedure.
  • Pairs with opplet-website (the strategy/doctrine) as its operational companion. References the release procedure (SOP §11, RELEASE.md) rather than restating it. Reconciles to Constitution v12.8.

END OF DOCUMENT

All charter documents

Has anything touched?

If reading this made you want to argue with it, extend it, or notice what's missing, that's the signal to show up.

You're invited to:

commit register to step into opplet partner advance or support the development sync chat or stay without committing deploy clone or fork opplet as your enclave
:/back-to-top