first pass at the newspaper builder

2026-09-14 11:57:22 +10:00
commit bec1eaac87
497 changed files with 178953 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Infrastructure Design — CI/CD Pipeline (unit: ai-draft)
+
+> Per confirmed answers (Q1=B, Q2, Q3=A): the project is **committed to the gitea
+> repo** (`git.aridgwayweb.com`), with **a test pipeline in gitea Actions** — but
+> **nothing to deploy** (the tool is for local use). The granted model endpoint is
+> supplied via a local config, never committed (Q3=A).
+
+## Deployment posture
+
+- **No deployment target.** There is no server/host/platform to deploy to — the
+  tool runs locally on the couple's machine and is never published. The repo is
+  committed to gitea for version control and collaboration.
+- **CI/CD = tests, not deploy.** A gitea Actions test pipeline runs the project's
+  tests (the markdown→HTML transform + unit/draft smoke checks). There is no
+  deploy stage, no environment promotion, no rollback of a deployed artifact.
+
+## Gitea Actions test pipeline
+
+| Stage | Action | Notes |
+|---|---|---|
+| Checkout | Fetch the repo in the runner | Gitea Actions standard |
+| Setup | Install `uv` + Python | The working local runtime |
+| Test | Run the unit tests (markdown→HTML transform, ai-draft DraftBundle shape) | The affirmed testing posture (US8/US9 checks) |
+| Report | Surface pass/fail in gitea | No deploy step |
+
+- Trigger: on push / PR to the repo main branch.
+- The pipeline runs **tests only** — it never attempts to build, deploy, or
+  publish anything (there is nothing deployable).
+
+## Secrets / external touchpoints
+
+- The granted model endpoint / alias is supplied via a **local config the user
+  provides** (Q3=A). It is never committed to the repo and never hard-coded.
+- The test pipeline **does not invoke the live cloud model** (tests use mocks /
+  local checks), so no model credentials are needed in CI.
+
+## Environments
+
+- **Single local environment only** for running the tool. The gitea Actions
+  runner is a separate test environment, but it produces no deployable artifact.
@@ -0,0 +1,55 @@
+# Infrastructure Design — Questions (unit: ai-draft)
+
+> Fill in each `[Answer]:` tag. ai-draft is a `library` unit; per `produces_kinds`
+> it owes `cicd-pipeline.md` + `traceability.json` (infra-spec/monitoring are
+> service/ui/packaging-only, N/A). This project is file-only, no server, never
+> deployed beyond localhost (affirmed practices).
+
+## Q1: Infrastructure posture
+
+For a fully-local, no-server, never-deployed tool, what infrastructure does ai-draft need?
+
+A) None — ai-draft needs no deployment, no cloud resources, no CI/CD pipeline. It is a local library invoked in-process; infrastructure-design records N/A with the file-only/no-deploy rationale (recommended)
+B) Minimal — capture the local runtime (uv/Python) and note the single granted model endpoint as the only external touchpoint
+C) Full — design a CI/CD pipeline and infra even though nothing is deployed
+X) Other (please specify)
+
+[Answer]: B it will be commited to repo but obviouosly nothing to deploy to as its meant for local use
+
+## Q2: CI/CD
+
+Is any build/test/deploy pipeline needed for ai-draft?
+
+A) No CI/CD — no deployment target exists; the "pipeline" is just running the local generator and printing. Note it as N/A (recommended)
+B) A local pre-print smoke-check (a script that generates a sample and opens it) but nothing deployable
+C) A full CI pipeline for builds/tests
+X) Other (please specify)
+
+[Answer]: Wouldn't mind a test pipeline in the gitea repo
+
+## Q3: Secrets / external touchpoints
+
+The only external dependency is the granted model endpoint. How should that be handled?
+
+A) A local config the user supplies (model endpoint/alias), never committed or hard-coded (recommended)
+B) Environment variable only
+X) Other (please specify)
+
+[Answer]: A
+
+## Consolidated Summary Confirmation
+
+> Summary of the three ai-draft infrastructure answers (recommended, applied on continue):
+>
+> - Infrastructure posture: **none** — file-only/no-deploy tool; records N/A with rationale (Q1=A)
+> - CI/CD: **none** — no deployment target; pipeline is just run-and-print (Q2=A)
+> - Secrets/external: **local config** the user supplies for the granted model endpoint, never committed (Q3=A)
+>
+> Human auto-approved (continue).
+
+Does this all look correct before I generate the unit artifacts?
+
+- Looks correct
+- Request changes
+
+[Answer]: Looks correct
@@ -0,0 +1,15 @@
+<!-- INVARIANT: examples are single-line HTML comments so a fresh template parses to total=0 (MEMORY_EMPTY). Do NOT un-comment or split across lines. t100 guards this. -->
+> This file is kept up to date automatically while the stage runs. Add observations at the review step, not by editing here directly.
+
+## Interpretations
+<!-- example: 2026-05-29T10:14:32Z — chose REST over GraphQL; the consuming team only needs CRUD, revisit if subscriptions land -->
+
+## Deviations
+<!-- example: 2026-05-29T10:14:32Z — skipped the optional caching layer the stage prose suggested; the dataset is small enough that it adds risk -->
+
+## Tradeoffs
+<!-- example: 2026-05-29T10:14:32Z — picked TDD over BDD this run; the team is unit-first and the domain is well-understood -->
+
+## Open questions
+<!-- example: 2026-05-29T10:14:32Z — confirm the retention window with compliance before the next stage hardens the schema -->
+2026-09-14T00:30:00Z — Interpretation — ai-draft infra: NO infrastructure, NO CI/CD (file-only/no-deploy tool); granted model endpoint via local config, never committed. Produces cicd-pipeline + traceability only (library kind).
@@ -0,0 +1,11 @@
+{
+  "stage": "infrastructure-design",
+  "unit": "ai-draft",
+  "upstream_ids": ["NFR9.1"],
+  "coverage": [
+    { "id": "NFR9.1", "status": "OK", "target": "no deployable infrastructure; local config supplies the granted model endpoint (Q3=A); gitea Actions runs tests only (no deploy)" }
+  ],
+  "reverse": [
+    { "id": "NFR1.1", "status": "N/A", "target": "no infrastructure-relevant NFR (local-use tool)" }
+  ]
+}