write-supplemental

## What's new in v1.2 (2026-05-24, S233 pipeline.33) **Step 3.4 envelope-wrap discipline + format-contract inline + Step 2 brief pre-extraction.** v1.1 deferred all format-shape detail to [[../../../docs/EDITION_PIPELINE]] §Published .txt Format Contract; the S231 C94 `let_walks_reset` supplemental run surfaced three structural failure modes when Mags-during-compile re-interpreted that pointer: - **G-S5 silent-zero on NAMES INDEX + BUSINESSES NAMED** — Step 3.4 .txt compile output used markdown-table syntax (`| POPID | Name | Role |` with header + `|---|---|` separator) for NAMES INDEX and dash-list for BUSINESSES NAMED. Parser `scripts/ingestEditionWiki.js:294` requires strict pipe-format with first field matching `/^[A-Z]+-[A-Z0-9]+$/`; markdown-table form parses to 0 entities silently. Source-of-mis-training: `editions/SUPPLEMENTAL_TEMPLATE.md` v2.0 used markdown-table syntax on ARTICLE TABLE which Mags then patterned across the parser-strict sections. - **G-S4 compile re-introduced engine-language** — Step 3.4 free-form rewrite of agent .md content transformed Hal's `"this cycle"` cross-reference into `"Edition 94"` (Hal's source agent had complied with the prior rule; compile broke compliance). Note: governance.15 S233 carved out edition-number cross-references in editorial chrome contexts (See also / byline / sidebar) — so the specific G-S4 trigger is partially mooted, but the deeper principle stays: Step 3.4 is envelope-wrap, not editorial-pass. - **G-S3 brief asked agent to grep inside full edition .txt** for a specific prior article — search inside 40KB file for one section when pre-extraction to a single file would be cleaner. **What changed:** - **Step 2 brief pre-extraction (G-S3)** — one sentence added: when brief references a specific prior article for the agent to read, pre-extract it to `output/reporters/<reporter>/articles/<source-cycle>_<slug>.md` and reference that path in the brief rather than directing the agent to grep inside the full edition .txt. - **Step 3 small guardrail (G-S4 deeper principle)** — added clarifying clause: compile preserves agent-written prose verbatim where it satisfies canon-rules; quality checks (deck lines, photo credits, name verification, opinion markers) are validation operations, not rewrite operations. - **Step 3.4 FORMAT CONTRACT inline (G-S5)** — explicit line-shape exemplars for NAMES INDEX (`POP-NNNNN | Full Name | Role/Title`) + BUSINESSES NAMED (`BIZ-NNNNN | Name | Sector | Neighborhood`); explicit warning against markdown-table syntax (silent-zero pattern); §What Step 3.4 IS / IS NOT framing (envelope-wrap not editorial-pass); verification gate citing expected ingestEditionWiki.js entity count > 0. - **`editions/SUPPLEMENTAL_TEMPLATE.md` v2.0 → v2.1 (G-S5 root cause fix)** — added §NAMES INDEX + §BUSINESSES NAMED sections in strict pipe-format mirroring `docs/media/EDITION_FORMAT_TEMPLATE.txt` canonical exemplar; reformatted §Article Table from markdown-table to flat strict pipe so all three intake sections share consistent shape; ADR-0006 Contract A pattern notes inline. **Cross-link:** engine.26 follow-up filed for parser defensive-emit (warning when standalone BUSINESSES NAMED section has non-empty content but parser extracts 0 — same defensive-emit shape engine.24 added to NAMES INDEX S229 — fail-loud rather than silent-zero). **Out of scope (deferred):** mechanical assembly script for Step 3.4 (operator-driven discipline holds for now via FORMAT CONTRACT inline + template alignment; mechanical guard files if format-contract violations recur). **Source:** `output/production_log_supplemental_c94_let_walks_reset_gaps.md` (entries G-S3 + G-S4 + G-S5). --- # /write-supplemental — Supplemental Edition Production ## Usage `/write-supplemental [topic]` - Produces a supplemental edition on any topic - Mags picks the reporters, designs the coverage, compiles the result - One supplemental per cycle minimum — this is how the city gets built ## Live Status (auto-injected) **Supplemental triggers:** ``` !`cat output/supplemental-triggers/triggers_c*.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'{len(d)} triggers available'); [print(f' - {t.get(\"topic\",\"?\")} ({t.get(\"type\",\"?\")})') for t in d[:5]]" 2>/dev/null || echo "No triggers file — pick a topic or run checkSupplementalTriggers.js"` ``` **Recent supplementals:** ``` !`ls -1t editions/*supplemental* 2>/dev/null | head -3 || echo "No supplementals yet"` ``` ## Philosophy The Cycle Pulse is the engine's newspaper — it reports what the simulation produced. Supplementals are where the world gets built. A restaurant review canonizes a restaurant. A neighborhood walk canonizes what that neighborhood feels like. A sports deep dive gives the dynasty texture beyond box scores. Every supplemental adds something to the world that the Cycle Pulse can't. **Supplementals reflect the current state of the world.** Read the world summary (`output/world_summary_c{XX}.md`) before writing anything. If there's a health crisis in West Oakland, a food piece set there feels it. If the A's are 7-1, a Jack London walk has fans in jerseys. If Rosh Hashanah is happening across three neighborhoods, a culture piece acknowledges it. The supplemental lives in the same city as the edition — same weather, same nightlife, same mood. Different angle, same world. **Any reporter can lead a supplemental.** Not just Carmen and Jordan. There are 24 journalists on the roster and most of them have never gotten a supplemental assignment. Mason Ortega is a former sous chef — give him a food piece. Sharon Okafor covers lifestyle — let her cover lifestyle. Kai Marston was a music blogger — give him First Fridays. The voice files are built for this. Use them. **The tone is not locked to civic drama.** Supplementals can be breaking news, but they can also be a farmers market, a restaurant opening, a neighborhood walk, a sports feature, a weather story, a school profile. The city should feel like a city, not a council chamber. **GodWorld is a prosperity city.** Dynasty-era Oakland. People buying homes, opening businesses, enjoying life. Not every story is displacement, struggle, or crisis. Include wealth, aspiration, joy, normalcy. ## Rules - Show the user a coverage plan before launching agents - Get user approval before proceeding to agent launch - One story, many angles — or one story, one angle. Size fits the topic. - Rotate reporters. Check who's been used recently and who hasn't. - **Every name gets verified via MCP.** `lookup_citizen(name)` for citizens. `get_roster("as")` for A's players (contracts, quirks, positions — reads truesource). `search_canon(name)` for what's been published. No exceptions. - **Read criteria files.** `docs/media/story_evaluation.md` for story quality, `docs/media/brief_template.md` for brief structure, `docs/media/citizen_selection.md` for citizen handling. Same standards as sift — supplementals are editions too. - **No calendar dates.** Cycles only. - **World summary is your context.** Read `output/world_summary_c{XX}.md` for cycle texture — food, nightlife, famous people, weather, events. - **Photos, PDF, print — that's `/edition-print`.** Not part of this skill. - **Memory Fence (Phase 40.6 Layer 2).** Reporter briefs carry recalled canon from `search_canon` and world-data queries. Wrap those excerpts via `require('/root/GodWorld/lib/memoryFence').wrap(text, 'bay-tribune')` before embedding them in the brief. Full convention: [[SUPERMEMORY]] §Memory Fence. --- ## Step 0: Production Log Read the existing unified production log: `output/production_log_c{XX}.md` (legacy fallback `production_log_edition_c{XX}.md` if absent). This is the one-true-cycle source write-edition + city-hall both use — all of the cycle's work (civic + edition + supplemental) lives in one document. If the edition has already been produced, the log exists and has Steps 0-9 filled in. Append a new section: ```markdown ## Supplemental: {topic} **Started:** {timestamp} **Topic:** {topic} **Reporters:** {who's assigned} **Status:** IN PROGRESS ### Coverage Plan [filled in at Step 1] ### Agent Results [filled in at Step 2] ### Compile + Publish [filled in at Steps 3-5] ``` If no production log exists yet (supplemental running before edition), create the log using the write-edition template and start with the supplemental section. ## Step 0.5: Pick the Topic Topics come from anywhere: 1. **User drops it** — "let's do a food piece" or "what's Temescal look like?" 2. **Trigger list** — check `output/supplemental-triggers/triggers_c{XX}.json` for auto-detected candidates (run `node scripts/checkSupplementalTriggers.js {cycle}` if it doesn't exist yet) 3. **Engine signal** — a citizen event, a new business, a neighborhood shift 4. **Editorial instinct** — Mags sees a gap in the world and fills it 5. **Journalist flag** — a reporter's voice suggests a feature 6. **Variety check** — if the last 3 supplementals were civic, do something else Read whatever the user provides. If it's vague, that's fine — "what's the food scene like?" is a valid topic. ### Civic Supplemental Types (from triggers) When the trigger list suggests civic content, use one of these formats: | Type | What | Who Produces | Format | |------|------|-------------|--------| | **Civic Dispatch** | Official city communications — press releases, public notices, community alerts | Carmen Delaine + voice agent statements | In-world government output, not journalism. 1-3 short pieces. | | **Neighborhood Report** | What life looks like in one neighborhood this cycle. Businesses, events, people, weather. | Maria Keen + culture desk reporters | World-texture, not news coverage. Walk-through format. | | **Initiative Spotlight** | Deep dive on one initiative's progress. What happened, what's next, who's affected. | Carmen Delaine or Jordan Velez + civic desk | Feature-length, single-subject, investigative. | These follow the same Step 1-5 pipeline as any supplemental — they just have a civic angle and draw from voice agent statements as source material. **Note:** Supplementals do **not** use `buildDecisionQueue`, `buildInitiativePackets`, `buildInitiativeWorkspaces`, or `applyTrackerUpdates`. Those pipelines are Cycle Pulse only. Civic supplementals can reference voice agent **output** from previous cycles as source material (e.g., mayor statements), but supplementals don't generate new voice decisions or advance initiative state. ## Step 1: Design the Coverage Plan ### 1a. Pick the Reporters **Check the roster first.** Who hasn't had a supplemental? Who's perfect for this topic? The full roster is in `docs/media/voices/` — 24 journalists across every beat. Reporters by specialty (not exhaustive — anyone can cover anything): | Reporter | Specialty | Good For | |----------|-----------|----------| | Mason Ortega | Food & Hospitality | Restaurants, food culture, kitchen life, nightlife | | Sharon Okafor | Lifestyle | Daily routines, behavior trends, how people live | | Kai Marston | Arts & Entertainment | Galleries, music, First Fridays, cultural events | | Angela Reyes | Education | Schools, youth, packet-supplied school systems, after-school programs | | Noah Tan | Weather & Environment | Climate, air quality, seasons, outdoor life | | Dr. Lila Mezran | Health | Public health, clinics, medical stories | | Sgt. Rachel Torres | Public Safety | Crime, safety, OPD, neighborhood security | | Jax Caldera | Accountability | Street-level pressure, policy gaps | | Maria Keen | Neighborhoods | Hyper-local culture, community pulse | | Simon Leary | Long View | Essays, philosophy, contemplative pieces | | Tanya Cruz | Sideline / Social | Behind-the-scenes, real-time dispatches | | Selena Grant | Oaks Beat | Oaks roster construction, player development, front office | | Talia Finch | Oaks Ground | The Oaks from the street — bars, platforms, the deciding fan | | MintConditionOakTown | Internet/Rumors | Speculative threads, chaotic truth-seeking | | Carmen Delaine | Civic | Government, infrastructure, policy | | Jordan Velez | Business/Labor | Economics, workforce, port, development | | Luis Navarro | Investigations | Accountability, fact-checking, anomalies | | Celeste Tran | Social Trends | Hashtags, streaming data, cultural temperature | | Farrah Del Rio | Opinion | Policy critique, cultural commentary | | Trevor Shimizu | Infrastructure | Transit, utilities, systems | | P Slayer | Fan Voice | Sports opinion, emotional takes | | Anthony | Sports Analytics | Data-driven sports, roster breakdowns | | Hal Richmond | Sports History | Dynasty context, retrospectives | | Reed Thompson | Wire | Neutral verification, quick reports | ### 1b. Match the Roster **Design the stories first, then match reporters.** Don't pick reporters by habit — pick them by beat fit. For each story, ask: who on the 24-person roster is the natural match for this angle? **Supplementals develop the bench.** Default to reporters with fewer than 5 edition appearances. The Cycle Pulse is the big stage for trusted voices. Supplementals build the next ones. Check the reporter table above. If you're about to assign Carmen, Jordan, Maria, or P Slayer — stop and ask if someone else fits better. #### Engine B byline pool (T4.3) When the supplemental originates from a `Story_Seed_Deck` seed (e.g., a `storyline-followup` carrying a `BylineCandidate` per Engine B), **the candidate is valid even if the byline is not on the edition's 9-reporter front-page table.** Engine B scores against the full 25-byline `rosterLookup.js` pool — Simon Leary, Hal Richmond, Sharon Okafor, Trevor Shimizu, Mason Ortega, Angela Reyes, Kai Marston, Talia Finch, Selena Grant, etc. — and `formatFitScore_('<journalist>', 'supplemental')` ranks long-view + deep-dive bylines highest on the supplemental format. The edition's 9-reporter constraint is a CYCLE-PULSE concern, not a supplemental concern. For supplemental work: - Engine B's `bylineCandidate` from the supplemental's source seed is the default suggestion - The full 25-byline pool is in scope; nothing about supplementals constrains to the front-page 9 - Editorial latitude is unchanged — Mags can override the Engine B candidate per the "design stories first, then match reporters" principle above - "Develop the bench" rule still applies; Engine B's format-fit table actively biases toward the supplemental archetype (Hal/Simon/Sharon/Mags = 4-fit), which aligns with the bench-development goal **Lookup:** if running supplemental against a specific seed, read the deck's `BylineCandidate` value for that seed — **resolve the column by header name from row 0, never by a fixed letter** (the v4 deck migration reordered/renamed columns; positional reads silently break — same fix as `/sift` v2.2). `BylineCandidate` is a shadow Engine-B append: absent until Engine-A/B ships, so when the header is missing, fall through to the existing "design first, match second" workflow (that fallback is the default state right now). ### 1c. Plan the Coverage Show the user something like: ``` SUPPLEMENTAL: [TOPIC] COVERAGE PLAN: 1. Mason Ortega — [assignment, ~word count] 2. Maria Keen — [assignment, ~word count] 3. [Reporter] — [assignment, ~word count] Team: [N] reporters, [N] articles ``` Keep it simple. The plan is a pitch, not a contract. Get user approval before proceeding. ### 1d. Size It Right Not everything needs 7 articles and 10,000 words. | Size | Articles | Words | When | |------|----------|-------|------| | Light | 1-2 | 1,500-3,000 | Neighborhood walk, single-topic color | | Standard | 3-5 | 3,000-6,000 | Multi-angle feature, event coverage | | Heavy | 5-8 | 5,000-10,000 | Breaking news, deep dive, major event | A farmers market piece might be one article from Mason Ortega and one from Maria Keen. That's fine. Not everything is a five-reporter production. --- ## Step 1.5: Write the Topic Brief The brief tells the reporters what they need to know. Save to: ``` output/supplemental-briefs/{topic_slug}_c{XX}_brief.md ``` ### For color/variety pieces (lightweight brief): - **The topic** — What are we covering? - **Citizens available** — Pull from the ledger. Include citizens who live in the relevant neighborhood, work in the relevant industry, etc. Don't just use the usual names. - **Canon to establish** — What new things does this piece create? (businesses, venues, cultural events, neighborhood texture) - **Voice assignments** — Who writes what ### For news/investigative pieces (heavier brief): - Add: **The news** (what happened), **The context** (timeline, stakes), **Civic voice statements** (if relevant) - Add: **Archive context** from Supermemory or NEWSROOM_MEMORY.md ### Brief sources (check in order): 1. User-provided content 2. World summary — `output/world_summary_c{XX}.md` — cycle texture, events, food, nightlife, famous people 3. Bay-tribune canon — `search_canon("TOPIC")` via MCP — published history 4. World-data citizens — `lookup_citizen(name)` via MCP for each candidate 5. World-data domain cards (when supplemental is sector-focused) — `lookup_business` / `lookup_faith_org` / `lookup_cultural` / `get_neighborhood_state` via MCP. Full inventory: [[../../../docs/SUPERMEMORY|SUPERMEMORY]] §Search/save matrix. 6. Simulation_Ledger — direct sheet query via service account for neighborhood-based candidates 7. NEWSROOM_MEMORY.md — errata, character continuity, active arcs ### Enhanced data sources (use if available): All of these are optional. If none exist, the brief works exactly as today. Check each path — if the file exists, add the corresponding section to the brief.