hugohe3/ppt-master v4.1.0

on GitHub

First, an apology

The architectural cleanup that shipped with v4.0.0 carried changes it did not need to make, and those changes suffocated the project's creativity. That is on me, and I'm sorry.

It also taught me something I had underweighted: this project is not only its code. The prompts and the orchestration of the workflow matter just as much — arguably more. A quota tightened by one line, a reference demoted to a lock, a permission rewritten as a limit: none of that shows up as a failing test, but it decides whether the AI is allowed to design at all.

In my own testing, the deck aesthetics have recovered a good deal, so I'm publishing this fix right away rather than batching it.

The wider lesson is that a great many details hide inside every small design decision here. Every future change deserves extreme care, and I need to slow the rate of change down.

The v4.0.0 refactor compressed the prompt contract hard. Some of that compression turned permissions into quotas, references into locks, and flexible realization into silent constraint — the AI had less room to design than the system intends. This release restores that range and pins down why each remaining boundary exists, so a future compression pass cannot quietly take it away again.

Creative range restored

• Palette: the 60-30-10 split, the "no more than 4 colors per page" cap, and the industry color table as a default lock are gone. Industry anchors are optional recall; color count and distribution follow encoding, style, and natural asset colors. Body-text contrast ≥ 4.5:1 and confirmed brand/semantic roles still hold.
• Typography: fixed line-height ratios (1.4–1.5× / 1.6–2.0×) are replaced by spacing chosen from typeface, size, density, and reading distance — no fixed ratio overrides legibility or the selected style.
• Page-local expression: page-local tints, gradient stops, shadow/glow paints, transparency composites, one-off illustration tones, and export-safe display families no longer need a lock row. spec_lock.md is an identity anchor set, not an allowlist of every legal value; promote a value only when it recurs.
• Effect capability discovery: Executor now opens with a visible menu of available constructions — alpha/gradient paint, elevation, image integration (scrim, vignette, faux glass, clipping), line and type treatments, constructed styles (hand-drawn, Riso, halftone, isometric, paper cut). It is a reference, not a constraint; svg-effects.md still owns syntax and fallbacks.
• Image composition: the "use image-as-canvas at least once per 4+ image deck" rule becomes an intent audit. Repeated left/right or top/bottom structures are valid when the narrative calls for them, and catalog families and modifiers stay available without a usage quota.
• Quality checker: two taste-encoding warnings (missing_image_as_canvas, layout_pattern_degenerated) are removed. Contextual colors and safe font families are informational anchor comparisons, not drift errors.
• Structured pages: the "3–8 content groups" capacity hint becomes one group per logical content unit.

Decision ownership: Strategist prepares, Executor realizes

• Strategist owns material sufficiency, resource selection, and project-local readiness — image layout pattern and crop policy, chart selection, native-ready choices, icons, and adaptive Layout mappings.
• §VIII gains an explicit Crop Policy column (no-crop protects required pixels; adaptive lets Executor choose complete display or a focal-safe crop) and projects into the lock as <path> | source= | pattern= | crop=.
• §VII gains a Native-ready column: an independent data chart or pure text-grid table is promoted to a native editable object only when the requirement or the deck's afterlife benefits; incidental sparklines and KPI insets stay designed SVG.
• AI and web image acquisition stays after final confirmation and before Executor.
• Executor realizes the confirmed plan: Design Spec §IX is final page-copy authority, source reads are limited to explicit verification, and a prototype or Layout mapping that no longer fits returns to Strategist instead of being silently reselected downstream.

Governance against silent tightening

docs/rules/prompt-style.md gains a Prompt Refactor Review contract: every compression pass must record before → after strength deltas, preserve the compact objective predicate behind each non-self-evident hard rule, and prove that a permission did not become a quota, a reference did not become a lock, and preparation timing did not shift downstream. A shorter prompt that changes decision ownership, constraint strength, preparation timing, or capability discoverability is a semantic regression even when structural and token-budget audits pass.

Planning artifacts

• Whole-document authoring restored: read the Design Spec reference → author the complete design_spec.md once → Gate 1 → read the Spec Lock reference → author the complete spec_lock.md once. No placeholder scaffold is materialized and filled piecemeal; scaffold-spec / scaffold-lock are optional manual helpers.
• project_manager.py validate no longer reopens confirm_ui/result.json — it validates the planning artifacts against their schemas.
• Orphan locks are rebuilt from recovered Design Specs, with recovery guidance aligned.

Typography roles

Confirm UI's heading/body choice remains the base, and Strategist may add recurring content-driven roles (project title, body, support-role stacks) that carry from Design Spec into spec_lock intact. Executor resolves fonts by exact role with a legacy font_family fallback, so existing locks keep working.

Chart recall

Lexical recall stays bounded, but low or absent lexical confidence now returns the full live registry under semantic_fallback, and --semantic-fallback forces that review when every lexical candidate conflicts. Candidates are compared semantically; the catalog is never opened separately or mirrored into a second index.

Custom creative directions

• spec_lock.md accepts optional catalog reference lists (mode, visual style, image rendering) for custom directions, with unique ids that must resolve to their catalog files. Genuinely novel directions stay behavior-only.
• A catalog-backed custom direction now reads every source it combines, and those optional references persist and reload across planning, execution, image generation, and resume.

Topic research

Research is gap-driven: it triggers on outcome-critical factual gaps found after reading the available sources, stays fact-only, writes non-colliding supplements, and defers all image acquisition until after final confirmation.

Docs

• Roadmap restructured around the positioning axis and signal-driven directions; month-by-month history compacted into a milestones table pointing at release notes and the commit log.
• Model recommendation in both READMEs: Kimi K3 (sponsor) as default with Claude as an alternative, paired with gpt-image-2 (OpenAI) or gemini-3.1-flash-image (Google) for images.
• Confirmation channel wording is now channel-neutral: a decision is honored from whichever channel it actually happened in — result.json when the Confirm UI was used, the conversation otherwise.