Skip to content

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

docs(generate): define strategist-owned material preparation

hugohe361c3789b655b
diff --git a/AGENTS.md b/AGENTS.md
index b9eadc03..c4ab3476 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,6 +27,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
## Required Conventions
- **Repo-wide style rules** — when editing prompt files under [`skills/ppt-master/references/`](skills/ppt-master/references/), Python under [`skills/ppt-master/scripts/`](skills/ppt-master/scripts/), or any other code/prose in the repo, follow the matching style rule in [`docs/rules/`](docs/rules/).
+- **Prompt decision ownership** — follow [`docs/rules/prompt-style.md`](docs/rules/prompt-style.md) §4.1: Strategist readies every selected resource; Executor uses only that inventory and owns realization. Never move acquisition or reselection downstream.
- **Markdown language consistency** — Markdown files under `skills/ppt-master/workflows/`, `skills/ppt-master/references/`, and `docs/` are currently single-language per directory. New files mirror the language of their siblings; do not mix English scaffolding with Chinese paragraphs (or vice versa) inside one file. Chat replies are unaffected.
## Compatibility Boundary
diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.md
index 51e65dab..5bb97014 100644
--- a/docs/rules/prompt-style.md
+++ b/docs/rules/prompt-style.md
@@ -94,6 +94,24 @@ Boundary cases go by this test, not by how strong the verb feels: "never split a
> 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
+
+Constraint strength and decision ownership are independent. Preserve this chain whenever writing, compressing, or reviewing multi-role prompts:
+
+| Layer | Owns |
+|---|---|
+| User / initial materials | Supplied facts/assets, desired outcome, exclusions, and permission boundaries remain authoritative |
+| Strategist / plan + preparation | Assess material sufficiency; trigger permitted fact research; decide the approved content, resources, keys, identity anchors, and exact page roster; materialize the planned project-local inventory or record an explicit `Needs-Manual` dependency before execution |
+| Executor / realization | Use only the prepared inventory and realize the approved selections through geometry, composition, hierarchy, and treatment; sparse local font/color garnish is allowed only while non-structural and non-recurring |
+
+**Preparation timing**: Fact research required for planning may run before final confirmation. AI / web / slice acquisition runs only from the completed `design_spec.md §VIII` and `spec_lock.md`, after final confirmation and before Executor. Image_Generator, Image_Searcher, and icon-sync tooling execute Strategist-owned preparation; they are not independent decision owners.
+
+**Hard rule**: downstream freedom exists only in dimensions left open upstream. A named outcome retains identity; a broad semantic request permits in-class choice. Once the plan resolves that choice, execution cannot reopen or substitute it. Executor never searches, generates, downloads, syncs, invents, or replaces a resource; missing material returns to Strategist-owned preparation or upstream repair.
+
+> Mnemonic — restaurant contract: the customer supplies initial ingredients and the desired dish; Strategist plans the dish and prepares the complete mise en place; Executor cooks from that prepared inventory. “Mapo tofu” cannot become tomato-and-eggs or tofu soup, while “a tofu dish” leaves deliberate in-class freedom.
+
+**Review gate**: treat any prompt refactor that erases this ownership chain, moves acquisition into Executor, turns a permission into a quota, or turns flexible realization into silent reselection as a semantic regression even when the compressed wording is shorter.
+
---
## 5. Tables First
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 8e0f5b08..4d4b63d4 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -377,7 +377,7 @@ The Strategist phase produces two artifacts that look redundant but serve differ
- `design_spec.md` — human-readable narrative; the "why" of the deck (communication intent, audience outcome, narrative / template / visual rationale, page outline)
- `spec_lock.md` — machine-readable execution contract; the compact `audience` / `objective` / `core_message` communication anchors plus stable identity/reuse roles and routing values (core HEX/font roles, icon library, image resources, and structure mappings)
-Why both? `design_spec.md` preserves the complete confirmed solution and rationale; `spec_lock.md` names the subset that must remain stable or routable across pages. It is authored from that Design Spec plus the page/resource/template context, not copied field by field from `result.json`. [Generate PPTX Step 6](../skills/ppt-master/workflows/generate-pptx.md#step-6-executor-phase) rebuilds a read-only `page-context` view before every page. The projector emits the stable anchors and current-page routing facts needed for authoring. Contextual tints, gradient/effect paints, and one-off export-safe display families remain page decisions; they need a lock row only after becoming a recurring semantic role.
+Why both? `design_spec.md` preserves the complete confirmed solution and rationale; `spec_lock.md` names the subset that must remain stable or routable across pages. It is authored from that Design Spec plus the page/resource/template context, not copied field by field from `result.json`. [Generate PPTX Step 6](../skills/ppt-master/workflows/generate-pptx.md#step-6-executor-phase) rebuilds a read-only `page-context` view before every page. The projector emits the stable anchors and current-page routing facts needed for authoring. Contextual tints, gradient/effect paints, and sparse non-structural display-font accents remain page decisions; recurrence or a stable semantic role requires an upstream lock role.
The view omits universal SVG/icon prohibitions already owned by the always-loaded Executor core and retains only project-specific forbidden rows. It selects images from the current page brief, explicit image-resource page assignments, and mirror prototype references. Images assigned elsewhere are excluded; any unresolved legacy image remains in a compatibility subset, and `confirmed-none` appears only when every locked image has a deterministic assignment elsewhere.
@@ -393,6 +393,28 @@ The tool refuses to back up: it relies on git for revert. Adding a backup mechan
---
+## Materials → Plan → Realization: the Kitchen Contract
+
+The cooking analogy is the canonical ownership model for generation, not just explanatory prose:
+
+| Restaurant | PPT Master | Authority |
+|---|---|---|
+| Customer and initial ingredients | User confirmation and supplied sources/assets | Defines facts, intent, exclusions, acquisition permissions, and how specific the requested outcome is |
+| Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart/layout keys, fonts, palette anchors, icons, and crop boundaries; readies the complete project-local inventory before execution |
+| Cook | Executor | Uses only the prepared inventory and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients |
+
+**Preparation has two clocks.** Topic Research, when triggered, may precede final confirmation because its facts are planning input. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates the icon inventory while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners.
+
+**Prepared inventory is the boundary.** A resource is available to Executor only when Strategist has selected it, recorded it in the planning artifacts, and made its project path resolvable or explicitly `Needs-Manual`. Merely existing elsewhere on disk does not authorize its use. Missing material returns upstream; Executor never searches, generates, downloads, syncs, or substitutes it.
+
+**Specificity controls freedom.** “Make Mapo tofu” fixes the result's identity: technique and presentation may vary, but tomato-and-eggs or tofu soup is a substitution. “Make a tofu dish” leaves an in-class choice. Strategist may resolve that choice; if the Design Spec deliberately leaves a dimension broad, Executor may realize it within that envelope. Once the Design Spec names a concrete choice, execution cannot reopen it.
+
+**Garnish remains local.** Sparse page-local font or color accents may add hierarchy, differentiation, or atmosphere without becoming a second visual system. Structural/recurring fonts, palette roles, resources, or patterns remain Strategist decisions and require an upstream Design Spec/lock update before reuse.
+
+**Prompt-refactor invariant.** Compression must preserve initial materials, user confirmation, Strategist-owned preparation, planning ownership, and execution freedom as separate layers. Moving acquisition into Executor, turning permission into quota, flexible realization into reselection, or an exact plan into an approximate target is a semantic regression. Runtime authority lives in [`strategist.md`](../skills/ppt-master/references/strategist.md) and [`executor-base.md`](../skills/ppt-master/references/executor-base.md); prompt-writing governance lives in [`prompt-style.md`](./rules/prompt-style.md).
+
+---
+
## Image Acquisition & Embedding
Several architectural decisions shape this phase:
@@ -424,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 the composition is declared *before* SVG generation, audited by `svg_quality_checker`, and survives session re-entry. Pushing composition onto Executor alone would lose it on context compression in long decks; encoding it in the spec_lock-adjacent resource list makes it a piece of the design contract.
+**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 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.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index be7bc0ea..ef70b645 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -373,7 +373,7 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
- `design_spec.md` —— 人类可读叙述;deck 的「为什么」(沟通意图、受众变化、叙事 / 模板 / 视觉理由、页面大纲)
- `spec_lock.md` —— 机器可读执行契约;包含紧凑的 `audience` / `objective` / `core_message` 沟通锚点,以及跨页稳定的身份/复用角色和路由值(核心 HEX/字体角色、图标库、图片资源与结构映射)
-为什么两份都要?`design_spec.md` 保存完整的确认方案与理由;`spec_lock.md` 只命名必须跨页稳定或参与路由的子集。它根据 Design Spec 与页面/资源/模板上下文编写,不再逐字段复制 `result.json`。[Generate PPTX Step 6](../../skills/ppt-master/workflows/generate-pptx.md#step-6-executor-phase) 会在每页生成前重建只读 `page-context` 视图,只输出稳定锚点与逐页路由事实。局部色阶、渐变/效果色与一次性的可导出展示字体属于页面判断;只有形成复用语义后才需要写入 lock。
+为什么两份都要?`design_spec.md` 保存完整的确认方案与理由;`spec_lock.md` 只命名必须跨页稳定或参与路由的子集。它根据 Design Spec 与页面/资源/模板上下文编写,不再逐字段复制 `result.json`。[Generate PPTX Step 6](../../skills/ppt-master/workflows/generate-pptx.md#step-6-executor-phase) 会在每页生成前重建只读 `page-context` 视图,只输出稳定锚点与逐页路由事实。局部色阶、渐变/效果色与零星的非结构性展示字体属于页面判断;一旦重复出现或形成稳定语义,就必须先提升为上游 lock 角色。
该视图省略 Executor core 已经恒定加载的通用 SVG/图标禁令,只保留项目专属 forbidden 行。图片从当前页 brief、图片资源表中的显式页分配和 mirror 原型引用中选择;已分配给其他页面的图片会被排除,仍无法归属的 legacy 图片保留在兼容子集中,只有所有锁定图片都能确定归属到其他页面时才记录 `confirmed-none`。
@@ -389,6 +389,28 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
---
+## 材料 → 规划 → 实现:餐厅合同
+
+“做饭”不是临时解释,而是生成流程的正式所有权模型:
+
+| 餐厅角色 | PPT Master 对应项 | 决策权 |
+|---|---|---|
+| 顾客与初始食材 | 用户确认与用户提供的原材料/素材 | 决定事实、意图、排除项、材料补充许可,以及要求具体到什么程度 |
+| 菜单策划与备料负责人 | Strategist、`design_spec.md`、`spec_lock.md` 及其负责的材料获取阶段 | 判断材料是否充分;补齐获准补充的事实;选定内容、资源、页面清单、图表/版式 key、字体、色板锚点、图标和裁剪边界;在执行前备齐项目级材料清单 |
+| 厨师 | Executor | 只使用已备材料,以几何、构图、层级、间距和视觉处理实现方案;不得改变所选“菜品”,也不得自行找料、换料 |
+
+**备料有两个时点。** Topic Research 被触发时可以早于最终确认,因为其中的事实是策略规划的输入。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证图标 inventory。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。
+
+**已备材料清单就是边界。** 只有被 Strategist 选定、写入规划产物,并且项目路径可解析或已明确标为 `Needs-Manual` 的资源,才对 Executor 可用。文件仅仅存在于其他目录并不构成使用许可。缺料必须返回上游;Executor 不得搜索、生成、下载、同步或替换资源。
+
+**具体程度决定自由度。** “做麻婆豆腐”锁定成品身份:火候、口感和摆盘可以发挥,但不能换成番茄炒蛋或豆腐汤。“做一道豆腐菜”则保留了品类内选择空间。Strategist 可以把这个开放要求收敛成具体方案;如果 Design Spec 有意保留某个维度的开放性,Executor 可以在该范围内实现。一旦 Design Spec 已经选定具体结果,执行阶段不得重新打开选择。
+
+**点缀只能保持局部。** 零星的页面级字体或颜色可以用于增加层级、区分和氛围,但不能发展成第二套视觉系统。结构性或重复出现的字体、色板角色、资源与 pattern 仍属于 Strategist 决策;复用前必须先更新 Design Spec/lock。
+
+**提示词重构不变量。** 压缩提示词时,必须继续区分初始材料、用户确认、Strategist 负责的备料、策略规划和执行自由。把材料获取下放给 Executor、把许可变成配额、把灵活实现变成重新选型,或把精确计划降级成近似目标,均属于语义回归。运行时权威位于 [`strategist.md`](../../skills/ppt-master/references/strategist.md) 与 [`executor-base.md`](../../skills/ppt-master/references/executor-base.md),提示词编写规则位于 [`prompt-style.md`](../rules/prompt-style.md)。
+
+---
+
## 图片获取与嵌入
这一阶段有多项架构层面的决策:
@@ -420,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——所以组合在 SVG 生成**之前**就被声明、被 `svg_quality_checker` 审计、并能在 session 重入后存活。把组合责任只压在 Executor 身上,长 deck 上下文压缩时就会丢;把它编码进 spec_lock 旁的资源列表,组合就成为设计契约的一部分。
+**为什么组合走 Strategist 资源列表,不只交给 Executor 临场发挥。** `§VIII 图片资源列表` 的 `Layout pattern` 列接受 `#<id> + #<id> ...` 表达式——Primary id 加可选 Modifier id——所以 Strategist 会在 SVG 生成前选定语义构图,并让这项决策在 session 重入后继续存在。Executor 负责实现方式,而不是重新选型:它可以根据真实图片比例和内容层级调整所选 pattern 的尺寸、位置、流向与权重,但必须保留选定 id、来源、素材、页面角色和裁剪边界。若要更换 pattern,必须先更新 Design Spec。
**为什么真正的硬约束留在上游。** 跨切的 SVG 创作与 PPTX 兼容性例外属于 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 路由的权威集。版式词表只指向该路由,不再复述合同;每条规则仍只有一个所属模块,词表里也不会留下过期副本。
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 7ba6eace..e99ac536 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -41,6 +41,10 @@ python3 skills/ppt-master/scripts/project_manager.py page-context <project_path>
`global` deliberately repeats the sub-1000-token cross-page anchor set; `lock_source.sha256` binds its version. These anchors preserve identity and recurring semantics but do not enumerate every legal color or font. `page_context` is the current §IX/resource/template/chart delta. For every `reference_set` entry—project/template Design Spec or selected prototype/chart SVG—reuse an in-context path + SHA; read it once only when absent or changed.
+**Hard rule — exact page roster**: `design_spec.md §IX` is the ordered queue: one final slide per entry, with the same id/order. The UI range no longer applies. Never add, drop, merge, split, or reorder; repair/reconfirm the Design Spec first.
+
+**Hard rule — selection vs realization**: use Strategist-selected content, resources/paths, chart/layout keys, core fonts, palette anchors, icons, and crop boundaries. Adapt realization, never selection, except sparse local font/color garnish allowed below. Missing or unresolved material stops execution and returns to Strategist-owned acquisition/failure recovery; never search, generate, download, sync, invent, or substitute it. Selection changes require upstream repair.
+
Use named lock roles literally when that role applies, and use optional `Template Application` from the retained Design Spec. Choose contextual page-local values from the Design Spec, style, content, and current composition rather than forcing every object into a lock row. The delta overrides neither facts nor constraints. After an approved change, rerun the command and reload only changed references. Deprecated `--bundle` is a compatibility no-op.
**Source facts**: The page delta carries page intent and routing facts, not the complete source corpus. Read the relevant `sources/` content and resolve listed `Fact IDs` from `sources/*.facts.json` when the page needs concrete claims, quotes, names, or data.
@@ -72,8 +76,8 @@ The §IX wording and sourced facts remain authoritative. Do not rewrite, drop, o
**Execution anchors and contextual values**:
- Icons MUST come from `icons.inventory`; library MUST equal `icons.library`
-- Core color roles in `colors` retain their confirmed meaning. Use them directly for recurring semantic roles. Page-local tints, gradient stops, shadow/glow paints, transparency composites, and one-off illustration colors may be chosen from context when they preserve the deck's visual identity, contrast, and semantic color behavior.
-- Structural title/body typography uses its declared role override (`title_family` / `body_family` / `emphasis_family` / `code_family`) or `font_family` fallback. A page-local display treatment may use another installed/export-safe family when the content and locked visual style justify it; promote it to a named `*_family` role only when it recurs.
+- Core color roles retain their meaning. Derive tints, shades, alpha, gradients, and effects; preserve natural asset colors; and use sparse page-local accents for differentiation/ornament. They must not become a competing or recurring palette.
+- Use declared role families or `font_family`. A sparse export-safe accent family may style short non-structural display/ornament only—never title/body/data/annotation. Recurrence requires upstream selection.
- Font sizes follow a ramp anchored on `typography.body`. Structural roles use their locked size deck-wide; recurring feature roles such as lead, pull quote, or hero number need their own lock slot. Never resize one role page by page or inherit a template placeholder size.
- **Core message ≥ `body`**: map the page's primary claim to locked `lead` / `subtitle`, never below body. Footnotes, page numbers, and credits use locked `footnote` / `annotation`; do not invent smaller sizes.
- **Write locked px verbatim, with at most two decimals.** Do not substitute familiar pt-style numbers or emit long precision tails.
@@ -81,7 +85,7 @@ The §IX wording and sourced facts remain authoritative. Do not rewrite, drop, o
- Images MUST reference files listed under `images`; no invented filenames
- Formula PNGs are images with `Acquire Via: formula`; place a `Rendered` file only from its listed path, use the normal placeholder for `Needs-Manual`, and never recreate the formula as text.
-When an intentional value becomes deck-wide or gains a recurring semantic role, extend `spec_lock.md` **before the next affected page**, regenerate that page's context, and use the named role thereafter. A genuinely page-local color, gradient/effect paint, or export-safe display family stays in the SVG and does not require a lock edit. Never expand the lock merely to silence the checker's informational anchor comparison. Icons, images, structural font roles, and recurring type sizes keep their explicit inventory/role rules.
+Return upstream before any derived/accent value becomes recurring or structural, then regenerate context. Local garnish needs no lock row. Never expand the lock to silence a comparison. Icons, images, structural fonts/sizes, and resources keep their inventory/role rules.
**Per-page layout rhythm — `page_rhythm` section**:
@@ -176,7 +180,7 @@ Examples: `01_封面.svg` / `02_目录.svg` / `03_核心优势.svg`; `01_cover.s
Strategist chooses the library and inventory; Executor only implements. Library details and one-library rule: [`../templates/icons/README.md`](../templates/icons/README.md). This section defines placeholder syntax.
-> **Resolution is project-first.** Strategist copied the chosen icons into `<project_path>/icons/<lib>/` (via `icon_sync.py`); `finalize_svg.py embed-icons` embeds from there, falling back to the global library per-icon. **Custom icons**: drop an `.svg` into `<project_path>/icons/<lib>/` (any `<lib>`, e.g. `custom/`) and reference it as `data-icon="<lib>/<name>"` — it embeds like any other. Reference only icons in the `spec_lock.md` inventory.
+> **Resolution is project-first.** Strategist copied the chosen icons into `<project_path>/icons/<lib>/` (via `icon_sync.py`); `finalize_svg.py embed-icons` embeds from there, falling back to the global library per-icon. Custom SVGs must already exist in the prepared project inventory under `<project_path>/icons/<lib>/`. Reference only icons in `spec_lock.md icons.inventory`.
> **Icon identifiers are case-sensitive filenames.** For bundled libraries, copy the verified lowercase basename exactly (`tabler-outline/award`, never `tabler-outline/Award`) into `spec_lock.md` and every `data-icon` value. Custom icon identifiers preserve the custom file's exact case; the pipeline never silently lowercases names.
@@ -211,49 +215,20 @@ Strategist chooses the library and inventory; Executor only implements. Library
>
> Icons are auto-embedded by `finalize_svg.py` — no need to run `embed_icons.py` manually.
-**Searching for icons** — use terminal, zero token cost:
+**Locked-id verification only**: verify the exact project-local file already named in `icons.inventory`:
```bash
-ls skills/ppt-master/templates/icons/chunk-filled/ | grep home
-ls skills/ppt-master/templates/icons/tabler-filled/ | grep home
-ls skills/ppt-master/templates/icons/tabler-outline/ | grep chart
-ls skills/ppt-master/templates/icons/phosphor-duotone/ | grep house
-ls skills/ppt-master/templates/icons/simple-icons/ | grep github
+test -f "<project_path>/icons/<lib>/<name>.svg"
```
-**Abstract concept → icon name** (names for `chunk-filled`; tabler libraries use their own equivalents — verify with `ls | grep`):
-
-| Concept | chunk-filled | tabler-filled / tabler-outline |
-|---------|-------|-------------------------------|
-| Growth / Increase | `arrow-trend-up` | same |
-| Decline / Decrease | `arrow-trend-down` | same |
-| Success / Complete | `circle-checkmark` | `circle-check` |
-| Warning / Risk | `triangle-exclamation` | `alert-triangle` |
-| Innovation / Idea | `lightbulb` | `bulb` |
-| Strategy / Goal | `target` | same |
-| Efficiency / Speed | `bolt` | same |
-| Collaboration / Team | `users` | same |
-| Settings / Config | `cog` | `settings` |
-| Security / Trust | `shield` | same |
-| Money / Finance | `dollar` | `currency-dollar` |
-| Time / Deadline | `clock` | same |
-| Location / Region | `map-pin` | same |
-| Communication | `comment` | `message` |
-| Analysis / Data | `chart-bar` | same |
-| Process / Flow | `arrows-rotate-clockwise` | `refresh` |
-| Global / World | `globe` | `world` |
-| Excellence / Award | `star` | same |
-| Expand / Scale | `maximize` | same |
-| Problem / Issue | `bug` | same |
-
-> For self-evident names (home, user, file, search, arrow, etc.) — just `grep chunk-filled/` directly without consulting the table.
-
-> ⚠️ **Icon validation**: only use icons from the Design Spec's approved inventory. Verify each via `ls | grep` before use. Mixing libraries within one deck is FORBIDDEN.
+**Missing locked icon** → return to Strategist's inventory / `icon_sync.py` gate. Do not search the global library, select an alternative, copy a candidate, or edit the lock in Executor.
+
+**Hard rule — icon inventory**: use only the Design Spec's approved inventory. Mixing stylistic libraries within one deck is FORBIDDEN.
---
## 5. Font Usage
-Structural typography anchors come from `spec_lock.md typography`. Use `font_family` as default; override recurring roles with `title_family` / `body_family` / `emphasis_family` / `code_family` if declared. Contextual one-off display type remains allowed under §2.1 when export-safe. LaTeX formulas that Strategist rendered are PNG images, not a `code_family` text role.
+Structural typography anchors come from `spec_lock.md typography`. Use `font_family` by default and declared role overrides when present. Sparse accent families follow §2.1; all structural text uses selected families. LaTeX formulas rendered by Strategist are PNG images, not a `code_family` role.
**Missing required field — `typography.font_family`** → stop and return to Generate Step 4 / [`strategist.md`](strategist.md) §6.2 to repair `spec_lock.md`; do not infer a stack from `design_spec.md`.
diff --git a/skills/ppt-master/references/executor-chart.md b/skills/ppt-master/references/executor-chart.md
index 08be54d4..2b162591 100644
--- a/skills/ppt-master/references/executor-chart.md
+++ b/skills/ppt-master/references/executor-chart.md
@@ -113,13 +113,14 @@ Chart SVGs referenced in **VII. Visualization Reference List** are loaded once t
**Hard rule**: adapt the loaded chart SVG; do not improvise from memory and do not replicate verbatim. Apply the active Design Spec and `spec_lock.md`; preserve the visualization type and data semantics.
**Adaptation rules**:
-- **Preserve**: visualization type (bar/line/pie/timeline/process/framework…), information relationships, data encoding, structural grouping, and capacity
+- **Preserve**: visualization type (bar/line/pie/timeline/process/framework…), information relationships, data encoding, and every content obligation in the active Design Spec
+- **Selected key, flexible realization**: keep the Strategist-selected chart key/type; its preview grouping, frame count, item count, capacity, and geometry are adaptable to the actual authored content
- **Carry forward**: every planned label, value, unit, status, source, and explanatory block; never shorten or drop content to imitate a lighter catalog preview
- **Adapt**: project data and labels, dimensions, axes, legend, and spacing as the authored content requires
- **Project-owned**: palette, typography, container treatment, effects, background, and page chrome; catalog preview values are fallbacks, never defaults
- **Bound final body modules**: add or revise root-coordinate `data-pptx-bounds` on every visible direct root `<g>` copied into the final page; nested groups need none, chart geometry and local references are not content-boundary inputs, and catalog reference warnings never waive the final-page contract
-- **Adjust with fidelity**: composition, axis ranges, and grid may change within the project contract only when no content, relationship, hierarchy, or capacity is lost
-- **Forbidden**: changing visualization type without spec justification; omitting data points or structural elements from the outline
+- **Adjust with fidelity**: composition, axis ranges, grouping, and grid may change when the actual content, relationships, hierarchy, and data encoding remain complete
+- **Forbidden**: changing visualization type without spec justification; omitting planned data points, labels, relationships, or explanatory content to fit the catalog preview
> Templates: `templates/charts/`. The Strategist's selected key is already locked in `page_charts`; execution opens only that key's SVG.
diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.md
index a2b78278..4427c0fb 100644
--- a/skills/ppt-master/references/executor-image.md
+++ b/skills/ppt-master/references/executor-image.md
@@ -21,12 +21,12 @@ Handle images by their status in the Design Spec's Image Resource List. Status e
**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).
-**Template-bundled images**: when a template (deck / layout / brand) is applied, its bitmaps are copied into the project's `images/` alongside every other runtime image ([`apply-template-workspace.md`](../workflows/stages/apply-template-workspace.md)). Reference them the same way — `../images/<name>` — and do **not** reproduce a template SVG's bare sibling href (e.g. `href="cover_bg.png"`): the template SVG is reference material, the rendered page lives in `svg_output/` and must point at `../images/`. `template_reuse_scope: mirror` ([`executor-structured.md`](./executor-structured.md) §1.1) is the one exception — it copies hrefs verbatim, and the exporter resolves those bare hrefs against `images/`.
+**Template-bundled images**: [`apply-template-workspace.md`](../workflows/stages/apply-template-workspace.md) copies them into project `images/`. Outside `mirror`, reference `../images/<name>` and never copy a template SVG's bare sibling href: the rendered page lives in `svg_output/`. `mirror` ([`executor-structured.md`](./executor-structured.md) §1.1) keeps hrefs verbatim; export resolves them against `images/`.
-Use each resource row's locked layout pattern; do not collapse image-led pages into a generic left/right split.
+**Selected pattern, flexible realization**: Preserve the row's primary/modifier ids and semantic composition. Adapt geometry, ratio, placement, spacing, and hierarchy for the actual page; never replace the pattern, role, file/source, must-use, or crop policy downstream. If another pattern is needed, return upstream to update the Design Spec. Only explicit user/template preservation locks exact geometry. Avoid generic left/right repetition.
**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 entries are croppable — default to `slice`.
+**`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.
**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/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.md
index a72d49bc..b17cd218 100644
--- a/skills/ppt-master/references/image-layout-spec.md
+++ b/skills/ppt-master/references/image-layout-spec.md
@@ -2,33 +2,33 @@
# Image Layout Specification
-Layout rules for pages where the image is placed **side-by-side with body text** as a container block. Strategist and Executor both follow these rules when the image's narrative intent is *side-by-side*.
+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.
-**Core principle (side-by-side)**: compute container layout from the image's original aspect ratio so the image displays completely — no excess whitespace, no cropping.
+**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.
-> **Scope**: this spec applies to *side-by-side* intent only. Other intents (hero / full-bleed, atmosphere / background, accent / inline) use full-bleed placement where ratio alignment is not a constraint and cropping is expected — the ratio→split table below does NOT apply. See `references/strategist-image.md` for intent selection.
+> **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).
---
## Layout Decision Flow
```
-1. Decide narrative intent (hero / atmosphere / side-by-side / accent) — see strategist-image.md
-2. If intent = side-by-side: continue below. Otherwise: compose per narrative; this spec does not apply.
-3. Get image original dimensions → Calculate ratio (width/height)
-4. Select layout type based on ratio
-5. Calculate maximum display size for the image
-6. Allocate remaining space for text area
-7. Fill results into the Design Specification's image resource list
+1. Read the selected narrative intent, hierarchy, and primary/modifier ids from Strategist's plan.
+2. If the selected pattern is not side-by-side or multi-image, this spec does not apply.
+3. Read the asset's `no-crop` boundary and original dimensions; calculate ratio (width/height).
+4. Use the tables as candidate structures, not an automatic selector.
+5. Calculate the image/text rectangles, then choose `meet` or focal-safe `slice` within the crop boundary.
+6. Revise geometry within the selected ids when the result weakens hierarchy, legibility, or required image content.
+7. Return upstream for a different pattern, resource, role, or crop boundary; Executor never rewrites selection.
```
-**When to run**: if image approach includes "B) User-provided", run the scan and populate the image resource list after the Strategist's confirmation stage and before content analysis / outlining.
+**When to run**: after `analyze_images.py` has produced current dimensions and a side-by-side or multi-image composition is under consideration. Skip this sizing reference for other page structures.
---
-## Layout Type Selection (side-by-side intent)
+## Layout Starting Points (side-by-side intent)
-| Image Ratio | Layout Type | Image Position | Description |
+| Image Ratio | Useful Starting Structure | Image Position | Description |
|-------------|-------------|----------------|-------------|
| > 2.0 (ultra-wide) | Top-bottom split | Top full-width | Image spans canvas width, height proportional |
| 1.5-2.0 (wide) | Top-bottom split | Top | Image width = content area width, height proportional |
@@ -36,7 +36,7 @@ Layout rules for pages where the image is placed **side-by-side with body text**
| 0.8-1.2 (square) | Left-right split | Left | Image takes content area height, width proportional |
| < 0.8 (portrait) | Left-right split | Left | Image height = content area height, width proportional |
-> Boundary ratio (e.g., 1.5): decide by text volume — more text → left-right; less text → top-bottom.
+> Boundary ratios are orientation cues, not thresholds. Let text volume, focal content, page hierarchy, and crop safety decide.
---
@@ -62,8 +62,8 @@ Image width = W = 1160 px
Image height = W / R = 1160 / R px
Text area height = H - image height - gap(20px)
-Validation: Text area height >= 150px (at least 3-4 lines of text)
-If not satisfied → Switch to left-right layout
+Review: if the remaining text area cannot carry the planned copy legibly,
+recompose as left-right or choose another layout pattern.
```
### Left-Right Layout Calculation
@@ -82,7 +82,7 @@ Image height = image width / R
Text area width = W - image width - gap(20px)
```
-**Validation**: Text area width >= 280px; otherwise reduce image area width.
+**Review**: if the remaining text area cannot carry the planned copy legibly, reduce the image area or choose another layout pattern.
---
@@ -116,7 +116,7 @@ Switch to left-right: image 780x446 (left), text area 360x600 (right) → 7:3 le
Default selection table assumes **landscape or square canvas**. For portrait canvases (height > width), left-right splits leave both columns too narrow — use the override below.
-| Canvas Orientation | Image Ratio | Recommended Layout | Reason |
+| Canvas Orientation | Image Ratio | Useful Starting Structure | Reason |
|-------------------|-------------|-------------------|--------|
| Portrait (Xiaohongshu, Story) | > 1.5 (wide) | Top-bottom | Same as landscape canvas |
| Portrait (Xiaohongshu, Story) | 1.2-1.5 (standard) | Top-bottom | Left-right too narrow on tall canvas |
@@ -165,20 +165,18 @@ Image positions:
(60, 390) 570x290 (650, 390) 570x290
```
-> Multi-image slides: use `preserveAspectRatio="xMidYMid meet"` on all images for consistent in-cell display.
+> Multi-image slides: decide `meet` or focal-safe `slice` per asset. Keep `no-crop` images complete; do not force every image into the same scaling mode merely for grid uniformity.
---
-## Prohibited Practices
+## Composition Checks
-| Prohibited | Correct Approach |
+| Check | Action |
|-----------|-----------------|
-| Fixed 50:50 or arbitrary ratios | Dynamic calculation based on image ratio |
-| Forcing wide image into square container | Use top-bottom layout or increase image area width |
-| Placing portrait image in narrow horizontal strip | Use left-right layout, image on left |
-| Image whitespace exceeding 10% | Recalculate layout or choose alternative approach |
-| Cropping key image content | Use `preserveAspectRatio="xMidYMid meet"` |
-| Text area too small to read | Ensure text area >= 150px (top-bottom) or >= 280px (left-right) |
+| 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 |
---
@@ -189,15 +187,15 @@ This spec only defines layout calculation. Write computed fields into the Image
| Field | Meaning |
|-------|---------|
| `Ratio` | Original image width / height |
-| `Layout plan` | Top-bottom / left-right / grid, including split ratio when relevant |
-| `Image area` | Computed display rectangle size |
-| `Text area` | Computed remaining text area size |
+| `Layout pattern` | Strategist-selected catalog pattern; semantic composition fixed, geometry flexible |
+| `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 |
For SVG `<image>` syntax, path rules, `preserveAspectRatio`, external refs, and Base64 embedding: see [`svg-image-embedding.md`](svg-image-embedding.md).
### SVG Image Embedding Examples
-Complete display (data charts, side-by-side — must not crop):
+Complete display (`no-crop` assets such as data charts):
```xml
<image href="../images/xxx.png"
@@ -205,7 +203,7 @@ Complete display (data charts, side-by-side — must not crop):
preserveAspectRatio="xMidYMid meet"/>
```
-Crop-to-fill (backgrounds and hero images only):
+Crop-to-fill (any untagged asset with a verified focal-safe crop):
```xml
<image href="../images/bg.png"
@@ -223,7 +221,7 @@ python3 scripts/analyze_images.py <project_path>/images --canvas ppt43 # PPT
python3 scripts/analyze_images.py <project_path>/images --canvas xiaohongshu # Xiaohongshu
```
-`--canvas` selects target format (default `ppt169`). The tool computes layout type (top-bottom / left-right), image display area, and text area per the formulas above. Output is a Markdown table — paste directly into the image resource list.
+`--canvas` selects target format (default `ppt169`). The tool computes a top-bottom / left-right candidate, image display area, and text area from the formulas above. Treat its output as planning input; record the composition actually selected for the page.
---
@@ -231,5 +229,5 @@ python3 scripts/analyze_images.py <project_path>/images --canvas xiaohongshu #
| Role | Responsibility |
|------|---------------|
-| **Strategist** | Run analyze_images.py, calculate layout per this spec, populate image resource list |
-| **Executor** | Strictly follow the layout plan and dimensions in the image resource list when generating SVGs |
+| **Strategist** | Run `analyze_images.py`, select the catalog pattern/resources, and record the crop boundary |
+| **Executor** | Realize the selected pattern for the actual asset/page while preserving its ids, role, source, must-use, and `no-crop` constraints |
diff --git a/skills/ppt-master/references/modes/_index.md b/skills/ppt-master/references/modes/_index.md
index b6e1ca5a..02587f33 100644
--- a/skills/ppt-master/references/modes/_index.md
+++ b/skills/ppt-master/references/modes/_index.md
@@ -20,7 +20,7 @@ Each mode has its own file with: narrative skeleton, page-structure tendencies,
> The five are **argument strategies, not a taxonomy of communication purposes**. A presentation may inform + align + request a decision at once; that composite intent stays as open prose in the Stage-1 communication contract. Stage 2 chooses the mode that best carries the dominant body-page spine, or one concrete `custom` act sequence when no preset can serve the stated priority / sequence.
>
-> **A mode is a lens, not a mandate over the user's own structure.** When the user brings their own outline, it is authoritative: transcribe it into `design_spec.md §IX` as given — page order and titles preserved — and let the mode govern only voice / register and page-internal treatment. A mode never reorders a user's pages or rewrites their given titles (mode is Reference-strength; a user-authored outline is exactly the override). When the user gives no structure, the mode does the structural lifting. To lay an outline out with the least reshaping, `briefing` imposes the lightest skeleton.
+> **A mode is a lens, not a mandate over an explicitly preserved structure.** Apply the confirmed `content_divergence` to a user-supplied outline. An ordinary source outline is a Reference that the mode may regroup, reorder, or retitle while preserving its facts and intended relationships. Preserve page order, titles, or wording only when the user presents the outline as the final page plan or explicitly requests that boundary. When the user gives no structure, the mode does the structural lifting. To keep reshaping light, `briefing` imposes the least skeleton.
---
diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.md
index 71eefb36..79e7b9ab 100644
--- a/skills/ppt-master/references/strategist-image.md
+++ b/skills/ppt-master/references/strategist-image.md
@@ -10,7 +10,7 @@ Conditional extension for formula assets, proposed / confirmed image elaboration
## 1. Proposed and Confirmed Image Plan
-Before Stage 2, use proposed sources only for candidate construction. After confirmation, discard candidate-only sources, map the confirmed set through [`strategist.md`](./strategist.md) §h, and honor every explicit role or page instruction in `image_notes`; this module never adds a source. The confirmed set is a production requirement, not a fresh candidate list: represent every confirmed non-`none` source at least once. Asset inventory and later aesthetic judgment may shape the unconfirmed count, subject, placement, and composition, but must not delete, substitute, or demote a confirmed source.
+Before Stage 2, use proposed sources only for candidate construction. After confirmation, discard candidate-only sources, map the confirmed set through [`strategist.md`](./strategist.md) §h, and honor explicit `image_notes` roles; this module never adds a source. The confirmed non-`none` set is an allowed acquisition boundary, not coverage: use a suitable subset and leave irrelevant sources unused. Explicit must-use sources, assets, or page roles remain required. Asset inventory and judgment determine unconfirmed count, subject, placement, and composition without substituting an unconfirmed source.
For illustration, apply this precedence: confirmed `none` → explicit user intent → the locked visual style's `Illus.` propensity (`core` / `supportive` / `sparse`) → none. Propensity controls the lean, not the source or a page quota. When illustration is active, prefer one coherent motif family across hero/section anchors and local spots, but only when the confirmed assets can form that family.
@@ -47,10 +47,10 @@ Follow `latex_render.py --help` for the manifest fields. The renderer writes dim
## 4. Image Resource List
-Add §VIII for every confirmed non-`none` source and selected formula; a formula-only plan contains only formula rows. 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 an asset is not yet available, retain its confirmed-source 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 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.
-🚧 **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. 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. 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.
-Choose narrative intent before dimensions: hero/full-bleed, atmosphere/background, side-by-side, or accent/inline. Only side-by-side containers follow native ratio; portrait and multi-image calculations belong to [`image-layout-spec.md`](./image-layout-spec.md). Most assets are croppable. Add `no-crop` in `spec_lock.md images` only for screenshots, charts, certificates/contracts, dense diagrams, and every formula; 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). 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`.
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.md b/skills/ppt-master/references/strategist.md
index 40682cfb..9cccc486 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -32,7 +32,7 @@ As a top-tier AI presentation strategist, receive source documents, perform cont
| **2 — complete deck solution** (authored once from the user's *actual* Stage 1) | reading mode (`delivery_purpose`, PPT only) · `d` mode + visual style · `b` page count · `e` color · `f` icon · `g` typography · `h` image source + generated-image rendering · conditional natural-language template application | derived from the confirmed contract; internal template exporter modes remain hidden |
| **3 — resources / production** (authored once from the user's *actual* Stage 1 + Stage 2) | formula policy · conditional AI-image acquisition path · generation mode · refine-spec toggle | derived from the confirmed solution |
-Do not force communication intent into one catalog label. A deck may report progress, expose risk, and request a decision in the same artifact; Stage 1 records that relationship in prose. Its editable prose fields are recommendation drafts, not required inputs: confirmation accepts the current text exactly, including blanks, and a cleared field must not be repopulated later. Stage 2 then confirms one complete solution: narrative spine, reading density, page budget, visual system, and image direction. When a template workspace is installed, Strategist also inspects its real prototypes and current content, presents one editable natural-language application plan, and keeps only exporter reuse/adherence values internal. Present ≥3 coordinated design directions (safe / shifted / bold) so color, type, icons, and generated-image rendering begin coherent; the user may still override each component. Generated images inherit the selected deck colors directly—there is no second image-palette confirmation. Stage 3 asks only how to produce the locked solution. **Page count is derived, not an anchor**—it follows content volume × desired audience outcome × reading mode. Author each stage once: same-stage edits update only visible browser state through documented deterministic dependencies and never trigger a new AI / backend recommendation. The launch / derive / wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; the item specs below keep their `a`–`h` letters.
+Do not force communication intent into one catalog label; Stage 1 records composite intent in prose. Editable prose fields are recommendation drafts, not required inputs: confirmation preserves current text and blanks; never repopulate a cleared field. Stage 2 confirms narrative spine, reading density, page budget, visual system, and image direction. With a template, inspect its actual prototypes/content, present one editable application plan, and keep exporter reuse/adherence internal. Present ≥3 coordinated safe / shifted / bold directions so color, type, icons, and generated-image rendering begin coherent; the user may override each component. Generated images inherit deck colors—there is no second image palette. Stage 3 covers production. Author each stage once; same-stage edits update only visible browser state through documented deterministic dependencies, without another AI/backend recommendation. Launch/derive/wait mechanics live in [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4; item specs keep `a`–`h`.
> **Execution discipline**: This is the last BLOCKING checkpoint in the pipeline. After confirmation, complete the Design Spec and proceed to image generation / SVG / post-processing without further pauses.
>
@@ -40,7 +40,21 @@ Do not force communication intent into one catalog label. A deck may report prog
> **Default presentation surface — Confirm UI.** Write `<project>/confirm_ui/recommendations.json` and launch per Generate Step 4. Stage 2 carries ≥3 safe / shifted / bold `design_directions`; each bundles visual style, a six-role HEX palette, CJK + Latin typography, icons, and conditional image rendering. Also print the recommendations + URL in chat as fallback context. Skip launch only for an explicit chat-only request; a chat-question tool is not a substitute. Generate Step 4 reads the final confirmed `result.json` once and retains that object for Design Spec authoring. [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns schema and lifecycle.
-> ⛔ **GATE — final confirmation is consumed once into the Design Spec.** Use the complete final object already read by Generate Step 4 (`stage: final`, `status: confirmed`); on a chat path, use the final visible confirmation summary as the equivalent retained state. Do not reopen `result.json` during normal Design Spec or lock authoring. Every explicitly present confirmed field is mandatory. Decide only details that remain unconfirmed. Never omit, delete, replace, narrow, weaken, reinterpret, or re-recommend a confirmed value because later analysis, asset inventory, template evidence, or personal judgment suggests another choice. Consume conditional fields according to their declared semantics, and preserve an explicitly cleared prose field as empty. If a confirmed value cannot be honored, keep the requirement visible and follow [`failure-recovery.md`](../workflows/governance/failure-recovery.md) instead of silently changing it.
+**Confirmed-value semantics**: confirmation preserves both the value and the owning field's semantic type. Apply the type to the affected property, not automatically to the whole object:
+
+| Type | Consumption |
+|---|---|
+| Literal requirement | Preserve the exact contracted value, pixels, wording, or topology. |
+| Semantic requirement | Preserve facts, relationships, intent, prohibitions, and completeness; expression may change. |
+| Identity anchor | Keep recurring identity stable without creating an exhaustive allowlist. |
+| Reference | Preserve the selected direction or role; adapt its realization to context. |
+| Permission / default | An allowed candidate/source boundary or preference; Strategist may leave it unused, with no quota. |
+
+**Authority chain — materials → Strategist preparation → realization.** User inputs set materials/acquisition bounds. Strategist owns sufficiency, gap-filling, and selection: roster/content, resources, chart/layout keys, fonts, palette anchors, icons, and crop bans. Fact research may precede confirmation; AI/web/slice follows final confirmation plus completed §VIII/lock; icons are synced/validated during authoring. Before Executor, each resource has a path and terminal/`Needs-Manual` state. Executor owns geometry, composition, hierarchy, spacing, treatment; it never searches, generates, syncs, invents, or substitutes resources. Missing material/reselection returns upstream. Specificity defines freedom; References flex realization, never selection.
+
+Explicit *must*, *only*, *exactly*, *verbatim*, *do not*, or `no-crop` wording may strengthen only the named property into the appropriate Literal or Semantic requirement. Accepting an AI recommendation keeps the field's default type; it does not promote a Reference or Permission into a Literal requirement.
+
+> ⛔ **GATE — final confirmation is consumed once into the Design Spec.** Use the complete final object already read by Generate Step 4 (`stage: final`, `status: confirmed`); on a chat path, use the final visible confirmation summary as the equivalent retained state. Do not reopen `result.json` during normal Design Spec or lock authoring. Consume every explicitly present field according to the semantics above and its field owner. Do not omit or substitute a value, and do not silently strengthen or weaken its type. Decide only details left unconfirmed; preserve an explicitly cleared prose field as empty. If a confirmed requirement cannot be honored, keep it visible and follow [`failure-recovery.md`](../workflows/governance/failure-recovery.md) instead of silently changing it.
### a. Canvas Format Confirmation
@@ -48,7 +62,7 @@ Recommend format based on scenario (see [`canvas-formats.md`](canvas-formats.md)
### b. Page Count Confirmation
-**Stage-2 (derived).** Page count is not an anchor—recommend it only after the Stage-1 communication contract is confirmed and alongside reading mode. Derive it from source volume, desired audience outcome, delivery context / artifact afterlife, and reading mode (`text` packs denser; `presentation` is one-idea-per-page and may need more). The user's confirmed count still wins.
+**Stage-2 planning input.** Confirm UI may hold an approximation/range; *exactly*, *1:1*, or preservation fixes it. After Stage 1, choose one exact count from source volume, audience outcome, delivery context/afterlife, and reading mode, then author the complete §IX roster. After Gate 1, that roster's ids, count, and order—not the earlier UI wording—are invariant. Executor cannot add, drop, merge, split, or reorder pages; changes first repair or reconfirm the Design Spec.
### c. Communication Contract Confirmation
@@ -110,7 +124,7 @@ Two independent layers, each locks one preset or `custom`. Output: `d. Mode: <mo
The deck's **narrative + persuasion skeleton** — how the argument is organized and advanced. Lock one preset from `pyramid` / `narrative` / `instructional` / `showcase` / `briefing`, or `custom` with behavior.
**Source**:
-- User supplied their own outline / structure → it is authoritative. Transcribe it into `§IX` as given (page order + titles preserved); still lock a mode, but for register / voice and page-internal treatment, **not** to reshape — never reorder the user's pages or rewrite their given titles. Note in `design_spec.md` that the structure is user-authored. `briefing` imposes the least if no particular "讲法" is intended.
+- User supplied their own outline / structure → preserve its facts and intended relationships, then apply the confirmed `content_divergence`. Treat an ordinary source outline as a Reference: regroup, reorder, or retitle when the communication contract benefits. Treat it as authoritative only when the user presents it as the final page plan or explicitly asks to preserve page order, titles, or wording; record that promoted boundary in `design_spec.md`. Still lock a mode for register, voice, and any permitted reshaping. `briefing` imposes the least if no particular "讲法" is intended.
- Beautify / re-layout profile ([`beautify-pptx.md`](../workflows/profiles/beautify-pptx.md)) → the extracted source content is authoritative and **verbatim**, one step stricter than the user-outline case above. Each source slide becomes exactly one `§IX` page in source order; transcribe every content block word-for-word — never reshape / re-primary / condense / merge / split / reword. Lock `mode: briefing`; color (e) and typography (g) are whatever the user confirmed in the beautify plan — the source identity (theme or observed) by default, or a content / brand-aware alternative the beautify plan offered and the user picked — locked as truth (the beautify plan already ran the recommendation through the confirm UI, so do not re-recommend here). Charts / tables / images are regenerated from their extracted data in the inherited style (route chart/table data to §VII, pictures to §VIII) — data values stay frozen, the rendering is the deck's own; never carried over verbatim. Layout, hierarchy, rhythm, and visual rendering are what gets redesigned.
- A bespoke direction the five don't give — a nameable cadence (dialectic 正反合, myth-vs-reality, countdown, Socratic), a multi-act fusion of modes, or the user's own feel (confrontational here, detached there). Either the user asks, **or you recommend it** when a fusion / bespoke direction genuinely serves the deck better than a single preset (a recommendation the user confirms, like every lock). The *kind* doesn't matter → `mode: custom` + a `mode_behavior:` paragraph that **crystallizes the intent** (act sequence or posture shifts, title voice, page rhythm, register) concretely enough for the Executor to follow per page; it reads only `spec_lock.md`, never the chat. If the direction uses existing modes, read every corresponding `modes/<id>.md` before synthesis and retain those exact ids as its catalog basis; if it is genuinely new, do not invent a basis. One deck locks **one** value — a fusion is one `custom` describing the acts, never several modes. Avoid only the *dodge*: don't default to `custom` when a preset genuinely fits, and prefer a dominant mode + page-level variation when one mode leads.
- No user structure or cadence → recommend from the confirmed `communication_intent`, `audience_outcome`, source texture, and delivery context using the index's auto-selection table. Composite intent does not automatically require `custom`: choose the dominant spine of the body pages when one exists; use a concrete `custom` act sequence only when no single spine can serve the stated priority / sequence. Present as a recommendation; the user may override.
@@ -208,7 +222,7 @@ See [`../templates/icons/README.md`](../templates/icons/README.md) for the curre
- User or active template typography is authoritative. Otherwise present two coherent choices: one concord (safe) and one contrast (more tension). Do not pair title/body families that are merely near-duplicates.
- Every Stage-2 direction carries `heading` / `body` `cjk`, `latin`, `css`, and positive `body_size`; repeat user/template-fixed stacks.
-- Exported faces must resolve to fonts available in PowerPoint. Safe anchors are CJK `Microsoft YaHei` / `SimHei` / `SimSun` / `FangSong` / `KaiTi`; Latin sans `Arial` / `Calibri` / `Segoe UI`; Latin serif `Times New Roman` / `Georgia` / `Cambria`; mono `Consolas`; display `Impact` / `Arial Black`.
+- Exported faces must resolve to fonts available in PowerPoint. Safe anchors are CJK `Microsoft YaHei` / `SimHei` / `SimSun` / `FangSong` / `KaiTi`; Latin sans `Arial` / `Calibri` / `Segoe UI`; Latin serif `Times New Roman` / `Georgia` / `Cambria`; mono `Consolas`; display `Impact` / `Arial Black`. Executor may sparsely use another export-safe family on short non-structural display/ornament; never on title/body/data/annotation roles. Recurrence requires upstream selection.
- Keep each stack to four families or fewer. A non-installed brand or web face is legal only when the Design Spec explicitly records the install / embed requirement and a safe substitute.
- Avoid splitting roles across near-equivalents such as YaHei↔PingFang, SimSun↔Songti, Arial↔Helvetica↔Segoe UI, or Times New Roman↔Times. A cross-platform counterpart may remain inside one fallback stack.
- Choose by the locked style: serif for editorial / data-journalism, display weight for brutalist / poster directions, KaiTi or FangSong for ink character, mono accents for dark-tech / blueprint, and restrained sans for swiss-minimal / soft-rounded.
@@ -333,7 +347,7 @@ Read the relevant `_index.md` at confirmation `d` (Layer 1 / Layer 2) for its ca
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.
-Lock the stable role set the deck already needs, including recurring neutrals such as `surface`, `grid`, `scrim`, `overlay`, or `block-shade`. Treat these rows as identity and reuse anchors, not an exhaustive color allowlist. Executor may derive or choose contextual paints for gradients, effects, illustrations, and one-off page expression while preserving the confirmed palette's character and contrast. For data semantics, add reusable positive / warning / negative roles when they recur; do not scatter unrelated accents.
+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.
---
@@ -385,7 +399,7 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck
Generate Step 4 owns both artifact scaffolds. `design_spec.md` is the Strategist's complete human-readable design decision; `spec_lock.md` is the context-selected execution subset and routing contract. Author them in that order. `result.json` is read once into the active final-confirmation state and consumed completely while writing the Design Spec. Never reopen it to author the lock, and never treat the two planning files as parallel interpretations of the confirmation.
1. Use the retained complete final-confirmation state already read once by Generate Step 4.
-2. Write the full `design_spec.md` from that state plus source analysis and current project context. Record the confirmed production mechanics in §I so later stages never need to reopen `result.json`. In §IX, each page carries layout, title, one core message, an **Audience move**, final content wording, applicable visualization/image references, `Fact IDs` for sourced claims, and `Data class: scenario` for invented demonstration data.
+2. Write `design_spec.md` from that state, source analysis, and project context; record production mechanics in §I. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, final wording, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1, roster ids/count/order and content are authoritative; layout, cover/closing composition, and image/chart patterns remain References unless promoted.
3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before creating `spec_lock.md`.
4. Author `spec_lock.md` from the completed Design Spec plus the current execution context: retain confirmed identity anchors, select stable cross-page roles and routing values, and omit page-local values that need no reusable name. This is implementation judgment, not a second user-facing recommendation.
@@ -394,21 +408,21 @@ Generate Step 4 owns both artifact scaffolds. `design_spec.md` is the Strategist
| Confirmed state | Required Design Spec realization |
|---|---|
| Communication contract and `content_divergence` | §I records the confirmed contract; §IX realizes every stated purpose, outcome, priority, and source-treatment constraint |
-| Canvas, reading mode, and page count | §I–II record the confirmed values; §IX page count and page grammar obey them |
-| Mode, visual style, palette, and generated-image rendering | §I and §III record the selected direction exactly and use it throughout the layout and visual plan |
+| Canvas, reading mode, and page count | §I records the confirmed input and exact resolved count; §IX contains that many ordered pages. Executor produces exactly one output slide per entry, in order |
+| Mode, visual style, palette, and generated-image rendering | §I and §III record the selected direction as identity anchors; named core roles stay stable while page-local expression remains contextual |
| Typography, including every visible role size | §IV records the confirmed families and exact `body`, `title`, `subtitle`, and `annotation` values; never re-derive a confirmed size |
| Icons | §VI uses the confirmed library or confirmed no-icon/custom path |
-| Every confirmed non-`none` image source, `image_notes`, and AI strategy | §VIII contains at least one matching resource row per source; explicit page roles and intent appear in §VIII and the affected §IX pages |
+| Confirmed image-source set, `image_notes`, and AI strategy | §VIII uses only permitted sources and includes every explicitly required source, asset, or page role; a permitted but unused source needs no row |
| Natural-language template application | §I records it and the relevant layout/prototype choices realize it without silently dropping a requested use or exclusion |
| Formula policy, AI-image acquisition path, generation mode, refine-spec toggle | §I records them as production mechanics; their owning Generate stage consumes the Design Spec, and formula policy also shapes §VIII when formula-worthy content exists |
-⛔ **GATE 1 — confirmation fidelity.** Do not create or fill `spec_lock.md` until the complete Design Spec has passed the field-by-field comparison above. A missing, changed, substituted, or weakened confirmed value blocks Step 4 even when the Design Spec schema validates. Schema validity proves structure, not fidelity to the user's decision.
+⛔ **GATE 1 — confirmation fidelity.** Do not create or fill `spec_lock.md` until the complete Design Spec has passed the field-by-field comparison above. A missing or substituted value, or a silently strengthened/weakened semantic type, blocks Step 4 even when the Design Spec schema validates. Adapting a Reference within its owner-defined bounds or leaving an unused Permission unmaterialized is not a fidelity failure. Schema validity proves structure, not fidelity to the user's decision.
⛔ **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` is the compact context-authored contract for communication execution, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Project every recurring typography size into its named role; do not collapse a confirmed `subtitle` or `annotation` value back into a derived default. Keep confirmed title/body families and core palette roles stable, while leaving contextual gradient/effect paints and one-off export-safe type choices to page authoring. Project every §VIII image row with its acquisition source so downstream routing cannot infer a different one. Do not copy planning-only context or decision provenance into the lock. Free-design, brand-only, and `template_reuse_scope: style` routes write `pptx_structure.mode: flat`; the conditional template module owns every structured mapping. Executor rebuilds the lock's current-page projection before every page (see [executor-base.md](executor-base.md) §2.1). Never repair the Design Spec from the lock; repair the Design Spec from the retained final-confirmation state, then re-author the 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 §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.
-**Contextual extension during execution**: a page-local color, gradient stop, effect paint, or export-safe display family may remain only in that SVG when its use is genuinely local. If the same value acquires a recurring semantic role across pages, add one named row to `spec_lock.md` before the next affected page and regenerate page-context. This reverse lock update is legitimate consolidation, not a checker workaround; never add one-off values merely to silence an informational comparison.
+**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.
- **Communication trace is mandatory**: Keep the full confirmed communication contract in `design_spec.md §I`, then project only `audience`, `objective`, `core_message`, and canonical `consumption_mode` into `spec_lock.md communication`. Write `objective` as one concise execution sentence that preserves both the confirmed `communication_intent` and the success condition in `audience_outcome`; do not copy `delivery_context`, `artifact_afterlife`, dates, provenance, or conflict-resolution commentary into the lock. Before finalizing §IX, check that every named purpose has at least one outline obligation and **every Slide block**, including cover / divider / closing pages, has an `Audience move` that advances the global outcome. A page that advances no purpose or outcome should be merged, rewritten, or cut. `project_manager.py validate` and `svg_quality_checker.py` enforce the compact lock fields and per-page move presence, not their subjective quality.
- **Custom behavior is concise and executable**: For confirmed `custom` mode or visual style, project one resolved `mode_behavior` / `visual_style_behavior` sentence or short paragraph. When the direction actually combines or borrows catalog entries, also project the exact, comma-separated `mode_references` / `visual_style_references`; omit the field for a genuinely novel direction and never fabricate a nearby reference. Preserve the confirmed direction, reference locked role names such as `colors.primary` when needed, and omit selection history, contradictions, precedence explanations, or other Design Spec provenance. Page-context carries these fields directly to Executor.
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index 75d74664..2fa1708f 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -52,9 +52,9 @@ pip install flask
- **Enumerable + custom** — canvas / icons retain blank manual inputs; mode / visual_style instead show a mandatory AI-authored proposal in full, initially unselected and editable after selection. Selected mode / style writes literal `custom` plus its behavior sibling.
- **Visual examples for hard-to-name choices** — the full-screen confirmation page loads real SVG page samples from `static/style_previews/` for `visual_style`, and renders real sample SVGs from `templates/icons` for `icons`. These thumbnails make style and icon-library choices visually comparable before the user locks them. Preview copy is fixed role text (big title / section title / body / points), not project content from `recommendations.json`, so users compare visual treatment rather than copywriting. These previews are a confirmation aid only: they do not add fields to `recommendations.json` or `result.json`, and they do not replace the later Step 6 live preview.
-- **Image usage multi-select** — image sources are selected as one or more catalog ids: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. `none` is exclusive. Recommendation and result values may be a legacy single string, but new files should use an array. When several sources are recommended, write the source ids to `recommend.image_usage` and write the actual usage strategy to `image_notes`, not a custom prose value.
+- **Image usage multi-select** — image sources are selected as one or more catalog ids: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. `none` is exclusive. A confirmed non-`none` set is the allowed acquisition-source boundary, not a requirement to use every selected source; only explicit `image_notes` wording can require a source, asset, or page role. Recommendation and result values may be a legacy single string, but new files should use an array. When several sources are recommended, write the source ids to `recommend.image_usage` and write the actual usage strategy to `image_notes`, not a custom prose value.
- **Closed enumerable** — PPT reading mode (`delivery_purpose` compatibility key), formula policy / generation mode / refine spec, plus AI source only when image usage includes `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option.
-- **Open prose** — `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, `content_divergence`, and `page_count`. `communication_intent` may carry several purposes plus priority / sequence; common paths appear only as help text. `content_divergence` remains a separate source-treatment axis.
+- **Open prose** — `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, `content_divergence`, and `page_count`. `communication_intent` may carry several purposes plus priority / sequence; common paths appear only as help text. `content_divergence` is the source-treatment axis. `page_count` may be a range here; Strategist resolves the exact §IX roster, leaving Executor no pagination latitude.
- **Coordinated generative directions** — `design_directions` carries ≥3 safe / shifted / bold candidates. Each candidate bundles visual style, color, typography, icon id, and conditional generated-image rendering. The page can still render legacy top-level `color`, `typography`, and `image_strategy` candidates, but new staged recommendations use the coordinated bundle.
AI-authored custom proposals apply only to mode, visual style, and conditional AI-image rendering; a selected proposal cannot be blank. Color / typography keep their existing manual Custom cards. Image usage uses source ids plus `image_notes`; closed sets have no Custom path.
@@ -256,10 +256,10 @@ After Stage 2 is confirmed, overwrite it with Stage-3 production recommendations
The shape above is final. Selected custom values use `mode: custom` + `mode_behavior`, `visual_style: custom` + `visual_style_behavior`, or `image_strategy.rendering: custom` + `behavior`. During Design Spec and lock authoring, Strategist projects optional `mode_references`, `visual_style_references`, or `image_rendering_references` only when that confirmed behavior actually uses named catalog sources; genuinely novel custom behavior has no reference list. Intermediate writes retain accumulated fields; legacy tier names remain read-compatible.
-**Final-result consumption contract.** A final result is the user-confirmed input contract for the Strategist's Design Spec, not another recommendation input. After the final wait, Generate Step 4 reads the complete final object exactly once and retains it while Strategist writes and audits `design_spec.md` against every explicitly present field. Normal lock authoring and downstream execution do not reopen `result.json`; the completed Design Spec is the durable authority. Only after that audit passes does Strategist author `spec_lock.md` from the Design Spec plus current execution context, selecting stable anchors and routing rather than copying every field or enumerating every legal color/font. It must not omit, substitute, narrow, weaken, reinterpret, or re-recommend a confirmed value. If one value cannot be honored, the owning workflow reports or pauses under failure recovery; it never deletes the requirement to keep the pipeline moving.
+**Final-result consumption contract.** A final result is the user-confirmed input contract for the Strategist's Design Spec, not another recommendation input. After the final wait, Generate Step 4 reads the complete final object exactly once and retains it while Strategist writes and audits `design_spec.md` against every explicitly present field. Normal lock authoring and downstream execution do not reopen `result.json`; the completed Design Spec is the durable authority. Only after that audit passes does Strategist author `spec_lock.md` from the Design Spec plus current execution context, selecting stable anchors and routing rather than copying every field or enumerating every legal color/font. Every value must be consumed at the semantic type owned by [`strategist.md`](../../references/strategist.md) §1 and its field owner: do not omit or substitute it, and do not silently strengthen or weaken its type. If a confirmed requirement cannot be honored, the owning workflow reports or pauses under failure recovery; it never deletes the requirement to keep the pipeline moving.
- Bespoke mode / style prose lives only in the required behavior sibling; image custom prose lives in `image_strategy.behavior`. Canvas / icons retain free-text edge cases, color / typography retain `name: "custom"`, and image usage remains a source-id array plus `image_notes`.
-- `image_ai_path` and `image_strategy` appear only with `image_usage: ai` and remain confirmed downstream. The page is default; explicit/failure chat fallback keeps identical fields. `image_ai_path` selects the Step 5 path, and [`strategist-image.md`](../../references/strategist-image.md) §2 locks the chosen strategy verbatim.
+- `image_ai_path` and `image_strategy` appear only with `image_usage: ai` and remain confirmed downstream. The page is default; explicit/failure chat fallback keeps identical fields. `image_ai_path` selects the Step 5 path, and [`strategist-image.md`](../../references/strategist-image.md) §2 retains the selected rendering or custom behavior as the deck-level image identity anchor; individual prompts still adapt subject, composition, and atmosphere within it.
- After the user clicks the **final Confirm** (Stage 3, or single-pass), the page saves `result.json` and shuts the server down (auto-close). Stage-1 **Confirm contract & continue** and Stage-2 **Confirm solution & continue** keep the page open while it polls for the once-authored downstream stage. In the default flow, the first `--daemon --wait` returns on the stage-1 result, `--wait-only --wait-stage stage2` returns on the stage-2 result, and the final `--wait-only` returns on the final result; the AI reads each immediately — no extra chat confirmation is required. Chat fallback shows the same initially-unselected custom proposals. Either way, Step 4 ends with a `--shutdown` cleanup so a never-confirmed page cannot keep holding port 5050 ahead of the Step 6 live preview.
## Scope
diff --git a/skills/ppt-master/templates/charts/README.md b/skills/ppt-master/templates/charts/README.md
index 05e9bac0..5bafa133 100644
--- a/skills/ppt-master/templates/charts/README.md
+++ b/skills/ppt-master/templates/charts/README.md
@@ -10,7 +10,7 @@ For one planned page, provide 3-8 English semantic content-shape tags, then insp
## Authoring contract
-[`CHART_STYLE_GUIDE.md`](./CHART_STYLE_GUIDE.md) owns readable standalone SVG, semantic and structural fidelity, root-group bounds, data encoding, and neutral previews. The active Design Spec and `spec_lock.md` own final palette, typography, containers, effects, and chrome. Preview styling is adaptable, but visible content and frames that express real grouping, hierarchy, or capacity remain authoritative until the template is fully migrated and reviewed.
+[`CHART_STYLE_GUIDE.md`](./CHART_STYLE_GUIDE.md) owns readable standalone SVG, semantic and structural fidelity, root-group bounds, data encoding, and neutral previews. The active Design Spec and `spec_lock.md` own final palette, typography, containers, effects, and chrome. The reference preserves visualization semantics; its preview styling, example frames, grouping implementation, item count, and capacity are adaptable to the actual authored content.
## Visualization output model
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 3994e198..8665b70e 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -28,7 +28,7 @@ The command refuses to shadow any recognized existing design-spec artifact, incl
| 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 |
-| IX. Content Outline | Ordered Slide blocks; each has `Audience move` | Page-specific facts, charts, images, and template mappings |
+| 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 | — |
**Hard rule**: Keep all ten `##` headings, even when §VII or §VIII contains no rows. Do not add a second schema description inside the project artifact.
diff --git a/skills/ppt-master/templates/scaffolds/design_spec.md b/skills/ppt-master/templates/scaffolds/design_spec.md
index 7b289707..21b0b9fe 100644
--- a/skills/ppt-master/templates/scaffolds/design_spec.md
+++ b/skills/ppt-master/templates/scaffolds/design_spec.md
@@ -7,7 +7,7 @@
| --- | --- |
| Project Name | {{PROJECT_NAME}} |
| Canvas Format | {{CANVAS_NAME}} ({{CANVAS_DIMENSIONS}}) |
-| Page Count | [fill] |
+| Page Count | [fill exact final count matching §IX] |
| Target Audience | [fill] |
| Communication Intent | [fill] |
| Desired Audience Outcome | [fill] |
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 094dd6d2..009bdbf1 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -200,7 +200,7 @@ The core first chooses the proposed Stage 2 source ids. Load the image module be
If 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 a user-owned Design Spec requirement. The Strategist may autonomously elaborate only unconfirmed implementation details; it must not omit, delete, substitute, narrow, weaken, reinterpret, or re-recommend a confirmed value. 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, every confirmed image source, and explicit `image_notes` role. 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 one confirmed value 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, 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:
@@ -251,7 +251,7 @@ After filling the lock, compare its identity anchors and routing values against
- [x] Split-mode note appended below the confirmation fields (heavy or normal variant)
- [x] Spec-refinement opt-in line appended (default OFF; only the user's explicit request enters the refine-spec stage)
- [x] Design Specification & Content Outline generated
-- [x] Gate 1 passed: Design Spec preserves every confirmed value
+- [x] Gate 1 passed: Design Spec preserves every confirmed value at its owner-defined semantic type
- [x] Execution lock (`spec_lock.md`) authored from the completed Design Spec + current context as stable anchors/routing, not an exhaustive value whitelist
- [x] Communication trace validated: Design Spec retains the contract; the lock has compact `audience` / `objective` / `core_message` fields (plus PPT `consumption_mode`); every §IX Slide has an `Audience move`
- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase
@@ -263,7 +263,7 @@ After filling the lock, compare its identity anchors and routing values against
🚧 **GATE**: Step 4 complete; `<project_path>/design_spec.md` and `<project_path>/spec_lock.md` both exist. If either required artifact is missing, stop before any acquisition or generation and follow [`failure-recovery.md`](governance/failure-recovery.md) §3. Formula rows already have `Acquire Via: formula` and status `Rendered` or `Needs-Manual`.
-> **Trigger**: At least one row in the resource list has `Acquire Via: ai`, `web`, and/or `slice`. If every row is `user`, `formula`, or `placeholder`, skip to Step 6. If the completed Design Spec records `ai` or `web` acquisition intent without a matching §VIII resource row, the Design Spec is incomplete; return to Step 4 Gate 1, repair it from the retained final state, and re-author the affected lock anchors from context. Do not reopen `result.json` during this check.
+> **Trigger**: At least one row in the resource list has `Acquire Via: ai`, `web`, and/or `slice`. If every row is `user`, `formula`, or `placeholder`, skip to Step 6. A permitted but unused image source creates no row and does not trigger acquisition. If §VIII omits a source, asset, or page role that `image_notes` explicitly requires, the Design Spec is incomplete; return to Step 4 Gate 1, repair it from the retained final state, and re-author the affected lock anchors from context. Do not reopen `result.json` during this check.
**Failure recovery**: stop/continue behavior for AI/web/slice/image-readiness failures is defined in [`workflows/governance/failure-recovery.md`](governance/failure-recovery.md). This Step keeps the acquisition procedure.
@@ -328,6 +328,8 @@ Workflow:
🚧 **GATE**: Step 4 (and Step 5 if triggered) complete; all prerequisite deliverables are ready.
+**Exact page roster**: render `design_spec.md §IX` one-for-one, in order. Any add/drop/merge/split/reorder requires Spec repair/refinement first.
+
**Artifact ownership**: `svg_output/` is the author source, `svg_final/` is derived, and image facts come from the regenerated `analysis/image_analysis.csv`; see [`references/artifact-ownership.md`](../references/artifact-ownership.md).
Read the execution references for this deck's locked `mode` + `visual_style` (from `spec_lock.md`):
@@ -419,7 +421,7 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final
- [x] Live preview started before the first SVG and kept available at the reported URL
- [x] P01 gate passed; remaining pages authored without checker calls
- [x] Each failing checker run was reviewed as one complete issue set and followed by one consolidated edit pass; checker output was not filtered
-- [x] All SVGs generated to svg_output/
+- [x] `svg_output/` matches the ordered §IX roster exactly, one SVG per planned page
- [x] Every wrapped prose paragraph uses one `<text>` frame with `<tspan>` line breaks
- [x] svg_quality_checker.py passed (0 errors)
- [x] Speaker notes generated at notes/total.md