3yearplan/outputs/longform-spec.md

# Longform Spec — Faithful Typeset PDF

**The structure anchor for [`generated/plan-longform.pdf`](generated/).** Every regeneration reads this file first and produces a PDF that renders the current plan markdown as a typeset document with cover, TOC, chapters, and appendices. Edit this file to change PDF structure; do not edit prompts, do not edit the source plan files.

## Meta

| Property | Value |
|---|---|
| **Type** | Faithful typeset (option (a) from the design brainstorm). Structure and headings map 1:1 from source. No curated narrative reshaping. |
| **Audience** | Anyone reading the plan standalone — new stakeholders, archival readers, anyone handed the plan without having followed the day-to-day authoring. |
| **Expected length** | Roughly 50–80 pages depending on rendering density. |
| **Theme** | `document-skills:theme-factory` default professional theme (serif body font). Override by adding a `**Theme override:**` line here. |
| **Page size** | US Letter (8.5" × 11"). Change to A4 if distribution is primarily non-US. |
| **Margins** | 1" on all sides |
| **Running header** | Chapter title (left-aligned) · "SCADA IT/OT Transformation — 3-Year Plan" (right-aligned) |
| **Running footer** | Page number (center) · As-of date (right) |
| **Title on cover** | "SCADA IT/OT Transformation" |
| **Subtitle on cover** | "3-Year Plan" |
| **Cover as-of line** | "As of {{regeneration-date}}" |
| **Cover abstract** | A single paragraph lifted **verbatim** from [`../goal-state.md`](../goal-state.md) → **Vision** (the opening paragraph). Do not paraphrase. |

## Document structure

```
Cover page                         — title, subtitle, as-of date, abstract
Table of Contents                  — auto-generated, two levels deep
Chapter 1 — Current State          (source: ../current-state.md)
Chapter 2 — Goal State             (source: ../goal-state.md)
Chapter 3 — Roadmap                (source: ../roadmap.md)
Appendix A — Legacy Integrations Inventory  (source: ../current-state/legacy-integrations.md)
```

**Chapter / appendix file-to-source mapping:**

| Label | Title | Source file |
|---|---|---|
| Chapter 1 | Current State | [`../current-state.md`](../current-state.md) |
| Chapter 2 | Goal State | [`../goal-state.md`](../goal-state.md) |
| Chapter 3 | Roadmap | [`../roadmap.md`](../roadmap.md) |
| Appendix A | Legacy Integrations Inventory | [`../current-state/legacy-integrations.md`](../current-state/legacy-integrations.md) |

## Explicitly excluded

These files are **not** part of the PDF — do not include them even if they seem relevant:

| File | Why excluded |
|---|---|
| [`../CLAUDE.md`](../CLAUDE.md) | Repo meta — instructions for Claude, not plan content. |
| [`../status.md`](../status.md) | Working bookmark — a session-state artifact, not authoritative plan content. |
| [`./README.md`](README.md), [`./DESIGN.md`](DESIGN.md), [`./presentation-spec.md`](presentation-spec.md), [`./longform-spec.md`](longform-spec.md), [`./IMPLEMENTATION-PLAN.md`](IMPLEMENTATION-PLAN.md), [`./run-log.md`](run-log.md) | Output pipeline files — the pipeline does not document itself inside its own output. |
| [`./diagrams/*`](diagrams/), [`./generated/*`](generated/) | Output pipeline artifacts. |

If a new plan file is added to the repo and should be in the PDF, **add it here**, under Document structure, as a new chapter or appendix — not in the source file and not in the prompt.

### Section-level exclusions (render-time)

These **subsections** of an included source file are skipped when rendering. The source markdown is not edited — the renderer detects each heading by exact text match and omits the section through to the next sibling-or-higher heading. If the heading text in the source changes, this list must be updated.

| Source file | Heading to skip | Why excluded |
|---|---|---|
| [`../goal-state.md`](../goal-state.md) | `## Non-Goals` | Non-goals are still authoritative plan content (visible to anyone reading `goal-state.md` directly), but they were dropped from the long-form PDF + presentation in the 2026-04-30 trim — out-of-scope items don't need to be enumerated for the long-form audience the way they do for an in-room slide-deck audience. |
| [`../goal-state.md`](../goal-state.md) | `### Enterprise reporting: BOBJ → Power BI migration (adjacent initiative)` | Coordination ownership was transferred to another team on 2026-04-30 (see the "Coordination ownership (resolved 2026-04-30)" note retained at the end of the section). The full three-paths / eight-questions / decision-rubric analysis is preserved in `goal-state.md` for the other team and for future reference, but is not part of the long-form PDF anymore. |

**Sub-heading scope:** when a `##` is excluded, every `###`/`####` under it is also excluded (the renderer walks until it hits another `##` or the end of file). Same rule applies one level down for `###`. Be deliberate when adding to this list: excluding a `##` removes more than excluding a `###`.

If you want to **re-include** an excluded section, remove it from this table — do not modify the source file.

## Transformations applied during rendering

The narrow set of changes applied to source markdown when producing the PDF. Source markdown files are **not edited** — transformations are applied at render time.

### 1. File H1 → chapter/appendix title

`# Current State` (the first line of `current-state.md`) becomes the chapter title *"Chapter 1 — Current State"* on the chapter's opening page. The H1 is consumed by the chapter heading; it does not appear a second time in the body.

### 2. Heading numbering

All `##`, `###`, `####` headings receive section numbers:

- `##` → `N.M` where N = chapter number, M increments per ## within the chapter
- `###` → `N.M.K`
- `####` → `N.M.K.L`

Example: `## Systems & Interfaces` in Chapter 1 becomes `1.2 Systems & Interfaces`.

Numbering is **added at render time**; source markdown remains unchanged. Numbering is **applied to body text** but **not to the TOC** (TOC uses unnumbered section titles for readability).

### 3. Inter-file link normalization

Markdown links between plan files are resolved to section references in the rendered PDF:

| Source link form | Rendered form |
|---|---|
| `[current-state.md](current-state.md)` | "see Chapter 1 — Current State" |
| `[goal-state.md](goal-state.md)` | "see Chapter 2 — Goal State" |
| `[roadmap.md](roadmap.md)` | "see Chapter 3 — Roadmap" |
| `[legacy-integrations.md](current-state/legacy-integrations.md)` | "see Appendix A — Legacy Integrations Inventory" |
| `[equipment-protocol-survey.md](current-state/equipment-protocol-survey.md)` | Render as **plain text** — file removed. Log as warning. |
| Intra-file anchor links like `[X](#section-name)` | Rendered as internal PDF cross-reference to the numbered section (e.g., "see §1.2") |
| Links to excluded files (e.g., `status.md`) | Rendered as **plain text** — the link target is dropped, the link text stays. Logged as a warning in the run log. |
| External links (http://, https://) | Rendered as clickable external links, unchanged. |
| Unresolvable links (file not found) | Rendered as plain text, logged as a warning in the run log. **Do not silently drop.** |

### 4. `_TBD_` marker highlighting

Every occurrence of `_TBD_` in the source becomes a **visual callout** in the rendered PDF:

- Inline `_TBD_` tokens get a colored background (theme-appropriate warning color)
- A small margin icon (⚑ or similar) in the left margin on lines containing a TBD
- TBDs remain readable — the goal is visibility, not obstruction

This makes the "gaps stay visible" convention from [`../CLAUDE.md`](../CLAUDE.md) → Conventions actually visible on paper.

### 5. ASCII / text diagrams preserved

The Layered Architecture text diagram in `goal-state.md` (and any similar text diagrams elsewhere) renders as a monospace code block with a subtle border. Option (a) faithful typeset explicitly accepts this — proper visual diagrams live in the PPTX, not the PDF.

### 6. Tables preserved (with multi-page support)

Markdown tables render as PDF tables with row-level borders and header-row emphasis. Tables that exceed one page split cleanly at row boundaries, with the header row repeated at the top of each continuation page. `document-skills:pdf` handles this natively.

Specific large tables to expect:
- [`../roadmap.md`](../roadmap.md) → **The grid** (6 workstreams × 3 years) — likely spans 2–3 pages
- [`../current-state/legacy-integrations.md`](../current-state/legacy-integrations.md) → per-row integration detail tables (one per integration)
- [`../current-state/equipment-protocol-survey.md`](../current-state/equipment-protocol-survey.md) → field schema table, classification table, rollup views

### 7. Code blocks preserved

Fenced code blocks in the source (for example, the directory-structure `dot` block in [`../goal-state.md`](../goal-state.md) or the structure trees in this file) render as monospace blocks with a light background. Line wrapping preferred over horizontal scroll.

### 8. Block quotes preserved

Markdown `>` block quotes render as indented italic or colored blocks per the theme. Several key notes in the source (file headers, carve-outs) use block quotes and their emphasis is load-bearing.

### 9. Emphasis preserved

`**bold**`, `*italic*`, and `` `inline code` `` all render as expected. The source uses these deliberately (especially bold for decisions and vocabulary terms) — preserve fidelity.

## Front matter

### Cover page

```
[Large type]        SCADA IT/OT Transformation
[Medium type]       3-Year Plan

[Small type]        As of {{regeneration-date}}

[Body paragraph, centered or full-width]
{{abstract — verbatim from ../goal-state.md → Vision, opening paragraph}}
```

### Table of Contents

- Auto-generated from chapter and appendix headings
- **Two levels deep:** chapter titles + `##` headings within each chapter
- Unnumbered in the TOC for readability (numbering appears in body)
- Page numbers right-aligned
- Leaders (`.....`) between heading text and page number
- Chapters and appendices visually distinguished (slight indent, different weight, or section label)

### Back matter

- **No index.** Generating a useful index requires curation; automated indexing produces noise. Skip for the first pass.
- **No glossary.** Plan vocabulary (OtOpcUa, ScadaBridge, SnowBridge, Redpanda, etc.) is defined at first use in the source. If readers need a glossary, that's a future enhancement.

## Editing this spec

- **Structural changes go here** — chapter order, appendix additions, cover layout, page setup, transformation rules.
- **Content changes go in the source** — typos, new sections, corrections to the plan. The next regeneration picks them up automatically.
- **Theme / page-setup changes go in the Meta section** at the top of this file. Override with a `**Theme override:**` or `**Page size override:**` line.
- **Never hand-edit `generated/plan-longform.pdf`.** It is overwritten on the next regeneration.

## Planned follow-ups (not first-pass scope)

These are deliberately deferred:

- **Curated executive-narrative PDF** (option (b) from the design brainstorm) — a second output shaped as a standalone written report with intro, argument flow, transitions. Would live at `generated/plan-narrative.pdf` with its own `narrative-spec.md`.
- **Bilingual rendering** — if the plan ever serves a non-English audience.
- **Redacted variant** — a version with sensitive detail removed, for external stakeholders.
- **Date-stamped archival copies** — `generated/plan-longform-YYYY-MM-DD.pdf` alongside the current one, so the history of the plan is preserved as a series of snapshots.

None of these require changes to the current spec; add them when/if they become real requirements.