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(workflow-log): record project-scoped execution transcripts

hugohe3663fe419ec71
diff --git a/docs/technical-design.md b/docs/technical-design.md
index ddf0424f..8be1a500 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -24,13 +24,21 @@ The intermediate language distinguishes three input states:
For example, project typography uses SVG px semantics, with finite unitless values such as `font-size="24"` as the canonical spelling. Another unit remains compatible input only when the converter has a deterministic normalization and the checker accepts it as compatible; it must not become a new generated spelling. Compatible reads are a controlled migration boundary, not permission to widen the authoring language.
-The three layers have separate responsibilities and cannot substitute for one another:
+The workflow, authoring guidance, and deterministic tool layers have separate
+responsibilities and cannot substitute for one another:
| Layer | Single responsibility | Explicit non-responsibility |
|---|---|---|
+| Generate workflow | Sequence stages, invoke gates, switch roles, and hand artifacts to their declared consumers | It does not absorb Strategist, Executor, checker, or exporter decisions merely because it coordinates them |
| Prompts, templates, and examples | State the project-canonical spelling precisely and reduce drift and warnings at the source | They are not a correctness or safety boundary |
| `svg_quality_checker.py` | Enforce the project contract on authoring state; errors block and non-blocking warnings pass | It does not silently rewrite pages or guess design intent |
| `svg_to_pptx.py` | Defensively validate compiler mappings and the package, normalize supported compatible forms, require a current matching final quality report for formal release, and link it into postflight | It does not rerun the complete `svg_quality_checker.py` or treat file creation as proof that the upstream quality gate passed |
+| `workflow_transcript.py` / `workflow_log.py` | Automatically mirror project-scoped Python text stdout/stderr and explicitly append important non-Python audit events | They do not interpret output, infer readiness, rerun another tool, or alter the owning tool's result |
+
+The automatic recorder resolves the project from `PPT_MASTER_PROJECT_PATH`, a
+path-bearing argument, or the current working directory, in that order. The
+environment signal is needed only for stdout-oriented helpers with no project
+path; it is placed on the same Python command and creates no wrapper process.
---
@@ -92,6 +100,7 @@ Output:
└── <project_name>_<timestamp>_narrated.pptx ← --recorded-narration or --narration-audio-dir variant
validation/
+ ├── workflow.log ← Automatic Python-output transcript + important manual audit events
├── svg_quality_report.json ← Blocking/introduced/inherited/source-import SVG findings
└── <output_stem>.report.json ← Postflight package/resource audit linked to the final SVG quality report
@@ -305,8 +314,9 @@ Two converter design choices still shape the system:
## Project Structure & Lifecycle
`project_manager.py init` creates the standard project working directories;
-`--quick-generate` creates only `svg_output/`, omits the project README, and
-leaves other directories on demand. The explicit
+`--quick-generate` creates `svg_output/` plus the cold
+`validation/workflow.log` transcript, omits the project README, and leaves
+other directories on demand. The explicit
[`quick-generate`](../skills/ppt-master/workflows/profiles/quick-generate.md)
profile omits planning artifacts and `svg_final/`, but its project may still
contain converted sources, analysis, images, icons, rendered formulas, and
@@ -325,7 +335,7 @@ backup around the final PPTX. The default delivery lifecycle is:
| `svg_final/` | mandatory normal-flow derived visual-preview SVGs; supported bitmap/SVG resources are inlined when possible, while EMF/WMF retain an external-reference exception; used for IDE/browser preview or manual insertion as SVG pictures |
| `live_preview/` | preview server state, edit history, and annotation logs |
| `notes/` | `total.md` and split per-slide speaker notes |
-| `validation/` | SVG quality reports and PPTX postflight audit reports |
+| `validation/` | cold workflow transcript, SVG quality reports, and PPTX postflight audit reports |
| `exports/` | timestamped native PPTX deliverables |
| `backup/<timestamp>/` | default export creates the timestamped directory, then attempts a frozen `svg_output/` copy; copy failure does not fail export, but directory-creation failure is not currently downgraded |
@@ -514,8 +524,12 @@ Strategist and confirmation layer; it does not remove preparation.
| Restaurant | PPT Master | Authority |
|---|---|---|
| Customer and initial ingredients | User confirmation and supplied sources/assets | Defines facts, intent, exclusions, acquisition permissions, and how specific the requested outcome is |
+| Service coordinator | Generate workflow | Sequences the declared stages, gates, role switches, and handoffs without taking over any role's decisions or deterministic tool's checks |
| Menu planner and preparation lead | Strategist, `design_spec.md`, `spec_lock.md`, and Strategist-owned acquisition stages | Assesses sufficiency; fills permitted factual gaps; selects the content, resources, page roster, chart-reference/template-layout keys, fonts, palette anchors, icon system and curated pool, and crop boundaries; records optional capability/expression recommendations; readies the complete project-local inventory before execution |
| Cook | Executor | Uses only prepared project-local assets and realizes the plan through geometry, composition, hierarchy, spacing, and treatment without changing the selected “dish” or acquiring/substituting ingredients; chooses suitable prepared icons per page and may adapt fields explicitly labeled as suggestions or References |
+| Quality inspector | `svg_quality_checker.py` | Reads authoring state and reports contract findings; it does not edit pages, own the page roster, or package the deck |
+| Packager | `svg_to_pptx.py` | After a matching final report passes, compiles the authored SVG, validates the package, and publishes the receipt; it does not repair SVG or rerun the checker |
+| Run recorder | `workflow_transcript.py`, `workflow_log.py`, and `validation/workflow.log` | Automatically mirrors project-scoped Python text stdout/stderr and accepts explicitly selected important non-Python events; it does not decide what the output means or whether the workflow may advance |
**Quick generation collapses planning into the current agent.** Source conversion,
factual-gap research, and resource preparation still run when needed. The agent
@@ -524,6 +538,9 @@ needs in active context, prepares supplied/extracted/AI/web/sliced images,
icons, and formulas with their required manifests or provenance records, and
then hand-authors SVG. It does not invoke Strategist, Confirm UI,
`design_spec.md`, or `spec_lock.md`.
+One agent may therefore perform several creative stages in sequence, but their
+ownership boundaries do not merge; checker, exporter, and transcript recorder
+remain separate deterministic tools.
**Default preparation has two clocks.** Topic Research supplies facts before final confirmation: it starts immediately for topic-only input, or after supplied material is converted/read when planning-critical factual gaps remain. It supplements only those gaps and acquires no images. When the current AI editor provides an isolated worker with web/fetch access and write access to the declared outputs, the main agent defines the gaps and the worker writes the existing research/provenance artifacts, returning only a receipt; otherwise research runs in the main context. AI / web / slice image acquisition runs only after final confirmation and the completed `design_spec.md §VIII` / `spec_lock.md`, then reaches a terminal status before Executor starts. Strategist also resolves, syncs, and validates a curated project icon pool while authoring the final plan. Image_Generator, Image_Searcher, and icon-sync tooling are preparation mechanisms under Strategist ownership, not independent decision owners. Quick generation uses those preparation mechanisms as needed under the current agent's in-context decisions, without inserting a confirmation gate.
@@ -642,7 +659,20 @@ The post-processing and export stages keep authoring, validation, preview, deliv
| `exports/<narrated_stem>.mp4` (optional via `powerpoint_video.py`) | animation-faithful narrated video on Windows PowerPoint 2016+ | delegates to PowerPoint's native encoder and waits for completion; it is a post-PPTX integration, not a second deck renderer |
| `backup/<ts>/svg_output/` (default output path only; copy is best-effort after directory creation) | re-export from frozen SVG sources without rerunning the LLM | after successful conversion the exporter creates the backup directory and attempts the copy; explicit `-o` creates none, copy failure does not block export, prints a warning outside quiet mode, and leaves postflight `backup_path` empty, while directory-creation failure remains fatal |
-Validation JSON files are cold audit artifacts, not routine model inputs. The exporter reads the SVG quality report programmatically and, in the default non-quiet flow, prints a compact `[POSTFLIGHT]` receipt with the status, quality-gate result, Slide count, warning-category counts, and artifact paths. Successful agents consume that receipt instead of loading either complete JSON; only failure investigation or an explicit audit extracts targeted report fields.
+Validation JSON files and `validation/workflow.log` are cold audit artifacts,
+not routine model inputs. The workflow transcript is opened only when the user
+explicitly requests a run review. It can reconstruct observed commands and
+their text output, plus selected non-Python details such as a material stage
+handoff or rework reason, user-approved exception, or manual recovery choice.
+These manual entries are optional and never duplicate artifacts, routine
+progress, or private reasoning; current artifacts still establish the stage
+and readiness. The
+exporter reads the SVG quality report programmatically and, in the default
+non-quiet flow, prints a compact `[POSTFLIGHT]` receipt with the status,
+quality-gate result, Slide count, warning-category counts, and artifact paths.
+Successful agents consume that receipt instead of loading either complete
+JSON; only failure investigation or an explicit audit extracts targeted report
+fields.
### SVG preprocessors have TWO usage forms
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 1cc2a95d..62ebd5f7 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -24,13 +24,17 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
例如,项目字号统一采用 SVG px 语义,规范写法是有限的无单位数值(如 `font-size="24"`);其他单位只有在转换器已有确定性换算、Checker 也按兼容输入放行时才可保留,不能成为生成提示词的新写法。兼容读取是一条受控迁移边界,不是放宽创作语言的理由。
-三层职责必须分开,不能用其中一层替代另一层:
+流程、创作规范与确定性工具各自承担单一职责,不能互相替代:
| 层级 | 单一职责 | 不承担的职责 |
|---|---|---|
+| Generate 流程 | 编排阶段、调用门禁、切换角色,并把制品交给声明的消费者 | 不会因为自己负责协调,就吸收 Strategist、Executor、Checker 或 Exporter 的决策权 |
| 提示词、模板与示例 | 精确表达项目规范写法,从源头减少偏差和 warning | 不作为正确性或安全边界 |
| `svg_quality_checker.py` | 在作者状态上执行项目合同;error 阻塞,非阻塞 warning 放行 | 不静默改写页面,也不猜测设计意图 |
| `svg_to_pptx.py` | 对编译映射与 package 执行防御校验;归一化已支持的兼容形式;正式发布前要求当前匹配的 final 质量报告,并把它关联进 postflight | 不重跑完整 `svg_quality_checker.py`,也不以“文件已生成”替代前置质量门 |
+| `workflow_transcript.py` / `workflow_log.py` | 自动转录项目级 Python 工具的文本 stdout/stderr,并显式追加重要的非 Python 审计事项 | 不解释输出、推断就绪状态、重跑其他工具,也不改变所属工具的结果 |
+
+自动记录器依次从 `PPT_MASTER_PROJECT_PATH`、带路径的命令参数和当前工作目录解析项目。只有不携带项目路径、以 stdout 为主要输出的 helper 才需要在同一条 Python 命令前设置该环境信号;它不会再启动包装进程。
---
@@ -85,6 +89,7 @@ PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使
└── <project_name>_<timestamp>_narrated.pptx ← --recorded-narration 或 --narration-audio-dir 变体
validation/
+ ├── workflow.log ← 自动 Python 输出转录与重要人工审计事项
├── svg_quality_report.json ← blocking / introduced / inherited / source-import 分类结果
└── <output_stem>.report.json ← 关联最终 SVG 质量报告的 package / 资源审计
@@ -290,7 +295,8 @@ SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可
## 项目结构与生命周期
`project_manager.py init` 默认创建标准项目工作目录;使用
-`--quick-generate` 时只创建 `svg_output/`,省略项目 README,其他目录按需产生。
+`--quick-generate` 时创建 `svg_output/` 与冷转录
+`validation/workflow.log`,省略项目 README,其他目录按需产生。
显式
[`quick-generate`](../../skills/ppt-master/workflows/profiles/quick-generate.md)
profile 省略规划产物与 `svg_final/`,但项目中仍可按需存在已转换来源、分析结果、
@@ -308,7 +314,7 @@ profile 省略规划产物与 `svg_final/`,但项目中仍可按需存在已
| `svg_final/` | 强制派生的视觉预览 SVG;尝试内联受支持位图 / SVG,保留 EMF/WMF 外链例外;服务 IDE / 浏览器,也可手动作为 SVG 图片插入 PowerPoint |
| `live_preview/` | 预览服务状态、直接编辑历史和注解日志 |
| `notes/` | `total.md` 与拆分后的逐页讲稿 |
-| `validation/` | SVG 质量报告与 PPTX postflight 审计报告 |
+| `validation/` | 冷流程转录、SVG 质量报告与 PPTX postflight 审计报告 |
| `exports/` | 带时间戳的 native PPTX 交付物 |
| `backup/<timestamp>/` | 默认导出先创建时间戳目录,再尝试复制冻结的 `svg_output/`;复制失败不令导出失败,但目录创建失败当前不会降级处理 |
@@ -462,10 +468,15 @@ Generate 执行以 [`workflows/generate-pptx.md`](../../skills/ppt-master/workfl
| 餐厅角色 | PPT Master 对应项 | 决策权 |
|---|---|---|
| 顾客与初始食材 | 用户确认与用户提供的原材料/素材 | 决定事实、意图、排除项、材料补充许可,以及要求具体到什么程度 |
+| 流程协调者 | Generate 流程 | 排列已声明的阶段、门禁、角色切换和交接,不接管任何角色的决策或确定性工具的检查 |
| 菜单策划与备料负责人 | Strategist、`design_spec.md`、`spec_lock.md` 及其负责的材料获取阶段 | 判断材料是否充分;补齐获准补充的事实;选定内容、资源、页面清单、图表参考 key / 模板版式 key、字体、色板锚点、图标系统与精选图标池、裁剪边界;记录可选的能力 / 表达建议;在执行前备齐项目级材料清单 |
| 厨师 | Executor | 只使用项目中已备好的材料,以几何、构图、层级、间距和视觉处理实现方案;不得改变所选“菜品”,也不得自行找料、换料;按页选择适合的已备图标,并可调整明确标为 suggestion 或 Reference 的字段 |
+| 质检员 | `svg_quality_checker.py` | 只读取作者状态并报告合同问题;不改页面、不拥有页面清单,也不打包 deck |
+| 打包员 | `svg_to_pptx.py` | 匹配的 final 报告通过后,编译已创作 SVG、校验 package 并发布回执;不修 SVG,不重跑 Checker |
+| 运行记录员 | `workflow_transcript.py`、`workflow_log.py` 与 `validation/workflow.log` | 自动转录项目级 Python 工具的文本 stdout/stderr,并接收显式选定的重要非 Python 事项;不解释输出,也不决定流程是否可以前进 |
**快速生成把规划职责合并到当前 Agent。** 来源转换、事实缺口研究和资源准备仍按需运行。当前 Agent 在上下文中自动选择内容、页面清单、视觉系统和资源需求,准备用户提供 / 来源抽取 / AI / 网络 / 切片图片、图标和公式及其必要 manifest 或来源记录,随后手写 SVG;不进入 Strategist、Confirm UI、`design_spec.md` 或 `spec_lock.md`。
+因此同一 Agent 可以顺序承担多个创作阶段,但阶段权责不会合并;Checker、Exporter 与运行记录器仍是独立的确定性工具。
**默认备料有两个时点。** Topic Research 在最终确认前补充规划所需的事实:只有主题时立即运行;已有材料时先转换 / 阅读,仅在仍有关键事实缺口时补齐,而且不获取任何图片。当前 AI 编辑器若能提供具备网页检索 / 抓取能力并可写入声明输出路径的隔离研究子代理,由主代理定义缺口,子代理写入现有研究及来源产物并只返回回执;否则研究仍在主上下文运行。AI / web / slice 图片只能在最终确认以及完整的 `design_spec.md §VIII` / `spec_lock.md` 之后获取,并在 Executor 开始前进入终态。Strategist 还会在编写最终方案时解析、同步并验证精选项目图标池。Image_Generator、Image_Searcher 与图标同步工具只是 Strategist 负责的备料机制,不是独立决策者。快速生成则由当前 Agent 根据上下文决策按需使用这些备料机制,不插入确认门禁。
@@ -584,7 +595,7 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“
| `exports/<narrated_stem>.mp4`(可选,经 `powerpoint_video.py`) | Windows PowerPoint 2016+ 下保留动画与旁白的视频交付物 | 委托 PowerPoint 原生编码器并等待完成;它是 PPTX 后处理集成,不是第二套 deck 渲染器 |
| `backup/<ts>/svg_output/`(仅默认输出路径;目录创建后复制为 best-effort) | 在不重跑 LLM 的前提下从冻结 SVG 源重建 pptx | 转换成功后先创建备份目录再尝试复制;显式 `-o` 不创建,复制失败不阻断导出,非 quiet 模式打印 warning,postflight 的 `backup_path` 为空,但目录创建失败仍会中断 |
-校验 JSON 是冷审计产物,不是常规模型输入。导出器在程序内部读取 SVG 质量报告,并在默认非 quiet 流程打印紧凑的 `[POSTFLIGHT]` 回执,包含状态、质量门结果、Slide 数量、warning 类别计数和产物路径。成功流程只消费该回执,不加载两份完整 JSON;只有失败排查或用户明确要求审计时才定向提取报告字段。
+校验 JSON 与 `validation/workflow.log` 都是冷审计产物,不是常规模型输入。只有用户明确要求复核运行过程时才打开转录。它可以还原项目级 Python 工具及其文本输出,也允许选择性记录重要阶段交接或返工原因、用户批准的例外及人工恢复选择等非 Python 事项;这些人工记录不重复制品内容、常规页面进度或私有推理,也不能替代当前制品对阶段与就绪状态的判定。导出器在程序内部读取 SVG 质量报告,并在默认非 quiet 流程打印紧凑的 `[POSTFLIGHT]` 回执,包含状态、质量门结果、Slide 数量、warning 类别计数和产物路径。成功流程只消费该回执,不加载两份完整 JSON;只有失败排查或用户明确要求审计时才定向提取报告字段。
### SVG 预处理器有**两种使用形态**
diff --git a/skills/ppt-master/references/artifact-ownership.md b/skills/ppt-master/references/artifact-ownership.md
index 1ae3ec99..bf84f4a6 100644
--- a/skills/ppt-master/references/artifact-ownership.md
+++ b/skills/ppt-master/references/artifact-ownership.md
@@ -52,6 +52,7 @@ package postflight as the default profile, but it does not create `svg_final/`.
| `notes/total.md` | Conditional speaker-note source | Complete notes before splitting | Step 6 writes only when the effective Speaker Notes outcome is enabled; Step 7.1 splits |
| `notes/slide_*.md` | Conditional split notes | Per-slide notes generated from `total.md` | Derived by `total_md_split.py` only when speaker notes are enabled |
| `svg_final/` | Default-only derived visual preview | Self-contained post-processed SVGs that may be opened directly or inserted as SVG pictures | Default rebuilds it from `svg_output/` with `finalize_svg.py`; Quick omits it. Never use it as a supported PPTX source. |
+| `validation/workflow.log` | Cold workflow transcript | Append-only Python command envelopes with tagged stdout/stderr, plus selective manual entries for important details with no owning Python output | `project_manager.py init` creates the log and records its milestone. Later project-scoped Python tools find that existing log through the shared CLI bootstrap and mirror their own text output without a wrapper command. A helper whose arguments/cwd do not identify the active project receives `PPT_MASTER_PROJECT_PATH=<project_path>` on the same Python command. A role may run `workflow_log.py` once for a material non-Python stage handoff or rework reason, user-approved exception, or manual recovery choice; never duplicate artifacts, routine progress, or private reasoning. Detached services retain detailed output in their component logs. Never read this transcript during normal generation/resume or use it as stage, artifact, or quality authority; inspect it only for an explicit user-requested run review. |
| `validation/svg_quality_report.json` | Final SVG quality provenance | Final SVG gate split into blocking / introduced / inherited / source-import categories, bound to the checked SVG bytes by SHA-256 | Default runs `svg_quality_checker.py --stage final --json`; Quick adds `--quick-generate` so the checker ignores Design Spec/lock and validates the lockless flat roster. Export links the report only when fingerprints match; Quick requires that link to pass before PPTX creation. |
| `validation/<output_stem>.report.json` | Published-package audit | PPTX package/resource postflight status, part counts, and quality-gate linkage | Both Generate profiles write it and emit `[POSTFLIGHT]` after package validation. |
| `exports/` | Delivery artifacts | Native DrawingML PPTX and explicit native-object/narration variants | Default Step 7.3 or Quick direct export writes final deliverables from `svg_output/`. |
@@ -78,6 +79,7 @@ package postflight as the default profile, but it does not create `svg_final/`.
| 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. |
+| Workflow transcript | `validation/workflow.log` automatically records text written through a project-scoped Python tool's configured `sys.stdout` / `sys.stderr`, plus explicitly selected manual audit entries. It does not 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 line proves nothing about those stages. Automatic transcript 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. |
| Confirmation | Final UI/chat confirmation overrides recommendations and is consumed once into `design_spec.md`. Enabled refinement applies arbitrary revisions there and requires approval; only then may active-decision fidelity release lock authoring. |
@@ -90,6 +92,10 @@ package postflight as the default profile, but it does not create `svg_final/`.
## 3. Regeneration Rules
+The table names each owning command. Generate profiles invoke these commands
+directly; project-scoped Python stdout/stderr is recorded automatically after
+initialization. Other routes retain their own invocation contract.
+
| Derived artifact | Regenerate from | Command / owner |
|---|---|---|
| `analysis/image_analysis.csv` | Current `images/` | `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` |
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 44617c7e..ee1e89ec 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -56,7 +56,7 @@ Before the first SVG page, output a confirmation listing: the compact communicat
**On-demand page-context diagnostic**: only for explicit telemetry/debugging or an unresolved page/template/chart path-SHA question; never as a pre-page gate:
```bash
-python3 skills/ppt-master/scripts/project_manager.py page-context <project_path> P<NN> [--record-usage]
+python3 ${SKILL_DIR}/scripts/project_manager.py page-context <project_path> P<NN> [--record-usage]
```
Consume stdout directly; stop on non-zero exit. The projection is derived, not authoritative. Use `--record-usage` only for measurement.
@@ -147,8 +147,8 @@ Before drawing each page, look up its entry in `page_rhythm` (key format `P<NN>`
- **Reference — prefer semantic geometry over preset stacks**: for relationships such as ascending, converging, breaking through, or stacking, first seek a basic primitive, one exact preset, or a clear Boolean result. Only when none can faithfully express the relationship should one page-specific polygon/path replace a stack of generic arrows.
- **Reference — create depth with restraint**: use rhythm, spacing, typography, accent bars, and subtle tints before shadows. Reserve lift for a few genuinely floating elements; keep peer grids, dividers, and body containers flat.
- **Phased generation** (recommended):
- 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every §IX-planned data-chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every planned native-ready object. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 scripts/svg_quality_checker.py <project_path> --stage first-page --json` without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls.
- 2. **Quality Check Gate**: only after every planned SVG exists, run `python3 scripts/svg_quality_checker.py <project_path> --stage final --json` on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
+ 1. **Visual Construction Phase**: generate all SVG pages sequentially for visual consistency. Use layout judgment for chart marks during the draft. **MUST embed plot-area markers** per [`executor-chart.md`](./executor-chart.md) §2.1 on every §IX-planned data-chart page — coordinate calibration is a post-generation step (see [`verify-charts`](../workflows/stages/verify-charts.md)) that depends on these markers — and **native object metadata** per [`executor-chart.md`](./executor-chart.md) §2.2 on every planned native-ready object. **Reach for native presets** per §3.0 as you draw each page: a block arrow, chevron, banner/ribbon, callout, standard flowchart node, or star is authored through `preset_shape_svg.py` at draw time — decided by the object's intent as you create it, never by scanning finished paths, and never committed to a bare `<path>`/`<polygon>` when a preset expresses it (a gradient fill/stroke or a pattern fill is the one paint exception — keep those ordinary SVG). **First-page gate (Mandatory)**: after completing the first page, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage first-page --json` directly without output filtering. Review the whole P01 issue set, make one consolidated edit pass for every error and any selected warnings, then perform one verification rerun. If it still fails, treat that complete output as the next batch; never check between individual fixes. After it passes, draw P02 through the last page without checker calls.
+ 2. **Quality Check Gate**: only after every planned SVG exists, run `python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final --json` directly on `svg_output/` without `tail` / `head` / `grep` filtering. One run already reports all pages. Review its complete issue set, fix every `error` plus any selected advisory warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, its complete output begins the next batch cycle; never use checker calls to discover or fix one next issue at a time. Every `warning` is advisory: it never sends the page back for required modification, never authorizes automatic rewriting of compatible user syntax, and needs no acknowledgement/disposition line. Recommendation warnings describe the generated-SVG default; fidelity/quality warnings may be surfaced when material, while the existing input remains releasable. Prototype-identical diagnostics are recorded as `inherited`, source conversion losses as `source-import`, changed/new advisories as `introduced`, and release failures as `blocking` in `validation/svg_quality_report.json`. If release truly depends on a condition, it belongs in `errors`. On success, use the exit status and terminal summary; do not open or `cat` the complete JSON into model context. If terminal output is truncated on failure, read only the relevant issue arrays from the report written by that same run. Do NOT defer error handling to after `finalize_svg.py` — finalize rewrites SVG and masks some violations.
3. **Logic Construction Phase (conditional)**: after SVGs pass the quality check, batch-generate speaker notes for narrative continuity only when the effective Speaker Notes outcome is enabled.
### 3.0 Native Shape Selection
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index a9ba9e5d..3939d842 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -35,6 +35,10 @@ python3 scripts/animation_config.py scaffold <project_path> # optional object-l
python3 scripts/svg_to_pptx.py <project_path>
```
+After `init`, project-scoped Python CLIs automatically mirror their text
+stdout/stderr into `<project_path>/validation/workflow.log`; invoke them
+directly, without a logging wrapper.
+
Repository update:
```bash
@@ -46,7 +50,7 @@ python3 scripts/update_repo.py
| Area | Primary scripts | Documentation |
|------|-----------------|---------------|
| Conversion | `source_to_md.py`, `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py`, `pptx_to_svg.py` | [docs/conversion.md](./docs/conversion.md) |
-| Project management | `project_manager.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py`, `pptx_delivery_check.py` | [docs/project.md](./docs/project.md) |
+| Project management | `project_manager.py`, `workflow_log.py`, `workflow_transcript.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py`, `pptx_delivery_check.py` | [docs/project.md](./docs/project.md) |
| SVG pipeline | `preset_shape_svg.py`, `shape_boolean_svg.py`, `svg_authoring_view.py`, `compact_svg_coordinates.py`, `mirror_template_materialize.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `extract_svg_pictures.py`, `animation_config.py`, `notes_to_audio.py`, `narration_sync.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native shape authoring](../references/native-shape-authoring.md) |
| PPTX transitions | `pptx_transitions.py` | [docs/pptx-transitions.md](./docs/pptx-transitions.md) |
| PPTX animations | `pptx_animations.py`, `animation_config.py` | [docs/pptx-animations.md](./docs/pptx-animations.md) |
diff --git a/skills/ppt-master/scripts/console_encoding.py b/skills/ppt-master/scripts/console_encoding.py
index 6d3a1862..8970f24d 100644
--- a/skills/ppt-master/scripts/console_encoding.py
+++ b/skills/ppt-master/scripts/console_encoding.py
@@ -10,6 +10,7 @@ from pathlib import Path
from typing import TextIO
from attribution_guard import require_skill_integrity
+from workflow_transcript import install_auto_transcript
_SKILL_DIR = Path(__file__).resolve().parent.parent
@@ -79,8 +80,9 @@ def _reconfigure_stream(stream: TextIO) -> TextIO:
def configure_utf8_stdio() -> None:
- """Use UTF-8 for CLI stdout/stderr, including Windows non-UTF-8 locales."""
+ """Configure CLI streams and enable project-scoped output recording."""
require_skill_integrity()
_require_official_distribution_identity()
sys.stdout = _reconfigure_stream(sys.stdout)
sys.stderr = _reconfigure_stream(sys.stderr)
+ install_auto_transcript()
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index 4bad07fd..1ea15c41 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -22,7 +22,8 @@ python3 scripts/project_manager.py page-context-report <project_path>
```
Notes:
-- `init --quick-generate`: only `svg_output/`; no README
+- `init --quick-generate`: `svg_output/` plus
+ `validation/workflow.log`; no README
- Files outside `projects/` are always copied into `sources/`
- `--move` applies only to sources under the repository's `projects/` tree
- A directly supplied supported bitmap is also copied into `images/` with a
@@ -146,6 +147,53 @@ python3 scripts/project_manager.py page-context projects/my_presentation_ppt169_
python3 scripts/project_manager.py page-context-report projects/my_presentation_ppt169_20251116
```
+## `workflow_transcript.py` and `workflow_log.py`
+
+Project initialization creates `validation/workflow.log` and records its own
+milestone. Run later project-scoped Python tools normally:
+
+```bash
+python3 scripts/<tool>.py <project_path> <args...>
+```
+
+Their shared CLI bootstrap discovers the existing project log from the working
+directory or command arguments. `workflow_transcript.py` mirrors text written
+through configured `sys.stdout` / `sys.stderr` as tagged logical lines under a
+UTC Python-command envelope; no outer launcher or second Python process is
+used. Commands before project initialization are not backfilled. Binary-buffer
+writes, hidden child output, and detached service activity are not copied;
+Confirm UI and live preview retain detailed output in their component
+`server.log` files. Their shared detached-process launcher disables automatic
+workflow transcription in the long-running child while preserving the short
+foreground launcher's own record.
+
+For a Python helper whose arguments and working directory do not identify the
+active project, set the routing signal on the same command:
+
+```bash
+PPT_MASTER_PROJECT_PATH="<project_path>" python3 scripts/<helper>.py <args...>
+```
+
+This variable selects only the destination transcript; it does not authorize
+the helper to read project artifacts or change its ownership.
+
+Append a manual note only when an important audit detail has no owning command
+output:
+
+```bash
+python3 scripts/workflow_log.py <project_path> "<material audit detail>"
+```
+
+Suitable notes include a material stage handoff or rework reason, a
+user-approved exception, or a manual recovery choice. Do not duplicate
+artifact contents, routine page progress, or private reasoning.
+
+The transcript is append-only audit evidence. It is not a stage, quality, or
+artifact authority and is not read during normal generation or resume. Inspect
+it only when the user explicitly requests a run review. An automatic transcript
+failure emits a warning but does not change the Python tool's result; an
+explicit manual entry that cannot be written exits non-zero.
+
## `project_utils.py`
Shared helper module used by other scripts.
diff --git a/skills/ppt-master/scripts/project_management/cli.py b/skills/ppt-master/scripts/project_management/cli.py
index 2ff337c7..29e1cccd 100644
--- a/skills/ppt-master/scripts/project_management/cli.py
+++ b/skills/ppt-master/scripts/project_management/cli.py
@@ -52,6 +52,7 @@ if str(SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(SCRIPTS_DIR))
from attribution_guard import require_skill_integrity # noqa: E402
+from workflow_log import append_note # noqa: E402
try:
from project_utils import (
@@ -313,7 +314,7 @@ class ProjectManager:
"- `live_preview/`: browser preview runtime files and history (lock.json, server.log, edits.jsonl, annotations.jsonl)\n"
"- `sources/`: source materials and normalized markdown\n"
"- `analysis/`: machine-extracted intermediate analysis (PPTX intake, image_analysis.csv) — the pipeline's canonical must-read source/asset facts\n"
- "- `validation/`: SVG quality reports and PPTX postflight audit reports\n"
+ "- `validation/`: cold workflow transcript, SVG quality reports, and PPTX postflight audit reports\n"
"- `exports/`: final native DrawingML pptx deliverables only (timestamped); `_native_charts_tables.pptx` name with `--native-charts-and-tables`, `_narrated.pptx` name when narration audio is embedded\n"
"- `backup/<timestamp>/`: svg_output/ archive (always written in default-flow mode; safe to delete old timestamps)\n"
),
@@ -1079,7 +1080,10 @@ def build_parser() -> argparse.ArgumentParser:
init.add_argument(
"--quick-generate",
action="store_true",
- help="Create only the svg_output directory and omit README.md",
+ help=(
+ "Create svg_output plus the validation workflow transcript and "
+ "omit README.md"
+ ),
)
import_sources = subparsers.add_parser(
@@ -1164,10 +1168,23 @@ def main(argv: list[str] | None = None) -> int:
if args.quick_generate:
print("1. Generate SVG files into svg_output/")
print("2. Run the Quick Generate final checker and exporter")
+ profile = "quick"
else:
print("1. Put source files into sources/ (or use import-sources)")
print("2. Save your design spec to the project root")
print("3. Generate SVG files into svg_output/")
+ profile = "default"
+ try:
+ append_note(
+ project_path,
+ f"Project initialized: profile={profile}; "
+ f"canvas={args.format}; path={project_path}",
+ )
+ except OSError as exc:
+ print(
+ f"[WARN] Workflow transcript unavailable: {exc}",
+ file=sys.stderr,
+ )
return 0
if args.command == "import-sources":
diff --git a/skills/ppt-master/scripts/server_common.py b/skills/ppt-master/scripts/server_common.py
index f4c99ff7..6efdbdd7 100644
--- a/skills/ppt-master/scripts/server_common.py
+++ b/skills/ppt-master/scripts/server_common.py
@@ -23,6 +23,8 @@ import subprocess
from pathlib import Path
from typing import Optional
+from workflow_transcript import DISABLE_TRANSCRIPT_ENV
+
MIN_PORT = 1
MAX_PORT = 65535
@@ -75,7 +77,15 @@ def popen_detached(
caller's Job Object. ``CREATE_BREAKAWAY_FROM_JOB`` lets the local UI server
survive after the launcher command returns; when that flag is forbidden, the
function falls back to the previous detached-process flags.
+
+ Detached service output remains in its component log, so the child receives
+ the shared workflow-transcript opt-out environment flag.
"""
+ supplied_env = kwargs.get('env')
+ child_env = dict(os.environ if supplied_env is None else supplied_env)
+ child_env[DISABLE_TRANSCRIPT_ENV] = '1'
+ kwargs['env'] = child_env
+
if os.name != 'nt':
return subprocess.Popen(args, start_new_session=True, **kwargs)
diff --git a/skills/ppt-master/scripts/workflow_log.py b/skills/ppt-master/scripts/workflow_log.py
new file mode 100644
index 00000000..486f8345
--- /dev/null
+++ b/skills/ppt-master/scripts/workflow_log.py
@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Workflow Log
+
+Append one manually selected important event to a project's cold audit log.
+
+Usage:
+ python3 scripts/workflow_log.py <project_path> <message>
+
+Examples:
+ python3 scripts/workflow_log.py projects/demo "Strategist handoff complete"
+ python3 scripts/workflow_log.py projects/demo "Reworked P07 after source-label mismatch"
+
+Dependencies:
+ None (standard library only)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from console_encoding import configure_utf8_stdio # noqa: E402
+
+WORKFLOW_LOG_RELATIVE_PATH = Path("validation/workflow.log")
+
+
+def _utc_timestamp() -> str:
+ """Return a compact UTC timestamp."""
+ return (
+ datetime.now(timezone.utc)
+ .isoformat(timespec="milliseconds")
+ .replace("+00:00", "Z")
+ )
+
+
+def workflow_log_path(project_path: str | Path) -> Path:
+ """Return the canonical workflow-log path for a project."""
+ return Path(project_path) / WORKFLOW_LOG_RELATIVE_PATH
+
+
+def append_note(project_path: str | Path, message: str) -> Path:
+ """Append one important event without interpreting workflow state."""
+ log_path = workflow_log_path(project_path)
+ log_path.parent.mkdir(parents=True, exist_ok=True)
+ record = (
+ f"\n=== {_utc_timestamp()} NOTE id={uuid.uuid4().hex[:12]} ===\n"
+ f"{message.rstrip()}\n"
+ )
+ with log_path.open(
+ "a",
+ encoding="utf-8",
+ errors="replace",
+ newline="",
+ ) as handle:
+ handle.write(record)
+ handle.flush()
+ return log_path
+
+
+def build_parser() -> argparse.ArgumentParser:
+ """Build the command-line parser."""
+ parser = argparse.ArgumentParser(
+ description="Append one important event to validation/workflow.log.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("project_path", help="Existing project directory")
+ parser.add_argument("message", help="Concise important event")
+ return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+ """Run the CLI entry point."""
+ configure_utf8_stdio()
+ parser = build_parser()
+ args = parser.parse_args(argv)
+ project_path = Path(args.project_path)
+ if not project_path.is_dir():
+ parser.error(f"project path does not exist: {project_path}")
+
+ message = args.message.strip()
+ if not message:
+ parser.error("message must not be empty")
+ try:
+ log_path = append_note(project_path, message)
+ except OSError as exc:
+ print(
+ f"[ERROR] Could not append workflow event to "
+ f"{workflow_log_path(project_path)}: {exc}",
+ file=sys.stderr,
+ )
+ return 1
+ print(f"[OK] Workflow event appended: {log_path}", file=sys.stderr)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/workflow_transcript.py b/skills/ppt-master/scripts/workflow_transcript.py
new file mode 100644
index 00000000..3b2a61bd
--- /dev/null
+++ b/skills/ppt-master/scripts/workflow_transcript.py
@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Automatic Workflow Transcript
+
+Internal runtime helper that mirrors a project-scoped Python tool's text
+stdout/stderr into an existing project workflow log.
+
+Dependencies:
+ None (standard library only)
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import sys
+import threading
+import time
+import uuid
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TextIO
+
+WORKFLOW_LOG_RELATIVE_PATH = Path("validation/workflow.log")
+PROJECT_PATH_ENV = "PPT_MASTER_PROJECT_PATH"
+DISABLE_TRANSCRIPT_ENV = "PPT_MASTER_DISABLE_WORKFLOW_TRANSCRIPT"
+_EXCLUDED_ENTRYPOINTS = {"workflow_log.py"}
+_ACTIVE_TRANSCRIPT: _AutomaticTranscript | None = None
+
+
+def _utc_timestamp() -> str:
+ """Return a compact UTC timestamp."""
+ return (
+ datetime.now(timezone.utc)
+ .isoformat(timespec="milliseconds")
+ .replace("+00:00", "Z")
+ )
+
+
+def _candidate_directory(value: str) -> Path | None:
+ """Resolve one CLI value to an existing directory candidate."""
+ if not value or value.startswith("-") or "://" in value:
+ return None
+ try:
+ raw_path = Path(value)
+ except (OSError, ValueError):
+ return None
+ if not raw_path.exists() and raw_path.parent == Path("."):
+ return None
+ path = raw_path
+ if not path.is_absolute():
+ path = Path.cwd() / path
+ while not path.exists() and path != path.parent:
+ path = path.parent
+ if path.is_file():
+ path = path.parent
+ return path.resolve()
+
+
+def _find_project_root(argv: list[str]) -> Path | None:
+ """Find the first ancestor that already owns a workflow log."""
+ explicit_project = os.environ.get(PROJECT_PATH_ENV, "").strip()
+ values = [explicit_project, *argv[1:], str(Path.cwd())]
+ for value in values:
+ directory = _candidate_directory(value)
+ if directory is None:
+ continue
+ for candidate in (directory, *directory.parents):
+ if (candidate / WORKFLOW_LOG_RELATIVE_PATH).is_file():
+ return candidate
+ return None
+
+
+class _AutomaticTranscript:
+ """Append tagged logical lines without changing the owning tool."""
+
+ def __init__(
+ self,
+ handle: TextIO,
+ original_stderr: TextIO,
+ argv: list[str],
+ ) -> None:
+ self.handle = handle
+ self.original_stderr = original_stderr
+ self.argv = argv
+ self.run_id = uuid.uuid4().hex[:12]
+ self.started_clock = time.monotonic()
+ self.pending = {"stdout": "", "stderr": ""}
+ self.lock = threading.RLock()
+ self.enabled = True
+
+ def _disable(self, exc: OSError | UnicodeError | ValueError) -> None:
+ """Stop transcript writes without changing tool execution."""
+ self.enabled = False
+ try:
+ self.original_stderr.write(
+ f"[WARN] Workflow transcript stopped: {exc}\n"
+ )
+ self.original_stderr.flush()
+ except (OSError, ValueError):
+ pass
+
+ def _write(self, text: str) -> None:
+ """Append and flush one complete transcript record."""
+ if not self.enabled:
+ return
+ try:
+ self.handle.write(text)
+ self.handle.flush()
+ except (OSError, UnicodeError, ValueError) as exc:
+ self._disable(exc)
+
+ def start(self) -> None:
+ """Write the Python-command envelope."""
+ self._write(
+ f"\n=== {_utc_timestamp()} PYTHON run={self.run_id} ===\n"
+ f"cwd: {Path.cwd()}\n"
+ f"argv: {json.dumps(self.argv, ensure_ascii=False)}\n"
+ )
+
+ def write_stream(self, stream_name: str, text: str) -> None:
+ """Buffer fragments and write complete logical lines."""
+ if not text or not self.enabled:
+ return
+ with self.lock:
+ pending = self.pending[stream_name] + text
+ while "\n" in pending:
+ line, pending = pending.split("\n", 1)
+ self._write(
+ f"{_utc_timestamp()} "
+ f"[run={self.run_id} {stream_name}] {line}\n"
+ )
+ self.pending[stream_name] = pending
+
+ def flush_stream(self, stream_name: str) -> None:
+ """Flush a partial logical line when the owning stream flushes."""
+ with self.lock:
+ if not self.enabled:
+ self.pending[stream_name] = ""
+ return
+ pending = self.pending[stream_name]
+ if pending:
+ self._write(
+ f"{_utc_timestamp()} "
+ f"[run={self.run_id} {stream_name}] {pending}\n"
+ )
+ self.pending[stream_name] = ""
+
+ def close(self) -> None:
+ """Flush pending output and close the command envelope."""
+ with self.lock:
+ if not self.enabled:
+ return
+ self.flush_stream("stdout")
+ self.flush_stream("stderr")
+ elapsed_ms = int((time.monotonic() - self.started_clock) * 1000)
+ self._write(
+ f"=== {_utc_timestamp()} END run={self.run_id} "
+ f"elapsed_ms={elapsed_ms} ===\n"
+ )
+ self.enabled = False
+ try:
+ self.handle.close()
+ except (OSError, ValueError) as exc:
+ self._disable(exc)
+
+
+class _TeeTextIO:
+ """Mirror text writes while preserving the original stream interface."""
+
+ def __init__(
+ self,
+ primary: TextIO,
+ transcript: _AutomaticTranscript,
+ stream_name: str,
+ ) -> None:
+ self.primary = primary
+ self.transcript = transcript
+ self.stream_name = stream_name
+ self.lock = threading.RLock()
+
+ def write(self, text: str) -> int:
+ """Write to the original stream, then mirror the same text."""
+ with self.lock:
+ written = self.primary.write(text)
+ self.transcript.write_stream(self.stream_name, text)
+ return written
+
+ def writelines(self, lines: Iterable[str]) -> None:
+ """Mirror a sequence through the ordinary write path."""
+ for line in lines:
+ self.write(line)
+
+ def flush(self) -> None:
+ """Flush the original stream without splitting a logical log line."""
+ with self.lock:
+ self.primary.flush()
+
+ def __getattr__(self, name: str) -> object:
+ """Delegate the remaining text-stream interface."""
+ return getattr(self.primary, name)
+
+
+def install_auto_transcript(argv: list[str] | None = None) -> Path | None:
+ """Mirror a project-scoped Python command when its project log exists."""
+ global _ACTIVE_TRANSCRIPT
+
+ effective_argv = list(sys.argv if argv is None else argv)
+ if _ACTIVE_TRANSCRIPT is not None:
+ return None
+ if os.environ.get(DISABLE_TRANSCRIPT_ENV):
+ return None
+ if Path(effective_argv[0]).name in _EXCLUDED_ENTRYPOINTS:
+ return None
+
+ project_root = _find_project_root(effective_argv)
+ if project_root is None:
+ return None
+ log_path = project_root / WORKFLOW_LOG_RELATIVE_PATH
+ original_stdout = sys.stdout
+ original_stderr = sys.stderr
+ try:
+ handle = log_path.open(
+ "a",
+ encoding="utf-8",
+ errors="replace",
+ newline="",
+ )
+ except OSError as exc:
+ try:
+ original_stderr.write(
+ f"[WARN] Workflow transcript unavailable ({log_path}): {exc}\n"
+ )
+ original_stderr.flush()
+ except (OSError, ValueError):
+ pass
+ return None
+
+ transcript = _AutomaticTranscript(
+ handle,
+ original_stderr,
+ [sys.executable, *effective_argv],
+ )
+ transcript.start()
+ _ACTIVE_TRANSCRIPT = transcript
+ sys.stdout = _TeeTextIO(original_stdout, transcript, "stdout")
+ sys.stderr = _TeeTextIO(original_stderr, transcript, "stderr")
+ atexit.register(transcript.close)
+ return log_path
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index d281aa3e..a4de1cf9 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -126,6 +126,35 @@ After reading direct and converted content, assess factual sufficiency:
python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>
```
+Project initialization creates `<project_path>/validation/workflow.log` and
+records the initialization milestone. After the project exists, run each
+project-scoped Python tool normally. The shared CLI bootstrap automatically
+mirrors its text stdout/stderr into that log; no wrapper command is required.
+Detached Confirm UI and live-preview processes retain their detailed output in
+their existing component logs.
+
+When a Python helper serves the active deck but neither its arguments nor its
+working directory identifies the project, provide the routing signal on that
+same command — still one Python process:
+
+```bash
+PPT_MASTER_PROJECT_PATH="<project_path>" python3 ${SKILL_DIR}/scripts/<helper>.py <args...>
+```
+
+When an important audit detail has no owning command output — for example a
+material stage handoff or rework reason, a user-approved exception, or a manual
+recovery choice — the active role may append one concise note:
+
+```bash
+python3 ${SKILL_DIR}/scripts/workflow_log.py <project_path> "<material audit detail>"
+```
+
+Notes are selective and non-authoritative. Do not duplicate artifact contents,
+routine page progress, or chain-of-thought; current artifacts and gate results
+still determine stage and readiness. The transcript is cold audit evidence:
+never read it during normal generation; open it only when the user explicitly
+asks to review the run.
+
Format options must be named with concrete dimensions. Default: `ppt169` = `1280x720`, `viewBox="0 0 1280 720"`. Other examples: `ppt43` = `1024x768`, `story` = `1080x1920`, `banner` = `1920x1080`. For the full format list, see `references/canvas-formats.md`.
Import source content (choose based on the situation):
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index a69a5318..43957963 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -91,8 +91,14 @@ python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> \
--format <format> --quick-generate
```
-It creates only `svg_output/` and no root README. Add capability inputs only
-when triggered; checker/exporter create `validation/`, `exports/`, and the
+It creates `svg_output/` plus the cold
+`validation/workflow.log` Python-output transcript, and no root README. After
+this command, run project-scoped Python tools directly; their shared CLI
+bootstrap automatically mirrors stdout/stderr into the existing log. A concise
+manual entry is allowed only for a material non-Python audit detail under
+Generate Step 2's selective policy. Never read the transcript during ordinary
+Quick execution; open it only for an explicit user-requested run review. Add
+capability inputs only when triggered; later tools create `exports/` and the
default-path `backup/`. With source files, continue with Step 2
`import-sources`; it creates the triggered input directories. Never scaffold a
Design Spec or lock. Use a new path, or verify that an existing path's
diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.md
index 4263e670..a2188cac 100644
--- a/skills/ppt-master/workflows/stages/resume-execute.md
+++ b/skills/ppt-master/workflows/stages/resume-execute.md
@@ -8,6 +8,13 @@ description: Main-pipeline control stage for resuming execution in a fresh chat
This stage is **context-independent**: it owns the execution session starting from a fresh chat — no upstream conversation context required. Persisted project artifacts replace the planning session's confirmation dialogue and image-acquisition history.
+`validation/workflow.log` is a cold Python-output transcript with optional
+important manual entries, not persisted planning state. Do not open or replay
+it while resuming. Use the real artifacts in Step 1 to establish current state;
+inspect the transcript only when the user explicitly asks to review the prior
+run. Run inherited Python commands normally; their shared CLI bootstrap records
+stdout/stderr automatically.
+
## When to Run
The user opens a new chat and gives a phrase that names a project path and signals continuation. Recognize any of: