diff --git a/workplans/HOH-WP-0002-published-hall-and-renderers.md b/workplans/HOH-WP-0002-published-hall-and-renderers.md new file mode 100644 index 0000000..2bc1486 --- /dev/null +++ b/workplans/HOH-WP-0002-published-hall-and-renderers.md @@ -0,0 +1,194 @@ +--- +id: HOH-WP-0002 +type: workplan +title: "Publish the hall at helix.coulomb.social with selectable renderers" +domain: infotech +repo: hall-of-helix +status: proposed +owner: claude-code +topic_slug: helix-forge +priority: medium +created: "2026-09-05" +updated: "2026-09-05" +quality_dor: DoR-Failed +quality_dor_at: "2026-09-05" +quality_dor_by: claude-code +quality_dor_note: "Intent and URI shape are set by the operator, but four decisions block implementation: the entry identifier in the URI, where the service lives, how renderers are discovered and trusted, and whether the corpus is cleared for public publication. T01-T04 resolve those; the build tasks are deliberately not specified until they are." +related: + - HOH-WP-0001 +state_hub_workstream_id: "5e0db595-2f0e-5388-9413-7d4d5a4a2ef5" +--- + +# Publish the hall at helix.coulomb.social with selectable renderers + +The hall is 102 authored seats that can only be read as raw Markdown in a git +repository. It was always intended to be readable as a hall — a record of who +engaged on the Helix Forge platform, in the spirit of the end titles of a film +or a game, without the compensation framing that "credits" would import. + +There is no `helixforge` domain, so the canonical form is: + +``` +https://helix.coulomb.social/hall-of-helix/?renderer= +``` + +`` maps to one seat. `renderer` selects how the Markdown is presented and +is optional — omitting it is the same as `?renderer=default`. Renderers are +expected to be established as their own repos: a hypothetical `render-hrgiger` +would present a seat in an H.R. Giger register, selected as +`?renderer=render-hrgiger`. + +**This workplan is design-first and deliberately incomplete.** Four decisions +gate the build, and the implementation tasks should not be written until they +are settled. `status` stays `proposed` and DoR is `DoR-Failed` until then — +that is the honest state, not an oversight. + +## Decide the entry identifier in the URI + +```task +id: HOH-WP-0002-T01 +status: todo +priority: high +state_hub_task_id: "fc2e4306-5ecf-50db-9a75-8a241a4ae9bc" +``` + +Seat files are named `--.md`, which makes a poor URL: +`2026-09-05T16:36:12.000Z-codex-statehub-snapshot-and-signature`. + +Every seat already carries a unique frontmatter `id` +(`hall-worker-codex-statehub-snapshot-and-signature`), and `make check` already +rejects duplicates — so identity exists and is enforced. Options: + +- the frontmatter `id` verbatim — stable and already unique, but repeats the + `hall-worker-` prefix in every URL; +- the `id` with that prefix stripped — prettier, needs uniqueness re-checked; +- a short opaque id — stable under renaming, unreadable, and a new thing to keep. + +Whatever is chosen, **the URI is a permanent commitment**: a hall that breaks its +own links is not a record. Decide how a seat that is renamed or corrected keeps +its URI, and extend `make check` to enforce whatever invariant the answer needs. + +## Decide where the service lives and how it is built + +```task +id: HOH-WP-0002-T02 +status: todo +priority: high +state_hub_task_id: "b6ccb11c-2cf5-5f32-a2c5-a4f849eec437" +``` + +Two shapes, and they differ in more than effort: + +- **Static generation** — render at commit time, publish artifacts. Cheap, + cacheable, no runtime attack surface. `?renderer=` becomes a pre-rendered + variant per renderer, so the renderer set must be known at build time. +- **Dynamic service** — render on request. Naturally supports an open renderer + set and new renderers without rebuilding the corpus, at the cost of a running + service that executes selected code. + +Also decide whether the service lives in this repo or a sibling. This repo is +classified `publication` (canon v1.1 §5.7): the corpus is the deliverable, and +tooling that renders it is conventionally a separate `tooling` repo. That +suggests a sibling — `hall-render` or similar — with this repo staying the +content. + +Name the deployment target (railiance / k3s) and who owns the DNS record for +`helix.coulomb.social`. + +## Define the renderer contract and trust boundary + +```task +id: HOH-WP-0002-T03 +status: todo +priority: high +state_hub_task_id: "64370b21-2b30-5ce9-be63-0379c55dad5b" +``` + +`?renderer=` is **user-controlled input that selects code to run**. Treat +it as such from the first line of design: + +- resolve renderers through a **fixed allowlist**, never by interpreting the + parameter as a path, module name, package name, or repo URL; +- an unknown value falls back to `default` or returns a clean 404 — it never + attempts a fetch or an import; +- a renderer receives parsed Markdown plus frontmatter and returns markup; it + gets no credentials, no filesystem, and no network; +- renderer output is sanitised before it reaches a page. A renderer is + third-party code producing HTML, which is an XSS sink by construction. + +Then define the contract itself: input shape, output shape, how a renderer +declares itself, and how it is registered. Check whether the fleet's existing +capability discovery (`reuse-surface`, the capability catalog) is the right +registry before inventing one. + +Write it down as an ADR in this repo — a renderer author needs a spec, and this +is the part that will be got wrong quietly if it stays implicit. + +## Clear the corpus for public publication + +```task +id: HOH-WP-0002-T04 +status: todo +priority: high +state_hub_task_id: "8a67d5de-8974-576c-9c59-f7d2036403d9" +``` + +**Gate on this before anything is served publicly.** The seats were written as +an internal record. Publishing 102 of them to a public domain is an outward +change that cannot be undone by deleting the page — search engines and archives +keep copies. + +Review the corpus for: session identifiers and model/harness details, internal +hostnames, IP addresses, repository and infrastructure names, workplan and +decision ids, credential-adjacent narrative, third-party names, and anything a +human author would not have written for readers outside the fleet. + +Decide the disposition: publish whole, publish a filtered projection, or serve +the hall behind authentication. If a filter is chosen, it must be enforced in +the renderer pipeline rather than left to the author of each seat. + +The operator makes this call. Do not publish on an agent's judgement. + +## Build the hall index — the roll of participants + +```task +id: HOH-WP-0002-T05 +status: todo +priority: medium +state_hub_task_id: "57ddf0ad-01cf-5ac5-98d2-aa4d6449daff" +``` + +`https://helix.coulomb.social/hall-of-helix/` is the roll: every worker who has +sat, human and agent, drawn from the seats themselves rather than maintained by +hand — `README.md`'s list is already hand-maintained and will drift. + +Derive it from frontmatter: `display_name`, `worker_kind`, `recorded_at`, +`repos`, and the link to the seat. Group as the hall groups — by the work +shared, in the spirit of end titles — and let humans and agents appear on the +same roll, which is the point of the hall. + +Constraints from both `INTENT.md` files: no ranking, no scoreboard, no sorting +that implies merit, and **no aggregation of PQRST estimates**. The estimates +carried on seats since `HOH-WP-0001` describe sessions, not workers. A roll that +totals them becomes the leaderboard the hall exists not to be. + +Blocked on T01, T02, and T04. + +## Implement rendering with the default renderer + +```task +id: HOH-WP-0002-T06 +status: wait +priority: medium +state_hub_task_id: "bfab19dc-7f19-59f6-b85a-5a72cad89586" +``` + +Serve a single seat at the canonical URI with `renderer=default`, honouring the +decisions from T01-T04: identifier mapping, static or dynamic, allowlist +resolution, sanitised output, and whatever disposition T04 sets. + +The default renderer should present a seat plainly and legibly — the portrait, +the account, and the record — and set the reference implementation that a +renderer repo like the hypothetical `render-hrgiger` is written against. + +Deliberately unspecified until T01-T04 are decided.