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
refactor(planning): restore whole-document spec authoring
hugohe30bc7454cc430
diff --git a/AGENTS.md b/AGENTS.mdindex 8c99bf52..28ff8bed 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -47,8 +47,8 @@ python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or# Project managementpython3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs_or_URLs...> --move-python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path>-python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path>+python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path> # optional manual helper+python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path> # optional manual helperpython3 skills/ppt-master/scripts/project_manager.py validate <project_path># Icon selection — copy chosen library icons into <project>/icons/ (missing names reported + non-zero = re-pick)diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.mdindex 04f4dc17..b6767b1e 100644--- a/skills/ppt-master/references/strategist-image.md+++ b/skills/ppt-master/references/strategist-image.md@@ -47,7 +47,7 @@ Follow `latex_render.py --help` for the manifest fields. The renderer writes dim## 4. Image Resource List-Add §VIII rows for the image resources actually planned from the confirmed source boundary and for every selected formula; a formula-only plan contains only formula rows. A permitted but unused source needs no row. Fill the scaffold's filename, dimensions/ratio, layout pattern, crop policy, purpose/type, acquisition, status, reference, and conditional AI fields. `Acquire Via` is `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`; status follows [`svg-image-embedding.md`](./svg-image-embedding.md). When a planned or explicitly required asset is not yet available, retain its row as `Pending` or `Needs-Manual`; never remove the row or change `Acquire Via` to make the Design Spec look complete. After §VIII passes final confirmation, project every placed row into `spec_lock.md images` as `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>` and omit unplaced Illustration Sheets. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web uses a concrete subject plus a few positive quality descriptors; formula preserves the source LaTeX and placement intent.+Add §VIII rows for the image resources actually planned from the confirmed source boundary and for every selected formula; a formula-only plan contains only formula rows. A permitted but unused source needs no row. Author each row's filename, dimensions/ratio, layout pattern, crop policy, purpose/type, acquisition, status, reference, and conditional AI fields as part of the complete Design Spec. `Acquire Via` is `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`; status follows [`svg-image-embedding.md`](./svg-image-embedding.md). When a planned or explicitly required asset is not yet available, retain its row as `Pending` or `Needs-Manual`; never remove the row or change `Acquire Via` to make the Design Spec look complete. After §VIII passes final confirmation, project every placed row into `spec_lock.md images` as `<path> | source=<Acquire Via> | pattern=<Layout pattern> | crop=<adaptive|no-crop>` and omit unplaced Illustration Sheets. References describe visual intent: AI uses subject + intent + composition without repeating rendering or HEX; web uses a concrete subject plus a few positive quality descriptors; formula preserves the source LaTeX and placement intent.🚧 **GATE — non-formula rows**: read every entry in [`image-layout-patterns.md`](./image-layout-patterns.md). Copy one primary `#<id> <name>` plus any modifier names verbatim into each row; no empty, paraphrased, or invented ids. Strategist owns that pattern selection; Executor adapts its geometry while retaining the selected primary/modifier semantics, resource role, and explicit constraints. Audit the completed column against page intent: repeated left/right or top/bottom structures are valid when the narrative calls for them, but catalog families and modifiers must remain available without a usage quota.diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 487244a7..91e82345 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -20,7 +20,7 @@ As a top-tier AI presentation strategist, receive source documents, perform cont## 1. Strategist Confirmation Stage-🚧 **GATE — artifact structure**: Generate Step 4 creates both versioned scaffolds before authoring. Fill those files in place and run `project_manager.py validate`; the machine schemas, not remembered headings, own their grammar.+🚧 **GATE — whole-document authoring**: Generate Step 4 reads `templates/design_spec_reference.md`, writes the complete Design Spec from scratch, passes Gate 1, then reads `templates/spec_lock_reference.md` and writes the complete lock projection. For a new project, create each finished artifact once; do not instantiate or patch a placeholder scaffold. Run `project_manager.py validate`; the machine schemas, not remembered headings, own grammar validation.⛔ **BLOCKING**: After the read, present professional recommendations for the confirmation fields below and wait for explicit user confirmation.@@ -386,12 +386,12 @@ This is what makes the axis meaningful: a `presentation` deck and a `text` deck### 6.2 Planning Artifact Content-Generate Step 4 owns both artifact scaffolds. `design_spec.md` is the Strategist's complete human-readable design decision; `spec_lock.md` is the context-selected execution subset and routing contract. Author them in that order. `result.json` is read once into the active final-confirmation state and consumed completely while writing the Design Spec. Never reopen it to author the lock, and never treat the two planning files as parallel interpretations of the confirmation.+Generate Step 4 owns this reference-first sequence. `design_spec.md` is the Strategist's complete human-readable design decision; `spec_lock.md` is the context-selected execution subset and routing contract. `result.json` is read once into the active final-confirmation state and consumed completely while writing the Design Spec. Never reopen it to author the lock, and never treat the two planning files as parallel interpretations of the confirmation.-1. Use the retained complete final-confirmation state already read once by Generate Step 4.-2. Write `design_spec.md` from that state, source analysis, and project context; record production mechanics in §I. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, final wording, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1, roster ids/count/order and content are authoritative; layout, cover/closing composition, and image/chart patterns remain References unless promoted.-3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before creating `spec_lock.md`.-4. Author `spec_lock.md` from the completed Design Spec plus the current execution context: retain confirmed identity anchors, select stable cross-page roles and routing values, and omit page-local values that need no reusable name. This is implementation judgment, not a second user-facing recommendation.+1. Use the retained complete final-confirmation state already read once by Generate Step 4, then read `templates/design_spec_reference.md`.+2. Compose the whole Design Spec in active context before touching the target path. Create `design_spec.md` once from the schema marker through §X; do not copy a scaffold into the project or patch placeholder fields. Record production mechanics in §I. In §IX, create the complete ordered roster; each entry carries layout, title, core message, **Audience move**, final wording, visualization/image references, sourced `Fact IDs`, and `Data class: scenario` for invented demo data. After Gate 1, roster ids/count/order and content are authoritative; layout, cover/closing composition, and image/chart patterns remain References unless promoted.+3. Compare `design_spec.md` against the final confirmation field by field. Repair every omission or deviation before authoring `spec_lock.md`.+4. After Gate 1, read `templates/spec_lock_reference.md`. Compose the whole lock in active context from the completed Design Spec plus current execution context, then create `spec_lock.md` once. Retain confirmed identity anchors, select stable cross-page roles and routing values, omit page-local values that need no reusable name, and do not reopen final evidence. This is implementation judgment, not a second user-facing recommendation.**Final confirmation → Design Spec consumption map**:@@ -431,7 +431,7 @@ Generate Step 4 owns both artifact scaffolds. `design_spec.md` is the Strategist## 7. Project Boundary-The Generate route owns project initialization and supplies `<project_path>`. Strategist writes only the two scaffolded planning artifacts at that root plus the explicitly triggered resource manifests; it does not choose or create another project path.+The Generate route owns project initialization and supplies `<project_path>`. Strategist writes only the two complete planning artifacts at that root plus the explicitly triggered resource manifests; it does not choose or create another project path.---diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 50c31ca7..182d3ea3 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -73,8 +73,8 @@ Project setup:```bashpython3 scripts/project_manager.py init <project_name> --format ppt169python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move-python3 scripts/project_manager.py scaffold-spec <project_path>-python3 scripts/project_manager.py scaffold-lock <project_path>+python3 scripts/project_manager.py scaffold-spec <project_path> # optional manual helper+python3 scripts/project_manager.py scaffold-lock <project_path> # optional manual helperpython3 scripts/project_manager.py validate <project_path>python3 scripts/project_manager.py page-context <project_path> P07 --record-usagepython3 scripts/project_manager.py page-context-report <project_path>diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex 1865b257..96fd607b 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -13,8 +13,8 @@ Main entry point for project setup and validation.```bashpython3 scripts/project_manager.py init <project_name> --format ppt169python3 scripts/project_manager.py import-sources <project_path> <source1_or_dir> [<source2_or_dir> ...]-python3 scripts/project_manager.py scaffold-spec <project_path>-python3 scripts/project_manager.py scaffold-lock <project_path>+python3 scripts/project_manager.py scaffold-spec <project_path> # optional manual helper+python3 scripts/project_manager.py scaffold-lock <project_path> # optional manual helperpython3 scripts/project_manager.py validate <project_path>python3 scripts/project_manager.py info <project_path>python3 scripts/project_manager.py page-context <project_path> P07 [--pretty] [--record-usage]@@ -35,7 +35,11 @@ Notes:note), to avoid leaving unintended artifacts that could be committed by mistake.Pass `--copy` to force a copy for in-repo sources instead.- `--move` and `--copy` are mutually exclusive.-- `scaffold-spec` creates `design_spec.md` from+- Normal Generate authoring reads `templates/design_spec_reference.md`, writes+ the complete `design_spec.md` from scratch, then reads+ `templates/spec_lock_reference.md` and writes the complete lock projection.+ It does not call either scaffold command.+- Optional `scaffold-spec` creates `design_spec.md` from`templates/scaffolds/design_spec.md`; `scaffold-lock` creates `spec_lock.md`from `templates/scaffolds/spec_lock.md`. Both substitute project/canvasmetadata deterministically and refuse to overwrite an existing artifact.@@ -57,7 +61,8 @@ Notes:Master/Layout; adaptive input prototypes retain the assigned Master while anew output Layout already declared by Strategist is cross-validated after itsgenerated SVG exists. Versioned- scaffolds carry the schema marker. Markerless legacy artifacts are left on+ Direct-authored current artifacts and optional scaffolds carry the schema+ marker. Markerless legacy artifacts are left ontheir prior validation path with a warning;malformed or unsupported markers are errors.- PPTX-family inputs are enriched automatically under `analysis/` with@@ -124,8 +129,8 @@ Examples:```bashpython3 scripts/project_manager.py init my_presentation --format ppt169-python3 scripts/project_manager.py scaffold-spec projects/my_presentation_ppt169_20251116-python3 scripts/project_manager.py scaffold-lock projects/my_presentation_ppt169_20251116+python3 scripts/project_manager.py scaffold-spec projects/my_presentation_ppt169_20251116 # optional+python3 scripts/project_manager.py scaffold-lock projects/my_presentation_ppt169_20251116 # optionalpython3 scripts/project_manager.py validate projects/my_presentation_ppt169_20251116python3 scripts/project_manager.py info projects/my_presentation_ppt169_20251116python3 scripts/project_manager.py page-context projects/my_presentation_ppt169_20251116 P07 --record-usagediff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex d1e67854..d3abffe1 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -28,12 +28,12 @@"skills/ppt-master/references/svg-effects.md": 11600,"skills/ppt-master/references/native-data-interface.md": 6200,"skills/ppt-master/references/pptx-structure-interface.md": 4300,- "skills/ppt-master/references/strategist.md": 12900,+ "skills/ppt-master/references/strategist.md": 13000,"skills/ppt-master/references/strategist-image.md": 2100,"skills/ppt-master/references/strategist-template.md": 2100,- "skills/ppt-master/templates/design_spec_reference.md": 850,- "skills/ppt-master/templates/spec_lock_reference.md": 1650,- "skills/ppt-master/workflows/generate-pptx.md": 12300,+ "skills/ppt-master/templates/design_spec_reference.md": 2300,+ "skills/ppt-master/templates/spec_lock_reference.md": 1750,+ "skills/ppt-master/workflows/generate-pptx.md": 12400,"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800},"load_sets": {@@ -106,7 +106,7 @@"files": ["skills/ppt-master/workflows/native-enhance-pptx.md"],- "max_tokens": 8100+ "max_tokens": 8200},"route.fill-native-pptx": {"description": "Raw-PPTX native fill route.",@@ -120,7 +120,7 @@"max_tokens": 10800},"route.generate.planning": {- "description": "Generate-PPTX planning through Strategist, including representative multi-source custom mode/style synthesis; schemas and scaffolds are tool-consumed.",+ "description": "Generate-PPTX planning through Strategist, including reference-first whole-document authoring and representative multi-source custom mode/style synthesis; schemas and optional scaffolds are tool-consumed.","scope": "cumulative","include": ["bootstrap.routing"@@ -129,6 +129,8 @@"skills/ppt-master/workflows/generate-pptx.md","skills/ppt-master/references/artifact-ownership.md","skills/ppt-master/references/strategist.md",+ "skills/ppt-master/templates/design_spec_reference.md",+ "skills/ppt-master/templates/spec_lock_reference.md","skills/ppt-master/references/modes/_index.md","skills/ppt-master/references/visual-styles/_index.md","skills/ppt-master/scripts/docs/confirm_ui.md",@@ -304,7 +306,7 @@"stage.generate.executor.notes"],"files": [],- "max_tokens": 75500+ "max_tokens": 79400},"route.generate.flat-ai-two-types": {"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",@@ -317,7 +319,7 @@"stage.generate.image.ai-two-types"],"files": [],- "max_tokens": 116000+ "max_tokens": 119500},"route.generate.flat-in-hand-image": {"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.",@@ -329,7 +331,7 @@"stage.generate.executor.notes"],"files": [],- "max_tokens": 89000+ "max_tokens": 92800},"route.generate.flat-web-image": {"description": "Generate-PPTX context with web image acquisition.",@@ -342,7 +344,7 @@"stage.generate.image.web"],"files": [],- "max_tokens": 96500+ "max_tokens": 100100},"route.enhance-native-pptx.audio": {"description": "Enhance Native PPTX with the shared narration-audio stage.",@@ -362,7 +364,7 @@"profile.generate.beautify-pptx"],"files": [],- "max_tokens": 82000+ "max_tokens": 86200},"route.generate.flat-no-image-chart": {"description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",@@ -375,7 +377,7 @@"stage.generate.verify-charts"],"files": [],- "max_tokens": 99500+ "max_tokens": 103200},"route.generate.brand-flat-no-image": {"description": "Brand-preset flat Generate-PPTX path without image acquisition.",@@ -387,7 +389,7 @@"stage.generate.template.brand"],"files": [],- "max_tokens": 82200+ "max_tokens": 86400},"route.generate.deck-structured-no-image": {"description": "Deck-preset structured Generate-PPTX path without image acquisition.",@@ -399,7 +401,7 @@"stage.generate.template.deck"],"files": [],- "max_tokens": 92200+ "max_tokens": 96300},"route.generate.layout-structured-no-image": {"description": "Layout-preset structured Generate-PPTX path without image acquisition.",@@ -411,7 +413,7 @@"stage.generate.template.layout"],"files": [],- "max_tokens": 92700+ "max_tokens": 96800},"route.generate.topic-only-flat-no-image": {"description": "Topic research followed by the default flat no-image Generate-PPTX path.",@@ -421,7 +423,7 @@"route.generate.flat-no-image"],"files": [],- "max_tokens": 77000+ "max_tokens": 80800},"stage.generate.executor.flat": {"description": "Incremental flat Executor core with representative multi-source custom mode/style execution.",@@ -625,7 +627,7 @@"files": ["skills/ppt-master/workflows/governance/failure-recovery.md"],- "max_tokens": 2300+ "max_tokens": 2350},"stage.shared.conversion-reference": {"description": "Conditional source-conversion and import compatibility reference.",@@ -659,7 +661,7 @@"stage.generate.strategist.template"],"files": [],- "max_tokens": 54000+ "max_tokens": 57900},"route.generate.planning-template-ai": {"description": "Explicit template workspace plus confirmed AI-image planning.",@@ -669,16 +671,7 @@"route.generate.planning-ai"],"files": [],- "max_tokens": 66000- },- "stage.generate.artifact-schema-guide": {- "description": "Compact human guide loaded only to diagnose planning-artifact schema or scaffold failures.",- "scope": "incremental",- "files": [- "skills/ppt-master/templates/design_spec_reference.md",- "skills/ppt-master/templates/spec_lock_reference.md"- ],- "max_tokens": 2400+ "max_tokens": 70100},"stage.generate.executor.chart": {"description": "Conditional chart/table page execution rules.",@@ -1120,7 +1113,7 @@},{"glob": "skills/ppt-master/templates/scaffolds/*.md",- "reason": "Versioned tool-copy assets; project_manager materializes them into the project rather than prompt-loading them."+ "reason": "Optional versioned tool-copy assets; normal Generate authoring reads the reference guides and writes complete artifacts from scratch."},{"glob": "skills/ppt-master/templates/charts/charts_index.json",diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.mdindex 1506fda7..73927437 100644--- a/skills/ppt-master/templates/README.md+++ b/skills/ppt-master/templates/README.md@@ -75,10 +75,11 @@ readable; directory shape alone does not indicate legacy Master/Layout semantics## Design specification references-[`schemas/design_spec.schema.json`](./schemas/design_spec.schema.json) and-[`scaffolds/design_spec.md`](./scaffolds/design_spec.md) own the machine-structure and starting artifact; [`design_spec_reference.md`](./design_spec_reference.md)-is their compact authoring index. Reusable template `design_spec.md` files are+[`design_spec_reference.md`](./design_spec_reference.md) and+[`spec_lock_reference.md`](./spec_lock_reference.md) own normal whole-document+authoring; their schemas own machine validation. Files under `scaffolds/` are+optional overwrite-safe CLI conveniences, not Generate-route starting artifacts.+Reusable template `design_spec.md` files aredeliberately smaller: they contain portable metadata and only the identity,structure, or application rules owned by that package. General SVG rules livein [`shared-standards-core.md`](../references/shared-standards-core.md), withdiff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex a3efe315..ca4f2314 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -1,72 +1,206 @@# Design Spec Structure-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).+Project-level `design_spec.md` is a human-readable English-heading Markdown artifact. This file owns its normal authoring structure. [`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`.Strategist reads the complete final confirmation once, writes this artifact from that retained state plus source analysis, and audits every confirmed field here. Afterward, `spec_lock.md` is authored from the completed Design Spec plus current project/page/template context; normal lock authoring never reopens `result.json`.-## 1. Create the artifact+## 1. Author the complete artifact-Run the scaffold command once, then replace every `[fill]` value while preserving the section headings:+After final confirmation, compose the entire document in active context from the retained final state, source analysis, and project context. Then create `<project_path>/design_spec.md` once, from the first line through §X.-```bash-python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path>-```+**Mandatory — new-project write**: The first non-empty line is exactly `<!-- ppt-master-schema: design-spec/v1 -->`, followed by `# <Project Name> - Design Spec`. Write all ten sections with final values and the complete page roster. Do not create a placeholder-bearing project file, copy example rows, or patch a scaffold field by field.-The command refuses to shadow any recognized existing design-spec artifact, including legacy filenames. Re-running it in an otherwise equivalent empty project produces the same bytes.+`project_manager.py scaffold-spec` remains an optional manual convenience and overwrite-safe troubleshooting tool. It is not part of normal Generate authoring. Resume and refine paths edit an existing completed Design Spec rather than replacing it with a scaffold.----## 2. Section contract+## 2. Exact document contract-| Section | Required content | Conditional content |-| --- | --- | --- |-| 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 |-| V. Layout Principles | Page regions and project spacing | Template-specific constraints only when active |-| VI. Icon Usage Specification | Approved icon inventory | Empty table when no icons are used |-| VII. Visualization Reference List | Candidates and independent charts/tables with `Native-ready`, or empty | Incidental microvisuals stay in §IX |-| VIII. Image Resource List | Rows with `Layout pattern` and `Crop Policy`, or empty | AI columns apply only to `ai` rows |-| IX. Content Outline | Complete ordered execution roster; one Slide block per final page, matching the exact Page Count; each has `Audience move` | Page-specific facts, charts, images, and template mappings |-| X. Speaker Notes Requirements | Filename and content policy | — |--**Hard rule**: Keep all ten `##` headings, even when §VII or §VIII contains no rows. Do not add a second schema description inside the project artifact.+Angle-bracketed text below is authoring notation, not project content. Resolve every universal value before writing the file; omit only rows explicitly marked conditional. Keep all ten `##` headings even when §VII or §VIII has no data rows. Do not copy examples, notation tokens, or a second schema description into the project artifact.----+### 2.1 Header and project contract-## 3. Machine validation+Start with this exact heading order:-```bash-python3 skills/ppt-master/scripts/project_manager.py validate <project_path>+```markdown+<!-- ppt-master-schema: design-spec/v1 -->+# <Project Name> - Design Spec++## I. Project Information++| Item | Value |+| --- | --- |+| Project Name | <resolved project name> |+| Canvas Format | <canonical format and dimensions> |+| Page Count | <exact final count matching §IX> |+| Target Audience | <confirmed audience> |+| Communication Intent | <confirmed intent, including priority or sequence> |+| Desired Audience Outcome | <confirmed observable outcome> |+| Core Message / Ask / Action | <confirmed core message or ask> |+| Delivery Context | <confirmed delivery context> |+| Artifact Afterlife | <confirmed afterlife> |+| Reading Mode | <text, balanced, presentation, or the active non-PPT equivalent> |+| Content Strategy | <confirmed material-divergence prose or balanced default> |+| Design Style | <resolved design direction> |+| Formula Policy | <mixed, render-all, or text-only> |+| AI Image Acquisition Path | <confirmed path or not applicable> |+| Generation Mode | <continuous or split> |+| Spec Refinement | <enabled or disabled> |+| Created Date | <YYYY-MM-DD> |++## II. Canvas Specification++| Property | Value |+| --- | --- |+| Format | <canonical format name> |+| Dimensions | <width × height> |+| viewBox | `<exact viewBox>` |+| Margins | <safe margins> |+| Content Area | <usable bounds> |```-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.+When a template workspace is active, append exactly one line after the §I table: `- **Template Application**: <confirmed or Strategist-resolved natural-language plan>`. Omit it for free design. Never replace this prose with internal reuse/adherence ids.-The schema owns structure only. Strategist role modules own field meaning, recommendation logic, page planning, image policy, and template policy. `spec_lock.md` owns stable execution anchors and routing selected in context; it is not an exhaustive value projection. On divergence, repair the Design Spec from the retained final state when Gate 1 fails, then re-author affected lock anchors from the audited Design Spec and current context. Never reopen `result.json` merely to author or validate the lock, and never use the lock to overwrite a valid Design Spec decision.+### 2.2 Visual, typography, layout, and icons------## 4. Minimal filled shape+Use these exact subsections and field shapes:```markdown## III. Visual Theme### Theme Style-- **Mode**: briefing-- **Visual style**: swiss-minimal++- **Mode**: <confirmed preset or custom>+- **Visual style**: <confirmed preset or custom>+- **Theme**: <resolved identity direction>+- **Tone**: <resolved tone>### Color Scheme+| Role | HEX | Purpose || --- | --- | --- |-| Background | `#FFFFFF` | Canvas |+| Background | <HEX> | <semantic use> |+| Secondary background | <HEX> | <semantic use> |+| Primary | <HEX> | <semantic use> |+| Accent | <HEX> | <semantic use> |+| Secondary accent | <HEX> | <semantic use> |+| Body text | <HEX> | <semantic use> |++## IV. Typography System++### Font Plan++| Role | Chinese | English | Fallback tail |+| --- | --- | --- | --- |+| Title | <family> | <family> | <fallback> |+| Body | <family> | <family> | <fallback> |++- **Title stack**: <complete ordered stack>+- **Body stack**: <complete ordered stack>++### Font Size Hierarchy++| Purpose | Size (px) |+| --- | ---: |+| Body | <confirmed value> |+| Title | <confirmed value> |+| Subtitle | <confirmed value> |+| Annotation | <confirmed value> |++## V. Layout Principles++### Page Structure++- **Header area**: <rule>+- **Content area**: <rule>+- **Footer area**: <rule>++### Spacing Specification++| Element | Current Project |+| --- | --- |+| Safe margin | <value> |+| Content block gap | <value> |+| Icon-text gap | <value> |++## VI. Icon Usage Specification++- **Library**: <confirmed library, custom, or none>++| Purpose | Icon Path | Page |+| --- | --- | --- |+```++Add every recurring palette role and typography role established by the plan, including `Emphasis`, `Code`, `Lead`, or `Footnote` rows/stacks/sizes only when they recur; do not enumerate one-off paint or display garnish. For confirmed custom directions, add the applicable `Mode References`, `Mode Behavior`, `Visual Style References`, and `Visual Style Behavior` lines under Theme Style. Include `Stroke Width` under §VI only for a stroke library. Leave the §VI table empty when no icons are used.++When §VIII contains any `Acquire Via: ai` row, add this subsection under §III and preserve the complete confirmed AI direction:++```markdown+### AI Image Strategy++- **Image Rendering**: <confirmed preset or custom>+- **Visual**: <confirmed visual treatment>+- **Mood**: <confirmed mood and analogy>+```++For a selected custom rendering, also add `Image Rendering Behavior`; add `Image Rendering References` only when the confirmed custom direction actually uses catalog material. Never add a separate image palette.++### 2.3 Visualization and image resources++Use these exact combined tables; an inactive section keeps its header row and no data rows:++```markdown+## VII. Visualization Reference List++| Page | Template | Path | Summary-quote (verbatim) | Native-ready | Usage |+| --- | --- | --- | --- | --- | --- |++## VIII. Image Resource List++| Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Crop Policy | Acquire Via | Status | Reference | text_policy | page_role |+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |+```++In §VII, use `yes`, `no`, or `n/a` for `Native-ready`; record `no-template-match` plus the fallback and reason when recall finds no fit. After the table, list real runners-up as `- <returned_key> | rejected for P<NN>: <page-specific reason>` when candidates were compared. Incidental sparklines, KPI trends, and insets stay in the relevant §IX page rather than becoming independent §VII rows.++In §VIII, author every planned or explicitly required resource from the confirmed source boundary. Copy the selected `Layout pattern` id/name and modifiers verbatim; set `Crop Policy` to `adaptive` or `no-crop`; set `Acquire Via` to `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`. Preserve unresolved required assets as `Pending` or `Needs-Manual` instead of dropping or reclassifying them.++### 2.4 Complete page roster and notes++Write one ordered Slide block per page. Slide count and order must equal §I `Page Count`; `Content` is final wording, not an Executor writing prompt.+```markdown## IX. Content Outline-#### Slide 01 - Decision frame-- **Audience move**: undecided → understands the decision-- **Layout**: claim + evidence-- **Title**: Choose the funded path+### Part 1: <section name>++#### Slide 01 - <page name>++- **Audience move**: <audience state before → after>+- **Layout**: <composition; include the chosen prototype when template-active>+- **Title**: <final title>+- **Core message**: <one governing assertion>+- **Content**: <complete final on-slide wording and hierarchy>++## X. Speaker Notes Requirements++- **Filename**: match each SVG filename under `notes/`+- **Content**: <notes content and source-handling policy>+- **Total duration**: <resolved duration>+- **Notes style**: <formal, conversational, interactive, or resolved equivalent>+- **Presentation purpose**: <inform, persuade, inspire, instruct, report, or resolved combination>```-Use the scaffold for the complete shape; this excerpt is not a second template.+Add `Visualization` and `Images` to a Slide block when it consumes §VII/§VIII rows or uses a page-local microvisual. Add `Fact IDs` for sourced claims and `Data class: scenario` for invented demo values. Add `Cover impact` to P01 except on preservation paths; add `Closing impact` only when the final page genuinely resolves the deck. Roster ids/count/order and final content are authoritative. Layout, cover/closing composition, and image/chart patterns are References whose selected semantics remain fixed while Executor realizes their geometry, hierarchy, treatment, and sparse local garnish.++---++## 3. Machine validation++```bash+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...]` placeholders, missing per-slide `Audience move`, and a missing §III `AI Image Strategy` when an §VIII table selects `ai` acquisition.++The schema validates structure only. Strategist role modules own field meaning, recommendation logic, page planning, image policy, and template policy. `spec_lock.md` owns stable execution anchors and routing selected in context; it is not an exhaustive value projection. On divergence, repair the Design Spec from the retained final state when Gate 1 fails, then re-author affected lock anchors from the audited Design Spec and current context. Never reopen `result.json` merely to author or validate the lock, and never use the lock to overwrite a valid Design Spec decision.diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.mdindex 08f08ad7..986ef0bd 100644--- a/skills/ppt-master/templates/spec_lock_reference.md+++ b/skills/ppt-master/templates/spec_lock_reference.md@@ -1,16 +1,14 @@# Execution Lock Structure-`spec_lock.md` is the compact execution contract authored from an audited `design_spec.md` and the current project context. It keeps stable cross-page anchors and routing values; it is not an exhaustive allowlist of every color, gradient stop, effect paint, or typeface that a page may use. After confirmation fidelity passes, start from [`scaffolds/spec_lock.md`](./scaffolds/spec_lock.md); [`schemas/spec_lock.schema.json`](./schemas/spec_lock.schema.json) owns its grammar.+`spec_lock.md` is the compact execution contract authored from an audited `design_spec.md` and the current project context. It keeps stable cross-page anchors and routing values; it is not an exhaustive allowlist of every color, gradient stop, effect paint, or typeface that a page may use. This file owns normal authoring structure; [`schemas/spec_lock.schema.json`](./schemas/spec_lock.schema.json) owns machine grammar.-## 1. Create the artifact+## 1. Author the complete artifact-After Generate Step 4 Gate 1, run once and author the execution anchors from the Design Spec plus current page/resource/template context:+After Generate Step 4 Gate 1, read the completed Design Spec and current page/resource/template context, compose the entire lock in active context, then create `<project_path>/spec_lock.md` once.-```bash-python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path>-```+**Mandatory — new-project write**: The first non-empty line is exactly `<!-- ppt-master-schema: spec-lock/v1 -->`, followed by `# Execution Lock`. Write only final sections and values; do not create a blank lock, copy inactive optional sections, or patch scaffold placeholders. Do not reopen final confirmation or interpret it independently.-The command refuses to overwrite an existing `spec_lock.md`. Re-running it with the same project metadata produces the same bytes.+`project_manager.py scaffold-lock` remains an optional manual convenience and overwrite-safe troubleshooting tool. It is not part of normal Generate authoring. When a credible completed Design Spec/lock pair needs correction, repair only the affected projection after auditing the Design Spec. When the Design Spec was missing and an orphan lock survived, discard that lock as authority and re-author the complete lock from the recovered, audited Design Spec plus current context.**Hard rule**: A project lock contains only `##` sections and `- key: value` data lines, except `## forbidden`, whose list items are literal rules. Do not copy guidance paragraphs into the lock.@@ -33,6 +31,15 @@ The command refuses to overwrite an existing `spec_lock.md`. Re-running it withOptional data sections: `images`, `page_charts`.+The required universal block is:++```markdown+## forbidden+- Mixing icon libraries+- `mask`, `<style>`, `class`, external CSS, `<foreignObject>`, `textPath`, `@font-face`, `<animate*>`, `<set>`, `<script>` / event attributes, `<iframe>`+- HTML named entities in text; write typography as raw Unicode and escape XML reserved characters+```+---## 3. Conditional sections and fieldsdiff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex d04bab8b..27e6e0de 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -162,7 +162,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 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.+> ⚠️ **Mandatory artifact gates**: after final confirmation, read `templates/design_spec_reference.md` and author the complete `design_spec.md` from scratch; after Gate 1, read `templates/spec_lock_reference.md` and author the complete `spec_lock.md` from the Design Spec plus current context. For a new project, create each finished artifact once—do not materialize a placeholder scaffold and fill it piecemeal. The references own authoring structure, the schemas own machine validation, and semantic projection fidelity remains mandatory. `scaffold-spec` / `scaffold-lock` are optional manual conveniences, not normal Generate steps.**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.@@ -238,19 +238,14 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images- `<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`-For a new project, scaffold the Design Spec after final confirmation; the command refuses to overwrite an existing artifact:+For a new project, use the reference-first whole-document sequence:-```bash-python3 ${SKILL_DIR}/scripts/project_manager.py scaffold-spec <project_path>-```--Fill and audit `design_spec.md` against the retained complete final confirmation. This is the only normal consumption of the final result. Only after that audit passes, scaffold and author the machine lock from the completed Design Spec plus current execution context:--```bash-python3 ${SKILL_DIR}/scripts/project_manager.py scaffold-lock <project_path>-```+1. Read `templates/design_spec_reference.md`. Compose the complete I–X document in active context from the retained final confirmation, source analysis, and project context; then create `<project_path>/design_spec.md` once with no `[fill]` placeholders or example rows. This is the only normal consumption of the final result.+2. Audit the finished Design Spec field by field against that retained confirmation. Gate 1 must pass before lock authoring.+3. Read `templates/spec_lock_reference.md`. Compose the complete execution projection from the audited Design Spec plus current page/resource/template context; then create `<project_path>/spec_lock.md` once. Do not reopen `result.json` or make an independent design choice.+4. Compare the lock's identity anchors and routing values against the completed Design Spec, then run `python3 ${SKILL_DIR}/scripts/project_manager.py validate <project_path>`.-After filling the lock, compare its identity anchors and routing values against the completed Design Spec, then run `python3 ${SKILL_DIR}/scripts/project_manager.py validate <project_path>`. A retained final state → Design Spec mismatch or Design Spec/context → lock mismatch is blocking even when the standalone Markdown schemas pass. `validate` reads the planning artifacts only; it does not reopen `confirm_ui/result.json` or prove semantic fidelity. Repair the Design Spec from the retained final state; only a fresh recovery turn with no retained state reads persisted final evidence once. Then re-author the affected lock rows from the corrected Design Spec and current context. A resume path edits existing files in the same order and never re-scaffolds them.+A retained final state → Design Spec mismatch or Design Spec/context → lock mismatch is blocking even when the standalone Markdown schemas pass. `validate` reads the planning artifacts only; it does not reopen `confirm_ui/result.json` or prove semantic fidelity. Repair the Design Spec from the retained final state; only a fresh recovery turn with no retained state reads persisted final evidence once. Then re-author the affected lock rows from the corrected Design Spec and current context. A resume or refine path edits existing completed files in the same order; it does not replace them with scaffolds.**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:```markdowndiff --git a/skills/ppt-master/workflows/governance/failure-recovery.md b/skills/ppt-master/workflows/governance/failure-recovery.mdindex 70f10d57..b3c83a35 100644--- a/skills/ppt-master/workflows/governance/failure-recovery.md+++ b/skills/ppt-master/workflows/governance/failure-recovery.md@@ -67,8 +67,8 @@ 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; read final evidence once into the fresh context, scaffold and write `design_spec.md` from it plus source analysis, pass Gate 1, then replace the orphan lock's affected anchors from the completed Design Spec and current context. 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; in this fresh recovery context read final evidence once to audit the existing Design Spec, then run `project_manager.py scaffold-lock` and author the lock from the audited Design Spec plus current context. |+| 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; read final evidence once into the fresh context, read [`design_spec_reference.md`](../../templates/design_spec_reference.md), author the complete `design_spec.md` from scratch using that state plus source analysis, and pass Gate 1. Then read [`spec_lock_reference.md`](../../templates/spec_lock_reference.md) and re-author the complete `spec_lock.md` from the audited Design Spec plus current context, replacing any orphan lock. Never reconstruct the Design Spec from an orphan lock or retain orphan-lock choices as authority. |+| Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to Generate Step 4; in this fresh recovery context read final evidence once to audit the existing Design Spec, then read [`spec_lock_reference.md`](../../templates/spec_lock_reference.md) and author the complete lock from the audited Design Spec plus current context. || Final confirmation evidence and both planning artifacts exist, but Gate 1 fails | In a fresh recovery context read final evidence once, repair `design_spec.md`, then re-author 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-author only the mismatched lock anchors/routing rows from it plus current context. || 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. |