Skip to content

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

fix(checker): default a missing pptx_structure.mode to flat and relax non-export gates

hugohe3cc535363b8cf
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index e1324e45..16d7d52d 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -86,7 +86,7 @@ history, or resumable planning state. Context loss restarts the Quick run.
| SVG source | `svg_output/` is the only author source for generated pages. |
| Page-design closure | On SVG-authoring routes, every visible exported-slide object exists in the corresponding page SVG or an explicitly referenced visual asset. |
| Package-behavior separation | Speaker notes, animations, transitions, narration, and direct native-PPTX workflows keep their owning artifacts; do not force them into SVG metadata. |
-| Post-processed SVG | In Default Generate, `svg_final/` is disposable, must be rebuilt in Step 7.2, and serves only as a self-contained visual preview / manually insertable SVG picture. Quick omits it. |
+| Post-processed SVG | In Default Generate, `svg_final/` is an optional disposable preview rebuilt by Step 7.2; it serves only as a self-contained visual preview / manually insertable SVG picture. Quick omits it. |
| Workflow audit log | `validation/workflow.log` automatically records each project-scoped Python command envelope, all explicit error/failure and receipt/report lines, bounded warning/OK/stderr samples, summary context, and omission counts, plus explicitly selected manual audit entries. It does not retain the full console stream or automatically capture direct file-authoring actions, host-native tools, pre-project conversion, binary-buffer writes, hidden child output, or detached-service activity; absence of a detail line proves nothing about those stages. Automatic recording failure is advisory and never changes the owning tool's outcome; a failed explicit manual append reports failure because no entry was recorded. |
| 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. |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index fb141989..eb3209de 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -25,7 +25,7 @@ Evaluate branches from each object's actual information model, not only from a C
**Hard rule — flat PowerPoint structure**: Free-design, brand-only, Style-only, and every `template_reuse_scope: style` project use `pptx_structure.mode: flat`: write no root Master/Layout identity, `data-pptx-layer`, or `data-pptx-placeholder`; every visible object remains Slide-local, and the root declares exactly one canonical `data-pptx-page-role` (`cover` / `toc` / `section` / `content` / `ending`). A Style workspace supplies reusable communication/design direction, composition rhythm, and information-expression defaults without page prototypes. Its identity-adjacent color, typography, icon, and image defaults yield to the final Brand/Deck identity and confirmed project lock. When a Style is installed alongside Layout/Deck, it changes only Direction / method and follows the resolved non-Style structure route. Export materializes one clean project-owned Master plus one Blank Layout from the current lock. Add `data-pptx-role` only to structural page-frame objects whose package, page-number, or animation behavior is not already expressed by specialized metadata; the marked element uses a stable unique `id`. See [`semantic-svg.md`](./semantic-svg.md).
-**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 still generates `svg_final/` as a mandatory self-contained visual preview that may be inserted as an SVG picture. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.
+**Hard rule — supported PPTX route**: The only supported generated-PPTX path is `svg_output/` through the project SVG-to-DrawingML converter. Step 7.2 generates `svg_final/` as an optional self-contained visual preview that may be inserted as an SVG picture; its absence never blocks export. Do not treat PowerPoint's manual Convert-to-Shape operation as an authoring target or compatibility requirement.
> Note: this rule covers page design only. Speaker notes, animations, transitions, narration, and direct native-PPTX workflows retain their separate artifacts and package-level processing.
diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.md
index 22ed7edc..ed31bcd3 100644
--- a/skills/ppt-master/references/shared-standards-core.md
+++ b/skills/ppt-master/references/shared-standards-core.md
@@ -332,7 +332,7 @@ one. This array is still diagnostic metadata, not an authoring surface.
| `standard` / `fidelity` output | Use §1.5 compact presets; never transplant opaque payload or source topology. |
| `mirror` output | Template_Designer reviews/authors the compact parsed IR; materialization validates refs/graph and publishes that tree without restoring visible lossless subtrees. Recover only supported non-visible semantics; expand fixed Master/Layout wrappers without changing ownership or intended presentation. |
-**Hard rule — model-facing page-coordinate precision**:
+**Default — model-facing page-coordinate precision (the canonical checker reports over-precision as an advisory warning)**:
| Surface | Precision contract |
|---|---|
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 48e6a2ec..ccfa0d05 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -706,7 +706,7 @@ It aggregates:
- `align_embed_images.py` (`crop-images` / `fix-aspect` / `embed-images` aliases route here)
- `flatten_tspan.py`
-`svg_final/` remains a required Step 7.2 artifact even though the native exporter reads `svg_output/`. It is the self-contained visual reference and may be manually inserted as an SVG picture.
+`svg_final/` is an optional Step 7.2 preview artifact; the native exporter reads `svg_output/` and never requires it. It is the self-contained visual reference and may be manually inserted as an SVG picture.
## `svg_to_pptx.py`
diff --git a/skills/ppt-master/scripts/project_utils.py b/skills/ppt-master/scripts/project_utils.py
index 4a3295e1..20fd7438 100644
--- a/skills/ppt-master/scripts/project_utils.py
+++ b/skills/ppt-master/scripts/project_utils.py
@@ -407,11 +407,11 @@ def validate_project_structure(
# Check required files
if not (project_path / 'README.md').exists():
- msg = "Missing required file: README.md"
+ msg = "Missing README.md (optional project notes; nothing reads it)"
if use_helper and verbose:
msg += "\n" + ErrorHelper.format_error_message('missing_readme',
{'project_path': str(project_path)})
- errors.append(msg)
+ warnings.append(msg)
# Check design specification file
has_spec = any((project_path / name).exists() for name in _DESIGN_SPEC_NAMES)
diff --git a/skills/ppt-master/scripts/svg_quality/checker.py b/skills/ppt-master/scripts/svg_quality/checker.py
index 090edec7..79d1ec8f 100644
--- a/skills/ppt-master/scripts/svg_quality/checker.py
+++ b/skills/ppt-master/scripts/svg_quality/checker.py
@@ -5893,6 +5893,16 @@ class SVGQualityChecker:
if standard_project
else None
)
+ implicit_flat = bool(standard_project) and not declared_mode
+ if implicit_flat:
+ self._pptx_structure_issues.append((
+ 'warning',
+ 'spec_lock.md declares no pptx_structure.mode; the project is '
+ 'treated as mode: flat, matching the exporter default. Declare '
+ 'mode: flat explicitly, or mode: structured for a deck/layout '
+ 'template.',
+ ))
+ declared_mode = 'flat'
if standard_project and declared_mode in {'flat', 'structured'}:
self._pptx_structure_issues.extend(
('error', message)
@@ -5914,6 +5924,8 @@ class SVGQualityChecker:
except _TemplateStructureError as exc:
self._pptx_structure_issues.append(('error', str(exc)))
return
+ if structure_lock is None and implicit_flat:
+ return
if structure_lock is None or structure_lock.mode != 'flat':
self._pptx_structure_issues.append((
'error',
@@ -5969,18 +5981,14 @@ class SVGQualityChecker:
return
if standard_project and declared_mode != 'structured':
- label = repr(declared_mode) if declared_mode else (
- 'missing (legacy implicit baseline)'
- )
self._pptx_structure_issues.append((
'error',
- 'release SVG projects require an explicit spec_lock.md '
- 'pptx_structure.mode: flat (free design / brand-only) or '
- f'structured (deck/layout template); found {label}. New '
- 'free-design projects use mode: flat; create a new template '
- 'workspace through skills/ppt-master/workflows/create-template.md, '
- 'then generate new structured SVG pages before export. Existing '
- 'PPTX/SVG files are not upgraded in place.',
+ 'release SVG projects require spec_lock.md pptx_structure.mode: '
+ 'flat (free design / brand-only) or structured (deck/layout '
+ f'template); found {declared_mode!r}. Create a template '
+ 'workspace through skills/ppt-master/workflows/create-template.md '
+ 'before generating structured SVG pages. Existing PPTX/SVG files '
+ 'are not upgraded in place.',
))
return
diff --git a/skills/ppt-master/templates/schemas/spec_lock.schema.json b/skills/ppt-master/templates/schemas/spec_lock.schema.json
index 7108563d..c025f47c 100644
--- a/skills/ppt-master/templates/schemas/spec_lock.schema.json
+++ b/skills/ppt-master/templates/schemas/spec_lock.schema.json
@@ -13,7 +13,6 @@
"typography",
"icons",
"page_rhythm",
- "pptx_structure",
"forbidden"
],
"properties": {
@@ -183,7 +182,7 @@
{
"id": "pptx_structure",
"pattern": "^pptx_structure$",
- "required": true,
+ "required": false,
"required_fields": ["mode"],
"allowed_fields": ["mode", "template_reuse_scope", "template_adherence"],
"field_enums": {
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index 5122667a..a30516c8 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -32,7 +32,7 @@ request does not explicitly select Quick.
| Any route that authors or regenerates slide visuals through SVG | `svg_output/` is the complete page-design source: every visible text, image, shape, chart/table fallback, block/inline native-formula preview, and layout element that should appear on the exported slide is present in that page SVG or referenced by it. |
| Templates, `design_spec.md`, and `spec_lock.md` | Authoring/control inputs. They guide SVG creation but MUST NOT supply visible slide content that is absent from the completed SVG during export. |
| Semantic SVG markers | Minimal rendering-neutral compiler hints used only after existing Layout/Layer/Placeholder/Native metadata has been considered. Chart/table markers preserve their visible SVG fallback; block and inline formula markers carry exact LaTeX and replace only their registered ordinary SVG preview with editable Office Math during PPTX export. |
-| `svg_final/` | Mandatory derived, self-contained SVG visual preview in the default pipeline. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. Quick-generate skips it. |
+| `svg_final/` | Optional derived, self-contained SVG visual preview in the default pipeline; release export never reads it. It may be opened directly or inserted into PowerPoint as an SVG picture, but it is not a supported PPTX source and carries no manual Convert-to-Shape compatibility contract. Quick-generate skips it. |
| SVG-to-PPTX export | The only supported generated-PPTX route reads `svg_output/` and maps its content through the project converter to DrawingML/native objects. It compiles only the selected route's explicit structure contract: `flat` keeps represented content Slide-local, while `structured` may place explicitly scoped content in Master/Layout/Slide parts. It MUST NOT infer structure, upgrade `flat`, or invent new visible page content. |
| Native PPTX routes and presentation-behavior stages | Remain outside SVG page-design closure. `template-fill-pptx`, `native-enhance-pptx`, animations, transitions, speaker notes, narration, and package relationships are not required to round-trip through SVG. |
@@ -835,7 +835,7 @@ command and proceed directly to Step 7.2.
python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
```
-**Success criterion**: `<project_path>/svg_final/` contains one self-contained preview SVG for every published slide. This mandatory derived preview does not replace `svg_output/` as the native-export source.
+**Success criterion**: `<project_path>/svg_final/` contains one self-contained preview SVG for every published slide. This optional derived preview does not replace `svg_output/` as the native-export source, and its absence never blocks Step 7.3.
#### Step 7.3 — Export the Native PPTX