Epic: Go+HTMX+SQLite production-ready template

[zircote]

Goal

Turn attested-delivery/go-htmx from a governance-only scaffold into a production-ready, reusable Go + HTMX + SQLite template repository, implementing the architecture specified in the research-derived spec go-htmx-sqlite-project-template.ai-architecture-doc.md (9 accepted decisions AD-1…AD-9, 10 EARS NFRs) and the attested-delivery org's central reusable workflows end to end.

Architectural contract (from the seed spec)

• AD-1/AD-2: modernc.org/sqlite (pure Go, CGO-free) default driver; WAL + BEGIN IMMEDIATE + single serialized writer connection as a fixed, non-configurable concurrency contract.
• AD-3: templ default templating (compile-time checked); html/template documented fallback; gomponents documented alternative.
• AD-4: Go 1.22+ stdlib ServeMux default router; chi documented escalation (preserves net/http middleware signatures).
• AD-5: Litestream backup by default; LiteFS / libSQL(Turso) documented opt-in escalations only.
• AD-6: feature-oriented internal/<feature>/ layout; compiler-enforced import boundary.
• AD-7: dual AGENTS.md + CLAUDE.md AI-agent conventions plus checked-in SKILL.md skills targeting mechanical scaffolding work.
• AD-8: test triad — httptest + fresh in-memory SQLite per test + golden-file snapshots (goldie).
• AD-9: go:embed single-binary bundling (templates, static assets, migration SQL) with build-tag dev/prod split.

Delivery shape

• One PR per Story (explicit override of the pipeline's single-PR default), each PR Closes its Story's Tasks.
• Wrapped by a final release/punchlist Story whose PR ships v0.1.0 as a signed, SLSA-attested release, independently verified from a workstation.
• All CI additions consume the org's central reusables (attested-delivery/.github), SHA-pinned; release artifacts follow org naming {name}-{version}-{platform} and the static-artifact attestation path (actions/attest-build-provenance, anchore/sbom-action + actions/attest-sbom, seam-signed gate verdicts, inline fail-closed gh attestation verify). anchore/sbom-action@* is confirmed on the org Actions allow-list (added 2026-07-12).

Build order

1. Story: Application skeleton & toolchain #2 — Story: Application skeleton & toolchain (Task: Go module, cmd/ entrypoint, feature-oriented internal/ layout #11, Task: HTTP layer — ServeMux router + net/http-compatible middleware chain #12, Task: templ integration + go:embed asset bundling with dev/prod build-tag split #13, Task: golangci-lint config, core justfile recipes, SHA-pinned build/lint/test CI #14)
2. Story: Data layer — SQLite concurrency contract, migrations, codegen, durability #3 — Story: Data layer — SQLite concurrency contract, migrations, codegen, durability (Task: SQLite driver + WAL/BEGIN IMMEDIATE/single-writer concurrency contract #15, Task: goose migrations — zero-padded, embedded, run at startup #16, Task: sqlc codegen wired to the migration schema #17, Task: Litestream durability config + LiteFS/libSQL escalation docs #18)
3. Story: HTMX UI & real-time layer (SSE + OOB swaps) with example feature #4 — Story: HTMX UI & real-time layer (SSE + OOB swaps) with example feature (Task: Base layout, vendored htmx, example feature vertical slice #19, Task: SSE endpoint + pub/sub fan-out for server-driven push #20, Task: hx-swap-oob multi-region update patterns over SSE #21)
4. Story: Testing layer — httptest + in-memory SQLite + golden files #5 — Story: Testing layer — httptest + in-memory SQLite + golden files (Task: httptest + in-memory SQLite test helpers #22, Task: goldie golden-file snapshot tests for rendered output #23, Task: Wire test tiers into justfile and CI #24)
5. Story: Template-instantiation experience — minimal just init #6 — Story: Template-instantiation experience — minimal just init (Task: just init — project identity rewrite recipe #25, Task: Identity-placeholder audit + post-copy checklist #26, Task: Template-instantiation smoke check #27)
6. Story: AI-agent conventions — AGENTS.md, CLAUDE.md, checked-in skills #7 — Story: AI-agent conventions — AGENTS.md, CLAUDE.md, checked-in skills (Task: AGENTS.md — boundaries, commands, self-verifying idioms #28, Task: CLAUDE.md pointer strategy — resolve org §10 vs AD-7 #29, Task: Checked-in SKILL.md — add-feature-package scaffolding skill #30)
7. Story: Diátaxis user documentation set #8 — Story: Diátaxis user documentation set (Task: Run /doc-set-planner and reconcile the doc-set plan #31, Task: Tutorial — getting started (copy → just init → first change) #32, Task: How-to guides — feature, migration, SSE region, deploy, escalations #33, Task: Reference — justfile, layout, config, concurrency contract, artifacts #34, Task: Explanation — architecture rationale and decision log #35)
8. Story: Attested release pipeline — provenance, SBOM, seam-signed verdicts, fail-closed verify #9 — Story: Attested release pipeline — provenance, SBOM, seam-signed verdicts, fail-closed verify (Task: Release workflow — cross-platform CGO-free builds, org artifact naming #36, Task: SLSA build provenance + CycloneDX SBOM attestations (static-artifact path) #37, Task: Seam-sign SAST/SCA/IaC gate verdicts at release, digest-bound #38, Task: Fail-closed verify job + SECURITY.md verification instructions #39, Task: Ungate SAST + required-checks update (owner commands) #40)
9. Story: Release & punchlist — wrap, verify, ship v0.1.0 #10 — Story: Release & punchlist — wrap, verify, ship v0.1.0 (Task: Punchlist sweep — README, CHANGELOG, gate-coverage audit, conventions reconcile #41, Task: End-to-end consumer proof on a fresh template copy #42, Task: Tag v0.1.0, publish attested release, verify independently #43)

Sequencing rationale: each Story builds on the previous PR's merged state; #40 (SAST ungate) depends on Go source from #2 existing on main; #10 is the wrap Story the user framed as the "release/punchlist Epic PR".

Board conventions note

The org project #1 board now has a Kind single-select field (added 2026-07-12: Epic / Story / Task / Feature / Bug / Documentation); every issue in this hierarchy carries its Kind on the board. GitHub-native issue types remain Task / Bug / Feature only, so Epic/Story native typing still degrades to Feature — the MIF frontmatter and the board Kind field are the authoritative typing.

References

• Seed spec: research-harness/reports/go-htmx-sqlite-project-template/go-htmx-sqlite-project-template.ai-architecture-doc.md
• Org governance: attested-delivery CLAUDE.md §1 (invariants), §3 (central reusables), §5 (gates/predicates), §6 (release standards)
• Milestone: v0.1.0 — production-ready template (milestone 1)

[zircote]

Planning complete (plan-only run): decomposed the go-htmx-sqlite architecture spec into this Epic → 9 Stories (#2–#10) → 33 Tasks (#11–#43), all linked as native sub-issues, milestone-assigned to v0.1.0 (milestone 1), and on the org board at Backlog (set by the board's auto-add workflow). Build order is in the Epic body. Execution has not started — awaiting go-ahead; delivery shape is one PR per Story, wrapped by the release/punchlist Story #10.

[zircote]

Board metadata backfill: created the missing Kind field on org project #1 (Epic/Story/Task/Feature/Bug/Documentation) and stamped it across this hierarchy — #1 = Epic, #2–#10 = Story, #11–#43 = Task. Statuses untouched (still Backlog). Epic body's board-conventions note updated accordingly. Also recorded: anchore/sbom-action@* is now allow-listed (see #37).

[zircote]

Story #2 (Application skeleton & toolchain) merged via #44. Starting Story #3 (Data layer) next, per the build order.

[zircote]

Story #4 (HTMX UI & real-time layer) merged via #46. Starting Story #5 (Testing layer) next, per the build order.