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

fix(execution): reuse valid planning context across pages

hugohe34366a7bff87f
diff --git a/docs/rules/prompt-style.md b/docs/rules/prompt-style.md
index 0cf8877a..3596c290 100644
--- a/docs/rules/prompt-style.md
+++ b/docs/rules/prompt-style.md
@@ -74,8 +74,7 @@ Begin substantive paragraphs with a bolded short label. Reuse this fixed vocabul
✅ Good (from `executor-base.md`):
```
-**Hard rule**: Before generating **each** SVG page, run:
-`python3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> --record-usage`.
+**Hard rule**: Reuse the complete Design Spec and lock while the active context remains valid. After compaction or fresh/resumed execution, read both once before continuing.
**Forbidden — unresolved asset references**:
- Icons MUST resolve to prepared project-local assets
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 347149b9..a7d4e3d6 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -165,17 +165,14 @@ analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spe
analysis/image_analysis.csv ────┘
design_spec.md + spec_lock.md + images/ + icons/ + templates/
- └─> project_manager.py page-context <project> P<NN>
- + [bounded repeated anchor set]
- + [current-page delta]
- + [Design Spec / prototype / chart path + SHA fingerprints]
- ├─> Executor -> svg_output/
- │ ├─> unchanged large references stay in the active context
- │ ├─> svg_quality_checker.py -> validation/svg_quality_report.json
- │ ├─> finalize_svg.py -> svg_final/
- │ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx + validation/<output_stem>.report.json
- │ backup/<ts>/svg_output/
- └─> --record-usage -> analysis/page-context/P<NN>.usage.json
+ └─> Executor -> svg_output/
+ ├─> planning artifacts/references stay in the valid active context
+ ├─> project_manager.py page-context <project> P<NN> [on demand]
+ │ └─> --record-usage -> analysis/page-context/P<NN>.usage.json
+ ├─> svg_quality_checker.py -> validation/svg_quality_report.json
+ ├─> finalize_svg.py -> svg_final/
+ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx + validation/<output_stem>.report.json
+ backup/<ts>/svg_output/
Direct OOXML routes:
analysis/<stem>.slide_library.json + source PPTX + fill_plan.json
@@ -276,8 +273,9 @@ These invariants are stronger than ordinary implementation preferences. If a cha
|---|---|
| `sources/` content-type files are the main-pipeline content contract | text, tables, and chart values come from content-type files in `sources/` (Markdown is primary, but `.txt` / `.csv` / `.json` / `.yaml` / … count too); known sidecars (`*.conversion_profile.json`, `*_files/image_manifest.json`) are excluded |
| `analysis/` stores machine facts, not design contracts | `source_profile.json` and intake artifacts inform Strategist; they do not lock page count/order except in workflows that say so |
-| `design_spec.md` explains the design; `spec_lock.md` executes it | the per-page projection derives narrative and locked values from their owning artifacts, not from prose memory |
-| `page-context` is rebuilt before every page | each read-only view contains the current global lock, page brief, rhythm, chart/image choice, and route-selected template inputs |
+| `design_spec.md` explains the design; `spec_lock.md` executes it | both remain owning artifacts; an on-demand projection never replaces them |
+| Planning context is retained until invalidated | continuous execution reuses the complete Design Spec, lock, and triggered references; fresh/resumed/restarted or compacted execution reloads them once |
+| `page-context` is on demand | the read-only projector supports diagnostics, deterministic routing checks, and optional usage telemetry; it is not a pre-page gate |
| `svg_output/` is the only hand-authored SVG directory | quality checks, manual edits, re-export, and `update_spec.py` target authored source |
| `svg_final/` is mandatory but derived | it is regenerated from `svg_output/` for self-contained visual preview or manual insertion as an SVG picture; it does not become the native export source of truth, and PowerPoint Convert to Shape is outside the supported contract |
| Native PPTX export reads `svg_output/` by default | converter preserves icons, `preserveAspectRatio`, rounded rects, and native image crop metadata before finalization rewrites them |
@@ -354,7 +352,7 @@ PPT Master uses **role switching within one main agent** rather than parallel su
**Image analysis is metadata-first, with a narrow Strategist visual fallback.** When images exist, `analyze_images.py` supplies the regenerated measured facts in `analysis/image_analysis.csv`; the CSV is a view over the live `images/` folder, not a durable cache. Strategist first resolves supplied images from source placement and nearby prose, captions / alt text / titles, filenames, user notes, existing resource records, and that metadata. It may inspect one specific image only when a material ambiguity remains about selection, factual identity, page role, crop safety, or focal placement—never as a bulk inventory scan. The answer is written into Design Spec §VIII, after which Executor uses the plan and measured geometry without reopening source pixels for semantic discovery. User images, extracted images, web images, AI outputs, formulas, and sliced elements still converge into the same measured fact table.
-**Per-page context projection** carries stable continuity anchors plus the current page delta — full rationale in § Spec Propagation below.
+**Retained planning context** carries continuity; the on-demand page projector is only a diagnostic described below.
---
@@ -377,15 +375,15 @@ 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 sparse non-structural display-font accents remain page decisions; recurrence or a stable semantic role requires an upstream lock 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) retains both artifacts once per valid execution context. Fresh/resumed/restarted execution, compaction, or summary-only recovery reloads both once; an unchanged continuous context does not reread either file. 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.
-The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values that decide which execution rule files are loaded. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. When it actually combines or borrows catalog entries, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`, and execution reads every listed file before synthesis; a genuinely novel custom omits the corresponding reference field. Page-context projects these fields instead of leaving Executor with only literal `custom` ids. `template_reuse_scope: mirror|layout` projects additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.
+The lock is also the per-page routing table. Beyond global colors and typography, it carries `page_rhythm` (`anchor` / `dense` / `breathing`), `page_charts` (which chart template should be adapted), image rows with placement/cropping contracts, and the locked `mode` / `visual_style` values that decide which execution rule files are loaded. A selected custom direction also carries its resolved `mode_behavior` / `visual_style_behavior`. When it actually combines or borrows catalog entries, the lock records their exact ids in optional `mode_references` / `visual_style_references` / `image_rendering_references`, and execution reads every listed file before synthesis; a genuinely novel custom omits the corresponding reference field. `template_reuse_scope: mirror|layout` locks additionally carry `page_layouts` (which input template SVG each page inherits), unique `pptx_masters` / `pptx_layouts` definitions, and `page_pptx_layouts` assignments. `template_reuse_scope: style`, free-design, and brand-only projects use `pptx_structure.mode: flat` and omit those sections entirely rather than writing empty values. Empty entries elsewhere are meaningful signals: no chart or no image is often a design decision rather than missing data.
-`page-context v2` separates bounded continuity state from large references. It deliberately repeats the compact global anchor set on every page and binds it to `lock_source.sha256`; that set is not a color/font allowlist. The current §IX brief, rhythm, image choice, and template/chart assignment form the page delta. The project/template Design Specs plus selected prototype and `templates/charts/<key>.svg` files appear only as scoped path/SHA fingerprints. Executor reads one of those files only when that fingerprint is absent from the active context or changed, then reuses the retained understanding. The project Design Spec fingerprint additionally advertises `same_context_edit_policy: targeted-readback-and-rebind`: a bounded exact repair authored by the current main agent, with roster/order/identity/communication unchanged, is verified by targeted fragment readback, validation, and a rebuilt page context, then the retained understanding is rebound to the new SHA without reloading the whole document. Fresh, external, unknown, structural, or mismatched changes still require one complete read. Flat pages have no prototype reference; structured pages reference the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring.
+`page-context v2` remains an on-demand projector. Each invocation emits a compact global anchor set bound to `lock_source.sha256`, the current §IX/resource/routing delta, and scoped path/SHA fingerprints for large references; the projection is not a color/font allowlist or a replacement authority. It is used only for explicit diagnostics/telemetry or an unresolved page/template/chart path-SHA question. A bounded exact repair in a valid uncompacted context may use targeted fragment readback plus validation; fresh, compacted, external, unknown, structural, or mismatched changes require one complete Design Spec and lock read. Flat pages have no prototype reference; structured pages use the authoritative complete SVG. Manifests and text-slot sidecars remain derived tool diagnostics and are never injected into page authoring.
-`--record-usage` writes a derived, input-hashed compact-output snapshot for that page under `analysis/page-context/`. Token counting lazily uses `o200k_base`; a missing `tiktoken` installation records `tokens: null` without blocking execution. `page-context-report` excludes stale snapshots, reports compact page-context totals, and lists unique reference fingerprints. The once-loaded reference payloads and other session context remain intentionally unmeasured.
+`--record-usage` writes a derived, input-hashed compact-output snapshot for an invoked page under `analysis/page-context/`. Token counting lazily uses `o200k_base`; a missing `tiktoken` installation records `tokens: null` without blocking execution. `page-context-report` excludes stale snapshots, reports existing snapshots, and lists unique reference fingerprints; telemetry may be partial. The once-loaded reference payloads and other session context remain intentionally unmeasured.
`update_spec.py` propagates an intentional deck-wide anchor change in two coordinated steps: write the new value to `spec_lock.md`, then literal-replace it across every `svg_output/*.svg`. The tool's scope is deliberately narrow — only `colors.*` (HEX values, case-insensitive replacement) and `typography.font_family` (attribute-scoped). Other fields (font sizes, icons, images, canvas) are intentionally **not supported** because their replacements would need attribute-scoped or semantic awareness whose risk/benefit doesn't justify bulk propagation. This reverse lock update is also valid when repeated contextual use is deliberately promoted into a named semantic role; it must not be used merely to empty an informational checker comparison. For unsupported fields, edit the owning artifact and re-author the affected pages.
@@ -568,7 +566,7 @@ These direct routes share some analysis primitives with the main pipeline, espec
**Why reusable bounds are design zones, not measured text boxes.** Slot bounds come from the intended safe area, column, panel inset, or picture frame—not glyph width, line count, or the current content's tight box. The current Slide retains its own authored carrier geometry, so 4:6, 3:7, and 5:5 instances may share one Layout when they express the same semantic composition. Text length therefore cannot accidentally split or mutate the reusable Layout contract.
-**Why the internal application plan retains two fields.** Strategist derives `template_reuse_scope` to record literal mirror reuse, structural layout reuse, or flat style reference. Structured plans then derive `template_adherence: strict|adaptive`: `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master, and Strategist may declare a new Layout only when fixed Layout atoms or slot topology/bounds change. If construction reveals that need, execution returns upstream and resumes only after Strategist updates the definition and assignment and regenerates page context; the exporter never infers it later. These are exporter values, not user confirmation options. A template-backed definition may remain unused and still register in the final package. Layout skin remains project-controlled, while mirror additionally preserves literal visuals and text-node topology. `style` has no adherence value or structure mappings.
+**Why the internal application plan retains two fields.** Strategist derives `template_reuse_scope` to record literal mirror reuse, structural layout reuse, or flat style reference. Structured plans then derive `template_adherence: strict|adaptive`: `page_layouts` records the complete authoring prototype, `pptx_masters` / `pptx_layouts` record unique reusable definitions, and `page_pptx_layouts` records page assignment. Strict preserves the declared prototype contract. Adaptive retains its Master, and Strategist may declare a new Layout only when fixed Layout atoms or slot topology/bounds change. If construction reveals that need, execution returns upstream and resumes only after Strategist updates, reads back, and validates the definition and assignment; the exporter never infers it later. These are exporter values, not user confirmation options. A template-backed definition may remain unused and still register in the final package. Layout skin remains project-controlled, while mirror additionally preserves literal visuals and text-node topology. `style` has no adherence value or structure mappings.
**Why explicit-Layout text defaults are split between Master and Layout.** Both flat and structured export write the declared title anchor and a deterministic nine-level body hierarchy into Master defaults while preserving indentation and bullet settings. On structured routes, each generated Layout text slot additionally copies its carrier's first run size into the level-one default while retaining the prompt's direct size. This preserves Layout-specific scale when placeholder text is inserted or reset; direct runs on generated Slides remain unchanged.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index e8e1bca1..cd7379b9 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -166,17 +166,14 @@ analysis/source_profile.json ───┼─> Strategist -> design_spec.md + spe
analysis/image_analysis.csv ────┘
design_spec.md + spec_lock.md + images/ + icons/ + templates/
- └─> project_manager.py page-context <project> P<NN>
- + [有界重复的执行锚点集]
- + [当前页 delta]
- + [Design Spec / 原型 / 图表的路径与 SHA 指纹]
- ├─> Executor -> svg_output/
- │ ├─> 未变化的大型引用保留在当前上下文中
- │ ├─> svg_quality_checker.py -> validation/svg_quality_report.json
- │ ├─> finalize_svg.py -> svg_final/
- │ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx + validation/<output_stem>.report.json
- │ backup/<ts>/svg_output/
- └─> --record-usage -> analysis/page-context/P<NN>.usage.json
+ └─> Executor -> svg_output/
+ ├─> 规划产物与引用保留在有效的当前上下文中
+ ├─> project_manager.py page-context <project> P<NN> [按需]
+ │ └─> --record-usage -> analysis/page-context/P<NN>.usage.json
+ ├─> svg_quality_checker.py -> validation/svg_quality_report.json
+ ├─> finalize_svg.py -> svg_final/
+ └─> svg_to_pptx.py -> exports/<name>_<ts>.pptx + validation/<output_stem>.report.json
+ backup/<ts>/svg_output/
直接 OOXML 路由:
analysis/<stem>.slide_library.json + 源 PPTX + fill_plan.json
@@ -277,8 +274,9 @@ CLI 支持 `--move`、`--copy` 和自动默认,但共享同一条固定的所
|---|---|
| `sources/` 内容型文件是主流水线内容契约 | 主 SVG 路线中的文本、表格和图表数值来自 `sources/` 内容型文件(Markdown 为主,`.txt` / `.csv` / `.json` / `.yaml` 等同样计入);已知 sidecar(`*.conversion_profile.json`、`*_files/image_manifest.json`)排除在外 |
| `analysis/` 存机器事实,不存设计契约 | `source_profile.json` 和 intake artifact 辅助 Strategist;除非工作流明确规定,否则不锁定页数 / 页序 |
-| `design_spec.md` 解释设计;`spec_lock.md` 执行设计 | 逐页视图从各自权威 artifact 派生叙事和锁定值,而不是从叙述记忆里取 |
-| 每页生成前重建 `page-context` | 只读视图包含当前全局 lock、页面 brief、节奏、图表/图片选择和按路线选出的模板输入 |
+| `design_spec.md` 解释设计;`spec_lock.md` 执行设计 | 两者始终是权威产物;按需投影不会取代它们 |
+| 规划上下文有效时持续复用 | 连续执行直接使用完整 Design Spec、lock 与已触发引用;fresh/resumed/restarted 或压缩后才重新读取一次 |
+| `page-context` 按需调用 | 只读投影器用于诊断、确定性路由检查和可选的用量统计,不是逐页门禁 |
| `svg_output/` 是唯一手写 SVG 目录 | 质量检查、手工编辑、重导出和 `update_spec.py` 都面向作者源 |
| `svg_final/` 是派生产物 | 它必须能从 `svg_output/` 重建,只负责自包含视觉预览,不应成为 native 导出的事实源 |
| native PPTX 标准导出读取 `svg_output/` | 唯一受支持的可编辑形状路线由项目转换器执行;它要在 finalize 重写前保留图标、`preserveAspectRatio`、圆角矩形和原生图片裁剪语义 |
@@ -350,7 +348,7 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理
**图片分析以重算元数据为先,Strategist 只保留小范围视觉兜底。** 当项目里存在图片时,`analyze_images.py` 把可度量事实重算到 `analysis/image_analysis.csv`;该 CSV 是实时 `images/` 目录的派生视图,不是持久缓存。Strategist 先根据图片在源文中的位置与前后文、图注 / alt / 标题、文件名、用户说明、已有资源记录和这些元数据判断。只有当某一张具体图片在选用、事实身份、页面角色、裁剪安全或焦点放置上仍有实质歧义时,才可单独查看它,绝不得扫描整个图片目录。结论写入 Design Spec §VIII 后,Executor 只消费该计划与几何数据,不会重新打开源图进行语义探索。用户图、抽取图、网络图、AI 图、公式图和切片图仍统一汇入同一张可度量事实表。
-**逐页上下文投影** 是长 deck 的抗漂移机制——完整理由见下面的 § 设计规范的传播。
+**保留的规划上下文**负责跨页连续性;按需逐页投影只承担下文所述的诊断用途。
---
@@ -373,15 +371,15 @@ 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) 在有效执行上下文中只保留并复用这两份产物。fresh/resumed/restarted、上下文压缩或只剩摘要时重新完整读取一次;未变化的连续上下文不重复读取。局部色阶、渐变/效果色与零星的非结构性展示字体属于页面判断;一旦重复出现或形成稳定语义,就必须先提升为上游 lock 角色。
该视图省略 Executor core 已经恒定加载的通用 SVG/图标禁令,只保留项目专属 forbidden 行。图片从当前页 brief、图片资源表中的显式页分配和 mirror 原型引用中选择;已分配给其他页面的图片会被排除,仍无法归属的 legacy 图片保留在兼容子集中,只有所有锁定图片都能确定归属到其他页面时才记录 `confirmed-none`。
-这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它确实综合或借鉴已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id,执行阶段会先读取每个对应文件再综合。真正全新的 custom 不写参考字段。page-context 会把这些字段投影给 Executor,而不是只留下字面上的 `custom` id。`template_reuse_scope: mirror|layout` 项目额外承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。
+这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_charts`(某页应适配哪个图表模板)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它确实综合或借鉴已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id,执行阶段会先读取每个对应文件再综合。真正全新的 custom 不写参考字段。`template_reuse_scope: mirror|layout` 项目的 lock 还承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有图表、没有图片,很多时候是设计选择,而不是漏填。
-`page-context v2` 把有界的连续性状态与大型引用分开。它有意在每页重复紧凑的全局锚点集,并用 `lock_source.sha256` 绑定版本;这个集合不是颜色/字体白名单。当前 §IX brief、节奏、图片选择和模板/图表分配构成逐页 delta。项目/模板 Design Spec、选中的原型,以及 `templates/charts/<key>.svg` 只以带 scope 的路径/SHA 指纹出现。只有该指纹不在当前执行上下文中或 SHA 已变化时,Executor 才读取文件一次;后续页面直接复用已有理解。项目 Design Spec 的指纹还会声明 `same_context_edit_policy: targeted-readback-and-rebind`:当前主代理基于已保留内容做有界精确回修,且页清单、叙事顺序、确认身份与沟通契约均未改变时,只回读修改片段、执行校验并重建 page-context,然后把既有整体理解和已验证 delta 绑定到新 SHA,无需重新加载整份文档。fresh、外部、来源不明、结构性或投影不符的修改仍必须完整读取一次。flat 页面没有原型引用;structured 页面引用权威的完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。
+`page-context v2` 保留为按需投影器。每次调用都会输出绑定 `lock_source.sha256` 的紧凑全局锚点、当前 §IX/资源/路由 delta,以及大型引用的带 scope 路径/SHA 指纹;该投影既不是颜色/字体白名单,也不是替代权威。只有明确的诊断/统计需求,或页面/模板/图表的路径-SHA 问题仍未解决时才调用。有效且未压缩的上下文中做有界精确回修,可以只回读修改片段并校验;fresh、已压缩、外部、来源不明、结构性或投影不符的修改必须完整读取 Design Spec 与 lock。flat 页面没有原型引用;structured 页面使用权威完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。
-`--record-usage` 在 `analysis/page-context/` 下写入当前页的派生快照,记录输入 hash 和紧凑 stdout 的实测大小。token 计数按需加载 `o200k_base`;没有安装 `tiktoken` 时写入 `tokens: null`,但不阻塞执行。`page-context-report` 排除过期快照,汇总紧凑 page-context,并列出唯一引用指纹;一次加载的大型引用 payload 与其他会话上下文有意不纳入统计。
+`--record-usage` 在 `analysis/page-context/` 下为实际调用的页面写入派生快照,记录输入 hash 和紧凑 stdout 的实测大小。token 计数按需加载 `o200k_base`;没有安装 `tiktoken` 时写入 `tokens: null`,但不阻塞执行。`page-context-report` 排除过期快照,汇总已有快照并列出唯一引用指纹;统计可以只覆盖部分页面。一次加载的大型引用 payload 与其他会话上下文有意不纳入统计。
`update_spec.py` 用两个协调步骤传播一次有意的 deck 级锚点修改:把新值写入 `spec_lock.md`,然后字面替换到每一份 `svg_output/*.svg`。工具的范围**故意收得很窄**——只支持 `colors.*`(HEX 值,大小写不敏感替换)和 `typography.font_family`(属性级)。其他字段(字号、图标、图片、画布)**有意不支持**——它们的替换需要属性级或语义级理解,风险/收益不值得做批量传播。当重复出现的上下文值被明确提升为具名语义角色时,反向回写 lock 同样合理;但不能只为了清空 checker 的信息提示而扩充 lock。其他字段应修改其权威产物并重做受影响页面。
@@ -564,7 +562,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路
**为什么可复用 bounds 是设计区域,不是量出来的文本框。** bounds 来自安全区、分栏、面板内框或图片框,而不是字形宽度、行数或当前内容紧包围盒。当前 Slide 保留自己的 carrier 几何,因此只要语义构图相同,4:6、3:7、5:5 的实例都可复用同一 Layout。文本长度不会意外拆分或改变可复用合同。
-**为什么内部应用计划保留两个字段。** Strategist 推导 `template_reuse_scope`,记录字面镜像复用、结构化版式复用或 flat 风格参考;structured 计划再推导 `template_adherence: strict|adaptive`。`page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时,Strategist 才可声明新 Layout。若制作过程暴露出这一需求,执行必须退回上游,待 Strategist 更新定义与分配并重新生成页面上下文后才能继续;导出器不会事后推断。这些是导出器内部值,不是用户确认选项。模板定义即使暂时没有页面使用,也能注册进最终文件。layout 的皮肤由项目控制;mirror 还要保持字面视觉与文字节点拓扑。`style` 不带 adherence 或结构 mapping。
+**为什么内部应用计划保留两个字段。** Strategist 推导 `template_reuse_scope`,记录字面镜像复用、结构化版式复用或 flat 风格参考;structured 计划再推导 `template_adherence: strict|adaptive`。`page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时,Strategist 才可声明新 Layout。若制作过程暴露出这一需求,执行必须退回上游,待 Strategist 更新、回读并校验定义与分配后才能继续;导出器不会事后推断。这些是导出器内部值,不是用户确认选项。模板定义即使暂时没有页面使用,也能注册进最终文件。layout 的皮肤由项目控制;mirror 还要保持字面视觉与文字节点拓扑。`style` 不带 adherence 或结构 mapping。
**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把锁定的 title 字号和确定性的九级 body 层级写入 Master 文本默认值,同时保留原有缩进与项目符号设置;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index f33d61bf..e4fef453 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -19,9 +19,9 @@ Global artifact ownership rules for PPT Master projects.
| `analysis/<stem>.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches, SmartArt nodes/connections | Direct PPTX workflows use as native fill/structure contract |
| `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes |
| `design_spec.md` | Strategist design authority | Human-readable design intent, complete page brief, rationale, resource plan, and confirmed production mechanics authored from the final confirmation plus source analysis | Strategist consumes the final confirmation once, writes and audits every confirmed field here, then later roles read this artifact instead of reopening `result.json`; after Gate 1, §IX is the Executor's page-content authority. |
-| `spec_lock.md` | Execution anchor and routing contract | Machine-readable stable color/type roles, icons, images, page rhythm, charts, `template_reuse_scope`, and the route's PowerPoint structure mode; mirror/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist authors the route-specific anchors from the audited Design Spec plus current project/page/template context. `page-context` repeats that compact anchor set per page and adds current-page routing values. Sparse page-local color/font garnish needs no lock row; a recurring semantic role or new adaptive Layout identity requires Strategist repair before reuse. |
-| `project_manager.py page-context` stdout | Derived per-page context | Read-only model-facing anchor set + current-page delta + fingerprints for large references | Generate immediately before each page without `--bundle`; never edit or persist it as a replacement source of truth. `global` is the bounded repeated anchor set, not a whitelist of every valid page-local value. `reference_set` carries path/SHA/load policy for project/template Design Specs and selected prototype/chart SVGs, but never appends their payloads. The project Design Spec alone may carry `same_context_edit_policy` for verified targeted readback/rebind after the current main agent's own repair. |
-| `analysis/page-context/P<NN>.usage.json` | Derived context telemetry | Actual compact page-context size plus hashes of owning inputs/references | `page-context --record-usage` deterministically replaces that page's snapshot; `page-context-report` summarizes current snapshots and unique references. Use token data to evaluate context cost, never as content or an execution contract. |
+| `spec_lock.md` | Execution anchor and routing contract | Machine-readable stable color/type roles, icons, images, page rhythm, charts, `template_reuse_scope`, and the route's PowerPoint structure mode; mirror/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist authors the route-specific anchors from the audited Design Spec plus current project/page/template context. Executor retains the complete lock once per valid execution context; local uncertainty consults that retained copy before the owning Design Spec fragment. Sparse page-local color/font garnish needs no lock row; a recurring semantic role or new adaptive Layout identity requires Strategist repair before reuse. |
+| `project_manager.py page-context` stdout | Derived on-demand page context | Read-only model-facing anchor set + current-page delta + fingerprints for large references | Use only for explicit diagnostics/telemetry or an unresolved page/template/chart path-SHA projection. Never edit or persist it as a replacement source of truth, and never run it as a routine pre-page gate. `global` is a bounded anchor set, not a whitelist. `reference_set` carries path/SHA/load policy but never appends reference payloads. |
+| `analysis/page-context/P<NN>.usage.json` | Derived optional context telemetry | Measured on-demand page-context size plus hashes of owning inputs/references | `page-context --record-usage` deterministically replaces only the invoked page's snapshot; `page-context-report` summarizes existing snapshots. Telemetry may be partial. Use token data to evaluate context cost, never as content or an execution contract. |
| `images/` | Runtime image pool | User, extracted, AI, web, formula, slice, EMF/WMF assets | Step 5 writes here; `analysis/image_analysis.csv` derives from current contents |
| `icons/` | Prepared project icon pool | Bundled icons copied by `icon_sync.py` plus user-provided, template, imported, or custom icon SVGs | Executor may use any icon in this project-local pool; `spec_lock.icons.inventory` records planned bundled choices rather than an exhaustive whitelist. Exporter global fallback is legacy compatibility only. |
| `templates/` | Project template reference | Step 3 imported specs, template SVGs, and non-image assets | Strategist reads the template Design Spec and actual SVG roster during planning. Continuous Executor reuses that context; fresh Executor reads the Design Spec once and each selected complete SVG only before first use or after its SHA changes. |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 7b5e36e0..fb40b784 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -45,27 +45,27 @@ Always-loaded Executor authority for flat SVG page authoring and behavior shared
Before the first SVG page, output a confirmation listing: the compact communication objective, canvas dimensions, body font size, color scheme (primary/secondary/accent HEX), font plan, and the live-preview URL reported by the launcher. If the preview launch failed, state that failure before generating SVGs instead of silently proceeding. Prevents purpose/spec/execution drift.
-### 2.1 Per-page execution context (Mandatory)
+### 2.1 Execution context validity (Mandatory)
-Before the first SVG, retain `design_spec.md`: continuous execution reuses planning context; fresh/resumed execution reads it once.
+- **Valid**: if the exact complete Design Spec and lock remain in the unchanged, uncompacted active context, reuse both for every page. Do not reread or poll them.
+- **Invalid**: fresh/resumed/restarted execution, compaction/summary-only recovery, or an external/unknown change requires one complete read of `design_spec.md`, then `spec_lock.md`, plus triggered references/template inputs. Mid-deck recovery also reads the latest completed SVG and, when images are used, current image metadata.
+- **Uncertain**: consult the retained lock first, then only the owning Design Spec fragment; use sources only for facts. Design Spec remains upstream on conflict.
-**Hard rule**: Before generating **each** SVG page, load its canonical current-page delta and record its model-facing size:
+**On-demand page-context diagnostic**: only for explicit telemetry/debugging or an unresolved page/template/chart path-SHA question; never as a pre-page gate:
```bash
-python3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> --record-usage
+python3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> [--record-usage]
```
-**Hard rule — direct context consumption**: Run every load as a standalone command and consume stdout directly; repair/rebind does not replace the final pre-page load. Never batch, loop, pipe through another parser, or merge stderr into stdout. Stop on a non-zero exit.
+Consume stdout directly; stop on non-zero exit. The projection is derived, not authoritative. Use `--record-usage` only for measurement.
-`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 — known same-context Design Spec repair**: When the current main agent returns to Strategist and authors an exact project `design_spec.md` repair from its retained state, the `design-spec` reference's `same_context_edit_policy: targeted-readback-and-rebind` avoids a full reread. This applies only to bounded repairs that keep the page roster, narrative order, confirmed identity, and communication contract unchanged. Repair the owning Design Spec headings/page blocks first, re-author only affected lock rows, read back those changed fragments, run `project_manager.py validate`, then rerun `page-context` for every affected page. If each projected brief/global view matches the intended repair, bind the retained whole-document understanding plus verified delta to the new Design Spec SHA. A fresh context, an external/unknown edit, a roster/global-contract change, an unexpected diff, failed validation, or mismatched projection requires one full Design Spec read before continuing.
+**Same-context repair**: in a valid uncompacted context, a bounded repair that preserves roster/order/identity/communication needs only affected Design Spec/lock fragment readback plus `project_manager.py validate`. Any broader or invalid-context repair requires the complete reads above.
**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; reload changed references except the verified same-context Design Spec repair above. Deprecated `--bundle` is a compatibility no-op.
+Use named lock roles literally when that role applies, and use optional `Template Application` from the retained Design Spec. Choose contextual page-local values from the Design Spec, style, content, and current composition rather than forcing every object into a lock row. A page-context delta overrides neither facts nor constraints. Deprecated `page-context --bundle` is a compatibility no-op.
**Source verification**: §IX owns the complete page brief; the page delta does not carry the source corpus. Read sources only to resolve listed `Fact IDs` or verify required claims, quotes, names, or data. Do not add facts, claims, or selected content. Return underspecified blocks for Design Spec repair.
@@ -89,7 +89,7 @@ Use named lock roles literally when that role applies, and use optional `Templat
> Note: block-level phrasing, applied *within* the page's `page_rhythm` density (below), not against it.
-**Missing `spec_lock.md` or `design_spec.md`** → stop before drawing and report the missing gate artifact. Recover through [`failure-recovery.md`](../workflows/governance/failure-recovery.md) §3; do not bypass a failed page-context command or silently downgrade.
+**Missing `spec_lock.md` or `design_spec.md`** → stop before drawing and report the missing gate artifact. Recover through [`failure-recovery.md`](../workflows/governance/failure-recovery.md) §3; do not silently downgrade. A failed on-demand `page-context` diagnostic is also not evidence that a required planning artifact may be bypassed.
**Missing field in an existing lock**: follow [`failure-recovery.md`](../workflows/governance/failure-recovery.md) §2.
@@ -101,12 +101,12 @@ Use named lock roles literally when that role applies, and use optional `Templat
- Font sizes use the named `typography` role values as deck-wide anchors. Map every structural text item to a declared role before drawing; never inherit a template placeholder size. Start from the anchor, then use composition and content fit to adjust that occurrence by at most `±2`px. Keep same-page peers consistent and preserve the role hierarchy; bounded adjustment does not create a new role.
- **Core message ≥ `body`**: map the page's primary claim to declared `lead` / `subtitle`, never below the current body treatment. Footnotes, page numbers, and credits use declared `footnote` / `annotation`; do not invent a smaller role.
- **Write unitless px, with at most two decimals.** Structural and mapped-role text uses only its anchor or a value within its `±2`px band; the sparse display-size exception is defined separately below. Do not substitute familiar pt-style numbers or emit long precision tails.
-- **Sparse display-size exception**: a short non-structural Hero/Display element may use one undeclared size outside all anchor bands at most twice across the deck without a lock row. The third occurrence makes that size recurring: stop and return to Strategist to name the role in the Design Spec and `spec_lock.md`, then regenerate page-context. This exception never applies to titles, body copy, subtitles, annotations, footnotes, captions, data labels, or card copy, and nearby sizes must not be introduced to imitate one recurring treatment.
+- **Sparse display-size exception**: a short non-structural Hero/Display element may use one undeclared size outside all anchor bands at most twice across the deck without a lock row. The third occurrence makes that size recurring: stop and return to Strategist to name the role in the Design Spec and `spec_lock.md`, then read back and validate the affected fragments before reuse. This exception never applies to titles, body copy, subtitles, annotations, footnotes, captions, data labels, or card copy, and nearby sizes must not be introduced to imitate one recurring treatment.
- **Outside-band recovery**: for structural text, reflow geometry and use the declared role band locally. For a sparse display occurrence, keep the unitless value and verify that its deck-wide count remains at most two. Never flatten a justified distinction or add a role merely to silence the checker. Mirror pages preserve exact source typography as inherited input.
- 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.
-Return upstream before any derived/accent identity becomes recurring or structural, or when an undeclared display size reaches its third occurrence, then regenerate context. Local garnish, same-role `±2`px adjustments, and at most two sparse display-size occurrences need no lock row. Never expand the lock to silence a comparison. New icon acquisition, images, structural fonts, role anchors, and resources keep their preparation/role rules.
+Return upstream before any derived/accent identity becomes recurring or structural, or when an undeclared display size reaches its third occurrence, then update the retained context under §2.1. Local garnish, same-role `±2`px adjustments, and at most two sparse display-size occurrences need no lock row. Never expand the lock to silence a comparison. New icon acquisition, images, structural fonts, role anchors, and resources keep their preparation/role rules.
**Per-page layout rhythm — `page_rhythm` section**:
@@ -118,7 +118,7 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
| `dense` | Information-heavy. Card grids, multi-column layouts, KPI dashboards, tables, and charts are all permitted. This is the baseline behavior. |
| `breathing` | Low-density impact page. Avoid **multi-card grid layouts** — do not organize content as multiple parallel rounded containers (3-card row, 4-card KPI grid, 2×2 matrix rendered as cards). Use naked text blocks, dividers, whitespace, or full-bleed imagery as the content structure. Single rounded visual elements (hero image corners, callouts, tags, one emphasis block) are fine — the rule is about grid structure, not about the `rx` attribute. Proportions follow information weight (not a preset ratio). Typical forms: hero quote, single large number with one-line interpretation, full-bleed image with floating caption, section transition. |
-> Without rhythm variation, every page defaults to card grids (the "AI-generated" look). `page_rhythm` is the only narrative lever that survives context compression.
+> Without rhythm variation, every page defaults to card grids (the "AI-generated" look). Context recovery follows §2.1.
**Missing or empty `page_rhythm` section — fixed compatibility default** → emit `warning: spec_lock.md missing/empty page_rhythm — defaulting all pages to dense` once, fall back to `dense` for all pages.
diff --git a/skills/ppt-master/references/executor-structured.md b/skills/ppt-master/references/executor-structured.md
index 771fab8c..88f82840 100644
--- a/skills/ppt-master/references/executor-structured.md
+++ b/skills/ppt-master/references/executor-structured.md
@@ -12,17 +12,17 @@ Conditional Executor authority for `template_reuse_scope: mirror|layout` with `p
| Context | Load policy |
|---|---|
-| `templates/design_spec.md` | Strategist reads once; continuous Executor reuses it, fresh Executor reads it once |
-| Current page delta | Run [`executor-base.md`](./executor-base.md) §2.1 immediately before that page |
-| Selected prototype SVG | Read once on an absent/changed `reference_set` path + SHA; otherwise reuse it |
+| `templates/design_spec.md` | Reuse it in a valid active context; after context invalidation, read it once with the project planning artifacts |
+| Current page mapping | Read the retained `spec_lock.md page_layouts` row; a page change does not require another file load |
+| Selected prototype SVG | Read the complete `templates/<basename>.svg` once per valid context and reuse it until a known change or context invalidation |
-**Hard rule**: Page-context carries no prototype payload. `reference_set` identifies the authoritative complete SVG; never author from a roster, manifest, sidecar, filename, or summary alone.
+**Hard rule**: The complete prototype SVG is authoritative. An on-demand page-context result may fingerprint it but carries no prototype payload; never author from a roster, manifest, sidecar, filename, or summary alone.
Manifest/text-slot files are derived tool metadata, not model inputs. Missing metadata neither invalidates a legacy workspace nor permits text-topology changes.
-**Mapping change**: stop and return to Strategist to update the owning plan; regenerate that page's delta before resuming, then load only a new/changed prototype fingerprint.
+**Mapping change**: stop and return to Strategist to update the owning plan, read back and validate the affected planning fragments, then load the new prototype before resuming.
-Resolve the per-page template SVG from `page_context.template.prototype`; the owning `spec_lock.md page_layouts` row remains authoritative. There is no filename/page-type fallback.
+Resolve the per-page template SVG directly from the owning `spec_lock.md page_layouts` row. There is no filename/page-type fallback.
**Resolution order (per page):**
@@ -58,7 +58,7 @@ When `spec_lock.md` records the AI-derived `template_reuse_scope: mirror`, Execu
6. **Visible text editing** — mirror SVGs may keep literal source text rather than `{{...}}` authoring markers. Edit values in place while retaining imported semantic `data-pptx-placeholder` identity and exact text topology.
7. **Output filename** — follow the standard project SVG naming convention (`<NN>_<page_name>.svg` where `<NN>` matches the project page index, not the mirror source index). The mirror filename is the *reference*, not the *output*.
-**Detecting mirror mode**: read `page_context.template.reuse_scope` from the current page delta. `replication_mode: mirror` in the installed template only determines whether that derived scope is legal; it must never force mirror behavior when the lock records `layout` or `style`.
+**Detecting mirror mode**: read `template_reuse_scope` from the retained lock. `replication_mode: mirror` in the installed template only determines whether that scope is legal; it must never force mirror behavior when the lock records `layout` or `style`.
**Mirror + chart pages**: chart structures inside a mirror SVG are already drawn (axis, series, labels). Treat them as visual references — replace the data labels and series text content to match the project's chart spec, but do not redraw the chart from a `templates/charts/<name>.svg` baseline. A mirror template's `page_charts` entries are normally absent for this reason.
@@ -126,7 +126,7 @@ The exporter writes these solid fills as real Master/Layout/Slide `p:bg`, not se
**Per-page template lookup — `page_layouts` section (`mirror` / `layout` only)**:
-Before drawing each page, use `page_context.template.prototype` to identify the inherited basename. Its matching `reference_set` entry supplies the complete SVG's path and SHA; §1.0 owns whether that file must be read or can be reused from the active context:
+Before drawing each page, use its retained `spec_lock.md page_layouts` row to identify the inherited basename. Resolve the complete SVG from the selected template directory; §1.0 owns whether that file must be read or can be reused from the active context. An on-demand `reference_set` fingerprint may diagnose an uncertain path/SHA but is not required for normal lookup:
- Entry present (e.g., `P04: 03a_content_image_text`) → inherit the corresponding full SVG. The basename **must match** an actual file in the chosen template directory. If it does not, stop before drawing and report the invalid mapping; neither `strict` nor `adaptive` may fall back to free design inside a structured template deck.
- No entry for this page with `template_reuse_scope: mirror|layout` → stop before drawing and report the missing Strategist mapping. Adaptive mode still requires one selected complete template SVG; flexibility applies to the post-design output Layout, not to whether an input prototype exists.
@@ -142,7 +142,7 @@ Do **not** invent a prototype entry, and do **not** assume a structured template
- Read the current page assignment as `P<NN>: <layout_key>`. Resolve the assigned Layout key in `pptx_layouts`, then resolve its Master key in `pptx_masters`. Missing, malformed, or partial mappings stop before drawing.
- Write matching root Master/Layout key and picker names. Do not write `data-pptx-layout-kind` or `data-pptx-page-role`.
- On strict template use, the row and SVG contract match the selected prototype exactly.
-- On adaptive template use, retain the prototype Master and realize the Layout key/name already declared for this page. If construction proves that fixed Layout atoms or slot topology/bounds must change, stop before completing the page and return to Strategist to declare the revised definition and assignment; regenerate the current page context before resuming.
+- On adaptive template use, retain the prototype Master and realize the Layout key/name already declared for this page. If construction proves that fixed Layout atoms or slot topology/bounds must change, stop before completing the page and return to Strategist to declare, read back, and validate the revised definition and assignment before resuming.
- A Layout key may repeat across non-adjacent pages only when its fixed atoms and slot contracts are identical.
**Structured template-page scaffold**:
diff --git a/skills/ppt-master/references/pptx-structure-interface.md b/skills/ppt-master/references/pptx-structure-interface.md
index 7109f1aa..a786bb25 100644
--- a/skills/ppt-master/references/pptx-structure-interface.md
+++ b/skills/ppt-master/references/pptx-structure-interface.md
@@ -24,7 +24,7 @@ Every new SVG project declares one deterministic route. Free-design, brand-only,
**Project lock**: A Master row is `<master_key>: <PowerPoint picker name>`. A unique Layout row is `<layout_key>: <master_key> | <PowerPoint picker name> | <prototype source>`, where the source is a generated `P<NN>` or installed `template:<basename>`. A page assignment is `P<NN>: <layout_key>` under `page_pptx_layouts`. The SVG root values MUST match the assigned definition. A Layout key belongs to exactly one Master and must be globally unique. Reuse one key only when prototypes share identical ordered Layout atoms and slot ids/types/effective indices/default bounds/binding modes. An unused Layout uses a template SVG source and remains registered without a published carrier slide. Every structured route requires numeric `spec_lock.md` typography `title` / `body` rows.
-**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and realizes the current or new Layout key/name declared by Strategist. A construction-discovered change to fixed Layout atoms or slot topology/bounds returns upstream for plan/lock repair and regenerated page context before authoring resumes. Mirror-created prototypes preserve validated source identity, literal paint, typography, effects, atomic geometry, and referenced assets in a new workspace. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology or fill missing facts.
+**Template behavior**: Strict preserves the selected prototype's declared Master/Layout/slot contract. Adaptive retains its Master and realizes the current or new Layout key/name declared by Strategist. A construction-discovered change to fixed Layout atoms or slot topology/bounds returns upstream for plan/lock repair, readback, and validation before authoring resumes. Mirror-created prototypes preserve validated source identity, literal paint, typography, effects, atomic geometry, and referenced assets in a new workspace. `standard` / `fidelity` never make source topology authoritative; mirror does not synthesize a replacement topology or fill missing facts.
Imported inherited-shape visibility remains an immutable analysis fact until a
structured mirror is materialized. The final mirror root carries that fact with
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index c4033362..56c59c93 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -385,7 +385,7 @@ Content-outline and speaker-notes strategy follow the deck's locked **mode** —
This is what makes the axis meaningful: a `presentation` deck and a `text` deck built from the **same source and communication contract** must differ in page grammar, page count recommendation, per-page text volume, visual burden, layout density, rhythm, and notes—not only in font size. Page count stays the user's call; reading mode informs the recommendation when the user has not fixed one. Record it as **Reading Mode** in `design_spec.md §I` (compatibility key `delivery_purpose`, lock key `consumption_mode`). Separately, `communication_intent` / `audience_outcome` determine what the outline must accomplish, while `delivery_context` and `artifact_afterlife` help select the reading mode and still remain independent constraints after selection. The `page_rhythm` leans are a bias, not a quota. Preservation paths keep source wording and structure verbatim: honor reading mode only in styling and notes, never by rephrasing or re-paginating.
-> Note: §IX is the complete page brief projected into each Executor page-context — what you write there is what survives context compression.
+> Note: §IX is the complete page brief; Executor retains it with the lock until context invalidation, then reloads both once.
### 6.2 Planning Artifact Content
@@ -413,12 +413,12 @@ Generate Step 4 owns this reference-first sequence. `design_spec.md` is the Stra
⛔ **GATE 2 — lock context fidelity.** After the Design Spec passes Gate 1, author its machine-relevant execution anchors and routing values into `spec_lock.md`. The lock may normalize syntax and add named recurring implementation roles justified by the Design Spec/page plan, but it must not change confirmed identity or introduce a competing direction. It is intentionally not a field-for-field copy and not a whitelist of every legal SVG value. If authoring exposes a contradiction or missing confirmed decision, return to Gate 1 and repair the Design Spec from the retained final-confirmation state; on a fresh recovery turn only, read the persisted final result once to restore that state.
-**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, pattern, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor rebuilds page projection before every page ([executor-base.md](executor-base.md) §2.1). Repair the Design Spec only from retained final confirmation, then re-author affected lock rows.
+**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 role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, pattern, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor context policy lives in [executor-base.md](executor-base.md) §2.1. Repair the Design Spec only from retained final confirmation, then re-author affected lock rows.
-**Contextual extension**: derived paint or sparse local font/color garnish may stay in one SVG while non-structural and non-recurring. New base/semantic colors, structural/recurring fonts, resources, or patterns require upstream repair; Executor never reverse-projects a choice as fact. Promote garnish upstream before reuse, regenerate page-context, and never add values to silence a comparison.
+**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, read back and validate the affected planning fragments, 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.
+ - **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. Executor reads these fields from the retained lock and loads every referenced catalog entry once per valid context.
- **page_rhythm is mandatory**: Based on the page list in §IX Content Outline, assign each page one of `anchor` / `dense` / `breathing`. This is what breaks the uniform "every page is a card grid" feel. New locks may not omit the section; consumer omission behavior is owned by [`executor-base.md`](executor-base.md) §2.1.
- **Fact IDs and scenario labels are mandatory when applicable**: Read any `sources/*.facts.json`. For each §IX page, list the stable IDs actually used; never cite an ID whose claim is absent from the page. Mark invented KPIs/targets/internal ratios as `Data class: scenario` and state which values are scenario data. Executor carries external sources into notes/footnotes and renders a visible scenario label for scenario figures.
- **Rhythm follows narrative, not quota**: `breathing` pages mark natural pauses — chapter transitions, standalone emphasis (hero quote / big number), SCQA bridges. Dense decks may legitimately be all `dense`. **Do NOT invent filler pages** ("Thank you", empty dividers) to pad rhythm — every `breathing` page must say something independent. Consumption mode biases the overall lean (`presentation` toward more `anchor` / `breathing`, `text` toward `dense`; see §6.1) — a bias, never a quota.
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 532d9a36..a3663957 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -80,13 +80,15 @@ python3 scripts/project_manager.py page-context <project_path> P07 --record-usag
python3 scripts/project_manager.py page-context-report <project_path>
```
-`page-context` prints a read-only compact current-page projection. Its global
-lock projection repeats per page as a continuity anchor set, not a color/font allowlist; large Design Specs,
+`page-context` is an on-demand read-only current-page projection for diagnostics,
+routing checks, or context measurement; normal generation retains the complete
+Design Spec and lock once per valid execution context. Each invocation includes
+the global lock projection as a continuity anchor set, not a color/font allowlist; large Design Specs,
prototype, and `templates/charts/` references are emitted only as scoped
path/SHA fingerprints and are read once per execution context. `--bundle` is a
deprecated compatibility no-op. `--record-usage` writes one derived snapshot
under `analysis/page-context/`; exact `o200k_base` token counts are optional and
-degrade to `tokens: null` when `tiktoken` is absent.
+degrade to `tokens: null` when `tiktoken` is absent. Telemetry may be partial.
Chart candidate recall:
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index e8e03f34..cb8e8244 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -205,7 +205,7 @@ After Stage 2 is confirmed, overwrite it with Stage-3 production recommendations
- `custom_candidates` is recommendation-only. Mode / style carry localized `name` + `behavior`; conditional image strategy also carries `rendering: "custom"`, `visual`, and `mood`. When a proposal combines or borrows existing catalog entries, the visible behavior names every exact id and Strategist reads every corresponding file before authoring it; a genuinely novel proposal names none. The server rejects missing required candidates; the UI shows full copy, edits it only after selection, rejects a selected blank, and omits unselected candidates from `result.json`. Template-backed proposals obey inherited identity, prototype capacity, and `template_application`.
- `audience`, `communication_intent`, and `audience_outcome` are load-bearing Stage-1 reasoning inputs, so seed concrete recommendations when the evidence supports them; they are not required user inputs. Every Stage-1 prose field may be blank after confirmation. The complete six-field contract stays in `result.json` and `design_spec.md`; `spec_lock.md communication` receives only the compact `audience` / `objective` / `core_message` execution projection plus the applicable reading mode. `communication_intent` may preserve several purposes plus priority / sequence; never add a `primary_job` enum.
- Do not write `recommend.template_reuse_scope` or `recommend.template_adherence`. Strategist records those internal exporter values later in `spec_lock.md` after inspecting the actual template and current content.
-- For an active template workspace, write one editable prose field as top-level `template_application.value`. It summarizes actual page/prototype use and preservation/reorganization decisions. Omit it for free design. The UI returns the current string through Stage 2, Stage 3, and final confirmation; Strategist then persists the final effective plan as `- **Template Application**: ...` in `design_spec.md §I`, and `page-context` projects it to Executor. Never replace it with internal reuse/adherence ids or a fixed option menu.
+- For an active template workspace, write one editable prose field as top-level `template_application.value`. It summarizes actual page/prototype use and preservation/reorganization decisions. Omit it for free design. The UI returns the current string through Stage 2, Stage 3, and final confirmation; Strategist then persists the final effective plan as `- **Template Application**: ...` in `design_spec.md §I`, which Executor reads from the retained Design Spec. Never replace it with internal reuse/adherence ids or a fixed option menu.
- `recommend.image_usage` should be an array of source ids when more than one source applies, e.g. `["ai", "provided"]`. A single string is still accepted for backward compatibility. Do not write bare `"custom"` and do not encode a mixed-source plan as prose here; write the prose to top-level `image_notes.value`.
- `image_notes` is the initial strategy note shown under the image source chips. Use it for page-role guidance and constraints: which source applies where, what to avoid, which user assets are authoritative, how realistic / abstract the imagery should be, and what can remain as placeholders. It is intent guidance, not a separate finite option.
- When confirmed Stage-2 `image_usage` includes `ai`, Stage 3 sets `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`. Stage 2 never asks for the acquisition mechanism while the user is still deciding the image role.
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index 180efa02..f5d75e9b 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -70,26 +70,29 @@ Notes:
Multi-deck per project: several PPTX imports each get their own `<stem>.*`
artifacts and a `decks[]` entry; re-importing the same stem replaces its entry.
-### Per-page execution view
+### On-demand page execution view
`page-context` projects `design_spec.md` and `spec_lock.md` into one compact
current-page view on stdout. The default command is read-only; `--pretty`
changes JSON formatting only. Before projection it revalidates the machine lock
and selected template-root identities; design-brief values are not treated as
-a second lock. Slide headings at H3–H6 remain readable by the projector.
+a second lock. Slide headings at H3–H6 remain readable by the projector. Normal
+generation retains the complete planning artifacts once per valid execution
+context and does not invoke this command before every page; use it only for an
+explicit diagnostic, routing check, or context-usage measurement.
-The output deliberately repeats the bounded `global` anchor set on every
-page as a cross-page anchor set, not a color/font allowlist. `lock_source` binds that projection to the current
+Each invocation deliberately includes the bounded `global` anchor set as a
+cross-page continuity view, not a color/font allowlist. `lock_source` binds that projection to the current
`spec_lock.md` SHA. `page_context` contains the current §IX brief, rhythm,
resources, and conditional template/chart assignment. `reference_set` contains
`kind`, scoped path, SHA, and `once-per-execution-context` policy for the
project/template Design Specs and selected prototype/chart SVGs. The project
Design Spec additionally carries
`same_context_edit_policy: targeted-readback-and-rebind`: when the current main
-agent makes a bounded repair that preserves roster/order/identity/communication,
-it reads back only the exact changed fragments,
-validates, reruns `page-context`, and binds the verified delta to the new SHA.
-Fresh, external, unknown, or mismatched changes still require a complete read.
+agent makes a bounded repair in a valid uncompacted context that preserves
+roster/order/identity/communication, it reads back only the exact changed
+fragments and validates them before continuing. Fresh, compacted, external,
+unknown, or mismatched changes require one complete Design Spec and lock read.
The deprecated `--bundle` flag remains accepted as a compatibility no-op. It
never appends a Design Spec, prototype SVG, chart SVG, manifest, or text-slot
@@ -115,9 +118,9 @@ exact compact stdout, and records the reference fingerprints. `tiktoken` is
loaded lazily with `o200k_base`; when unavailable, the command still succeeds
and records bytes, characters, hashes, and `tokens: null`.
`page-context-report` summarizes only fresh snapshots and identifies stale or
-token-unavailable pages plus unique referenced files. The telemetry does not
-measure the once-loaded reference payloads, source-material reads, or other
-session-level prompt references.
+token-unavailable pages plus unique referenced files. Telemetry may be partial;
+it does not measure once-loaded references, source reads, or other session
+context.
Common formats:
- `ppt169`
diff --git a/skills/ppt-master/scripts/mirror_template_materialize.py b/skills/ppt-master/scripts/mirror_template_materialize.py
index 70e0c0fe..240508f9 100644
--- a/skills/ppt-master/scripts/mirror_template_materialize.py
+++ b/skills/ppt-master/scripts/mirror_template_materialize.py
@@ -278,11 +278,12 @@ def _template_execution_manifest_files(
"text_slots_schema": TEMPLATE_TEXT_SLOTS_SCHEMA,
"execution_policy": (
"This manifest and its text_slots_path records are derived tool "
- "metadata, not page-authoring inputs. Before each page, run "
- "project_manager.py page-context <project> P<NN> --record-usage. "
- "Read the selected complete prototype only when its path and SHA "
- "are absent from the active execution context or changed, then "
- "reuse it. Choose semantic replacements and edit only existing "
+ "metadata, not page-authoring inputs. Retain the complete project "
+ "Design Spec and lock once per valid uncompacted execution context; "
+ "use page-context only for on-demand diagnostics or telemetry. "
+ "Read the selected complete prototype once per valid context and "
+ "again only after a known change or context invalidation. Choose "
+ "semantic replacements and edit only existing "
"visible text values; structured export validates text/tspan "
"topology and attributes against the prototype."
),
diff --git a/skills/ppt-master/scripts/page_context.py b/skills/ppt-master/scripts/page_context.py
index 7ee24f75..3d0d7c81 100644
--- a/skills/ppt-master/scripts/page_context.py
+++ b/skills/ppt-master/scripts/page_context.py
@@ -552,8 +552,8 @@ def build_page_context(project: str | Path, raw_page: str) -> PageContextResult:
reference_set.append(chart_reference)
mode_fields = _section_fields(lock_sections, "mode")
visual_style_fields = _section_fields(lock_sections, "visual_style")
- # Repeat this bounded projection per page intentionally: stable lock roles
- # are continuity anchors, while large reference payloads use reference_set.
+ # Each on-demand projection includes bounded lock anchors; large reference
+ # payloads stay outside it and are represented by reference_set.
global_context = {
"communication": _section_fields(lock_sections, "communication"),
"canvas": _section_fields(lock_sections, "canvas"),
@@ -592,7 +592,7 @@ def build_page_context(project: str | Path, raw_page: str) -> PageContextResult:
"lock_source": {
"path": "spec_lock.md",
"sha256": _file_sha256(lock_path),
- "load_policy": "per-page-context-anchors",
+ "load_policy": "on-demand-anchor-projection",
},
"global": global_context,
"page_context": current_page,
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 4bff6dd0..e6f3776b 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -128,5 +128,5 @@ Field meaning and selection logic stay in the owning Strategist modules. Executo
- Confirmed core palette roles and every declared typography family/size role remain stable cross-page anchors.
- Page-local tints, gradient stops, shadow/glow paints, transparency composites, and one-off export-safe display families may be authored from context without adding a lock row.
- Executor may adjust one occurrence within its declared size role's anchor `±2px` while preserving hierarchy and readability; intermediate values are realization choices, not new lock rows.
-- When a contextual value becomes a recurring semantic role, or one undeclared display size reaches its third occurrence, add the descriptive color/family/size role and regenerate page-context before later pages use it. Structural typography outside its applicable anchor band returns upstream immediately.
+- When a contextual value becomes a recurring semantic role, or one undeclared display size reaches its third occurrence, add the descriptive role, read back and validate affected planning fragments, then reuse it. Structural typography outside its applicable anchor band returns upstream immediately.
- Do not expand the lock merely to make an informational checker comparison empty. A lock edit should express reuse or identity, not enumerate incidental literals.
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index d8586aa8..e45b7c36 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -12,7 +12,6 @@ description: Generate PPTX route authority for source intake, planning, SVG auth
- The current main agent hand-writes every SVG page; never delegate page generation or run a Python, Node, or shell generator over `svg_output/`.
- Initial SVG cadence: P01 → first-page gate → uninterrupted remaining pages → final gate. Grouped batches and mid-run checker calls are forbidden.
-- Before each page, load compact page-context; its repeated global values are continuity anchors, while unchanged large references stay in context.
- `preset_shape_svg.py` may provide one stdout fragment only after the main agent chooses its semantic role, frame, and paint; it cannot choose layout or write a page.
### SVG Page-Design Boundary
@@ -236,7 +235,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
**Output**:
- `<project_path>/design_spec.md` — complete human-readable design narrative and durable confirmed production state
-- `<project_path>/spec_lock.md` — machine-readable communication + stable execution anchors/routing contract; Executor consumes its current-page projection from `page-context`
+- `<project_path>/spec_lock.md` — machine-readable communication + stable execution anchors/routing contract; Executor retains it in the active execution context and may inspect an on-demand current-page projection for diagnostics
For a new project, use the reference-first whole-document sequence:
@@ -337,6 +336,8 @@ Workflow:
**Page content**: §IX is preferred wording and semantic authority. Use it when it works; adapt it when presentation benefits while preserving intent, facts, and explicit literal requirements. Read sources only to verify requested evidence; return incomplete blocks to Step 4 instead of enriching them during execution.
+**Planning context**: follow [`executor-base.md`](../references/executor-base.md) §2.1. Reuse the complete Design Spec and lock in an unchanged, uncompacted context. Fresh/resumed/restarted, compacted/summary-only, or externally/unknown changed execution reads both once and reloads triggered inputs. For a local question, consult the retained lock first, then only the owning Design Spec fragment; do not poll files merely to prove validity.
+
**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`):
@@ -376,26 +377,20 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemon
- **Do NOT read or apply submitted annotations during generation.** Users may annotate at any time, but Executor proceeds without touching them. The window to apply annotations opens only after Step 7 completes — see [`workflows/stages/live-preview.md`](stages/live-preview.md).
- The editor also supports **staged direct edits** (text content + SVG element attributes previewed immediately, then written to `svg_output/` only when the user clicks **Apply changes**; `Ctrl+Z` / Undo drops staged edits) alongside annotation; re-export stays chat-driven. Full scope and editor details: see [`workflows/stages/live-preview.md`](stages/live-preview.md) Notes.
-**Conditional reference reads**: Follow `executor-structured.md` for template Design Spec/prototypes and `executor-chart.md` for `templates/charts/<key>.svg`. Both reuse unchanged `reference_set` path + SHA fingerprints; flat routes skip template reads. Summaries and sidecars never replace full SVGs.
+**Conditional reference reads**: Follow `executor-structured.md` for template Design Spec/prototypes and `executor-chart.md` for chart SVGs. Read each selected full reference once per valid context; reread only after a known change or context invalidation. Flat routes skip template reads. Summaries and sidecars never replace full SVGs.
> Image facts: trust the latest `analysis/image_analysis.csv` from the Step 4 inventory read or the Step 5 post-acquisition refresh. If `images/` changed since, re-run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before layout; if the folder is empty, use no image inventory and ignore a stale CSV.
-**Per-page context load (Mandatory)**: before **each** SVG page, run:
-
-```bash
-python3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> --record-usage
-```
-
-Use `global` as the compact cross-page anchor set, `page_context` as the page delta, and `reference_set` under the Executor load policy. Anchors are defaults and reusable semantic roles, not a color/font allowlist. The retained Design Spec owns optional `Template Application`. This replaces neither gate artifacts nor source facts. See [`executor-base.md`](../references/executor-base.md) §2.1.
+**Page-context**: use the read-only projector only for the diagnostic/telemetry triggers in Executor §2.1, never as a routine pre-page load.
> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.
-> ⚠️ **Generation rhythm**: P01 → first-page gate → uninterrupted remaining pages → final gate, in one context without batches or mid-run checker calls.
+> ⚠️ **Generation rhythm**: P01 → first-page gate → uninterrupted remaining pages → final gate. After context invalidation, reload under §2.1 before continuing; do not insert batches or mid-run checker calls.
**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`
Each completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. When a page actually needs a literal stock shape, load and apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before drawing it. Diagram relationships remain Shape-first; do not infer a preset from contour similarity.
-`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive uses the current or new Layout key/name already declared by Strategist. If construction proves that fixed atoms or slot topology/bounds must change, stop and return upstream for Strategist to repair the owning plan and lock, regenerate the page context, then resume; Executor never mutates `spec_lock.md`. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.
+`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive uses the current or new Layout key/name already declared by Strategist. If construction proves that fixed atoms or slot topology/bounds must change, stop and return upstream for Strategist to repair the owning plan and lock, validate and read back the affected fragments, then resume; Executor never mutates `spec_lock.md`. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.
`template_reuse_scope: style`, free-design, and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.
diff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.md
index 52de05fb..a50c5f1f 100644
--- a/skills/ppt-master/workflows/governance/failure-recovery.md
+++ b/skills/ppt-master/workflows/governance/failure-recovery.md
@@ -20,7 +20,8 @@ Global stop/continue rules for all four top-level routes, plus concrete failure
| Missing final confirmation | Yes | None | User must confirm or change the values | Step 4 final confirmation |
| Final confirmed value is missing, changed, substituted, or weakened in `design_spec.md` | Yes | Repair from the retained final-confirmation object; only a fresh recovery turn with no retained state reads persisted final evidence once | Only when the confirmed value genuinely cannot be honored | Step 4 Gate 1 — confirmation fidelity |
| `spec_lock.md` changes confirmed identity or omits a required execution anchor/routing decision | Yes | Re-author the affected lock rows from the completed Design Spec and current context; do not enumerate page-local literals | No unless the Design Spec itself is incomplete | Step 4 Gate 2 — lock context fidelity |
-| Execution exposes a missing Strategist-owned semantic role or plan detail | Yes for the affected page | In the same main-agent context, return to Strategist; repair the owning Design Spec fragments, then affected lock rows; targeted-readback, validate, rerun `page-context` for affected pages, and rebind the new SHA per [`executor-base.md`](../../references/executor-base.md) §2.1. Fresh or unknown context reads the complete Design Spec once | Only if the repair changes confirmed identity or user intent | Step 4 Gate 1/2 → Step 6 current page |
+| Execution exposes a missing Strategist-owned role/plan detail | Yes for the affected page | Repair affected Design Spec/lock fragments under [`executor-base.md`](../../references/executor-base.md) §2.1 | Only if confirmed intent changes | Step 4 Gate 1/2 → Step 6 current page |
+| Execution context is fresh, resumed, restarted, compacted/summary-only, external, or unknown | Yes until rebuilt | Read complete Design Spec, then lock, once; reload triggered inputs and latest completed SVG when mid-deck | No | Step 6 current page |
| Step 3 rejects a legacy or incomplete template contract | Yes | Stop template consumption; create a new current workspace through Create Template from the original PPTX/reference, then return with its exact workspace root | Only when required source evidence or template choices are unavailable | Create Template → Generate PPTX Step 3 |
| Formula rendering provider failure | No until the Step 7 readiness gate | Exhaust the provider chain; if unresolved, mark only the affected formula rows `Needs-Manual` and continue | Supply the exact target PNG or change formula policy | Step 4 / Step 7 image readiness gate |
| AI image generation failure | No | `auto`: follow A → B → Offline Manual. Explicit `api` / `host-native`: retry only that path, then mark the row `Needs-Manual` without switching automated providers | Only when missing files are required before export | Step 5 / Step 7 image readiness gate |
diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.md
index fee66e7c..255fb224 100644
--- a/skills/ppt-master/workflows/stages/resume-execute.md
+++ b/skills/ppt-master/workflows/stages/resume-execute.md
@@ -28,8 +28,8 @@ Verify the project's planning-session artifacts before doing anything else:
| File / Directory | Required when | Reason |
|---|---|---|
-| `<project_path>/spec_lock.md` | Always | Strategist's execution contract; `page-context` projects its current-page values |
-| `<project_path>/design_spec.md` | Always | Section IX page outline; `page-context` projects the current page block |
+| `<project_path>/spec_lock.md` | Always | Strategist's execution anchors and routing contract; read it completely once in this fresh execution context |
+| `<project_path>/design_spec.md` | Always | Complete approved design narrative and Section IX page outline; read it completely once in this fresh execution context |
| `<project_path>/images/` plus files whose row status requires existence | `spec_lock images` references any image | `Existing` / `Generated` / `Sourced` / `Rendered` files must exist; an absent `Needs-Manual` file remains allowed until the Step 7 readiness gate |
| `<project_path>/templates/` | `spec_lock page_layouts` references any | Layout / mirror prototypes required by execution |
| `skills/ppt-master/templates/charts/` | `spec_lock page_charts` references any | Shared chart SVGs selected by key |
@@ -50,10 +50,12 @@ Read skills/ppt-master/workflows/generate-pptx.md
Then jump to `### Step 6: Executor Phase` and run the documented pipeline:
+- Read the complete project Design Spec, then the complete `spec_lock.md`, once to establish the fresh execution context
+- If resuming mid-deck, read the latest completed SVG and current image metadata when images are used
- Read the Step 6 flat core (`executor-base`, `shared-standards-core`, and the locked preset mode / visual-style files); for custom directions, reload every optional `*_references` file from `spec_lock.md` before applying the behavior, then only the branches selected by the condition table
- Design Parameter Confirmation
-- Read the project Design Spec and, when structured, the template Design Spec once; retain both in the fresh execution context. A later repair authored by this same main agent follows [`executor-base.md`](../../references/executor-base.md) §2.1 targeted readback/rebind instead of loading the project Design Spec a second time
-- Per-page `python3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> --record-usage` load + sequential page generation; the stable anchor projection repeats intentionally without becoming a color/font allowlist, while each prototype/chart SVG is loaded only before its first use or after its SHA changes
+- When structured, read the template Design Spec and each selected prototype once; retain unchanged references in the fresh context. A later bounded repair follows [`executor-base.md`](../../references/executor-base.md) §2.1 only while that context remains valid and uncompacted
+- Generate pages sequentially from the retained planning artifacts. Use `page-context` only for the on-demand diagnostic/telemetry triggers in Executor §2.1, never as a routine pre-page load
- Quality Check Gate
- Speaker notes generation
- Step 7: Post-processing & Export (`total_md_split` → `finalize_svg` → `svg_to_pptx`)