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.