3yearplan/outputs/longform-spec.md

Longform Spec — Faithful Typeset PDF

The structure anchor for generated/plan-longform.pdf. 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 → 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
Chapter 2	Goal State	../goal-state.md
Chapter 3	Roadmap	../roadmap.md
Appendix A	Legacy Integrations Inventory	../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	Repo meta — instructions for Claude, not plan content.
../status.md	Working bookmark — a session-state artifact, not authoritative plan content.
./README.md, ./DESIGN.md, ./presentation-spec.md, ./longform-spec.md, ./IMPLEMENTATION-PLAN.md, ./run-log.md	Output pipeline files — the pipeline does not document itself inside its own output.
./diagrams/*, ./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	## 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	### 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 → 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 → The grid (6 workstreams × 3 years) — likely spans 2–3 pages
• ../current-state/legacy-integrations.md → per-row integration detail tables (one per integration)
• ../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 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.