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(refine-spec): review surface follows the confirmation surface
hugohe3866efd844d94
diff --git a/docs/rules/rule-owners.md b/docs/rules/rule-owners.mdindex e53d04bc..b6a799e7 100644--- a/docs/rules/rule-owners.md+++ b/docs/rules/rule-owners.md@@ -30,6 +30,7 @@| R22 | Template discovery reads only the four `*_index.json` files; never scan kind directories; a bare name never resolves to a path; one root per kind, Layout precedes Deck | `workflows/routing.md` §7 | `workflows/generate-pptx.md` Step 3, `workflows/stages/apply-template-workspace.md` §1, `templates/README.md`, the four kind READMEs, `references/artifact-ownership.md`, `references/strategist-template.md` || R23 | Resource need is decided while composing the roster: which pages need a prepared image, lettering, or illustrated-icon file; the carrier mix itself is never planned | `references/plan-core.md` §5 | `references/strategist.md` Resource Need and Reference Planning (Design Spec handoff only), `workflows/profiles/quick-generate.md` §2, `references/strategist-image.md` §1 || R24 | Whole-roster rhythm check: neighbors and section arcs compared, chapter entries reset, same-density runs intentional, motif carries a continuity job | `references/plan-core.md` §4 | `references/strategist.md` §6.2, `workflows/profiles/quick-generate.md` §2 |+| R25 | Refine Spec reviews the one Design Spec on the surface the run confirmed on (review page on the page branch, otherwise chat); direct edits and comments revise that same file, and approval is given only in chat | `workflows/stages/refine-spec.md` Step 2 | `workflows/generate-pptx.md` Step 4, `workflows/stages/resume-execute.md` Step 1; `scripts/docs/spec_review.md` documents tool behavior |## 3. Structured-template rulesdiff --git a/skills/ppt-master/scripts/confirm_ui/static/app.js b/skills/ppt-master/scripts/confirm_ui/static/app.jsindex 9a0434f5..0e619229 100644--- a/skills/ppt-master/scripts/confirm_ui/static/app.js+++ b/skills/ppt-master/scripts/confirm_ui/static/app.js@@ -195,7 +195,7 @@mode_continuous_desc: "Generate the whole deck in one pass.",mode_split_desc: "Stop after the spec; resume SVG generation in a fresh window.",refine_off_desc: "Write the Design Spec and execution lock in sequence, then auto-proceed.",- refine_on_desc: "Stop after the Design Spec. Revise any part in chat; approval then creates the execution lock and continues generation.",+ refine_on_desc: "Stop after the Design Spec. A review page opens: edit any page directly or leave comments; approval in chat then creates the execution lock and continues generation.",off_default: "Off",on: "On",option_prefix: "Option",@@ -384,7 +384,7 @@mode_continuous_desc: "デッキ全体を一気に生成します。",mode_split_desc: "設計仕様の作成後に停止し、別ウィンドウでSVG生成を再開します。",refine_off_desc: "設計仕様と実行ロックを順番に作成し、そのまま自動で進みます。",- refine_on_desc: "設計仕様の作成後に停止します。チャットで任意の箇所を修正し、承認後に実行ロックを作成して生成を続けます。",+ refine_on_desc: "設計仕様の作成後に停止します。レビューページが開き、各ページを直接編集するかコメントを残せます。チャットで承認すると実行ロックを作成して生成を続けます。",off_default: "オフ",on: "オン",option_prefix: "案",@@ -573,7 +573,7 @@mode_continuous_desc: "一次性连续生成整份演示文稿。",mode_split_desc: "写完设计规范后停止,另开窗口继续生成页面。",refine_off_desc: "依次生成设计规范和执行锁,然后自动继续。",- refine_on_desc: "生成设计规范后暂停;你可在聊天中修改任何部分,明确确认后再生成执行锁并继续制作。",+ refine_on_desc: "生成设计规范后暂停,并打开评审页面:可逐页直接修改或留下修改意见;在聊天中明确确认后再生成执行锁并继续制作。",off_default: "关",on: "开",option_prefix: "方案",@@ -762,7 +762,7 @@mode_continuous_desc: "一次性連續生成整份簡報。",mode_split_desc: "寫完設計規範後停止,另開視窗繼續生成頁面。",refine_off_desc: "依次生成設計規範和執行鎖,然後自動繼續。",- refine_on_desc: "生成設計規範後暫停;你可在聊天中修改任何部分,明確確認後再生成執行鎖並繼續製作。",+ refine_on_desc: "生成設計規範後暫停,並開啟評審頁面:可逐頁直接修改或留下修改意見;在聊天中明確確認後再生成執行鎖並繼續製作。",off_default: "關",on: "開",option_prefix: "方案",diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex f48fe0ff..01dfed13 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -55,7 +55,7 @@"skills/ppt-master/references/artifact-ownership.md": 4500,"skills/ppt-master/workflows/governance/failure-recovery.md": 2750,"skills/ppt-master/workflows/stages/resume-execute.md": 1750,- "skills/ppt-master/workflows/stages/refine-spec.md": 1000,+ "skills/ppt-master/workflows/stages/refine-spec.md": 1500,"skills/ppt-master/workflows/stages/verify-charts.md": 2500,"skills/ppt-master/workflows/stages/topic-research.md": 2000,"skills/ppt-master/workflows/stages/live-preview.md": 1000,diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex a4e94543..69b93562 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -125,7 +125,7 @@ This is a capability map, not a usage checklist; direction construction follows**User images**: if the user provided images, run `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` before the Design Spec and read `analysis/image_analysis.csv` before §VIII. The CSV is a regenerated view of `images/`: rerun after any change, never treat it as a store. Never bulk-open images: Strategist inspects one specifically ambiguous asset under [`strategist-image.md`](../references/strategist-image.md) and records the result in §VIII; Executor inspects one `Existing` / `Sourced` asset only for crop, focal placement, or text contrast.-⛔ **BLOCKING — two-stage confirmation**: the always-on user gate unless explicitly delegated. Stage 1 confirms the communication contract and exactly one template mode (`free_design` or `templates`, the latter expanding the four registered-kind selectors plus supplied roots and requiring at least one selection). Final Stage 2 confirms the complete deck solution plus production mechanics only after the Stage-1 choice is installed or free design is closed; `refine_spec: true` adds one chat gate after Design Spec Gate 1. Author each stage once; submitted values — including blanks and unusual overrides — are authoritative.+⛔ **BLOCKING — two-stage confirmation**: the always-on user gate unless explicitly delegated. Stage 1 confirms the communication contract and exactly one template mode (`free_design` or `templates`, the latter expanding the four registered-kind selectors plus supplied roots and requiring at least one selection). Final Stage 2 confirms the complete deck solution plus production mechanics only after the Stage-1 choice is installed or free design is closed; `refine_spec: true` adds one approval gate after Design Spec Gate 1. Author each stage once; submitted values — including blanks and unusual overrides — are authoritative.**Only the user confirms**: the agent authors recommendations, operates the server, reads state, and applies a template. It never confirms on the user's behalf, automates submission, synthesizes a payload, or writes user result state; silence confirms nothing. Under explicit delegation the agent makes the Stage-1 decision, installs it, derives Stage 2, and presents one complete summary without fabricating UI receipts.@@ -157,7 +157,7 @@ If the user selects chat after launch, apply `confirm-surface.md`'s in-run switc1. Read `${SKILL_DIR}/templates/design_spec_reference.md`; create the complete I–X `design_spec.md` once at the confirmed `design_spec_depth`, without placeholders or `scaffold-*`.2. Audit it field by field against the retained confirmation — Gate 1.-3. With `refine_spec: true`, run [`refine-spec`](stages/refine-spec.md): review that file in chat, accept arbitrary revisions, touch no lock, stop until explicit approval. Otherwise skip.+3. With `refine_spec: true`, run [`refine-spec`](stages/refine-spec.md): review that file on the surface the run is using (its review page on the page branch, otherwise chat), accept arbitrary revisions, touch no lock, stop until explicit approval in chat. Otherwise skip.4. Read `${SKILL_DIR}/templates/spec_lock_reference.md`; author `spec_lock.md` once from the approved Design Spec and context — identity and refinements, every recurring typography role, routing anchors, each placed image's source/layout suggestion/crop policy; no page-local garnish, no image palette; `strategist-template.md` §3 when active.5. Compare lock anchors to the Design Spec and run `python3 ${SKILL_DIR}/scripts/project_manager.py validate <project_path>`. Schema validity never proves fidelity: a final-state → Design Spec mismatch, an approved Design Spec → lock mismatch, or an unapplied revision blocks. Repair from the retained confirmation (or the approved revision); resume and refine edit existing files, never scaffolds; only fresh recovery may reread persisted final evidence once. Unhonorable requirements follow [`failure-recovery.md`](governance/failure-recovery.md).diff --git a/skills/ppt-master/workflows/stages/refine-spec.md b/skills/ppt-master/workflows/stages/refine-spec.mdindex 4c6395af..abcee7e4 100644--- a/skills/ppt-master/workflows/stages/refine-spec.md+++ b/skills/ppt-master/workflows/stages/refine-spec.md@@ -24,16 +24,31 @@ Run [`generate-pptx`](../generate-pptx.md) Step 4 through the complete `design_s## Step 2: ⛔ HARD STOP — present, discuss, and revise-Present the one project `design_spec.md` in chat and wait for explicit revision or approval — no second draft, parallel summary, fixed-field questionnaire, scores, or field-by-field confirmation. The user may revise any part, any number of rounds; discuss in prose and let the user drive.+Present the one project `design_spec.md` and wait for explicit revision or approval — no second draft, parallel summary, fixed-field questionnaire, scores, or field-by-field confirmation. The user may revise any part, any number of rounds; discuss in prose and let the user drive.++**Review surface follows the confirmation surface** ([`confirm-surface.md`](../../references/confirm-surface.md) §1): on the page branch launch the review page; on the chat or delegated branch, after a switch to chat, or when the launch fails, present the file in chat. The page is a derived view of that one file — one page per `##` section and per §IX slide — never a second draft.++```bash+python3 ${SKILL_DIR}/scripts/spec_review/server.py <project_path> --daemon+```++Report the actual URL from the launch output (remote host: `--no-browser` plus port forwarding, [`spec_review.md`](../../scripts/docs/spec_review.md)) and tell the user in one short message: **Direct edit** rewrites one block of the same file on **Apply changes**; **Annotate** leaves a per-page or global comment for anything needing judgement and for every page added, dropped, or moved; return to chat to have comments applied or to approve. Then stop — never wait on the page; approval is given only in chat.++**Apply a review round** when the user returns from the page:++1. `spec_review/server.py <project_path> --hold on` — the page cannot write while the file is revised. Skip the hold when the page is no longer running (idle timeout, new session): the sidecars still carry the to-do list.+2. `python3 ${SKILL_DIR}/scripts/check_spec_annotations.py <project_path>` — the to-do list: pending comments plus blocks the user edited directly since the last round. Read those blocks from disk; the copy in context is stale.+3. A direct edit is a user revision: keep its wording and reconcile what it supersedes elsewhere. Apply each comment to the file on disk, then clear it with `--applied <id>`; a comment changed since listing stays pending — list again.+4. `check_spec_annotations.py <project_path> --ack-edits`, `--hold off`, then report what changed and what stays open.**Reference — review lenses, not a checklist**: raise these in plain language as directions, never numbers (no HEX, px, ratios, page quotas, or grades): outline — logical build, information density, one idea per page, register matched to the audience, hook and payoff, chapter balance; color — fit to mood and audience, enough hierarchy and contrast; typography — clear contrast or clean concord between title and body, legible size hierarchy, character matched to the visual style; layout — structure following each page's information weight rather than one uniform symmetric grid; icon/image — one consistent icon character, images that serve the content; page rhythm — `anchor` / `dense` / `breathing` tracking the narrative. They overlap what the confirmed `mode`, visual style, and §6.1 already shape; they are discussion angles, not permission to redo a decision without the user's explicit revision.-**Revise one Design Spec only**: apply each round incrementally; affected decisions supersede earlier values while unaffected confirmed decisions and cross-section coherence stay intact. Do not regenerate the document for a local change or touch lock anchors. After a changed reuse/prototype decision, repeat the [`strategist-template.md`](../../references/strategist-template.md) preflight before approval (`style` later locks flat; `mirror` / `layout` require a complete structured contract; Gate 2 derives structure mappings; legacy prototypes stay unselectable). Iterate until explicit approval.+**Revise one Design Spec only**: apply each round incrementally; affected decisions supersede earlier values while unaffected confirmed decisions and cross-section coherence stay intact. Do not regenerate the document for a local change, rewrite it from the copy in context, or touch lock anchors. After a changed reuse/prototype decision, repeat the [`strategist-template.md`](../../references/strategist-template.md) preflight before approval (`style` later locks flat; `mirror` / `layout` require a complete structured contract; Gate 2 derives structure mappings; legacy prototypes stay unselectable). Iterate until explicit approval.---## Step 3: Approve and author the lock-After explicit approval, return to [`generate-pptx`](../generate-pptx.md) Step 4 Gate 2: author or resynchronize `spec_lock.md` once from the approved Design Spec plus current context, validate, then continue to Step 5 or Step 6. Do not reopen `result.json`.+After explicit approval, apply any pending review round and end it with `spec_review/server.py <project_path> --shutdown` instead of `--hold off` — no edit lands between approval and the lock — then return to [`generate-pptx`](../generate-pptx.md) Step 4 Gate 2: author or resynchronize `spec_lock.md` once from the approved Design Spec plus current context, validate, then continue to Step 5 or Step 6. Do not reopen `result.json`.> This stage inserts a review-and-revise checkpoint between Gate 1 and Gate 2; [`strategist.md`](../../references/strategist.md) and [`generate-pptx`](../generate-pptx.md) remain authoritative for content and sequencing.diff --git a/skills/ppt-master/workflows/stages/resume-execute.md b/skills/ppt-master/workflows/stages/resume-execute.mdindex 082b1580..48fe4f69 100644--- a/skills/ppt-master/workflows/stages/resume-execute.md+++ b/skills/ppt-master/workflows/stages/resume-execute.md@@ -16,7 +16,7 @@ The user opens a new chat naming a project path with continuation intent — "## Step 1: Sanity check-`<project_path>/design_spec.md` (approved narrative and §IX outline) and `<project_path>/spec_lock.md` (execution anchors and routing contract) must both exist; their complete reads happen after the Executor role core loads. If either is missing, stop and recover through [`failure-recovery.md`](../governance/failure-recovery.md) §3 — never enter Step 6, treat an orphan lock as authority, or invent a replacement.+`<project_path>/design_spec.md` (approved narrative and §IX outline) and `<project_path>/spec_lock.md` (execution anchors and routing contract) must both exist; their complete reads happen after the Executor role core loads. When `<project_path>/spec_review/` exists, run `python3 ${SKILL_DIR}/scripts/check_spec_annotations.py <project_path>`; a pending comment or an unacknowledged direct edit means the Design Spec moved after the lock was authored — return to [`refine-spec`](refine-spec.md) Step 2 before any execution. If either file is missing, stop and recover through [`failure-recovery.md`](../governance/failure-recovery.md) §3 — never enter Step 6, treat an orphan lock as authority, or invent a replacement.---