lora.vegas/TODO.md

# Workflow

- branch (from `main`)
- do the work in Next Step
- move Next Step to the top of Completed Steps
- move the top item of Future Steps into Next Step
- commit (`TODO.md` changes in the same commit as the work)
- merge to `main` if the branch is not protected, otherwise open a PR
- push

# Status

pre-1.0

No git tags. The site is live and now has the scripts-to-rule-them-all scaffold
(`Makefile`, `script/`, `Dockerfile`, `check.yml`), the canonical policy
dotfiles and `LICENSE`, so the mandated minimum file list is complete. Every
external reference in the repo is now pinned by cryptographic hash (or, for the
wrangler CLI install, an exact version), and the Hugo that builds the published
site is a deliberate pinned version rather than whatever the base image's
package repo serves. The site now ships a Cloudflare Pages `_headers` file, so
its response security headers are declared in the repo instead of being whatever
the edge defaults to — unverified in production until the next deploy. Every
lint-class check now runs inside a container and nowhere else: `script/lint` and
`script/fmt-check` build stages of `Dockerfile.lint`, with no host path to fall
back to.

# Next Step

Add the missing `cibuild` and `precommit` shims to the `Makefile`, so that every
documented entrypoint has a make target and the documented "always use make
targets" rule is actually satisfiable
(https://git.eeqj.de/sneak/lora.vegas/issues/34). Done when `make cibuild` and
`make precommit` exist, are declared `.PHONY`, and the README Entrypoints
section matches.

# Completed Steps

- 2026-08-10: moved every lint-class check into Docker
  (https://git.eeqj.de/sneak/lora.vegas/issues/38). A new root `Dockerfile.lint`
  carries the checks as build steps — a `lint` stage running
  `hugo --minify --printPathWarnings` and a `fmt-check` stage running the
  prettier check — on a shared `base` stage whose first four instructions are
  byte-identical to the main `Dockerfile`'s, so the expensive
  `RUN script/bootstrap` layer that compiles Hugo from source is a cache hit
  against the main image rather than a second build of the same thing.
  `script/lint` and `script/fmt-check` are now nothing but a `docker build` of
  their stage; there is no host path and deliberately no "already inside a
  container?" branch, which would be a host lint path in disguise. The recursion
  this creates was resolved by splitting the checks by where they run rather
  than by adding an escape hatch: `make check` runs `script/lint`, so the main
  `Dockerfile` can no longer `RUN make check` — that would be docker-in-docker
  inside a bare Alpine with no docker client and no daemon socket, and
  `script/cibuild` is what CI runs on every push. The main `Dockerfile`
  therefore runs `make test`, the production build, and `script/cibuild` builds
  it and then calls `script/lint` and `script/fmt-check`, so CI still covers all
  three and cannot drift from what a developer runs. `script/fmt` stays on the
  host because it rewrites the working tree, which makes it the authoritative
  copy of the prettier version and flags that the `fmt-check` stage duplicates;
  both sides carry a keep-in-sync note, and that duplication is forced, since
  any `RUN script/fmt-check` inside the image is the recursion again. Caching is
  waived for the checks exactly as the main `Dockerfile` already does it:
  `ARG CHECK_EPOCH` with no default, declared and guarded separately in each
  stage because `ARG` does not cross a `FROM`, with the value expanded into the
  checked command as well as the guard. All four image-building entrypoints now
  generate and pass it — `script/cibuild`, `script/docker`, `script/lint`,
  `script/fmt-check` — which is the failure mode this repo already hit once, a
  Dockerfile guard asserting a property one entrypoint did not supply. Verified
  rather than assumed: two consecutive `script/lint` runs on an unchanged tree
  both executed hugo for real (second run 2.9s wall, `RUN script/bootstrap`
  `CACHED`, distinct epoch echoed, `Total in 37 ms` printed), a constant-epoch
  counterfactual restored the false green (exit 0 in 0.25s, lint layer `CACHED`,
  no hugo output at all), an empty epoch failed closed on the guard, a broken
  template failed the lint stage with hugo's own render error, and an over-long
  line appended to `README.md` failed the fmt-check stage with
  `[warn] README.md`; both violations were reverted and re-run clean. Not
  changed here, and still true: the lint stage fails on hugo build errors but
  not on render-target collisions, which `--printPathWarnings` only prints
  (https://git.eeqj.de/sneak/lora.vegas/issues/25) — containerising the run
  neither fixes nor worsens that
- 2026-08-10: added the `LICENSE` file and made the README say what it says
  (closes #10). The repo is public (`private: false` on the Gitea API, verified
  rather than assumed), so the owner's standing policy — MIT on any public repo
  lacking a license — applies. `LICENSE` is byte-identical to the canonical
  `sneak/homoicon` copy, confirmed by git blob hash rather than by eye
  (`3274443`), and its body is word-for-word the SPDX MIT text with only the
  line wrapping differing. The README's "Content is provided as-is for community
  use." — which granted nothing and matched no committed file — is replaced by
  `MIT. See [LICENSE](LICENSE).` plus an explicit statement that the licence
  covers the content in `content/` as well as the code, since this repo carries
  both and MIT names only "the Software". The Description first line now carries
  the licence, which `REPO_POLICIES.md` requires and which was the one field it
  was missing. Nothing published contradicts the choice: the built `public/`
  tree carries no copyright, all-rights-reserved or terms-of-use string
  anywhere, in `index.html`, `css/style.css`, `index.xml` or `sitemap.xml` — the
  footer `baseof.html` renders names `@sneak` and links the repo but asserts no
  reservation of rights, and the content is factual mesh channel data with no
  licence claim of its own. The fmt gate cannot reach `LICENSE` and needed no
  `.prettierignore` entry: `script/fmt` passes prettier the explicit globs
  `'**/*.md'` and `'**/*.css'`, and an extensionless root file matches neither.
  Measured, not assumed — a `script/fmt` run leaves the file's hash unchanged,
  and a counterfactual `LICENSE.md` copy was reflowed by the same run, which is
  the direct evidence that it is the extension and not an ignore rule doing the
  excluding. Deliberately not done, per the issue: per-file licence headers and
  SPDX identifiers, which no org standard mandates
- 2026-08-09: added `static/_headers` so Cloudflare Pages serves baseline
  response security headers (closes #14). Hugo copies `static/` verbatim into
  `public/`, which is the deploy root Pages reads the file from; this is the
  first root-level `static/` in the repo, and the built tree confirms it unions
  with the theme's rather than shadowing it — `public/css/style.css` and
  `public/index.html` are byte-identical to the previous build and the static
  file count goes 1 to 2. The live "before" was measured, not assumed:
  Cloudflare already sends `X-Content-Type-Options` and `Referrer-Policy` by
  default, so the substance here is `Strict-Transport-Security`,
  `Content-Security-Policy`, `X-Frame-Options` and `Permissions-Policy`. The CSP
  is `default-src 'none'` with `style-src 'unsafe-inline'`, which the built page
  supports exactly: it has no script, img, link, iframe, form or media element
  and no `style=`/`on*=` attribute, only the one inline `<style>` block
  `baseof.html` fills by `readFile`. Verified in a headless Chrome against a
  local server that parses the committed `_headers` and applies it as real
  response headers: zero CSP violations, the inlined stylesheet parses to 17
  rules and the computed body padding, tagline colour and link colour all come
  from the theme CSS, framing the page from another origin is refused by
  `frame-ancestors 'none'` (consistent with `X-Frame-Options: DENY`), and all
  five named outbound links still navigate with status 200. HSTS carries neither
  `preload` nor `includeSubDomains`: `www.lora.vegas` is the only other name in
  DNS and it is served by this same Pages project, so this file sets HSTS on its
  responses directly, and `includeSubDomains` would instead bind every future
  subdomain for a year with no way to walk it back inside the max-age window
  without also dropping the apex protection.
- 2026-08-09: restructured `README.md` into the canonical section set (closes
  #11): a Description first line, then Getting Started, Entrypoints, Rationale,
  Design, TODO, License, Author. The non-standard About / Contributing /
  Technical Details headings are gone, but nothing they held was dropped — the
  bullet list of what the site publishes moved under the Description, the
  contribute contact and the local-preview instructions moved into Getting
  Started. Getting Started was written against the current `Makefile` rather
  than the old prose: there is no `make build` target, so the former "Build:
  `hugo`" instruction is now `make test`, and the former "Local Development:
  `hugo server`" is `make setup` then `make serve`. Two stale claims fixed: the
  site is deployed by Gitea Actions to Cloudflare Pages, not "GitHub Actions",
  and the Entrypoints bullet for `script/fmt` still described the
  top-level-markdown-only scope that #12 replaced with `'**/*.md'` and
  `'**/*.css'`. The License section body is deliberately untouched — it is owned
  by #10, which is blocked on the owner's choice of license, and the Description
  sentence is likewise missing the license clause the policy calls for until #10
  lands. Design section claims were verified against the tree, not assumed
- 2026-08-09: widened the prettier gate from top-level markdown to `'**/*.md'`
  and `'**/*.css'` (closes #12). `themes/loravega/static/css/style.css` was
  never formatted or gated even though it is inlined into every page; it is now
  both, and the reformat landed as its own commit ahead of the script change so
  no commit in the branch is red. `content/` is excluded in `.prettierignore`,
  and that exclusion is measured rather than assumed: with `content/` in scope,
  prettier re-wrapped one list item in `content/_index.md` and the rendered
  `public/index.html` changed with it (the wrap became a literal newline between
  `7 PM at` and the following `<a>`). HTML collapses that newline to a space so
  the page looks identical, but the published bytes are not, and this content
  carries raw HTML that goldmark passes through verbatim under `unsafe = true`.
  `themes/loravega/layouts/` is excluded too, with the reason recorded: those
  files are Go templates, not HTML, and prettier has no parser for `{{ ... }}` —
  covering them would need a plugin and therefore a `package.json`. Verified by
  extracting `public/` from the built image before and after: with the final
  scope, `index.html`, `index.xml` and `sitemap.xml` are byte-identical and only
  the verbatim-copied `public/css/style.css` changes, in whitespace only — the
  minified `<style>` block inlined into `index.html` is unchanged, which is the
  direct evidence that CSS formatting cannot reach the rendered page
- 2026-08-09: added the canonical policy dotfiles and hardened both ignore files
  (closes #8). `REPO_POLICIES.md` is a byte-identical copy of the canonical
  `prompts` file, front matter intact; `.editorconfig`, `.prettierrc` and
  `.prettierignore` are the canonical contents. `.gitignore` keeps its three
  Hugo lines and gains the OS/editor/node/secrets block plus `.claude/`, so a
  clean checkout with agent tooling present is `git status`-clean and a stray
  key or `.env` can no longer be committed. `.dockerignore` gained the same
  coverage but **not** the same syntax: it matches with Go's `filepath.Match`
  rules extended with `**`, where `*` does not cross `/` and an unprefixed
  pattern is anchored at the context root, so every depth-independent pattern
  carries an explicit `**/` prefix and only the genuinely root-anchored entries
  (`.git`, `public`, `resources`, `.hugo_build.lock`) go bare. Verified by
  planting `.env`, `*.key`, `*.pem` and `node_modules` two directories deep: the
  unprefixed form shipped all of them into the image and the `**/` form ships
  none. Excluding `.claude/` also takes `worktrees/` — entire additional
  checkouts of this repo — out of the build context; #23's two-consecutive-run
  proof was re-run against the smaller context, since that issue was validated
  against the old one. Note the canonical upstream `REPO_POLICIES.md` is not
  clean under this repo's prettier settings, so the reformat is a separate
  follow-up commit rather than churn mixed into this one
- 2026-08-09: stopped `script/cibuild` reporting a green it never earned (closes
  #23). `COPY . .` is keyed on content, so on an unchanged tree Docker served
  `RUN make check` from cache: the checks never executed and the build still
  exited 0. Three separate reviewers had already been fooled by it here. The
  `Dockerfile` now declares `ARG CHECK_EPOCH` below `COPY . .` with no default
  (a default is a constant, and a constant is a stable cache key), guards it
  with `RUN [ -n "$CHECK_EPOCH" ] || exit 1`, and expands it into the check
  command; `script/cibuild` and `script/docker` both pass
  `epoch="$(date +%s%N)$$"` — assigned on its own line, because a failing
  command substitution inside an argument does not trip `set -e`, and with `$$`
  because busybox `date` drops `%N` silently. This is the canonical shape
  settled upstream in `prompts` #26, which has not merged there yet, so it may
  need re-syncing. Verified with two consecutive runs on an unchanged tree that
  both executed the checks while `RUN script/bootstrap` stayed `CACHED`, a
  constant-epoch counterfactual that restored the false green, and a planted
  prettier failure that failed the build
- 2026-08-09: disabled the unused `taxonomy` and `term` page kinds in
  `hugo.toml` (closes #13). Hugo enables the `tags` and `categories` taxonomies
  by default; this single-page site has no taxonomy terms and no taxonomy
  templates, so every build emitted
  `WARN found no layout file for "html" for kind "taxonomy"` and generated
  `categories/index.xml` and `tags/index.xml` that nothing links to. Re-verified
  the warning still occurs on the now-pinned hugo v0.164.0 rather than trusting
  the issue's text, which predates the version move. `make test` and `make lint`
  are now `WARN`-free, so the build's noise floor is zero and the next warning
  will be visible. `public/` is otherwise byte-identical — `index.html`,
  `css/style.css` and the RSS `index.xml` all unchanged — and `sitemap.xml` is
  still generated, now listing only the home page instead of two taxonomy URLs
- 2026-08-09: replaced `hugo.toml`'s deprecated `languageCode` key with `locale`
  (closes #18). Hugo deprecated `languageCode` in v0.158.0, so the Hugo pinned
  in the preceding commit warns about it; left alone it would become a third
  routinely-ignored warning, and a latent breakage when the key is removed.
  Deliberately sequenced **after** the Hugo version move and in the same branch:
  under the apk hugo 0.139.0 that CI ran until now, `locale` is an unknown key
  that is silently ignored, which downgrades the generated RSS from
  `<language>en-us</language>` to `<language>en</language>` with no warning and
  exit 0. Verified on hugo v0.164.0 that the RSS `<language>` still reads
  `en-us`, the `lang` attribute is unchanged, and `public/` is byte-identical to
  the preceding commit's output
- 2026-08-09: installed Hugo at a deliberate, hash-verified version instead of
  taking whatever alpine ships (closes #26). `script/bootstrap` no longer does
  `pkg_install hugo`; it installs `github.com/gohugoio/hugo@v0.164.0` with
  `go install`, which verifies the module against `sum.golang.org`. The version
  is a commented constant, as is the Go toolchain (`go1.26.5`) — hugo v0.164.0
  requires go >= 1.26.0 and alpine 3.21 ships go 1.23.9 with
  `GOTOOLCHAIN=local`, so a bare `go install` refuses to run. `CGO_ENABLED=0` is
  deliberate: standard Hugo, not extended, because this site has no SCSS, no
  `resources.ToCSS`, no PostCSS and no image processing. This moves the build
  off apk's hugo 0.139.0, about two years behind, onto the current stable.
  Rendered output across the whole `public/` tree is unchanged except the
  `meta name=generator` version string
- 2026-08-09: made `script/check` run `script/lint` (closes #9). It previously
  ran only `fmt-check` then `test`, so `script/lint` executed nowhere — not in
  `make check`, not in the pre-commit hook, and not in CI, even though the
  `Dockerfile` runs `make check` and `script/cibuild` builds it. It now runs
  `test`, `lint`, `fmt-check` in the canonical order, so the
  `hugo --printPathWarnings` render-target-collision signal is no longer
  discarded. `README.md`'s Entrypoints line was corrected to match
- 2026-08-09: hash-pinned every external reference in
  `.gitea/workflows/deploy.yml` (closes #7): both job container images are
  pinned by digest, all three `uses:` are pinned by 40-hex commit SHA, and the
  wrangler install is pinned to an exact version. The abandoned
  `klakegg/hugo:ext-alpine` image is gone: the build job now runs on the same
  pinned `alpine` digest the `Dockerfile` uses, with a pre-checkout
  `apk add nodejs git tar` step (the Actions runner needs `node` inside the job
  container to execute JavaScript actions), an explicit `shell: sh` default,
  then `script/bootstrap` and `script/test`. The `deploy` job is guarded with
  `if: github.ref_name == 'main'` so it can never publish from a branch. Also
  dropped the dead `feat/initial-site` push trigger and reindented the file to
  4-space YAML to match `check.yml`. This is the second attempt; the first broke
  the deploy and was reverted, so this one was verified by temporarily
  triggering the workflow on the PR branch and iterating until the `build` job
  ran green for real
- 2026-07-25: added the scripts-to-rule-them-all scaffold (closes #4): `script/`
  entrypoints, `Makefile` shims, a Hugo `Dockerfile` (sha256-pinned alpine) plus
  `.dockerignore` that runs `make check`, `.gitea/workflows/check.yml` running
  `script/cibuild`, and a README Entrypoints section. `test`/`lint` are a clean
  `hugo --minify` build; `fmt`/`fmt-check` run prettier over the repo's own
  top-level markdown only
- 2026-02-10: design pass: minimal light theme with inline CSS, grey wells for
  mesh channels and signal groups, horizontal overflow fix, body width tuning,
  map link update
- 2026-02-10: added README and footer contribute link
- 2026-02-10: added Gitea workflow that builds the site and deploys to
  Cloudflare Pages
- 2026-02-08: initial Hugo static site for lora.vegas

# Future Steps

Startable work first. Everything under "Blocked" waits on somebody or something
outside this repo, so nothing there may be picked up as the Next Step.

- Make the prettier scope's exclusion of dot-directories explicit instead of
  leaning on `.gitignore` (https://git.eeqj.de/sneak/lora.vegas/issues/33)
- Fix the README's SSH-only clone URL, and add the two entrypoints the
  Entrypoints section omits, `script/precommit` and `script/projectname`
  (https://git.eeqj.de/sneak/lora.vegas/issues/36)
- Drop the Go toolchain and module cache from the check image's final layer;
  they are needed to build hugo and dead weight afterwards
  (https://git.eeqj.de/sneak/lora.vegas/issues/28)
- Add a timeout guard to `script/test` and `script/lint` so a wedged build fails
  instead of hanging (https://git.eeqj.de/sneak/lora.vegas/issues/16)
- Sync the reformat of `REPO_POLICIES.md` back upstream to `prompts` so the
  canonical copy is clean under the shared prettier settings and future syncs
  are a straight byte copy
- Keep mesh channel and signal group listings current

## Blocked

- Decide whether `script/lint` should fail on render-target collisions rather
  than only print them; `--printPathWarnings` exits 0 today, so the signal is
  reported and not enforced. Owner call, since it changes what the gate rejects
  (https://git.eeqj.de/sneak/lora.vegas/issues/25)
- Move the artifact actions in `.gitea/workflows/deploy.yml` to v4 once this
  Gitea Actions instance serves the v4 artifact protocol; they are pinned on the
  deprecated v3 line because v4 fails here
  (https://git.eeqj.de/sneak/lora.vegas/issues/20). This touches the live deploy
  path, so it needs a real workflow run to verify rather than a local check
- Move the deploy container to a pinned node 22 so the wrangler pin can advance
  past 4.86.0 (https://git.eeqj.de/sneak/lora.vegas/issues/21)
- Delete the stale remote branches `feat/initial-site` and `security-audit`;
  only the owner can remove them
  (https://git.eeqj.de/sneak/lora.vegas/issues/15)
- After the next deploy, confirm the `_headers` file actually took effect, on
  both `https://lora.vegas/` and `https://www.lora.vegas/`: `curl -sSI` against
  each must show `strict-transport-security` or `content-security-policy`.
  Cloudflare Pages silently ignores a malformed `_headers`, and checking
  `x-content-type-options` would pass either way because the edge sends it
  regardless. `www` has to be checked too and not just the apex: dropping
  `includeSubDomains` rests on `www.lora.vegas` being served by this same Pages
  project, which was established behaviourally from identical response bodies
  rather than from the Cloudflare dashboard. If `www` turns out not to be
  covered, the `includeSubDomains` decision has to be revisited
  (https://git.eeqj.de/sneak/lora.vegas/issues/14)
- Decide the HSTS `includeSubDomains` and `preload` posture for `lora.vegas`.
  Both are owner calls: neither can be walked back inside the max-age window,
  and `includeSubDomains` binds hostnames this repo does not control
  (https://git.eeqj.de/sneak/lora.vegas/issues/14)
- Verify the Cloudflare Pages deploy still works after the workflow changes