| 1 | # Executor Flat and Shared Core |
| 2 | |
| 3 | Always-loaded Executor authority for flat SVG page authoring and behavior shared by every Generate route. Load conditional branches only when their trigger is present. |
| 4 | |
| 5 | **Conditional branch routing**: |
| 6 | |
| 7 | | Trigger | Load | |
| 8 | |---|---| |
| 9 | | `pptx_structure.mode: structured` | [`executor-structured.md`](./executor-structured.md) | |
| 10 | | Any data chart, chart catalog selection, or text-grid table | [`executor-chart.md`](./executor-chart.md) | |
| 11 | | A page will use a preset pattern fill or evaluate native chart/table replacement | [`native-data-interface.md`](./native-data-interface.md) before deciding eligibility or emitting metadata | |
| 12 | | Any image/formula | [`executor-image.md`](./executor-image.md) + [`image-layout-spec.md`](./image-layout-spec.md) + [`image-layout-patterns.md`](./image-layout-patterns.md) + [`svg-image-embedding.md`](./svg-image-embedding.md) | |
| 13 | | Any `Status: Sourced` web image | [`executor-web-image.md`](./executor-web-image.md), after `executor-image.md` | |
| 14 | | Effective Speaker Notes outcome is enabled after all SVG pages pass | [`executor-notes.md`](./executor-notes.md) | |
| 15 | |
| 16 | > Narrative skeleton and visual aesthetic come from this deck's locked files under [`modes/`](./modes/_index.md) and [`visual-styles/`](./visual-styles/_index.md). [`shared-standards-core.md`](./shared-standards-core.md) supplies the technical boundary plus the fallback visual-quality and leading defaults when those authorities are silent. |
| 17 | |
| 18 | **Hard rule — complete page SVG**: Every visible object intended for the exported slide MUST exist in the final page SVG or be explicitly referenced by it. Templates and `spec_lock.md` guide construction; they are not export-time overlays for missing visible content. |
| 19 | |
| 20 | **Hard rule — flat PowerPoint structure**: Free-design, brand-only, Style-only, and every `template_reuse_scope: style` project use `pptx_structure.mode: flat`: write no root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder`; every visible object remains Slide-local, and the root declares exactly one canonical `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`). A Style workspace supplies reusable communication/design direction, composition rhythm, and information-expression defaults without page prototypes. Its identity-adjacent color, typography, icon, and image defaults yield to the final Brand/Deck identity and confirmed project lock. When Style is fused with Layout/Deck, it changes only Direction / method and follows the resolved non-Style structure route. Export materializes one clean project-owned Master plus one Blank Layout from the current lock. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by specialized metadata; the marked element uses a stable unique `id`. See [`semantic-svg.md`](./semantic-svg.md). |
| 21 | |
| 22 | **Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 still generates `svg_final/` as a mandatory self-contained visual preview that may be inserted as an SVG picture. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement. |
| 23 | |
| 24 | > Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing. |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## 1. Effect Capability Discovery |
| 29 | |
| 30 | **Mandatory — select by visual job**: establish each page's semantic skeleton, |
| 31 | then run the already-loaded [`svg-effects.md`](./svg-effects.md) §6.1 procedure |
| 32 | and Visual Job Router before finalizing; use §6.13 for a coordinated page |
| 33 | recipe when useful. The catalog expands construction vocabulary; it creates no |
| 34 | effect quota. Active cross-page continuous action additionally loads |
| 35 | [`animations.md`](./animations.md) §3.1 before authoring both endpoints. |
| 36 | |
| 37 | **Hard rule — discovery does not expand compatibility**: Follow |
| 38 | `svg-effects.md` syntax and fallbacks; unsupported source/backdrop blur, blend |
| 39 | mode, SVG `<mask>` / per-pixel masking, dense texture, or skew remains |
| 40 | baked/alternative-only. |
| 41 | |
| 42 | **Default — resolve active cross-page geometry here, while pages are still being authored (may override when the deck has no continuous action to express)**: object effects, page transitions, and Morph pair keys are post-processing decisions, but the two visible endpoint states are not. Apply this preparation only when an explicit user motion instruction, an enabled effective Custom Animations outcome, or an existing `animations.json` activates motion; a §IX Motion suggestion alone remains non-operative advice. An active sequence that should read as one continuous action (slide-in, flip, camera push-in, progressive reveal, camera pan) must be authored as consecutive pages in `svg_output/` now. Give each continuing endpoint a compatible direct-root group; source and destination ids or geometry may differ because the later motion stage can bind them explicitly through `animations.json`. A deck that reaches export without both states cannot gain the motion by adding a flag. Adding pages is a §IX roster change and returns to Strategist for Design Spec repair first. |
| 43 | |
| 44 | --- |
| 45 | |
| 46 | ## 2. Design Parameter Confirmation (Mandatory Step) |
| 47 | |
| 48 | Before the first SVG page, output a confirmation listing: the compact communication objective, canvas dimensions, body font size, color scheme (primary/secondary/accent HEX), font plan, and the live-preview URL reported by the launcher. If the preview launch failed, state that failure before generating SVGs instead of silently proceeding. Prevents purpose/spec/execution drift. |
| 49 | |
| 50 | ### 2.1 Execution context validity (Mandatory) |
| 51 | |
| 52 | - **Valid**: if the exact complete Design Spec and lock remain in the unchanged, uncompacted active context, reuse both for every page. Do not reread or poll them. |
| 53 | - **Invalid**: fresh/resumed/restarted execution, compaction/summary-only recovery, or an external/unknown change requires one complete read of `design_spec.md`, then `spec_lock.md`, plus triggered references/template inputs. Mid-deck recovery also reads the latest completed SVG and, when images are used, current image metadata. |
| 54 | - **Uncertain**: consult the retained lock first, then only the owning Design Spec fragment; use sources only for facts. Design Spec remains upstream on conflict. |
| 55 | |
| 56 | **On-demand page-context diagnostic**: only for explicit telemetry/debugging or an unresolved page/template/chart path-SHA question; never as a pre-page gate: |
| 57 | |
| 58 | ```bash |
| 59 | python3 ${SKILL_DIR}/scripts/project_manager.py page-context <project_path> P<NN> [--record-usage] |
| 60 | ``` |
| 61 | |
| 62 | Consume stdout directly; stop on non-zero exit. The projection is derived, not authoritative. Use `--record-usage` only for measurement. |
| 63 | |
| 64 | **Same-context repair**: in a valid uncompacted context, a bounded repair that preserves roster/order/identity/communication needs only affected Design Spec/lock fragment readback plus `project_manager.py validate`. Any broader or invalid-context repair requires the complete reads above. |
| 65 | |
| 66 | **Hard rule — exact page roster**: `design_spec.md §IX` is the ordered queue: one final slide per entry, with the same id/order. The UI range no longer applies. Never add, drop, merge, split, or reorder; repair/reconfirm the Design Spec first. |
| 67 | |
| 68 | **Hard rule — binding selection vs realization**: use Strategist-selected semantic content, resources/paths, chart keys, template/layout routing keys, core fonts, palette anchors, icon-library/stroke anchors, and crop boundaries. Adapt realization—including which prepared project-local icon, if any, best serves each page—without changing those binding selections, except sparse local font/color garnish allowed below. A §VIII preferred image pattern is not a template/layout routing key; [`executor-image.md`](./executor-image.md) owns its realization freedom. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Binding selection changes require upstream repair. |
| 69 | |
| 70 | **Hard rule — content vs expression**: `design_spec.md §IX` owns each page's semantic content and supplies complete preferred wording and block texture; those expression choices are not verbatim requirements unless explicitly literal. Executor may paraphrase, condense repetition, regroup or reorder material within the same page, and switch among prose, bullets, keywords, labels, or visual annotation when fit or readability benefits. The result must remain information-equivalent: preserve the `Core message`, `Audience move`, and every substantive claim, fact, data value, proper name, qualifier or caveat, relationship, key argument or evidence, and literal requirement. Never add a claim, move content across pages, or drop information to make the layout fit; return an unfit or underspecified block for Design Spec repair. |
| 71 | |
| 72 | Use named lock roles literally when that role applies, and use optional `Template Application` from the retained Design Spec. Choose contextual page-local values from the Design Spec, style, content, and current composition rather than forcing every object into a lock row. A page-context delta overrides neither facts nor constraints. Deprecated `page-context --bundle` is a compatibility no-op. |
| 73 | |
| 74 | **Source verification**: §IX owns the complete page brief; the page delta does not carry the source corpus. Read sources only to resolve listed `Fact IDs` or verify required claims, quotes, names, or data. Do not add facts, claims, or selected content. Return underspecified blocks for Design Spec repair. |
| 75 | |
| 76 | **Per-page communication trace**: Read `communication.objective`, `communication.core_message`, and the current §IX `Core message` + `Audience move` before choosing composition. The page must advance the compact objective and move the audience as authored in §IX; the global core message remains the deck-wide north star. A page that cannot state this movement is an upstream outline defect — surface `warning: P<NN> has no communication move` instead of compensating with decorative layout. Do not invent a new purpose, ask, or outcome at execution time. Structural pages may advance the contract by establishing relevance / tension / decision frame or by completing the final commitment; they are not exempt from having a reason to exist. |
| 77 | |
| 78 | **Per-page reading-mode check**: Read `communication.consumption_mode` before choosing the page's composition. Apply it together with the authored §IX block texture and `page_rhythm`: |
| 79 | |
| 80 | | `consumption_mode` | Page execution | |
| 81 | |---|---| |
| 82 | | `text` | Make the visible page independently understandable. Preserve complete prose, explicit labels / captions / sources, tables, and necessary detail; use bullets only for genuinely parallel or ordered items. | |
| 83 | | `balanced` | Keep the primary claim and its evidence on the page; when notes are enabled, let them add interpretation and transitions. Mix prose, structured evidence, and necessary lists according to their semantic relationship. | |
| 84 | | `presentation` | Make one claim and one dominant visual expression legible at projection distance. Keep visible copy concise; when notes are enabled, put explanation and transitions there instead of creating paragraph dumps or compressed bullet prose. When notes are disabled, rely only on the confirmed presenter/page channels and never omit required content on the assumption that notes will carry it. | |
| 85 | |
| 86 | Apply the content-vs-expression contract above within the selected reading mode. Never drop or invent facts to force a mode. When the authored texture materially conflicts with the lock, render the least-destructive faithful composition and surface `warning: P<NN> content texture conflicts with consumption_mode <value>` as an upstream outline issue; do not encode this subjective judgment in the checker. |
| 87 | |
| 88 | **Default — authored texture (may override when information-equivalent)**: start from each `design_spec.md §IX Content` block's written texture because it is the Strategist's recommended expression. Keep prose when its continuity carries causal, argumentative, narrative, qualification, or emphasis relationships; use bullets or keywords when the material is genuinely parallel or ordered, or another information-equivalent structure is clearer. Never convert solely because a list is easier to lay out or an inherited template exposes a list slot. |
| 89 | |
| 90 | - **Hard rule — one paragraph, one text frame**: use one `<text>` per prose paragraph, never sibling `<text>` elements for its visual lines. Keep the first authored line as direct text; later lines use direct `<tspan>` children that repeat parent `x`, retain effective font size, and use positive relative `dy`. An all-`<tspan>` form may start at `dy="0"`. Default retains these breaks without PowerPoint wrapping; `--reflow-text` enables reflow. Start from the shared leading ranges in [`shared-standards-core.md`](./shared-standards-core.md) §4.2, then adjust for the typeface, reading distance, explicit user/template requirements, and locked style. |
| 91 | - **Template precedence**: an inherited slot never overrides the content relationship. If faithful expression needs prose, widen or reflow the container, or drop that card; never convert solely to fill a list slot. |
| 92 | - **Mode precedence**: the locked mode shapes voice / register, not §IX's authored titles or page order. When a `§IX` title is a user-authored topic label, keep it — do not upgrade it to an assertion just because the mode (e.g. `pyramid`) favors them; mode title-tendencies apply only to AI-drafted titles. |
| 93 | |
| 94 | > Note: block-level phrasing, applied *within* the page's `page_rhythm` density (below), not against it. |
| 95 | |
| 96 | **Missing `spec_lock.md` or `design_spec.md`** → stop before drawing and report the missing gate artifact. Recover through [`failure-recovery.md`](../workflows/governance/failure-recovery.md) §3; do not silently downgrade. A failed on-demand `page-context` diagnostic is also not evidence that a required planning artifact may be bypassed. |
| 97 | |
| 98 | **Missing field in an existing lock**: follow [`failure-recovery.md`](../workflows/governance/failure-recovery.md) §2. |
| 99 | |
| 100 | **Execution anchors and contextual values**: |
| 101 | |
| 102 | - Icons may use any SVG already prepared under `<project_path>/icons/`. `icons.library` records the Strategist's primary bundled style choice and `icons.inventory` indexes its curated synced pool; neither assigns icons to pages or limits other project-local assets. |
| 103 | - Core color roles retain their meaning. Derive tints, shades, alpha, gradients, and effects; preserve natural asset colors; and use sparse page-local accents for differentiation/ornament. They must not become a competing or recurring palette. |
| 104 | - Resolve structural families by role: exact `<role>_family` first, then `title_family` for title roles or `body_family` for other unoverridden roles, then legacy `font_family`. Never flatten declared role overrides. A sparse export-safe accent family may style short non-structural display/ornament only—never title/body/data/annotation. Recurrence requires upstream selection. |
| 105 | - Font sizes use the named `typography` role values as deck-wide anchors. Map every structural text item to a declared role before drawing; never inherit a template placeholder size. Start from the anchor, then use composition and content fit to adjust that occurrence by at most `±2`px. Keep same-page peers consistent and preserve the role hierarchy; bounded adjustment does not create a new role. |
| 106 | - **Core message ≥ `body`**: map the page's primary claim to declared `lead` / `subtitle`, never below the current body treatment. Footnotes, page numbers, and credits use declared `footnote` / `annotation`; do not invent a smaller role. |
| 107 | - **Write unitless px, with at most two decimals.** Structural and mapped-role text uses only its anchor or a value within its `±2`px band; the sparse display-size exception is defined separately below. Do not substitute familiar pt-style numbers or emit long precision tails. |
| 108 | - **Sparse display-size exception**: a short non-structural Hero/Display element may use one undeclared size outside all anchor bands at most twice across the deck without a lock row. The third occurrence makes that size recurring: stop and return to Strategist to name the role in the Design Spec and `spec_lock.md`, then read back and validate the affected fragments before reuse. This exception never applies to titles, body copy, subtitles, annotations, footnotes, captions, data labels, or card copy, and nearby sizes must not be introduced to imitate one recurring treatment. |
| 109 | - **Outside-band recovery**: for structural text, reflow geometry and use the declared role band locally. For a sparse display occurrence, keep the unitless value and verify that its deck-wide count remains at most two. Never flatten a justified distinction or add a role merely to silence the checker. Mirror pages preserve exact source typography as inherited input. |
| 110 | - Images MUST reference files listed under `images`; no invented filenames |
| 111 | - Formula PNGs are images with `Acquire Via: formula`; place a `Rendered` file only from its listed path, use the normal placeholder for `Needs-Manual`, and never recreate the formula as text. |
| 112 | |
| 113 | Return upstream before any derived/accent identity becomes recurring or structural, or when an undeclared display size reaches its third occurrence, then update the retained context under §2.1. Local garnish, same-role `±2`px adjustments, and at most two sparse display-size occurrences need no lock row. Never expand the lock to silence a comparison. New icon acquisition, images, structural fonts, role anchors, and resources keep their preparation/role rules. |
| 114 | |
| 115 | **Per-page layout rhythm — `page_rhythm` section**: |
| 116 | |
| 117 | Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>` matching the page index in §IX of `design_spec.md`) and apply the corresponding layout discipline: |
| 118 | |
| 119 | | Tag | Layout discipline | |
| 120 | |-----|-------------------| |
| 121 | | `anchor` | Structural page (cover / chapter / TOC / ending). `mirror` follows its prototype; `layout` retains its structure system. `style` / free design preserves the §IX cover hook or closing takeaway but may adapt the recommended composition. Avoid an information-empty generic cover/sign-off unless content, user direction, or template requires it. | |
| 122 | | `dense` | Information-heavy. Card grids, multi-column layouts, KPI dashboards, tables, and charts are all permitted. This is the baseline behavior. | |
| 123 | | `breathing` | Low-density impact page. Avoid **multi-card grid layouts** — do not organize content as multiple parallel rounded containers (3-card row, 4-card KPI grid, 2×2 matrix rendered as cards). Use naked text blocks, dividers, whitespace, or full-bleed imagery as the content structure. Single rounded visual elements (hero image corners, callouts, tags, one emphasis block) are fine — the rule is about grid structure, not about the `rx` attribute. Proportions follow information weight (not a preset ratio). Typical forms: hero quote, single large number with one-line interpretation, full-bleed image with floating caption, section transition. | |
| 124 | |
| 125 | > Without rhythm variation, every page defaults to card grids (the "AI-generated" look). Context recovery follows §2.1. |
| 126 | |
| 127 | **Missing or empty `page_rhythm` section — fixed compatibility default** → emit `warning: spec_lock.md missing/empty page_rhythm — defaulting all pages to dense` once, fall back to `dense` for all pages. |
| 128 | |
| 129 | **Tag not found for current page — fixed compatibility default** → emit `warning: spec_lock.md page_rhythm tag not found for P<NN> — falling back to dense` once per deck (aggregate; do not repeat per page), fall back to `dense`. Do not invent a tag. |
| 130 | |
| 131 | |
| 132 | --- |
| 133 | |
| 134 | ## 3. Execution Guidelines |
| 135 | |
| 136 | - **Element grouping (Mandatory)**: wrap each logical Slide-local body unit in a descriptive, page-unique top-level `<g id>`. Every visible direct root `<g>` declares root-coordinate `data-pptx-bounds="x y width height"`; frame/native coordinates do not replace it, and placeholder bounds also supply the slot frame. Nested groups need no bounds and any such values are ignored. Checker compares root bounds with the `viewBox`, recursively checks estimable text against its root module with DrawingML wrapping headroom, and independently checks every estimable visible text carrier against the page without that headroom: through `1px` is ignored; module overflow warns through `5%` and fails above it, while larger page overflow always fails. Unestimable visible text receives an advisory warning. Only a wholly off-canvas direct-root Morph endpoint may set `data-pptx-morph-staging="true"`; keep its text inside its own module bounds, use an explicit pair when Morph remains enabled, and never use the marker for partial overflow. Images, shapes, paths, `<use>`, effects, and object frames remain geometrically free. Flat pages use ordinary groups; structured slots already qualify, while titles, direct Master/Layout atoms, and canvas-level static framing may remain root primitives. On flat pages, give a root background image or full-canvas scrim/decoration rectangle a stable `id` plus `data-pptx-role="background"` / `"decoration"`; never wrap it only to silence the advisory. |
| 137 | - **Reference — not a constraint**: top-level groups set semantic and automatic-animation granularity, but they may contain descriptive nested `<g>` edit groups when the page has meaningful internal subunits. Nested groups need no bounds and create no automatic animation step; use or omit them from the page's actual editing semantics, with no default pattern, depth, or quota. |
| 138 | - **Default — size `data-pptx-bounds` as the intended module zone, not a glyph box (may skip when no text is estimable)**: make the zone as generous as the canvas and sibling layout allow, without overlapping another module zone. An untransformed line spans `y - 0.85 × font_size` to `y + 0.35 × font_size`; width uses the shared SVG-to-PPTX per-run estimate and safety headroom. If text does not fit, first expand a zone that has unused non-overlapping space; otherwise reflow or adapt. Larger bounds do not repair off-canvas text. |
| 139 | - **Spec adherence**: follow color, layout, canvas format, and typography in the spec |
| 140 | - **Template structure**: inherit the native visual framework only for `template_reuse_scope: mirror|layout`; `style` uses the flat route |
| 141 | - **Main-agent ownership**: SVG generation must run in the main agent (not sub-agents) — pages share upstream context for cross-page visual continuity |
| 142 | - **Generation rhythm**: P01 → first-page gate → uninterrupted remaining pages → final gate, in one context without batches or mid-run checker calls. |
| 143 | - **Fact provenance**: when a §IX page lists `Fact IDs`, resolve each ID from `sources/*.facts.json` and keep the claim/value unchanged. Render a compact source footnote using the source name and a short URL/domain when space permits; when speaker notes are enabled, state the attribution naturally there too. When §IX says `Data class: scenario`, place a visible localized `Scenario data` / `情景数据` label adjacent to the affected KPI/chart and, when notes are enabled, state naturally there that the number is illustrative. Never attach an external fact ID to scenario data or let an unlabeled invented KPI look factual. |
| 144 | - **Default — stage each page with the style's composition geometry (may override when the content genuinely calls for a plain grid)**: an SVG page is a canvas, not a DOM. Before defaulting to stacked rounded-rect cards or uniform equal columns, pick one page-scale move from the locked visual style's §1 `Composition geometry` (a bleed shape, diagonal split, oversized numeral, orbit rings, …) to stage the page's primary zone. Card grids are one option among many, not the house layout. |
| 145 | - **Default — vary a planned deck motif instead of cloning it (may omit where it has no page job)**: when §III `Theme` names a cross-page motif, use the current §IX `Layout` to preserve its recognizable contour, direction, material, or relationship while varying scale, crop, density, position, and content interaction by page role. Apply it only where it supports hierarchy or continuity; do not paste identical ornament or invent a second recurring identity. |
| 146 | - **Inherited containers**: preserve meaningful template frames; restyle radius, fill, stroke, and depth from the active Design Spec and `spec_lock.md`. Chart-catalog adaptation is owned by [`executor-chart.md`](./executor-chart.md); preview effects never override project styling or structural roles. |
| 147 | - **Reference — prefer semantic geometry over preset stacks**: for relationships such as ascending, converging, breaking through, or stacking, first seek a basic primitive, one exact preset, or a clear Boolean result. Only when none can faithfully express the relationship should one page-specific polygon/path replace a stack of generic arrows. |
| 148 | - **Reference — create depth with restraint**: use rhythm, spacing, typography, accent bars, and subtle tints before shadows. Reserve lift for a few genuinely floating elements; keep peer grids, dividers, and body containers flat. |
| 149 | - **Phased generation** (recommended): |
| 150 | 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every §IX-planned data-chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every planned native-ready object. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page --json` directly without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls. |
| 151 | 2. **Quality Check Gate**: only after every planned SVG exists, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json` directly on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations. |
| 152 | 3. **Logic Construction Phase (conditional)**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity only when the effective Speaker Notes outcome is enabled. |
| 153 | |
| 154 | ### 3.0 Native Shape Selection |
| 155 | |
| 156 | **Use the highest-level native construction that faithfully expresses the |
| 157 | object.** Basic primitives already export as editable PowerPoint shapes. For |
| 158 | anything beyond them, an exact Office preset is the default; when no single |
| 159 | preset suffices but closed operands can express the result, materialize a |
| 160 | Merge Shapes Boolean result. Hand-authored freeform geometry is the final |
| 161 | fallback, not the first drawing convenience. Block arrows, chevrons, banners / |
| 162 | ribbons, callouts, flowchart nodes, stars, and other Office symbols should be |
| 163 | **authored as presets** via `preset_shape_svg.py`, not redrawn as plain |
| 164 | `<path>`s or faked with rectangles. Apply the decision gate in |
| 165 | [`native-shape-authoring.md`](./native-shape-authoring.md) before drawing the |
| 166 | object. |
| 167 | |
| 168 | §IX `Native shape suggestion` records a semantic opportunity, not a literal |
| 169 | tool command. Decide from the actual page construction whether a basic |
| 170 | primitive, preset, Boolean result, or necessary freeform best realizes it; a |
| 171 | different implementation is valid when it preserves the intended object and |
| 172 | content. |
| 173 | |
| 174 | | Decision | Action | |
| 175 | |---|---| |
| 176 | | Plain rect / symmetric round rect / circle / ellipse | Keep the ordinary SVG primitive; it is already natively editable. | |
| 177 | | Straight relationship / divider / leader | Use `<line>`; add a registered marker only when direction is meaningful. | |
| 178 | | Exact single-preset match | Call `preset_shape_svg.py render` and paste its complete stdout fragment into the current hand-authored SVG. | |
| 179 | | Bent / curved relationship exactly expressed by a stock Connector contour, with no required endpoint attachment | Use the matching `bentConnector*` / `curvedConnector*` preset through the helper as an unconnected native Connector shape. | |
| 180 | | Supported closed-shape / resolvable-text operands need union, cutout, overlap, symmetric difference, or fragmentation | Use `shape_boolean_svg.py` when Boolean materialization is the clearest faithful construction; follow [`native-shape-authoring.md`](./native-shape-authoring.md) §6. | |
| 181 | | Stock shape that needs a gradient fill/stroke or a pattern fill | Keep ordinary SVG — the helper paints `none` or a solid HEX on both fill and stroke only ([`native-shape-authoring.md`](./native-shape-authoring.md) §5). | |
| 182 | | Page-specific freeform, organic, branded, icon, data geometry, or relationship contour that primitives, one preset, and Boolean materialization cannot faithfully express | Keep ordinary SVG path/polygon geometry. | |
| 183 | | Similar-looking contour only | Never infer a preset; continue to the Boolean gate, then use freeform only if no faithful construction exists. | |
| 184 | |
| 185 | **Hard rule — freeform is the last construction tier**: before hand-authoring a |
| 186 | stock-looking `<path>` / `<polygon>`, complete the primitive → exact preset → |
| 187 | Boolean-result decision order above. A freeform is permitted only when those |
| 188 | tiers cannot faithfully express the object; avoiding a helper or drawing the |
| 189 | browser-visible contour faster is not a valid exception. Data-defined geometry |
| 190 | and a genuinely locked organic / hand-drawn contour satisfy the exception by |
| 191 | semantics, not by convenience. |
| 192 | |
| 193 | This decision applies only while drawing a new object. A suggestion never |
| 194 | triggers retrospective scanning, contour classification, or automatic |
| 195 | upgrading of ordinary SVG during export. |
| 196 | |
| 197 | **Hard rule**: do not hand-write `data-pptx-authoring`, `data-pptx-prst`, |
| 198 | `data-pptx-frame`, adjustment metadata, or registry paths. The preset helper |
| 199 | generates one compact atomic `<g>` from the shared 187-shape registry, with |
| 200 | semantic metadata and base paint written once. Rerun that helper when geometry |
| 201 | or paint changes; never edit one of its direct paths. |
| 202 | |
| 203 | **Default — relationship geometry**: use `<line>` for a straight relationship. |
| 204 | When a relationship genuinely needs a bend or curve and a stock Connector |
| 205 | contour fits, prefer the matching `bentConnector*` / `curvedConnector*` preset |
| 206 | over a hand-authored SVG Bézier. Use an open freeform path only when a straight |
| 207 | line and the native Connector families cannot faithfully express the required |
| 208 | route, data geometry, or locked hand-drawn / organic style. A directional solid |
| 209 | object remains an ordinary `shape` preset such as `rightArrow` or `chevron`. |
| 210 | |
| 211 | Authored Connector presets export as unconnected `p:cxnSp` objects: they do not |
| 212 | bind to node sites or follow moved nodes. Never hand-add endpoint/site metadata |
| 213 | or claim attachment semantics. Imported Connector topology stays under the |
| 214 | preserve/mirror contract. `actionButton*` presets provide visual geometry only, |
| 215 | not actions or hyperlinks. |
| 216 | |
| 217 | **Hard rule — narrow helper scope**: Both helpers print only their documented |
| 218 | stdout fragment(s); neither writes a page or chooses layout. Read every returned |
| 219 | fragment and insert it through the normal `apply_patch` page edit; never |
| 220 | redirect, loop, or batch helper output into `svg_output/`. |
| 221 | |
| 222 | |
| 223 | ### SVG File Naming Convention |
| 224 | |
| 225 | Format: `<index>_<page_name>.svg`. Use one roster-wide zero-padded index width sized for the Design Spec §IX roster, such as `01_cover.svg` through `12_end.svg` or `001_cover.svg` through `120_end.svg`; match the deck language and page title. |
| 226 | |
| 227 | --- |
| 228 | |
| 229 | ## 4. Icon Usage |
| 230 | |
| 231 | Strategist chooses at most one primary bundled stylistic library and may select `simple-icons` alone or alongside it; Executor implements from the complete prepared project-local pool. Library details and selection rules: [`../templates/icons/README.md`](../templates/icons/README.md). This section defines placeholder syntax. |
| 232 | |
| 233 | > **Prepared-project boundary.** Any SVG already under `<project_path>/icons/<lib>/` is valid execution material, whether selected from a bundled library or supplied by the user, a template, or an import workflow. New authoring must resolve there. The global fallback in `finalize_svg.py embed-icons` is legacy compatibility, not permission for Executor to discover or use an unprepared global icon. |
| 234 | |
| 235 | > **Icon identifiers are case-sensitive filenames.** Every `data-icon` value must use the exact project-local relative basename (`tabler-outline/award`, never `tabler-outline/Award`). Strategist records its curated bundled pool in `spec_lock.md`; Executor need not add other already-prepared project-local icons to that inventory. Custom identifiers preserve the custom file's exact case; the pipeline never silently lowercases names. |
| 236 | |
| 237 | **Built-in icons — Placeholder method (recommended)**: |
| 238 | |
| 239 | ```xml |
| 240 | <!-- chunk-filled (straight-line geometry, sharp corners, structured) --> |
| 241 | <use data-icon="chunk-filled/home" x="100" y="200" width="48" height="48" fill="#005587"/> |
| 242 | |
| 243 | <!-- tabler-filled (bezier-curve forms, smooth & rounded contours) --> |
| 244 | <use data-icon="tabler-filled/home" x="100" y="200" width="48" height="48" fill="#005587"/> |
| 245 | |
| 246 | <!-- tabler-outline (light, line-art style — screen-only decks) --> |
| 247 | <use data-icon="tabler-outline/home" x="100" y="200" width="48" height="48" fill="#005587"/> |
| 248 | |
| 249 | <!-- phosphor-duotone (single color + 20% backplate — soft depth without solid weight) --> |
| 250 | <use data-icon="phosphor-duotone/house" x="100" y="200" width="48" height="48" fill="#005587"/> |
| 251 | |
| 252 | <!-- simple-icons (brand logos — used alongside the deck's primary library, only for real company/product marks) --> |
| 253 | <use data-icon="simple-icons/github" x="100" y="200" width="48" height="48" fill="#181717"/> |
| 254 | |
| 255 | <!-- tabler-outline with thin / bold stroke (stroke-style libraries only) --> |
| 256 | <use data-icon="tabler-outline/home" x="100" y="200" width="48" height="48" fill="#005587" stroke-width="1.5"/> |
| 257 | <use data-icon="tabler-outline/home" x="100" y="200" width="48" height="48" fill="#005587" stroke-width="3"/> |
| 258 | ``` |
| 259 | |
| 260 | > ⚠️ **Color**: ALWAYS use `fill="#HEX"` on `<use data-icon="...">`. NEVER use `stroke` or `fill="none"`, even for stroke-style libraries. |
| 261 | > |
| 262 | > **stroke-width** (stroke-style libraries only, currently `tabler-outline`): allowed values `{1.5, 2, 3}`. If `spec_lock.md icons.stroke_width` is declared, all placeholders MUST use that value deck-wide. Ignored on non-stroke libraries. |
| 263 | > |
| 264 | > **Missing `icons.stroke_width` in an existing stroke-library lock — fixed compatibility default**: use `2`, emit one warning, and continue. New authoring must still declare the field. |
| 265 | > |
| 266 | > Icons are auto-embedded by `finalize_svg.py` — no need to run `embed_icons.py` manually. |
| 267 | |
| 268 | **Project-local verification**: verify the exact prepared file before use: |
| 269 | ```bash |
| 270 | test -f "<project_path>/icons/<lib>/<name>.svg" |
| 271 | ``` |
| 272 | |
| 273 | **Default — purposeful icon use**: choose prepared icons per page when they compress a label, distinguish parallel categories, clarify a process / KPI / state, or improve navigation and visual rhythm. Omit them when imagery, charts, or typography already carry the meaning. There is no coverage quota, and the prepared pool need not be exhausted. |
| 274 | |
| 275 | **Missing project-local icon** → return to Strategist's preparation / `icon_sync.py` gate. Do not search the global library, select an alternative, or copy a candidate in Executor. |
| 276 | |
| 277 | **Hard rule — prepared assets**: Executor may freely combine project-local icons, regardless of namespace or style. It may not acquire a new icon or treat a globally resolvable file as prepared material. |
| 278 | |
| 279 | --- |
| 280 | |
| 281 | ## 5. Font Usage |
| 282 | |
| 283 | Read typography from `spec_lock.md`: `<role>_family` → `title_family` / `body_family` → legacy `font_family`; sparse accents follow §2.1 and LaTeX stays PNG. |
| 284 | |
| 285 | **Default — locked-stack realization (may vary treatment)**: Express the Design Spec Character Reference through scale, weight, spacing, color, and composition; keep the locked family. Put the common stack on root `<svg>`, omit matching descendants, and override at the nearest clear `<g>`, `<text>`, or `<tspan>`. |
| 286 | |
| 287 | **Missing required field — `typography.font_family`** → stop and return to Generate Step 4 / [`strategist.md`](strategist.md) §6.2 to repair `spec_lock.md`; do not infer a stack from `design_spec.md`. |
| 288 | |
| 289 | **Hard rule**: every SVG `font-family` stack MUST resolve to target-installed/approved Latin and EA faces. PPTX writes one face per script; CSS tails affect preview only, and fonts are not embedded. Missing-face substitution is viewer-selected—not guaranteed Calibri or a later stack entry. |
| 290 | |
| 291 | --- |
| 292 | |
| 293 | ## 6. Completion Routing |
| 294 | |
| 295 | After every SVG page passes the final quality check, load |
| 296 | [`executor-notes.md`](./executor-notes.md) and complete its notes contract only |
| 297 | when the effective Speaker Notes outcome in `design_spec.md §I` is enabled. |
| 298 | When disabled, proceed directly to the route's conditional motion handling and |
| 299 | Step 7. |
| 300 | |
| 301 | ## 7. Next Steps After Completion |
| 302 | |
| 303 | > **Auto-continuation**: After Visual Construction Phase and any enabled Logic Construction Phase are complete, the Executor proceeds directly to the post-processing pipeline. |
| 304 | |
| 305 | **Post-processing & Export**: Follow [`generate-pptx.md`](../workflows/generate-pptx.md) |
| 306 | Step 7. That workflow owns the serial commands, gates, success criteria, and |
| 307 | published artifacts; [`svg-pipeline.md`](../scripts/docs/svg-pipeline.md) owns |
| 308 | tool-specific flags and behavior. |
| 309 | |
| 310 | `svg_final/` may be opened directly or manually inserted into PowerPoint as an SVG picture. It is not a second PPTX route. Use `-s final` only for converter diagnostics; release exports use the default `svg_output/` source. Manual Convert-to-Shape behavior is unsupported. |
| 311 |