From db5b310853ffbdeac9667aa6e84f8937b94c0e53 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 17 Aug 2026 15:12:15 +0200 Subject: [PATCH] Add INTENT and WP-0001: permanent publication surface policy.coulomb.social replaces disposable artifact-page publication. The repo has two halves - publishing estate policy outward, and gathering external policy inward - and one standing constraint: it reads from the repos that own policy and never writes back, so it cannot become a second source of truth. WP-0001 is scoped by a forcing case. ADR-008 needs review from six repos and is currently served from a private URL that may not resolve later. It is both the first publication and the acceptance test: if the site cannot carry five ladders, a threat matrix, an E x P grid and twelve owner-attributed questions, the site is not finished. T01 fixes addressing and the permanence promise before anything is built, because changing it later breaks the one thing this repo exists to guarantee. T02 takes over the renderer that already exists in the-custodian rather than reimplementing it - stdlib-only is an acceptance criterion, not a preference. T06 is deliberately last and carries a hard rule: a gathered record says what a source said and when, never what the estate must therefore do. Four questions left open for the operator, including who owns this and whether "government policies" in the README means regulation bearing on the estate or a broader public corpus. T06 cannot be specified until that is answered. Co-Authored-By: Claude Opus 5 --- INTENT.md | 105 +++++++++ ...S-WP-0001-permanent-publication-surface.md | 213 ++++++++++++++++++ 2 files changed, 318 insertions(+) create mode 100644 INTENT.md create mode 100644 workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..acd3a1b --- /dev/null +++ b/INTENT.md @@ -0,0 +1,105 @@ +# INTENT — policy-nexus + +## Why this repo exists + +`policy-nexus` is the permanent home for the estate's **policy surface**: the +place where policy is published, kept current, and gathered from the outside +world. It serves `policy.coulomb.social`. + +Before this repo existed, policy lived in two bad places. + +**Published policy was temporary.** Documents that other people needed to read +were pushed to disposable artifact pages — private URLs, no index, no history, +no guarantee the link resolves next month. A document that governs how six +repos behave cannot be delivered as a link that might expire. The estate has +already been bitten by the adjacent failure: a canon draft routed for +ratification on 2026-08-10 sat unratified in neither canon directory because +nothing tracked that it was in flight. + +**Incoming policy was nowhere.** Government and regulatory policy that bears on +what the estate may do — data protection, procurement rules, sector regulation +— was consulted ad hoc, at the moment somebody needed it, and never retained. +The same question was researched more than once, and the answer was never +recorded against the decision it informed. ADR-008's retention plane is a live +example: whether key destruction satisfies an erasure obligation is a question +about external policy that the estate answered in a research digest and has no +mechanism to keep current when the position moves. + +This repo exists so that policy has a permanent address, a known freshness, and +a path in as well as out. + +## What it owns + +- **`policy.coulomb.social`** — the public publication surface: its + infrastructure, deployment, availability and rollback. +- **Publication of estate policy.** Rendering governing documents from their + source repos into a durable, addressable, indexed site. The source of truth + stays in the owning repo; this repo owns the *publication*, not the content. +- **Stable addressing.** A published document keeps its URL. Superseded + versions remain reachable and are marked superseded rather than removed. +- **Currency.** Every published document carries its status, revision, and when + it was last reviewed. A stale document is visibly stale rather than silently + wrong. +- **Information gathering.** The intake path for external policy: what was + found, when, from where, and which internal decision it bears on. +- **The relevance loop.** Detecting when a published or gathered document has + gone out of date, and surfacing that rather than waiting for someone to + notice. + +## What it does not own + +- **The content of estate policy.** Canon lives in `the-custodian`; per-repo + ADRs live in their repos. This repo publishes what those own and must never + become a second place where policy is edited. The local-files-are-source-of- + truth rule applies with full force: if the site and the source disagree, the + source is right and the publication is a defect. +- **Ratification.** Whether a draft becomes canon is a canon-process decision. + This repo can show that a draft is in flight and how long it has been; it + cannot advance it. +- **Legal advice.** Gathered external policy is recorded with its source and + date. Interpreting what it requires of the estate is the owning repo's + decision, informed by the record, and the record must not read as a ruling. +- **Identity, authorization, storage, secrets.** Consumed from the platform + packages, never reimplemented. +- **Being a CMS.** No editing surface, no drafting in a browser. Documents + arrive from repositories. + +## Permanence is the point + +The word doing the work in this repo's purpose is *permanent*. It sets +requirements that a temporary page does not have: + +- **A URL that resolves in five years.** Addressing is a design decision made + once and then honoured, not a consequence of whatever generated the page. +- **History that survives.** A superseded policy is part of the record. Anyone + asking "what did this say when we made that decision" must be able to find + out. +- **Availability that is somebody's job.** If policy governs behaviour, policy + being unreachable is an incident, not an inconvenience. +- **Generated, never authored.** Every page is derived from a source document + in a repository. Nothing is hand-written into the site, because hand-written + content diverges from its source — a failure this estate has already had + once, between an ADR and its published page, and fixed by generating the page + from the markdown. + +## Relationship to the rest of the estate + +`policy-nexus` is downstream of every repo that owns policy and upstream of +nobody. It reads; it does not write back. That direction is deliberate: a +publication surface with write authority becomes a second source of truth, and +the estate has a standing rule against exactly that. + +The first content it must carry is already waiting: Custodian ADR-008 +(*Tenancy Posture*), which needs to reach six reviewing repos and is currently +served from a disposable artifact URL. The renderer that produces that page +from canon markdown (`the-custodian/tools/render-artifact.py`) is a prototype +of what this repo generalises — and taking it over rather than reimplementing +it is the intended path. + +## What good looks like + +A person outside the estate can find the policy that governs a decision, see +when it was last reviewed, read the version that was current at any past date, +and tell at a glance whether it is ratified or in flight. A person inside the +estate never asks "where is the current version of that" and never has to be +told "the link expired". diff --git a/workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md b/workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md new file mode 100644 index 0000000..02cc293 --- /dev/null +++ b/workplans/POLICY-NEXUS-WP-0001-permanent-publication-surface.md @@ -0,0 +1,213 @@ +--- +id: POLICY-NEXUS-WP-0001 +type: workplan +title: "Stand up policy.coulomb.social as the permanent publication surface" +domain: government +repo: policy-nexus +status: proposed +owner: unassigned +topic_slug: policy-nexus +created: "2026-08-17" +updated: "2026-08-17" +--- + +# POLICY-NEXUS-WP-0001 — permanent publication surface + +## Goal + +Replace disposable artifact-page publication with permanent infrastructure at +`policy.coulomb.social` that keeps policy **available**, **addressable**, +**current**, and **honest about its own staleness**. + +Done means: a governing document lives in its owning repo, is published +automatically, keeps its URL, shows its status and review date, retains its +superseded versions, and can be reached by someone outside the estate. + +## The forcing case + +Custodian ADR-008 (*Tenancy Posture*, draft-4) needs review from six repos — +`tenant-engine`, `flex-auth`, `rapp-postgres`, `railiance-platform`, +`adaptive-pricing`, `audit-core`. It is currently served from a private, +disposable artifact URL. Routing a document that governs six repos to a link +that may not resolve later is the problem this workplan exists to end. + +ADR-008 is therefore the first publication and the acceptance test. If the site +cannot carry it correctly — five ladders, a threat matrix, an E×P grid, twelve +owner-attributed open questions — the site is not finished. + +## Existing structure this workplan must respect + +**The renderer already exists in prototype.** +`the-custodian/tools/render-artifact.py` generates the ADR-008 page from canon +markdown: stdlib only, no dependency tree, recognising conventions already +present in the document rather than requiring extra markup. It was written +because the page and the ADR had diverged. **Take it over and generalise it; do +not reimplement it.** Its companion `tools/artifact-style.css` carries the +design system. + +**Source of truth stays upstream.** Canon lives in `the-custodian/canon`; +per-repo ADRs live in their own repos. This repo reads and never writes back. +A publication surface with write authority is a second source of truth, and the +estate has a standing rule against that. + +**The adoption stance applies** (ADR-008 §14): adopt published standards and +structural patterns; build tooling ground-up unless it is an established +industry standard with broad application. A static-site generator with a +plugin ecosystem is exactly what this rule excludes. + +**Platform packages are consumed, not rebuilt.** TLS, DNS, ingress, and any +credential come from the existing platform. If this repo needs storage it is a +`rapp-postgres` consumer and declares a posture vector like anyone else. + +## Non-goals + +- No editing surface. No CMS, no browser drafting, no comments. +- No ratification workflow. The site may *show* that a draft is in flight and + for how long; advancing it is a canon-process decision. +- No authentication in this workplan. Everything published here is + public-by-intent; anything that is not does not belong on this surface. +- No search index in this workplan. Deferred until there is enough content for + search to beat a good index page. + +## Tasks + +### T01 — Addressing scheme and permanence contract + +Decide, once, how a document maps to a URL, and write down what the estate is +promising about that URL. + +- URL shape for a document, and for a specific revision of it. +- What happens on supersession: the old URL keeps resolving and gains a + superseded banner pointing forward. +- What happens on withdrawal: distinguish *withdrawn* (kept, marked) from + *deleted* (does not happen). +- Where the version history lives, given the source is git in another repo. +- The commitment being made — a URL published here is expected to resolve + indefinitely, and what would have to happen for that to be broken. + +**Output:** `docs/adr/ADR-0001-addressing-and-permanence.md`. + +**Why first:** everything downstream bakes in the answer, and changing it later +breaks the one promise the repo exists to make. + +### T02 — Generalise the renderer + +Move `render-artifact.py` and `artifact-style.css` in, and lift them from +one-document to many. + +- Multi-document: a manifest of sources rather than one path argument. +- Front-matter driven: title, status, revision, review date, owner from the + source document rather than from command-line flags. +- Index generation: a landing page listing documents with status and currency. +- Keep the convention recognisers (level ladders, threat matrix, E×P grid, + evidence chips, section rail) and keep it stdlib-only. +- Keep the "generated from canon — do not edit" marker on every page. + +**Acceptance:** ADR-008 renders byte-identically in substance to the current +generated page, plus an index entry. + +### T03 — Source ingestion + +Define how a document gets from its owning repo to this one. + +- Manifest format: source repo, path, publication URL, owner. +- Fetch mechanism for documents in other repositories, and how a fetch failure + is surfaced rather than silently serving stale content. +- Determinism: the same source commit must produce the same page. +- Record the source commit on the published page, so a reader can tell exactly + what was rendered. + +**Open decision for T03:** pull (this repo fetches on a schedule) or push (the +owning repo triggers on merge). Pull is simpler and keeps the direction of +dependency clean; push is fresher. Recommend pull with a manual trigger, and +record the choice. + +### T04 — Deploy to policy.coulomb.social + +- DNS, TLS, ingress via the existing platform packages. +- Static hosting — the output is static files by construction, so the serving + layer should be the least interesting part of this workplan. +- Availability expectation stated plainly, with the honest caveat that a + single-node rail gives restart recovery, not high availability. Do not claim + an SLA the substrate cannot support. +- Rollback: republishing a previous build must be a single command. +- Smoke check after every deploy: the index resolves, ADR-008 resolves, and a + known superseded URL still resolves. + +### T05 — Currency and staleness + +The relevance half of the repo's purpose. A permanently available document that +is quietly out of date is worse than no document. + +- Every page shows status, revision, and last-reviewed date. +- A review interval per document, and a visible marker once exceeded. +- A report of documents past review, and where it is delivered. +- Drafts show how long they have been in flight. The + `shared-platform-relational-storage_v0.1` draft has been routed and + unratified since 2026-08-10; that fact should be visible on the site, because + invisibility is precisely why it stalled. + +### T06 — External policy intake + +The information-gathering half. Deliberately last: the publication path must +work before a second content type is added. + +- A record format for an external policy finding: what, source URL, date + retrieved, jurisdiction, which internal decision it bears on, and who + recorded it. +- Where records live and how they are published. +- The staleness question, which is sharper here than for internal documents: + external policy changes without telling us. A record must carry its retrieval + date prominently and be treated as a snapshot, never as current law. +- **A hard rule to write into the format:** a gathered record states what a + source says and when it said it. It does not state what the estate must + therefore do. That interpretation belongs to the repo making the decision. + +**Worked example available:** the ADR-008 retention research already holds one +of these — whether key destruction satisfies an erasure obligation, where data +protection authorities have accepted it under conditions and the EDPB has not +formally endorsed it. That is exactly a finding that is true today, may not be +in a year, and must never be recorded as settled. + +## Sequencing + +T01 gates everything. T02 and T03 can proceed in parallel once addressing is +fixed. T04 needs both. T05 is additive. T06 is deliberately last. + +The temporary artifact URL for ADR-008 stays live until T04 passes its smoke +check, and the review is routed to the permanent URL, not before. + +## Risks + +**This repo becomes a second source of truth.** The likeliest failure and the +most damaging. Mitigation: no editing surface, generated pages carry a +do-not-edit marker, and the manifest records the source commit for every page. + +**Permanence is promised before it can be delivered.** A URL committed to in +T01 and broken in year two is worse than never having promised. Mitigation: +T01 states what would break the promise, and T04 declines to claim an +availability level the single-node rail cannot support. + +**Scope drift toward a CMS.** Every publication surface attracts requests for +editing, comments, and workflow. Mitigation: the non-goals above are part of +the workplan, not a preface to it. + +**The renderer grows a dependency tree.** The moment it needs a framework, it +becomes something only CI can run. Mitigation: stdlib-only is an acceptance +criterion on T02, not a preference. + +## Open questions for the operator + +1. **Owner.** This workplan is `unassigned`. It spans infrastructure and canon + process and does not obviously belong to an existing repo's agent. +2. **Public by default?** INTENT assumes everything on this surface is + public-by-intent. Confirm that no estate policy is sensitive enough to need + an authenticated tier — if any is, that changes T04 substantially. +3. **Scope of "policy".** Canon and ADRs are clearly in. Are workplans, + decision records, and evidence in scope, or is this a policy site rather + than a general documentation site? Recommend starting narrow — canon and + ADRs only — and widening on demand. +4. **Government policy scope** (T06). The README describes convergence for + *government* policies. Is the intake scoped to regulation bearing on the + estate, or is a broader public-interest corpus intended? These are very + different repos, and T06 cannot be specified until this is answered.