Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(template-reuse): align workflow contracts with explicit reuse scopes

hugohe3c4fb1c60ba22
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 8f611622..75b349d5 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -58,7 +58,7 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
[Executor]
├── Live preview starts and stays available during generation
├── Visual construction: generate project-canonical SVG pages sequentially → svg_output/
- ├── [Quality Check] svg_quality_checker.py (mandatory — 0 errors; warnings are non-blocking)
+ ├── [Quality Check] svg_quality_checker.py --stage final --json (mandatory — 0 errors; warnings are non-blocking)
└── Notes generation: complete speaker notes → notes/total.md
↓
[Chart calibration (conditional)] → verify-charts stage (required for decks containing data charts)
@@ -74,6 +74,8 @@ Output:
# Every PPTX variant below is produced through the svg_output → native DrawingML route
exports/
├── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — canonical output, edit & deliver from here
+ ├── presentation_<timestamp>.report.json ← Postflight package/resource audit linked to the final SVG quality report
+ ├── svg_quality_report.json ← Blocking/introduced/inherited/source-import SVG findings
├── presentation_<timestamp>_native_charts_tables.pptx ← PowerPoint-native Chart/Table replacements (opt-in via --native-charts-and-tables)
└── presentation_<timestamp>_narrated.pptx ← Narrated version — embedded per-slide audio + auto-advance timings (via --recorded-narration audio)
@@ -86,7 +88,7 @@ Output:
For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority, but SVG here means project-canonical SVG accepted by the project contract—not any SVG a browser can render. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. Templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; the exporter does not use them as a second visual layer that fills in missing page content.
-Minimal semantic markers do not weaken that closure. Free-design and brand-only pages use `pptx_structure.mode: flat`: every represented object stays Slide-local and no Master/Layout identity, layer, or placeholder metadata is authored. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks without promoting Slide content. On structured deck/layout-template routes, every new page declares its Master/Layout identity from the first SVG draft. Fixed Master/Layout visuals are direct atomic root children, while reusable content slots are top-level groups with explicit design-zone bounds and one compatible carrier; composite `object` regions use an explicit proxy fallback, and zero-slot Layouts are valid. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. A semantic-legacy template package is not upgraded in place or accepted as a structured Step 3 input: create a new workspace through `create-template`, using a native PPTX's still-present package facts or an old SVG's visuals only as reference, then author new structured pages through the Generate PPTX route. A flat project is intentionally unmapped, not legacy. Export never infers, repairs, or migrates Master/Layout structure or placeholders.
+Minimal semantic markers do not weaken that closure. Free-design, brand-only, and `template_reuse_scope: style` pages use `pptx_structure.mode: flat`: every represented object stays Slide-local and no Master/Layout identity, layer, or placeholder metadata is authored. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks without promoting Slide content. Only `template_reuse_scope: mirror|layout` uses the structured route, where every new page declares its Master/Layout identity from the first SVG draft. Fixed Master/Layout visuals are direct atomic root children, while reusable content slots are top-level groups with explicit design-zone bounds and one compatible carrier; composite `object` regions use an explicit proxy fallback, and zero-slot Layouts are valid. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. A semantic-legacy template package is not upgraded in place or accepted as a structured Step 3 input: create a new workspace through `create-template`, using a native PPTX's still-present package facts or an old SVG's visuals only as reference, then author new pages through the confirmed reuse-scope route. A flat project is intentionally unmapped, not legacy. Export never infers, repairs, or migrates Master/Layout structure or placeholders.
| Domain | Authority |
|---|---|
@@ -156,14 +158,17 @@ The workflow is easier to maintain if the artifacts are read as a dataflow rathe
```text
sources/<content files> ────────┐
+sources/*.facts.json ───────────┤
analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spec_lock.md
analysis/image_analysis.csv ────┘
spec_lock.md + images/ + icons/ + templates/
+ + templates/template_execution_manifest.json
+ + selected templates/template_execution/*.text-slots.json
└─> Executor -> svg_output/
- ├─> svg_quality_checker.py
+ ├─> svg_quality_checker.py -> exports/svg_quality_report.json
├─> finalize_svg.py -> svg_final/
- └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx
+ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx + <output_stem>.report.json
backup/<ts>/svg_output/
Direct OOXML routes:
@@ -331,7 +336,7 @@ PPT Master uses **role switching within one main agent** rather than parallel su
**Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode (no improvisation, no missing attributes). Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest.
-**Strategist confirmation stage as the only blocking gate.** Strategist ends with a single confirmation gate delivered in three stages: Stage 1 confirms direction anchors (canvas, audience, divergence, delivery purpose, mode, visual style, plus template adherence only when Step 3 loaded a deck/layout template); Stage 2 is re-derived from those anchors and confirms the design system (page count, palette, typography, icons, formula policy); Stage 3 is re-derived from the confirmed design system and confirms images / execution (image usage, generated-image style, AI image path, generation mode, refine-spec). Template adherence defaults to `adaptive`: every page still references the template architecture, but unmatched compositions may create a new explicit Layout under the same Master. `strict` keeps every selected Layout contract unchanged. The final `confirm_ui/result.json` is authoritative.
+**Strategist confirmation stage as the only blocking gate.** Strategist ends with a single confirmation gate delivered in three stages: Stage 1 confirms direction anchors (canvas, audience, divergence, delivery purpose, mode, visual style, plus `template_reuse_scope` when Step 3 loaded a deck/layout template and `template_adherence` only for `mirror` / `layout`); Stage 2 is re-derived from those anchors and confirms the design system (page count, palette, typography, icons, formula policy); Stage 3 is re-derived from the confirmed design system and confirms images / execution (image usage, generated-image style, AI image path, generation mode, refine-spec). Reuse scope defaults to `layout`; `style` selects the flat free-design route, while structured `mirror` / `layout` defaults adherence to `adaptive`, which may create a new explicit Layout under the same Master. `strict` keeps every selected Layout contract unchanged. The final `confirm_ui/result.json` is authoritative.
**Image analysis goes through regenerated metadata, not pixels.** When images exist, Strategist and Executor use `analyze_images.py` output (`analysis/image_analysis.csv`) rather than directly opening image files. The CSV is a regenerated view over the live `images/` folder, not a durable cache. Re-running it before image-sensitive decisions is the staleness strategy: user images, extracted images, web images, AI outputs, formulas, and sliced elements all converge into the same measured fact table.
@@ -360,7 +365,7 @@ The Strategist phase produces two artifacts that look redundant but serve differ
Why both? Without `spec_lock.md`, the Executor would re-read `design_spec.md` per page during long decks and the LLM's context-compression drift would gradually mutate colors and fonts mid-deck. `spec_lock.md` is the **anti-drift mechanism** — the SKILL.md mandates `read_file <project>/spec_lock.md` before every page, so values stay verbatim across 20+ slides.
-The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` references that decide which execution rule files are loaded. Structured deck/layout-template projects additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments; flat free-design/brand-only projects keep only `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.
+The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` references that decide which execution rule files are loaded. `template_reuse_scope: mirror|layout` projects additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.
`update_spec.py` propagates a post-generation change in two coordinated steps: write the new value to `spec_lock.md`, then literal-replace it across every `svg_output/*.svg`. The tool's scope is deliberately narrow — only `colors.*` (HEX values, case-insensitive replacement) and `typography.font_family` (attribute-scoped). Other fields (font sizes, icons, images, canvas) are intentionally **not supported** because their replacements would need attribute-scoped or semantic awareness whose risk/benefit doesn't justify bulk propagation. For those, edit `spec_lock.md` and re-author the affected pages.
@@ -456,6 +461,8 @@ The post-processing and export stages work with distinct artifacts. Each one ser
| `svg_output/` | source of truth, manual editing, `update_spec.py`, `svg_quality_checker.py` | only directory whose contents are authored, not derived |
| `svg_final/` | mandatory self-contained visual preview; IDE/browser inspection; manual insertion as an SVG picture | `.pptx` is not openable in IDEs; `svg_output/` won't render fully because of external icon / image refs. PowerPoint Convert to Shape is not supported |
| `exports/<name>_<ts>.pptx` (native) | primary deliverable — editable in PowerPoint with DrawingML shapes | only artifact whose shapes the user can resize / recolor / restyle natively in PowerPoint |
+| `exports/svg_quality_report.json` | machine-readable final SVG gate | separates blocking failures, introduced advisories, inherited prototype findings, and source-import losses, and fingerprints the checked SVG bytes |
+| `<output_stem>.report.json` | published-PPTX postflight and resource audit | records actual ZIP/package part counts; reruns ZIP and Slide-count checks; labels relationship, structured-package, transition, and animation validation as build-time enforcement; accepts quality-report linkage only when its SHA-256 fingerprint matches the export inputs; and surfaces unresolved tokens, external images, and generic-only font stacks |
| `exports/<name>_<ts>_native_charts_tables.pptx` (opt-in via `--native-charts-and-tables`) | when `data-pptx-replace-with` markers should replace SVG-derived, shape-based charts/tables with PowerPoint-native Chart/Table objects | data-backed objects with chart/table-specific controls; the default DrawingML shapes remain independently editable |
| `exports/<name>_<ts>_narrated.pptx` (via `--recorded-narration audio`) | narrated deck for auto-play and PowerPoint video export | embedded per-slide audio plus auto-advance timings; name marks it apart from silent exports |
| `backup/<ts>/svg_output/` (always written in default-flow mode) | re-export from frozen SVG sources without re-running the LLM, archival | the only persisted copy of the Executor's raw SVG source after the project has been edited downstream |
@@ -509,7 +516,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why there is only one PPTX compiler route.** Native export reads authored SVGs and translates supported SVG elements into DrawingML shapes. The normal deck path reads `svg_output/`; when requested, create-template invokes the same structured compiler on validated template prototypes to produce `exports/<id>_template_preview.pptx` as review evidence. The project does not package whole-slide SVG media or alternate raster renderings into a second PPTX. `svg_final/` is still generated on every standard deck run, but it is a self-contained visual-preview artifact rather than a PPTX source; users may insert it as an SVG picture, while PowerPoint's manual Convert to Shape command remains outside the supported contract.
-**Why structure is authored before visual generation on template routes.** Master and Layout are not post-processing discoveries. On a structured deck/layout-template route, the Strategist writes unique Master/Layout definitions and complete page assignments before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. Free-design and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export — reusable structure is a template-route deliverable, not a free-design authoring tax. Legacy inputs may inform a new `create-template` workspace, but they never enter an in-place structure-upgrade route; neither generation mode triggers heuristic Master/Layout promotion or placeholder inference.
+**Why structure is authored before visual generation on structured reuse routes.** Master and Layout are not post-processing discoveries. With `template_reuse_scope: mirror|layout`, the Strategist writes unique Master/Layout definitions and complete page assignments before SVG generation; the Executor writes those identities, fixed atoms, and slots while composing each page, and export only compiles declared structure. `template_reuse_scope: style`, free-design, and brand-only decks make the opposite trade: they stay on `mode: flat`, keep every object Slide-local, author no structure metadata, and receive only a clean project-owned Master/Blank-Layout shell at export. Legacy inputs may inform a new `create-template` workspace, but they never enter an in-place structure-upgrade route; neither generation mode triggers heuristic Master/Layout promotion or placeholder inference.
**Why Master/Layout visuals are atomic.** A Master or fixed Layout object must be one direct root child. Group-level transforms, opacity, styles, and z-order from imported PPTX objects are pushed into individual atoms during reconstruction. This deliberately gives up source group-editing hierarchy in exchange for a simple, deterministic ownership model that can be compared across pages and rebuilt into native parts without nested structural ambiguity.
@@ -517,7 +524,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why reusable bounds are design zones, not measured text boxes.** Slot bounds come from the intended safe area, column, panel inset, or picture frame—not glyph width, line count, or the current content's tight box. The current Slide retains its own authored carrier geometry, so 4:6, 3:7, and 5:5 instances may share one Layout when they express the same semantic composition. Text length therefore cannot accidentally split or mutate the reusable Layout contract.
-**Why strict and adaptive templates share one structured route.** `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master and defines a new Layout only when fixed Layout atoms or slot topology/bounds change; the assignment is updated during page authoring rather than inferred later. A template-backed definition may remain unused and still register in the final package. Non-mirror skin remains project-controlled, while mirror keeps the preserved output visual identities declared by its new workspace.
+**Why reuse scope and adherence are separate.** `template_reuse_scope` first selects literal mirror reuse, structural layout reuse, or flat style reference. Only `mirror` and `layout` then use `template_adherence: strict|adaptive` on the structured route: `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master and defines a new Layout only when fixed Layout atoms or slot topology/bounds change; the assignment is updated during page authoring rather than inferred later. A template-backed definition may remain unused and still register in the final package. Layout skin remains project-controlled, while mirror additionally preserves literal visuals and text-node topology. `style` has no adherence value or structure mappings.
**Why explicit-Layout text defaults are split between Master and Layout.** Both flat and structured export write the locked title size and a deterministic nine-level body hierarchy into Master defaults while preserving indentation and bullet settings. On structured routes, each generated Layout text slot additionally copies its carrier's first run size into the level-one default while retaining the prompt's direct size. This preserves Layout-specific scale when placeholder text is inserted or reset; direct runs on generated Slides remain unchanged.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 2b3eaaba..f3cf0149 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -58,7 +58,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
[Executor] 执行师
├── 生成开始前启动 live preview,并在生成期间保持可用
├── 视觉构建:按页顺序连续生成项目规范化 SVG 页面 → svg_output/
- ├── [Quality Check] svg_quality_checker.py(强制通过,0 错误;warning 非阻塞)
+ ├── [Quality Check] svg_quality_checker.py --stage final --json(强制通过,0 错误;warning 非阻塞)
└── 讲稿生成:完整讲稿 → notes/total.md
↓
[图表校准(条件触发)] → verify-charts 工作流(含数据图表的 deck 必须在此步骤校准坐标)
@@ -73,6 +73,8 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
exports/
├── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 唯一 PPTX 生成路线的标准文件
+ ├── presentation_<timestamp>.report.json ← 关联最终 SVG 质量报告的 package / 资源审计
+ ├── svg_quality_report.json ← blocking / introduced / inherited / source-import 分类结果
├── presentation_<timestamp>_native_charts_tables.pptx ← 同一路线的 PowerPoint 原生 Chart/Table 替换变体(加 --native-charts-and-tables 时生成)
└── presentation_<timestamp>_narrated.pptx ← 同一路线的旁白变体(加 --recorded-narration audio 时生成)
@@ -85,7 +87,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威,但这里的 SVG 专指通过项目合同校验的项目规范化 SVG,而不是任意浏览器可渲染的 SVG。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。模板、`design_spec.md` 和 `spec_lock.md` 负责指导 SVG 创作;导出器不能把它们当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。
-最小语义标记不会削弱这条闭包。自由设计与 brand-only 页面使用 `pptx_structure.mode: flat`:所有已表达对象保持 Slide 本地,不创作任何 Master/Layout 身份、分层或 placeholder metadata。导出器根据当前配色/字体 lock 生成一个属于本项目的干净 Master 和一个 Blank Layout,删除 title/body 等内置内容占位符与未使用的内置 Layout,仅保留标准日期、页脚和页码能力钩子,但不提升任何 Slide 内容。结构化 deck/layout 模板路线上,每张新页面从第一版 SVG 起就声明 Master/Layout 身份。固定 Master/Layout 视觉是根节点直接原子元素;可复用内容槽位是顶层 group,带显式设计区域 bounds 和一个兼容 carrier;复合 `object` 区域走显式 proxy 降级,Layout 也允许零槽。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。带旧结构语义的模板包不能原地升级,也不能作为 Step 3 的 structured 输入:先通过 `create-template` 创建新工作区;原生 PPTX 只提供包内仍然存在的事实,旧 SVG 只作为视觉参考;随后由 Generate PPTX 路线创作新的 structured 页面。flat 项目是有意不带 mapping,不算 legacy。导出器不推断、修补或迁移 Master/Layout 结构与 placeholder。
+最小语义标记不会削弱这条闭包。自由设计、brand-only 和 `template_reuse_scope: style` 页面使用 `pptx_structure.mode: flat`:所有已表达对象保持 Slide 本地,不创作任何 Master/Layout 身份、分层或 placeholder metadata。导出器根据当前配色/字体 lock 生成一个属于本项目的干净 Master 和一个 Blank Layout,删除 title/body 等内置内容占位符与未使用的内置 Layout,仅保留标准日期、页脚和页码能力钩子,但不提升任何 Slide 内容。只有 `template_reuse_scope: mirror|layout` 使用 structured 路线,每张新页面从第一版 SVG 起就声明 Master/Layout 身份。固定 Master/Layout 视觉是根节点直接原子元素;可复用内容槽位是顶层 group,带显式设计区域 bounds 和一个兼容 carrier;复合 `object` 区域走显式 proxy 降级,Layout 也允许零槽。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。带旧结构语义的模板包不能原地升级,也不能作为 Step 3 的 structured 输入:先通过 `create-template` 创建新工作区;原生 PPTX 只提供包内仍然存在的事实,旧 SVG 只作为视觉参考;随后由 Generate PPTX 路线按照已确认的复用范围创作新页面。flat 项目是有意不带 mapping,不算 legacy。导出器不推断、修补或迁移 Master/Layout 结构与 placeholder。
| 领域 | 权威来源 |
|---|---|
@@ -157,14 +159,17 @@ Artifact 的来源 / 派生所有权以 [`artifact-ownership.md`](../../skills/p
```text
sources/<content files> ────────┐
+sources/*.facts.json ───────────┤
analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spec_lock.md
analysis/image_analysis.csv ────┘
spec_lock.md + images/ + icons/ + templates/
+ + templates/template_execution_manifest.json
+ + 当前原型的 templates/template_execution/*.text-slots.json
└─> Executor -> svg_output/
- ├─> svg_quality_checker.py
+ ├─> svg_quality_checker.py -> exports/svg_quality_report.json
├─> finalize_svg.py -> svg_final/
- └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx
+ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx + <output_stem>.report.json
backup/<ts>/svg_output/
直接 OOXML 路由:
@@ -333,7 +338,7 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理
**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式(开放式、对话式、可以回退),Executor 跑的是「产出严格 XML」模式(不准即兴、不准漏属性)。把两者塞进同一个 prompt,强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开,每个角色只加载它需要的、扔掉其他。
-**策略师确认阶段是唯一的阻塞 gate。** Strategist 阶段以一个三阶段确认 gate 作为核心阻塞决策点:第一阶段确认方向锚点(画布、受众、改写幅度、交付目的、mode、visual style,以及只在 Step 3 加载 Deck/Layout 模板时出现的模板遵循方式);第二阶段基于已确认锚点重新推导并确认设计系统(页数、调色板、字体、图标、公式策略);第三阶段基于已确认设计系统重新推导并确认图片与执行方式(图片来源、生成图风格、AI 图片路径、生成模式、refine-spec)。模板遵循默认推荐 `adaptive`:每页仍引用模板架构,但无匹配构图时可在同一 Master 下创建新 Layout;`strict` 则保持所选 Layout 契约不变。最终的 `confirm_ui/result.json` 是权威输入。
+**策略师确认阶段是唯一的阻塞 gate。** Strategist 阶段以一个三阶段确认 gate 作为核心阻塞决策点:第一阶段确认方向锚点(画布、受众、改写幅度、交付目的、mode、visual style,以及 Step 3 加载 Deck/Layout 模板时出现的 `template_reuse_scope`;`template_adherence` 只在 `mirror` / `layout` 下出现);第二阶段基于已确认锚点重新推导并确认设计系统(页数、调色板、字体、图标、公式策略);第三阶段基于已确认设计系统重新推导并确认图片与执行方式(图片来源、生成图风格、AI 图片路径、生成模式、refine-spec)。复用范围默认推荐 `layout`;`style` 选择 flat 自由设计路线,structured 的 `mirror` / `layout` 默认推荐 `adaptive`,允许无匹配构图时在同一 Master 下创建新 Layout;`strict` 则保持所选 Layout 契约不变。最终的 `confirm_ui/result.json` 是权威输入。
**图片分析走重算元数据,不读像素。** 当项目里存在图片时,Strategist 和 Executor 使用 `analyze_images.py` 的输出(`analysis/image_analysis.csv`),而不是直接打开图片文件。这个 CSV 是基于当前 `images/` 目录重算出来的视图,不是持久缓存。每次做图片敏感决策前重跑分析,就是它的防陈旧策略:用户图、抽取图、网络图、AI 图、公式图和切片图最终都会汇入同一张可度量事实表。
@@ -362,7 +367,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
为什么两份都要?没有 `spec_lock.md` 的话,Executor 在长 deck 里会逐页重读 `design_spec.md`,LLM 上下文压缩漂移会逐渐扭曲色值和字体。`spec_lock.md` 是**抗漂移机制**——SKILL.md 强制要求生成每一页前 `read_file <project>/spec_lock.md`,让数值在 20+ 页里保持字面一致。
-这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。结构化 deck/layout 模板项目额外承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;flat 自由设计 / brand-only 项目只保留 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。
+这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。`template_reuse_scope: mirror|layout` 项目额外承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。
`update_spec.py` 把生成后的修改用两个协调步骤传播:把新值写入 `spec_lock.md`,然后字面替换到每一份 `svg_output/*.svg`。工具的范围**故意收得很窄**——只支持 `colors.*`(HEX 值,大小写不敏感替换)和 `typography.font_family`(属性级)。其他字段(字号、图标、图片、画布)**有意不支持**——它们的替换需要属性级或语义级理解,风险/收益不值得做批量传播。这些情况手动改 `spec_lock.md` 然后重做受影响的页面。
@@ -458,6 +463,8 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路
| `svg_output/` | 唯一源、手工编辑入口、`update_spec.py`、`svg_quality_checker.py` | 流水线中唯一**手写**而非派生的目录 |
| `svg_final/` | IDE 内即时预览(VSCode/Cursor 直接打开 `.svg`)、浏览器单页预览、手动作为 SVG 图片插入 | `.pptx` 在 IDE 里打不开;`svg_output/` 因图标 / 图片是外部引用,IDE 中渲染不完整。PowerPoint 手工“转换为形状”不在支持范围 |
| `exports/<name>_<ts>.pptx`(native) | 主交付物——PowerPoint 中以 DrawingML 形状形态可编辑 | 唯一一份用户可在 PowerPoint 中原生改尺寸 / 改色 / 改样式的产物 |
+| `exports/svg_quality_report.json` | 机器可读的最终 SVG 门禁 | 把阻断错误、新增提示、原型继承项和来源导入损失分开,并为受检 SVG 字节生成指纹 |
+| `<output_stem>.report.json` | 已发布 PPTX 的 postflight 与资源审计 | 记录实际 ZIP/package part 数量;重新检查 ZIP 与正式页数;把内部关系、结构化包、转场和动画如实标为构建期强制校验;只有 SHA-256 指纹与导出输入一致时才接受质量报告关联,同时暴露未解析变量、外部图片和纯通用字体栈 |
| `exports/<name>_<ts>_native_charts_tables.pptx`(需 `--native-charts-and-tables` 显式开启) | 让带 `data-pptx-replace-with` 标记的 SVG 派生形状图表/表格替换为 PowerPoint 原生 Chart/Table 对象 | 带数据源和图表/表格专属控制的对象;默认 DrawingML shape 本身仍可独立编辑 |
| `exports/<name>_<ts>_narrated.pptx`(经 `--recorded-narration audio` 生成) | 自动放映与 PowerPoint 视频导出用的旁白版 deck | 逐页嵌入音频并写入自动推进时间;命名与无声导出区分开 |
| `backup/<ts>/svg_output/`(默认流程下始终生成) | 不重跑 LLM 的前提下从冻结 SVG 源重建 pptx、长期存档 | 项目下游被改动后,Executor 原始 SVG 唯一的留存副本 |
@@ -511,7 +518,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路
**为什么只有一条 PPTX 编译路线。** Native 导出把作者 SVG 中受支持的元素逐个翻译成 DrawingML 形状。常规 deck 路线读取 `svg_output/`;用户需要时,create-template 对通过校验的模板原型调用同一 structured 编译器,生成 `exports/<id>_template_preview.pptx` 作为审阅证据。项目不会把整页 SVG 媒体或另一套位图渲染打包成第二类 PPTX。`svg_final/` 仍由常规 deck 的强制后处理生成,但只承担自包含视觉预览和 SVG 图片插入,不为 PowerPoint 手工“转换为形状”提供兼容兜底。
-**为什么模板路线的结构必须在视觉生成前确定。** Master 和 Layout 不是后处理阶段才发现的结果。在结构化 deck/layout 模板路线上,Strategist 在 SVG 生成前写出唯一 Master/Layout 定义和完整页面分配;Executor 在构图时同步写入这些身份、固定原子元素和槽位,导出器只编译声明。自由设计与 brand-only deck 做的是相反的取舍:保持 `mode: flat`,所有对象留在 Slide 本地,不写任何结构 metadata,导出时只获得一个属于本项目的干净 Master/Blank-Layout 壳——可复用结构是模板路线的交付物,不是自由设计的创作税。旧输入可以为新的 `create-template` 工作区提供参考,但不存在原地升级结构的路线;两种生成模式都不会触发启发式 Master/Layout 提升或 placeholder 推断。
+**为什么结构化复用路线必须在视觉生成前确定结构。** Master 和 Layout 不是后处理阶段才发现的结果。使用 `template_reuse_scope: mirror|layout` 时,Strategist 在 SVG 生成前写出唯一 Master/Layout 定义和完整页面分配;Executor 在构图时同步写入这些身份、固定原子元素和槽位,导出器只编译声明。`template_reuse_scope: style`、自由设计与 brand-only deck 做的是相反的取舍:保持 `mode: flat`,所有对象留在 Slide 本地,不写任何结构 metadata,导出时只获得一个属于本项目的干净 Master/Blank-Layout 壳。旧输入可以为新的 `create-template` 工作区提供参考,但不存在原地升级结构的路线;两种生成模式都不会触发启发式 Master/Layout 提升或 placeholder 推断。
**为什么 Master/Layout 视觉必须原子化。** 一个 Master 或固定 Layout 对象必须是根节点的直接子元素。导入 PPTX 时,group 的 transform、opacity、style 和 z-order 会下推到各个原子对象。这个选择有意放弃来源 group 的整体编辑层级,换取简单、可比较、可确定重建的结构归属,避免嵌套结构歧义。
@@ -519,7 +526,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路
**为什么可复用 bounds 是设计区域,不是量出来的文本框。** bounds 来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容紧包围盒。当前 Slide 保留自己的 carrier 几何,因此只要语义构图相同,4:6、3:7、5:5 的实例都可复用同一 Layout。文本长度不会意外拆分或改变可复用合同。
-**为什么 strict 与 adaptive 模板共享一条 structured 路线。** `page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才定义新 Layout,并在页面创作时立即更新分配,而不是事后推断。模板定义即使暂时没有页面使用,也能注册进最终文件。非 mirror 的皮肤由项目控制;mirror 保持新工作区声明的已保留视觉身份。
+**为什么复用范围与遵循方式要拆开。** `template_reuse_scope` 先选择字面镜像复用、结构化版式复用或 flat 风格参考。只有 `mirror` 和 `layout` 再在 structured 路线上使用 `template_adherence: strict|adaptive`:`page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时才定义新 Layout,并在页面创作时立即更新分配,而不是事后推断。模板定义即使暂时没有页面使用,也能注册进最终文件。layout 的皮肤由项目控制;mirror 还要保持字面视觉与文字节点拓扑。`style` 不带 adherence 或结构 mapping。
**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把锁定的 title 字号和确定性的九级 body 层级写入 Master 文本默认值,同时保留原有缩进与项目符号设置;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 2dc48927..a831259d 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -38,7 +38,7 @@ description: >
> 5. **NO SPECULATIVE EXECUTION** — "Pre-preparing" content for subsequent Steps is FORBIDDEN (e.g., writing SVG code during the Strategist phase)
> 6. **NO SUB-AGENT SVG GENERATION** — Executor Step 6 SVG generation is context-dependent and MUST be completed by the current main agent end-to-end. Delegating page SVG generation to sub-agents is FORBIDDEN
> 7. **SEQUENTIAL PAGE GENERATION ONLY** — In Executor Step 6, after the global design context is confirmed, SVG pages MUST be generated sequentially page by page in one continuous pass. Grouped page batches (for example, 5 pages at a time) are FORBIDDEN
-> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also read `pptx_structure.mode`, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), and `page_charts`. Only a deck/layout template route (`mode: structured`) looks up `page_layouts` (the input template SVG), `page_pptx_layouts` (the page assignment), `pptx_masters`, `pptx_layouts` (the unique reusable roster), and `template_adherence`; free-design and brand-only routes use `mode: flat` and omit those sections. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
+> 8. **SPEC_LOCK RE-READ PER PAGE** — Before generating each SVG page, Executor MUST `read_file <project_path>/spec_lock.md`. All colors / fonts / icons / images MUST come from this file — no values from memory or invented on the fly. Executor MUST also read `pptx_structure.mode`, `template_reuse_scope`, the current page's `page_rhythm` (`anchor` / `dense` / `breathing`), and `page_charts`. `template_reuse_scope: mirror|layout` uses `mode: structured` and looks up `page_layouts` (the input template SVG), `page_pptx_layouts` (the page assignment), `pptx_masters`, `pptx_layouts` (the unique reusable roster), and `template_adherence`; `template_reuse_scope: style`, free-design, and brand-only routes use `mode: flat` and omit those sections. This rule exists to resist context-compression drift on long decks and to break the uniform "every page is a card grid" default
> 9. **SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED** — Every SVG page is written by the main agent directly, one page at a time (see rules 6 and 7). Writing or running a Python / Node / shell script that produces the SVG files in batch — looping over pages, templating from data, or emitting them via a generator — is FORBIDDEN, including under "save tokens", "quick draft", or "user is in a hurry" pretexts. The script-generation path was tried on a feature branch and abandoned: cross-page visual consistency depends on per-page authoring with full upstream context, which a generator script cannot reproduce. **Narrow exception**: `preset_shape_svg.py` may print one deterministic stock-shape fragment to stdout after the main agent has selected its semantic role, frame, and paint. It cannot write `svg_output/`, choose layout, batch shapes, or generate a page; the main agent reads the fragment and inserts it through the normal hand-authored page edit
> 10. **FOLLOW DETERMINISTIC ROUTING RULES** — Do not add blocking routing questions when this skill defines a route. If the user request violates a route precondition, state the required prerequisite and stop that route instead of asking the user to choose around the rule. Ordinary finite options, stylistic preferences, and recoverable details are surfaced with a recommended value plus alternatives at the next existing confirmation gate.
@@ -330,7 +330,7 @@ A project-scoped workspace has the same portable routing as a library workspace.
Legacy template packages may ship `native_structure.json` + `source_template.pptx`, omit root Master identity, use direct atomic placeholders, or carry old baseline/distillation metadata. Do not copy, consume, or migrate those semantic contracts through Step 3. Create a new workspace through [`create-template`](workflows/create-template.md), preferably from the original PPTX when existing native topology matters, then return with that new workspace root. Old flat packaging remains readable when its SVG structure is already current.
-The Strategist confirmation stage decides whether the selected deck/layout template is used `strict` or `adaptive`. Those template projects use `pptx_structure.mode: structured`, map every page to one input SVG in `page_layouts`, declare unique reusable identities in `pptx_masters` / `pptx_layouts`, and assign each page through `page_pptx_layouts` before SVG generation. A Layout definition may remain unused by generated pages when it names an installed template SVG as its prototype source. Brand-only projects remain on the free-design `mode: flat` route. Strict preserves the template's declared Master/Layout/slot contract. Adaptive keeps the template Master and may define and assign a new Layout key during authoring when the composition genuinely changes. Non-mirror paint and typography follow the project skin rules.
+The Strategist confirmation stage first decides the selected deck/layout template's `template_reuse_scope`: `mirror`, `layout`, or `style`. `mirror` and `layout` use `pptx_structure.mode: structured`, map every page to one input SVG in `page_layouts`, declare unique reusable identities in `pptx_masters` / `pptx_layouts`, and assign each page through `page_pptx_layouts` before SVG generation. Their second axis, `template_adherence`, is `strict` or `adaptive`: strict preserves the declared Master/Layout/slot contract; adaptive keeps the template Master and may define a new Layout key when the reusable composition genuinely changes. `mirror` is offered only for a workspace whose frontmatter declares `replication_mode: mirror`; it preserves literal visuals and text-node topology. `layout` reuses the structure system without literal mirror visual protection. `style` extracts only color, typography, decoration language, and rhythm, then uses the free-design `mode: flat` route with no template structure mappings. User phrases such as “不要严格复用”, “只参考风格”, or “不必照搬版式” deterministically recommend `style` (or `layout` when they explicitly want the layout system); only “原样复刻”, “替换内容”, or “保持模板页面外观” recommends `mirror`. Brand-only projects remain on `mode: flat`.
#### Multi-path fusion
@@ -416,7 +416,7 @@ Read references/strategist.md
2. Page count range
3. Target audience
4. Style objective
-5. Template adherence — `strict` / `adaptive` (only when Step 3 loaded a deck/layout template)
+5. Template reuse scope — `mirror` / `layout` / `style`; then template adherence — `strict` / `adaptive` only for `mirror` / `layout` (deck/layout templates only)
6. Color scheme
7. Icon usage approach
8. Typography plan, including formula rendering policy
@@ -426,7 +426,7 @@ Read references/strategist.md
| Stage | Confirms | Driven by |
|---|---|---|
-| **1 — direction anchors** | canvas · audience + core message + `content_divergence` + `delivery_purpose` *(PPT only — omitted on non-PPT canvases)* (all §c key info) · `mode` + `visual_style` · `template_adherence` *(only when Step 3 loaded a deck/layout template)* | the source + user intent |
+| **1 — direction anchors** | canvas · audience + core message + `content_divergence` + `delivery_purpose` *(PPT only — omitted on non-PPT canvases)* (all §c key info) · `mode` + `visual_style` · `template_reuse_scope`, then `template_adherence` for `mirror` / `layout` *(only when Step 3 loaded a deck/layout template)* | the source + user intent |
| **2 — design system** (re-derived from Stage 1) | page count · color · typography (font + size) · icons · formula policy | the confirmed Stage 1 |
| **3 — images / execution** (re-derived from Stage 1 + Stage 2) | image usage · generated-image style · AI-image generation path · generation mode · refine-spec toggle | the confirmed direction + design system |
@@ -436,7 +436,7 @@ Steps:
> ⛔ **Steps 2 → 3 → 4 are ONE uninterrupted run — do NOT yield to the user mid-flow.** When an intermediate `--wait` returns, the AI **immediately and autonomously** re-derives and writes the next stage in the **same turn**: do **not** summarize, ask a question, report progress, or end the turn in between. The browser is sitting on a "deriving…" spinner polling for the next stage you must write — stopping here strands the page and the user must prod you in chat to finish (a bug, not the intended flow). **Stage-1 and Stage-2 confirmations are intermediate machine handoffs, not stopping points.** The single ⛔ BLOCKING wait is the **final** confirmation at the end of step 4. (Chat-fallback path — only when the page never opened — is the exception: there you do present each stage in chat and wait for a reply.)
-1. **Write Stage 1** to `<project_path>/confirm_ui/recommendations.json` with `"stage": "stage1"` and only the anchor fields. New recommendations MUST use the canonical `stage` selector. Enumerable anchors (`canvas` / `mode` / `visual_style` / `delivery_purpose`) name a recommended canonical `id` in a `recommend` block (the page lists common options from `confirm_ui/static/catalogs.json`); `visual_style` also carries the ≥3-style `visual_style_spectrum` (safe / shifted / bold — same hard rule as h.5). When Step 3 loaded a deck/layout template, also set `recommend.template_adherence` to `strict` or `adaptive`; omit the field entirely for free design and brand-only templates so the page does not display it. `audience` and `content_divergence` are plain `{ "value": "<free text>" }`. `content_divergence` is the **free-text** field shown under audience in §c — how closely to follow the source vs how freely to reshape it (blank = balanced; facts stay sourced at every level); it is consumed by Strategist when authoring `§IX`, recorded in `design_spec.md §I`, carries no page-count coupling, and is **not** written to `spec_lock.md`. Set `lang` to the page language (`zh` / `en` / `ja`); visible text matches `lang`, or provide multilingual `name_zh` / `name_en` / `name_ja` + `note_zh` / `note_en` / `note_ja` — when the user's language is Japanese, set `lang: "ja"` and always include the `_ja` variants (labels resolve in the page language first — a `ja` page falls back ja → en → zh, so missing `_ja` labels silently render in English; zh/en pages keep their zh↔en fallback and only try `_ja` last).
+1. **Write Stage 1** to `<project_path>/confirm_ui/recommendations.json` with `"stage": "stage1"` and only the anchor fields. New recommendations MUST use the canonical `stage` selector. Enumerable anchors (`canvas` / `mode` / `visual_style` / `delivery_purpose`) name a recommended canonical `id` in a `recommend` block (the page lists common options from `confirm_ui/static/catalogs.json`); `visual_style` also carries the ≥3-style `visual_style_spectrum` (safe / shifted / bold — same hard rule as h.5). When Step 3 loaded a deck/layout template, set `recommend.template_reuse_scope` to `mirror`, `layout`, or `style`; `mirror` is valid only when the installed workspace declares `replication_mode: mirror`. Set `recommend.template_adherence` to `strict` or `adaptive` only when the reuse scope is `mirror` or `layout`; `style` hides adherence and later writes `pptx_structure.mode: flat`. Omit both fields entirely for free design and brand-only templates. `audience` and `content_divergence` are plain `{ "value": "<free text>" }`. `content_divergence` is the **free-text** field shown under audience in §c — how closely to follow the source vs how freely to reshape it (blank = balanced; facts stay sourced at every level); it is consumed by Strategist when authoring `§IX`, recorded in `design_spec.md §I`, carries no page-count coupling, and is **not** written to `spec_lock.md`. Set `lang` to the page language (`zh` / `en` / `ja`); visible text matches `lang`, or provide multilingual `name_zh` / `name_en` / `name_ja` + `note_zh` / `note_en` / `note_ja` — when the user's language is Japanese, set `lang: "ja"` and always include the `_ja` variants (labels resolve in the page language first — a `ja` page falls back ja → en → zh, so missing `_ja` labels silently render in English; zh/en pages keep their zh↔en fallback and only try `_ja` last).
2. **Launch + wait for Stage 1.** Background launch; the parent returns when the page writes the stage-1 `result.json`. **Long tool timeout — 600000 ms** (the `--wait` ≈590 s budget):
```bash
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait
@@ -462,6 +462,8 @@ Steps:
**Honoring the confirmation (result.json is authoritative — Mandatory)**: the confirmed values **override your own recommendations** when you write `design_spec.md` / `spec_lock.md`. A user who changed any field changed it on purpose. In particular, map `image_usage` to §VIII `Acquire Via` (its value names differ from §h options — translate). `image_usage` may be either a legacy single string or a Confirm UI multi-select array; for arrays, apply every selected source. `image_notes`, when present, is a user-authored image intent note that Strategist must honor while assigning per-page §VIII rows:
+For a confirmed template route, map `template_reuse_scope` mechanically: `style` → `pptx_structure.mode: flat` and omit `template_adherence`, `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`; `layout` / `mirror` → `mode: structured`, retain the confirmed `template_adherence`, and write the complete mappings. Never infer mirror behavior from the template workspace's `replication_mode` alone—the confirmed reuse scope is the downstream execution authority.
+
| `result.json.image_usage` | §VIII `Acquire Via` | h.5 + Step 5 generation |
|---|---|---|
| `ai` | `ai` rows | Run h.5 (lock rendering + palette); Step 5 generates |
@@ -644,11 +646,11 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/stages/live-preview.md`](workflows/stages/live-preview.md).
- The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/stages/live-preview.md`](workflows/stages/live-preview.md) Notes.
-**Pre-generation Batch Read (Mandatory)**: before the first SVG, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` and every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts). One read per file, up front — do not re-read these during page generation. See executor-base.md §1.0.
+**Pre-generation Template Read (Mandatory)**: first read `templates/template_execution_manifest.json` when present. It is the compact prototype roster and points each prototype to one `text_slots_path`. Use the roster to select prototypes; before each mirror page, read that prototype's text-slot sidecar and complete `templates/<basename>.svg`. Layout reuse reads the selected complete SVG but does not apply mirror-only text topology restrictions. When the manifest is absent, batch-read every distinct layout SVG referenced in `spec_lock.page_layouts` once before the first page. In both cases, batch-read every distinct chart SVG referenced in `spec_lock.page_charts` (plus any §VII backup charts) once up front. Do not substitute a manifest or sidecar for the selected full prototype. See executor-base.md §1.0.
> Image facts: trust the `analysis/image_analysis.csv` regenerated at the end of Step 5. If `images/` changed since (the user swapped or added files), re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before laying images out — facts are re-derived on use, never a stale store (Step 4 image-facts note).
-**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus `pptx_structure.mode` and the per-page `page_rhythm` / `page_charts` lookups. Read `page_layouts` / `page_pptx_layouts` / `pptx_masters` / `pptx_layouts` only on a structured deck/layout template route; they are absent in flat free-design and brand-only projects. Resists context-compression drift on long decks. See executor-base.md §2.1.
+**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images, plus `pptx_structure.mode`, `template_reuse_scope`, and the per-page `page_rhythm` / `page_charts` lookups. Read `page_layouts` / `page_pptx_layouts` / `pptx_masters` / `pptx_layouts` only on a structured `template_reuse_scope: mirror|layout` route; they are absent in flat `style`, free-design, and brand-only projects. Resists context-compression drift on long decks. See executor-base.md §2.1.
> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.
> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).
@@ -657,26 +659,27 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Before drawing a literal stock shape, apply [`native-shape-authoring.md`](references/native-shape-authoring.md): use the stdout-only helper when one PowerPoint preset exactly matches, keep basic SVG primitives for rect/round-rect/ellipse, and keep free SVG for custom semantics. Diagram relationships are Shape-first: use ordinary line/path shapes with registered arrow markers for thin edges and ordinary shape presets for solid block arrows; do not default to connector-family presets or author attachment metadata. Never infer a preset from contour similarity.
-Template pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. Non-mirror fill/stroke/effects/font sizes still follow `spec_lock`.
+`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. `layout` pages may reflow and re-skin to the project lock; `mirror` pages preserve literal visuals and may change only visible `<text>` / `<tspan>` values while keeping text/tspan count, order, nesting, and every attribute unchanged. `template_reuse_scope: style` follows the flat free-design paragraph below and does not inherit template structure metadata.
-Free-design and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.
+`template_reuse_scope: style`, free-design, and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.
Do not duplicate specialized identity with `data-pptx-role`. Add it only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by `data-pptx-layer`, `data-pptx-placeholder`, or `data-pptx-replace-with`; such an element needs a stable unique `id`. Do not add generic content roles to ordinary titles, body text, cards, KPIs, diagrams, charts, icons, or images. Full contract: [`references/semantic-svg.md`](references/semantic-svg.md).
**First-page gate (Mandatory)** — after the **first** SVG page, before drawing page 2:
```bash
-python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>/svg_output/<first_page>.svg
+python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page
```
Fix every `error` on page 1 first — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite.
**Quality Check Gate (Mandatory)** — after all SVGs, BEFORE annotation handling and speaker notes:
```bash
-python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
+python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json
```
- Any `error` (banned/unsupported SVG features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.
- Every `warning` is advisory and non-blocking: do not return the page for mandatory modification, do not auto-normalize user-authored compatible syntax, and do not require an acknowledgement/disposition line. Recommendation warnings identify the generated-SVG default; fidelity/quality warnings may be reported when material, but the existing input may ship unchanged. If a condition must be corrected before release, the checker must classify it as an `error`, not a `warning`.
-- The same rule applies to structured-template warnings (empty/framing-only Layout, bare Master, duplicate layout keys): they may guide an optional template cleanup, but warnings alone never fail the quality gate. Flat free-design and brand-only routes still rely on their existing hard errors for invalid structure metadata or incomplete required locks.
+- The same rule applies to structured-template warnings (empty/framing-only Layout, bare Master, duplicate layout keys): they may guide an optional template cleanup, but warnings alone never fail the quality gate. Flat `style`, free-design, and brand-only routes still rely on their existing hard errors for invalid structure metadata or incomplete required locks.
- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).
+- The JSON report is written to `exports/svg_quality_report.json`. `inherited` prototype diagnostics and `source-import` compatibility losses are informational provenance; only changed/new warnings remain `introduced`, and all release-blocking failures remain `blocking`.
**Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`
@@ -730,6 +733,7 @@ This mandatory step writes self-contained visual-preview SVGs to `svg_final/`. T
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
# Output (default-flow mode):
# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output, reads svg_output/)
+# exports/<project_name>_<timestamp>.report.json ← package/resource/quality postflight audit
# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)
# backup/<timestamp>/templates/native_payloads.json.gz
# ← copied when compact native metadata refs are used
@@ -761,6 +765,15 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> exports. `-s final` is diagnostic-only
> when comparing conversion behavior against the post-processed SVGs; it does
> not change `svg_output/` ownership or establish a supported release route.
+> Every successful export also writes `<output_stem>.report.json`. It separates
+> formal Slides from internal Layout-definition inputs, counts Notes/Masters/
+> Layouts from the finished package, reruns ZIP-integrity and published-Slide
+> checks, labels relationship/structured/transition/animation validation as
+> enforced at build time, inventories unresolved template tokens, generic-only
+> font stacks, and image references, records the backup/trace paths, and links
+> final SVG quality categories only when the report's SHA-256 source fingerprint
+> matches the exact export inputs. A stale or unverified quality gate leaves the
+> successful package as `passed-with-warnings`.
> **Supported PPTX boundary** — the only supported generated-PPTX path is
> `svg_output/` → the project SVG-to-DrawingML converter → native PPTX. The
@@ -770,7 +783,8 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> results of an unsupported Office conversion.
> **PPTX structure mode** — release export reads the explicit route from
-> `spec_lock.md`. Free-design and brand-only projects use
+> `spec_lock.md`. Free-design, brand-only, and `template_reuse_scope: style`
+> projects use
> `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` /
> `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata in
> SVG. Export keeps every represented object Slide-local while materializing
@@ -778,7 +792,8 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> stock content placeholders and unused built-in Layouts are removed; only the
> standard date/footer/slide-number capability hooks remain.
>
-> Deck/layout template projects use `pptx_structure.mode: structured`, a
+> Deck/layout template projects confirmed with `template_reuse_scope:
+> mirror|layout` use `pptx_structure.mode: structured`, a
> complete `pptx_masters` roster, one unique `pptx_layouts` definition per
> reusable Layout, and exactly one `page_pptx_layouts` assignment per page.
> A Layout definition records Master key, PowerPoint picker name, and either a
@@ -807,14 +822,17 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
> structured SVG pages from that workspace before export.
-> **Template structured export** — `page_layouts` records the complete
+> **Template structured export** — `template_reuse_scope: mirror|layout` uses
+> `page_layouts` to record the complete
> input prototype per page, `pptx_masters` / `pptx_layouts` record the unique
> reusable output roster, and `page_pptx_layouts` records page assignment.
> Strict keeps the prototype
> Master/Layout/slot contract. Adaptive keeps its Master and may assign a new
> Layout identity during page authoring only when fixed Layout atoms or slot
-> topology/bounds change; the lock is updated immediately. Non-mirror skin
-> remains project-controlled, mirror preserves the reused visual identities,
+> topology/bounds change; the lock is updated immediately. `layout` skin
+> remains project-controlled; `mirror` preserves literal visuals and text-node
+> topology. `template_reuse_scope: style` uses `mode: flat` and omits all
+> structure mappings,
> and the exporter never reads a template to add visible objects missing from
> `svg_output/`. Raw PPTX templates still route to `template-fill-pptx`;
> reusable template creation goes through `create-template`.
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index 2bb09787..2a33a7de 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -11,6 +11,7 @@ Global artifact ownership rules for PPT Master projects.
| Artifact | Owner | Role | Read/write contract |
|---|---|---|---|
| `sources/` content-type files | Content contract | Main pipeline source for text, tables, chart data values, and SmartArt node wording | Strategist reads content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judges by content; do not replace values with PPTX geometry JSON in the main pipeline |
+| `sources/*.facts.json` | Fact provenance contract | Stable external `fact_id` → claim/source mapping created by topic research | Strategist cites IDs in §IX; Executor resolves them for visible footnotes / natural notes attribution. Scenario data never enters this file. |
| `sources/` converted-source originals | Source archive | Imported source files that have a converted content contract (`.pdf` / `.pptx` / `.docx` / `.xlsx` / `.html` / `.epub` / `.tex` / `.rst` / `.ipynb` / `.typ`, etc.) and source-adjacent extracted assets | Read via the converted `<stem>.md` in the main pipeline; direct-PPTX workflows read the `.pptx` by route |
| `sources/*.conversion_profile.json`, `sources/*_files/image_manifest.json` | Pipeline sidecar | Conversion audit record / asset index | NOT read as slide content; open only to audit a conversion or resolve assets |
| `analysis/source_profile.json` | Machine fact index | Compact Strategist-facing PPTX intake digest | Main pipeline reads as factual context and recommendation candidates |
@@ -18,10 +19,11 @@ Global artifact ownership rules for PPT Master projects.
| `analysis/<stem>.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches, SmartArt nodes/connections | Direct PPTX workflows use as native fill/structure contract |
| `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes |
| `design_spec.md` | Human design narrative | Explains design intent, outline, rationale, and resource plan | Strategist writes; humans and later roles read for intent |
-| `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, charts, and the route's PowerPoint structure mode; deck/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist writes the route-specific contract; Executor re-reads it before every page and may add a new adaptive Layout identity only on a structured template route while authoring the page that first needs it |
+| `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, charts, `template_reuse_scope`, and the route's PowerPoint structure mode; mirror/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist writes the route-specific contract; Executor re-reads it before every page and may add a new adaptive Layout identity only on a structured mirror/layout route while authoring the page that first needs it |
| `images/` | Runtime image pool | User, extracted, AI, web, formula, slice, EMF/WMF assets | Step 5 writes here; `analysis/image_analysis.csv` derives from current contents |
| `icons/` | Project icon inventory | Icons copied by `icon_sync.py` for this project | Executor uses locked project icons; exporter may fall back to global library only as documented |
| `templates/` | Project template reference | Step 3 imported specs, template SVGs, and non-image assets | Strategist/Executor read only when Step 3 is triggered |
+| `templates/template_execution_manifest.json` + `templates/template_execution/*.text-slots.json` | Model-readable template execution index | Compact prototype roster and source-import summary plus per-prototype exact mirror-safe text-slot selectors/topology | Read the roster once; before each mirror page, read only the selected text-slot sidecar and complete template SVG. Layout reuse needs the complete SVG but not the mirror-only sidecar. Never author from either JSON artifact alone. |
| `<import_workspace>/svg/` | Imported native-payload backing | Complete PPTX-derived metadata, hidden carriers, fallback evidence, and source structure | Keep immutable; create-template materialization may resolve a validated source ref against these files, but models do not edit or bulk-read them |
| `<import_workspace>/svg-flat/` | Optional complete-page verification backing | Self-contained visual composition generated only by explicit `--inheritance-mode both` | Keep immutable when requested; never use as authoring or materialization input |
| `<import_workspace>/authoring-svg/` | Template-creation author source | Layered editable SVG IR for imported Master, Layout, and Slide objects | Template_Designer reads and edits this bundle; final template SVGs are materialized from it rather than copied from lossless backing |
@@ -35,7 +37,8 @@ Global artifact ownership rules for PPT Master projects.
| `notes/total.md` | Speaker-note source | Complete notes before splitting | Step 6 writes; Step 7.1 splits |
| `notes/slide_*.md` | Split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` |
| `svg_final/` | Derived visual preview | Self-contained post-processed SVGs that may be opened directly or inserted as SVG pictures | Rebuild from `svg_output/` with `finalize_svg.py`; do not use as a supported PPTX source |
-| `exports/` | Delivery artifacts | Native DrawingML PPTX and its explicit native-object/narration variants | Step 7.3 writes final outputs from `svg_output/` |
+| `exports/svg_quality_report.json` | Quality provenance | Final SVG gate split into blocking / introduced / inherited / source-import categories, bound to the checked SVG bytes by SHA-256 | `svg_quality_checker.py --stage final --json` writes before export; postflight links it only when the export-source fingerprint matches. |
+| `exports/` | Delivery artifacts | Native DrawingML PPTX, `<output_stem>.report.json` postflight audit, and explicit native-object/narration variants | Step 7.3 writes final outputs from `svg_output/` |
| `backup/<timestamp>/svg_output/` | Frozen author-source archive | Re-export source without re-running LLM | `svg_to_pptx.py` writes a snapshot during export |
| `animations.json` | Optional animation config | Object-level animation sidecar | Created only by explicit animation workflow/request |
@@ -49,8 +52,9 @@ Global artifact ownership rules for PPT Master projects.
| Sources read policy | In `sources/`, read content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judge by content — a `.json` / `.csv` may be core content or just data. Exclude known sidecars: `*.conversion_profile.json` and `*_files/image_manifest.json`. `analysis/` facts (`source_profile.json`, `<stem>.slide_library.json`) are read per Step 4 / direct-PPTX workflow, not in the `sources/` content scan. |
| PPTX structure | `slide_library.json` owns native geometry, slot facts, and SmartArt layout/relationships for direct PPTX workflows. |
| Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. |
-| Free-design / brand-only packaging authority | `spec_lock.md` declares `pptx_structure.mode: flat` and omits `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. `svg_output/` owns the complete Slide-local visual design without root Master/Layout identity, fixed-layer ownership, or placeholder metadata. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme defaults, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. |
-| Template structure authority | `page_layouts` owns each page's authoring-input prototype. `pptx_masters` / `pptx_layouts` own the unique reusable output definitions, while `page_pptx_layouts` owns page assignment. Strict keeps the prototype contract; adaptive may create a new Layout definition during page authoring and updates its assignment immediately. Unused definitions may register without a published Slide. Templates validate provenance but never add missing visible page objects during export. |
+| Flat packaging authority | Free-design, brand-only, and `template_reuse_scope: style` declare `pptx_structure.mode: flat` and omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. `svg_output/` owns the complete Slide-local visual design without root Master/Layout identity, fixed-layer ownership, or placeholder metadata. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme defaults, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. |
+| Template structure authority | `template_reuse_scope: mirror|layout` uses `page_layouts` for each page's authoring-input prototype. `pptx_masters` / `pptx_layouts` own the unique reusable output definitions, while `page_pptx_layouts` owns page assignment. Strict keeps the prototype contract; adaptive may create a new Layout definition during page authoring and updates its assignment immediately. Mirror additionally preserves literal visuals/text topology; layout allows project-controlled reflow/re-skinning. Unused definitions may register without a published Slide. Templates validate provenance but never add missing visible page objects during export. |
+| Fact classes | External facts resolve through `sources/*.facts.json`; invented demo KPIs/targets/internal ratios are labeled `scenario` in `design_spec.md §IX` and visibly in the page. Never promote scenario data into the external fact registry. |
| Imported-template authoring | Editable SVGs under `authoring-svg/` own create-template edits, `authoring_summary.json` owns model-facing orientation, and `authoring_manifest.json` owns tool-only source-object identity. Lossless `svg/` owns immutable native payload and fallback evidence; optional `svg-flat/` owns only complete-page verification. Materialized `templates/*.svg` own the validated deliverable contract and contain no IR-only source refs. |
| Legacy template input | Old unmapped/distilled/preserve structured projects and incomplete template packages are not migrated in place. [`create-template`](../workflows/create-template.md) authors a new current workspace: original PPTX Type A may preserve existing native topology in mirror; legacy SVG-only Type B is visual reference for `standard` / `fidelity`. An intentional free-design or brand-only `flat` project is already current. The exporter does not migrate or visually cluster legacy structure. |
| Image facts | `images/` is live state; `analysis/image_analysis.csv` is a regenerated view, not a durable cache. |
@@ -74,6 +78,7 @@ Global artifact ownership rules for PPT Master projects.
| `<import_workspace>/authoring-svg/authoring_summary.json` | Current authoring SVGs plus tool-only manifest roster | `python3 ${SKILL_DIR}/scripts/svg_authoring_view.py <import_workspace>/authoring-svg --refresh-summary`; in-place vector/picture extraction refreshes it automatically |
| `notes/slide_*.md` | `notes/total.md` | `python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>` |
| `svg_final/` | `svg_output/` plus project assets | `python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>` |
-| Native PPTX | `svg_output/` plus notes/assets | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>` |
+| `exports/svg_quality_report.json` | `svg_output/`, locks, template provenance | `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json` |
+| Native PPTX + `<output_stem>.report.json` | `svg_output/` plus notes/assets and final quality report | `python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>` |
**Default - regenerate derived views**: When a source artifact changes, regenerate the derived artifact at the owning step instead of patching the derived file directly.
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 9cade6df..da063da8 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -4,7 +4,7 @@
**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.
-**Hard rule — route-specific PowerPoint structure**: Free-design and brand-only projects 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`). Export materializes one clean project-owned Master plus one Blank Layout from the current lock. Deck/layout template projects use `mode: structured`: every page reads its locked Master/Layout row and declares the four root identity attributes from the first draft. Do not add `data-pptx-layout-kind` or duplicate identity with `data-pptx-page-role`. 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).
+**Hard rule — route-specific PowerPoint structure**: Free-design, brand-only, and `template_reuse_scope: style` projects 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`). Export materializes one clean project-owned Master plus one Blank Layout from the current lock. `template_reuse_scope: mirror|layout` projects use `mode: structured`: every page reads its locked Master/Layout row and declares the four root identity attributes from the first draft. Do not add `data-pptx-layout-kind` or duplicate identity with `data-pptx-page-role`. 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).
**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.
@@ -12,41 +12,40 @@
---
-## 1. Template Adherence Rules
+## 1. Template Reuse Rules
-### 1.0 Pre-generation Batch Read
+### 1.0 Pre-generation Template Read
-**Hard rule**: Before the first SVG page, batch-read every template SVG this deck will reference. Read once up front, never re-read during generation.
+**Hard rule**: Read the compact template roster once, but never treat a summary as the full page prototype.
| Source list | Read path |
|---|---|
-| Chosen template's `design_spec.md` (read frontmatter to detect `replication_mode`) | `templates/design_spec.md` |
-| Every distinct `<basename>` in `spec_lock.md page_layouts` | `templates/<basename>.svg` |
+| Chosen template's `design_spec.md` (template capabilities) | `templates/design_spec.md` |
+| Model-readable execution roster, when present | `templates/template_execution_manifest.json` |
+| Selected mirror prototype's text-slot sidecar | The roster entry's `text_slots_path` under `templates/` |
| Every distinct chart name in `spec_lock.md page_charts` | `templates/charts/<chart_name>.svg` |
| Chart types in `design_spec.md §VII` not covered above | `templates/charts/<chart_name>.svg` |
-**Default — read each template once; re-read only on the mid-deck exception below**:
-- Layout SVG already loaded in this batch
-- Chart SVG already loaded in this batch
+When `template_execution_manifest.json` exists, read its compact page roster once for selection/orientation. Before authoring each mirror page, read that roster entry's `text_slots_path` for selectors, current segments, bounds, font stacks, tspan attributes, and topology hashes, then read the selected complete `templates/<basename>.svg`; the SVG is the visual/structural authority. Layout reuse reads the selected complete SVG but does not need the mirror-only sidecar. When the manifest is absent, batch-read every distinct `<basename>` in `spec_lock.md page_layouts` before page 1 as the compatibility fallback. Chart SVGs remain one-time batch reads.
`spec_lock.md` is the only file re-read per page (§2.1).
-**Exception**: user mid-deck adds pages or swaps templates introducing a basename/chart absent from the original batch → read the new file once, continue.
+**Exception**: user mid-deck adds pages or swaps templates introducing a basename/chart absent from the original roster/batch → read the new file once, continue.
-> Note: batched prefix reads stay in the cached prompt prefix; per-page `spec_lock.md` re-reads append below and benefit from that cache. Scattered on-demand reads of layout/chart SVGs would invalidate downstream cache and sit in the compression-vulnerable mid-context region.
+> The execution manifest reduces roster/context load; it never authorizes writing from selectors alone. The selected full SVG must be open before editing that page.
Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritative). There is no filename/page-type fallback.
**Resolution order (per page):**
-1. **Mirror-mode template** (template's `design_spec.md` frontmatter has `replication_mode: mirror`) → see §1.1 below. The page is consumed as a **visual reference**, not as a placeholder shell.
-2. `spec_lock.md page_layouts` has `P<NN>: <basename>` for this page → inherit the structure of `templates/<basename>.svg` (already in context from §1.0).
-3. `template_adherence` is present but this page has no `page_layouts` entry → stop; the template contract is incomplete. Adaptive mode must still select a reference SVG.
-4. No deck/layout template at all → flat free design: use the visual composition planned in §IX, but write no native Master/Layout mapping or SVG structure metadata.
+1. `template_reuse_scope: mirror` → see §1.1. The installed workspace must support `replication_mode: mirror`.
+2. `template_reuse_scope: layout` → resolve `P<NN>: <basename>` from `page_layouts`, retain the structure system, and apply the non-mirror skin/reflow rules below.
+3. `template_reuse_scope: style` or no deck/layout template → flat free design: use template colors/typography/decoration/rhythm as style input, but write no native Master/Layout mapping or SVG structure metadata.
+4. `mirror` / `layout` with no current-page `page_layouts` row → stop; adaptive mode still requires one selected input prototype.
> Note: `page_layouts` disambiguates the multiple content variants a template may ship; missing mappings are contract errors.
-**Templates supply structure, not skin (non-mirror)**: a chart or layout template's gradients, drop-shadows, palette, **and font sizes** are placeholder. Inherit its geometry, label / legend placement, and series-encoding logic; re-skin every fill / stroke to the deck's `visual_style` + `spec_lock.colors` — flat styles strip the gradients and shadows, gradient / glass styles repaint their own. Forbidden — shipping a template's default `<linearGradient>` / `cardShadow` / Tailwind fills unchanged. Mirror templates are the exception: §1.1 preserves their visuals verbatim.
+**Templates supply structure, not skin (`layout` scope)**: a chart or layout template's gradients, drop-shadows, palette, **and font sizes** are placeholder. Inherit its geometry, label / legend placement, and series-encoding logic; re-skin every fill / stroke to the deck's `visual_style` + `spec_lock.colors` — flat styles strip the gradients and shadows, gradient / glass styles repaint their own. Forbidden — shipping a template's default `<linearGradient>` / `cardShadow` / Tailwind fills unchanged. `mirror` scope is the exception: §1.1 preserves visuals verbatim.
**Font size is skin, not geometry (non-mirror).** A chart / layout template's hardcoded `font-size` values (often 11–16px, sized for the template's own dense placeholder text) are NOT inherited — classify each text into its `spec_lock.md` role and use that role's locked size, exactly as you re-skin color. **Structural roles (page title / body / subtitle / annotation / footnote) hold their one deck-wide size on every page** — the template's placeholder px never overrides it; same-role text drifting page to page is what makes a deck look unprofessional.
@@ -60,19 +59,19 @@ Resolve the per-page template SVG via `spec_lock.md page_layouts` (authoritative
**Geometry adapts to the type, never the reverse**: when the locked size is larger than the template's placeholder text, widen / heighten the card, open spacing, and recompute child `y` / `dy` to make room — do not shrink the font to fit the inherited container. A `font-size` change is a layout change: revise line-height and every downstream vertical coordinate that depends on it. For wrapped text, allocate at least the wrapped line count × line-height plus top / bottom padding; fixed `y` stacks copied from a smaller template are invalid once the locked role size is applied. The Executor renders the page it was given; page count and per-page density are the Strategist's call, fixed at confirmation — do **not** re-paginate, split the page, or drop authored content to cope with size here. Only when a single block still cannot fit after the geometry is fully reflowed may you shrink **that block** as a bounded last resort — and **only body text** is ever shrunk this way. Title, subtitle, annotation / caption, footnote and page number are **locked once set and never adjusted to fit** — their values hold across the whole deck. Step the overflowing body block's `font-size` down by `2`px at a time, and only if it still overflows step it down again, up to a cumulative floor of **`4`px below the locked body size** (e.g. `24` → no smaller than `20`). This is a **local, single-block** reduction — the deck-wide locked body size is unchanged on every other block and page. (The Executor works in **unitless px** throughout — spec_lock and SVG carry no `pt`.) If the block still overflows at the floor, surface a `warning:` rather than silently restructure the page. (Mirror templates are the exception: §1.1 preserves their sizes verbatim — there the source deck's typography *is* the spec.)
-### 1.1 Mirror-mode templates — reference-style consumption
+### 1.1 Mirror reuse — literal page replacement
-When the project's chosen template is a `mirror` template (`design_spec.md` frontmatter declares `replication_mode: mirror`), Executor switches to a **reference-style** consumption path that bypasses placeholder substitution:
+When `spec_lock.md` confirms `template_reuse_scope: mirror`, Executor switches to a literal replacement path. The workspace capability `replication_mode: mirror` is a prerequisite, not the trigger by itself:
1. **Per-page reference selection** — Strategist selects one mirror page per project page via `spec_lock.md page_layouts` (e.g., `P04: 015_content`). The basename is the mirror filename without extension; Strategist made this choice by reading `design_spec.md §V Page Roster` descriptions, not by guessing.
-2. **Copy, don't fill** — open the referenced mirror SVG (already in context from §1.0). Copy it as the starting point, then edit slide-specific text in place. Preserve every non-text element and every `data-pptx-*` structure attribute verbatim unless adaptive mode intentionally assigns a new Layout contract.
-3. **What you may edit** — the visible text content of `<text>` / `<tspan>` elements that express slide-specific content (title, body, captions, KPI labels, dates, page numbers). Replace the source deck's example text with the project's text for this page from `design_spec.md §IX` and `notes/<NN>_*.md`.
+2. **Copy, don't fill** — open the referenced full mirror SVG immediately before authoring the page. Copy it as the starting point, then edit slide-specific text in place. Preserve every non-text element and every `data-pptx-*` structure attribute verbatim.
+3. **What you may edit** — only the visible string values already carried by `<text>` and `<tspan>` nodes that express slide-specific content (title, body, captions, KPI labels, dates, page numbers). Keep the number, order, nesting relationship, and **all attributes** of every `<text>` / `<tspan>` node unchanged. Never merge or split nodes, move a string between nodes, add a new tspan, or delete an empty carrier. The selected `text_slots_path` sidecar exposes the expected selectors/counts/hashes, but the complete SVG remains authoritative.
4. **What you must not touch** — element positions, sizes, fonts, colors, fills, strokes, gradients, **which image each `<image>` points at**, `<g>` grouping, sprite-sheet `<svg viewBox>` wrappers, decorative `<rect>` / `<path>` / `<circle>` / `<polygon>` shapes, `<use data-icon="...">` markers, embedded chart data structures. Mirror's value is preserving the source deck's visual identity — any geometric / decorative drift defeats the purpose. **The `href` path is not the image**: normalizing a bare `href="cover_bg.png"` to `href="../images/<name>"` (when Step 3 relocated the asset to `images/`) points at the *same* image and changes nothing visual — that is an allowed path fix, not a fidelity edit. Leaving the bare href as-is is also fine; the exporter and live preview resolve bare hrefs against `images/` either way.
-5. **Content fit** — the mirror page was chosen by Strategist because its layout matches the content slot. If the project's content for `P<NN>` legitimately needs more / fewer items than the mirror page provides (e.g. mirror shows 3 KPI cards, project has 4 metrics), keep the mirror page's visual rhythm and either drop one metric to fit or split across two pages — do **not** restructure the mirror page's grid. If neither works, surface a `warning: P<NN> content does not fit mirror reference <basename>; suggest different reference page` and proceed with the closest-fit edit.
-6. **Visible text editing** — mirror SVGs may keep literal source text rather than `{{...}}` authoring markers. Edit visible text in place, but retain any imported semantic `data-pptx-placeholder` identity.
+5. **Content fit** — if the replacement needs a different number of text segments/items, do not merge/split nodes, drop sourced content, or restructure the grid. Select a better mirror prototype and update the planning mappings, or report `warning: P<NN> content does not fit mirror reference <basename>; choose another prototype or change template_reuse_scope to layout/style`.
+6. **Visible text editing** — mirror SVGs may keep literal source text rather than `{{...}}` authoring markers. Edit values in place while retaining imported semantic `data-pptx-placeholder` identity and exact text topology.
7. **Output filename** — follow the standard project SVG naming convention (`<NN>_<page_name>.svg` where `<NN>` matches the project page index, not the mirror source index). The mirror filename is the *reference*, not the *output*.
-**Detecting mirror mode**: read the chosen template's `design_spec.md` frontmatter once during §1.0 batch read. If `replication_mode: mirror`, every page follows §1.1 through its mandatory `page_layouts` reference.
+**Detecting mirror mode**: read `template_reuse_scope` from `spec_lock.md` before every page. `replication_mode: mirror` in the installed template only determines whether that confirmed scope is legal; it must never force mirror behavior when the confirmed scope is `layout` or `style`.
**Mirror + chart pages**: chart structures inside a mirror SVG are already drawn (axis, series, labels). Treat them as visual references — replace the data labels and series text content to match the project's chart spec, but do not redraw the chart from a `templates/charts/<name>.svg` baseline. A mirror template's `page_charts` entries are normally absent for this reason.
@@ -92,9 +91,9 @@ Before generating each page, output which template is used:
### 1.2 PowerPoint Master / Layout Mapping
-This section applies only to deck/layout template routes. `page_layouts` selects the input SVG prototype, `pptx_masters` / `pptx_layouts` declare unique reusable output definitions, and `page_pptx_layouts` assigns every generated page before the first page is drawn. Free-design and brand-only routes use `pptx_structure.mode: flat`, omit all four sections, skip the rest of §1.2, and keep every SVG object Slide-local.
+This section applies only when a deck/layout template is confirmed with `template_reuse_scope: mirror|layout`. `page_layouts` selects the input SVG prototype, `pptx_masters` / `pptx_layouts` declare unique reusable output definitions, and `page_pptx_layouts` assigns every generated page before the first page is drawn. `template_reuse_scope: style`, free-design, and brand-only routes use `pptx_structure.mode: flat`, omit all four sections, skip the rest of §1.2, and keep every SVG object Slide-local.
-**Hard rule — template mode only**: A deck/layout template project uses `pptx_structure.mode: structured`. Missing mode or legacy values (`baseline`, `template`, `preserve`), `layout_strategy`, Layout-kind fields, partial mappings, and old direct placeholders stop generation. Create a new template workspace through [`create-template`](../workflows/create-template.md); do not upgrade the active SVG project in place. `flat` is valid only when no deck/layout template is active.
+**Hard rule — reuse-scope route**: `template_reuse_scope: mirror|layout` requires `pptx_structure.mode: structured`. `template_reuse_scope: style` requires `mode: flat` even though a template supplied its visual vocabulary. Missing mode or legacy values (`baseline`, `template`, `preserve`), `layout_strategy`, Layout-kind fields, partial mappings, and old direct placeholders stop generation. Create a new template workspace through [`create-template`](../workflows/create-template.md); do not upgrade the active SVG project in place.
**Hard rule — root identity**: A `page_pptx_layouts` row binds the page to one key in `pptx_layouts`; that unique definition supplies its Master key, Layout picker name, and prototype source. Put the declared Master key/name and Layout key/name on the root SVG. A Layout key belongs to exactly one Master and remains globally unique.
@@ -175,7 +174,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
| Tag | Layout discipline |
|-----|-------------------|
-| `anchor` | Structural page (cover / chapter / TOC / ending). With a template, follow the matching template verbatim. In free design (no template), realize the page's §IX intent — for the cover deliver its `Cover impact` and for a closing page its `Closing impact` (the committed hook / takeaway + composition), never a default centered title + subtitle or a generic "Thank you" sign-off. |
+| `anchor` | Structural page (cover / chapter / TOC / ending). With `template_reuse_scope: mirror`, follow the selected prototype verbatim except visible text values. With `layout`, retain the selected structure system while realizing the page's §IX intent. With `style` or free design, realize §IX directly — for the cover deliver its `Cover impact` and for a closing page its `Closing impact`, never a default centered title + subtitle or generic "Thank you" sign-off. |
| `dense` | Information-heavy. Card grids, multi-column layouts, KPI dashboards, tables, and charts are all permitted. This is the baseline behavior. |
| `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. |
@@ -185,20 +184,21 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
**Tag not found for current page** → 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.
-**Per-page template lookup — `page_layouts` section**:
+**Per-page template lookup — `page_layouts` section (`mirror` / `layout` only)**:
Before drawing each page, look up its entry in `page_layouts` to decide which basename to inherit (the SVG itself was loaded in §1.0):
-- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding SVG already in context. The basename **must match** an actual file in the chosen template directory. If it does not, stop before drawing and report the invalid mapping; neither `strict` nor `adaptive` may fall back to free design inside a template deck.
-- No entry for this page with `template_adherence: strict|adaptive` → stop before drawing and report the missing Strategist mapping. Adaptive mode still requires one selected complete template SVG; flexibility applies to the post-design output Layout, not to whether an input prototype exists.
-- Whole section absent while `template_adherence` is present → stop before drawing; the current template contract is incomplete.
+- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding full SVG. The basename **must match** an actual file in the chosen template directory. If it does not, stop before drawing and report the invalid mapping; neither `strict` nor `adaptive` may fall back to free design inside a structured template deck.
+- No entry for this page with `template_reuse_scope: mirror|layout` → stop before drawing and report the missing Strategist mapping. Adaptive mode still requires one selected complete template SVG; flexibility applies to the post-design output Layout, not to whether an input prototype exists.
+- Whole section absent while `template_reuse_scope: mirror|layout` is present → stop before drawing; the current template contract is incomplete.
+- `template_reuse_scope: style` → the whole section must be absent; do not perform per-page prototype lookup.
-Do **not** invent a prototype entry, and do **not** assume a template just because `templates/` exists. For either template-adherence value, a missing or invalid `page_layouts` row is an upstream contract error. Free design is a separate deck route, never a per-page fallback.
+Do **not** invent a prototype entry, and do **not** assume a structured template just because `templates/` exists. For `mirror` / `layout`, a missing or invalid `page_layouts` row is an upstream contract error. `style` is a separate flat deck route, never a per-page fallback.
-**Per-page PowerPoint layout lookup — structured deck/layout templates only**:
+**Per-page PowerPoint layout lookup — `template_reuse_scope: mirror|layout` only**:
-- When `pptx_structure.mode` is `flat`, skip this lookup and the structured scaffold below. `pptx_masters`, `pptx_layouts`, `page_layouts`, and the corresponding SVG metadata must all be absent; each root still declares its canonical `data-pptx-page-role`.
-- When a deck/layout template is active, `pptx_structure.mode` must equal `structured`; any other or missing value is rejected. Do not migrate it in place: create a new current-contract workspace through Create Template before generation resumes.
+- When `pptx_structure.mode` is `flat` (including `template_reuse_scope: style`), skip this lookup and the structured scaffold below. `pptx_masters`, `pptx_layouts`, `page_layouts`, and the corresponding SVG metadata must all be absent; each root still declares its canonical `data-pptx-page-role`.
+- With `template_reuse_scope: mirror|layout`, `pptx_structure.mode` must equal `structured`; any other or missing value is rejected. Do not migrate an invalid structured contract in place: create a new current-contract workspace through Create Template before generation resumes.
- Read the current page row as `<master_key> | <layout_key> | <layout name>` and resolve `master_key` in `pptx_masters`. Missing, malformed, or partial mappings stop before drawing.
- Write matching root Master/Layout key and picker names. Do not write `data-pptx-layout-kind` or `data-pptx-page-role`.
- On strict template use, the row and SVG contract match the selected prototype exactly.
@@ -250,14 +250,15 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha
- **Proximity**: group related elements with tight spacing; separate unrelated groups
- **Element grouping (Mandatory)**: wrap every logical Slide-local content unit — title, core-message line, each content block, card, list item, and diagram — in a top-level `<g id="...">` with a descriptive, page-unique id. Nested implementation groups within that unit may remain anonymous; they are not independent animation targets. Flat free-design/brand-only pages use ordinary semantic groups for every logical unit. On structured template pages, slot `<g>` elements are already semantic groups and direct Master/Layout atoms are the required exception to grouping. Authored native preset fragments (`preset_shape_svg.py`) already are one atomic `<g id>` each and count as one ordinary content group. When a preset needs labels or decorations, put the preset and those siblings inside a separate parent content group; never put them inside the preset group itself.
- **Spec adherence**: follow color, layout, canvas format, and typography in the spec
-- **Template structure**: if templates exist, inherit the visual framework
+- **Template structure**: inherit the native visual framework only for `template_reuse_scope: mirror|layout`; `style` uses the flat route
- **Main-agent ownership**: SVG generation must run in the main agent (not sub-agents) — pages share upstream context for cross-page visual continuity
- **Generation rhythm**: lock global design context first, then generate pages sequentially in one continuous context. No batched groups (e.g., 5 at a time).
+- **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; state the attribution naturally in speaker notes. When §IX says `Data class: scenario`, place a visible localized `Scenario data` / `情景数据` label adjacent to the affected KPI/chart and state naturally in notes that the number is illustrative. Never attach an external fact ID to scenario data or let an unlabeled invented KPI look factual.
- **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.
- **Reference — image-led promotional pages (not a constraint)**: for travel, venue, product-introduction, hospitality, event, real-estate, and brochure-style decks, let images define the page skeleton before placing text. Consult [`image-layout-patterns.md`](image-layout-patterns.md) §Imported Deck Patterns and prefer patterns such as `#74` TOC image-navigation cards, `#75` asymmetric chapter banners, `#77` photo mosaic with a text cell, `#78` ambient banner + evidence photo + text panel, `#79` ribbon-header image cards, and `#80` side hero image + staggered evidence cards before falling back to plain left/right image-text splits.
- **Phased batch generation** (recommended):
- 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 §3.1 below on every 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 §3.2 on every eligible data-chart page. **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 scripts/svg_quality_checker.py <project_path>/svg_output/<first_page>.svg` and fix every error before drawing page 2 — structural violations are systematic, and a first-page error repeated deck-wide costs a whole-deck rewrite.
- 2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path>` on `svg_output/`. Any `error` (banned/unsupported features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. 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. This includes structured deck/layout-template warnings. If release truly depends on a condition, it belongs in `errors`. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
+ 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 §3.1 below on every 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 §3.2 on every eligible data-chart page. **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 scripts/svg_quality_checker.py <project_path> --stage first-page` and fix every error before drawing page 2. This stage validates only the first authored page with a partial structure roster; future declared pages are not reported missing.
+ 2. **Quality Check Gate**: run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/`. Any `error` (banned/unsupported features, invalid values, unresolved references, viewBox mismatch, etc.) MUST be fixed on the offending page before proceeding — regenerate and re-check. 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 `exports/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.
### 3.0 Native Preset Shape Selection
@@ -507,7 +508,7 @@ Handle images by their status in the Design Spec's Image Resource List. Status e
**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).
-**Template-bundled images**: when a template (deck / layout / brand) is applied, its bitmaps are copied into the project's `images/` alongside every other runtime image (SKILL.md Step 3). Reference them the same way — `../images/<name>` — and do **not** reproduce a template SVG's bare sibling href (e.g. `href="cover_bg.png"`): the template SVG is reference material, the rendered page lives in `svg_output/` and must point at `../images/`. Mirror templates (§1.1) are the one exception — they copy hrefs verbatim, and the exporter resolves those bare hrefs against `images/`.
+**Template-bundled images**: when a template (deck / layout / brand) is applied, its bitmaps are copied into the project's `images/` alongside every other runtime image (SKILL.md Step 3). Reference them the same way — `../images/<name>` — and do **not** reproduce a template SVG's bare sibling href (e.g. `href="cover_bg.png"`): the template SVG is reference material, the rendered page lives in `svg_output/` and must point at `../images/`. `template_reuse_scope: mirror` (§1.1) is the one exception — it copies hrefs verbatim, and the exporter resolves those bare hrefs against `images/`.
**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text
diff --git a/skills/ppt-master/references/semantic-svg.md b/skills/ppt-master/references/semantic-svg.md
index 2a350039..4f15cead 100644
--- a/skills/ppt-master/references/semantic-svg.md
+++ b/skills/ppt-master/references/semantic-svg.md
@@ -16,7 +16,7 @@ PPT Master uses rendering-neutral compiler hints only where ordinary SVG cannot
The completed SVG remains the full visible page. Removing the metadata must not change browser rendering. Do not copy visible text, geometry, style, or asset values into metadata.
-**Hard rule — route boundary**: Free-design and brand-only pages use `pptx_structure.mode: flat`, declare one canonical root `data-pptx-page-role`, and omit every Master/Layout/layer/placeholder marker in this document. Deck/layout template pages declare their final Master and Layout before drawing begins and omit `data-pptx-page-role`; the structured exporter compiles that contract and never selects, clusters, distills, or visually infers it.
+**Hard rule — route boundary**: Free-design, brand-only, and `template_reuse_scope: style` pages use `pptx_structure.mode: flat`, declare one canonical root `data-pptx-page-role`, and omit every Master/Layout/layer/placeholder marker in this document. Only deck/layout template pages confirmed with `template_reuse_scope: mirror|layout` declare their final Master and Layout before drawing begins and omit `data-pptx-page-role`; the structured exporter compiles that contract and never selects, clusters, distills, or visually infers it.
**Hard rule — specialized metadata wins**: Use Master/Layout/placeholder metadata for native structure, `data-pptx-replace-with` for optional PowerPoint-native Chart/Table replacement, and the imported/authored shape metadata defined in [`shared-standards.md`](./shared-standards.md) §§1.4–1.5. Do not duplicate those facts with `data-pptx-role`.
@@ -24,7 +24,7 @@ The completed SVG remains the full visible page. Removing the metadata must not
## 2. Master and Layout Atoms
-On structured deck/layout template routes, Master and fixed Layout visuals are atomic root children:
+On structured `template_reuse_scope: mirror|layout` routes, Master and fixed Layout visuals are atomic root children:
```xml
<svg xmlns="http://www.w3.org/2000/svg"
@@ -117,7 +117,7 @@ Do not add structural roles to ordinary titles, body copy, cards, KPIs, diagrams
## 5. Validation and Migration
-For structured deck/layout template projects, validation rejects:
+For structured `template_reuse_scope: mirror|layout` projects, validation rejects:
- a missing root Master/Layout identity or a page-to-lock mismatch;
- a Master/Layout `<g>`, nested structure marker, missing/stale id, or inconsistent shared atom contract;
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 86735146..d789436b 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -562,7 +562,7 @@ continue without modification.
### 4.1 Semantic SVG Marker Contract
-Semantic markers are minimal compiler hints orthogonal to native SVG semantics. Free-design and brand-only pages use flat export, declare one canonical root `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`), and omit Master/Layout/layer/placeholder markers. On deck/layout template routes, root Master/Layout identity, atomic layer elements, grouped slots, and native-object metadata are authoritative and read first; each page carries its final structured contract from the start of SVG authoring and omits `data-pptx-page-role`. Add `data-pptx-role` only when no specialized marker expresses the required page-frame behavior; the element also uses a stable unique `id`. Do not classify ordinary page content or move visible facts out of SVG attributes/text into metadata. See [`semantic-svg.md`](semantic-svg.md) for the canonical vocabulary and examples.
+Semantic markers are minimal compiler hints orthogonal to native SVG semantics. Free-design, brand-only, and `template_reuse_scope: style` pages use flat export, declare one canonical root `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`), and omit Master/Layout/layer/placeholder markers. On `template_reuse_scope: mirror|layout` routes, root Master/Layout identity, atomic layer elements, grouped slots, and native-object metadata are authoritative and read first; each page carries its final structured contract from the start of SVG authoring and omits `data-pptx-page-role`. Add `data-pptx-role` only when no specialized marker expresses the required page-frame behavior; the element also uses a stable unique `id`. Do not classify ordinary page content or move visible facts out of SVG attributes/text into metadata. See [`semantic-svg.md`](semantic-svg.md) for the canonical vocabulary and examples.
- **Canvas authority**: New authoring writes the root canvas exactly as
`viewBox="0 0 W H"`, using single spaces and positive ordinary-decimal integer
@@ -1766,7 +1766,7 @@ defaults to `bottom` and accepts `top`, `left`, or `right`.
### PPTX Structure Routing
-Every new SVG project declares one deterministic route. Free-design and brand-only projects use `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata. Export keeps all represented content Slide-local while materializing one clean project-owned Master plus one Blank Layout from the current color/typography lock; stock content placeholders and unused built-in Layouts are removed, while the standard date/footer/slide-number capability hooks remain. Deck/layout template projects use `mode: structured`; `standard` / `fidelity` templates use their authored contract, while mirror templates use the validated source identities and parentage declared by the newly materialized workspace.
+Every new SVG project declares one deterministic route. Free-design, brand-only, and `template_reuse_scope: style` projects use `pptx_structure.mode: flat`, omit `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and author no Master/Layout/layer/placeholder metadata. Export keeps all represented content Slide-local while materializing one clean project-owned Master plus one Blank Layout from the current color/typography lock; stock content placeholders and unused built-in Layouts are removed, while the standard date/footer/slide-number capability hooks remain. Deck/layout template projects confirmed with `template_reuse_scope: mirror|layout` use `mode: structured`; `standard` / `fidelity` templates use their authored contract, while mirror templates use the validated source identities and parentage declared by the newly materialized workspace.
**Hard rule — no structure inference**: Flat export performs no promotion or deduplication; every object stays Slide-local. Structured template export compiles only declared root identities, atomic fixed layers, and slot groups—it does not assign Layout families, cluster pages, infer placeholders, repair missing metadata, or migrate legacy contracts. Create a new current workspace through [`create-template`](../workflows/create-template.md) before generating structured pages.
@@ -1778,7 +1778,7 @@ Every new SVG project declares one deterministic route. Free-design and brand-on
### Explicit PPTX Master / Layout / Placeholder Metadata
-**Trigger**: This explicit metadata interface applies only to new pages generated from a current deck/layout template workspace. `spec_lock.md` declares `pptx_structure.mode: structured`, complete unique `pptx_masters` / `pptx_layouts` rosters, one `page_pptx_layouts` assignment per generated page, and `page_layouts` as authoring-prototype provenance. Flat free-design/brand-only SVGs use none of these metadata fields.
+**Trigger**: This explicit metadata interface applies only to new pages generated from a current deck/layout template workspace with `template_reuse_scope: mirror|layout`. `spec_lock.md` declares `pptx_structure.mode: structured`, complete unique `pptx_masters` / `pptx_layouts` rosters, one `page_pptx_layouts` assignment per generated page, and `page_layouts` as authoring-prototype provenance. `template_reuse_scope: style`, free-design, and brand-only SVGs use `mode: flat` and none of these metadata fields.
**Project lock**: A Master row is `<master_key>: <PowerPoint picker name>`. A unique Layout row is `<layout_key>: <master_key> | <PowerPoint picker name> | <prototype source>`, where the source is a generated `P<NN>` or installed `template:<basename>`. A page assignment is `P<NN>: <layout_key>` under `page_pptx_layouts`. The SVG root values MUST match the assigned definition. A Layout key belongs to exactly one Master and must be globally unique. Reuse one key only when prototypes share identical ordered Layout atoms and slot ids/types/effective indices/default bounds/binding modes. An unused Layout uses a template SVG source and remains registered without a published carrier slide. Every structured route requires numeric `spec_lock.md` typography `title` / `body` rows.
@@ -1837,7 +1837,7 @@ prototype size remain unchanged.
| `data-pptx-placeholder-binding="proxy"` | composite `object` slot `<g>` only | Keeps the visible group ordinary and creates one hidden transparent binding proxy |
| `data-pptx-editable="false"` | master/layout element or slide background | Declares intentional editing outside ordinary slide content |
-**Hard rule — explicit only**: On a structured deck/layout template route, every SVG requires the four root Master/Layout identity attributes. Optional inherited-shape visibility uses only exact lowercase `true` / `false`; other spellings fail, and omission means `true`. Every Master/Layout atom and slot requires a unique stable `id` and is a direct root child. Layouts with zero slots are valid. `data-pptx-layout-kind`, `distilled`, and `utility` are legacy metadata and fail the structured contract. Flat free-design/brand-only pages omit the entire interface, including the visibility attributes.
+**Hard rule — explicit only**: On a structured `template_reuse_scope: mirror|layout` route, every SVG requires the four root Master/Layout identity attributes. Optional inherited-shape visibility uses only exact lowercase `true` / `false`; other spellings fail, and omission means `true`. Every Master/Layout atom and slot requires a unique stable `id` and is a direct root child. Layouts with zero slots are valid. `data-pptx-layout-kind`, `distilled`, and `utility` are legacy metadata and fail the structured contract. Flat `template_reuse_scope: style`, free-design, and brand-only pages omit the entire interface, including the visibility attributes.
**Layer order**: Author the SVG in PowerPoint paint order: Master background,
Layout background, optional Slide background, remaining Master atoms, remaining Layout atoms,
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index c063e90a..79b06266 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -28,7 +28,7 @@ As a top-tier AI presentation strategist, receive source documents, perform cont
| Stage | Items | Role |
|---|---|---|
-| **1 — direction anchors** | `a` canvas · `c` key info — audience + `content_divergence` + **delivery purpose** *(PPT only)* (promoted out of `g`) · `d` mode + visual_style · template adherence *(only when Step 3 loaded a deck/layout template)* | confirmed first |
+| **1 — direction anchors** | `a` canvas · `c` key info — audience + `content_divergence` + **delivery purpose** *(PPT only)* (promoted out of `g`) · `d` mode + visual_style · template reuse scope, then adherence for `mirror` / `layout` *(only when Step 3 loaded a deck/layout template)* | confirmed first |
| **2 — design system** (re-derived from the user's *actual* Stage 1) | `b` page count · `e` color · `f` icon · `g` typography (font + size, formula policy) | derived from Stage 1 |
| **3 — images / execution** (re-derived from the user's *actual* Stage 1 + Stage 2) | `h` image source + generated-image style · generation mode · refine-spec toggle | derived from confirmed direction + design system |
@@ -60,6 +60,8 @@ Read the user's prose as a point on a spectrum and apply judgment — from *stay
**Hard rule — facts stay sourced however free the user asks.** Divergence is freedom to *develop* what is in the source (reorganize / reframe / expand / connect), never licence to invent. Even the freest request must not introduce facts, figures, or claims from outside the source material — that is the `topic-research` job, not divergence. `mode` and divergence are orthogonal (e.g. a pyramid that hews to the source's own points vs. a pyramid built from freely synthesized themes).
+**Fact provenance contract**: When `sources/*.facts.json` exists, read it before outlining and reference its stable `fact_id` values in every §IX page that uses an external quantitative or factual claim. Add `Fact IDs: F001, ...` to that page. Invented demo KPIs, internal ratios, targets, and roadmap numbers must instead carry `Data class: scenario`; never assign them an external `fact_id`. The same page may use both classes, but each number's class must remain unambiguous so Executor can place citations in notes/footnotes and visibly label scenario data.
+
**Consumption — outline-authoring only.** Apply the user's stated intent when authoring the `§IX` outline. Record the prose (or "balanced default") in `design_spec.md §I` (Content Strategy). Do **NOT** write it to `spec_lock.md` — it is baked into `§IX` at authoring time and the Executor never reads it. It carries no page-count coupling — the §b page count stays the user's separate call. The beautify profile and Fill Native PPTX route keep content verbatim, so they do not surface this field.
### d. Style Objective Confirmation
@@ -102,16 +104,26 @@ Write the locked value to `spec_lock.md` `- visual_style:` and the rationale to
**Legacy template boundary**: A template containing `native_structure.json`, `source_template.pptx`, missing root Master identity, direct atomic placeholders, or old `baseline` / `preserve` / distillation metadata is not a Step 3 input. Create a new current workspace through [`create-template`](../workflows/create-template.md), preferably from the original PPTX when existing native topology matters. Do not plan against a legacy compatibility contract or mutate the input in place.
-**Template adherence confirmation**: Surface this closed Stage-1 choice only when Step 3 loaded a `kind: deck` or `kind: layout` template. Omit it for free design and brand-only templates.
+**Template reuse confirmation**: Surface `template_reuse_scope` only when Step 3 loaded a `kind: deck` or `kind: layout` template. Omit it for free design and brand-only templates.
+
+| Reuse scope | Planning and export behavior |
+|---|---|
+| `mirror` | Mirror workspaces only. Start from the full selected page, preserve literal visuals and text-node topology, and replace only allowed visible text values. |
+| `layout` | Reuse the template Master/Layout system and input prototypes, but allow project-controlled reflow/re-skinning and explicit adaptive Layouts. |
+| `style` | Reuse only color, typography, decoration language, and rhythm. Plan a free-design `pptx_structure.mode: flat` deck with no template structure mappings. |
+
+**Deterministic language mapping**: “不要严格复用”, “只参考风格”, “参考这个风格”, and “不必照搬版式” recommend `style` unless the user explicitly asks to retain the layout system, in which case recommend `layout`. “原样复刻”, “替换内容”, and “保持模板页面外观” recommend `mirror` only when `replication_mode: mirror` is available. A bare template path with no stronger language defaults to `layout`, not `mirror`.
+
+For `mirror` / `layout`, surface the second closed Stage-1 choice, `template_adherence`. Hide it for `style`.
| Value | Planning and export behavior |
|---|---|
| `strict` | Map every page to one template SVG. Keep its explicit Master/Layout/slot contract and output Layout key unchanged. |
| `adaptive` | Map every page to the closest template SVG. Keep the template Master contract, but allow a new explicit Layout key when the selected composition must adapt to the content. |
-**Default — adaptive (may override when the user requests exact template use)**: Recommend `adaptive` when the user supplied only a template path with no stricter instruction. Preselect `strict` when the user explicitly asks to follow or preserve the template closely; the Stage-1 confirmation still records the final choice. Record the confirmed value in `design_spec.md §I` and as `template_adherence` under `spec_lock.md pptx_structure`.
+**Default — layout + adaptive**: When the user supplied only a template path, recommend `layout` and `adaptive`. Preselect `strict` only when the user explicitly asks to keep the selected Layout contract unchanged. Record the confirmed scope in `design_spec.md §I` and as `template_reuse_scope` under `spec_lock.md pptx_structure`; record adherence only for `mirror` / `layout`.
-> Note: `content_divergence` controls how source material is reorganized; `template_adherence` controls how template visuals/layouts are used. Never infer one from the other.
+> Note: `content_divergence` controls how source material is reorganized; `template_reuse_scope` controls which template layer is reused; `template_adherence` controls structural strictness inside `mirror` / `layout`. Never collapse these axes.
**Downstream effect**: e / f / g / h realize the locked mode + visual style. Example: `showcase` + `dark-tech` → e applies one luminous accent on a dark field; g pairs a clean sans with mono; f minimal glow icons; h the `digital-dashboard` rendering.
@@ -840,29 +852,30 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck
| VI. Icon Usage Spec | Source description, placeholder syntax, recommended icon list |
| VII. Visualization Reference List | Visualization type, reference template path, used-in pages, purpose |
| VIII. Image Resource List | Filename, dimensions, ratio, purpose, status, generation description |
-| IX. Content Outline | Grouped by chapter; each page includes layout, title, core message (the page's one idea), content blocks (in the selected phrasing mode), visualization type (if applicable) |
+| IX. Content Outline | Grouped by chapter; each page includes layout, title, core message (the page's one idea), content blocks (in the selected phrasing mode), visualization type (if applicable), plus `Fact IDs` for sourced claims and `Data class: scenario` for invented demonstration data |
| X. Speaker Notes Requirements | File naming rules, content structure description |
**Generation steps**:
1. Read reference template: `templates/design_spec_reference.md`
2. Generate complete spec from scratch based on analysis
3. Save to: `projects/<project_name>.../design_spec.md`
-4. **Generate execution lock**: read `templates/spec_lock_reference.md` and produce `projects/<project_name>.../spec_lock.md` — a compact, machine-readable form of the color / typography / icon / image / **page_rhythm** / **page_charts** and route-specific PowerPoint structure decisions above. Within the PowerPoint structure portion, free-design and brand-only routes write only `pptx_structure.mode: flat`; deck/layout template routes additionally write `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts`. This file is what the Executor re-reads before every page (see [executor-base.md](executor-base.md) §2.1). The values in `spec_lock.md` MUST exactly match the decisions recorded in `design_spec.md`; if they ever diverge, `spec_lock.md` wins and `design_spec.md` should be treated as historical narrative.
+4. **Generate execution lock**: read `templates/spec_lock_reference.md` and produce `projects/<project_name>.../spec_lock.md` — a compact, machine-readable form of the color / typography / icon / image / **page_rhythm** / **page_charts** and route-specific PowerPoint structure decisions above. Within the PowerPoint structure portion, free-design, brand-only, and `template_reuse_scope: style` routes write `pptx_structure.mode: flat` and omit all template mappings; only `template_reuse_scope: mirror|layout` routes additionally write `page_layouts`, `page_pptx_layouts`, `pptx_masters`, and `pptx_layouts`. This file is what the Executor re-reads before every page (see [executor-base.md](executor-base.md) §2.1). The values in `spec_lock.md` MUST exactly match the decisions recorded in `design_spec.md`; if they ever diverge, `spec_lock.md` wins and `design_spec.md` should be treated as historical narrative.
- **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing` (see `spec_lock_reference.md` for the full vocabulary). This is what breaks the uniform "every page is a card grid" feel — without it the Executor defaults all pages to `dense`.
+ - **Fact IDs and scenario labels are mandatory when applicable**: Read any `sources/*.facts.json`. For each §IX page, list the stable IDs actually used; never cite an ID whose claim is absent from the page. Mark invented KPIs/targets/internal ratios as `Data class: scenario` and state which values are scenario data. Executor carries external sources into notes/footnotes and renders a visible scenario label for scenario figures.
- **Rhythm follows narrative, not quota**: `breathing` pages mark natural pauses — chapter transitions, standalone emphasis (hero quote / big number), SCQA bridges. Dense decks may legitimately be all `dense`. **Do NOT invent filler pages** ("Thank you", empty dividers) to pad rhythm — every `breathing` page must say something independent. Delivery purpose biases the overall lean (`presentation` toward more `anchor` / `breathing`, `text` toward `dense`; see §6.1) — a bias, never a quota.
- **Cover impact is mandatory**: Page `P01` is the deck's first visual contract, not a generic title slide. In `design_spec.md §IX`, add a `Cover impact` line for `P01` that names one concrete hook and one concrete composition strategy. Use the source's strongest available signal: a provocative core claim, object / scene metaphor, hero number, founder / product / audience moment, or a distilled conflict. Pair it with one concrete composition strategy — such as `full-bleed image + floating title`, `typographic poster`, `hero object`, `data hook`, `editorial scene`, `high-contrast abstract geometry`, or a fresh composition the deck's subject suggests (these are starting points, not the allowed set). If no external or AI image is available, still specify a native-SVG visual hook; do not fall back to "title + subtitle + decorative background". (Beautify / template-fill keep the source cover verbatim — this rule does not apply on those preservation paths.)
- **Cover rhythm lock**: `P01` remains `anchor` in `spec_lock.md page_rhythm`, but its §IX `Cover impact` must prevent content-page patterns. Do not plan multi-card grids, agenda-like bullets, or equal-weight columns on the cover unless a template explicitly requires that structure, or a preservation path (beautify / template-fill) is transcribing the source cover verbatim.
- **Closing impact (only when the deck closes)**: the deck's last page is its final visual contract — the strongest impression after the cover. When the deck genuinely lands on a conclusion / call-to-action / final-takeaway page, give it a `Closing impact` line in §IX: name the one thing the audience should leave with (a distilled takeaway, a forward call, a memorable restatement of the core claim) + one composition that delivers it — never a generic "Thank you" / contact-only slide or a centered-title reprise of the cover. **Do NOT invent a closing page to satisfy this** — the filler-page ban above still holds; apply it only to the page where the deck actually resolves. Same exemptions as the cover: skip on template / beautify / template-fill preservation paths.
- - **pptx_structure is mandatory**: Free-design and brand-only routes write `mode: flat`. Deck/layout template routes write `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.
+ - **pptx_structure is mandatory**: Free-design, brand-only, and `template_reuse_scope: style` routes write `mode: flat`; a style-reference route may also record `template_reuse_scope: style` but omits every structure mapping and `template_adherence`. `template_reuse_scope: mirror|layout` writes `mode: structured` plus `template_adherence: strict|adaptive`. Do not write legacy `baseline`, `template`, `preserve`, `layout_strategy`, or Layout-kind rows into a new project.
- **Flat-route boundary**: With `mode: flat`, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. Do not plan native Master/Layout families or reusable placeholder slots. Every generated SVG object remains Slide-local: omit root Master/Layout identity, `data-pptx-layer`, and `data-pptx-placeholder*` metadata. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks.
- - **Master roster (deck/layout templates only)**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>` and copy the template workspace's declared prototype roster. Keys use 1–64 ASCII letters, digits, dots, underscores, or hyphens, start with a letter/digit, and contain no spaces; human-readable spaces belong only in `<picker name>`. Master visuals are root-level atomic elements and may never be `<g>`.
- - **pptx_layouts (deck/layout template reusable roster)**: Write every unique reusable Layout once as `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`. Copy the installed template roster with `template:<basename>` sources, including Layouts no generated page currently uses. A genuinely new adaptive Layout uses its first generated `P<NN>` as the source. Reuse a key only when fixed Layout atoms plus slot ids/types/indices/bounds/binding modes are identical. Name authored keys after composition (`timeline-spine`, `kpi-band-trio`, `content-image-right`), never after page topic. A Layout may intentionally have zero slots; never manufacture an empty `utility` kind or full-page fake slot.
- - **page_pptx_layouts (deck/layout template page assignment)**: Write exactly one `P<NN>: <layout_key>` row per generated page. The key must exist in `pptx_layouts`; Master and picker name are inherited from that unique definition. **Self-check before writing the section**: compare distinct assigned keys against distinct compositions in §IX. Distinct compositions collapsing into a handful of role-only keys means pages were clustered by topic label; one shared skeleton splitting into topic-specific keys means pages were split by content wording. Both misstate the roster.
- - **Slot planning (deck/layout templates only)**: Each reusable slot is a direct root `<g id>` with `data-pptx-placeholder`, positive design-zone bounds, and exactly one compatible direct carrier. Bounds come from the intended safe area, column, panel inset, or media frame—not sample text ink. A genuinely composite region may use only the explicit `object` + `proxy` downgrade.
- - **Adaptive refinement boundary (deck/layout templates only)**: The initial definitions and assignments are complete, not provisional. If actual adaptive construction genuinely changes reusable framing or slot topology/bounds, Executor creates one new `pptx_layouts` definition sourced from that page and updates its `page_pptx_layouts` assignment while authoring the first page. It never mutates a reused contract silently. Export only compiles declared structure and never discovers or clusters Layouts.
- - **page_layouts (deck/layout templates only)**: Add one `P<NN>: <svg_basename>` row for every page. This is the complete authoring-input prototype mapping. Strict preserves that SVG's structural contract; adaptive keeps its Master and may explicitly define and assign a new output Layout identity during page authoring. Omit the whole section for free-design and brand-only routes.
+ - **Master roster (`mirror` / `layout` only)**: Write one `pptx_masters` row per Master as `<master_key>: <picker name>` and copy the template workspace's declared prototype roster. Keys use 1–64 ASCII letters, digits, dots, underscores, or hyphens, start with a letter/digit, and contain no spaces; human-readable spaces belong only in `<picker name>`. Master visuals are root-level atomic elements and may never be `<g>`.
+ - **pptx_layouts (`mirror` / `layout` reusable roster)**: Write every unique reusable Layout once as `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`. Copy the installed template roster with `template:<basename>` sources, including Layouts no generated page currently uses. A genuinely new adaptive Layout uses its first generated `P<NN>` as the source. Reuse a key only when fixed Layout atoms plus slot ids/types/indices/bounds/binding modes are identical. Name authored keys after composition (`timeline-spine`, `kpi-band-trio`, `content-image-right`), never after page topic. A Layout may intentionally have zero slots; never manufacture an empty `utility` kind or full-page fake slot.
+ - **page_pptx_layouts (`mirror` / `layout` page assignment)**: Write exactly one `P<NN>: <layout_key>` row per generated page. The key must exist in `pptx_layouts`; Master and picker name are inherited from that unique definition. **Self-check before writing the section**: compare distinct assigned keys against distinct compositions in §IX. Distinct compositions collapsing into a handful of role-only keys means pages were clustered by topic label; one shared skeleton splitting into topic-specific keys means pages were split by content wording. Both misstate the roster.
+ - **Slot planning (`mirror` / `layout` only)**: Each reusable slot is a direct root `<g id>` with `data-pptx-placeholder`, positive design-zone bounds, and exactly one compatible direct carrier. Bounds come from the intended safe area, column, panel inset, or media frame—not sample text ink. A genuinely composite region may use only the explicit `object` + `proxy` downgrade.
+ - **Adaptive refinement boundary (`mirror` / `layout` only)**: The initial definitions and assignments are complete, not provisional. If actual adaptive construction genuinely changes reusable framing or slot topology/bounds, Executor creates one new `pptx_layouts` definition sourced from that page and updates its `page_pptx_layouts` assignment while authoring the first page. It never mutates a reused contract silently. Export only compiles declared structure and never discovers or clusters Layouts.
+ - **page_layouts (`mirror` / `layout` only)**: Add one `P<NN>: <svg_basename>` row for every page. This is the complete authoring-input prototype mapping. Strict preserves that SVG's structural contract; adaptive keeps its Master and may explicitly define and assign a new output Layout identity during page authoring. Mirror additionally preserves literal visuals and text-node topology. Omit the whole section for free-design, brand-only, and `style` routes.
- **page_charts (write only for chart pages that match a catalog template)**: For each page in `design_spec.md §VII` whose `reference template path` points to `templates/charts/<name>.svg`, add `P<NN>: <chart_name>`. Pages with `no-template-match` in §VII MUST NOT appear here (Executor would look for a non-existent reference). If the deck has no data-visualization pages, omit the section.
- - **Hard rule**: Use both `page_layouts` and `page_charts` only with a compatible template shell. For a chart page without an exact roster match, adaptive mode selects the closest neutral input prototype and assigns an explicit output Layout key in the planning map; strict mode must select an existing compatible Layout or revise the outline. Never omit `page_layouts` inside a new deck/layout template route.
+ - **Hard rule**: On `template_reuse_scope: mirror|layout`, use `page_layouts` together with any `page_charts` entries only when the selected prototype shell is compatible. For a chart page without an exact roster match, adaptive mode selects the closest neutral input prototype and assigns an explicit output Layout key in the planning map; strict mode must select an existing compatible Layout or revise the outline. Never omit `page_layouts` on a structured mirror/layout route. A `style` route may still use chart templates through `page_charts`, but it has no page prototype mapping.
---
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index 64c247d2..dbb9ff02 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -40,7 +40,7 @@ python3 scripts/confirm_ui/server.py <project_path> --shutdown # Step 4 clean
- Refuses to start unless `<project_path>/confirm_ui/recommendations.json` exists (except `--shutdown`, which needs no recommendations).
- Per-project lock at `<project_path>/.confirm_ui.lock` — duplicate launches are refused; stale locks (dead pid) are overwritten.
- Idle auto-shutdown after 900 s by default; `/api/shutdown` exits gracefully and releases the lock.
-- `/api/recommendations` derives `_template_adherence_enabled` from `<project>/templates/design_spec.md` frontmatter. Only `kind: deck` / `kind: layout` enables the Stage-1 field; no template and `kind: brand` force it off even if a stale recommendation contains the key. When enabled but no recommendation was authored, the server supplies `adaptive` as the default recommendation.
+- `/api/recommendations` derives `_template_reuse_scope_enabled`, `_template_adherence_enabled`, and `_template_replication_mode` from `<project>/templates/design_spec.md` frontmatter. Only `kind: deck` / `kind: layout` enables template reuse; no template and `kind: brand` force both fields off even if stale recommendations contain them. The server defaults reuse scope to `layout`, exposes `mirror` only for `replication_mode: mirror`, defaults adherence to `adaptive` for `mirror` / `layout`, and removes adherence for `style`.
Dependency:
@@ -53,16 +53,16 @@ pip install flask
- **Enumerable + custom** — canvas / mode / visual_style / icons. The page lists common options from `static/catalogs.json`, badges the AI's recommendation, and still offers a Custom box for edge cases (custom canvas size, bespoke narrative mode, self-provided icon system, etc.). `visual_style` additionally honors an optional `visual_style_spectrum` that badges a 3-pick personality spectrum (safe / shifted / bold, each with a temperament tag + analogy) in place of the single recommendation — see the schema below.
- **Visual examples for hard-to-name choices** — the full-screen confirmation page loads real SVG page samples from `static/style_previews/` for `visual_style`, and renders real sample SVGs from `templates/icons` for `icons`. These thumbnails make style and icon-library choices visually comparable before the user locks them. Preview copy is fixed role text (big title / section title / body / points), not project content from `recommendations.json`, so users compare visual treatment rather than copywriting. These previews are a confirmation aid only: they do not add fields to `recommendations.json` or `result.json`, and they do not replace the later Step 6 live preview.
- **Image usage multi-select** — image sources are selected as one or more catalog ids: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. `none` is exclusive. Recommendation and result values may be a legacy single string, but new files should use an array. When several sources are recommended, write the source ids to `recommend.image_usage` and write the actual usage strategy to `image_notes`, not a custom prose value.
-- **Closed enumerable** — template adherence (conditional), formula policy / generation mode / refine spec, plus AI source only when image usage includes `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option. Use pipeline vocabulary: icon ids are actual library ids such as `tabler-outline`, or `emoji` for system emoji.
+- **Closed enumerable** — template reuse scope + template adherence (conditional), formula policy / generation mode / refine spec, plus AI source only when image usage includes `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option. Use pipeline vocabulary: icon ids are actual library ids such as `tabler-outline`, or `emoji` for system emoji.
- **Generative (open)** — color, typography, generated-image style. No finite catalog; the AI authors **≥3 candidates** the page renders as cards (never a single option — creative fields must offer real choice; fewer than 3 only on the honest-shortfall exception). `page_count`, `audience`, and `content_divergence` are free inputs (`content_divergence` is a free-text intent shown under audience in §c, not a fixed-option field).
-**Custom box** appears only on fields whose universe is genuinely open — `canvas`, `mode`, `visual_style`, and `icons`. Image usage uses a multi-select source list plus `image_notes` instead of a Custom box. Fully closed sets — `template_adherence`, `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec` — have **no** Custom box; an out-of-catalog value there is snapped back to the recommended option.
+**Custom box** appears only on fields whose universe is genuinely open — `canvas`, `mode`, `visual_style`, and `icons`. Image usage uses a multi-select source list plus `image_notes` instead of a Custom box. Fully closed sets — `template_reuse_scope`, `template_adherence`, `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec` — have **no** Custom box; an out-of-catalog value there is snapped back to the recommended option.
`image_ai_path` is conditional: the page shows it and writes it to `result.json` only when `image_usage` includes `ai`. Web-sourced / User-provided / Placeholder / No images paths do not carry an AI backend choice.
## Catalogs — `static/catalogs.json` (the finite option universe)
-The front-end loads `/api/catalogs` (served by the confirm server) and falls back to the static `/static/catalogs.json` if that route is unavailable. `/api/catalogs` returns the static file **with the `canvas` list synced live from `config.py CANVAS_FORMATS`** — the set of formats and their `dim` come from config (single source of truth, zero drift), while trilingual labels / use text stay in catalogs.json (a plain fallback label is synthesized for any new id config adds). Keys: `canvas`, `modes`, `visual_styles` (grouped), `template_adherence`, `icons`, `image_usage`, `image_ai_path`, `formula_policy`, `generation_mode`, `delivery_purpose`. Each entry is `{ "id", "label", "label_zh", "label_en", "label_ja", ... }`; descriptions use `desc_zh` / `desc_en` / `desc_ja`, and `visual_styles` groups use `group_zh` / `group_en` / `group_ja`. The front-end falls back to legacy `label` / `desc` / `group`, so old catalogs still load, but new user-facing catalog text must cover all three languages (zh / en / ja). English labels should mirror canonical reference names (`pyramid`, `swiss-minimal`, `Path A`, `mixed`, etc.); Chinese and Japanese labels should be translated for users. Descriptions render inline after the option title, not as a separate selected-option line. `visual_styles` is `[{ "group", "group_zh", "group_en", "group_ja", "items": [...] }]`. For `canvas` you only need to maintain the trilingual labels in catalogs.json; the format set and dimensions are authoritative in `config.py CANVAS_FORMATS`.
+The front-end loads `/api/catalogs` (served by the confirm server) and falls back to the static `/static/catalogs.json` if that route is unavailable. `/api/catalogs` returns the static file **with the `canvas` list synced live from `config.py CANVAS_FORMATS`** — the set of formats and their `dim` come from config (single source of truth, zero drift), while trilingual labels / use text stay in catalogs.json (a plain fallback label is synthesized for any new id config adds). Keys: `canvas`, `modes`, `visual_styles` (grouped), `template_reuse_scope`, `template_adherence`, `icons`, `image_usage`, `image_ai_path`, `formula_policy`, `generation_mode`, `delivery_purpose`. Each entry is `{ "id", "label", "label_zh", "label_en", "label_ja", ... }`; descriptions use `desc_zh` / `desc_en` / `desc_ja`, and `visual_styles` groups use `group_zh` / `group_en` / `group_ja`. The front-end falls back to legacy `label` / `desc` / `group`, so old catalogs still load, but new user-facing catalog text must cover all three languages (zh / en / ja). English labels should mirror canonical reference names (`pyramid`, `swiss-minimal`, `Path A`, `mixed`, etc.); Chinese and Japanese labels should be translated for users. Descriptions render inline after the option title, not as a separate selected-option line. `visual_styles` is `[{ "group", "group_zh", "group_en", "group_ja", "items": [...] }]`. For `canvas` you only need to maintain the trilingual labels in catalogs.json; the format set and dimensions are authoritative in `config.py CANVAS_FORMATS`.
## Round-trip data contract
@@ -74,7 +74,7 @@ The page runs as a **three-stage wizard in one browser session**. `recommendatio
| `recommendations.json stage` | Page renders | Button | On submit |
|---|---|---|---|
-| `"stage1"` | direction anchors — canvas, audience + `content_divergence` + `delivery_purpose` *(PPT only — omitted on non-PPT canvases, not written to the result)*, mode + visual_style, plus `template_adherence` only when a deck/layout template is active | **Next** | writes `result.json` `{ stage: "stage1", status: "stage1-confirmed", <anchors> }`; the page does **not** close — it shows a "deriving…" state and polls `GET /api/recommendations` |
+| `"stage1"` | direction anchors — canvas, audience + `content_divergence` + `delivery_purpose` *(PPT only — omitted on non-PPT canvases)*, mode + visual_style, plus `template_reuse_scope` and conditional `template_adherence` when a deck/layout template is active | **Next** | writes `result.json` `{ stage: "stage1", status: "stage1-confirmed", <anchors> }`; the page does **not** close — it shows a "deriving…" state and polls `GET /api/recommendations` |
| `"stage2"` | design system — page count, color, icons, typography, formula policy | **Next** | writes `result.json` `{ stage: "stage2", status: "stage2-confirmed", <anchors + design system> }`; the page stays open and polls for Stage 3 |
| `"stage3"` | images and execution — image usage + generated-image style, generation mode, refine spec | **Confirm** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
| *(absent)* | legacy single-pass — every section on one page | **Confirm** | single final write (`status: "confirmed"`) — backward-compatible |
@@ -93,6 +93,7 @@ The AI launches Stage 1 (`--daemon --wait`), reads the stage-1 result, **re-deri
"canvas": "ppt169",
"mode": "pyramid",
"visual_style": "swiss-minimal",
+ "template_reuse_scope": "layout",
"template_adherence": "adaptive",
"icons": "tabler-outline",
"image_usage": ["ai", "provided"],
@@ -155,7 +156,8 @@ The AI launches Stage 1 (`--daemon --wait`), reads the stage-1 result, **re-deri
> Each `candidates` array above shows **one** entry for brevity — `color` and `typography` must each carry **≥3** in a real file, while `image_strategy.candidates` should carry **exactly 3 non-custom recommendation** entries when AI image generation is offered. The UI adds the fourth **Custom** card itself; `selected` indexes the recommended default among the recommendation entries.
- `recommend.*` names the recommended `id` for each enumerable field (must match a `catalogs.json` id, or be a free string for a recommended custom value). The page badges and pre-selects it. **Guarantee**: if a `recommend.*` is omitted, the page falls back to the first catalog option so every enumerable field always shows one badged recommendation — but the AI should still set them for a meaningful default. Legacy aliases are accepted for old files (`line` → `tabler-outline`, `filled` → `tabler-filled`, `monochrome` → `chunk-filled`, `search` → `web`, `default` → `auto`, `builtin` → `host-native`), but new files should write canonical ids.
-- `recommend.template_adherence` is conditional. Write `adaptive` or `strict` only when Step 3 loaded a `kind: deck` or `kind: layout` template. The server independently checks the copied template spec and enables the field only for those two kinds; free design and brand-only templates cannot display or return it. If the template is active but the recommendation key is missing, the server supplies `adaptive`. Both values use explicit template export and require a reference SVG for every page: `strict` keeps the selected Layout contract; `adaptive` may create a new Layout under the same Master.
+- `recommend.template_reuse_scope` is conditional. Write `layout`, `style`, or `mirror` only when Step 3 loaded a `kind: deck` or `kind: layout` template. The default is `layout`; `mirror` is displayed only when the installed spec declares `replication_mode: mirror`. `style` means free-design `pptx_structure.mode: flat` and suppresses/removes `template_adherence`.
+- `recommend.template_adherence` is conditional on reuse scope `mirror` or `layout`. Write `adaptive` or `strict`; the default is `adaptive`. Both values require a reference SVG for every page: `strict` keeps the selected Layout contract; `adaptive` may create a new Layout under the same Master. Free design, brand-only templates, and `style` cannot display or return this field.
- `recommend.image_usage` should be an array of source ids when more than one source applies, e.g. `["ai", "provided"]`. A single string is still accepted for backward compatibility. Do not write bare `"custom"` and do not encode a mixed-source plan as prose here; write the prose to top-level `image_notes.value`.
- `image_notes` is the initial strategy note shown under the image source chips. Use it for page-role guidance and constraints: which source applies where, what to avoid, which user assets are authoritative, how realistic / abstract the imagery should be, and what can remain as placeholders. It is intent guidance, not a separate finite option.
- When `recommend.image_usage` includes `ai`, also set `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`; the page presents these as explicit choices.
@@ -181,6 +183,7 @@ The AI launches Stage 1 (`--daemon --wait`), reads the stage-1 result, **re-deri
"content_divergence": "freely restructure and expand within the source",
"mode": "pyramid",
"visual_style": "swiss-minimal",
+ "template_reuse_scope": "layout",
"template_adherence": "adaptive",
"color": { "name": "...", "palette": { "background": "#...", "secondary_bg": "#...", "primary": "#...", "accent": "#...", "secondary_accent": "#...", "body_text": "#..." } },
"icons": "tabler-outline",
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index f29b0763..24c40812 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -271,9 +271,18 @@ python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio
Behavior:
- Default output (default-flow mode, no `-o`):
- `exports/<project_name>_<timestamp>.pptx` — native editable pptx (canonical output)
+ - `exports/<project_name>_<timestamp>.report.json` — package postflight, quality-gate linkage, unresolved resource audit, and published part counts
- `backup/<timestamp>/svg_output/` — copy of Executor SVG source, always written so the pptx can be rebuilt via `finalize_svg → svg_to_pptx` without re-running the LLM
- `finalize_svg.py` always creates `svg_final/` before export. This directory is the self-contained SVG visual preview; it is not packaged as a second PPTX.
- Explicit `-o/--output` changes the native PPTX destination and skips `backup/`.
+- Postflight reruns ZIP integrity and published Slide count. Internal relationships,
+ structured-package validation, transitions, and animations are enforced before the
+ builder publishes the PPTX and are reported as `enforced-at-build`, not as repeated
+ postflight checks.
+- `font_portability` warns only when a complete font stack contains generic CSS families
+ and no concrete family name. A recommended stack such as
+ `"Microsoft YaHei", Arial, sans-serif` does not warn merely because it ends with a
+ generic fallback.
- Paragraph merging is enabled by default and trades some SVG line-layout fidelity for PowerPoint editability:
- Default: mergeable paragraph blocks (same x, dy clustered around one base line-height) collapse into one editable text frame. Equal effective font sizes may join as flowing prose; a font-size change, list marker, or accepted larger gap starts a new `<a:p>` with precise `<a:lnSpc>` / `<a:spcBef>`. Resizing the box reflows text inside it without erasing those paragraph boundaries.
- With `--no-merge`: every dy-stacked `<tspan>` becomes its own text frame — exact SVG line layout is preserved but a 12-line paragraph is 12 separate textboxes
@@ -288,7 +297,7 @@ Behavior:
inputs and package-level processing.
- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.
- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content.
-- Omitting `--pptx-structure` reads `spec_lock.md`. Free-design and brand-only releases declare `mode: flat`, omit Master/Layout mappings and SVG structure metadata, and materialize one clean project-owned Master plus one Blank Layout from the current lock. Deck/layout template releases declare `mode: structured` with complete unique `pptx_masters` / `pptx_layouts` rosters and one `page_pptx_layouts` assignment per page. A template-backed Layout definition may remain unused by pages and still register in the final package.
+- Omitting `--pptx-structure` reads `spec_lock.md`. Free-design, brand-only, and `template_reuse_scope: style` releases declare `mode: flat`, omit Master/Layout mappings and SVG structure metadata, and materialize one clean project-owned Master plus one Blank Layout from the current lock. Deck/layout templates use `mode: structured` only for `template_reuse_scope: mirror|layout`, with complete unique `pptx_masters` / `pptx_layouts` rosters and one `page_pptx_layouts` assignment per page. A template-backed Layout definition may remain unused by pages and still register in the final package.
- On structured template routes, every page root repeats Master/Layout keys and picker names. Master/Layout fixed visuals are direct semantic atoms. Ordinary layer `<g>` elements are invalid; one validated compact authored-preset `<g>` emitted by `preset_shape_svg.py` is the sole group exception because it compiles to one native shape.
- On structured template routes, each normal slot is a direct root `<g id>` with semantic type, positive design-zone bounds, and exactly one compatible carrier. Composite `object` slots use explicit proxy binding; zero-slot Layouts are valid. Flat pages keep all SVG objects Slide-local.
- Flat export maps locked typography/colors into a clean project-owned theme/Master, removes stock content placeholders and unused built-in Layouts, retains only the standard date/footer/slide-number capability hooks, and keeps one Blank Layout without promoting Slide content. Structured export additionally creates one reusable Layout per declared key and reopens the package to verify the full Presentation → Master → Layout → Slide graph, fixed-object order, placeholder identities/bounds, carrier bindings, hidden proxies, and zero-slot Layouts.
@@ -297,6 +306,7 @@ Behavior:
- Native output uses content-hash media filenames, so identical images are reused and different images cannot overwrite each other by sharing a basename.
- `[Content_Types].xml` is generated from the actual media extensions written into the PPTX. Unknown media extensions fail unless Python's `mimetypes` can identify them.
- Native export writes to a temporary file first and publishes the requested PPTX only after conversion succeeds. A failed conversion does not replace the main output file.
+- After publication, native export writes `<output_stem>.report.json`. The report distinguishes authored Slides from internal Layout definitions, reruns ZIP integrity and published Slide-count checks, records slide/layout/master/notes part counts, labels relationship/structured/transition/animation validation as enforced at build time, links the final SVG quality report only when its SHA-256 source fingerprint matches the exact export inputs, and surfaces stale/unverified gates, unresolved template tokens, generic-only font stacks, and external image references.
- Before publishing structured template output, export reopens the temporary PPTX and validates the Slide → Layout → Master graph and registrations, Layout identity, placeholder identity, reusable bounds, and prompt/level-one sizes. A mismatch aborts publication. Flat release instead validates its single referenced Master/Layout shell and exact date/footer/slide-number hook roster before packaging.
- SVG clip paths are still restricted for authored SVGs, but nested crop wrappers generated by PPTX import are mapped back to native picture crop / geometry when possible.
- Speaker notes are embedded automatically unless `--no-notes` is used
@@ -360,6 +370,8 @@ Validate SVG technical compliance.
python3 scripts/svg_quality_checker.py examples/project/svg_output/01_cover.svg
python3 scripts/svg_quality_checker.py examples/project/svg_output
python3 scripts/svg_quality_checker.py examples/project
+python3 scripts/svg_quality_checker.py examples/project --stage first-page
+python3 scripts/svg_quality_checker.py examples/project --stage final --json
python3 scripts/svg_quality_checker.py examples/project --format ppt169
python3 scripts/svg_quality_checker.py --all examples
python3 scripts/svg_quality_checker.py examples/project --export
@@ -377,6 +389,16 @@ Checks include:
Warnings are advisory: they require no modification or acknowledgement and do
not affect the command's zero exit status. Only errors block the quality gate.
+`--stage first-page` resolves only the first authored SVG and permits an incomplete
+future page roster. `--stage final` checks the complete project. With `--json`,
+the final stage writes `exports/svg_quality_report.json`, while the first-page
+stage writes `exports/svg_quality_first_page_report.json` so it cannot overwrite
+the release gate (or use `--json-output`). The report separates
+release failures (`blocking`), changed/new advisories (`introduced`),
+prototype-identical diagnostics (`inherited`), and source-conversion losses
+(`source-import`). It also fingerprints every checked SVG so postflight cannot
+mistake a stale report for the current export gate.
+
Template mode accepts the same compact canonical preset groups as generated
pages: one atomic `<g data-pptx-authoring="preset">` with direct visible paths.
It validates those paths dynamically against the locked registry and does not
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 10546642..78c0a754 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -16,7 +16,8 @@
| **Use Case** | [Filled by Strategist] |
| **Delivery Purpose** | [`text` read-close / `balanced` business / `presentation` — confirmed at c; a deck-wide consumption mode that drives per-page density, page-count recommendation, page_rhythm lean, and the body baseline (px). See strategist.md §6.1.] |
| **Content Strategy** | [Material divergence — the user's free-text intent on how closely to follow the source vs how freely to reshape it (or "balanced default"); facts stay sourced however free. Confirmed at c; consumed when authoring §IX. Not in spec_lock.] |
-| **Template Adherence** | [`adaptive` / `strict` — include only when Step 3 loaded a deck/layout template; omit for free design and brand-only templates. Also written under `spec_lock.md pptx_structure`.] |
+| **Template Reuse Scope** | [`mirror` / `layout` / `style` — include only when Step 3 loaded a deck/layout template; omit for free design and brand-only templates. `mirror` requires a mirror-capable workspace; `style` uses the flat route.] |
+| **Template Adherence** | [`adaptive` / `strict` — include only when Template Reuse Scope is `mirror` or `layout`; omit for `style`. Also written under `spec_lock.md pptx_structure`.] |
| **Created Date** | {date_str} |
---
@@ -308,7 +309,7 @@ Catalog read: 76 templates
## IX. Content Outline
-> **Native Layout boundary**: Each `Layout` line below always describes visual composition intent. On free-design and brand-only routes, it does not create native Master/Layout identity: `spec_lock.md` uses `pptx_structure.mode: flat`, omits `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and every SVG object stays Slide-local. Export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. Deck/layout template routes use `mode: structured`: Strategist writes each unique Master/Layout definition once, assigns every page through `page_pptx_layouts`, and selects its authoring prototype through `page_layouts`. Strict preserves the prototype contract. Adaptive keeps its Master and may define and assign a new Layout key during page authoring only when fixed Layout atoms or slot topology/bounds change. Legacy prototypes are not selectable; create a current workspace through [`create-template`](../workflows/create-template.md) and generate new SVG pages from it. No deferred distillation or immediate-compatibility fallback exists.
+> **Native Layout boundary**: Each `Layout` line below always describes visual composition intent. On free-design, brand-only, and `template_reuse_scope: style` routes, it does not create native Master/Layout identity: `spec_lock.md` uses `pptx_structure.mode: flat`, omits `pptx_masters` / `pptx_layouts` / `page_pptx_layouts` / `page_layouts`, and every SVG object stays Slide-local. Export materializes one clean project-owned Master plus one Blank Layout from the current lock, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. `template_reuse_scope: mirror|layout` uses `mode: structured`: Strategist writes each unique Master/Layout definition once, assigns every page through `page_pptx_layouts`, and selects its authoring prototype through `page_layouts`. Strict preserves the prototype contract. Adaptive keeps its Master and may define and assign a new Layout key during page authoring only when fixed Layout atoms or slot topology/bounds change. Mirror also preserves literal visuals and text-node topology; layout permits project-controlled reflow/re-skinning. Legacy prototypes are not selectable; create a current workspace through [`create-template`](../workflows/create-template.md) and generate new SVG pages from it. No deferred distillation or immediate-compatibility fallback exists.
### Part 1: [Chapter Name]
@@ -325,6 +326,8 @@ Catalog read: 76 templates
- **Layout**: [Choose a pattern from §V, combine two, or break the grid as the content demands]
- **Title**: [Page title]
- **Core message**: [the one thing this page exists to land — its spine, always phrased as one assertion sentence (prose by nature). One per page; can't name it → merge or cut the page.]
+- **Fact IDs**: [stable IDs from `sources/*.facts.json` used on this page, e.g. `F001, F004`; omit when none]
+- **Data class**: [`external` for sourced facts / `scenario` for invented demo KPIs, targets, internal ratios; identify the affected values when scenario; omit when the page has no factual/quantitative claims]
- **Visualization**: [visualization_type] (see VII. Visualization Reference List)
- **Content**: write each block in the phrasing that fits it (prose / bullet / keyword / … any phrasing the content calls for) and write it already in that mode, so the texture itself carries the intent — a prose block reads as a real sentence, not a fragment. One page may mix modes; blocks still sit under the core message, never replace it:
- [a connected sentence or two that argues the point]
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 602a4347..6d2b6284 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -127,26 +127,35 @@
## pptx_structure
- mode: flat
-> One deck-wide native PowerPoint structure policy. Free-design and brand-only routes use `flat`; deck/layout template routes use `structured`.
+> One deck-wide native PowerPoint structure policy. Free-design, brand-only, and template style-reference routes use `flat`; template layout/mirror routes use `structured`.
>
> `flat` keeps every SVG object Slide-local. Export materializes one clean project-owned Master plus one Blank Layout, maps the current color/typography lock into the theme and Master defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. In this mode, omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`, and do not add root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder*` metadata to generated pages.
>
-> When Step 3 loaded a deck/layout template, replace the `flat` row above with exactly one of:
+> When a loaded deck/layout template is used only as a visual-style reference, write:
+> ```
+> - mode: flat
+> - template_reuse_scope: style
+> ```
+> `style` may retain template-derived color/typography/decoration values elsewhere in this lock, but it MUST omit `template_adherence` and every structured mapping.
+>
+> For layout-system reuse, replace the `flat` row above with:
> ```
> - mode: structured
+> - template_reuse_scope: layout
> - template_adherence: adaptive
> ```
-> or:
+> Use `strict` instead of `adaptive` when the selected Layout contract cannot change. For literal page replacement from a mirror-capable workspace, write:
> ```
> - mode: structured
+> - template_reuse_scope: mirror
> - template_adherence: strict
> ```
-> Both values require complete `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts` sections. Existing legacy template SVGs that lack the current root Master identity, grouped slot/carrier contract, or positive bounds cannot be selected or upgraded in place. Create a current workspace through [`create-template`](../workflows/create-template.md), then generate new structured pages from it.
+> `mirror` is legal only when the installed template frontmatter declares `replication_mode: mirror`; it preserves literal visuals and the complete `<text>` / `<tspan>` topology while replacing visible values. Both `layout` and `mirror` require complete `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts` sections. Existing legacy template SVGs that lack the current root Master identity, grouped slot/carrier contract, or positive bounds cannot be selected or upgraded in place. Create a current workspace through [`create-template`](../workflows/create-template.md), then generate new structured pages from it.
## pptx_masters
- master-default: Default Master
-> Deck/layout template routes only. One row per Master: `<master_key>: <PowerPoint picker name>`. A key contains 1–64 ASCII letters, digits, dots, underscores, or hyphens; its first character is a letter or digit. Spaces belong only in the PowerPoint picker name, never in the key. Keys are deck-unique and stable. Omit this entire section when `pptx_structure.mode: flat`.
+> Structured `template_reuse_scope: mirror|layout` routes only. One row per Master: `<master_key>: <PowerPoint picker name>`. A key contains 1–64 ASCII letters, digits, dots, underscores, or hyphens; its first character is a letter or digit. Spaces belong only in the PowerPoint picker name, never in the key. Keys are deck-unique and stable. Omit this entire section when `pptx_structure.mode: flat`.
## pptx_layouts
- cover-hero-split: master-default | Cover — Hero Split | template:01_cover
@@ -154,7 +163,7 @@
- content-two-column: master-default | Two Column | template:03a_content_abstract
- quote-focus: master-default | Quote Focus | template:04_quote_focus
-> Deck/layout template routes only. This is the unique reusable Layout roster, not a page roster. Layout keys use the same grammar as Master keys. Value format: `<master_key> | <PowerPoint layout name> | <prototype source>`. Supply all three non-empty fields separated by `|`. A prototype source is either `P<NN>` for one generated page carrying that exact Layout contract, or `template:<basename>` for an installed `templates/<basename>.svg`; the `template:` prefix is required, so a bare basename is invalid. Omit this section when `pptx_structure.mode: flat`.
+> Structured `template_reuse_scope: mirror|layout` routes only. This is the unique reusable Layout roster, not a page roster. Layout keys use the same grammar as Master keys. Value format: `<master_key> | <PowerPoint layout name> | <prototype source>`. Supply all three non-empty fields separated by `|`. A prototype source is either `P<NN>` for one generated page carrying that exact Layout contract, or `template:<basename>` for an installed `templates/<basename>.svg`; the `template:` prefix is required, so a bare basename is invalid. Omit this section when `pptx_structure.mode: flat`.
>
> Every Layout key appears exactly once, belongs to exactly one declared Master, and is globally unique even when two Masters use the same picker name. Every declared Master owns at least one Layout definition. A Layout may remain unused by generated pages; such a Layout must use `template:<basename>` so export can register it without manufacturing a published slide.
>
@@ -172,20 +181,20 @@
- P03: content-two-column
- P04: content-two-column
-> Deck/layout template routes only. Include exactly one row per generated page. The value is one key declared in `pptx_layouts`; Master and picker name come from that unique definition and are not repeated per page. The generated SVG root must match the assigned definition. Omit this section when `pptx_structure.mode: flat`.
+> Structured `template_reuse_scope: mirror|layout` routes only. Include exactly one row per generated page. The value is one key declared in `pptx_layouts`; Master and picker name come from that unique definition and are not repeated per page. The generated SVG root must match the assigned definition. Omit this section when `pptx_structure.mode: flat`.
## page_layouts
- P01: 01_cover
- P03: 02a_chapter
- P04: 03a_content_abstract
-> For a deck/layout template route, include one entry per page. Key: `P<NN>` matching §IX. Value: the template SVG basename without extension. This is the authoring-input prototype mapping; `page_pptx_layouts` is the output page assignment, while `pptx_layouts` defines the unique reusable roster. Strict preserves the prototype Master/Layout/slot contract. Adaptive retains its Master contract and may explicitly define and assign a new Layout key while authoring. Non-mirror skin follows the project lock.
+> For `template_reuse_scope: mirror|layout`, include one entry per page. Key: `P<NN>` matching §IX. Value: the template SVG basename without extension. This is the authoring-input prototype mapping; `page_pptx_layouts` is the output page assignment, while `pptx_layouts` defines the unique reusable roster. Strict preserves the prototype Master/Layout/slot contract. Adaptive retains its Master contract and may explicitly define and assign a new Layout key while authoring. `layout` skin follows the project lock; `mirror` preserves literal visual/text topology.
>
> **No entry for a page** is an error in structured template mode.
>
> **Hard rule**: Use both `page_layouts` and `page_charts` only with a compatible shell. Adaptive mode may start from a neutral content template and finalize a new explicit Layout after design; strict mode must choose an existing compatible Layout or revise the outline.
>
-> **Whole section omitted** → required for free-design and brand-only `flat` routes. Template strict/adaptive routes require complete `page_layouts`. A legacy package that cannot satisfy the current structured contract must migrate before use; it never enters a compatibility branch inside normal generation.
+> **Whole section omitted** → required for free-design, brand-only, and `template_reuse_scope: style` flat routes. `mirror` / `layout` strict/adaptive routes require complete `page_layouts`. A legacy package that cannot satisfy the current structured contract must migrate before use; it never enters a compatibility branch inside normal generation.
>
> **Strategist source**: record each project-page choice in project `design_spec.md §IX Content Outline`, using the copied template package's `templates/design_spec.md §V Page Roster` descriptions as the roster authority. Basenames must match files in `templates/` exactly. A typo is a blocking contract error: stop before drawing and report it; never fall back to free design inside template mode.
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 01c25e12..de96c784 100644
--- a/skills/ppt-master/workflows/create-template.md
+++ b/skills/ppt-master/workflows/create-template.md
@@ -520,7 +520,12 @@ extracted-vector inventory. It then stages and publishes the entire roster in
one operation. It emits source-ordered page SVGs, unused-Layout definition
SVGs, `icons/imported/`, referenced `images/` / `templates/assets/`, and one
deduplicated `templates/native_payloads.json.gz` store when supported native
-payload or repeated restoration metadata exists. Template SVGs and imported
+payload or repeated restoration metadata exists. It also writes
+`templates/template_execution_manifest.json`, a compact model-readable prototype
+roster and grouped source-import warning summary. Each prototype points to one
+`templates/template_execution/*.text-slots.json` sidecar containing its exact
+mirror text selectors, segments, attributes, topology hashes, bounds, and font
+stacks. Template SVGs and imported
vectors keep content-hash payload references plus short
`data-pptx-native-ref` attribute-record ids. Structural Master/Layout,
placeholder, layer, and editable-object fields remain inline. The command does
@@ -569,7 +574,7 @@ syntax here; its single authority is
[`shared-standards.md`](../references/shared-standards.md), with selection and
usage guidance in the native-shape reference.
-Downstream, both template-adherence choices use `pptx_structure.mode: structured`. `page_layouts` selects one complete authoring prototype per page, `pptx_masters` / `pptx_layouts` declare unique reusable definitions, and `page_pptx_layouts` assigns generated pages. Strict preserves the selected prototype contract. Adaptive keeps its Master and may explicitly create and assign a new Layout key/name while authoring the page that needs it. A retained Layout may remain unassigned while still registering through its definition SVG. A mirror-created package does not force a future generated deck to keep the source page count or order.
+Downstream, a mirror-created workspace supports three separately confirmed reuse scopes. `mirror` and `layout` use `pptx_structure.mode: structured`; `page_layouts` selects one complete authoring prototype per page, `pptx_masters` / `pptx_layouts` declare unique reusable definitions, and `page_pptx_layouts` assigns generated pages. Strict preserves the selected prototype contract. Adaptive keeps its Master and may explicitly create and assign a new Layout key/name while authoring the page that needs it. `mirror` additionally preserves literal visuals/text topology; `layout` allows project-controlled reflow/re-skinning. `style` uses `mode: flat` and takes only the workspace's design language. A retained Layout may remain unassigned while still registering through its definition SVG. No scope forces a future generated deck to keep the source page count or order.
**Apply the visual-fidelity decision from Step 3 to authored modes**: in `standard` / `fidelity`, pages marked `literal` reproduce the selected reference geometry and decoration while still using a newly designed structure; pages marked `adapted` may evolve the composition. Mirror preserves every supported source visual represented by the validated IR and does not use this authored-page distinction.
@@ -681,6 +686,7 @@ This checker validates the authoring contract, not the compiled OOXML package. T
- [ ] `standard` / `fidelity` output SVGs and their Master/Layout/slot contracts were newly authored without preserving or distilling source topology
- [ ] Every additional authored Master represents a distinct reusable design family, not one Layout or an equivalent duplicate; every declared Master owns at least one emitted Layout and every declared Layout has at least one emitted prototype
- [ ] Mirror output preserves source slide order, Master/Layout identity and parentage, placeholder facts, and ownership; fixed-layer group expansion is mechanical and pixel-equivalent, and the Source Preservation Map lists every source slide
+- [ ] Mirror materialization wrote the compact `templates/template_execution_manifest.json`; each prototype is listed once and links one `template_execution/*.text-slots.json` sidecar, every sidecar slot records selector/current segments/tspan attributes/topology hash/bounds/font stack, and source-import diagnostics are summarized separately from downstream generation issues
- [ ] Mirror roots preserve source inherited-shape visibility with canonical lowercase `data-pptx-show-master-shapes` and `data-pptx-show-inherited-shapes`; same-key Layouts agree on the former, while each Slide retains its own latter value
- [ ] Mirror preflight covered the complete source graph; each unused Layout has one `layout_<layout_key>.svg` definition prototype and each otherwise-unused Master is retained through at least one such Layout
- [ ] For `standard` / `fidelity`, no duplicate-Layout-contract warning remains; mirror may keep equivalent source Layout identities when the preservation map explains them
diff --git a/skills/ppt-master/workflows/stages/refine-spec.md b/skills/ppt-master/workflows/stages/refine-spec.md
index 33a1fa83..50bd3fb4 100644
--- a/skills/ppt-master/workflows/stages/refine-spec.md
+++ b/skills/ppt-master/workflows/stages/refine-spec.md
@@ -49,7 +49,7 @@ These overlap with what the locked `mode`, visual style, and §6.1 already shape
**Keep both files in sync on every change.** Any revision the user approves must land in both `design_spec.md` and `spec_lock.md`; on divergence `spec_lock.md` wins (see [`strategist.md`](../../references/strategist.md) §6.2). Iterate as many rounds as the user wants. The loop ends only when the user explicitly approves the spec.
-**Re-run the structured-template preflight after structural revisions.** If the user changes `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the Strategist preflight in [`strategist.md`](../../references/strategist.md) §6.2 before approval and hand-back. Every newly selected prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype is not selectable; create a current workspace through [`create-template`](../create-template.md) before refinement.
+**Re-run the route/template preflight after reuse revisions.** If the user changes `template_reuse_scope`, `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the Strategist preflight in [`strategist.md`](../../references/strategist.md) §6.2 before approval and hand-back. Switching to `style` rewrites the route to `pptx_structure.mode: flat` and removes all structure mappings/adherence; switching to `mirror` / `layout` restores a complete structured contract. Every newly selected structured prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype is not selectable; create a current workspace through [`create-template`](../create-template.md) before refinement.
---
diff --git a/skills/ppt-master/workflows/stages/topic-research.md b/skills/ppt-master/workflows/stages/topic-research.md
index 4ee0eb9a..aa5fa5a5 100644
--- a/skills/ppt-master/workflows/stages/topic-research.md
+++ b/skills/ppt-master/workflows/stages/topic-research.md
@@ -4,7 +4,7 @@ description: Main-pipeline intake stage that gathers source material for topic-o
# Topic Research Stage
-> Generate-PPTX intake stage. Run before SKILL.md Step 1 when the user supplies only a topic or requirements with no source files. Output is a research document + image folder, both shaped to feed `project_manager.py import-sources` directly.
+> Generate-PPTX intake stage. Run before SKILL.md Step 1 when the user supplies only a topic or requirements with no source files. Output is a research document, a stable fact-provenance file, and an image folder, all shaped to feed `project_manager.py import-sources` directly.
This stage is **context-independent**: it owns source acquisition when no file exists; subsequent SKILL.md steps proceed normally with the produced materials as input.
@@ -74,11 +74,12 @@ python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>
## Step 3: Save materials
-Two artifacts under `projects/`:
+Three artifacts under `projects/`:
| Artifact | Path |
|---|---|
| Research document | `projects/<topic_slug>.md` |
+| Fact provenance | `projects/<topic_slug>.facts.json` |
| Image folder | `projects/<topic_slug>/` |
**Hard rule — naming**: filename (without `.md`) and folder name MUST match. **Hard rule — location**: under `projects/`, never the repository root.
@@ -87,6 +88,27 @@ Two artifacts under `projects/`:
**Content density** — concrete facts (dates, names, numbers, quotes). Skip filler prose; the Strategist composes final slide copy.
+**Fact provenance** — write every externally sourced, verifiable claim that may enter the deck to `<topic_slug>.facts.json` with a stable sequential ID, especially quantitative, date, ranking, attribution, and named-entity claims. Do not put invented demonstration values in this file; Strategist marks those as `scenario` later. When research yields no external claims, still write the schema with an empty `facts` array.
+
+```json
+{
+ "schema": "ppt-master.fact-provenance.v1",
+ "topic": "<topic>",
+ "facts": [
+ {
+ "fact_id": "F001",
+ "claim": "One concise, presentation-ready factual claim",
+ "source_title": "Authoritative page title",
+ "source_url": "https://example.org/source",
+ "classification": "external",
+ "retrieved_at": "YYYY-MM-DD"
+ }
+ ]
+}
+```
+
+IDs are immutable within the file. If a claim is corrected, update its value/source under the same ID; if a claim is removed, do not silently reuse its ID for a different fact. The research Markdown and `facts.json` must agree.
+
**Images**:
| Decision | Rule |
@@ -110,10 +132,11 @@ Output a checkpoint, then continue with the main pipeline. The artifacts feed di
```markdown
## ✅ Topic Research Complete
- [x] Document: `projects/<topic_slug>.md` (N sections)
+- [x] Facts: `projects/<topic_slug>.facts.json` (N external facts)
- [x] Images: `projects/<topic_slug>/` (N files)
- [ ] **Next**: SKILL.md Step 2 →
`project_manager.py init <project_name> --format <format>`
- `project_manager.py import-sources projects/<project_name> projects/<topic_slug>.md projects/<topic_slug>/*.* --move`
+ `project_manager.py import-sources projects/<project_name> projects/<topic_slug>.md projects/<topic_slug>.facts.json projects/<topic_slug>/*.* --move`
```
`<project_name>` is the user's chosen project identifier (typically `<format>_<topic_slug>`, e.g. `ppt169_joe_hisaishi`); `--move` removes the research artifacts from `projects/<topic_slug>` after they are imported.