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
fix(generate): align planning and execution decision boundaries
hugohe3c33bf6ad519e
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.mdindex e4e65e3a..29538140 100644--- a/docs/powerpoint-svg-mapping.md+++ b/docs/powerpoint-svg-mapping.md@@ -59,10 +59,10 @@ See [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md) for| Free-design deck structure | `pptx_structure.mode: flat`; page content remains slide-local | One clean project Master and one Blank Layout, with represented objects on slides | `Native-stable` package topology for the flat route | No authored Master/Layout/layer/placeholder metadata is allowed || Template-backed deck structure | `pptx_structure.mode: structured` plus explicit Master/Layout/page assignments | Declared `p:sldMaster`, `p:sldLayout`, registrations, and slide parentage | `Native-stable` within the explicit structure contract | The exporter never guesses a Master, Layout, or placeholder topology || Slide Master | Root Master identity plus atomic `data-pptx-layer="master"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Master part and picker identity | Create Template mirror may preserve validated source-package facts in a new workspace; authored modes create a new identity | Master atoms must be direct, stable, and identical across their slides; ordinary or expanded authored groups do not qualify |-| Slide Layout | Root Layout identity plus atomic `data-pptx-layer="layout"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Layout part under one Master | Create Template mirror may preserve a validated source Layout in a new workspace; adaptive authoring may allocate a new Layout | Reuse a Layout key only when its fixed atoms and slot contract are identical; ordinary or expanded authored groups do not qualify |+| Slide Layout | Root Layout identity plus atomic `data-pptx-layer="layout"` objects; one validated compact authored-preset `<g>` counts as one semantic atom | Reusable Layout part under one Master | Create Template mirror may preserve a validated source Layout in a new workspace; Strategist's adaptive plan may declare a new Layout | Reuse a Layout key only when its fixed atoms and slot contract are identical; ordinary or expanded authored groups do not qualify || Imported inherited-shape visibility | Layered analysis records normalized source booleans; a materialized structured mirror writes exact lowercase root `data-pptx-show-inherited-shapes` and `data-pptx-show-master-shapes` | Declared source values written to `p:sld@showMasterSp` and `p:sldLayout@showMasterSp` | `Native-stable`: Slide false hides Layout and Master shapes; Layout false hides only Master shapes | Omission means true; every page using one Layout key must agree on the Layout value. Backgrounds, Slide-local objects, placeholder inheritance, parts, and parent relationships remain intact || Strict template Layout | Selected prototype contract | Existing declared Layout topology is preserved | `Native-stable` when the page follows the prototype | Fixed Layout atoms and slot structure may not change |-| Adaptive template Layout | Selected Master plus an explicit current or newly declared Layout | A new Layout identity may be created when reusable structure changes | `Native-stable` after the lock and page mapping are updated | Never mutate a reused Layout key silently |+| Adaptive template Layout | Selected Master plus an explicit current or new Layout declared by Strategist | A declared new Layout identity is created when reusable structure changes | `Native-stable` after Strategist updates the plan/lock mapping and execution resumes | Construction-discovered changes return upstream; never mutate a reused Layout key downstream || Slide background fill outside structured mode | First eligible full-canvas `<rect>`, direct or in a simple single-child group, with a registered solid, linear/radial gradient, or preset-pattern fill | Native slide `p:bg` | Fidelity follows the corresponding paint row below | Transform, filter, clip, rounding, visible stroke, or an unmapped fill prevents promotion || Master/Layout/slide background fill in structured mode | One direct full-canvas solid `<rect>` in the declared structural layer | Native `p:bg` at Master, Layout, or slide scope | `Native-stable` | Explicit scoped background ownership is intentionally solid-only || Gradient or pattern backdrop in structured mode | Ordinary gradient/pattern `<rect>` on its declared Master/Layout layer or as slide-local content | Editable shape on the owning part | Fidelity follows the corresponding paint row below | Structured export disables generic background promotion; do not use `data-pptx-layer="slide"` |diff --git a/docs/roadmap.md b/docs/roadmap.mdindex c01d7ec2..14d45f92 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -70,7 +70,7 @@ The Generate PPTX route is built around full control of newly authored shapes, tPixel-fidelity across the four renderers (PowerPoint / Keynote / LibreOffice / WPS) is the project's spine. Switching the default route to native PowerPoint charts breaks that — the same PPTX renders different chart layouts across renderers. Charts as SVG is **by design**, not a capability gap.-The narrow exception is the `data-pptx-replace-with` marker: supported data charts and pure text-grid tables carry a PowerPoint-native Chart/Table replacement payload at generation time, and exporting with `--native-charts-and-tables` activates it for users who deliberately trade cross-renderer fidelity for a data-backed object and its chart/table-specific editing model — the activated objects preserve the deck's chart-area / plot / axis / gridline / label colors and native table formatting rather than snapping to PowerPoint's default theme (see the [v4.0.0 release notes](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0)). The default export path and editable SVG-derived shape system are unchanged.+The narrow exception is the `data-pptx-replace-with` marker: independently planned supported data charts and pure text-grid tables can carry a PowerPoint-native Chart/Table replacement payload when their Design Spec §VII row says `Native-ready: yes`; `no` / `n/a` and incidental microvisuals remain ordinary shapes. Exporting with `--native-charts-and-tables` activates prepared markers for users who deliberately trade cross-renderer fidelity for a data-backed object and its chart/table-specific editing model — the activated objects preserve the deck's chart-area / plot / axis / gridline / label colors and native table formatting rather than snapping to PowerPoint's default theme (see the [v4.0.0 release notes](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0)). The default export path and editable SVG-derived shape system are unchanged.### uv as default / required dependencydiff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.mdindex 5bb97014..d6604461 100644--- a/docs/rules/prompt-style.md+++ b/docs/rules/prompt-style.md@@ -51,7 +51,7 @@ Role definition for the **web image acquisition path**: translate Strategist int| `MUST come from Z` | `It is recommended to source from Z` || `Forbidden — unresolved image references` | `Anti-pattern: broken image links` |-**Hard rule**: if a sentence explains *why*, demote it to a single `> Note` blockquote line OR cut it. The agent does not need motivation, only behavior.+**Hard rule — retain failure predicates**: Cut narrative teaching and background motivation. Keep one compact protected invariant or failure predicate when it determines the rule's strength, scope, or safe generalization; attach it to the rule or one `> Note` line. Runtime prompts need the behavior and its objective failure boundary, not the full rationale.---@@ -92,6 +92,8 @@ Begin substantive paragraphs with a bolded short label. Reuse this fixed vocabulBoundary cases go by this test, not by how strong the verb feels: "never split a full sentence into bullets" stays near-MUST because splitting *loses the information that the block was continuous reasoning*, not because "never" sounds strict.+**Hard rule**: A `Hard rule` or `Forbidden` label whose failure boundary is not self-evident retains one compact objective predicate. If no objective predicate exists, demote the instruction to `Default` or `Reference` instead of preserving only a strong verb.+> Note: only a MUST with a concrete objective trigger may become a `svg_quality_checker.py` rule. SHOULD is at most a `warning`; MAY is never checked — encoding taste as a check turns the checker into a de-facto spec.### 4.1 Ownership Contract: Ingredients → Plan + Preparation → Realization@@ -224,3 +226,21 @@ The canonical exemplars to model new files after:| A shared spec across roles | [`image-base.md`](../../skills/ppt-master/references/image-base.md), [`shared-standards-core.md`](../../skills/ppt-master/references/shared-standards-core.md) || A technical / format spec | [`canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md), [`svg-image-embedding.md`](../../skills/ppt-master/references/svg-image-embedding.md), [`image-layout-spec.md`](../../skills/ppt-master/references/image-layout-spec.md) || Stage runbook | [`workflows/stages/verify-charts.md`](../../skills/ppt-master/workflows/stages/verify-charts.md) |++---++## 13. Prompt Refactor Review++Prompt compression is complete only after reviewing token reduction and semantic change separately.++| Check | Required evidence |+|---|---|+| Owner and consumer | Each moved field or capability still has one authority, and every runtime consumer loads or projects that authority |+| Strength delta | Record `before → after` for deleted, moved, or rewritten `Hard rule`, `Forbidden`, `Default`, and `Reference` instructions |+| Failure predicate | Preserve the compact objective invariant that justifies every non-self-evident hard boundary |+| Freedom boundary | A permission did not become a quota, a reference did not become a lock, and flexible realization did not become silent reselection |+| Preparation timing | Strategist-owned acquisition and materialization did not move into Executor or before final confirmation |+| Capability discovery | Conditional deep specifications retain a short visible menu or an externally observable trigger before their load gate |+| Token delta | Report route/file budget changes separately; a budget pass does not prove semantic equivalence |++**Hard rule**: A shorter prompt that changes decision ownership, constraint strength, preparation timing, or capability discoverability is a semantic regression even when structural and token-budget audits pass.diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 41fd47a1..c263da64 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -446,7 +446,7 @@ The catalog of *how an image is placed on a slide* (full vocabulary in [`referen**Why the layers are physically separated, not just tagged.** Patterns are reorganized so all Primary structures appear first, then all Modifiers — a Strategist or Executor reading the file once internalizes the two-layer mental model from the table of contents alone. Numbers are stable identifiers (`#38` is still image-as-canvas + annotation cards regardless of where it sits in the file), so existing references across `spec_lock.md`, `design_spec.md §VIII`, executor logs, and historical examples all keep resolving.-**Why composition flows through Strategist's resource list, not just Executor's improvisation.** The `Layout pattern` column in `§VIII Image Resource List` accepts a `#<id> + #<id> ...` expression — Primary id plus optional Modifier ids — so Strategist selects the semantic composition before SVG generation and that decision survives session re-entry. Executor owns its realization, not its selection: it may resize, reflow, reposition, and rebalance the chosen pattern for the real asset ratio and content hierarchy while preserving the selected ids, source, asset, role, and crop boundary. Replacing the pattern requires a Design Spec update.+**Why composition flows through Strategist's resource list, not just Executor's improvisation.** The `Layout pattern` column in `§VIII Image Resource List` accepts a `#<id> + #<id> ...` expression — Primary id plus optional Modifier ids — while `Crop Policy` records `adaptive` or `no-crop`. Strategist therefore selects the semantic composition and information-integrity boundary before SVG generation, and both survive session re-entry through the lock projection. Executor owns realization, not selection: it may resize, reflow, reposition, and rebalance the chosen pattern for the real asset ratio and content hierarchy, and an `adaptive` row may use complete display or a focal-safe crop. Replacing the pattern or strengthening the crop boundary requires a Design Spec update.**Why true hard constraints stay upstream.** Cross-cutting SVG authoring and PPTX-compatibility exceptions live in the authority set routed by [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md). The layout patterns file points to that router rather than restating the contract, so each rule still has one owning module and no stale duplicate in the pattern catalog.@@ -568,7 +568,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 the internal application plan retains two fields.** Strategist derives `template_reuse_scope` to record literal mirror reuse, structural layout reuse, or flat style reference. Structured plans then derive `template_adherence: strict|adaptive`: `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. These are exporter values, not user confirmation options. 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 the internal application plan retains two fields.** Strategist derives `template_reuse_scope` to record literal mirror reuse, structural layout reuse, or flat style reference. Structured plans then derive `template_adherence: strict|adaptive`: `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 Strategist may declare a new Layout only when fixed Layout atoms or slot topology/bounds change. If construction reveals that need, execution returns upstream and resumes only after Strategist updates the definition and assignment and regenerates page context; the exporter never infers it later. These are exporter values, not user confirmation options. 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.@@ -580,7 +580,7 @@ These direct routes share some analysis primitives with the main pipeline, espec**Why each template SVG stays complete while still compiling to native structure.** A template SVG repeats the inherited Master/Layout visuals together with sample Slide content so it opens as a complete standalone page. During generation, `page_layouts` selects that prototype and the output SVG remains complete. Export removes repeated inherited atoms, emits real Master/Layout parts, and leaves actual slot carriers and Slide-local content on the Slide.-**Why PowerPoint-native Chart/Table reconstruction uses explicit replacement markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer emits a visible SVG fallback plus `data-pptx-replace-with` and `<metadata type="application/json">` only for validated table/chart subsets. The parent marker determines the payload schema; ordinary shapes and connectors never use this contract. Table import covers exact physical row/grid topology, canonical rectangular merges with empty slaves, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph form. A rich paragraph contains non-empty `runs`; every run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. Unknown source presentation-only run XML without a non-empty `effectLst` / `effectDag` normalizes into that schema; a table-cell run effect instead disables native replacement and adds a blocking effect diagnostic. Relationship-bearing text, extensions, line breaks, fields, tabs, bullets, malformed text topology, noncanonical merges, unsafe borders, and non-solid fills remain fallback-only. The normalized fallback for table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct overrides; this is not a full built-in/custom style registry.+**Why PowerPoint-native Chart/Table reconstruction uses explicit replacement markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer emits a visible SVG fallback plus `data-pptx-replace-with` and `<metadata type="application/json">` only for validated table/chart subsets. Generated decks prepare that pair only when Strategist marks the §VII row `Native-ready: yes`; a catalog marker is a capability example, not an execution decision. The parent marker determines the payload schema; ordinary shapes and connectors never use this contract. Table import covers exact physical row/grid topology, canonical rectangular merges with empty slaves, safe solid/no-fill per-side borders, plain multi-paragraph cells, and a closed run-rich paragraph form. A rich paragraph contains non-empty `runs`; every run requires `text` and may use only `bold`, `italic`, `underline`, `strike`, `color`, `font_size`, one `font_family`, `lang`, and `alt_lang`. Unknown source presentation-only run XML without a non-empty `effectLst` / `effectDag` normalizes into that schema; a table-cell run effect instead disables native replacement and adds a blocking effect diagnostic. Relationship-bearing text, extensions, line breaks, fields, tabs, bullets, malformed text topology, noncanonical merges, unsafe borders, and non-solid fills remain fallback-only. The normalized fallback for table style `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` resolves `wholeTbl`, `firstRow`, horizontal banding, theme colors/fonts, and direct overrides; this is not a full built-in/custom style registry.For supported parsed column/bar/line/area, pie/doughnut, scatter, and bubble charts, a missing baked preview is replaced by a deterministic readable SVG fallback marked `data-pptx-fallback-kind="normalized"`. The importer also covers the verified column/line/area combo subset, canonical four-series OHLC stock, area charts with numeric date axes, verified scatter/bubble charts with the closed `axes.x` / `axes.y` contract, radar, safe `of_pie` `serLines`, axis/title/legend normalization, and bounded bar/column gap/overlap cases. `gapWidth` is accepted only as one integer in `0..500`, and `overlap` only as one integer in `-100..100`; these presentation values intentionally normalize in native output, while malformed, duplicate, or out-of-range input fails closed. Combo plots may retain independent primary/secondary category caches and workbook ranges. XY import derives `scatter_style` from uniform effective series line/marker/smooth state. The closed category/value and XY axis contracts retain kind, position, visibility, label position, number format, min/max/major unit, reversal, and major gridlines for native read-back; the normalized XY fallback consumes only the two `major_gridlines` flags.diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.mdindex 727b5388..cd4c1de9 100644--- a/docs/zh/powerpoint-svg-mapping.md+++ b/docs/zh/powerpoint-svg-mapping.md@@ -59,10 +59,10 @@ PowerPoint 意图| 自由设计演示文稿结构 | `pptx_structure.mode: flat`;页面内容保持 Slide-local | 一个干净的项目 Master 和一个 Blank Layout,已表达对象留在 Slide | flat 路线包拓扑为 `Native-stable` | 禁止编写 Master/Layout/layer/placeholder metadata || 基于模板的演示文稿结构 | `pptx_structure.mode: structured` 加显式 Master/Layout/页面分配 | 声明的 `p:sldMaster`、`p:sldLayout`、注册与 Slide 父子关系 | 在显式结构合同内为 `Native-stable` | 导出器绝不猜测 Master、Layout 或占位符拓扑 || 幻灯片母版 | 根 Master 身份加原子级 `data-pptx-layer="master"` 对象;一个校验通过的 compact authored-preset `<g>` 计为一个 semantic atom | 可复用 Master part 与 picker 身份 | Create Template mirror 可把来源包中已验证的事实保留到新工作区;创作模式使用新身份 | Master atom 必须为直接、稳定对象,并在所属页面间一致;普通组或 expanded authored 组不具备该资格 |-| 幻灯片版式 | 根 Layout 身份加原子级 `data-pptx-layer="layout"` 对象;一个校验通过的 compact authored-preset `<g>` 计为一个 semantic atom | 某个 Master 下的可复用 Layout part | Create Template mirror 可把已验证的源 Layout 保留到新工作区;adaptive 创作可分配新 Layout | 仅当固定 atom 和 slot 合同完全相同时才复用 Layout key;普通组或 expanded authored 组不具备该资格 |+| 幻灯片版式 | 根 Layout 身份加原子级 `data-pptx-layer="layout"` 对象;一个校验通过的 compact authored-preset `<g>` 计为一个 semantic atom | 某个 Master 下的可复用 Layout part | Create Template mirror 可把已验证的源 Layout 保留到新工作区;Strategist 的 adaptive 计划可声明新 Layout | 仅当固定 atom 和 slot 合同完全相同时才复用 Layout key;普通组或 expanded authored 组不具备该资格 || 回导的继承图形可见性 | 分层分析记录规范化源布尔值;物化后的 structured mirror 在根写入精确小写的 `data-pptx-show-inherited-shapes` 与 `data-pptx-show-master-shapes` | 把已声明来源值写入 `p:sld@showMasterSp` 与 `p:sldLayout@showMasterSp` | `Native-stable`:Slide 为 false 时隐藏 Layout 与 Master 图形;Layout 为 false 时只隐藏 Master 图形 | 省略即 true;使用同一 Layout key 的页面必须使用相同 Layout 值。背景、Slide-local 对象、占位符继承、part 与父子关系保持不变 || strict 模板 Layout | 选中的原型合同 | 保留现有已声明 Layout 拓扑 | 页面遵循原型时为 `Native-stable` | 不得改变固定 Layout atom 和 slot 结构 |-| adaptive 模板 Layout | 选定 Master 加显式的当前或新声明 Layout | 可在可复用结构变化时创建新 Layout 身份 | 更新 lock 与页面映射后为 `Native-stable` | 绝不默默改变已复用 Layout key |+| adaptive 模板 Layout | 选定 Master 加 Strategist 显式声明的当前或新 Layout | 可复用结构变化时创建已声明的新 Layout 身份 | Strategist 更新计划与 lock 映射、执行恢复后为 `Native-stable` | 制作中发现变化须退回上游;绝不在下游改变已复用 Layout key || structured 模式以外的 Slide 背景填充 | 第一个合格的全幅 `<rect>`,可直接位于根下或位于简单单子组中,使用已登记纯色、线性/径向渐变或预设图案填充 | Slide 的原生 `p:bg` | 保真度遵循下文对应 paint 行 | transform、filter、clip、圆角、可见 stroke 或未映射 fill 会阻止提升 || structured 模式的 Master/Layout/Slide 背景填充 | 声明结构层中一个直接铺满画布的纯色 `<rect>` | Master、Layout 或 Slide 层级的原生 `p:bg` | `Native-stable` | 显式 scoped background 所有权有意只支持纯色 || structured 模式的渐变或图案背景形状 | 声明在 Master/Layout 层的普通渐变/图案 `<rect>`,或 Slide-local 内容 | 所属 part 上的可编辑 shape | 保真度遵循下文对应 paint 行 | structured 导出关闭通用背景提升;不得使用 `data-pptx-layer="slide"` |diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex 2eb27828..8f492477 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -70,7 +70,7 @@ Generate PPTX 路线围绕完全可控的新形状、文字与版式创作。结跨四渲染器(PowerPoint / Keynote / LibreOffice / WPS)的位置保真是项目主轴。把默认路线改成 PowerPoint 原生图表会让「像素级一致性」破功——同一个 PPTX 在不同渲染器里图表会显示不同布局。图表默认用 SVG 是 **by design**,不是能力缺失。-窄例外是 `data-pptx-replace-with` marker:受支持的数据图表与纯文本网格表格在生成时携带 PowerPoint 原生 Chart/Table 替换 payload,导出加 `--native-charts-and-tables` 才激活——供主动用跨渲染器保真换取带数据源对象及图表/表格专属编辑模型的用户使用;激活后的对象会保留 deck 的 chart-area / plot / 轴线 / 网格线 / 标签颜色与原生表格格式,不再塌回 PowerPoint 默认主题(见 [v4.0.0 发布说明](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0))。默认导出路径与可编辑的 SVG 派生形状系统不变。+窄例外是 `data-pptx-replace-with` marker:Design Spec §VII 中独立规划、且写明 `Native-ready: yes` 的受支持数据图表与纯文本网格表格可以携带 PowerPoint 原生 Chart/Table 替换 payload;`no` / `n/a` 与零星微型图形保持普通 shape。导出加 `--native-charts-and-tables` 才激活已准备的 marker——供主动用跨渲染器保真换取带数据源对象及图表/表格专属编辑模型的用户使用;激活后的对象会保留 deck 的 chart-area / plot / 轴线 / 网格线 / 标签颜色与原生表格格式,不再塌回 PowerPoint 默认主题(见 [v4.0.0 发布说明](https://github.com/hugohe3/ppt-master/releases/tag/v4.0.0))。默认导出路径与可编辑的 SVG 派生形状系统不变。### uv 作为默认 / 必需依赖diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex ef39088a..a201a893 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -442,7 +442,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:**为什么物理拆分两层,而不是只打标签。** 词表被重排成「Primary 全部在前,Modifier 全部在后」——Strategist 或 Executor 读一次目录,就能从结构上内化「两层」心智模型。编号是稳定 id(`#38` 永远是「图作画布 + 注解卡」,不论它在文件里的物理位置),所以 `spec_lock.md`、`design_spec.md §VIII`、历史 executor 输出、过往示例里所有 `#<id>` 引用照样解析。-**为什么组合走 Strategist 资源列表,不只交给 Executor 临场发挥。** `§VIII 图片资源列表` 的 `Layout pattern` 列接受 `#<id> + #<id> ...` 表达式——Primary id 加可选 Modifier id——所以 Strategist 会在 SVG 生成前选定语义构图,并让这项决策在 session 重入后继续存在。Executor 负责实现方式,而不是重新选型:它可以根据真实图片比例和内容层级调整所选 pattern 的尺寸、位置、流向与权重,但必须保留选定 id、来源、素材、页面角色和裁剪边界。若要更换 pattern,必须先更新 Design Spec。+**为什么组合走 Strategist 资源列表,不只交给 Executor 临场发挥。** `§VIII 图片资源列表` 的 `Layout pattern` 列接受 `#<id> + #<id> ...` 表达式——Primary id 加可选 Modifier id;`Crop Policy` 则记录 `adaptive` 或 `no-crop`。Strategist 会在 SVG 生成前同时选定语义构图和信息完整性边界,并通过 lock 投影让两者在 session 重入后继续存在。Executor 负责实现方式,而不是重新选型:它可以根据真实图片比例和内容层级调整所选 pattern 的尺寸、位置、流向与权重;`adaptive` 行既可完整显示,也可安全裁剪。若要更换 pattern 或收紧裁剪边界,必须先更新 Design Spec。**为什么真正的硬约束留在上游。** 跨切的 SVG 创作与 PPTX 兼容性例外属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由的权威集。版式词表只指向该路由,不再复述合同;每条规则仍只有一个所属模块,词表里也不会留下过期副本。@@ -564,7 +564,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路**为什么可复用 bounds 是设计区域,不是量出来的文本框。** bounds 来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容紧包围盒。当前 Slide 保留自己的 carrier 几何,因此只要语义构图相同,4:6、3:7、5:5 的实例都可复用同一 Layout。文本长度不会意外拆分或改变可复用合同。-**为什么内部应用计划保留两个字段。** Strategist 推导 `template_reuse_scope`,记录字面镜像复用、结构化版式复用或 flat 风格参考;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。+**为什么内部应用计划保留两个字段。** Strategist 推导 `template_reuse_scope`,记录字面镜像复用、结构化版式复用或 flat 风格参考;structured 计划再推导 `template_adherence: strict|adaptive`。`page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时,Strategist 才可声明新 Layout。若制作过程暴露出这一需求,执行必须退回上游,待 Strategist 更新定义与分配并重新生成页面上下文后才能继续;导出器不会事后推断。这些是导出器内部值,不是用户确认选项。模板定义即使暂时没有页面使用,也能注册进最终文件。layout 的皮肤由项目控制;mirror 还要保持字面视觉与文字节点拓扑。`style` 不带 adherence 或结构 mapping。**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把锁定的 title 字号和确定性的九级 body 层级写入 Master 文本默认值,同时保留原有缩进与项目符号设置;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。@@ -576,7 +576,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路**为什么模板 SVG 保持完整却仍能编译成原生结构。** 模板 SVG 会重复携带继承的 Master/Layout 视觉和示例 Slide 内容,因此可独立打开。生成时由 `page_layouts` 选择该原型,输出 SVG 仍保持视觉闭包。导出器移除重复继承原子、生成真实 Master/Layout part,并把槽位 carrier 与 Slide-local 内容留在 Slide。-**为什么 PowerPoint 原生 Chart/Table 重建使用显式替换 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器只为已验证的表格 / 图表子集输出可见 SVG fallback、`data-pptx-replace-with` 与 `<metadata type="application/json">`。父组 marker 决定 payload schema;普通 shape 与 connector 不使用该合同。表格导入覆盖精确的物理行列 topology、slave 为空的规范矩形 merge、安全的 solid/no-fill 逐边 border、纯文本多段落,以及封闭的 run 级富文本段落。富文本段落包含非空 `runs`;每个 run 必须有 `text`,并且只能使用 `bold`、`italic`、`underline`、`strike`、`color`、`font_size`、单一 `font_family`、`lang` 和 `alt_lang`。不含非空 `effectLst` / `effectDag` 的来源展示型 run XML 会归一化到该 schema;表格单元格 run 效果则会禁用原生替换,并添加阻塞效果诊断。带 relationship 的文本、扩展节点、换行、字段、tab、项目符号、破损文本 topology、非规范 merge、不安全 border 与非纯色填充仍保持 fallback-only。表格样式 `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` 的规范化 fallback 会解析 `wholeTbl`、`firstRow`、横向带状行、主题颜色 / 字体和直接格式覆盖;这不代表完整 built-in/custom style registry。+**为什么 PowerPoint 原生 Chart/Table 重建使用显式替换 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器只为已验证的表格 / 图表子集输出可见 SVG fallback、`data-pptx-replace-with` 与 `<metadata type="application/json">`。生成型 deck 只在 Strategist 将 §VII 行标为 `Native-ready: yes` 时准备这组内容;catalog marker 只是能力示例,不替项目做决策。父组 marker 决定 payload schema;普通 shape 与 connector 不使用该合同。表格导入覆盖精确的物理行列 topology、slave 为空的规范矩形 merge、安全的 solid/no-fill 逐边 border、纯文本多段落,以及封闭的 run 级富文本段落。富文本段落包含非空 `runs`;每个 run 必须有 `text`,并且只能使用 `bold`、`italic`、`underline`、`strike`、`color`、`font_size`、单一 `font_family`、`lang` 和 `alt_lang`。不含非空 `effectLst` / `effectDag` 的来源展示型 run XML 会归一化到该 schema;表格单元格 run 效果则会禁用原生替换,并添加阻塞效果诊断。带 relationship 的文本、扩展节点、换行、字段、tab、项目符号、破损文本 topology、非规范 merge、不安全 border 与非纯色填充仍保持 fallback-only。表格样式 `{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}` 的规范化 fallback 会解析 `wholeTbl`、`firstRow`、横向带状行、主题颜色 / 字体和直接格式覆盖;这不代表完整 built-in/custom style registry。受支持的柱 / 条 / 折线 / 面积、饼 / 圆环、散点 / 气泡图在没有 baked preview 时会生成确定性、可读的 SVG fallback,并标记 `data-pptx-fallback-kind="normalized"`。导入器还覆盖已验证的柱 / 折线 / 面积组合图、规范四系列 OHLC stock、数值日期轴面积图、采用封闭 `axes.x` / `axes.y` 合同的散点 / 气泡图、radar、安全的 `of_pie` `serLines`、坐标轴 / 标题 / 图例归一化,以及有界的柱 / 条图 gap/overlap 场景。`gapWidth` 只接受 `0..500` 内的单个整数,`overlap` 只接受 `-100..100` 内的单个整数;这两个表现字段在 native 输出中有意归一化,非法、重复或越界输入 fail closed。组合图可保留主 / 次 plot 各自的 category cache 与 workbook range。XY 导入根据各系列一致的有效 line/marker/smooth 状态推导 `scatter_style`。封闭的 category/value 与 XY 轴合同为 native read-back 保留 kind、position、visibility、label position、number format、min/max/major unit、reverse 和 major gridlines;规范化 XY fallback 只消费两个 `major_gridlines` 开关。diff --git a/skills/ppt-master/references/ai-image-comparison/README.md b/skills/ppt-master/references/ai-image-comparison/README.mdindex 0acb32f2..67eb4d00 100644--- a/skills/ppt-master/references/ai-image-comparison/README.md+++ b/skills/ppt-master/references/ai-image-comparison/README.md@@ -26,7 +26,7 @@ Each subdirectory contains:| Choice | Reason ||---|---|| rendering=`vector-illustration` | Most versatile in the catalog; ✓✓ compatible with all 14 palettes; minimal interference when used as the "origin" for palette / type comparisons |-| palette=`cool-corporate` | Most neutral and most common; simple color behavior (HEX 60-30-10 applied directly) so it doesn't overpower the dimension under comparison |+| palette=`cool-corporate` | Most neutral and common; clear dominant/support/accent roles keep the compared dimension visible || composition=single-subject hero (§4.1 Primitive A) | One dominant subject (60-70% of canvas) — the most visually representative shape, so rendering / palette differences show up most clearly |## How the images were generateddiff --git a/skills/ppt-master/references/ai-image-comparison/palette/_subject.md b/skills/ppt-master/references/ai-image-comparison/palette/_subject.mdindex a763f571..c39639dc 100644--- a/skills/ppt-master/references/ai-image-comparison/palette/_subject.md+++ b/skills/ppt-master/references/ai-image-comparison/palette/_subject.md@@ -47,5 +47,5 @@ Scan all 14 images side by side. Focus on:- **Color temperature** — cool-professional vs warm-human vs neutral-editorial- **Saturation** — restrained vs vivid vs monochrome-- **The 60-30-10 proportional feel** — how dominant the secondary really is+- **Dominant/support/accent balance** — how strongly each semantic role appears- **Accent weight** — how much visual presence the small accent commandsdiff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex 854205df..026017ce 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -158,7 +158,7 @@ Flags:Per-element animations are anchored on **top-level `<g id="...">` content groups** in the SVG (e.g. `<g id="cover-title">`, `<g id="card-1">`). IDs must be unique within the page. One group produces one animation-pane entrance row; whether that row needs a click depends on the selected Start mode. Nested implementation groups may remain anonymous because the sidecar does not target them.-Aim for **3–8 content groups per slide**. This is also the granularity PowerPoint uses for group-select / group-move, so it improves editing ergonomics regardless of animation.+Use one content group per logical page unit. This is also the granularity PowerPoint uses for group-select / group-move, so semantic grouping improves editing ergonomics regardless of animation; do not split or merge units to hit a target count.**Chrome groups skip the cascade automatically.** Explicit SVG role and placeholder semantics are authoritative. A group with `data-pptx-layer` or an explicit static role/placeholder marker can never animate. For marker-free legacy SVGs only, top-level groups whose id tokens look like page chrome (background, header/footer, decorations, watermark, page number, nav, logo, dividing rule) are excluded and appear with the slide. An explicit `animations.json` group entry may override this id-name heuristic, but never an explicit structural marker. Examples that auto-skip by legacy id: `<g id="background">`, `<g id="bg-texture">`, `<g id="cover-footer">`, `<g id="p03-header">`, `<g id="bottom-decor">`, `<g id="watermark">`, `<g id="nav">`, `<g id="logo-area">`, `<g id="column-rule">`. Examples that still animate: `<g id="card-1">`, `<g id="cover-title">`, `<g id="step-discover">`, `<g id="timeline-track">`. Do not strip the `<g>` wrapper to avoid animation — keep it for PowerPoint group selection and use `effect: none` when the content should remain static.diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex 51404c75..2990a7a2 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -19,7 +19,7 @@ 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` | Strategist design authority | Human-readable design intent, outline, rationale, resource plan, and confirmed production mechanics authored from the final confirmation plus source analysis | Strategist consumes the final confirmation once, writes and audits every confirmed field here, then later roles read this artifact instead of reopening `result.json` |-| `spec_lock.md` | Execution anchor and routing contract | Machine-readable stable color/type roles, 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 authors the route-specific anchors from the audited Design Spec plus current project/page/template context. `page-context` repeats that compact anchor set per page and adds current-page routing values. Page-local color/font choices need no lock row; Executor may promote a recurring semantic color/type role or add a new adaptive Layout identity while authoring the first page that establishes the reuse. |+| `spec_lock.md` | Execution anchor and routing contract | Machine-readable stable color/type roles, 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 authors the route-specific anchors from the audited Design Spec plus current project/page/template context. `page-context` repeats that compact anchor set per page and adds current-page routing values. Sparse page-local color/font garnish needs no lock row; a recurring semantic role or new adaptive Layout identity requires Strategist repair before reuse. || `project_manager.py page-context` stdout | Derived per-page context | Read-only model-facing anchor set + current-page delta + fingerprints for large references | Generate immediately before each page without `--bundle`; never edit or persist it as a replacement source of truth. `global` is the bounded repeated anchor set, not a whitelist of every valid page-local value. `reference_set` carries path/SHA/load policy for project/template Design Specs and selected prototype/chart SVGs, but never appends their payloads. || `analysis/page-context/P<NN>.usage.json` | Derived context telemetry | Actual compact page-context size plus hashes of owning inputs/references | `page-context --record-usage` deterministically replaces that page's snapshot; `page-context-report` summarizes current snapshots and unique references. Use token data to evaluate context cost, never as content or an execution contract. || `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 |@@ -56,7 +56,7 @@ Global artifact ownership rules for PPT Master projects.| PPTX structure | `slide_library.json` owns native geometry, slot facts, and SmartArt layout/relationships for direct PPTX workflows. || Design contract | Final confirmation is read once → complete audited `design_spec.md` → context-authored `spec_lock.md` anchors/routing. Executor may apply projected `Template Application` prose to visible template content, but never replace confirmed identity with an independent direction. On divergence, repair the lock from the Design Spec/current context unless the Design Spec itself fails confirmation fidelity. || 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. |+| 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 use a current or new Layout already declared by Strategist. A construction-discovered structural change returns upstream for definition and assignment repair before authoring resumes. 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. |diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex e99ac536..0af413c2 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -25,6 +25,22 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared---+## 1. Effect Capability Discovery++**Reference — not a constraint**: Scan this menu for treatments that support the locked style and hierarchy. After selecting one, load [`svg-effects.md`](./svg-effects.md) before authoring it.++| Visual need | Available construction |+|---|---|+| Color / material | alpha paint, gradients, translucent overlays |+| Elevation | shadow, glow, explicit highlights |+| Image integration | scrim, vignette, brand wash, clipping, faux glass |+| Line / type | dash/cap/join, markers, gradient stroke; tracking, outline, alpha/gradient text |+| Space / constructed style | transform/reuse, curves/arcs, hand-drawn, ink/Riso, halftone, isometric, paper cut |++**Hard rule — discovery does not expand compatibility**: Follow `svg-effects.md` syntax and fallbacks; unsupported blur, blend, mask, dense texture, or skew remains baked/alternative-only.++---+## 2. Design Parameter Confirmation (Mandatory Step)Before the first SVG page, output a confirmation listing: the compact communication objective, canvas dimensions, body font size, color scheme (primary/secondary/accent HEX), font plan, and the live-preview URL reported by the launcher. If the preview launch failed, state that failure before generating SVGs instead of silently proceeding. Prevents purpose/spec/execution drift.@@ -63,7 +79,7 @@ The §IX wording and sourced facts remain authoritative. Do not rewrite, drop, o**Per-block expression**: render each `design_spec.md §IX Content` block in its written texture — a full-sentence block as wrapped prose, a fragment/label block as bullets/keywords. **Never split a full-sentence block into a bullet list** — splitting loses the information that the block was continuous reasoning, not a set of parallel points; not because a bullet lays out easier, and not because an inherited template slot is shaped as a list. If a block carries no clear texture, infer the mode from its wording and the page layout.-- **Hard rule — one paragraph, one text frame**: use one `<text>` per prose paragraph, never one sibling `<text>` per visual line. Keep the first line as direct text; each later wrap is a direct `<tspan>` that repeats the parent `x`, keeps its effective font size, and uses one positive relative `dy`. An all-`<tspan>` form may start with `dy="0"`. Line height: 1.4–1.5× for dense/small body, 1.6–2.0× for large/breathing text.+- **Hard rule — one paragraph, one text frame**: use one `<text>` per prose paragraph, never one sibling `<text>` per visual line. Keep the first line as direct text; each later wrap is a direct `<tspan>` that repeats the parent `x`, keeps its effective font size, and uses one positive relative `dy`. An all-`<tspan>` form may start with `dy="0"`. Choose consistent positive line spacing from the typeface, size, density, and reading distance; no fixed ratio overrides legibility or the selected style.- **Template precedence**: when an inherited template slot is a bullet list but the §IX block is prose, the prose wins — widen or reflow the container to hold the paragraph, or drop that card; do not pour the sentence back into the list slot.- **Mode precedence**: the locked mode shapes voice / register, not §IX's authored titles or page order. When a `§IX` title is a user-authored topic label, keep it — do not upgrade it to an assertion just because the mode (e.g. `pyramid`) favors them; mode title-tendencies apply only to AI-drafted titles.@@ -120,7 +136,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`- **Reference — prefer semantic geometry over preset stacks**: for relationships such as ascending, converging, breaking through, or stacking, consider one page-specific polygon/path that expresses the relationship before stacking generic arrows. This does not override §3.0 when one literal stock shape is the semantic object.- **Reference — create depth with restraint**: use rhythm, spacing, typography, accent bars, and subtle tints before shadows. Reserve lift for a few genuinely floating elements; keep peer grids, dividers, and body containers flat.- **Phased 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 [`executor-chart.md`](./executor-chart.md) §2.1 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 [`executor-chart.md`](./executor-chart.md) §2.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 --json` without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls.+ 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every §VII data-chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every planned native-ready object. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path> --stage first-page --json` without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls.2. **Quality Check Gate**: only after every planned SVG exists, run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.3. **Logic Construction Phase**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity.diff --git a/skills/ppt-master/references/executor-chart.md b/skills/ppt-master/references/executor-chart.mdindex 2b162591..9b990f58 100644--- a/skills/ppt-master/references/executor-chart.md+++ b/skills/ppt-master/references/executor-chart.md@@ -22,11 +22,11 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha## 2. Chart and Native-data Authoring-### 2.1 Chart Plot-Area Marker (MANDATORY on every chart page)+### 2.1 Chart Plot-Area Marker (MANDATORY on planned data-chart pages)> The [`verify-charts`](../workflows/stages/verify-charts.md) stage enumerates chart pages from `design_spec.md §VII`, then reads each page's plot-area marker to feed `svg_position_calculator.py`. A missing marker invokes that stage's declared fallback and adds avoidable derivation work.-**Hard rule**: every SVG page that contains a data visualization chart includes a plot-area marker inside `<g id="chartArea">`, placed **after axis lines** and **before the first data element** (bar, line, area, point).+**Hard rule**: every data-driven chart page enumerated in `design_spec.md §VII` includes a plot-area marker inside `<g id="chartArea">`, placed **after axis lines** and **before the first data element** (bar, line, area, point). An incidental microvisual outside §VII needs no marker; if its geometry must enter `verify-charts`, return upstream and record it in §VII first.**Rectangular plot area** (bar / horizontal_bar / grouped_bar / stacked_bar / line / area / stacked_area / scatter / waterfall / pareto / butterfly):@@ -53,7 +53,7 @@ Before drawing each page, look up its entry in `page_charts` to decide which cha| `cx, cy` | Center point of pie/donut/radar (accounting for `transform="translate()"`) || `r` | Outer radius of the chart |-**Per-page verification** — after writing each chart SVG, confirm the marker exists:+**Per-page verification** — after writing each §VII data-chart SVG, confirm the marker exists:```bashrg -n "chart-plot-area" <project_path>/svg_output/<current_page>.svg@@ -65,15 +65,15 @@ rg -n "chart-plot-area" <project_path>/svg_output/<current_page>.svg> the same library do not use a plot-area marker.Technical SVG/PPT constraints remain in [`shared-standards-core.md`](./shared-standards-core.md).-### 2.2 PowerPoint-Native Chart/Table Replacement Marker (MANDATORY on eligible data-chart and text-grid table pages)+### 2.2 PowerPoint-Native Chart/Table Replacement Marker (MANDATORY on planned native-ready objects)-> `svg_to_pptx.py --native-charts-and-tables` replaces marked groups with PowerPoint-native Chart/Table objects (charts get an embedded Excel workbook). Markers stay dormant in the default export, whose SVG children become independently editable DrawingML shapes, but a deck without markers can never form data-backed native Chart/Table objects. Write the marker at draw time: the data is already in hand, and recovering it later costs a full re-read pass.+> `svg_to_pptx.py --native-charts-and-tables` replaces marked groups with PowerPoint-native Chart/Table objects (charts get an embedded Excel workbook). Markers stay dormant in the default export, whose SVG children become independently editable DrawingML shapes. Prepare this optional capability for planned independent data objects, not every numeric embellishment.-**Hard rule**: before deciding whether a chart or table is eligible for native replacement, load [`native-data-interface.md`](./native-data-interface.md). Every data chart whose type appears in that authority's **Supported chart types** list gets `data-pptx-replace-with="chart"` plus one `<metadata type="application/json">` JSON child on its top-level `<g>`, transcribing the same data just plotted. Every pure text-grid data table gets `data-pptx-replace-with="table"` the same way, transcribing all visible cell text into `columns` / `rows`. The parent marker determines the JSON schema; do not duplicate a chart/table kind on the metadata child.+**Hard rule**: load [`native-data-interface.md`](./native-data-interface.md) for each §VII row whose `Native-ready` value is `yes`. A supported data chart then gets `data-pptx-replace-with="chart"` plus one JSON `<metadata>` child; a pure text-grid table gets the table form, transcribing all plotted data or visible cells. `no` / `n/a` stays ordinary SVG even when the catalog reference contains a marker. Missing or invalid values return upstream; Executor never infers eligibility. The parent marker selects the schema.-**MUST — atomic authoring**: Treat the visible SVG fallback, the parent `data-pptx-replace-with` marker, and its JSON `<metadata>` child as one object. Write all three in the same SVG edit while the plotted data is in context. A supported chart or eligible table is unfinished if either the marker or metadata is missing; do not defer either one to `verify-charts`, the final quality gate, or export.+**MUST — atomic authoring**: For each native-ready object, treat the visible SVG fallback, the parent `data-pptx-replace-with` marker, and its JSON `<metadata>` child as one object. Write all three in the same SVG edit while the data is in context. Do not defer the marker or metadata to `verify-charts`, the final quality gate, or export.-**Hard rule — eligibility follows data semantics**: Size, point count, visual prominence, page role, catalog match, and the current export mode do not change eligibility. A two-point mini line chart, sparkline, chart inset, KPI-card trend, or small multiple that encodes recoverable categories/values still gets its own marked top-level `<g>` and metadata payload when its chart type is supported. Decorative strokes and arrows without recoverable chart data remain ordinary SVG geometry.+**Hard rule — eligibility follows the plan**: A two-point line or small multiple gets metadata only when its §VII row says `yes`. A sparkline, inset, KPI-card trend, or other microvisual outside §VII stays ordinary SVG even when values are recoverable. Changing eligibility requires upstream repair.Generated authoring MUST omit `data-pptx-import-source` and`data-pptx-fallback-sha256`: those attributes record imported-PPTX provenance@@ -82,7 +82,7 @@ catalog or reusable template; normal content edits would make it stale.`data-pptx-replace-with` is a **data-backed replacement claim**, not a generic label for a group that contains numbers and not a marker for ordinary PowerPoint shapes or connectors. Add it only when the matching JSON payload can be written in the same edit; if the object is meant to remain SVG geometry, do not add the marker.-- Chart types absent from that list and conceptual/diagrammatic graphics (process flows, cycles, quadrant cards, timelines, or a KPI card container) get **no marker** — `svg_quality_checker.py` rejects unsupported marker types. A supported data chart nested visually inside one of those compositions still gets its own marker.+- Chart types absent from that list and conceptual/diagrammatic graphics (process flows, cycles, quadrant cards, timelines, or a KPI card container) get **no marker** — `svg_quality_checker.py` rejects unsupported marker types. A supported data chart nested inside one of those compositions gets its own marker only when its §VII row says `Native-ready: yes`.- Canonical rectangular merged text cells may carry a table marker by putting anchor-only `row_span` / `col_span` in metadata and leaving covered cells blank. Nonrectangular/overlapping merges, nonblank covered cells, and graphical cells (icons, harvey balls, rating dots) get **no table marker** and stay on the SVG fallback route.- Transcribe, don't restyle: `categories` / `series[].values` are the numbers just plotted; `style.colors` copies the series HEX values already rendered on the page, whether they use a recurring `spec_lock.colors` anchor or a contextual page-local color.- Data-point color: when a single column/bar series uses data-point colors in the fallback, copy those fills into `series[].point_colors` in category order.@@ -97,7 +97,7 @@ catalog or reusable template; normal content edits would make it stale.- The marker group's transform stays translate/scale only (no rotate / matrix / skew).- Visual parity is not a goal: the SVG drawing remains the designed visual and exports as editable DrawingML shapes; the native object is the data-backed counterpart with PowerPoint's chart/table-specific model. Never simplify the SVG design to match what a native object could show.-**Per-page verification** — after writing each eligible data-chart or text-grid table page, enumerate the eligible objects and confirm a one-to-one match: every object has one parent marker and exactly one JSON metadata child. Finding one marker somewhere on a page is insufficient when the page contains multiple eligible objects.+**Per-page verification** — after writing a page with planned native-ready objects, enumerate those objects and confirm a one-to-one match: every object has one parent marker and exactly one JSON metadata child. Finding one marker somewhere on a page is insufficient when the page contains multiple planned objects.```bashrg -n 'data-pptx-replace-with="(chart|table)"|<metadata type="application/json">' <project_path>/svg_output/<current_page>.svg@@ -128,6 +128,6 @@ Chart SVGs referenced in **VII. Visualization Reference List** are loaded once tCoordinate calibration runs as a **conditional post-generation stage**, not inside the Executor authoring loop. After SVG generation completes, if the deck contains data charts, run [`verify-charts`](../workflows/stages/verify-charts.md) before post-processing.-The executor's only obligation here is upstream: embed the `<!-- chart-plot-area ... -->` marker on every chart page during initial draft (§2.1). Verify-charts enumerates chart pages from `design_spec.md §VII` (authoritative deck plan) and uses the marker to feed `svg_position_calculator.py`.+The executor's only obligation here is upstream: embed the `<!-- chart-plot-area ... -->` marker on each §VII data-chart page during initial draft (§2.1). Verify-charts enumerates those pages from the authoritative deck plan and uses the marker to feed `svg_position_calculator.py`.> Do NOT run `svg_position_calculator.py` during the initial draft. The calculator calibrates already-generated SVGs against their declared plot areas; running it before the SVG exists has nothing to compare against.diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.mdindex 4427c0fb..15cb15e8 100644--- a/skills/ppt-master/references/executor-image.md+++ b/skills/ppt-master/references/executor-image.md@@ -27,6 +27,6 @@ Handle images by their status in the Design Spec's Image Resource List. Status e**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text-**`no-crop` images**: when a `spec_lock.md images` entry ends with ` | no-crop`, size the container to the image's native ratio (from `analyze_images.py` or file dims) and use `preserveAspectRatio="xMidYMid meet"`. Untagged permits, but does not require, cropping; choose `meet` or `slice` from purpose, focal safety, ratio, and container.+**Crop policy**: read the §VIII row and matching lock projection. `crop=no-crop` (or a legacy trailing `| no-crop`) requires a native-ratio container and `preserveAspectRatio="xMidYMid meet"`. `crop=adaptive` permits but never requires cropping; choose `meet` or focal-safe `slice` from purpose, ratio, focus, and container. A missing or conflicting projection returns upstream instead of being inferred during execution.**Formula images — declared-inference fallback for a missing `no-crop` flag**: rows with `Acquire Via: formula` or `Type: Latex Formula` MUST be treated as no-crop. For a rendered file, use dimensions in this order: current `analysis/image_analysis.csv`, `design_spec.md §VIII`, then `images/formula_manifest.json`. For a `Needs-Manual` row, size the dashed placeholder from the planned dimensions in §VIII, then the manifest; the Step 7 readiness gate re-analyzes the supplied file and reconciles the container before export. Do not normalize all formulas to one height unless the spec explicitly states that layout choice.diff --git a/skills/ppt-master/references/executor-structured.md b/skills/ppt-master/references/executor-structured.mdindex 2b94c8ef..5289e52e 100644--- a/skills/ppt-master/references/executor-structured.md+++ b/skills/ppt-master/references/executor-structured.md@@ -20,7 +20,7 @@ Conditional Executor authority for `template_reuse_scope: mirror|layout` with `pManifest/text-slot files are derived tool metadata, not model inputs. Missing metadata neither invalidates a legacy workspace nor permits text-topology changes.-**Mapping change**: update the owning plan and regenerate that page's delta; load only a new/changed prototype fingerprint.+**Mapping change**: stop and return to Strategist to update the owning plan; regenerate that page's delta before resuming, then load only a new/changed prototype fingerprint.Resolve the per-page template SVG from `page_context.template.prototype`; the owning `spec_lock.md page_layouts` row remains authoritative. There is no filename/page-type fallback.@@ -54,7 +54,7 @@ When `spec_lock.md` records the AI-derived `template_reuse_scope: mirror`, Execu2. **Copy, don't fill** — use the retained full mirror SVG as the starting point, then edit slide-specific text in place. Preserve every non-text element and every `data-pptx-*` structure attribute verbatim. Do not reopen the same path + SHA merely because another page selects it.3. **What you may edit** — decide the semantic slot mapping and replacement text only. Change only 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. `svg_quality_checker.py` and export validate attributes, topology, and prototype hashes against the complete prototype internally.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** — 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`.+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. Report `warning: P<NN> content does not fit mirror reference <basename>; choose another prototype or change template_reuse_scope to layout/style`, then return to Strategist to select the prototype or scope and update the planning mappings.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*.@@ -142,7 +142,7 @@ Do **not** invent a prototype entry, and do **not** assume a structured template- Read the current page assignment as `P<NN>: <layout_key>`. Resolve the assigned Layout key in `pptx_layouts`, then resolve its 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.-- On adaptive template use, retain the prototype Master. If the final composition changes fixed Layout atoms or slot topology/bounds, allocate a new key/name and update this row before completing the page.+- On adaptive template use, retain the prototype Master and realize the Layout key/name already declared for this page. If construction proves that fixed Layout atoms or slot topology/bounds must change, stop before completing the page and return to Strategist to declare the revised definition and assignment; regenerate the current page context before resuming.- A Layout key may repeat across non-adjacent pages only when its fixed atoms and slot contracts are identical.**Structured template-page scaffold**:@@ -168,7 +168,7 @@ Do **not** invent a prototype entry, and do **not** assume a structured templatedata-pptx-bounds="570 120 650 500"><image id="picture-carrier" data-pptx-carrier="true" …/></g>- <g id="content-block-1" data-pptx-bounds="60 120 470 500">…</g> <!-- 3–8 content groups -->+ <g id="content-block-1" data-pptx-bounds="60 120 470 500">…</g> <!-- one group per logical content unit --><g id="content-block-2" data-pptx-bounds="570 120 650 500">…</g></svg>```diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.mdindex 24f355cd..03a501ce 100644--- a/skills/ppt-master/references/image-base.md+++ b/skills/ppt-master/references/image-base.md@@ -21,12 +21,9 @@ Active when at least one resource list row has `Acquire Via: ai` / `web` / `slicDefined in `design_spec.md §VIII`. Status enum: see [`svg-image-embedding.md`](svg-image-embedding.md).-| Filename | Dimensions | Purpose | Type | Acquire Via | Status | Reference |-|---|---|---|---|---|---|---|-| cover.png | 1280x720 | Cover background | Background | `ai` | Pending | Modern tech abstract, deep blue gradient #0A2540 |-| team.jpg | 800x600 | Team photo | Photography | `web` | Pending | Diverse engineering team in modern office |-| formula_001.png | 736x168 | Block equation on P03 | Latex Formula | `formula` | Rendered | `E = mc^2` |-| spot_team.png | TBD after slicing | Team spot illustration | Illustration | `slice` | Pending | From `spot_sheet.png` cell 1,1 |+| Filename | Dimensions | Purpose / Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference |+|---|---|---|---|---|---|---|---|+| `<planned file>` | `<planned size>` | `<planned role>` | `<Strategist selection>` | `adaptive` / `no-crop` | `ai` / `web` / `slice` | Pending | `<acquisition brief>` |**Required per non-skipped row**: `Acquire Via` and `Status`. `Reference` is required for every `web` / `slice` row and every newly authored `ai` row. An existing `ai` row whose `Reference` is omitted or blank may continue only through the declared inference in [`image-generator.md`](./image-generator.md) §8; no other path may infer it.diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.mdindex 6dfb23da..dceaddac 100644--- a/skills/ppt-master/references/image-generator.md+++ b/skills/ppt-master/references/image-generator.md@@ -279,7 +279,7 @@ If one deck needs mixed shapes, create separate sheets per shape family unless o**Resource contract — the sheet and its elements are different row kinds.** A sliced element can only be placed if it exists as a resource the Executor is allowed to reference (`spec_lock.md images`). So §VIII carries two row kinds (planning authority: [`strategist-image.md`](./strategist-image.md)):- **Sheet row** — `Acquire Via: ai`, `Type: Illustration Sheet`, the intent prompt, named as the slice source with its intended cell shape and placement purpose (`Reference: landscape footer-vignette spot set`). It is generated in Step 5 but **never placed on a slide** — keep it **out of** `spec_lock.md images`. Image_Generator resolves the exact `aspect_ratio`, grid, and slice command from this intent.-- **Element rows** — one per used element, `Acquire Via: slice`, filename matching a `--names` output, `Reference` naming the parent sheet + cell/element. These **are** placed — list every one in `spec_lock.md images`, usually with ` | no-crop` (a tight-trimmed transparent spot should be fit, not cover-cropped). Their dimensions are filled in after slicing (Step 5 re-runs `analyze_images.py`). **Set each element row's Layout pattern from the decorative-cutout family, never a boxed container** — see Placement below.+- **Element rows** — one per used element, `Acquire Via: slice`, filename matching a `--names` output, `Reference` naming the parent sheet + cell/element. These **are** placed — list every one in `spec_lock.md images`, normally with `crop=no-crop` (a tight-trimmed transparent spot should be fit, not cover-cropped). Their dimensions are filled in after slicing (Step 5 re-runs `analyze_images.py`). Each row must already carry a Strategist-selected decorative-cutout Layout pattern, never a boxed container — see Placement below.For traceability, add optional `slice_grid` and `slice_names` fields to the sheet item in `image_prompts.json` after choosing the geometry. `image_gen.py` ignores unknown item fields but preserves them in the manifest, so these fields document the exact command that must be used for slicing.@@ -296,7 +296,7 @@ python3 scripts/slice_images.py <project>/images/illus_sheet.png --grid 2x3 \2. **Clean grid, or it cuts ugly.** The model will not place every element perfectly; force a clear grid with gutters, and generate **a few sheets** (re-roll the same prompt) to pick the cleanest-laid-out one before slicing. State the exact row/column structure and cell shape so the model does not invent a square matrix. `--trim` absorbs the rest.3. **Generate only as large as needed.** Each cell is a fraction of the sheet. Pick the smallest sheet size that keeps each sliced cell at least **1.5-2x** the intended display size. `1K` is usually enough for small 80-160px decorative spots; use `2K` for medium 180-320px placements; reserve `4K` for large, cropped, or potentially enlarged elements.-**Placement — these are decorative accessories, not boxed pictures.** A transparent spot wasted in a centered rectangle looks cheaper than no spot at all. Each element row's Layout pattern comes from the decorative-cutout family in [`image-layout-patterns.md`](./image-layout-patterns.md): `#63` sticker/cutout, `#4` bleed off the canvas edge, `#58` corner fragment, `#66` fade into the background, `#69` slight editorial rotation, `#49` asymmetric cluster. Push spots to the margins, let them run off-edge or sit behind/beside text, vary size and angle across pages, and overlap the content rather than reserving a tidy tile for them. Anchor most pages on one primary element and let the rest stay small ([primary-per-page](./strategist-image.md)) — scattered same-weight tiles are exactly the generic look to avoid.+**Placement — these are decorative accessories, not boxed pictures.** Strategist selects each element row's pattern from the decorative-cutout family in [`image-layout-patterns.md`](./image-layout-patterns.md): `#63` sticker/cutout, `#4` bleed off the canvas edge, `#58` corner fragment, `#66` fade into the background, `#69` slight editorial rotation, or `#49` asymmetric cluster. Executor realizes that choice through margin position, off-edge treatment, overlap, scale, and angle rather than reserving a tidy tile. Anchor most pages on one primary element and let the rest stay small ([primary-per-page](./strategist-image.md)).**Through-line — one family, many roles.** A spot sheet pays off more when the same motif family also drives the cover and section dividers. A large cover / divider anchor is not a giant sheet cell—generate it as its own `hero_page` image sharing the sheet's `deck_rendering`, `color_scheme`, and subject world. Plan this only when the deck leans into illustration, never as a quota.diff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.mdindex b17cd218..452313d6 100644--- a/skills/ppt-master/references/image-layout-spec.md+++ b/skills/ppt-master/references/image-layout-spec.md@@ -4,7 +4,7 @@Sizing reference for side-by-side or multi-image pages. Use only after Strategist selects the composition; this file never selects layout or crop policy.-**Selected pattern, flexible geometry**: Let original aspect ratio inform the container. A `no-crop` asset displays completely; an untagged asset may use `meet` or a focal-safe `slice`. Rework geometry within the selected pattern when either mode produces weak hierarchy, unsafe cropping, or excessive dead space; changing the pattern requires an upstream Design Spec update.+**Selected pattern, flexible geometry**: Let original aspect ratio inform the container. A `no-crop` asset displays completely; an `adaptive` asset may use `meet` or a focal-safe `slice`. Rework geometry within the selected pattern when either mode produces weak hierarchy, unsafe cropping, or excessive dead space; changing the pattern requires an upstream Design Spec update.> **Scope**: The ratio tables and formulas are calculation aids for a selected side-by-side or multi-image plan. Hero, background, accent, and other compositions stay outside this file. Layout never overrides the `no-crop` boundary owned by [`strategist-image.md`](./strategist-image.md) and [`executor-image.md`](./executor-image.md).@@ -63,7 +63,8 @@ Image height = W / R = 1160 / R pxText area height = H - image height - gap(20px)Review: if the remaining text area cannot carry the planned copy legibly,-recompose as left-right or choose another layout pattern.+rebalance the rectangles within the selected pattern; otherwise return upstream+for a Design Spec pattern update.```### Left-Right Layout Calculation@@ -82,7 +83,7 @@ Image height = image width / RText area width = W - image width - gap(20px)```-**Review**: if the remaining text area cannot carry the planned copy legibly, reduce the image area or choose another layout pattern.+**Review**: if the remaining text area cannot carry the planned copy legibly, rebalance the image/text rectangles within the selected pattern; otherwise return upstream for a Design Spec pattern update.---@@ -106,8 +107,8 @@ Image: 773x560 (left), Text area: 367x560 (right) → 7:3 left-right```Original: 1820x1040, R=1.75-Try top-bottom: image height=663, text area=-43 ❌-Switch to left-right: image 780x446 (left), text area 360x600 (right) → 7:3 left-right+Strategist compares top-bottom: image height=663, text area=-43 ❌+Strategist selects left-right: image 780x446 (left), text area 360x600 (right) → 7:3 left-right```---@@ -176,7 +177,7 @@ Image positions:| Proportion does not reflect information weight | Rebalance image and text rectangles || Container conflicts with the native ratio | Change the container, choose `meet`, or use a focal-safe crop || Required pixels, labels, identity, or evidence would be cropped | Use `preserveAspectRatio="xMidYMid meet"` and recompose around the complete image |-| Text area cannot carry the planned copy legibly | Increase its area or choose another composition |+| Text area cannot carry the planned copy legibly | Increase its area within the selected pattern; otherwise return upstream |---@@ -188,8 +189,9 @@ This spec only defines layout calculation. Write computed fields into the Image|-------|---------|| `Ratio` | Original image width / height || `Layout pattern` | Strategist-selected catalog pattern; semantic composition fixed, geometry flexible |+| `Crop Policy` | `no-crop` protects complete pixels; `adaptive` lets Executor choose `meet` or focal-safe `slice` || `Reference` | Optional calculated image/text rectangles, focal notes, and composition intent |-| `spec_lock.md images` suffix | Add `no-crop` only when information integrity or explicit user intent requires complete display |+| `spec_lock.md images` value | `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>` |For SVG `<image>` syntax, path rules, `preserveAspectRatio`, external refs, and Base64 embedding: see [`svg-image-embedding.md`](svg-image-embedding.md).@@ -203,7 +205,7 @@ Complete display (`no-crop` assets such as data charts):preserveAspectRatio="xMidYMid meet"/>```-Crop-to-fill (any untagged asset with a verified focal-safe crop):+Crop-to-fill (an `adaptive` asset with a verified focal-safe crop):```xml<image href="../images/bg.png"diff --git a/skills/ppt-master/references/native-data-interface.md b/skills/ppt-master/references/native-data-interface.mdindex b475ac41..189b0266 100644--- a/skills/ppt-master/references/native-data-interface.md+++ b/skills/ppt-master/references/native-data-interface.md@@ -38,11 +38,11 @@ itself is never used as a repeatable tile.it errors when the pattern uses `patternTransform` or names a preset outsidethis enum.-## 2. PowerPoint-Native Chart / Table Replacement Markers (Authoring Mandatory; Export Opt-in)+## 2. PowerPoint-Native Chart / Table Replacement Markers (Opt-in)-Native PowerPoint tables and Excel-backed charts activate at export time only. Metadata authoring is not opt-in: the default chart/table route still writes dormant replacement metadata while keeping hand-authored SVG geometry pixel-stable across PowerPoint / Keynote / LibreOffice / WPS.+Native PowerPoint tables and Excel-backed charts activate at export time only. Generated pages prepare dormant replacement metadata for independently planned native-ready objects while keeping hand-authored SVG geometry pixel-stable across PowerPoint / Keynote / LibreOffice / WPS.-**Hard rule — authoring is mandatory**: Executor writes the marker and JSON metadata in the same edit as every supported data chart and pure text-grid data table ([`executor-chart.md`](./executor-chart.md) §2.2). Mini charts, sparklines, insets, KPI-card trends, and small multiples are included when they encode recoverable data in a supported chart type. Canonical rectangular merged text cells may use the narrow `row_span` / `col_span` contract below; graphical cells stay unmarked on the SVG fallback route. The marker group supplies both visible SVG fallback children for browser/live-preview rendering and JSON metadata for `svg_to_pptx` native export.+**Hard rule — planned-object authoring**: Executor writes the marker and JSON metadata in the same edit only for a supported chart or pure text-grid table whose `design_spec.md §VII` row says `Native-ready: yes` ([`executor-chart.md`](./executor-chart.md) §2.2). `no`, `n/a`, and microvisuals outside §VII stay on the SVG fallback route. Canonical rectangular merged text cells may use the narrow `row_span` / `col_span` contract below; graphical cells stay unmarked. The marker group supplies visible SVG fallback children for browser/live-preview rendering and JSON metadata for `svg_to_pptx` native export.**Hard rule — activation is the opt-in, dormant unless exported with `--native-charts-and-tables`**: A marker only declares that a group is eligible for PowerPoint-native Chart/Table replacement. Normal `svg_to_pptx.py` runs keep the fallback SVG children and convert them into independently editable DrawingML shapes. Pass `--native-charts-and-tables` only when the data source and chart/table-specific object model matter more than cross-renderer layout fidelity: it emits the PowerPoint Chart/Table object and skips the fallback children to avoid duplicates. Native styling preserves the core palette, text, axis, grid, and background colors where possible, but it is still a PowerPoint Chart/Table object rather than a pixel-identical SVG drawing.diff --git a/skills/ppt-master/references/pptx-structure-interface.md b/skills/ppt-master/references/pptx-structure-interface.mdindex 70a38091..e04d02bc 100644--- a/skills/ppt-master/references/pptx-structure-interface.md+++ b/skills/ppt-master/references/pptx-structure-interface.md@@ -16,7 +16,7 @@ Every new SVG project declares one deterministic route. Free-design, brand-only,**Zero-slot Layout**: A named Layout may contain no slots and no fixed Layout atoms. This is valid for a cover, poster, full-visual page, or other fixed composition. Do not manufacture an empty `utility` kind or full-page fake `object` slot.-**Adaptive change**: Template `strict` preserves the selected prototype contract. `adaptive` retains the prototype Master and may create a new Layout identity only when fixed Layout atoms or slot topology/bounds change. Update the page mapping immediately while authoring the first such page; never mutate a reused key silently.+**Adaptive change**: Template `strict` preserves the selected prototype contract. `adaptive` retains the prototype Master and may use a current or new Layout identity only when Strategist already declared it in the complete plan and lock. If construction proves that fixed Layout atoms or slot topology/bounds must change, stop and return upstream for Strategist to add or revise the definition and page mapping before authoring resumes; Executor never mutates a reused key or the lock.## 2. Explicit PPTX Master / Layout / Placeholder Metadata@@ -24,7 +24,7 @@ Every new SVG project declares one deterministic route. Free-design, brand-only,**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.-**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and may allocate a new Layout key/name only when fixed Layout atoms or slot topology/bounds change; update the lock during authoring. Mirror-created prototypes preserve validated source identity, literal paint, typography, effects, atomic geometry, and referenced assets in a new workspace. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology or fill missing facts.+**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and realizes the current or new Layout key/name declared by Strategist. A construction-discovered change to fixed Layout atoms or slot topology/bounds returns upstream for plan/lock repair and regenerated page context before authoring resumes. Mirror-created prototypes preserve validated source identity, literal paint, typography, effects, atomic geometry, and referenced assets in a new workspace. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology or fill missing facts.Imported inherited-shape visibility remains an immutable analysis fact until astructured mirror is materialized. The final mirror root carries that fact withdiff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.mdindex d05ae6ff..adf60106 100644--- a/skills/ppt-master/references/shared-standards-core.md+++ b/skills/ppt-master/references/shared-standards-core.md@@ -577,7 +577,7 @@ These forms are needed only when the stated PPT behavior matters:| Stable object grouping or object-level animation anchor | Wrap the intended object in `<g id="...">`. Content grouping is **mandatory** per §4.3 — a top-level `<g id>` is also the animation anchor; it is not an optional convenience. || Native PowerPoint background promotion | Outside structured mode, the first eligible visual layer may be a direct full-canvas `<rect>` or one inside a simple single-child group. Its fill must have a registered native mapping (solid, linear/radial gradient, or preset pattern), and it must have no transform, filter, clip, rounding, or visible stroke. Export writes the fill as Slide `p:bg`; image elements remain pictures. Structured routes use the narrower explicit solid-background ownership contract in [`pptx-structure-interface.md`](./pptx-structure-interface.md). || Free-design / brand-only PowerPoint structure | Use `pptx_structure.mode: flat`. Keep every represented object 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. Do not author Master/Layout identities, layers, or placeholder slots. |-| Reusable template-based PowerPoint Layout | Select one complete authoring SVG per page in `page_layouts`, declare each unique Master/Layout definition once, and assign pages through `page_pptx_layouts`. Strict preserves the prototype contract; adaptive retains its Master and may define and assign a new explicit Layout key during page authoring. Non-mirror skin follows `spec_lock`. |+| Reusable template-based PowerPoint Layout | Select one complete authoring SVG per page in `page_layouts`, declare each unique Master/Layout definition once, and assign pages through `page_pptx_layouts`. Strict preserves the prototype contract; adaptive retains its Master and uses a current or new Layout key already declared and assigned by Strategist. Construction cannot extend or mutate that mapping downstream. Non-mirror skin follows `spec_lock`. |**Hard rule — supported shape conversion**: Every PPT editability claim in this specification refers to the project converter reading `svg_output/` and emitting native DrawingML. `svg_final/` is a self-contained visual preview that may be inserted into PowerPoint as an SVG picture. PowerPoint's manual Convert-to-Shape operation is unsupported; do not narrow the authoring contract to its undocumented SVG subset.@@ -585,7 +585,7 @@ These forms are needed only when the stated PPT behavior matters:**Hard rule — root groups protect body-text layout**: Every visible direct root `<g>` declares positive root-coordinate `data-pptx-bounds="x y width height"`. Keep it when frame/native coordinates size one PowerPoint object; placeholder bounds also supply the slot frame. Checker validates this subcanvas against the root `viewBox`, then recursively validates only estimable `<text>` descendants against it. Nested groups and all shapes, images, paths, `<use>` instances, effects, and object frames are not content-boundary inputs. Per side, Checker ignores text/bounds overflow through `1px`, warns through `5%` of the containing boundary dimension, and fails above `5%`. Bounds do not clip or reflow.-Wrap each logical Slide-local body unit in a descriptive top-level `<g id>`; aim for **3–8 ordinary groups**, each becoming one animation step. Nested implementation groups may remain anonymous and need no bounds; any nested bounds are ignored. Flat pages use ordinary groups; structured slots already qualify, while titles, direct atomic Master/Layout elements, and canvas-level decoration may remain root primitives.+Wrap each logical Slide-local body unit in one descriptive top-level `<g id>`; group count follows the page's semantic units, and each group becomes one animation step when animation is enabled. Nested implementation groups may remain anonymous and need no bounds; any nested bounds are ignored. Flat pages use ordinary groups; structured slots already qualify, while titles, direct atomic Master/Layout elements, and canvas-level decoration may remain root primitives.**Structural atoms and slots are excluded automatically.** `data-pptx-layer` and `data-pptx-placeholder` semantics are read first; otherwise explicit `data-pptx-role` values (`background`, `decoration`, `header`, `footer`, `chrome`, `watermark`, `page-number`, `logo`) mark Slide-local static framing (§4.1, [`semantic-svg.md`](semantic-svg.md)). A normal slot group has exactly one direct compatible carrier; several drawing atoms require the explicit composite `object` proxy fallback. Native chart/table carrier groups retain their specialized [`native-data-interface.md`](./native-data-interface.md) contract.diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.mdindex 79e7b9ab..04f4dc17 100644--- a/skills/ppt-master/references/strategist-image.md+++ b/skills/ppt-master/references/strategist-image.md@@ -47,10 +47,10 @@ Follow `latex_render.py --help` for the manifest fields. The renderer writes dim## 4. Image Resource List-Add §VIII rows for the image resources actually planned from the confirmed source boundary and for every selected formula; a formula-only plan contains only formula rows. A permitted but unused source needs no row. Fill the scaffold's filename, dimensions/ratio, layout suggestion/pattern, purpose/type, acquisition, status, reference, and conditional AI fields. `Acquire Via` is `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`; status follows [`svg-image-embedding.md`](./svg-image-embedding.md). When a planned or explicitly required asset is not yet available, retain its row as `Pending` or `Needs-Manual`; never remove the row or change `Acquire Via` to make the Design Spec look complete. Only after §VIII passes the final-confirmation fidelity gate, project the same planned filenames and acquisition sources into `spec_lock.md images`; do not redesign the image plan while writing the lock. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web uses a concrete subject plus a few positive quality descriptors; formula preserves the source LaTeX and placement intent.+Add §VIII rows for the image resources actually planned from the confirmed source boundary and for every selected formula; a formula-only plan contains only formula rows. A permitted but unused source needs no row. Fill the scaffold's filename, dimensions/ratio, layout pattern, crop policy, purpose/type, acquisition, status, reference, and conditional AI fields. `Acquire Via` is `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`; status follows [`svg-image-embedding.md`](./svg-image-embedding.md). When a planned or explicitly required asset is not yet available, retain its row as `Pending` or `Needs-Manual`; never remove the row or change `Acquire Via` to make the Design Spec look complete. After §VIII passes final confirmation, project every placed row into `spec_lock.md images` as `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>` and omit unplaced Illustration Sheets. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web uses a concrete subject plus a few positive quality descriptors; formula preserves the source LaTeX and placement intent.-🚧 **GATE — non-formula rows**: read every entry in [`image-layout-patterns.md`](./image-layout-patterns.md). Copy one primary `#<id> <name>` plus any modifier names verbatim into each row; no empty, paraphrased, or invented ids. Strategist owns that pattern selection; Executor adapts its geometry while retaining the selected primary/modifier semantics, resource role, and explicit constraints. For decks with at least four image-bearing pages, use an Image-as-Canvas + Native Overlay pattern at least once unless every image is purely a cover, divider, or atmospheric backdrop; record the legitimate exception below the table. Reconsider a plan that collapses every row to the same left/right or top/bottom split.+🚧 **GATE — non-formula rows**: read every entry in [`image-layout-patterns.md`](./image-layout-patterns.md). Copy one primary `#<id> <name>` plus any modifier names verbatim into each row; no empty, paraphrased, or invented ids. Strategist owns that pattern selection; Executor adapts its geometry while retaining the selected primary/modifier semantics, resource role, and explicit constraints. Audit the completed column against page intent: repeated left/right or top/bottom structures are valid when the narrative calls for them, but catalog families and modifiers must remain available without a usage quota.-Choose narrative intent before dimensions: hero/full-bleed, atmosphere/background, side-by-side, or accent/inline. Portrait and multi-image calculations belong to [`image-layout-spec.md`](./image-layout-spec.md). Crop policy follows information integrity and explicit user intent, not the selected layout pattern. Add `no-crop` in `spec_lock.md images` whenever cropping could remove required pixels, labels, evidence, identity, or edge content; screenshots, charts, certificates/contracts, dense diagrams, logos, product markings, and formulas are common triggers rather than an exhaustive list. Formula rows use `Type: Latex Formula`, `Acquire Via: formula`, and `Rendered` or `Needs-Manual`.+Choose narrative intent before dimensions: hero/full-bleed, atmosphere/background, side-by-side, or accent/inline. Portrait and multi-image calculations belong to [`image-layout-spec.md`](./image-layout-spec.md). Write `Crop Policy: no-crop` whenever cropping could remove required pixels, labels, evidence, identity, or edge content; screenshots, charts, certificates/contracts, dense diagrams, logos, product markings, and formulas are common triggers rather than an exhaustive list. Otherwise write `Crop Policy: adaptive`: Executor may use complete display or a focal-safe crop, and the value never commands cropping. Formula rows use `Type: Latex Formula`, `Acquire Via: formula`, `Crop Policy: no-crop`, and `Rendered` or `Needs-Manual`.Judge `text_policy` per AI row using [`image-generator.md`](./image-generator.md) §5.3; paper figures, academic schematics, panel comparisons, and data-axis graphics are positive triggers for reconsidering an all-`none` plan. Step 5 dispatches pending `ai` / `slice` rows to Image_Generator and pending `web` rows to Image_Searcher; formula rows bypass both.diff --git a/skills/ppt-master/references/strategist-template.md b/skills/ppt-master/references/strategist-template.mdindex d570390d..bcbd85e8 100644--- a/skills/ppt-master/references/strategist-template.md+++ b/skills/ppt-master/references/strategist-template.md@@ -76,7 +76,7 @@ For `mirror` / `layout`, write `pptx_structure.mode: structured` plus `template_- **Reusable Layout roster**: Write every unique Layout once as `<layout_key>: <master_key> | <PowerPoint layout name> | <prototype source>`. Copy installed `template:<basename>` sources, including currently unused Layouts. A new adaptive Layout uses its first generated `P<NN>` as source. Reuse a key only when fixed atoms and slot ids/types/indices/bounds/binding modes are identical. Name authored keys after composition, never page topic. A Layout may intentionally have zero slots; do not manufacture an empty `utility` kind or full-page fake slot.- **Page assignment**: Write exactly one `page_pptx_layouts` row per page. Each key must exist in `pptx_layouts`. Check that distinct compositions do not collapse into role-only keys and that one skeleton does not split into topic-specific keys.- **Slot planning**: 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**: Initial definitions are complete. If construction changes reusable framing or slot topology/bounds, Executor creates one new definition sourced from that page and updates its assignment; it never mutates a reused contract silently. Export only compiles declared structure and never discovers or clusters Layouts.+- **Adaptive refinement**: Initial definitions are complete. If construction shows that reusable framing or slot topology/bounds must change, return to Strategist to add a definition sourced from that page and update its assignment before execution resumes. Executor never mutates or extends the contract; export only compiles declared structure and never discovers or clusters Layouts.- **Input prototypes**: Add one `page_layouts` row per page. Strict preserves that SVG's contract; adaptive keeps its Master and may declare a new output Layout; mirror also preserves literal visuals and text-node topology.**Chart compatibility**: Use `page_layouts` together with `page_charts` only when the selected prototype shell is compatible. For a chart page without an exact roster match, adaptive mode starts from the closest neutral prototype and declares an output Layout; strict mode selects an existing compatible Layout or revises the outline. Never omit `page_layouts` on a structured route.diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 9cccc486..487244a7 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -153,20 +153,9 @@ Record the confirmed visual style and rationale in `design_spec.md` first, inclu### e. Color Scheme Recommendation-**Hard rule**: User-specified colors are truth. Lock supplied HEX, brand colors, or natural-language directives; templates follow inherited-design precedence. Even direct locks fill all six roles (`background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, `body_text`) in each of ≥3 directions: repeat fixed roles and vary only open ones. Never emit an empty palette. Only without user/template colors use the table below.+**Hard rule**: User-specified colors are truth. Lock supplied HEX, brand colors, or natural-language directives; templates follow inherited-design precedence. Even direct locks fill all six roles (`background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, `body_text`) in each of ≥3 directions: repeat fixed roles and vary only open ones. Never emit an empty palette. Keep body-text contrast at least 4.5:1 and preserve confirmed/brand semantic roles.-Proactively provide a color scheme (HEX values) based on content characteristics and industry.--**Industry color quick reference** (full 14-industry list in `scripts/config.py` under `INDUSTRY_COLORS`):--| Industry | Primary Color | Characteristics |-|----------|--------------|-----------------|-| Finance / Business | `#003366` Navy Blue | Stable, trustworthy |-| Technology / Internet | `#1565C0` Bright Blue | Innovative, energetic |-| Healthcare / Health | `#00796B` Teal Green | Professional, reassuring |-| Government / Public Sector | `#C41E3A` Red | Authoritative, dignified |--**Color rules**: 60-30-10 rule (primary 60%, secondary 30%, accent 10%); text contrast ratio >= 4.5:1; no more than 4 colors per page.+**Reference — not a constraint**: Without user/template colors, propose project-specific directions from content and style. `scripts/config.py` industry colors and dominant/support/accent hierarchy are recall aids, never default locks, ratios, or color-count quotas.**Lock recurring semantic anchors, not every possible paint.** Add the neutral roles already known to recur across the deck—such as `surface`, `grid`, `scrim`, `overlay`, or `block-shade`—when the visual style and page plan establish a stable meaning for them. Do not try to predict every page-local tint, gradient stop, shadow/glow color, transparency composite, or one-off illustration tone. Those values are chosen from page context during execution; promote one into `spec_lock.colors` only when it becomes a reusable named role.@@ -296,14 +285,13 @@ python3 skills/ppt-master/scripts/chart_recall.py recall \--limit 6```-The command reads the live `charts_index.json` and returns positive-scoring candidates up to the requested 3–8 limit, plus an explicit `no-template-match` option. It never pads the shortlist with zero-score keys; zero positive matches means use the fallback. Do not load the full catalog into the prompt.+The command returns a lexical shortlist plus `no-template-match`. `low` / `none` also returns the full catalog under `semantic_fallback`; if stronger candidates all conflict, rerun with `--semantic-fallback`. Compare every returned catalog rule semantically—lexical overlap is unnecessary. Do not open the catalog separately or maintain a second index.**Selection**:-1. Inspect every returned `Pick for` / `Skip if` summary against the page; prefer the most specific valid structure.-2. Keep one primary visualization per page. Adapt its composition, density, colors, and decoration to the page; do not mimic blindly.-3. If every candidate conflicts, choose `no-template-match`: data-driven content falls back to a table, conceptual/illustrative content to an AI image when the confirmed image source permits it, and structural content to a custom layout.-4. Validate all selected keys before writing the lock:+1. Choose the most specific valid structure from the applicable review; keep one primary visualization per page and adapt its treatment rather than mimicking it.+2. Only after that review finds no fit, use `no-template-match`: data content falls back to a table, permitted conceptual content to an AI image, and structural content to a custom layout.+3. Validate all selected keys before writing the lock:```bashpython3 skills/ppt-master/scripts/chart_recall.py validate <key> [<key> ...]@@ -313,10 +301,12 @@ A failed validation must be corrected with a recalled key. `no-template-match` i**Section VII audit**: Use one combined table. Copy the selected candidate's returned `summary` verbatim into `Summary-quote`; record its returned path and page-specific usage. List real returned runners-up with page-specific rejection reasons. If no candidate fits, record `no-template-match`, the fallback, and why.+**Native-ready boundary**: Put every independent data chart or pure text-grid table in §VII and set `Native-ready: yes|no`; use `n/a` for conceptual rows. Choose `yes` only when the confirmed requirement or artifact afterlife benefits from an editable native data object; otherwise keep the designed SVG with `no`. Incidental sparklines, KPI trends, and insets stay in §IX; Executor never promotes them.+```-| Page | Template | Path | Summary-quote (verbatim) | Usage |-|---|---|---|---|---|-| P03 | line_chart | templates/charts/line_chart.svg | "<returned summary>" | <intent> |+| Page | Template | Path | Summary-quote (verbatim) | Native-ready | Usage |+|---|---|---|---|---|---|+| P03 | line_chart | templates/charts/line_chart.svg | "<returned summary>" | <yes/no/n/a> | <intent> |Runners-up considered:- <returned_key> | rejected for P03: <page-specific reason>@@ -345,7 +335,7 @@ Read the relevant `_index.md` at confirmation `d` (Layer 1 / Layer 2) for its ca## 3. Color Selection Reference-Do not start from a universal palette. Precedence is user / brand values → active template inheritance → the industry anchors in `scripts/config.py` → a project-specific proposal that realizes the locked visual style. Keep body-text contrast at least 4.5:1 and normally use no more than four chromatic colors on one page.+Do not start from a universal palette. Precedence is user / brand → active template → project-specific proposal; `scripts/config.py` industry anchors are optional recall. Keep body-text contrast at least 4.5:1; color count and distribution follow encoding, style, and natural assets, not a quota.Lock the stable role set the deck needs, including recurring neutrals such as `surface`, `grid`, `scrim`, `overlay`, or `block-shade`. These are identity anchors, not an exhaustive paint list. Executor may derive tints, shades, alpha, gradients, and effects, preserve necessary natural asset colors, and add sparse page-local accents for differentiation or ornament. Such accents must not form a competing/recurring palette; Strategist owns reusable positive / warning / negative roles.@@ -420,7 +410,7 @@ Generate Step 4 owns both artifact scaffolds. `design_spec.md` is the Strategist⛔ **GATE 2 — lock context fidelity.** After the Design Spec passes Gate 1, author its machine-relevant execution anchors and routing values into `spec_lock.md`. The lock may normalize syntax and add named recurring implementation roles justified by the Design Spec/page plan, but it must not change confirmed identity or introduce a competing direction. It is intentionally not a field-for-field copy and not a whitelist of every legal SVG value. If authoring exposes a contradiction or missing confirmed decision, return to Gate 1 and repair the Design Spec from the retained final-confirmation state; on a fresh recovery turn only, read the persisted final result once to restore that state.-**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography size; never re-derive a confirmed role. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every §VIII image row with its acquisition source. Omit planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor rebuilds page projection before every page ([executor-base.md](executor-base.md) §2.1). Repair the Design Spec only from retained final confirmation, then re-author affected lock rows.+**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography size; never re-derive a confirmed role. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, pattern, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor rebuilds page projection before every page ([executor-base.md](executor-base.md) §2.1). Repair the Design Spec only from retained final confirmation, then re-author affected lock rows.**Contextual extension**: derived paint or sparse local font/color garnish may stay in one SVG while non-structural and non-recurring. New base/semantic colors, structural/recurring fonts, resources, or patterns require upstream repair; Executor never reverse-projects a choice as fact. Promote garnish upstream before reuse, regenerate page-context, and never add values to silence a comparison.diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.mdindex be6273e6..51795d1c 100644--- a/skills/ppt-master/references/svg-image-embedding.md+++ b/skills/ppt-master/references/svg-image-embedding.md@@ -11,15 +11,10 @@ Technical spec and workflow for adding images to SVG files.Defined in the Design Specification & Content Outline; each image carries an `Acquire Via` field plus a status annotation. This file is authoritative for status names and SVG embedding behavior. If image approach includes "B) User-provided": run `analyze_images.py` right after the Strategist confirmation stage and complete the list before outputting the design spec.```markdown-| Filename | Dimensions | Purpose | Type | Acquire Via | Status | Reference |-|----------|------------|---------|------|-------------|--------|-----------|-| cover_bg.png | 1280x720 | Cover background | Background | ai | Pending | Modern tech abstract, deep blue gradient |-| team.jpg | 800x600 | Team photo | Photography | web | Pending | Diverse engineering team in modern office |-| product.png | 600x400 | Page 3 product photo | Photography | user | Existing | - |-| formula_001.png | 736x168 | Page 3 block equation | Latex Formula | formula | Rendered | `E = mc^2` |-| chart.png | 600x400 | Page 5 placeholder | Illustration | placeholder | Placeholder | Team collaboration scene to be added later |-| spot_sheet.png | 1024x1024 | 2x2 spot illustration sheet, not placed | Illustration Sheet | ai | Pending | Four same-family spot illustrations on a clean grid |-| spot_team.png | TBD after slicing | Page 4 team spot illustration | Illustration | slice | Pending | From `spot_sheet.png` cell 1,1 |+| Filename | Dimensions | Purpose | Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference |+|----------|------------|---------|------|----------------|-------------|-------------|--------|-----------|+| team.jpg | 800x600 | Team photo | Photography | `#2 left-third` | adaptive | web | Pending | Diverse engineering team in modern office |+| formula_001.png | 736x168 | Page 3 block equation | Latex Formula | formula | no-crop | formula | Rendered | `E = mc^2` |```### Image Status Enumdiff --git a/skills/ppt-master/references/visual-review.md b/skills/ppt-master/references/visual-review.mdindex 685f180d..8ab1fcae 100644--- a/skills/ppt-master/references/visual-review.md+++ b/skills/ppt-master/references/visual-review.md@@ -40,7 +40,7 @@ The subagent reads inputs 2–4 **once** at the start of its turn, then iterates| ~~H5~~ | Font-ramp drift | *covered by `svg_quality_checker.py` — see §0 prerequisites* | n/a (do not re-check) || H6 | Element collision | rect/circle/path bboxes overlap with z-order violating semantics | open spacing || H7 | Anchored element displaced | page number / header / footer covered, missing, or out of canvas | restore to anchor position |-| H8 | Image rendering broken | `<image>` empty / broken-image / severe distortion | fix `href`, adjust `preserveAspectRatio`, add `no-crop` if face/data is cropped |+| H8 | Image rendering broken | `<image>` empty / broken-image / severe distortion | fix `href`; for `adaptive`, choose `meet` or a safer crop; a new complete-display requirement returns to §VIII `Crop Policy` and lock projection || H9 | Missing key element | element required by `design_spec §IX` outline is absent from rendered slide | recreate from spec |Detection order (run sequentially, do not parallelize within a single subagent):diff --git a/skills/ppt-master/references/visual-styles/soft-rounded.md b/skills/ppt-master/references/visual-styles/soft-rounded.mdindex 16ea7496..a66073a9 100644--- a/skills/ppt-master/references/visual-styles/soft-rounded.md+++ b/skills/ppt-master/references/visual-styles/soft-rounded.md@@ -21,9 +21,9 @@ Approachable and modern. Rounded cards, gentle elevation, friendly rhythm. For p## 3. Using the deck's colors- Theme color used confidently on covers / chapter backgrounds; same-hue tints for card backings; accent for key figures.-- Warmer, more generous color use than swiss / editorial — still disciplined (60-30-10), never rainbow.+- Warmer, more generous color use than swiss / editorial. Assign hues by semantic role and visual hierarchy; intentional multi-hue compositions remain valid.-> HEX values come from confirmation `e`; this style only governs the confident-but-disciplined (60-30-10) color use — it names no colors.+> HEX values come from confirmation `e`; this style governs confident, friendly color use without naming colors or imposing a ratio.## 4. Texture / elevationdiff --git a/skills/ppt-master/scripts/docs/chart-recall.md b/skills/ppt-master/scripts/docs/chart-recall.mdindex f318ac8d..7db3604f 100644--- a/skills/ppt-master/scripts/docs/chart-recall.md+++ b/skills/ppt-master/scripts/docs/chart-recall.md@@ -1,6 +1,6 @@# Chart Candidate Recall-`chart_recall.py` gives the Strategist a bounded, deterministic shortlist without loading the full chart catalog into the runtime prompt. It reads `templates/charts/charts_index.json` on every invocation, so the catalog remains the only template registry.+`chart_recall.py` gives the Strategist a bounded deterministic shortlist, then exposes the full live catalog only when lexical confidence is `low` / `none` or the caller requests semantic review after candidate conflict. It reads `templates/charts/charts_index.json` on every invocation, so the catalog remains the only template registry.## Recall candidates@@ -15,7 +15,9 @@ python3 skills/ppt-master/scripts/chart_recall.py recall \--limit 6```-`--limit` accepts 3-8 and defaults to 6. It is a maximum, not a padding target: the deterministic JSON contains only positive-scoring candidates, up to the requested limit. Zero positive matches return an empty `candidates` list plus the explicit `no-template-match` option.+`--limit` accepts 3-8 and defaults to 6. It is a maximum, not a padding target: the deterministic JSON contains only positive-scoring candidates, up to the requested limit. `low` / `none` results also contain `semantic_fallback.catalog`, allowing the Strategist to compare the page meaning against every live `Pick` / `Skip` rule without requiring lexical overlap.++When medium/high candidates all conflict with the page, rerun the same command with `--semantic-fallback`. Review the returned catalog semantically, then select one exact key or retain `no-template-match`; do not open or maintain a second keyword/category index.| Field | Contract ||---|---|@@ -23,9 +25,10 @@ python3 skills/ppt-master/scripts/chart_recall.py recall \| `semantic_tags` | Deduplicated input tags || `confidence` | Lexical recall strength; never a selection decision || `candidates` | Ranked keys, SVG paths, verbatim catalog summaries, scores, and matched tags |-| `no_template_match` | Explicit fallback option when every candidate conflicts with the page |+| `semantic_fallback` | Full live catalog, present only for `low` / `none` or `--semantic-fallback`; requires semantic comparison |+| `no_template_match` | Explicit fallback after the applicable lexical and semantic review finds no fit |-The scorer treats the key and the summary's Pick clause as positive evidence and the Skip clause as negative evidence. A term found only in Skip cannot make a candidate eligible, and Skip matches explicitly reduce a candidate's score. Unicode input is NFKC-normalized before matching. The Strategist still applies semantic judgment: inspect every returned summary, reject candidates whose Skip clause matches, and prefer the most specific valid structure. A low score does not authorize a forced match; when no candidate has a positive final score, the result carries an empty shortlist and the explicit fallback.+The scorer treats the key and the summary's Pick clause as positive evidence and the Skip clause as negative evidence. A term found only in Skip cannot make a candidate eligible, and Skip matches explicitly reduce a candidate's score. Unicode input is NFKC-normalized before matching. The Strategist still applies semantic judgment: inspect every applicable returned rule, reject candidates whose Skip clause matches, and prefer the most specific valid structure. An empty shortlist opens full semantic review; it does not authorize either a forced lexical match or immediate `no-template-match`.## Validate selected keysdiff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex c1205bdd..1865b257 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -55,7 +55,8 @@ Notes:the human-readable brief; the lock schema owns machine execution values. Forstructured template use, strict input prototypes must match their assignedMaster/Layout; adaptive input prototypes retain the assigned Master while a- new output Layout is validated only after its generated SVG exists. Versioned+ new output Layout already declared by Strategist is cross-validated after its+ generated SVG exists. Versionedscaffolds carry the schema marker. Markerless legacy artifacts are left ontheir prior validation path with a warning;malformed or unsupported markers are errors.diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 5b751798..c33dd92a 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -336,7 +336,7 @@ Behavior:- Missing root bounds fails on final pages/templates and under `--template-mode`; references warn until adapted.- 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.-- Template `page_layouts` remains input provenance. Strict preserves the prototype contract; adaptive retains its Master and may use a new Layout identity only when fixed Layout atoms or slot topology/bounds change.+- Template `page_layouts` remains input provenance. Strict preserves the prototype contract; adaptive retains its Master and may use a new Layout identity only when Strategist declared it in the plan and lock. Construction cannot allocate or mutate Layout identity downstream.- Legacy structured/template contracts using `baseline`, `template`, `preserve`, `layout_strategy`, `data-pptx-layout-kind`, `distilled`/`utility`, direct atomic placeholders, or incomplete Master identity are rejected with a pointer to [`create-template`](../../workflows/create-template.md). Create a new workspace and generate new structured SVG pages; do not upgrade the existing project in place. Explicit flat free-design/brand-only projects intentionally omit Master identity.- 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.@@ -358,7 +358,7 @@ Behavior:- Long-audio import and automatic long-audio splitting are not supported; keep narration assets page-level- Voice choices can be listed with `python3 scripts/notes_to_audio.py --list-common-voices`, `python3 scripts/notes_to_audio.py --list-voices --locale zh-CN`, or provider-specific `--provider <name> --list-voices`- Page transitions are controlled by `-t/--transition`; per-element entrance animations are controlled by `-a/--animation`-- Per-element animation applies to ordinary top-level SVG `<g id="...">` groups in z-order; aim for 3–8 Slide-local content groups per slide. Master/Layout atoms and slot groups are structural and excluded; exact id tokens remain a fallback only when explicit structural roles are absent+- Per-element animation applies to ordinary top-level SVG `<g id="...">` groups in z-order; use one group per logical Slide-local content unit rather than targeting a group count. Master/Layout atoms and slot groups are structural and excluded; exact id tokens remain a fallback only when explicit structural roles are absent- An explicit `animations.json` group entry may override the marker-free legacy chrome-name heuristic. It cannot override `data-pptx-layer` or an explicit static role/placeholder marker- Start mode is set by `--animation-trigger`, mirroring PowerPoint's Start dropdown: `after-previous` (default, cascade with `--animation-stagger` spacing on slide entry), `on-click` (presenter-paced), `with-previous` (all together on slide entry)- `on-click` is for live presentations only; recorded narration rejects it because the tool does not generate object-level click timingsdiff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex 747f1491..d1e67854 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -33,7 +33,7 @@"skills/ppt-master/references/strategist-template.md": 2100,"skills/ppt-master/templates/design_spec_reference.md": 850,"skills/ppt-master/templates/spec_lock_reference.md": 1650,- "skills/ppt-master/workflows/generate-pptx.md": 12200,+ "skills/ppt-master/workflows/generate-pptx.md": 12300,"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800},"load_sets": {@@ -77,7 +77,7 @@"skills/ppt-master/templates/README.md","skills/ppt-master/templates/decks/README.md"],- "max_tokens": 57100+ "max_tokens": 57200},"route.create-template.layout": {"description": "Create Layout path through Template_Designer, SVG core, and the structured PPTX interface.",@@ -95,7 +95,7 @@"skills/ppt-master/templates/README.md","skills/ppt-master/templates/layouts/README.md"],- "max_tokens": 57300+ "max_tokens": 57400},"route.enhance-native-pptx": {"description": "Finished-PPTX native enhancement route.",@@ -399,7 +399,7 @@"stage.generate.template.deck"],"files": [],- "max_tokens": 92000+ "max_tokens": 92200},"route.generate.layout-structured-no-image": {"description": "Layout-preset structured Generate-PPTX path without image acquisition.",@@ -411,7 +411,7 @@"stage.generate.template.layout"],"files": [],- "max_tokens": 92500+ "max_tokens": 92700},"route.generate.topic-only-flat-no-image": {"description": "Topic research followed by the default flat no-image Generate-PPTX path.",@@ -601,7 +601,7 @@"skills/ppt-master/scripts/docs/pptx-transitions.md","skills/ppt-master/scripts/docs/svg-pipeline.md"],- "max_tokens": 18500+ "max_tokens": 18600},"stage.generate.animation-options": {"description": "Conditional deck-wide transition, auto-advance, and entrance-animation options.",diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.pyindex 5a851c7b..08745170 100644--- a/skills/ppt-master/scripts/svg_quality_checker.py+++ b/skills/ppt-master/scripts/svg_quality_checker.py@@ -5876,28 +5876,6 @@ class SVGQualityChecker:f"{filename} is a Generated slice row but images/{filename} does not exist.",))- has_coverage_note = 'Image-as-canvas' in spec_text or 'image-as-canvas' in spec_text- pattern_ids = self._collect_layout_pattern_ids(image_rows)- if len(image_rows) >= 4 and not any(38 <= pid <= 46 for pid in pattern_ids):- if not has_coverage_note:- self._illustration_issues.append((- 'warning',- 'missing_image_as_canvas',- "deck has 4+ image-bearing rows but no #38-#46 image-as-canvas "- "layout and no coverage note in design_spec.md §VIII.",- ))-- conventional_ids = {1, 2, 3, 5, 6}- if len(image_rows) >= 4 and pattern_ids and pattern_ids.issubset(conventional_ids):- if not has_coverage_note:- self._illustration_issues.append((- 'warning',- 'layout_pattern_degenerated',- "all image-bearing rows use only basic full-bleed / left-right / "- "top-bottom patterns (#1/#2/#3/#5/#6); re-check "- "references/image-layout-patterns.md for modifiers or image-as-canvas options.",- ))-for row in image_rows:self._check_decorative_image_row(row, project_path, svg_texts)@@ -5982,14 +5960,6 @@ class SVGQualityChecker:def _row_layout(row: Dict[str, str]) -> str:return row.get('Layout pattern', '').strip()- @staticmethod- def _collect_layout_pattern_ids(rows: List[Dict[str, str]]) -> set[int]:- ids: set[int] = set()- for row in rows:- for match in re.finditer(r'#(\d+)\b', SVGQualityChecker._row_layout(row)):- ids.add(int(match.group(1)))- return ids-def _load_project_lock_images(self, project_path: Path) -> set[str]:"""Return filenames listed under spec_lock.md images."""lock_path = project_path / 'spec_lock.md'diff --git a/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md b/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.mdindex 2d19f0ae..b84546fb 100644--- a/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md+++ b/skills/ppt-master/templates/charts/CHART_STYLE_GUIDE.md@@ -25,12 +25,14 @@|---|---|| 可视化类型与数据到图形的映射 | 项目字体与字号体系 || 节点、连接、轴、系列和标签关系 | 项目调色板与品牌色 |-| 构图骨架、阅读顺序和容量边界 | 圆角、阴影、渐变、纹理和装饰语言 |+| 可视化类型、构图骨架和阅读顺序 | 实际分组、框架数量、项目数量与容量适配 || 必要的状态与语义区分 | 页面背景、页头、页脚和品牌 chrome || 独立预览所需的中性样式 | 最终强调策略与页面级视觉层级 |**Hard rule**: Executor 适配模板时保留可视化类型、信息关系和数据准确性;最终视觉必须来自当前项目,而不是继承模板的示例审美。+**Reference — not a constraint**: 模板的分组、框架数、项目数和示例容量用于展示结构,不是项目上限。Executor 可按实际内容调整,但不能改变已选可视化类型、关系或数据语义。+### 1.2 保留判断对每个视觉元素按顺序判断:diff --git a/skills/ppt-master/templates/charts/README.md b/skills/ppt-master/templates/charts/README.mdindex 5bafa133..bad4e6cf 100644--- a/skills/ppt-master/templates/charts/README.md+++ b/skills/ppt-master/templates/charts/README.md@@ -6,7 +6,7 @@ This directory contains the standardized SVG visualization templates used by PPT[`charts_index.json`](./charts_index.json) is the single source of truth for the library: total count + one selection-rule `summary` per template (format: `"Pick for X. Skip if Y (use other_key)."`). [`chart_recall.py`](../../scripts/chart_recall.py) can recall a bounded candidate set from this live registry without maintaining a second category or keyword index.-For one planned page, provide 3-8 English semantic content-shape tags, then inspect the positive-scoring returned summaries plus the explicit `no-template-match` option. The requested 3-8 limit is a cap: the tool never pads a weak result with zero-score keys, and zero positive matches returns only the fallback. See [`chart-recall.md`](../../scripts/docs/chart-recall.md). The Generate workflow remains the authority for when Strategist uses this helper; maintainers may still open the registry directly when editing or auditing the catalog.+For one planned page, provide 3-8 English semantic content-shape tags, then inspect the positive-scoring summaries plus the explicit `no-template-match` option. The requested limit is a cap, not a padding target. Low/no lexical confidence automatically returns the live catalog for AI semantic review; when stronger lexical candidates all conflict, rerun with `--semantic-fallback`. See [`chart-recall.md`](../../scripts/docs/chart-recall.md). The Generate workflow remains the authority for when Strategist uses this helper; maintainers may still open the registry directly when editing or auditing the catalog.## Authoring contract@@ -45,7 +45,7 @@ below. Conceptual diagrams and frameworks are never labeled as native charts.## Native Chart/Table replacement markers-Supported data chart templates include a `<g data-pptx-replace-with="chart">` marker by default, and pure text-grid table templates include a `<g data-pptx-replace-with="table">` marker the same way. The default SVG export path is unchanged: the fallback vector artwork is exported as shape-based DrawingML exactly as drawn. When `svg_to_pptx.py --native-charts-and-tables` is enabled, that fallback group is replaced with a native PowerPoint Chart or Table object using the JSON metadata inside its child `<metadata type="application/json">` node. The legacy `--native-objects` spelling remains a compatibility alias.+Supported data chart templates include a `<g data-pptx-replace-with="chart">` marker by default, and pure text-grid table templates include the table form. These are capability examples, not project decisions: a generated page keeps and rewrites the marker only when its Design Spec §VII row says `Native-ready: yes`; `no` / `n/a` omits it. The default SVG export path remains shape-based DrawingML. With `--native-charts-and-tables`, prepared groups become native PowerPoint Chart/Table objects from their JSON metadata. The legacy `--native-objects` spelling remains a compatibility alias.`--native-charts-and-tables` is an explicit native-object opt-in and may be lossy or visually normalized. Replacement-local value labels, center KPIs, callouts, quadrant notes, fixed axis ranges, and custom binning/splits may not survive native replacement unless represented by the payload. ChartEx palette entries do survive when supplied through valid payload colors, but this does not preserve every ChartEx style detail. Detectable information-loss risks should be reported as warnings, not handled by disabling an otherwise supported replacement marker. Review those warnings and compare the native-object export with the default shape-based export before delivery.diff --git a/skills/ppt-master/templates/charts/charts_index.json b/skills/ppt-master/templates/charts/charts_index.jsonindex dde2f940..5c6c675c 100644--- a/skills/ppt-master/templates/charts/charts_index.json+++ b/skills/ppt-master/templates/charts/charts_index.json@@ -5,8 +5,8 @@"formats": ["ppt169"],"filePattern": "{key}.svg","libraryPositioning": "Visualization template library covering charts, infographics, diagrams, and strategic frameworks. The `charts/` path is retained for backward compatibility. Templates are named by visual structure, not by business-model name — model-specific frameworks (SWOT, BCG, PEST, OKR, Porter's Five Forces, Value Chain, etc.) are matched via keywords in `summary`.",- "summaryGrammar": "Each chart's `summary` is a selection rule, not a description. Format: 'Pick for <content shape + scale>. Skip if <reason → alternative>'. Strategist supplies 3–8 semantic content-shape tags per candidate page; chart_recall.py returns a bounded shortlist without loading the full catalog into the runtime prompt.",- "updated": "2026-07-03"+ "summaryGrammar": "Each chart's `summary` is a selection rule, not a description. Format: 'Pick for <content shape + scale>. Skip if <reason → alternative>'. Strategist supplies 3–8 semantic content-shape tags per candidate page; chart_recall.py returns a bounded lexical shortlist and exposes the full catalog only for low/no confidence or requested semantic fallback.",+ "updated": "2026-07-21"},"charts": {"area_chart": {diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex 8665b70e..a3efe315 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -26,8 +26,8 @@ The command refuses to shadow any recognized existing design-spec artifact, incl| IV. Typography System | Per-role stacks and locked size slots | Additional recurring roles when used || V. Layout Principles | Page regions and project spacing | Template-specific constraints only when active || VI. Icon Usage Specification | Approved icon inventory | Empty table when no icons are used |-| VII. Visualization Reference List | Selected candidates or an empty table | Only pages with visualization work |-| VIII. Image Resource List | Image acquisition and placement rows or an empty table | AI-only columns apply to `ai` rows |+| VII. Visualization Reference List | Candidates and independent charts/tables with `Native-ready`, or empty | Incidental microvisuals stay in §IX |+| VIII. Image Resource List | Rows with `Layout pattern` and `Crop Policy`, or empty | AI columns apply only to `ai` rows || IX. Content Outline | Complete ordered execution roster; one Slide block per final page, matching the exact Page Count; each has `Audience move` | Page-specific facts, charts, images, and template mappings || X. Speaker Notes Requirements | Filename and content policy | — |diff --git a/skills/ppt-master/templates/scaffolds/design_spec.md b/skills/ppt-master/templates/scaffolds/design_spec.mdindex 21b0b9fe..30ee5bbf 100644--- a/skills/ppt-master/templates/scaffolds/design_spec.md+++ b/skills/ppt-master/templates/scaffolds/design_spec.md@@ -101,13 +101,13 @@## VII. Visualization Reference List-| Page | Template | Path | Summary-quote | Usage |-| --- | --- | --- | --- | --- |+| Page | Template | Path | Summary-quote | Native-ready | Usage |+| --- | --- | --- | --- | --- | --- |## VIII. Image Resource List-| Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Acquire Via | Status | Reference | text_policy | page_role |-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |+| Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference | text_policy | page_role |+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |## IX. Content Outlinediff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.mdindex 079b0690..08f08ad7 100644--- a/skills/ppt-master/templates/spec_lock_reference.md+++ b/skills/ppt-master/templates/spec_lock_reference.md@@ -73,6 +73,7 @@ Structured section value shapes:- `font_family` grammar: one non-empty PPT-safe exported family stack; role-specific families may extend it in the same section.- `objective` grammar: one concise sentence preserving the deck goal and audience success condition.- `image_rendering` grammar: one catalog id, or `custom` with `image_rendering_behavior`.+- `images`: `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>`; omit unplaced Illustration Sheets.- Custom reference grammar: comma-separated exact catalog ids with no duplicates. Reference fields are valid only for `custom`; omit them for a genuinely novel direction.- `stroke_width` grammar: `1.5`, `2`, or `3`; present only for `tabler-outline`.- `page_rhythm` grammar: `P` + at least two digits (`P01`, `P100`) followed by `anchor|dense|breathing`.diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 729ef460..d04bab8b 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -210,7 +210,7 @@ The core first chooses the proposed Stage 2 source ids. Load the image module beIf the user opted out of the page but did not delegate confirmation, skip launch and run the same three stages in chat with explicit user responses. If the user explicitly delegated confirmation, consolidate the same three stages into one AI-authored summary and proceed without `result.json`. Otherwise report the launch URL and keep the staged chat summaries available as fallback.-⛔ **GATE — consume the final state once into the Design Spec, then author the lock from context.** Treat every explicitly present final value as user-owned input and consume it at the semantic type defined by [`strategist.md`](../references/strategist.md) §1 and its field owner. Do not omit or substitute a value, and do not silently strengthen or weaken its type; accepting a recommendation does not turn a Reference or Permission into a Literal requirement. First author and audit the complete `design_spec.md` through [`strategist.md`](../references/strategist.md) §6.2 from the retained final object, including production mechanics, the confirmed image-source boundary, and explicit `image_notes` obligations. Do not reopen `result.json` afterward. Only after that audit passes, author `spec_lock.md` from the completed Design Spec and current project/page/template context: preserve confirmed identity, choose reusable execution anchors and routing values, and do not enumerate page-local paint or font choices. Apply `strategist-template.md` §3 for an active template, and never write a separate image palette. If a confirmed requirement cannot be honored, follow [`failure-recovery.md`](governance/failure-recovery.md) instead of silently changing it.+⛔ **GATE — consume the final state once into the Design Spec, then author the lock from context.** Treat every explicitly present final value as user-owned input and consume it at the semantic type defined by [`strategist.md`](../references/strategist.md) §1 and its field owner. Do not omit or substitute a value, and do not silently strengthen or weaken its type; accepting a recommendation does not turn a Reference or Permission into a Literal requirement. First author and audit the complete `design_spec.md` through [`strategist.md`](../references/strategist.md) §6.2 from the retained final object, including production mechanics, the confirmed image-source boundary, and explicit `image_notes` obligations. Do not reopen `result.json` afterward. Only after that audit passes, author `spec_lock.md` from the completed Design Spec and current project/page/template context: preserve confirmed identity, choose reusable execution anchors and routing values, project each placed image's source/pattern/crop policy without reselection, and do not enumerate page-local paint or font choices. Apply `strategist-template.md` §3 for an active template, and never write a separate image palette. If a confirmed requirement cannot be honored, follow [`failure-recovery.md`](governance/failure-recovery.md) instead of silently changing it.**Mandatory — split-mode note** (not a separate confirmation): after listing the Strategist confirmation stage details, you MUST append exactly one short line (rendered in the user's language, prefixed with 💡) about generation mode. Pick the variant by qualitative read of upstream-load signals — recommended page count, source-material bulk, whether `topic-research` ran with substantial web-fetch accumulation:@@ -398,7 +398,7 @@ Use `global` as the compact cross-page anchor set, `page_context` as the page deEach 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. When a page actually needs a literal stock shape, load and apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before drawing it. Diagram relationships remain Shape-first; do not infer a preset from contour similarity.-`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive assigns a new Layout key/name and updates `spec_lock.md` when fixed atoms or slot topology/bounds change. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.+`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive uses the current or new Layout key/name already declared by Strategist. If construction proves that fixed atoms or slot topology/bounds must change, stop and return upstream for Strategist to repair the owning plan and lock, regenerate the page context, then resume; Executor never mutates `spec_lock.md`. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.`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.@@ -414,7 +414,7 @@ Run the command unfiltered—do not pipe it through `tail`, `head`, `grep`, or a```bashpython3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json```-- **MUST**: Before this gate, every supported chart/table—including mini charts and sparklines—already has its own draw-time marker plus JSON metadata.+- **MUST**: Before this gate, every chart/table whose Design Spec §VII row says `Native-ready: yes` already has its own draw-time marker plus JSON metadata. Rows marked `no` / `n/a` and incidental microvisuals outside §VII remain ordinary SVG.- Run the command unfiltered—do not pipe it through `tail`, `head`, `grep`, or another output truncator. One invocation already scans every page and reports the complete issue set.- On failure, review all `blocking` errors and all advisory warnings from that run before editing. Choose which warnings merit work, fix every blocking error and the selected warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never run the checker between individual fixes or use repeated invocations to discover one next issue at a time. If terminal output is truncated, extract only `categories.blocking.issues` and, when needed, `categories.introduced.issues` from the report written by that same run.- 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`.diff --git a/skills/ppt-master/workflows/stages/verify-charts.md b/skills/ppt-master/workflows/stages/verify-charts.mdindex 03ca701f..58b4f6fc 100644--- a/skills/ppt-master/workflows/stages/verify-charts.md+++ b/skills/ppt-master/workflows/stages/verify-charts.md@@ -22,6 +22,8 @@ The calculator has direct CLI models for simple bars, lines/scatter, pie/donut,Read `<project_path>/design_spec.md` §VII Visualization Reference List (authoritative deck plan; cross-check against §IX page outline) and include every page whose SVG geometry is driven by data values. Classify each included page into exactly one mode:+Incidental microvisuals outside §VII are not inferred into this list. If one requires coordinate verification, repair §VII first so the Strategist-owned plan remains authoritative.+| Mode | `charts_index.json` keys | Notes ||------|--------------------------|-------|| `direct-calc` | `column_chart`, `horizontal_bar_chart` | Use `calc bar`; add `--horizontal` for horizontal bars. |diff --git a/skills/ppt-master/workflows/stages/visual-review.md b/skills/ppt-master/workflows/stages/visual-review.mdindex 5078bc29..81723265 100644--- a/skills/ppt-master/workflows/stages/visual-review.md+++ b/skills/ppt-master/workflows/stages/visual-review.md@@ -144,7 +144,7 @@ post-processing and export.- **Iteration budget**: default 1 iteration. Bumping to 2 doubles render cost and roughly triples token cost. Only worth it for high-stakes / final-cut decks.- **Don't-touch (rubric §3)** is hard-enforced by subagents. If you want the subagent to e.g. change a brand color, that is **out of scope** — make the change manually first, then re-render & re-review.- **Backups**: every modified SVG has a `.review/backup/<page>.iter<N>.svg` rollback anchor. Restore by `cp`.-- **The rubric is not the designer**: it catches collisions, drift, and rhythm errors — it does not improve a fundamentally weak layout. If 80%+ of pages come back `needs_human`, the design spec or the executor's choice of layout patterns is the root cause, not this stage.+- **The rubric is not the designer**: it catches collisions, drift, and rhythm errors — it does not improve a fundamentally weak layout. If 80%+ of pages come back `needs_human`, the Design Spec's pattern selection or Executor's realization geometry is the root cause, not this stage.- **Playwright output discipline**: when an agent uses the playwright MCP tool `browser_take_screenshot` directly (outside the `visual_review.py` script), the `filename` parameter is resolved against the CWD (typically the repo root) — passing a bare relative path will create stray directories inside the repository. Always pass an absolute path:- One-off probe / ad-hoc inspection → `/tmp/probe-<topic>-<n>.png`- Project artifact (replaces what the script would have produced) → `<project_path>/.preview/<page>.png` (absolute)