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,42 @@
+# Delivery Planning — Bolt Plan
+
+> Construction sequence for the wedding newspaper generator, per confirmed
+> answers (Q1=A value-core first, Q2=A no formal score, Q3=A one unit per Bolt,
+> Q4=B parallel ai-draft + funnies, Q5=A no external blockers). A **Bolt** is
+> one build pass over a piece of the work, ending in something that runs.
+> Topology is from Units Generation (2.7); this stage chooses the economic
+> path through it. Walking skeleton is skipped per affirmed team practice.
+
+## Bolt sequence
+
+| Bolt | Units | Notes / walking-skeleton | Definition of Done | Confidence hypothesis | Expected demo |
+|---|---|---|---|---|---|
+| Bolt 1 | `generator` (core) | Value core first (Q1=A): CLI, content parse, masthead, layout, emit. Simple content, works end-to-end early. | `newspaper generate <simple content>` emits a self-contained `newspaper.html` that prints to A4 with correct masthead + columns | The core render pipeline hangs together and the paper prints end-to-end with hand-written content | A one-page sample newspaper from simple markdown |
+| Bolt 2a | `ai-draft` | Parallel (Q4=B) with Bolt 2b — independent of funnies. | `--draft` calls the granted model and returns a DraftBundle review set | The AI drafting loop (cloud model + per-article DraftBundle) works and stays reviewable | A drafted article set ready for per-article review |
+| Bolt 2b | `funnies` | Parallel (Q4=B) with Bolt 2a — independent of ai-draft. | `funnies` builds crossword + find-a-word from content and embeds/selects a cartoon; falls back when none found | Content-derived puzzles + cartoon are produceable and A4-printable | A crossword, a find-a-word, and a selected cartoon block |
+| Bolt 3 | `generator` integration | Fold in ai-draft + funnies; add per-article review page + photo embedding. | Full newspaper: AI draft → per-article review → funnies section → photos → multi-page A4 print | The whole chain works end-to-end with all sections and the review handoff | A full multi-page newspaper with funnies, photos, AI drafts, reviewed |
+
+## Why this order (summary)
+
+- **Bolt 1 first** = value core / end-to-end early (Q1=A): the highest-confidence,
+  central capability lands first, matching the affirmed "no separate walking
+  skeleton" (the first Bolt is naturally a thin end-to-end slice anyway).
+- **Bolts 2a/2b parallel** = the independent, higher-unknown pair (funnies and AI
+  drafting — the user's stated worries, Q6=B,C) after the core works, so they
+  can be built and de-risked concurrently.
+- **Bolt 3 last** = integration: wire the funnies + AI review into the core and
+  polish multi-page fidelity. Tackles the print-fidelity worry (Q6=A) as the
+  finish pass.
+
+## Confidence hypotheses (per Bolt)
+
+- Bolt 1: "The core render pipeline produces a correct, A4-printable paper from
+  hand-written markdown."
+- Bolt 2a: "The AI draft produces acceptable wedding-appropriate copy and the
+  per-article DraftBundle is reviewable off file://."
+- Bolt 2b: "Content-derived crosswords/find-a-words and a selected cartoon print
+  correctly on A4 with a graceful fallback."
+- Bolt 3: "The full newspaper — AI drafts, review, funnies, photos, multi-page
+  print — works end-to-end with all sections."
+
+<!-- delivery-planning-after-confirm -->
@@ -0,0 +1,90 @@
+# Delivery Planning — Questions
+
+> Fill in each `[Answer]:` tag. Options A-E plus X (Other). The file is the
+> authoritative record of your construction-sequencing decisions.
+
+## Q1: Build-first strategy
+
+We have three units of work: `generator` (the CLI + layout + emit, which depends on the other two), `ai-draft` (optional local/cloud Ollama drafting), and `funnies` (crossword/find-a-word/cartoon). What should we build first?
+
+A) The value core first — `generator` layout/render/emit first (with simple content), then add `ai-draft` and `funnies` later; the paper works end-to-end early (recommended given we skip the separate walking skeleton)
+B) The risky parts first — `ai-draft` and `funnies` first (they have the most unknowns: Ollama/cloud model, cartoon search, puzzle generation), then wire them into `generator`
+C) The dependencies first — build `ai-draft` and `funnies` first (topologically), then `generator` last
+D) A thin end-to-end slice first — one markdown file → one A4 page proving the whole chain, despite practices saying we skip a formal walking skeleton
+X) Other (please specify)
+
+[Answer]: A
+
+## Q2: Scoring the work
+
+Should we rank the build with a formal scoring model (value + urgency against size — WSJF-style: higher score ships first)?
+
+A) No formal score — order by a pragmatic mix we decide in the plan (value core first, then the riskier funnies/AI), simplest for a solo local tool (recommended)
+B) Yes — a WSJF-style score per unit (weighted: value, risk-reduction, size) so the sequence is evidence-based
+X) Other (please specify)
+
+[Answer]: A
+
+## Q3: Bolt size
+
+How should we bundle the work into Bolts (a Bolt is one build pass over a piece of the work, ending in something that runs)?
+
+A) One unit per Bolt — three Bolts (`generator`, `ai-draft`, `funnies`), each independently built and reviewed (recommended)
+B) Fewer, larger Bolts — e.g. bundle all three into a couple of passes
+C) Thin slices cutting across units (e.g. a minimal crossword in the first pass)
+X) Other (please specify)
+
+[Answer]: A
+
+## Q4: Concurrency
+
+Can several Bolts be built at the same time, or one after another?
+
+A) One at a time, reviewed as we go (single-session, you approve each — recommended)
+B) Parallel — build `ai-draft` and `funnies` concurrently (they're independent), then `generator` integrates them
+X) Other (please specify)
+
+[Answer]: B
+
+## Q5: External blockers
+
+Is anything outside the team going to hold us up (external APIs, data waiting on someone, approvals, another hand-off)?
+
+A) No blockers — the Ollama/cloud model and the internet content-enrichment are things the generator itself calls; we control the timeline (recommended)
+B) Yes — there are external dependencies (e.g. specific photos, a particular cartoon license, awaiting content from someone) that could gate a Bolt
+X) Other (please specify)
+
+[Answer]: A
+
+## Q6: Biggest worry
+
+What worries you most about this build, so we tackle it early?
+
+A) Print fidelity — getting the broadsheet look, columns, and clean A4 page breaks right (the highest-value surface)
+B) The funnies — crossword/puzzle generation from content and the cartoon search are the most unpredictable
+C) The AI drafting quality — whether the model produces copy that feels right for the wedding
+D) The review handoff — making the per-article review page reliable under the file:// no-server constraint
+E) Nothing specific — the scope is clear enough
+X) Other (please specify)
+
+[Answer]: B, C, D
+
+## Consolidated Summary Confirmation
+
+> Summary of your six delivery-planning answers before the construction Bolt plan is generated:
+>
+> - Build-first strategy: **value core first** — the `generator` layout/render/emit first with simple content, then `ai-draft` and `funnies` added later; the paper works end-to-end early (Q1=A)
+> - Scoring: **no formal score** — a pragmatic mix we decide in the plan (Q2=A)
+> - Bolt size: **one unit per Bolt** — three Bolts (`generator`, `ai-draft`, `funnies`), each independently built and reviewed (Q3=A)
+> - Concurrency: **parallel** — `ai-draft` and `funnies` built concurrently (they're independent), then `generator` integrates them (Q4=B)
+> - External blockers: **none** — we control the timeline (Q5=A)
+> - Biggest worries (tackle early): **funnies unpredictability, AI drafting quality, review-handoff reliability** (Q6=B,C,D)
+>
+> Human pre-approved this summary (answers read from the file; explicit permission granted to auto-approve).
+
+Does this all look correct before I generate the Bolt plan artifacts?
+
+- Looks correct
+- Request changes
+
+[Answer]: Looks correct
@@ -0,0 +1,22 @@
+# Delivery Planning — External Dependency Map
+
+> Anything outside the team that could gate a Bolt. Per Q5=A, **no external
+> blockers** — we control the timeline.
+
+## Dependency map
+
+| Bolt | External dependency | Owner | Lead time | Slip handling |
+|---|---|---|---|---|
+| Bolt 2a (`ai-draft`) | The granted AI model (`deepseek-v4-flash:cloud`), called by the generator | The tool itself (sanctioned cloud call, human-approved) | Instant (on demand) | If model unreachable: `ai-draft` returns a clear no-draft result; the paper builds without AI (graceful failure per Q4/A in contracts). Slip does not gate the core. |
+| Bolt 2b (`funnies`) | Internet content-enrichment (cartoon search / comic source), a build-time fetch allowed by human ruling | The tool itself | Instant (on demand) | If no suitable cartoon found: tasteful content-derived placeholder, never a remote dependency at print (NFR4). Does not gate the build. |
+
+## Notes
+
+- No approvals, no people, no data windows, and no other teams gate any Bolt.
+- The two "external" touchpoints are both things the generator itself calls at
+  **generation time** and both degrade gracefully, so they are **not** blocking
+  dependencies — consistent with Q5=A.
+- Photos (US4) are user-supplied inputs; if absent the layout renders without
+  them (FR7.4), so they don't gate the build either.
+
+## (effectively empty — fully AI/self-contained)
@@ -0,0 +1,16 @@
+<!-- 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-13T12:40:00Z — Interpretation — Confirmed sequencing: value core (generator) first, then parallel ai-draft+funnies, then integration. No formal WSJF. No external blockers. Worries: funnies, AI quality, review-handoff.
+2026-09-13T12:40:00Z — Tradeoff — Bolt order deviates from strict 2.7 topology: generator (which topologically depends on the other two) ships first per Q1=A value-core; captured in risk-and-sequencing-rationale.
@@ -0,0 +1,54 @@
+# Delivery Planning — Risk & Sequencing Rationale
+
+> The why behind the Bolt order. **Bolt** is one build pass over a piece of the
+> work, ending in something that runs. The economic order chosen here is: value
+> core first, then the higher-unknown parallel pair, then integration.
+
+## Sequencing argument
+
+The chosen order balances **early working software** (Q1=A) with **de-risking the
+uncertain parts early** (Q6=B,C,D — the user's worries: funnies unpredictability,
+AI drafting quality, review-handoff reliability).
+
+- **Bolt 1 — `generator` core first (value/skeleton case).** Builds the central,
+  highest-confidence capability: CLI → content → layout → emit → A4 print. The
+  paper works end-to-end with hand-written content early, so the highest-value
+  surface (the printable broadsheet) is proven before the exotic parts land.
+  This also naturally satisfies the affirmed "no separate walking skeleton": the
+  first Bolt IS a thin end-to-end slice (markdown in → A4 page out) without
+  calling it one.
+- **Bolts 2a/2b — `ai-draft` and `funnies` in parallel (risk-reduction).** The
+  two most unpredictable units — AI copy quality and content-derived puzzle/
+  cartoon generation — are independent, so they build concurrently (Q4=B). Both
+  de-risk the user's stated worries (Q6=B,C) before integration. Each is also
+  independently testable (DraftBundle contract; puzzle+cartoon output).
+- **Bolt 3 — integration last.** Wires the two new units into the core and
+  completes the full-chain fidelity (multi-page print, photo embed, per-article
+  review handoff). The review-handoff reliability worry (Q6=D) is addressed here
+  against the file:// no-server constraint.
+
+## Reference heuristic
+
+No formal WSJF score (Q2=A). The order follows a pragmatic mix:
+**value-first + risk-reduction + dependency-aware**. It is coherent with
+Reinertsen's CD3-style reasoning (deliver value early while sequencing the high
+uncertainty soon enough to learn from it), but we did not compute a numeric score.
+
+## Deviation-from-topology note
+
+The Bolt order **does not strictly follow 2.7's topological order**. Topology
+says `generator` depends on `ai-draft` and `funnies`; a strict topological walk
+would build ai-draft + funnies first. We deviate deliberately: **Bolt 1 builds
+`generator` with simple/sample content first** (no ai-draft/funnies needed for
+the core hand-written path), then the independent pair in parallel (Bolt 2a/2b),
+then integration (Bolt 3). This is justified by Q1=A (value core early) and the
+parallelism in Q4=B. The deviation is captured here as the stage requires.
+
+## Rationale
+
+| Bolt | Rationale |
+|---|---|
+| Bolt 1 | Value core, highest confidence, end-to-end early |
+| Bolt 2a | Independent + user worry (AI quality/drafting) — de-risk |
+| Bolt 2b | Independent + user worry (funnies) — de-risk |
+| Bolt 3 | Integration + full fidelity (incl. print-fidelity worry Q6=A) |
@@ -0,0 +1,29 @@
+# Delivery Planning — Team Allocation
+
+> Which team/mob owns which Bolt. A **mob** is a small team owning a Bolt's
+> delivery. Per affirmed team practice, this is a solo local project.
+
+## Allocation
+
+This project is a solo local tool (classic scope — the team-formation stage was
+skipped). **All Bolts are executed by the single developer agent**
+(`aidlc-developer-agent`), in this session, with you approving as each Bolt
+completes.
+
+| Bolt | Owner | Notes |
+|---|---|---|
+| Bolt 1 (`generator` core) | aidlc-developer-agent | build + verify + present |
+| Bolt 2a (`ai-draft`) | aidlc-developer-agent | build + verify + present |
+| Bolt 2b (`funnies`) | aidlc-developer-agent | build + verify + present |
+| Bolt 3 (integration) | aidlc-developer-agent | build + verify + present |
+
+## Program Board note
+
+Single-team (a solo developer), so there is no Program Board — no
+cross-team sequencing or hand-off coordination is required. The Bolt plan's
+parallelism (2a/2b) is scheduling, not separate teams.
+
+## Approval rhythm
+
+One approval per Bolt, one at a time as they complete (per Q4=A's "reviewed as we
+go" for the core, with 2a/2b built in parallel and each reviewed on return).