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(planning): preserve confirmed decisions through spec projection
hugohe30c3dd8cd72a0
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.mdindex b7a3f278..9b9d290c 100644--- a/skills/ppt-master/references/artifact-ownership.md+++ b/skills/ppt-master/references/artifact-ownership.md@@ -18,8 +18,8 @@ Global artifact ownership rules for PPT Master projects.| `analysis/<stem>.identity.json` | Native deck identity facts | Canvas, theme palette/fonts, observed usage | Read selectively when detailed identity facts are needed || `analysis/<stem>.slide_library.json` | Native PPTX structure facts | Text slots, geometry, native tables, native chart caches, SmartArt nodes/connections | Direct PPTX workflows use as native fill/structure contract || `analysis/image_analysis.csv` | Regenerated image fact view | Measured facts about the current `images/` folder | Re-run `analyze_images.py` before reading image facts after changes |-| `design_spec.md` | Human design narrative | Explains design intent, outline, rationale, and resource plan | Strategist writes; humans and later roles read for intent |-| `spec_lock.md` | Execution contract | Literal colors, typography, icons, images, page rhythm, charts, `template_reuse_scope`, and the route's PowerPoint structure mode; mirror/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist writes the route-specific contract; `page-context` projects the current-page subset for Executor. Executor may add a new adaptive Layout identity only on a structured mirror/layout route while authoring the page that first needs it. |+| `design_spec.md` | Strategist design authority | Human-readable design intent, outline, rationale, and resource plan authored from the final confirmation plus source analysis | Strategist writes and audits it against every confirmed field before lock projection; humans and later roles read it for intent |+| `spec_lock.md` | Execution projection | Machine-readable colors, typography, icons, images, page rhythm, charts, `template_reuse_scope`, and the route's PowerPoint structure mode; mirror/layout template routes additionally own input prototypes, the Master roster, and the complete page-to-Master/Layout mapping | Strategist projects the route-specific contract from the audited Design Spec without making another design decision; `page-context` projects the current-page subset for Executor. Executor may add a new adaptive Layout identity only on a structured mirror/layout route while authoring the page that first needs it. || `project_manager.py page-context` stdout | Derived per-page context | Read-only model-facing projection of current `design_spec.md`, `spec_lock.md`, and selected template assets | Generate immediately before each page with `--bundle`; never edit or persist it as a replacement source of truth. Flat bundles contain context only; layout adds the complete selected prototype; mirror adds that prototype plus the minimal text-slot view. || `analysis/page-context/P<NN>.usage.json` | Derived context telemetry | Actual model-facing bundle size by page and component | `page-context --record-usage` deterministically replaces that page's snapshot; `page-context-report` summarizes current snapshots. Use token data to evaluate later context tooling, 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 |@@ -54,7 +54,7 @@ Global artifact ownership rules for PPT Master projects.| Content values | Main pipeline text, tables, chart values, and SmartArt node wording come from content-type files in `sources/` (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`), not from `slide_library.json`. || Sources read policy | In `sources/`, read content-type files (`.md` / `.markdown` / `.txt` / `.csv` / `.tsv` / `.json` / `.jsonl` / `.yaml` / `.yml`) and judge by content — a `.json` / `.csv` may be core content or just data. Exclude known sidecars: `*.conversion_profile.json` and `*_files/image_manifest.json`. `analysis/` facts (`source_profile.json`, `<stem>.slide_library.json`) are read per Step 4 / direct-PPTX workflow, not in the `sources/` content scan. || PPTX structure | `slide_library.json` owns native geometry, slot facts, and SmartArt layout/relationships for direct PPTX workflows. |-| Design contract | `design_spec.md` explains; `spec_lock.md` executes. Executor must not infer execution values from prose. |+| Design contract | Final confirmation → audited `design_spec.md` → projected `spec_lock.md`. Executor may apply projected `Template Application` prose to visible template content, but never infer lock values from it. On divergence, repair the lock from the Design Spec unless the Design Spec itself fails confirmation fidelity. || Flat packaging authority | Free-design, brand-only, and `template_reuse_scope: style` declare `pptx_structure.mode: flat` and omit `pptx_masters`, `pptx_layouts`, `page_pptx_layouts`, and `page_layouts`. `svg_output/` owns the complete Slide-local visual design without root Master/Layout identity, fixed-layer ownership, or placeholder metadata. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme defaults, removes stock content placeholders/Layout inventory, and retains only the standard date/footer/slide-number capability hooks. || Template structure authority | `template_reuse_scope: mirror|layout` uses `page_layouts` for each page's authoring-input prototype. `pptx_masters` / `pptx_layouts` own the unique reusable output definitions, while `page_pptx_layouts` owns page assignment. Strict keeps the prototype contract; adaptive may create a new Layout definition during page authoring and updates its assignment immediately. Mirror additionally preserves literal visuals/text topology; layout allows project-controlled reflow/re-skinning. Unused definitions may register without a published Slide. Templates validate provenance but never add missing visible page objects during export. || Fact classes | External facts resolve through `sources/*.facts.json`; invented demo KPIs/targets/internal ratios are labeled `scenario` in `design_spec.md §IX` and visibly in the page. Never promote scenario data into the external fact registry. |@@ -67,7 +67,7 @@ Global artifact ownership rules for PPT Master projects.| Post-processed SVG | `svg_final/` is disposable, must be rebuilt in Step 7.2, and serves only as a self-contained visual preview / manually insertable SVG picture. || Export source | The only supported generated-PPTX route reads `svg_output/` through the project SVG-to-DrawingML converter. A diagnostic `-s final` override does not change ownership or create a supported release route. || Shape-conversion boundary | PowerPoint's manual Convert-to-Shape operation on `svg_final/` is outside the project compatibility contract. |-| Confirmation | Final `confirm_ui/result.json` or chat confirmation overrides recommendations. |+| Confirmation | Final `confirm_ui/result.json` or chat confirmation overrides recommendations and is the mandatory input contract for `design_spec.md`; `spec_lock.md` is derived only after that Design Spec passes confirmation-fidelity review. |**Forbidden - mixed ownership**: Do not copy chart values from Markdown into `analysis/` by hand, do not edit `svg_final/` as the source of a fix, do not edit imported lossless SVGs instead of their authoring IR, and do not treat `design_spec.md` prose as a replacement for `spec_lock.md`.diff --git a/skills/ppt-master/references/modes/_index.md b/skills/ppt-master/references/modes/_index.mdindex 210fcf30..6a6ec863 100644--- a/skills/ppt-master/references/modes/_index.md+++ b/skills/ppt-master/references/modes/_index.md@@ -53,7 +53,7 @@ Each mode has its own file with: narrative skeleton, page-structure tendencies,1. Strategist reads this index at confirmation `d. Layer 1`.2. Pick one mode from the auto-selection table + the confirmed communication contract and source structure.-3. Lock it: write `- mode: <name>` into `spec_lock.md`, record the rationale in `design_spec.md`.+3. Record the confirmed mode and rationale in `design_spec.md`, then project `- mode: <name>` into `spec_lock.md`.4. Executor reads **only** `modes/<locked-mode>.md` at generation entry — never globs this directory.**Lock scope**: deck-wide (one mode per deck). The five are the catalog you select from; if the structure is genuinely mixed, pick the mode of the body pages and let pages vary within it, or recommend a `custom` blend (§4). Recommend the best fit; the user confirms.@@ -64,7 +64,7 @@ Each mode has its own file with: narrative skeleton, page-structure tendencies,`custom` holds **any bespoke narrative direction the five don't give as-is** — and what *kind* of thing it is doesn't matter. It might be a nameable cadence (dialectic 正反合, myth-vs-reality, countdown / Top-N, Socratic), a deliberate multi-act fusion of several modes, or the user's own feel for how the deck should carry (confrontational here, detached there). Don't try to taxonomize it.-**Either side may originate it.** The user can ask for it directly; or the Strategist — as the deck's strategist — may **recommend** `custom` when a bespoke direction (often a fusion of two modes) genuinely serves the deck better than any single preset. Like every confirmation, it's a recommendation the user confirms or overrides — and the recommendation must **spell the custom out in plain language** (what the cadence / fusion / posture actually is), never present the bare token `custom`, so the user confirms something legible. Either way, the Strategist **crystallizes the intent into a `- mode_behavior:` paragraph** — concrete enough that the Executor can follow it per page (the act sequence or posture shifts, the title voice, the page rhythm, the notes register). Set `- mode: custom` in `spec_lock.md` with that sibling line; the Executor follows the prose in place of a preset file. (This records the intent so it survives 20 pages of generation — the Executor only ever reads `spec_lock.md`, never the chat.)+**Either side may originate it.** The user can ask for it directly; or the Strategist — as the deck's strategist — may **recommend** `custom` when a bespoke direction (often a fusion of two modes) genuinely serves the deck better than any single preset. Like every confirmation, it's a recommendation the user confirms or overrides — and the recommendation must **spell the custom out in plain language** (what the cadence / fusion / posture actually is), never present the bare token `custom`, so the user confirms something legible. Either way, the Strategist crystallizes the intent in the Design Spec first, then projects it as `- mode: custom` plus a concrete `- mode_behavior:` paragraph in `spec_lock.md`. The Executor follows that prose in place of a preset file. (This records the intent so it survives 20 pages of generation — the Executor only ever reads `spec_lock.md`, never the chat.)> **One value per deck — fusion is *one* `custom`, not several modes.** A deck always locks a single `mode`. A multi-mode blend is expressed as **one** `mode: custom` whose `mode_behavior` paragraph describes the acts — never by locking several modes.>diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.mdindex 93a18332..887b87aa 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 `image_notes`; this module never adds a 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 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.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.@@ -20,7 +20,7 @@ For ≥3 AI-generated same-family spots, plan one unplaced `ai` Illustration SheWhen proposed sources include `ai`, read every entry in [`image-renderings/_index.md`](./image-renderings/_index.md) before constructing Stage 2. Unless the user or active template already names a rendering, place at least three credible, distinct renderings across the coordinated safe/shifted/bold directions; a genuine compatibility shortfall may return fewer with a reason. Each `image_strategy` carries localized `rendering`, `visual`, and `mood` only. Mood includes a recognizable real-world analogy. Image colors always inherit that direction's deck HEX roles; never add an image palette or alter deck colors to rescue a rendering.-`custom` is a tail case: at most one candidate uses it, and its visual prose must satisfy the catalog's custom grammar. A confirmed choice locks one deck-wide `image_rendering` in `design_spec.md §III` and `spec_lock.md colors`; confirmed custom prose also becomes `image_rendering_behavior` and is carried into every AI brief. A confirmed non-custom id needs no behavior row. Ignore legacy `image_palette` rows.+`custom` is a tail case: at most one candidate uses it, and its visual prose must satisfy the catalog's custom grammar. Record the confirmed deck-wide `image_rendering` in `design_spec.md §III` first, then project it to `spec_lock.md colors`; confirmed custom prose also becomes `image_rendering_behavior` and is carried into every AI brief. A confirmed non-custom id needs no behavior row. Ignore legacy `image_palette` rows.For specialized or regulated paper-figure subjects, preserve the prompt depth required by [`image-generator.md`](./image-generator.md) §4.2 rather than shortening to a generic brief. Scan the outline for genuine image-led pages, list the proposed hero pages in Stage-2 `image_notes` so the user can retain, edit, or remove them in the same confirmation, then mark only the confirmed pages' AI rows `page_role: hero_page`; local is the default. `text_policy: embedded` is reserved for lettering that must be fused into the artwork; ordinary titles, data, labels, and prose remain editable SVG. Analyze confirmed provided assets before writing §VIII.@@ -47,7 +47,7 @@ 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). 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 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.🚧 **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.diff --git a/skills/ppt-master/references/strategist-template.md b/skills/ppt-master/references/strategist-template.mdindex 30aa2240..24e43a0c 100644--- a/skills/ppt-master/references/strategist-template.md+++ b/skills/ppt-master/references/strategist-template.md@@ -41,9 +41,9 @@ Record the resulting exporter plan internally:| `template_adherence: strict` | Every structured page fits an existing prototype contract without changing its Layout identity or slot topology. Mandatory for `template_reuse_scope: mirror`. || `template_adherence: adaptive` | Structured reuse remains useful, but at least one page needs a new explicit Layout under the selected Master. |-Write the derived values to `design_spec.md §I` and `spec_lock.md pptx_structure`; omit `template_adherence` for `style`. Do not put these values in `recommendations.json`, the Confirm UI, or `result.json`.+Write only the derived values to `spec_lock.md pptx_structure`; omit `template_adherence` for `style`. Do not put these internal values in `design_spec.md`, `recommendations.json`, the Confirm UI, or `result.json`.-**Mandatory — natural-language Stage-2 plan**: Include one concise natural-language summary of the template application in the complete Stage-2 solution: which pages/prototypes are used, skipped, repeated, or reordered; what remains literal; and what may be replaced or reorganized. Write it to top-level `template_application.value` in Stage-2 `recommendations.json`; omit the field when no template workspace is active. The Confirm UI returns the user's current text as `template_application`. After Stage 2, re-read that confirmed value from `result.json` (or the exact chat answer in chat fallback) before deriving `template_reuse_scope`, `template_adherence`, §IX page plans, and structure mappings; never reuse the initial recommendation after the user edits or clears it. Blank means no explicit user constraint and returns the decision to Strategist. Do not add a template questionnaire, expose internal values, or turn the summary into fixed template-use options.+**Mandatory — natural-language Stage-2 plan**: Summarize which prototypes are used/skipped/repeated/reordered, what stays literal, and what may be replaced or reorganized. Write it to top-level `template_application.value` in Stage-2 `recommendations.json`; omit it without an active template. After Stage 2, re-read the confirmed `result.json` value (or exact chat answer), never the initial recommendation. Blank returns the decision to Strategist. Persist the effective plan on one line as `- **Template Application**: <prose>` in `design_spec.md §I`, then derive internal reuse/adherence values and mappings; never copy the prose to `spec_lock.md`. Do not add a questionnaire, internal controls, or fixed template-use options.**Three-stage boundary**: An installed template changes the content of Stage 2, never the confirmation sequence. Run Stage 1 → Stage 2 → Stage 3 in order in both Confirm UI and chat fallback; do not skip a stage or treat template inspection as user confirmation. On browser timeout, return to the same stage in chat.diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 63d4942e..d3807a7f 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -40,6 +40,8 @@ Do not force communication intent into one catalog label. A deck may report prog> **Default presentation surface — Confirm UI.** Deliver the package through the interactive page: write recommendations to `<project>/confirm_ui/recommendations.json`, then launch per [`generate-pptx.md`](../workflows/generate-pptx.md) Step 4. Stage 2 `design_directions` carries **≥3 coordinated candidates** (safe / shifted / bold); each bundles visual style, color, CJK + Latin typography, icons, and conditional generated-image rendering. This is one set of real alternatives, not independent candidate grids that happen to share a screen. Honest-shortfall exception: if the constraints genuinely cannot yield 3 non-conflicting directions, present the smaller set and say why—never pad with duplicates or conflicts. **Always also print the recommendations + URL in chat** as the fallback. On confirm, read `<project>/confirm_ui/result.json` (`generation_mode: "split"` / `refine_spec: true` are explicit user choices). Skip the page if the user wants chat-only. Generate Step 4 owns when to write, wait, and block; [`confirm_ui.md`](../scripts/docs/confirm_ui.md) owns the schema, lifecycle, and fallback contract.+> ⛔ **GATE — final confirmation is the Design Spec input contract.** Immediately before authoring `design_spec.md`, re-read the complete final `result.json` with `stage: final` and `status: confirmed`; on a chat path, use the final visible confirmation summary as the equivalent state. 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.+### a. Canvas Format ConfirmationRecommend format based on scenario (see [`canvas-formats.md`](canvas-formats.md)).@@ -113,7 +115,7 @@ The deck's **narrative + persuasion skeleton** — how the argument is organized- 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. 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.-Write the locked value to `spec_lock.md` `- mode:` and record the rationale in `design_spec.md` (for `custom`, also write the sibling `- mode_behavior:` paragraph). Executor loads only that one mode file, or follows `mode_behavior` when the value is `custom`.+Record the confirmed mode and rationale in `design_spec.md` first, then project `- mode:` to `spec_lock.md` (for `custom`, also project the sibling `- mode_behavior:` paragraph). Executor loads only that one mode file, or follows `mode_behavior` when the value is `custom`.#### Layer 2 — Visual style@@ -129,7 +131,7 @@ The deck's **visual aesthetic** — shape language, decoration density, whitespa**Carries no color.** A visual style governs how the deck's HEX (locked at `e`) is *used* — never which colors, same discipline as [`image-renderings`](./image-renderings/_index.md). When the deck has AI images, prefer the style's paired rendering so layout and illustration share one aesthetic.-Write the locked value to `spec_lock.md` `- visual_style:` and the rationale to `design_spec.md`. Executor loads only that one visual-style file.+Record the confirmed visual style and rationale in `design_spec.md` first, then project `- visual_style:` to `spec_lock.md`. Executor loads only that one visual-style file.**Conditional template workspace**: When Generate Step 3 installed an explicit workspace path into `<project_path>/templates/`, read [`strategist-template.md`](./strategist-template.md) before completing Stage 2. It owns the editable natural-language application plan, confirmed-value consumption, AI-authored prototype selection, internal reuse/adherence derivation, inherited design precedence, and structured-lock planning. Bare names, style words, and free-design projects do not trigger it.@@ -379,13 +381,33 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck### 6.2 Planning Artifact Content-Generate Step 4 scaffolds both artifacts. `design_spec.md` is the human-readable page narrative; `spec_lock.md` is the exact machine contract. Their schemas own their separate structures. Do not duplicate the lock in prose or require cross-file textual equality.+Generate Step 4 owns both artifact scaffolds. `design_spec.md` is the Strategist's human-readable design decision; `spec_lock.md` is its machine-readable execution projection. Author them in that order. Never treat the two files as parallel interpretations of `result.json`, and never let lock authoring become a second design pass.++1. Re-read the complete final confirmation state.+2. Write the full `design_spec.md` from that state plus source analysis. 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.+3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before creating `spec_lock.md`.+4. Derive `spec_lock.md` only from the completed Design Spec. Project the exact values needed by Executor without adding a new recommendation, preference, or interpretation.++**Final confirmation → Design Spec consumption map**:++| 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 |+| 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 |+| 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 | Their owning Generate stage consumes them; 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.-Fill the scaffolded artifacts from the confirmed state and analysis. 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. Run `project_manager.py validate` after both artifacts are filled.+⛔ **GATE 2 — lock projection fidelity.** After the Design Spec passes Gate 1, project its machine-relevant decisions into `spec_lock.md`. The lock may normalize syntax for its schema, but it must not change meaning or introduce an independent choice. If a projection exposes a contradiction or missing decision, return to Gate 1, repair the Design Spec from the final confirmation, and regenerate the affected lock rows.-**Execution lock content**: `spec_lock.md` is the compact communication and execution contract for colors, typography, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Do not copy `content_divergence` into the lock; its effect is already authored into §IX. 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). The design brief may summarize choices, but exact values come only from the lock; never repair it from prose or rewrite the brief solely for equality.+**Execution lock content**: `spec_lock.md` is the compact machine projection of the completed Design Spec for colors, typography, 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. Project every §VIII image row with its acquisition source so downstream routing cannot infer a different one. Do not copy `content_divergence` into the lock; its effect is already authored into §IX. 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 final confirmation, then re-project the lock.- - **Communication trace is mandatory**: Copy `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, and canonical `consumption_mode` into `spec_lock.md communication`. 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 section / field presence, not the subjective quality of the move.+ - **Communication trace is mandatory**: Project `audience`, `communication_intent`, `audience_outcome`, `core_message`, `delivery_context`, `artifact_afterlife`, and canonical `consumption_mode` from the audited Design Spec into `spec_lock.md communication`. 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 section / field presence, not the subjective quality of the move.- **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/references/visual-styles/_index.md b/skills/ppt-master/references/visual-styles/_index.mdindex c35a1461..37bb4fef 100644--- a/skills/ppt-master/references/visual-styles/_index.md+++ b/skills/ppt-master/references/visual-styles/_index.md@@ -92,7 +92,7 @@ Each style has its own file with: shape & decoration, typography character, colo## 3. Escape hatch — `custom`-When no preset captures the intended aesthetic, set `- visual_style: custom` in `spec_lock.md` and add a `- visual_style_behavior:` line: one paragraph naming shape language, composition geometry (page-scale moves), decoration density, whitespace, typographic character, and texture — **no HEX, no color names as values**. `custom` is a tail-case, not a default; reach for a preset first.+When no preset captures the intended aesthetic, record the confirmed custom aesthetic in the Design Spec first, then project `- visual_style: custom` plus a `- visual_style_behavior:` line to `spec_lock.md`: one paragraph naming shape language, composition geometry (page-scale moves), decoration density, whitespace, typographic character, and texture — **no HEX, no color names as values**. `custom` is a tail-case, not a default; reach for a preset first.---@@ -100,7 +100,7 @@ When no preset captures the intended aesthetic, set `- visual_style: custom` in1. Strategist reads this index at confirmation `d. Layer 2`.2. Pick one style from the auto-selection table + the deck's vibe.-3. Lock it: write `- visual_style: <name>` into `spec_lock.md`, record rationale in `design_spec.md`.+3. Record the confirmed style and rationale in `design_spec.md`, then project `- visual_style: <name>` into `spec_lock.md`.4. Executor reads **only** `visual-styles/<locked-style>.md` at generation entry — never globs this directory.**Lock scope**: deck-wide (one style per deck). It anchors taste as a **reference**, not a whitelist — pages may deviate with reason.diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex a86395a8..ce2ef4c8 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -186,12 +186,12 @@ After Stage 2 is confirmed, overwrite it with Stage-3 production recommendations- `recommend.*` names the recommended `id` for each enumerable field (must match a `catalogs.json` id, or be a free string for a recommended custom value). The page badges and pre-selects it. **Guarantee**: if a `recommend.*` is omitted, the page falls back to the first catalog option so every enumerable field always shows one badged recommendation — but the AI should still set them for a meaningful default. Legacy aliases are accepted for old files (`line` → `tabler-outline`, `filled` → `tabler-filled`, `monochrome` → `chunk-filled`, `search` → `web`, `default` → `auto`, `builtin` → `host-native`), but new files should write canonical ids.- `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, while the six communication keys remain present as key lines in `spec_lock.md communication`. `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 `design_spec.md` / `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; never replace it with internal reuse/adherence ids or a fixed option menu.+- 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.- `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.-- **Color candidates carry the user-facing core `palette`**: `background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, and `body_text`. The page renders labelled swatches and offers per-role override inputs for precise single-role edits, plus a **Custom color card with a free-text box** (parallel to the custom typography box) — the user can describe the palette in words or paste HEX values instead of filling each role; this writes `color: { "name": "custom", "custom": "<text>" }` to `result.json` for the AI to interpret. Legacy `text` is accepted as an alias for `body_text`, but new files should write `body_text`. Strategist derives secondary text, borders, state colors, and visual-style neutral tiers later when writing `design_spec.md` / `spec_lock.md`; those are not user-facing confirmation choices.+- **Color candidates carry the user-facing core `palette`**: `background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, and `body_text`. The page renders labelled swatches and offers per-role override inputs for precise single-role edits, plus a **Custom color card with a free-text box** (parallel to the custom typography box) — the user can describe the palette in words or paste HEX values instead of filling each role; this writes `color: { "name": "custom", "custom": "<text>" }` to `result.json` for the AI to interpret. Legacy `text` is accepted as an alias for `body_text`, but new files should write `body_text`. Strategist derives secondary text, borders, state colors, and visual-style neutral tiers while writing `design_spec.md`, then projects the machine values to `spec_lock.md`; those are not user-facing confirmation choices.- **Candidate display text may be multilingual**: color / typography candidates can provide `name_zh` / `name_en` / `name_ja` and `note_zh` / `note_en` / `note_ja`; the page falls back to legacy `name` / `note`. Labels resolve in the page language first, then fall back across the others (a `ja` page: ja → en → zh; zh/en pages keep their zh↔en fallback and try `_ja` last), so when `lang` is `ja` always include the `_ja` variants — otherwise the candidate labels render in English.- **Typography candidates split CJK and Latin** for both `heading` and `body`; `css` is the fallback preview stack. Each candidate includes topic-matched sample text. Stage 2 is authored once with a reading-mode baseline of `text` 20 · `balanced` 24 · `presentation` 32 px on PPT. Font cards choose family / character and preserve the current sizing state; they do not introduce a competing size recommendation. The page writes px directly. `delivery_purpose` remains the compatibility key only.- **Per-role size override** (parallel to color's per-role HEX override): besides `body_size`, the page exposes editable inputs for `title` / `subtitle` / `annotation`. The browser applies one documented deterministic dependency chain: `reading mode → body baseline → unpinned role sizes` (role ramp: `body ×` the §g ratios). Changing reading mode updates the body and all unpinned roles locally; changing body updates unpinned roles locally. Editing body or a role pins that value, so later reading-mode changes do not overwrite it. Font / direction-card selection preserves all current sizes. This is a browser-only state update: it performs no fetch, asks the backend to author no new recommendations, and a re-render preserves exactly what the user sees. Each role input is labelled as px and shows an approximate pt equivalent (`1px = 0.75pt`) for orientation. The final values are written to `result.json` as `typography.sizes: { "title", "subtitle", "annotation" }` in **px** — every canvas, no pt and no `sizes_pt` provenance. Candidate `sizes` remain accepted for compatibility, but the fresh Stage-2 baseline is normalized through the same local ramp before first render.@@ -238,6 +238,8 @@ After Stage 2 is confirmed, overwrite it with Stage-3 production recommendationsThe shape above is the **final** result: Stage 1 owns the communication contract, Stage 2 owns the complete deck solution (including color / typography / icons / images), and Stage 3 adds production mechanics. Intermediate writes carry the accumulated earlier fields with `stage1-confirmed` or `stage2-confirmed`; legacy `tier1` / `tier2` remain read-compatible but are no longer written.+**Final-result consumption contract.** A final result is the user-confirmed input contract for the Strategist's Design Spec, not another recommendation input. The Strategist re-reads the complete final object, writes and audits `design_spec.md` against every explicitly present field, and may autonomously decide only details that remain unconfirmed. Only after that audit passes does it project `spec_lock.md` from the completed Design Spec; lock authoring is not a second design pass. 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.+- Any option field may instead hold a **free-text custom string** (the user picked **Custom**); `color` / `typography` custom entries set `name: "custom"`. Image usage is not a custom string in new results: it is a source-id array, with free-text strategy captured in `image_notes`.- `image_ai_path` and `image_strategy` are omitted from `result.json` unless `image_usage` includes `ai`. Both are honored downstream as confirmed choices — and the page is only a convenience surface over the **canonical chat channel**: the same choices made in chat are honored identically when no `result.json` exists. `image_ai_path` drives the Step 5 generation path (`image-generator.md` §7 — `host-native` forces the host tool even when `IMAGE_BACKEND` is set); the chosen `image_strategy` candidate is locked verbatim by [`strategist-image.md`](../../references/strategist-image.md) §2 (no re-pick).- 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 confirmation remains the fallback when the page cannot be used. 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.diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex bae9ceff..32179aaf 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -41,8 +41,10 @@ Notes:`templates/schemas/spec_lock.schema.json`. It reports missing sections andfields, illegal enums, malformed page keys, and unmet conditional sections;it does not rewrite either artifact or compare their values for textual- equality. The design schema is structural lint for the human-readable brief;- the lock schema owns machine execution values. For structured template use,+ equality. It also does not prove final-confirmation → Design Spec fidelity or+ Design Spec → lock semantic projection; Generate Step 4 owns those two gates+ before this structural validation. The design schema is structural lint for+ the human-readable brief; the lock schema owns machine execution values. For structured template use,validation also compares the lock's Master/Layout identities with the actualtemplate SVG roots. Versioned scaffolds carry the schema marker. Markerlesslegacy artifacts are left on their prior validation path with a warning;@@ -59,7 +61,9 @@ Notes:view on stdout. The default command is read-only; `--pretty` changes JSONformatting only. Before projection it revalidates only the machine lock and anyselected template-root identities; design-brief values are not treated as a-second lock. Slide headings at H3–H6 remain readable by the projector.+second lock. When present, the human-readable `Template Application` prose from+`design_spec.md §I` is projected as `global.template_application`. Slide+headings at H3–H6 remain readable by the projector.`--bundle` appends only the route-selected authoring payloads:| Project mode | Bundle contents |diff --git a/skills/ppt-master/scripts/page_context.py b/skills/ppt-master/scripts/page_context.pyindex ea500d85..ad5e6a9d 100644--- a/skills/ppt-master/scripts/page_context.py+++ b/skills/ppt-master/scripts/page_context.py@@ -611,6 +611,7 @@ def build_page_context(project: str | Path, raw_page: str) -> PageContextResult:except (OSError, ValueError) as exc:raise PageContextError(str(exc)) from exclock_sections = _section_index(lock_sections_raw)+ design_sections_index = _section_index(design_sections)part, brief = _slide_block(design_sections, page_number)warnings: list[str] = []rhythm_fields = _section_fields(lock_sections, "page_rhythm")@@ -684,6 +685,10 @@ def build_page_context(project: str | Path, raw_page: str) -> PageContextResult:global_context = {"communication": _section_fields(lock_sections, "communication"),"canvas": _section_fields(lock_sections, "canvas"),+ "template_application": _section_fields(+ design_sections_index,+ "I. Project Information",+ ).get("Template Application"),"mode": _section_fields(lock_sections, "mode").get("mode"),"visual_style": _section_fields(lock_sections,diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex 74258f47..8e53b3d2 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -2,6 +2,8 @@Project-level `design_spec.md` is a human-readable English-heading Markdown artifact. [`schemas/design_spec.schema.json`](./schemas/design_spec.schema.json) provides structural lint for readable sections and page projection; it is not an execution lock and does not require textual equality with `spec_lock.md`. Authoring starts from [`scaffolds/design_spec.md`](./scaffolds/design_spec.md).+Strategist writes this artifact from the complete final confirmation plus source analysis, audits every confirmed field here first, and only then projects `spec_lock.md` from the completed Design Spec.+## 1. Create the artifactRun the scaffold command once, then replace every `[fill]` value while preserving the section headings:@@ -18,7 +20,7 @@ The command refuses to shadow any recognized existing design-spec artifact, incl| Section | Required content | Conditional content || --- | --- | --- |-| I. Project Information | Project and confirmed communication context | Template reuse rows only when a template workspace is active |+| I. Project Information | Project and confirmed communication context | `Template Application` prose when template-active || II. Canvas Specification | Format, dimensions, viewBox, margins | — || III. Visual Theme | Mode, visual style, colors | `### AI Image Strategy` when §VIII contains an `ai` row || IV. Typography System | Per-role stacks and locked size slots | Additional recurring roles when used |@@ -41,7 +43,7 @@ python3 skills/ppt-master/scripts/project_manager.py validate <project_path>Validation reads the Markdown directly. It reports missing or out-of-order I–X sections, unresolved `[fill...]` scaffold placeholders, missing per-slide `Audience move`, and a missing §III `AI Image Strategy` when an §VIII table selects `ai` acquisition.-The schema owns structure only. Strategist role modules own field meaning, recommendation logic, page planning, image policy, and template policy. `spec_lock.md` owns the compact execution values; on divergence, the lock wins.+The schema owns structure only. Strategist role modules own field meaning, recommendation logic, page planning, image policy, and template policy. `spec_lock.md` owns the compact execution projection. On divergence, first repair the Design Spec from the final confirmation when Gate 1 fails; otherwise repair the lock from the audited Design Spec. Never use the lock to overwrite a valid Design Spec decision.---diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 82e6fc82..7e49f814 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -152,7 +152,7 @@ Read references/strategist.mdThe core first chooses the proposed Stage 2 source ids. Load the image module before writing Stage 2 whenever that proposal is non-`none`; after confirmation, keep it active only for confirmed non-`none` sources or an active formula plan. A confirmed `none` path with no formula work writes no image rows. Bare template names and style language do not load the template module.-> ⚠️ **Mandatory artifact gate**: scaffold the human-readable `design_spec.md` and machine-readable `spec_lock.md`; do not reconstruct lock grammar from memory. The design schema only keeps the brief readable and page-projectable—it is not a second execution lock, and cross-file textual equality is not required. Reference indexes are for troubleshooting, not normal generation load.+> ⚠️ **Mandatory artifact gates**: scaffold the human-readable `design_spec.md` first; after it passes confirmation fidelity, scaffold the machine-readable `spec_lock.md` and project from the Design Spec. Do not reconstruct either grammar from memory. The design schema keeps the brief readable and page-projectable; the lock schema keeps its execution projection machine-readable. Cross-file textual equality is not required, but semantic projection fidelity is. Reference indexes are for troubleshooting, not normal generation load.**Artifact ownership**: fact-channel and source/derived artifact boundaries are defined in [`references/artifact-ownership.md`](../references/artifact-ownership.md). This Step uses those ownership rules; it does not redefine them.@@ -190,13 +190,17 @@ The core first chooses the proposed Stage 2 source ids. Load the image module bepython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only```-4. On any non-zero wait, re-read `result.json` once before using the documented chat fallback. A stage-skip result returns to the missing stage; it is not a browser failure. After final confirmation or chat fallback, always release the server:+4. After the final wait returns, re-read the complete `result.json` even when the wait succeeded. Proceed from the file only when it carries `stage: final` and `status: confirmed`. On a non-zero wait, perform this same read before using the documented chat fallback. A stage-skip result returns to the missing stage; it is not a browser failure.++5. After final confirmation or chat fallback, always release the server:```bashpython3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --shutdown```-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. Every path must preserve the final visible values; writing `design_spec.md`, `spec_lock.md`, and later pages consumes that state without a hidden repair or second recommendation pass. Map confirmed image sources through `strategist.md` §h, apply `strategist-template.md` §3 for an active template, and never write a separate image palette.+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 — write the Design Spec from the final state, then project the lock.** 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, including every confirmed image source and explicit `image_notes` role. Only after that audit passes, derive `spec_lock.md` from the completed Design Spec without making another design decision. 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.**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:@@ -224,24 +228,30 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images- `<project_path>/design_spec.md` — human-readable design narrative- `<project_path>/spec_lock.md` — machine-readable communication + execution contract; Executor consumes its current-page projection from `page-context`-For a new artifact pair, run these commands once after final confirmation and before filling the files; each refuses to overwrite an existing artifact:+For a new project, scaffold the Design Spec after final confirmation; the command refuses to overwrite an existing artifact:```bashpython3 ${SKILL_DIR}/scripts/project_manager.py scaffold-spec <project_path>+```++Fill and audit `design_spec.md` against the complete final confirmation. Only after that audit passes, scaffold and fill the machine lock from the completed Design Spec:++```bashpython3 ${SKILL_DIR}/scripts/project_manager.py scaffold-lock <project_path>```-After filling both files, run `python3 ${SKILL_DIR}/scripts/project_manager.py validate <project_path>` and repair schema findings in their owning artifact before the checkpoint. A resume path edits the existing files and never re-scaffolds them.+After filling the lock, compare its machine-relevant values against the completed Design Spec, then run `python3 ${SKILL_DIR}/scripts/project_manager.py validate <project_path>`. A `result.json` → Design Spec mismatch or Design Spec → lock projection mismatch is blocking even when the standalone Markdown schemas pass. Repair the Design Spec only from the final confirmation state, then re-project the affected lock rows. A resume path edits existing files in the same order and never re-scaffolds them.**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:```markdown## ✅ Strategist Phase Complete- [x] Read the auto-extracted facts already in `analysis/` (e.g. `source_profile.json`) before the Strategist confirmation stage- [x] Strategist confirmation stage completed (user confirmed via Confirm UI `result.json` or chat fallback)+- [x] Final confirmation re-read; `design_spec.md` audited field by field against it with no confirmed value omitted, substituted, or weakened- [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] Execution lock (spec_lock.md) generated+- [x] Execution lock (`spec_lock.md`) projected from the completed Design Spec with no independent design decision- [x] Communication trace validated: `spec_lock.md ## communication` contains all six contract key lines (optional values may be blank), and every `design_spec.md §IX` Slide block has an `Audience move`- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase```@@ -252,7 +262,7 @@ After filling both files, run `python3 ${SKILL_DIR}/scripts/project_manager.py v🚧 **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.+> **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 final confirmation that selected `ai` or `web` without a matching §VIII resource row is an incomplete Design Spec, not a reason to skip Step 5; return to Step 4 Gate 1, repair the Design Spec from the final confirmation, and re-project the lock.**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.@@ -366,7 +376,7 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemonpython3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> --bundle --record-usage```-Use this canonical projection for the global communication contract, current §IX `Core message` + `Audience move`, locked colors/fonts/icons/images, and current-page rhythm/chart/structure assignments. Flat bundles contain only page context; `layout` bundles also contain the selected complete prototype; `mirror` bundles contain that prototype plus its minimal text-slot view. This derived view does not replace `design_spec.md`, `spec_lock.md`, their gates, or any source facts needed by the page. See [`executor-base.md`](../references/executor-base.md) §2.1 and [`executor-structured.md`](../references/executor-structured.md) §1.0.+Use this projection for communication, optional `global.template_application`, current §IX `Core message` + `Audience move`, locked resources, and current-page assignments. Flat bundles contain page context; `layout` adds the selected complete prototype; `mirror` also adds its minimal text-slot view. The projection replaces neither gate artifacts nor source facts. See [`executor-base.md`](../references/executor-base.md) §2.1 and [`executor-structured.md`](../references/executor-structured.md) §1.0.> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).@@ -375,7 +385,7 @@ Use this canonical projection for the global communication contract, current §IEach 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 all inherited visible objects in `svg_output/`, and preserve the locked root Master/Layout identity plus stable atomic Master/Layout and slot ids. Strict keeps the prototype structure unchanged. Adaptive keeps its Master contract and, when Layout atoms or slot topology/bounds genuinely evolve, assigns a new key/name and updates `spec_lock.md` immediately. `layout` pages may reflow and re-skin to the project lock; `mirror` pages preserve literal visuals and may change only visible `<text>` / `<tspan>` values while keeping text/tspan count, order, nesting, and every attribute unchanged. `template_reuse_scope: style` follows the flat free-design paragraph below and does not inherit template structure metadata.+`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`, `global.template_application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive assigns a new Layout key/name and updates `spec_lock.md` when fixed atoms or slot topology/bounds change. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.`template_reuse_scope: 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.mdindex fe38a6f4..2e534aff 100644--- a/skills/ppt-master/workflows/governance/failure-recovery.md+++ b/skills/ppt-master/workflows/governance/failure-recovery.md@@ -18,6 +18,8 @@ Global stop/continue rules for all four top-level routes, plus concrete failure| Confirm UI wait timeout | No, if no final result yet | Re-check `result.json` once; keep server cleanup mandatory | Only if user still wants the page | Step 4 same stage or chat fallback || Confirm UI Stage 1 completed then interrupted | Yes until Stage 2 is written/confirmed | Read existing Stage 1 `result.json`, write Stage 2 recommendations, then `--wait-only --wait-stage stage2` | Usually no | Step 4 Stage 2 write/wait || 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 | Re-read the complete final confirmation state and repair the Design Spec before touching the lock | Only when the confirmed value genuinely cannot be honored | Step 4 Gate 1 — confirmation fidelity |+| `spec_lock.md` changes or omits a machine-relevant Design Spec decision | Yes | Re-project the affected lock rows from the completed Design Spec without making a new design choice | No unless the Design Spec itself is incomplete | Step 4 Gate 2 — lock projection fidelity || 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 |@@ -49,7 +51,7 @@ Global stop/continue rules for all four top-level routes, plus concrete failure| Derived artifact stale | Regenerate it from its owning source. || Required manual artifact missing | Pause and name the exact required artifacts; resume only after they exist. || Validation or export failure | Fix the owning source artifact, then rerun the failed operation and affected downstream operations only. |-| Confirmed execution choice cannot be honored | Retry the confirmed provider, mode, voice, effect, or path only as its owning workflow allows; if it remains unavailable, stop, request a new decision, or hand off through the owning workflow's declared manual fallback (e.g. `Needs-Manual` with a user summary). Never switch to another automated value or path silently. |+| Confirmed execution choice cannot be honored | Keep the confirmed requirement visible. Retry the confirmed provider, mode, voice, effect, or path only as its owning workflow allows; if it remains unavailable, stop, request a new decision, or hand off through the owning workflow's declared manual fallback (e.g. `Needs-Manual` with a user summary). Never omit it or switch to another automated value or path silently. |**Missing values**: For a field in an existing artifact, follow only the exact requiredness, inference procedure, or fixed default declared by its owning schema or workflow; an active omission with no such rule stops at the owning boundary. Empty values, inactive conditional fields, whole artifacts, derived artifacts, and file-format attributes keep their own declared semantics—do not extend a fallback by analogy. Owning rules label their fallbacks with two terms used across this repository: a **declared-inference / declared-procedure fallback** states its missing condition and a bounded procedure that needs no new user decision; a **fixed compatibility default** states the exact fallback value, applied with one warning.@@ -65,8 +67,10 @@ Here, **final confirmation evidence** means either the explicit final confirmati|---|---|| Stage 1 confirmation exists, Stage 2 missing | Write Stage 2 recommendations, then `confirm_ui/server.py <project> --wait-only --wait-stage stage2` || Stage 2 confirmation exists, final confirmation missing | Resume [`generate-pptx`](../generate-pptx.md) Step 4 confirmation orchestration at Stage 3: derive production mechanics from the confirmed solution, then perform the final wait. |-| Final confirmation evidence exists; `design_spec.md` is missing, with or without a surviving `spec_lock.md` | Return to Generate Step 4 and [`strategist.md`](../../references/strategist.md) §6.2; scaffold the missing artifact and regenerate `design_spec.md` and `spec_lock.md` together from the source material and confirmed state. Do not reconstruct the outline from an orphan lock. |-| Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to Generate Step 4, run `project_manager.py scaffold-lock`, and fill the lock from the confirmed state plus the design spec under [`strategist.md`](../../references/strategist.md) §6.2. |+| Final confirmation evidence exists; `design_spec.md` is missing, with or without a surviving `spec_lock.md` | Return to Generate Step 4 and [`strategist.md`](../../references/strategist.md) §6.2; scaffold and write `design_spec.md` from the final confirmation and source analysis, pass Gate 1, then replace the orphan lock's affected rows by projecting from the completed Design Spec. Never reconstruct the Design Spec from an orphan lock. |+| Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to Generate Step 4, audit the existing Design Spec against the final confirmation first, then run `project_manager.py scaffold-lock` and fill the lock only from the audited Design Spec. |+| Final confirmation evidence and both planning artifacts exist, but Gate 1 fails | Repair `design_spec.md` from the final confirmation, then re-project every affected lock row. Do not reopen recommendations or infer a replacement from the current lock. |+| Gate 1 passes but Gate 2 fails | Keep the Design Spec unchanged and re-project only the mismatched lock rows from it. || No final confirmation evidence is available | Resume Step 4 from the latest stage evidenced by `confirm_ui/result.json`; if no stage is persisted, restart Step 4 at Stage 1. Do not infer confirmed choices from partial planning artifacts. || `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](../stages/resume-execute.md) || Images acquired but SVGs not started | [`generate-pptx`](../generate-pptx.md) Step 6 |diff --git a/skills/ppt-master/workflows/stages/refine-spec.md b/skills/ppt-master/workflows/stages/refine-spec.mdindex 39473af9..92f8a78d 100644--- a/skills/ppt-master/workflows/stages/refine-spec.md+++ b/skills/ppt-master/workflows/stages/refine-spec.md@@ -26,7 +26,7 @@ The user **explicitly asks** to refine / review / revise the spec before generat## Step 1: Produce the full spec-Run the default Strategist output exactly as [`generate-pptx`](../generate-pptx.md) Step 4 specifies: write `design_spec.md` (§I–X) and `spec_lock.md`. Read the relevant `sources/` files so the content outline (`§IX`) carries real facts, not skeleton points. Nothing special here — this is the normal spec, just produced under the knowledge that the user is about to review it.+Run the default Strategist output exactly as [`generate-pptx`](../generate-pptx.md) Step 4 specifies: write `design_spec.md` (§I–X) from the final confirmation, pass the confirmation-fidelity gate, then project `spec_lock.md` from the completed Design Spec. Read the relevant `sources/` files so the content outline (`§IX`) carries real facts, not skeleton points. Nothing special here — this is the normal spec, just produced under the knowledge that the user is about to review it.---@@ -45,11 +45,11 @@ The user may revise **any part of the spec**, not just the outline — content o- *Icon / image*: one consistent icon character throughout; images that serve the content (hero / atmosphere used on purpose) rather than decorate.- *Page rhythm*: do `anchor` / `dense` / `breathing` track the narrative, or is everything flatly dense.-These overlap with what the locked `mode`, visual style, and §6.1 already shape — treat them as discussion angles to surface what is worth talking about, not a second pass to redo.+These overlap with what the confirmed `mode`, visual style, and §6.1 already shape — treat them as discussion angles to surface what is worth talking about, not permission for the Strategist to redo a decision without the user's explicit revision.-**Keep both files in sync on every change.** Any revision the user approves must land in both `design_spec.md` and `spec_lock.md`; on divergence `spec_lock.md` wins (see [`strategist.md`](../../references/strategist.md) §6.2). Iterate as many rounds as the user wants. The loop ends only when the user explicitly approves the spec.+**Revise the Design Spec first, then re-project the lock.** An explicit revision the user approves becomes the latest authority for the affected decision and supersedes its earlier confirmation value. Apply it to `design_spec.md` first, then re-project every affected machine value into `spec_lock.md`; lock authoring never decides or overrides the revision. On divergence, repair the lock from the approved Design Spec (see [`strategist.md`](../../references/strategist.md) §6.2). Iterate as many rounds as the user wants. The loop ends only when the user explicitly approves the spec.-**Re-run the route/template preflight after reuse revisions.** If the user changes `template_reuse_scope`, `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the preflight in [`strategist-template.md`](../../references/strategist-template.md) before approval and hand-back. Switching to `style` rewrites the route to `pptx_structure.mode: flat` and removes all structure mappings/adherence; switching to `mirror` / `layout` restores a complete structured contract. Every newly selected structured prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments in both artifacts immediately. A legacy prototype is not selectable; create a current workspace through [`create-template`](../create-template.md) before refinement.+**Re-run the route/template preflight after reuse revisions.** If the user changes `template_reuse_scope`, `template_adherence`, `page_layouts`, the Master/Layout definition roster, or any `page_pptx_layouts` assignment, repeat the preflight in [`strategist-template.md`](../../references/strategist-template.md) before approval and hand-back. Switching to `style` rewrites the route to `pptx_structure.mode: flat` and removes all structure mappings/adherence; switching to `mirror` / `layout` restores a complete structured contract. Every newly selected structured prototype must declare root Master/Layout identity, direct atomic Master/Layout visuals, and valid top-level slot groups with positive bounds plus one compatible carrier or explicit composite `object` proxy. A zero-slot Layout is valid. Update the human-facing prototype decisions in the Design Spec first, then re-project `pptx_masters`, unique `pptx_layouts` definitions, and complete `page_pptx_layouts` assignments into the lock. A legacy prototype is not selectable; create a current workspace through [`create-template`](../create-template.md) before refinement.---