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, and confirmed live in production on both hostnames. The lint now runs inside a container and nowhere else: script/lint is a build of Dockerfile.lint, with no host path to fall back to. Formatting is not a lint and stays on the host. Every entrypoint the README documents now has a Makefile target, so the org-wide "use make targets, never the underlying tool" rule is satisfiable for the CI build as well as for the everyday checks.

Next Step

Make the prettier scope's exclusion of dot-directories explicit instead of leaning on .gitignore (#33).

Completed Steps

• 2026-08-10: added the cibuild and precommit targets to the Makefile (#34). Both scripts already existed, were already documented, and are the two entrypoints a contributor is most likely to be told to run — the CI build and what the pre-commit hook runs — yet neither had a make target, so the standing rule to use make targets rather than the underlying tool could not be followed for either. It bit reviewers twice, most recently on #32, and it bit hardest for the build: since #30 a bare docker build . fails closed on the CHECK_EPOCH guard, so script/cibuild is one of only three supported ways to build an image and was the only one without a target. The two targets are thin shims in the existing style and change nothing about what the scripts do. .PHONY was already complete and now lists both. README.md's Entrypoints section gained the script-to-target mapping, including the two names that do not match — script/install-precommit is make hooks, and script/precommit is make precommit — plus a note that make cibuild is the slowest target because it is the only one that runs two container builds, while still taking seconds once the shared script/bootstrap layer is cached. The section's pre-existing script/install-precommit bullet, which claimed the installed hook runs script/check, now says script/precommit, which is what the script actually writes into .git/hooks/pre-commit. The stale Future Step asking for post-deploy confirmation of static/_headers is dropped here: it was confirmed live on both hostnames (#14). Verified that make cibuild earns its green rather than replaying a warm cache: one invocation ran both builds for real in sequence, each with its own distinct CHECK_EPOCH, with RUN script/bootstrap CACHED above and no check layer cached below it — the Dockerfile.lint build echoed its epoch and printed hugo's own build table, then the main image build echoed a different epoch, ran script/test for the production build and script/fmt-check for the formatting check. make precommit passes on a clean tree, and make check passes
• 2026-08-10: moved the lint into Docker (#38). A new root Dockerfile.lint runs hugo --minify --printPathWarnings as a build step, so a successful build is a clean lint, and script/lint is nothing but a build of that file — no host path and deliberately no "already inside a container?" branch, which would be a host lint path in disguise. The containerisation boundary is lint only, per the owner ruling of the same day: formatting is not a lint, so script/fmt and script/fmt-check stay on the host. Dockerfile.lint has exactly one stage on purpose. A whole-file docker build -f Dockerfile.lint . builds only the file's last stage, and sibling stages off a shared base have no ordering edge, so any second stage beside the lint would be silently skipped by the invocation the canonical org-wide script/lint uses — a green that linted nothing. With one stage there is nothing to skip and script/lint needs no --target. Its first four instructions are byte-identical to the main Dockerfile's, so the expensive RUN script/bootstrap layer that compiles Hugo from source is shared between the two images rather than paid twice. The recursion this creates was resolved by direction, not detection: make check calls script/lint, so the main Dockerfile can no longer RUN make check — that would attempt a docker build inside a build step, in a bare Alpine with no docker client and no daemon socket. It runs the individual non-lint checks instead, script/test and script/fmt-check, matching the canonical shape upstream, and script/cibuild runs script/lint first for fail-fast feedback before the main image build starts. So CI still covers all three checks and cannot drift from what a developer runs. Caching is waived for the lint exactly as the main Dockerfile already does it: ARG CHECK_EPOCH with no default, guarded with [ -n "$CHECK_EPOCH" ] || exit 1, and the value expanded into the linted command as well as the guard, so invalidation never rests on BuildKit's handling of an unreferenced ARG. Every image-building entrypoint generates and passes it — script/cibuild, script/docker, script/lint — which is the failure mode this repo already hit once, a Dockerfile guard asserting a property one entrypoint did not supply. script/lint builds with --output type=cacheonly: the build is run for its exit status, not for an image, and since the lint layer is cache-busted every run an exporting build would leave one dangling image per lint on a host shared with other work. Verified rather than assumed: two consecutive script/lint runs on an unchanged tree both executed hugo for real (second run 0.85s wall, RUN script/bootstrap CACHED, distinct epochs echoed, real build tables printed); a whole-file docker build -f Dockerfile.lint . with the argument and no --target ran the lint for real, which is the regression test for the skipped-sibling hazard; a bare build with no argument failed closed on the guard; a planted template error failed the lint with hugo's own render error and made script/cibuild exit in 0.6s without the main image build starting at all; a planted over-long line failed the host script/fmt-check with [warn] README.md; both violations were reverted and re-run clean. Not changed here, and still true: the lint fails on hugo build errors but not on render-target collisions, which --printPathWarnings only prints (#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.

• Fix the README's SSH-only clone URL, and add the two entrypoints the Entrypoints section omits, script/precommit and script/projectname (#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 (#28)
• Add a timeout guard to script/test and script/lint so a wedged build fails instead of hanging (#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 (#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 (#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 (#21)
• Delete the stale remote branches feat/initial-site and security-audit; only the owner can remove them (#15)
• 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 (#14)
• Verify the Cloudflare Pages deploy still works after the workflow changes