# Quality Gates This file is the universal QA authority for the workflow. A channel profile or preset may add requirements, but may not weaken these gates. ## Preflight Gate - Intake values required by `../SKILL.md` are resolved before production. - `run-state.json` records the resolved intake/mode for a production project. - A batch records resolved shared intake/mode in `queue.json` and links each item to its own `run-state.json`. - The selected mode and only the relevant references are identified. - No production path loads `references/legacy/`. - All active runtime skill files read as valid UTF-8 without mojibake. - On Windows/PowerShell production runs that write Vietnamese or other non-ASCII public text through inline scripts, pipes or shell-generated files, UTF-8 mode is required before writing: set the console/output encoding to UTF-8 and set `PYTHONIOENCODING=utf-8` for Python helpers. After writing, re-read at least one public text artifact (`SCRIPT.md`, `voiceover.txt` or `index.html`) as UTF-8 and verify Vietnamese diacritics are intact before generating voice or rendering. - `../templates/assets/required-assets.json` exists and every file it declares exists before selecting, building, saving or approving any template. - The shared TikTok profile card, `ainew247na.jpg`, `cursor-hand.png`, follow-click SFX and default `.mp3`/`.mp4`/`.gif` placeholders are available as common assets for all existing and future template sets. ## Content Gate - Title, post caption, hashtags, narration and CTA match the chosen language and profile. - Tool, repository, product and workflow videos include a clear audience/use-case beat explaining who should use the subject, why they need it and one concrete practical workflow. - `PUBLISH.md` contains a post-ready title and exactly 5 focused relevant hashtags; hashtags must not introduce unverified claims, unrelated trends or a supplementary publisher that is not itself the video topic. - Primary subject facts have an identified original/official source. - Repository videos include a repo evidence digest with README title/hero, description, license, stars/forks, relevant badges, feature headings and useful adoption/history signals when available. - Repository videos with homepage/docs/blog/changelog/release/demo links use Crawl4AI for those non-GitHub web pages when available, save Markdown under `capture/crawl4ai/`, and merge only digest-worthy facts into the repo evidence digest. Missing Crawl4AI is a recorded fallback, not silent behavior. - Crawl4AI dependency readiness is a preflight requirement for every user-supplied URL, including social/share URLs: if import/setup is missing, install `crawl4ai`, run setup/browser preparation, and record the result before crawling or falling back. - Every user-supplied URL has either useful Markdown saved under `capture/crawl4ai/` or an explicit recorded Crawl4AI attempt/fallback in the source record and `run-state.json` before scripting starts. - Social/share URL output that is only a login wall, metadata, redirect shell or partial snippet is `supplementary_hook_only`; it may shape the hook but cannot be used as `SOURCE PROOF`. - Repo/site/document and related links supplied by the user are source intake, not publishing metadata. They are read for hook/ideation, but supplementary publishers are not named, shown or cited in public output unless the user explicitly asks for coverage of that source itself. - Third-party social links used only for transcript extraction or remake guidance must not appear in public narration, captions, source labels, on-screen copy, publish captions or hashtags. This includes negative provenance phrases such as "khong dung frame Facebook", "no Facebook frames", "third-party" or "reference video". The public video should simply remake or explain from the official/source asset. - A hook or benefit angle extracted from supplementary material is followed by an original/official-source explanation that verifies, qualifies or corrects it; it is not presented as an unqualified conclusion. - Conflicts are resolved in favor of original/official material. - A risky or unverified claim blocks publishable output until resolved. - A quality-changing fallback is disclosed and approved before it is used. - The state file contains the approval event when a blocked fallback is used. ## Composition Gate - Visual output is authored as a HyperFrames composition. `index.html` is a HyperFrames project entry, and preview/inspection/render QA uses the HyperFrames CLI; non-HyperFrames runtimes cannot satisfy this gate. - Timing follows measured narration duration, not an estimate. - A completed public single-video output runs within `55-180` seconds unless the user explicitly approved a named duration exception; shorter template preview renders do not satisfy this public-output gate. - Evidence and important UI/text remain readable in a 9:16 frame. - Captions stay concise and MUST render in exactly 1 line (bắt buộc 1 hàng) inside the reserved mobile-safe caption zone; use a deterministic 1-line clamp, shorten or break up text sentences to fit in 1 line, and ensure sufficient bottom clearance. - Captions/subtitles must read as subtitles, not primary buttons: avoid plain white button-like bars for routine subtitles; place them high enough above TikTok/profile/outro UI and verify they do not collide with source labels, CTA buttons or profile-card elements in a 9:16 frame. - Evidence-led work loads `editorial-media.md`; official material is labelled `SOURCE PROOF`, rebuilt clarification is labelled `EXPLAINER`, and illustration is not passed off as proof. - Use focused, readable, and tightly cropped images/screenshots of only the key relevant areas (e.g. key code blocks, main files, or repo metrics) rather than uncropped full-screen or full-desktop screenshots, which are illegible and too small in a 9:16 layout. - Evidence screenshots that appear too small must be reviewed through a phone-like 9:16 composition frame or targeted proof frame, then replaced with a focused crop or redesigned callout before render handoff. - Embedded source video that is the primary proof must be visibly dominant: default to at least 78% of usable content width or 58% of the proof-panel height, preserve at least 36px padding from panel borders and keep the template outer safe zones. A video that reads as a small inset in a large empty proof panel is a composition QA failure. - When a source video or image is framed by a visible proof border, the media must be intentionally aligned to that frame: either flush to the frame edges with the source label in a separate strip, or inset by a documented and visually even padding value. Do not leave a large empty proof panel around a smaller media element, and do not allow the media frame to overlap titles, captions, badges or source labels. - HyperFrames Studio edit metadata must not become production layout truth. Before preview handoff or render, inspect `index.html` for `data-hf-studio-*`, `--hf-studio-*`, inline `translate`, inline `transform` or drag/resize `style` attributes on public media containers (`video`, `img`, `.video-panel`, `.video-wrap`, screenshot wrappers, proof panels). Remove or replace them with deterministic CSS classes unless they are an explicitly documented intentional animation state. Media that jumps away from its scene text because of Studio-written offsets is a QA failure. - A full-page/full-desktop screenshot may be kept only as raw source evidence in `assets/` or `capture/`; the visible public layer must be a focused crop or source-backed callout when readability would otherwise suffer. - Source visuals must be semantically tied to the narration: inventory official repo/site images first, then download only the necessary selected images that support planned scene claims. Prefer product/homepage images, changelog/release history, documentation diagrams, adoption/history charts or explicit source-backed callouts over arbitrary crops. A readable but purposeless screenshot is still a quality failure. - Public frames must not include QA/debug labels, crop markers, red review rectangles, "focus crop" text or internal inspection notes. - Public frames must not include internal source-compliance disclaimers such as "no Facebook frames used" when a third-party link was used only for research. Keep those details in `capture/source-record.json`, `QA.md` or `HANDOFF.md`. - A TikTok outro uses a compact profile-card below flexible closing content; it must retain the selected channel identity and must not display invented social metrics. - TikTok profile cards must be horizontally compact, visually centered in their allotted lower/outro area and content-fitted. Empty pill tails, over-wide black backgrounds, off-center placement or oversized cards are QA failures. - The TikTok outro/profile UI uses the canonical `templates/components/tiktok-profile-card/` component or a byte-identical vendored copy from the packaged common asset set. - A TikTok compact profile-card preview shows a pointer click on `Follow` and a visible confirmed state such as `Following`. - The packaged `ainew247na.jpg` avatar/brand image and `cursor-hand.png` pointer asset are used across all templates unless a documented channel override is approved; portable template copies must remain byte-identical to the packaged common assets. - A production TikTok follow click uses the packaged `follow-click.wav` or a documented localized, rights-cleared replacement synchronized with the button press. Visual-only template QA may use the packaged default SFX slot, but may not omit the SFX requirement. - Default `.mp3`, `.mp4` and `.gif` packaged under `templates/assets/default-media/` are placeholders for installation/template QA only; public production output must generate project-specific narration, rendered video and topic-specific visual media. - Public output contains no captured frames or screen recording from a third-party reference video. - Every composition MUST use actual, topic-specific visual evidence or illustrations (such as cropped screenshots, diagrams, images, or animated GIFs) under the local `assets/` directory and referenced in `index.html`. Relying solely on text panels without relevant visual media is a quality failure. - Public video/image inserts must be locked to deterministic CSS layout before render: the final visible state should be controlled by normal document flow, flex/grid constraints, aspect-ratio, object-fit/object-position and stable padding. Do not rely on manual Studio drag handles, transient preview transforms or per-element inline offsets for final placement. - Assets required for rendering are local or reliably addressed by the project. - The composition follows deterministic HyperFrames timing practices and does not rely on raw ffmpeg-only assembly, screen recordings, Remotion-only projects or slideshow exports as the primary runtime. ## Output Gate - The project contains its title/script, `PUBLISH.md` post package, storyboard, voiceover source, composition, render and appropriate visual check evidence. - Render output exists and has been generated via `npx hyperframes render` and checked for layout, clipping and audio alignment before it is described as complete. - Template preview/contact-sheet evidence is generated from HyperFrames sequences, not from manually mocked stills or another animation runtime. - Evidence-led output includes a source record, media-role plan, visual QA evidence and final handoff disclosure as defined by `editorial-media.md`. - The `QA` checkpoint is complete only for the current render/composition fingerprints; changing either invalidates prior QA. - Every successful render handoff explicitly sends the render path, publish title and exactly 5 hashtags to the user, sourced from `PUBLISH.md`. - A batch `SUMMARY.md` lists publish-ready output only when the linked current item state has QA complete and no unresolved template or fallback decision; blocked and failed items remain visible. ## Phase Boundaries Template promotion QA is defined in the template authority. Detailed proof-media and reference-video handling is active through `editorial-media.md`; this universal gate continues to block unverifiable or rights-risk material.