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

feat(pptx): gate template-fill apply on confirmed plan, add validate

hugohe3f1f0291fbb4a
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 7bf9d498..d80b866d 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -79,14 +79,17 @@ python3 scripts/pptx_template_import.py <template.pptx> --inheritance-mode both
Template fill (direct PPTX, no SVG conversion):
```bash
-mkdir -p <project_path>/sources <project_path>/analysis <project_path>/exports <project_path>/validation
+python3 scripts/project_manager.py init <project_name> --format ppt169
+python3 scripts/project_manager.py import-sources <project_path> <source.pptx> <material...>
+# Manual fallback when import-sources did not produce analysis/<stem>.slide_library.json:
python3 scripts/template_fill_pptx.py analyze <project_path>/sources/<source.pptx> -o <project_path>/analysis/<stem>.slide_library.json
python3 scripts/template_fill_pptx.py scaffold <project_path>/analysis/<stem>.slide_library.json -o <project_path>/analysis/fill_plan.json --slides "1,3,4"
python3 scripts/template_fill_pptx.py check-plan <project_path>/analysis/<stem>.slide_library.json <project_path>/analysis/fill_plan.json -o <project_path>/analysis/check_report.json
python3 scripts/template_fill_pptx.py apply <project_path>/sources/<source.pptx> <project_path>/analysis/fill_plan.json -o <project_path>/exports/filled.pptx
+python3 scripts/template_fill_pptx.py validate <project_path>
```
-`apply` automatically writes `filled_YYYYMMDD_HHMMSS.pptx` unless the output stem already ends with a timestamp. It applies a `fade` page transition by default; `--transition <effect>` (fade/push/wipe/split/strips/cover/random, `--transition-duration` in seconds) changes it, `--transition none` removes it, `--transition keep` preserves the source transitions, and a per-slide `transition` field in the plan overrides whatever the CLI selects.
+`apply` requires `fill_plan.json` to have top-level `"status": "confirmed"` unless `--force` is passed. It automatically writes `filled_YYYYMMDD_HHMMSS.pptx` unless the output stem already ends with a timestamp. It applies a `fade` page transition by default; `--transition <effect>` (fade/push/wipe/split/strips/cover/random, `--transition-duration` in seconds) changes it, `--transition none` removes it, `--transition keep` preserves the source transitions, and a per-slide `transition` field in the plan overrides whatever the CLI selects.
Native existing-PPTX enhancement (direct PPTX, no SVG conversion):
diff --git a/skills/ppt-master/scripts/template_fill_pptx.py b/skills/ppt-master/scripts/template_fill_pptx.py
index 22bea99a..76beb011 100644
--- a/skills/ppt-master/scripts/template_fill_pptx.py
+++ b/skills/ppt-master/scripts/template_fill_pptx.py
@@ -8,10 +8,11 @@ documented command paths keep working:
python3 scripts/template_fill_pptx.py scaffold <stem>.slide_library.json -o fill_plan.json
python3 scripts/template_fill_pptx.py check-plan <stem>.slide_library.json fill_plan.json
python3 scripts/template_fill_pptx.py apply <deck.pptx> fill_plan.json -o output.pptx
+ python3 scripts/template_fill_pptx.py validate <project>
Implementation lives in the template_fill_pptx/ package (ooxml, analyzer,
scaffolder, checker, text_fill, table_fill, chart_fill, transitions, notes,
-package, applier, cli).
+package, applier, validator, cli).
"""
import sys
diff --git a/skills/ppt-master/scripts/template_fill_pptx/__init__.py b/skills/ppt-master/scripts/template_fill_pptx/__init__.py
index 1fc98d45..8f3a682c 100644
--- a/skills/ppt-master/scripts/template_fill_pptx/__init__.py
+++ b/skills/ppt-master/scripts/template_fill_pptx/__init__.py
@@ -2,8 +2,8 @@
Direct OOXML editing (no SVG round-trip): select source slides, replace
text / table / chart content from a fill plan, and write a new .pptx that keeps
-the original PowerPoint design. Four stages mirror the CLI subcommands:
-analyze -> scaffold -> check-plan -> apply.
+the original PowerPoint design. CLI stages mirror the direct-PPTX workflow:
+analyze -> scaffold -> check-plan -> apply -> validate.
Public entry: analyze_pptx(), scaffold_plan(), check_plan(), apply_plan(), main().
"""
@@ -15,6 +15,7 @@ from .applier import apply_plan
from .checker import check_plan, print_check_report
from .cli import main
from .scaffolder import scaffold_plan
+from .validator import print_validate_report, validate_project
__all__ = [
"analyze_pptx",
@@ -22,5 +23,7 @@ __all__ = [
"check_plan",
"print_check_report",
"apply_plan",
+ "validate_project",
+ "print_validate_report",
"main",
]
diff --git a/skills/ppt-master/scripts/template_fill_pptx/checker.py b/skills/ppt-master/scripts/template_fill_pptx/checker.py
index 10b1fedf..db400db6 100644
--- a/skills/ppt-master/scripts/template_fill_pptx/checker.py
+++ b/skills/ppt-master/scripts/template_fill_pptx/checker.py
@@ -223,6 +223,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "replacements_not_list",
"plan_slide": slide_index,
"source_slide": source_slide,
"message": "replacements must be a list",
@@ -239,6 +240,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "replacement_target_not_found",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -274,6 +276,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": status,
+ "code": "text_capacity" if status == "WARN" else "text_fit",
"plan_slide": slide_index,
"source_slide": source_slide,
"slot_id": slot.get("slot_id"),
@@ -296,6 +299,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "table_edits_not_list",
"plan_slide": slide_index,
"source_slide": source_slide,
"message": "table_edits must be a list",
@@ -310,6 +314,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "table_target_not_found",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -323,6 +328,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "table_cells_not_list",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -340,6 +346,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "table_cell_out_of_bounds",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -352,6 +359,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "OK",
+ "code": "table_target_exists",
"plan_slide": slide_index,
"source_slide": source_slide,
"table_id": table.get("table_id"),
@@ -365,6 +373,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "chart_edits_not_list",
"plan_slide": slide_index,
"source_slide": source_slide,
"message": "chart_edits must be a list",
@@ -379,6 +388,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "chart_target_not_found",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -391,6 +401,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "chart_combo_unsupported",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -409,6 +420,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "chart_data_invalid",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -428,6 +440,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "ERROR",
+ "code": "chart_series_length_mismatch",
"plan_slide": slide_index,
"source_slide": source_slide,
"selector": selectors[0] if selectors else "",
@@ -440,6 +453,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "OK",
+ "code": "chart_target_valid",
"plan_slide": slide_index,
"source_slide": source_slide,
"chart_id": chart.get("chart_id"),
@@ -477,6 +491,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "WARN",
+ "code": "non_text_content_unedited",
"plan_slide": plan_slide_index,
"source_slide": source_slide,
"message": (
@@ -515,6 +530,7 @@ def check_plan(library: dict[str, Any], plan: dict[str, Any]) -> dict[str, Any]:
results.append(
{
"status": "WARN",
+ "code": "source_reuse_concentration",
"source_slide": src,
"reuse_count": count,
"unused_source_slides": unused_lib_indices,
diff --git a/skills/ppt-master/scripts/template_fill_pptx/cli.py b/skills/ppt-master/scripts/template_fill_pptx/cli.py
index 4ada454e..018e078f 100644
--- a/skills/ppt-master/scripts/template_fill_pptx/cli.py
+++ b/skills/ppt-master/scripts/template_fill_pptx/cli.py
@@ -1,4 +1,4 @@
-"""Command-line interface: analyze / scaffold / check-plan / apply subcommands."""
+"""Command-line interface: analyze / scaffold / check-plan / apply / validate."""
from __future__ import annotations
@@ -33,6 +33,7 @@ from .transitions import (
KEEP_TRANSITION,
TRANSITIONS,
)
+from .validator import print_validate_report, validate_project
def _parse_slide_list(value: str | None) -> list[int] | None:
@@ -60,6 +61,10 @@ def _timestamped_pptx_path(path: Path) -> Path:
return path.with_name(f"{path.stem}_{timestamp}{path.suffix}")
+def _plan_confirmed(plan: dict) -> bool:
+ return plan.get("status") == "confirmed"
+
+
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description="Analyze and fill native PPTX templates without converting slides to SVG.",
@@ -118,6 +123,14 @@ def build_parser() -> argparse.ArgumentParser:
default=DEFAULT_TRANSITION_DURATION,
help="Transition duration in seconds (default: 0.5).",
)
+ apply.add_argument(
+ "--force",
+ action="store_true",
+ help="apply without a confirmed fill plan (deliberate recovery/debug only)",
+ )
+
+ validate = subparsers.add_parser("validate", help="Read back and validate the latest project export")
+ validate.add_argument("project_path", help="Template-fill project directory")
return parser
@@ -160,6 +173,14 @@ def main(argv: list[str] | None = None) -> int:
if args.command == "apply":
pptx_path = Path(args.pptx_file).expanduser().resolve()
plan = _load_json(Path(args.plan_json).expanduser().resolve())
+ if not _plan_confirmed(plan) and not args.force:
+ print(
+ "Error: fill plan is not confirmed: "
+ f"{Path(args.plan_json).expanduser().resolve()} "
+ '(set status to "confirmed" after user approval, or pass --force)',
+ file=sys.stderr,
+ )
+ return 1
output_path = _timestamped_pptx_path(Path(args.output).expanduser().resolve())
apply_plan(
pptx_path,
@@ -170,6 +191,11 @@ def main(argv: list[str] | None = None) -> int:
)
print(f"Template-filled PPTX -> {output_path}", file=sys.stderr)
return 0
+
+ if args.command == "validate":
+ report = validate_project(Path(args.project_path))
+ print_validate_report(report)
+ return 0 if report["summary"]["error"] == 0 else 1
except RuntimeError as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
diff --git a/skills/ppt-master/scripts/template_fill_pptx/scaffolder.py b/skills/ppt-master/scripts/template_fill_pptx/scaffolder.py
index 0e83fc5a..0560711c 100644
--- a/skills/ppt-master/scripts/template_fill_pptx/scaffolder.py
+++ b/skills/ppt-master/scripts/template_fill_pptx/scaffolder.py
@@ -62,6 +62,11 @@ def scaffold_plan(
{
"source_slide": slide["slide_index"],
"purpose": slide.get("page_type", "content_candidate"),
+ "layout_rationale": {
+ "layout_pattern": "",
+ "why_fit": "",
+ "risk": "",
+ },
"replacements": replacements,
"table_edits": table_edits,
"chart_edits": chart_edits,
@@ -70,6 +75,8 @@ def scaffold_plan(
return {
"schema": "template_fill_pptx_plan.v1",
+ "status": "draft",
"source_pptx": library.get("source_pptx"),
+ "accepted_warnings": [],
"slides": slides,
}
diff --git a/skills/ppt-master/scripts/template_fill_pptx/validator.py b/skills/ppt-master/scripts/template_fill_pptx/validator.py
new file mode 100644
index 00000000..0a4d933b
--- /dev/null
+++ b/skills/ppt-master/scripts/template_fill_pptx/validator.py
@@ -0,0 +1,278 @@
+"""validate: read back the latest template-fill export and check core contract."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from .ooxml import _load_json, _write_json
+
+
+_SCRIPTS_DIR = Path(__file__).resolve().parents[1]
+_SLIDE_HEADING_RE = re.compile(r"^## Slide\s+\d+\s*$", re.MULTILINE)
+_TOTAL_SLIDES_RE = re.compile(r"^- Total slides:\s*(\d+)\s*$", re.MULTILINE)
+
+
+def _latest_export(project_path: Path) -> Path:
+ exports_dir = project_path / "exports"
+ candidates = [path for path in exports_dir.glob("*.pptx") if path.is_file()]
+ if not candidates:
+ raise RuntimeError(f"No PPTX exports found in: {exports_dir}")
+ return max(candidates, key=lambda path: path.stat().st_mtime)
+
+
+def _readback_slide_count(markdown: str) -> int:
+ match = _TOTAL_SLIDES_RE.search(markdown)
+ if match:
+ return int(match.group(1))
+ return len(_SLIDE_HEADING_RE.findall(markdown))
+
+
+def _normalize_text(value: object) -> str:
+ return re.sub(r"\s+", "", str(value or "")).strip()
+
+
+def _contains_text(markdown: str, value: object) -> bool:
+ normalized = _normalize_text(value)
+ if not normalized:
+ return True
+ return normalized in _normalize_text(markdown)
+
+
+def _first_library(project_path: Path) -> dict[str, Any] | None:
+ libraries = sorted((project_path / "analysis").glob("*.slide_library.json"))
+ if not libraries:
+ return None
+ return _load_json(libraries[0])
+
+
+def _slot_role_lookup(library: dict[str, Any] | None) -> dict[tuple[int, str], str]:
+ if library is None:
+ return {}
+ lookup: dict[tuple[int, str], str] = {}
+ for slide in library.get("slides", []):
+ slide_index = int(slide.get("slide_index", 0))
+ for slot in slide.get("slots", []):
+ slot_id = slot.get("slot_id")
+ if isinstance(slot_id, str):
+ lookup[(slide_index, slot_id)] = str(slot.get("role") or "")
+ return lookup
+
+
+def _title_texts(plan: dict[str, Any], role_lookup: dict[tuple[int, str], str]) -> list[tuple[int, str]]:
+ titles: list[tuple[int, str]] = []
+ for plan_slide, slide in enumerate(plan.get("slides", []), start=1):
+ source_slide = int(slide.get("source_slide", 0))
+ replacements = slide.get("replacements", [])
+ if not isinstance(replacements, list):
+ continue
+ first_text = ""
+ found_title = False
+ for replacement in replacements:
+ if not isinstance(replacement, dict):
+ continue
+ text = str(replacement.get("text") or "").strip()
+ if not text:
+ continue
+ if not first_text:
+ first_text = text
+ slot_id = replacement.get("slot_id")
+ if isinstance(slot_id, str) and role_lookup.get((source_slide, slot_id)) == "title_candidate":
+ titles.append((plan_slide, text))
+ found_title = True
+ break
+ if not found_title and first_text:
+ titles.append((plan_slide, first_text))
+ return titles
+
+
+def _table_tokens(plan: dict[str, Any]) -> list[tuple[int, str]]:
+ tokens: list[tuple[int, str]] = []
+ for plan_slide, slide in enumerate(plan.get("slides", []), start=1):
+ for table_edit in slide.get("table_edits", []) or []:
+ for cell in table_edit.get("cells", []) or []:
+ text = str(cell.get("text") or "").strip()
+ if text:
+ tokens.append((plan_slide, text))
+ return tokens
+
+
+def _chart_tokens(plan: dict[str, Any]) -> list[tuple[int, str]]:
+ tokens: list[tuple[int, str]] = []
+ for plan_slide, slide in enumerate(plan.get("slides", []), start=1):
+ for chart_edit in slide.get("chart_edits", []) or []:
+ for category in chart_edit.get("categories", []) or []:
+ if str(category).strip():
+ tokens.append((plan_slide, str(category)))
+ for series in chart_edit.get("series", []) or []:
+ name = str(series.get("name") or "").strip()
+ if name:
+ tokens.append((plan_slide, name))
+ for value in series.get("values", []) or []:
+ tokens.append((plan_slide, str(value)))
+ return tokens
+
+
+def _append_token_checks(
+ *,
+ results: list[dict[str, Any]],
+ summary: dict[str, int],
+ markdown: str,
+ tokens: list[tuple[int, str]],
+ code: str,
+ label: str,
+) -> None:
+ seen: set[tuple[int, str]] = set()
+ for plan_slide, text in tokens:
+ key = (plan_slide, text)
+ if key in seen:
+ continue
+ seen.add(key)
+ if _contains_text(markdown, text):
+ summary["ok"] += 1
+ continue
+ summary["warn"] += 1
+ results.append(
+ {
+ "status": "WARN",
+ "code": code,
+ "plan_slide": plan_slide,
+ "message": f"{label} not found in read-back Markdown",
+ "text": text,
+ }
+ )
+
+
+def validate_project(project_path: Path) -> dict[str, Any]:
+ """Run read-back validation for a template-fill project."""
+ project_path = project_path.expanduser().resolve()
+ plan_path = project_path / "analysis" / "fill_plan.json"
+ if not plan_path.is_file():
+ raise RuntimeError(f"Missing fill plan: {plan_path}")
+
+ plan = _load_json(plan_path)
+ output_path = _latest_export(project_path)
+ validation_dir = project_path / "validation"
+ validation_dir.mkdir(parents=True, exist_ok=True)
+ readback_path = validation_dir / "readback.md"
+
+ ppt_to_md = _SCRIPTS_DIR / "source_to_md" / "ppt_to_md.py"
+ try:
+ subprocess.run(
+ [sys.executable, str(ppt_to_md), str(output_path), "-o", str(readback_path)],
+ cwd=_SCRIPTS_DIR.parents[2],
+ check=True,
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ )
+ except FileNotFoundError as exc:
+ raise RuntimeError(f"Missing executable: {sys.executable}") from exc
+ except subprocess.CalledProcessError as exc:
+ details = (exc.stderr or exc.stdout or "").strip()
+ raise RuntimeError(details or "ppt_to_md read-back failed") from exc
+
+ markdown = readback_path.read_text(encoding="utf-8", errors="replace")
+ results: list[dict[str, Any]] = []
+ summary = {"ok": 0, "warn": 0, "error": 0}
+
+ expected_slides = len(plan.get("slides", []) or [])
+ actual_slides = _readback_slide_count(markdown)
+ if expected_slides == actual_slides:
+ summary["ok"] += 1
+ else:
+ summary["error"] += 1
+ results.append(
+ {
+ "status": "ERROR",
+ "code": "slide_count_mismatch",
+ "expected": expected_slides,
+ "actual": actual_slides,
+ "message": "read-back slide count does not match fill_plan.slides",
+ }
+ )
+
+ library = _first_library(project_path)
+ role_lookup = _slot_role_lookup(library)
+ _append_token_checks(
+ results=results,
+ summary=summary,
+ markdown=markdown,
+ tokens=_title_texts(plan, role_lookup),
+ code="title_missing_in_readback",
+ label="key title",
+ )
+ _append_token_checks(
+ results=results,
+ summary=summary,
+ markdown=markdown,
+ tokens=_table_tokens(plan),
+ code="table_text_missing_in_readback",
+ label="table text",
+ )
+ _append_token_checks(
+ results=results,
+ summary=summary,
+ markdown=markdown,
+ tokens=_chart_tokens(plan),
+ code="chart_text_missing_in_readback",
+ label="chart text",
+ )
+
+ planned_notes = [
+ slide
+ for slide in plan.get("slides", []) or []
+ if str(slide.get("notes") or slide.get("speaker_notes") or "").strip()
+ ]
+ note_sections = markdown.count("### Speaker Notes")
+ if len(planned_notes) == note_sections:
+ summary["ok"] += 1
+ elif planned_notes:
+ summary["warn"] += 1
+ results.append(
+ {
+ "status": "WARN",
+ "code": "notes_count_mismatch",
+ "expected": len(planned_notes),
+ "actual": note_sections,
+ "message": "read-back speaker notes count does not match planned notes",
+ }
+ )
+ elif note_sections:
+ summary["warn"] += 1
+ results.append(
+ {
+ "status": "WARN",
+ "code": "unexpected_notes_in_readback",
+ "expected": 0,
+ "actual": note_sections,
+ "message": "read-back contains speaker notes although the plan has no notes fields",
+ }
+ )
+
+ report = {
+ "schema": "template_fill_pptx_validate.v1",
+ "project": str(project_path),
+ "export": str(output_path),
+ "readback": str(readback_path),
+ "summary": summary,
+ "results": results,
+ }
+ _write_json(validation_dir / "validate_report.json", report)
+ return report
+
+
+def print_validate_report(report: dict[str, Any]) -> None:
+ """Print a compact validation report."""
+ summary = report["summary"]
+ print(f"validate: ok={summary['ok']} warn={summary['warn']} error={summary['error']}")
+ print(f"export: {report['export']}")
+ print(f"readback: {report['readback']}")
+ for item in report["results"]:
+ text = item.get("text")
+ suffix = f" text={text!r}" if text else ""
+ print(f"{item['status']} {item['code']}: {item['message']}{suffix}")
diff --git a/skills/ppt-master/workflows/template-fill-pptx.md b/skills/ppt-master/workflows/template-fill-pptx.md
index e8d9f2e4..d55b8873 100644
--- a/skills/ppt-master/workflows/template-fill-pptx.md
+++ b/skills/ppt-master/workflows/template-fill-pptx.md
@@ -41,12 +41,15 @@ If the content material is only a topic with no supporting facts, gather or ask
## Step 2: Create the Project Workspace
-Create a dedicated project directory under `projects/`. Do not write outputs directly into `projects/` root.
+Create a dedicated project directory under `projects/`. Do not write outputs directly into `projects/` root. Reuse the standard project manager so source import rules stay consistent with the rest of the repository:
```bash
-mkdir -p "<project_dir>/sources" "<project_dir>/analysis" "<project_dir>/exports" "<project_dir>/validation"
+python3 skills/ppt-master/scripts/project_manager.py init "<project_name>" --format ppt169
+python3 skills/ppt-master/scripts/project_manager.py import-sources "<project_dir>" "<source.pptx>" "<material...>"
```
+**Source import rule**: `project_manager.py import-sources` copies files from outside the repository and moves repo-local files by default, unless `--copy` / `--move` is explicitly supplied. Keep this shared behavior; do not create a separate template-fill import path.
+
Use this fixed layout:
| Path | Required content |
@@ -62,10 +65,10 @@ Use this fixed layout:
## Step 3: Extract the PPTX Intake Bundle
-Run:
+`project_manager.py import-sources` automatically runs the standard PPTX intake for imported PowerPoint files and writes `<stem>.slide_library.json` into `<project_dir>/analysis/`. If you are working from a manually assembled project that does not have the intake artifact, run the template-fill analyzer directly:
```bash
-python3 skills/ppt-master/scripts/pptx_intake.py "<project_dir>/sources/<source.pptx>" -o "<project_dir>/analysis"
+python3 skills/ppt-master/scripts/template_fill_pptx.py analyze "<project_dir>/sources/<source.pptx>" -o "<project_dir>/analysis/<stem>.slide_library.json"
```
Read `<project_dir>/analysis/<stem>.slide_library.json` (intake prefixes per-deck artifacts by the template deck's file stem) and identify:
@@ -95,7 +98,7 @@ A page's layout already encodes a rhetorical shape — a single hero statement,
**Hard rule**: The target story controls output order. Source slides may move forward, move backward, be omitted, or be reused several times when their layout matches multiple target messages. Never treat source slide order as a default outline unless the user explicitly asks to preserve it.
-**Required mapping pass**: Create a concise page-to-layout rationale in `<project_dir>/analysis/` before finalizing the plan. It can be JSON or Markdown, but it must record the intended target slide, chosen `source_slide`, and the layout reason (for example: `three-column strategy`, `two-problem contrast`, `timeline`, `metric focus`, `chapter divider`). This is evidence that selection came from template structure rather than sequential replacement.
+**Required mapping pass**: Record a concise page-to-layout rationale in each planned slide before finalizing the plan. Use the per-slide `layout_rationale` object in `fill_plan.json` with `layout_pattern`, `why_fit`, and `risk`. This is human-review evidence that selection came from template structure rather than sequential replacement; it is not a mechanical checker gate.
---
@@ -118,11 +121,25 @@ The plan structure:
```json
{
"schema": "template_fill_pptx_plan.v1",
+ "status": "draft",
"source_pptx": "projects/source.pptx",
+ "accepted_warnings": [
+ {
+ "plan_slide": 3,
+ "slot_id": "s03_sh5",
+ "code": "text_capacity",
+ "reason": "User accepted dense wording"
+ }
+ ],
"slides": [
{
"source_slide": 1,
"purpose": "cover",
+ "layout_rationale": {
+ "layout_pattern": "hero cover",
+ "why_fit": "Large title and subtitle slots fit the opening message without redesign.",
+ "risk": "Subtitle must stay short."
+ },
"notes": "Speaker notes for this filled slide.",
"transition": "fade",
"replacements": [
@@ -158,7 +175,10 @@ The plan structure:
| Decision | Rule |
|---|---|
+| `status` | Keep `"draft"` until the user has reviewed the page sequence / reuse / deletion decisions. Set to `"confirmed"` only after approval. |
| `source_slide` | Repeat the same value across multiple entries to reuse one source layout for several output slides; order is free and must follow the target story rather than source deck order |
+| `layout_rationale` | Human review aid for page selection. Include `layout_pattern`, `why_fit`, and `risk`; it is not a mechanical checker gate. |
+| `accepted_warnings` | Optional audit trail for warnings the user or agent explicitly accepts. `check-plan` warnings remain non-blocking; errors must be fixed. |
| `notes` | Optional spoken speaker notes for the filled slide — see **Speaker notes** below; write prose, not a copy of the on-slide text |
| `transition` | Optional per-slide page transition; overrides the `apply --transition` default. Accepts an effect name (`fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random`), `none` to strip it, or `{ "effect": "push", "duration": 0.6 }` |
| `replacements` | Target by `slot_id` whenever possible; `shape_id` and `shape_name` are fallback selectors |
@@ -219,12 +239,16 @@ Interpret the report:
| Body much longer than source slot | Compress, split across another selected page, or choose a larger source page |
| Missing target | Fix `slot_id` / `shape_id`; do not apply the plan |
+`check-plan` emits stable `code` fields in its JSON results so warnings can be tracked without parsing message text. Warnings are advisory and do not fail the command; record any intentionally accepted warning in `accepted_warnings` when it matters for review. Errors are blocking and must be fixed before apply.
+
**Default fitting policy**: Check fit against visual capacity, not raw character count. CJK characters, Latin letters, numbers, and punctuation occupy different visual widths; old placeholder text is only a weak signal. Use `capacity_visual_width` when present, together with `slots[].geometry` and `slots[].text_metrics.font_size_px`, to decide whether to rewrite, split, or choose a different source layout. Do not use per-item font shrinking as a default strategy because it breaks template consistency.
---
## Step 6: Apply the Plan
+⛔ **BLOCKING GATE**: The user has reviewed the planned output order, omitted pages, reused pages, and material-to-layout fit. Set `<project_dir>/analysis/fill_plan.json` top-level `status` to `"confirmed"` only after that review. `apply` rejects an unconfirmed plan by default; `--force` exists only for deliberate recovery/debug use.
+
Run:
```bash
@@ -256,10 +280,10 @@ The script:
Run a lightweight readability check:
```bash
-python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py "<project_dir>/exports/<output.pptx>"
+python3 skills/ppt-master/scripts/template_fill_pptx.py validate "<project_dir>"
```
-Move or copy the read-back Markdown and extracted files into `<project_dir>/validation/` so `exports/` contains only final deliverables.
+The validator finds the latest PPTX in `<project_dir>/exports/`, runs `ppt_to_md.py` into `<project_dir>/validation/readback.md`, and writes `<project_dir>/validation/validate_report.json`. `exports/` must contain only final deliverables.
Verify:
@@ -269,9 +293,9 @@ Verify:
| Slide count | Matches `len(fill_plan.slides)` |
| Key title text | Appears in the extracted Markdown |
| Native table cells | Updated values appear in the extracted Markdown table |
-| Native chart data | Updated labels / values are present in the cloned chart XML |
+| Native chart data | Updated labels / values are readable from the extracted Markdown when `ppt_to_md.py` can surface them |
| Multi-line body text | Preserves intended line / paragraph breaks |
-| Speaker notes | `ppt_to_md.py` can read the generated PPTX without notes-related errors |
+| Speaker notes | Read-back note count matches planned `notes` fields |
| Missing target errors | None from `template_fill_pptx.py apply` |
If the extracted text is correct but visual overflow is likely, reduce the text in `fill_plan.json` and re-run Step 4.
@@ -281,10 +305,11 @@ If the extracted text is correct but visual overflow is likely, reduce the text
- [x] Standard PPTX intake extracted from the source deck, including `<stem>.slide_library.json`
- [x] `fill_plan.json` selects only pages that fit the target story
-- [x] `check-plan` run and capacity warnings resolved or explicitly accepted
+- [x] User reviewed the story structure and `fill_plan.json` has `status: "confirmed"`
+- [x] `check-plan` run; errors fixed; warnings reviewed / optionally recorded in `accepted_warnings`
- [x] Output PPTX generated through direct OOXML text replacement
- [x] Speaker notes embedded when `notes` fields are present
-- [x] `ppt_to_md.py` readability check passed
+- [x] `template_fill_pptx.py validate` read-back check passed
```
---