Require buildable projects, mockup fidelity and page hierarchy (0.9.3)

references/execution-and-review.md

@@ -25,6 +25,8 @@ A user's later change affects the stated scope; revise the same arrangement and
 
 ## Review after revision
 
+The mandatory project build, approved-sample fidelity and full-page hierarchy checks apply regardless of whether specialist review is selected. Every page must be retained in its buildable project, reconstructed without unauthorized element loss and checked as a whole for sizes, families, weights, spacing and visual grouping. These are production requirements, not an additional review assignment or approval round; follow [mockup fidelity and page checks](visual-design.md#approved-mockup-fidelity).
+
 By default, the agreed post-revision review uses a fresh-context Agent who did not participate in editing that portion. Reuse the once-confirmed assignment and budget. If the user explicitly selected main-Agent checking or skipped this review, follow and label that choice; do not describe it as independent review.
 
 Provide current deliverable source and preview as relevant, confirmed report/section/page goals, audience knowledge, criteria, original evidence and sufficient prior content to verify dependencies. Include precise premises, symbol meanings, conditions and source locations needed for the current use. Do not make the reviewer assume a preceding block has already explained them. A missing item in the review input is not proof that the whole report lacks it; allow source lookup, and distinguish missing evidence from an input gap.

references/native-authoring.md

@@ -2,9 +2,11 @@
 
 Read the selected external template's specification, style, theme and relevant layout first. The bundled compiler accepts the native SVG workspace convention: `templates/roster.json` maps every manifest layout ID to one SVG; each source SVG declares `data-pptx-master`, `data-pptx-layout` and friendly names. Layout and master objects use their declared `data-pptx-layer`. Placeholder groups carry `data-pptx-placeholder`, a stable `data-pptx-idx`, and `data-pptx-bounds`.
 
+Create or continue the [mandatory buildable Skill project](project-workspace.md) before producing the page. Keep its selected template, page SVGs, notes, assets and real builder together; even a one-slide request must produce the PPTX through that project's build entrypoint, not a hand-assembled file or standalone export with no retained project.
+
 Start the current page from its selected layout source. Retain inheritance metadata, inherited objects and placeholder indices. Fill the declared placeholder carrier; put independent content objects in the intended slide layer. Do not paint opaque slide-local copies over the master logo or layout watermarks. When a template supplies a custom composition generator, inspect it and use its declared content interface rather than approximating its source geometry.
 
-Use the template's discrete typography, grid, fixed content region and spacing. Resolve overflow by choosing a suitable layout, shortening content or dividing the page according to the user's workflow. Do not infer ad hoc font sizes and alignment guides from mockup pixels. Keep text as text, simple panels and connectors as geometry, and exact image exceptions as independent assets. Tables, charts and formulas must retain their required native object type; a collection of lines/text or a formula picture does not automatically qualify.
+Use the template's discrete typography, grid, fixed content region and spacing. Resolve overflow by choosing a suitable layout, or by shortening content/dividing the page within the user's authorized content scope. For an approved mockup, preserve its content, graphics and relationship-bearing shapes under [mockup fidelity](visual-design.md#approved-mockup-fidelity); necessary quality repair does not permit silently dropping elements. Do not infer ad hoc font sizes and alignment guides from mockup pixels. Keep text as text, simple panels and connectors as geometry, and exact image exceptions as independent assets. Tables, charts and formulas must retain their required native object type; a collection of lines/text or a formula picture does not automatically qualify.
 
 Apply [text and container rules](text-and-containers.md) before authoring: prefer one native frame per paragraph, use a unified logical block for any necessary fragments, distinguish text functions by size/weight/color and instantiate repeated containers through a shared renderer. Inspect actual native paragraph structure after export; positional SVG spans can otherwise be split by the compiler.
 
@@ -12,20 +14,19 @@ Before emitting paragraph rows, check punctuation at both line edges and prohibi
 
 Keep separate paragraphs separated by the template's fixed paragraph gap, retaining their normal internal line height. Spacing values and applicable relationships belong to the shared recipe; content callers cannot adjust them. Check exact fixed padding/gaps and actual glyph/edge clearance at normal scale. Use [text-block/spacing helpers](text-and-containers.md#spacing-and-paragraph-separation) for supported content. Explicit math markers use the [Office Math wrapper](mathematics.md), not the upstream table/chart marker kinds.
 
-## Current-page export
+## Current-page project build
 
 The installer provides Python 3.12+ and [runtime requirements](../runtime/requirements.txt). Metadata-only selection and project commands use Python 3.10+ without third-party packages.
 
+Follow [project initialization and builder preparation](project-workspace.md#初始化与作者工作流), add the current authorized pages and their inputs, then build through the project. Source edits and quality repairs must be included in the locks before the next build:
+
 ```sh
-python3 /path/to/skill/scripts/native_export.py \
-  --manifest /path/to/separate-template/manifest.json \
-  --theme chosen-theme \
-  --source /path/to/current-page.svg \
-  --output /path/to/new-review.pptx \
-  --notes /path/to/notes.json
+python3 /path/to/report/tools/ppt_project.py lock --project /path/to/report
+python3 /path/to/report/tools/ppt_project.py check --project /path/to/report
+python3 /path/to/report/tools/ppt_project.py build --project /path/to/report
 ```
 
-`--source` may repeat to assemble explicitly authorized, already authored pages in order. It does not create or design additional pages. Source filename stems must be unique. `--notes` is optional JSON mapping source stems to complete speaker-notes strings; unknown stems are rejected.
+The project builder calls `native_export.py` as its low-level compiler, or imports its `export` function. That interface retains `--manifest`, `--theme`, repeatable `--source`, `--output` and optional `--notes`; it is not a projectless production shortcut. It may assemble only explicitly authorized, already authored pages in order. Source filename stems must be unique. `--notes` maps source stems to complete speaker-notes strings; unknown stems are rejected.
 
 The exporter consumes released v2 manifests and retains all native layout definitions, even for a single visible page. It requires a complete layout roster, unique layout names, declared `page_title`/`body` family roles and sizes, and the twelve PowerPoint theme color indices. Optional `style.language` supplies the presentation's BCP-47 language tag. Without it, the exporter preserves the compiler's legacy language metadata behavior; record the deck language in the project when it matters.
 
@@ -33,6 +34,8 @@ Page SVG viewBox and layout ID must match the selected template. Source assets a
 
 The exporter embeds images in temporary source copies, preserving canonical source bytes. It runs the bundled attribution guard, serial compiler and declared-font preservation context, then applies the external palette/theme fonts without overwriting resolved run weights, and verifies slide/Layout/Master links, placeholders and supplied notes. Authors/renderers must apply their selected role's actual size, weight and color to the source; family identity alone does not select a text function. Existing output is protected, including a concurrent writer appearing during compilation. A failed build does not replace old output.
 
+Before marking each page complete, perform the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check) on its current render, covering font sizes/families/weights, spacing and visual content groups across the entire page. Compare with any approved sample, repair the source and rebuild/reinspect as needed; a successful compile is not this visual check.
+
 ## Template authors and review prototypes
 
 Keep proposed styles and mockups outside the final template workspace until the user's design review allows formal construction. A proposal manifest cannot be consumed as a released production template. After approval, author the common style, independent themes, roster and native SVG layout definitions together; compare each theme against the same geometry and slot contract.

references/object-reconstruction.md

@@ -2,6 +2,8 @@
 
 Treat the current visual page as a design reference with explicit source fidelity requirements. Determine the background and asset boundaries before writing native text over it; otherwise old text and newly editable text can coexist invisibly in a background picture.
 
+Work inside the mandatory [buildable Skill project](project-workspace.md), including for one page. After the user confirms a sample, apply [approved-mockup fidelity](visual-design.md#approved-mockup-fidelity): retain its content, graphics and relationship-bearing shapes. Necessary quality repairs do not authorize omitting text, figures, diagram nodes, connectors or grouping boundaries.
+
 Inventory the page: canvas, fixed UI, text levels, content groups, foreground images/icons, simple geometry/connectors, tables/charts, formulas, decorative patterns and intended layout slots. Keep every text value, evidence value and source asset tied to the user-provided content. Record each object's target type and source.
 
 ## Background and materials
@@ -20,4 +22,4 @@ Use actual data for native charts; if source values are unavailable, preserve th
 
 Preserve crop, aspect ratio and source meaning for image objects. Independently editable text over an unchanged full-page screenshot is not a reconstructed page. Keep repeated UI in inherited layers, rather than covering it with copied slide objects.
 
-Compile the current SVG through [native export](native-authoring.md), then compare the actual rendered page with the accepted design at full size and a normal presentation view. Check hierarchy, density, line breaks, safe margins, alignment, clipping, asset identity and reading order. Native object checks establish object type and inheritance; they do not prove appearance. Complete the requested application checks before claiming editability acceptance.
+Build the current SVG through the project's declared builder using [native export](native-authoring.md), then compare the actual rendered page with the accepted design and element inventory at full size and a normal presentation view. Complete the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check), including all font sizes, families, weights, spacing and content groups. Check density, line breaks, safe margins, alignment, clipping, asset identity and reading order. Native object checks establish object type and inheritance; they do not prove appearance. Complete the requested application checks before claiming editability acceptance.

references/powerpoint-checks.md

@@ -4,12 +4,16 @@ Use the host's supported application UI tool, such as CUA, for PowerPoint operat
 
 Open the current generated file, verify the visible filename and page thumbnails, and inspect whether PowerPoint shows a repair/recovery warning. Work on task-owned copies and preserve the user's unrelated open presentations. Do not dismiss a repair prompt as successful opening; retain the diagnostic and repair the authored source.
 
+Use the current output of the mandatory [project build](project-workspace.md). Production corrections must be represented in project sources and rebuilt; edits made only in an application test copy do not become the deliverable. When the page follows an approved sample, compare it with that reference and its element inventory, preserving the accepted content and relationship-bearing shapes during repairs.
+
 For rendered evidence, export this file to PDF through PowerPoint's own export dialog using the intended quality setting and a task-owned destination. Check the export exists and belongs to the current file, render its pages and inspect the images. Compare page geometry, text wrapping, typography, images, transparent edges, alignment and separators. Confirm actual PDF font identities when font rendering is disputed; a declared PowerPoint face alone does not prove which font the application rendered.
 
 Use the [text/container review](text-and-containers.md#review-before-delivery): paragraph frame or justified logical-block fallback, no substantive statements in small muted notes, visible size/weight/color hierarchy within containers, one shared internal layout implementation per type/variant, compliant punctuation/singleton handling on every paragraph line, exact template-owned spacing and visible fixed paragraph gaps. Reject caller spacing overrides. Check actual glyphs/edges and visual rows, not only boxes, authored breaks or XML paragraphs. Review content/source and native objects as well as the render. A screenshot cannot prove a shared renderer or unified text source; grouping cannot prove native paragraph flow. Test fragment reflow in the application only when that editing behavior is part of the requested evidence.
 
 For equations, inspect `mc:Choice/a14:m` and OMML structures separately from compatibility fallback text. Verify the declared math family on runs and operator/control properties, missing glyphs, fraction/radical/script/limit placement and clearance from adjacent prose. Actual equation editing requires selecting and changing the equation in a disposable copy; XML or a correctly shaped picture cannot establish that evidence. See [math checks](mathematics.md#verification).
 
+Every completed page also requires the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check): sizes, families, weights, spacing and visual grouping across the whole rendered page. Component checks, a successful export or absence of overlap do not replace it. Repair issues and inspect the updated render; report application/projection evidence at its actual level.
+
 Opening and exporting are distinct from actual editing. When editing evidence is requested, use a disposable task-owned copy: select a representative text/shape/placeholder, change it through the UI, save or export, and verify the resulting independent object/content change. Check an appropriate inherited object separately if template behavior is in scope. Do not alter the authoritative source project or a user's finished original merely to demonstrate editing.
 
 Report the evidence actually obtained: source/reference validation, native structure and object types, current-page rendering, PowerPoint opening, actual object editing, or projection readability. A successful export cannot establish every later level. If the host application or UI capability is unavailable, deliver the validated source and PPTX with that specific unresolved application check.

references/production-rules.md

@@ -1,6 +1,6 @@
 # Production rules
 
-These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims, rebuildable inputs and the explicit text/container constraints below. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate. C16–C23 are requirements, including where C04–C06 offer broader design recommendations.
+These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims, rebuildable inputs and the explicit text/container constraints below. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate. C16–C26 are requirements, including where C04–C06 offer broader design recommendations.
 
 ## Understand and compose
 
@@ -41,3 +41,9 @@ These rules apply across templates and authoring routes. **Required** rules prot
 - **C23 · Required:** mathematical content uses an explicitly declared mathematical font and preserves symbols, operators, scripts, fractions and grouping. Keep ordinary prose in its own text role. Use native Office Math when native equations are required; ordinary Unicode text, linear compatibility text and formula images are different object types. Verify the declared math font and the actual equation structure/rendering; do not silently substitute the prose font or claim equation editability from its appearance. See [mathematics](mathematics.md).
 
 Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not infer paragraph identity, explanation importance or semantic text roles, and do not automatically enforce every text/container rule across arbitrary source files. The paragraph helper checks the lines supplied to it and reflows supported plain text; it does not intercept arbitrary SVG or PowerPoint reflow. Inspect source and current native/rendered output; export success alone is insufficient.
+
+## Buildable project, approved mockups and full-page hierarchy
+
+- **C24 · Required:** when the user requests this Skill, create a buildable project with its project tools, or continue a valid existing Skill project. This includes one-slide requests and revisions, regardless of whether Git collaboration or relocation is requested. Retain the real builder, selected template/compiler, sources, content, data, assets, notes and environment; generate the delivered PPTX through the declared project build. Do not bypass the Skill with a one-off PPTX packager, manually stitch XML/ZIP or assemble the final deck by hand and backfill a nominal project. An empty skeleton, cached export or metadata-only check is insufficient: the current authorized page set must build successfully from its inputs. See [project workspace](project-workspace.md).
+- **C25 · Required:** after the user confirms a mockup, reconstruct it as faithfully as possible, including its content, figures, graphics, grouping and relationship-bearing shapes. Preserve nodes, connectors, arrows, braces, enclosures, labels and other accepted elements; do not silently omit or simplify them because they are difficult to rebuild or seem expendable. Make necessary quality repairs to typography, wrapping, spacing, alignment, contrast, clipping and collisions while retaining the accepted content, composition and relationship semantics. A removal or substantive change needs the user's instruction; do not treat general quality repair as permission to reduce the sample. See [approved-mockup fidelity](visual-design.md#approved-mockup-fidelity).
+- **C26 · Required:** after every page is completed, inspect the entire current rendered page for hierarchy from font size, font family, font weight, spacing and visual content grouping. Cover all text roles and the relationships across containers, not just isolated boxes. Confirm that the main message, sections, body and supporting detail are distinguishable and groups reflect the intended meaning. Repair failures and re-render before reporting the page complete. No clipping/overlap, a successful compile or a few differently styled objects alone does not establish hierarchy. See [full-page hierarchy check](visual-design.md#full-page-hierarchy-check).

references/project-workspace.md

@@ -4,6 +4,8 @@
 
 工程把正文、页面源、数据、素材、模板源、必要工具和依赖说明放在同一目录。Git 可追踪这些输入；设备相关绝对路径、缓存和导出物在运行时重建。一次工程固定一个 template 版本和一个 theme，页面顺序由 `pages` 数组表达，重排页面无需更换页面 ID。
 
+用户要求使用本Skill时，必须使用本工程工具创建可构建项目，或继续使用已有的有效工程；单页、小样重建和修改任务也适用，不以需要Git协作或跨设备迁移为前提。选定template／theme后先初始化工程，再在其中维护页面源和真实builder。禁止绕过Skill编译器手拼PPT、临时拼接PPTX／XML／ZIP，或给已手拼的成品补一个空工程。交付PPTX必须由声明的工程入口从当前输入成功构建，并保留对应工程。
+
 ## 初始化与作者工作流
 
 解析和工程管理要求 Python 3.10+，只用标准库；实际 builder 的依赖由工程自行声明。消费方明确逐页制作时，保留 `interactive-page`，不要因建立工程而自动批量创作。
@@ -26,6 +28,8 @@ python3 /path/to/skill/scripts/ppt_project.py init \
 
 该通用 builder 读取各页已完成的 SVG 和 Markdown 讲稿；`content.json`／`data` 仍是锁定作者输入，不会自动绑定到 SVG。需要数据驱动生成的消费方应提供自己的明确绑定或预处理步骤。
 
+自定义预处理／builder仍须通过本Skill的相应编译路线生成最终PPTX，并声明真实输入，不能成为手拼成品的旁路。空骨架、`build_ready: false`、仅通过`check`或已有导出物都不算完成可构建项目；必须对当前获准页面实际执行`build`成功。若所选路线或环境暂时无法构建，完成可独立进行的源工作并说明具体缺口，不用手拼结果冒充工程交付。生产修复回写源后重建，PowerPoint内的临时编辑测试在独立副本中进行。
+
 ```sh
 python3 tools/ppt_project.py lock --project .
 python3 tools/ppt_project.py check --project .

references/visual-design.md

@@ -14,6 +14,16 @@ Record confirmed feedback in existing project/page notes or review material: the
 
 The template/shared recipe owns final geometry, typography, fixed spacing and UI. Rough positions in the draft cannot override those contracts. Rebuild the actual page with supported native objects and check its reading order, capacity and visual evidence associations. Draft feedback does not establish final native rendering, editing or projection acceptance. Follow [review after revision](execution-and-review.md#review-after-revision) for the agreed independent check of substantive changes.
 
+## Approved-mockup fidelity
+
+An approved current-page mockup becomes the reconstruction reference. Rebuild it as faithfully as possible: preserve the accepted content, figure/image identities, graphics, relative arrangement, proportions, grouping, emphasis and relationships within the selected template's contracts. The draft's roughness permits necessary quality repair; it does not make its accepted elements optional.
+
+Before reconstruction, inventory the accepted text and visual elements in existing page source/notes, including diagram nodes, links, arrows, braces, enclosures, legend items and labels. A shape that conveys grouping, containment, comparison, direction or a dependency is content. Do not drop it, replace it with an unrelated symbol or call it disposable decoration because native reconstruction is inconvenient. Preserve other accepted graphics too; an allowed picture exception must retain the element and disclose its object type.
+
+Repair typography defects, verified-text spelling, wrapping, contrast, alignment, spacing, clipping and collisions as needed. Keep substantive text, values, groups and relationship meanings intact; do not solve a quality problem by removing an accepted paragraph, figure, graph element or connection. Use the declared template fonts, discrete sizes and shared geometry rather than tracing raster artifacts. If preserving the accepted content would require a substantive redesign or omission, present that specific change for the user's decision; ordinary quality repairs need no repeated approval.
+
+Compare the new full-page render with the approved sample and its inventory. Check for missing elements, changed endpoints, lost group boundaries and altered emphasis as well as appearance. Keep the accepted reference and relevant repairs in the project; do not replace the baseline with a later simplified draft without user instruction. Follow the agreed review assignment without creating a new review pipeline.
+
 ## Page composition and HTML boundary
 
 Every title, text, formula, label, visualization and meaningful decorative group must serve the page task and, through it, the section and report goals. Choose their arrangement from the current information relationship. Pure text can serve a short question, quotation or conclusion; a picture or icon needs a useful role. Do not mechanically reuse website hero sections, selling cards or dashboards as report layouts. The page's main meaning must be readable without scrolling, hovering or clicking.
@@ -39,6 +49,22 @@ Use generated text only as visual guidance. Native source text comes from verifi
 
 Native paragraph lines must satisfy [punctuation and singleton rules](text-and-containers.md#paragraph-line-breaking-rules). Do not preserve a mockup's forbidden line-head/tail punctuation or a row containing only one character with optional punctuation; reflow the complete paragraph within the declared layout.
 
+## Full-page hierarchy check
+
+After completing each page, inspect its actual current render as a whole at a fitted full-page view and normal presentation scale. This check is required even for a single page or an authorized batch, and for both original authoring and mockup reconstruction. Inspect all visible text roles, including labels, chart text, captions, navigation and mathematical text, and the relationships between content containers.
+
+| Dimension | Check across the whole page |
+|---|---|
+| Font size | Main title/message, section headings, body and supporting details are distinguishable and readable; no essential explanation is demoted to tiny text. Use the declared role sizes. |
+| Font family | Each role uses its declared family, including math/monospace where relevant; substitutions and inconsistent families do not disrupt the hierarchy. |
+| Font weight | Declared title/heading/body weights are realized correctly; emphasis helps the reader distinguish roles without inventing undeclared bold styles. |
+| Spacing | Line spacing, paragraph gaps, internal padding and distances between groups follow the shared recipe and visibly separate their intended levels. Check actual glyph/edge clearance. |
+| Visual content groups | Proximity, alignment, containers, headings and meaningful connectors group related material and separate different groups, including across columns and boxes. The groups match the accepted content relationships. |
+
+Judge their combined effect: can the reader identify the main message, then the sections, explanations and supporting details in the intended order? Merely assigning several font sizes, passing a bounding-box check or avoiding overlap is not a pass. Uniform styling or equal gaps can flatten the page even when every object is individually legible.
+
+Repair the source and shared recipes as needed, preserve the approved elements, rebuild and inspect the new render before calling the page complete. Recheck affected pages when a shared recipe changes. Record meaningful findings/repairs briefly in existing page notes or review material; no new scoring schema or specialist review is required. Application editing and projection evidence remain separate under [PowerPoint checks](powerpoint-checks.md).
+
 ## Material generation and transparent assets
 
 For new bitmap illustrations, photos, textures or image edits, use the selected host image-generation capability. Request a transparent background when the final asset needs transparency. Preserve transparency on edits unless the user asks to change it. Use reference-image paths when all targets have paths, otherwise the smallest supported recent-image set that includes every target; do not silently omit a required target.