yugoo-design 0.1.0 → 0.2.0

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/smart_questions/schema.yaml

@@ -0,0 +1,93 @@
+# smart_questions Design Files data contract (write-time validation).
+# Faithful declarative translation of sdk-pilot
+# skill/design_skills/smart_questions/schema.py (Pydantic, extra="forbid").
+#
+# Executor-owned fixed-card contract (not automatic schema/Core seeding):
+# carry both fixed definitions into every complete state — prompt, kind and
+# choices are stable; only `answer` and `detail` are user-owned. Fixed cards
+# have no `round` / `rejected`; panel.yaml declares their UI protection.
+#
+#   const_auth_mode:
+#     prompt: 是否需要注册登录？
+#     kind: single
+#     choices:
+#       - { value: anonymous, label: 不需要，直接使用, recommended: true }
+#       - { value: auth_required, label: 需要，支持注册登录, recommended: false }
+#     answer: anonymous
+#     detail: ""
+#   const_storage_mode:
+#     prompt: 应用数据如何保存？
+#     kind: single
+#     choices:
+#       - { value: browser_temp, label: 仅当前浏览器临时保存, recommended: true }
+#       - { value: database_persistent, label: 持久保存，可跨设备继续使用, recommended: false }
+#     answer: browser_temp
+#     detail: ""
+#
+# Choice quality, answer resolution, fixed-card, and attachment-quality
+# semantics are Producer self-checks in SKILL.md; this schema owns the stable
+# persisted shape only.
+type: object
+additional_properties: false
+properties:
+  # Optional for existing files. New rounds have independently authored display
+  # copy keyed by the saved nonnegative integer round's decimal string, not its
+  # consecutive UI label. Meaningful nonempty copy is an executor self-check.
+  rounds:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [title, description]
+      properties:
+        title: { type: string }
+        description: { type: string }
+  questions:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [prompt]
+      properties:
+        prompt: { type: string }
+        kind: { type: enum, values: [single, multiple, text] }
+        choices:
+          type: array
+          items:
+            type: object
+            additional_properties: false
+            required: [value, label]
+            properties:
+              value: { type: string }
+              label: { type: string }
+              recommended: { type: boolean }
+        # The direct response: text questions store their substantive answer here;
+        # choice questions store selected choice values. Source-supported answers
+        # in reconstruction belong here too, without implying user confirmation.
+        # Leave genuinely unknown answers empty; never promote a proposal as an answer.
+        answer: { type: string }
+        # Optional supplementary explanation, constraints or source locations.
+        # Do not put a known text answer only here. A choice response outside the
+        # available options may be preserved here without inventing a selection.
+        # Supplementary detail alone does not mark the question answered.
+        detail: { type: string }
+        multimodal_answer:
+          # The native panel prepares each local Bundle-owned Design File and
+          # its reference together for generic atomic Panel Save. New uploads
+          # use a SHA-256 filename. Browser-only transport bytes are never
+          # persisted in canonical state.
+          type: array
+          items:
+            type: object
+            additional_properties: false
+            required: [type, file_md5, filename, mime_type, size_bytes]
+            properties:
+              # `image` remains readable for references created before generic files.
+              type: { type: enum, values: [file, image] }
+              file_md5: { type: string }
+              filename: { type: string }
+              mime_type: { type: string }
+              size_bytes: { type: number }
+              artifact_file: { type: string }
+        round: { type: number }
+        rejected: { type: boolean }

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/smart_questions/validation.yaml

@@ -0,0 +1,17 @@
+# Rich question and answer quality checks remain Producer self-checks in
+# SKILL.md. The persisted shape is enforced by schema.yaml.
+skill: smart_questions
+
+rules:
+  - id: referenced_files_present
+    scope: [state]
+    code: smart_questions.referenced_artifact_invalid
+    check:
+      referenced_files: ["questions.*.multimodal_answer.*.artifact_file"]
+
+  - id: questions_present
+    scope: [completion]
+    code: smart_questions.empty
+    message: "At least one question is required before completing the Bundle."
+    repair_hint: "Keep the fixed questions and add only the smallest useful current round."
+    check: { non_empty_map: questions }

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/web_app_prd_assembly/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: web_app_prd_assembly
+description: |-
+  - **Capability**: generate or update one development-ready Web App PRD from current design evidence and user material.
+  - **Candidate when**: the user asks to generate, export, update, or inspect a complete PRD.
+  - **Do not infer**: PRD assembly is an on-demand delivery action, not a required design gate and not permission to mutate owner Bundles.
+  - **Output**: one stable canonical `prd.html`; Git stores history.
+---
+
+# Web App PRD Assembly
+
+Produce a product specification, not a summary of design panels or a report
+about the assembly process. Product, design, engineering, test, implementation,
+and operations must be able to understand the same product behavior without
+knowing DSH, Bundle schemas, state revisions, or internal artifact mechanics.
+
+## Execution ownership
+
+The foreground Producer owns the complete logical job:
+
+1. read the template, current canonical PRD, and current evidence;
+2. create or target-edit `web_app_prd_assembly/prd.html` and its canonical JSON;
+3. materialize visuals through the shared artifact contract's file-mode script call;
+4. validate the landed HTML with the same contract's exact source files, state and template inputs;
+5. use every returned diagnostic to make the smallest targeted repair;
+6. keep the accepted state and artifact bytes in the WorkingCopy;
+7. call `design_publish({action:"complete"})` only after the script and normal
+   schema/declarative validation pass.
+
+Like every other heavy Bundle, a new PRD keeps `html_file: null` until the
+validated document exists in the Producer WorkingCopy. Host execution attempts,
+not canonical PRD fields, describe queued, working, failed, or completed work.
+
+The Producer uses the project-scoped `list` and `read` tools to inspect current
+evidence, then `write` or `edit` for its owned state and HTML. On a later user
+request it locates and reads the affected chapters, then modifies those
+chapters, answers, decisions, and temporary-completion ledger in place. It preserves
+unaffected content and never starts a new question round merely because an
+existing PRD answer needs revision.
+
+Keep reads bounded after visuals have been embedded: use native search and
+range reads for the relevant heading or passage, not a full read of the HTML
+containing SVG and base64 images. Pass whole files to the existing script by
+path when validation or visual projection needs them.
+
+The Producer performs the complete PRD assembly itself and retains validation
+and publication authority. It may use read-only evidence tools for independent
+source inspection, but does not delegate PRD file authorship.
+
+Core owns path isolation, schema/declarative checks, atomic Design Files writes,
+Git publication, and UI refresh. This Bundle's ordinary script deterministically
+projects fixed visual artifacts and checks PRD semantics. The Producer owns
+evidence selection, invoking that projection, repairs, and the final publication
+decision.
+
+## Shared output contract
+
+Read [reference/artifact-contract.md](reference/artifact-contract.md) and its linked template before writing. These define the single HTML shell, visual reference syntax and file-mode finalization shared by normal PRD assembly and reconstruction.
+
+## PRD writing standard
+
+Write a conventional implementation-oriented PRD, not a collection of schema
+tables. Prose carries the product reasoning; tables are supporting indexes for
+comparison, lookup, matrices, field definitions, and exact rule values. Never
+replace a chapter's explanation with one or more tables.
+
+Use a progressive narrative in each applicable chapter: context and user
+problem, intended outcome, product behavior, rationale and boundary, important
+rules or exceptions, dependencies, and observable acceptance. Explain only
+facts supported by the allowed evidence; use the existing temporary-completion
+rail when a necessary decision is unsupported.
+
+In particular:
+
+- product definition explains the problem, product judgment, goals, principles,
+  and non-goals as a coherent argument;
+- user and scope content follows real scenarios and outcomes before summarizing
+  segments or release scope in a table;
+- capability architecture has one subsection per Epic/module and explains its
+  user value, responsibility, boundary, collaboration, main behavior, rules,
+  exceptions, priority, and dependencies;
+- after the solution overview, every active `F-xxx` has an independently
+  readable functional requirement covering its goal and scenario, actor and
+  entry/precondition, system behavior, outcome, rules and exceptions, related
+  Page/Flow evidence, and unresolved gaps. An Epic summary or one-line function
+  table never substitutes for these functional requirements;
+- format each functional requirement for scanning: one short prose paragraph
+  states user value and the capability boundary; a compact bullet list states
+  actor, entry, preconditions, inputs, and outputs; a numbered list states the
+  main interaction or processing sequence; and a final bullet list states
+  observable states, rules, exceptions, dependencies, related Page/Flow
+  evidence, and unresolved gaps. Omit unsupported fields instead of inventing
+  them. Do not simulate this structure with a stack of bold-labelled
+  paragraphs;
+- business information explains object lifecycles and relationships from
+  `business_data` before any data dictionary. Distinguish subtype inheritance
+  from association, explain both quantity directions in ordinary language,
+  and preserve undecided quantities. Do not turn types into sample instances
+  or copy inherited fields into a second owner;
+- business rules explain why, when, and how controls apply before the rule table;
+- integrations, notifications, security, analytics, quality, and operations
+  explain runtime behavior, failure handling, and ownership instead of merely
+  listing fields;
+- acceptance criteria connect to the described behavior and are observable and
+  testable; avoid generic claims such as “good experience” or “high performance”.
+
+Do not inflate the document with repeated wording or arbitrary prose. Concise
+means shorter reasoning and fewer examples, not removal of the reasoning.
+Detailed means implementation-ready elaboration, not a larger table.
+
+## Evidence authority
+
+When function_modules contains optional structured `details`, consume its
+purpose, situation, behaviors, inputs, outputs, limits and exceptions as
+function-local specifications, not just the card description. Preserve their
+meaning in the relevant functional requirement; do not flatten them into an
+Epic index or invent missing fields to fill a template. Source `references`
+are locations of evidence, not approvals. Read their exact pinned version
+when needed, and compare with current owner evidence and later user intent;
+an obsolete, unavailable or positional-array source cannot prove a current
+decision. Existing shared Flow/Rule/Data/Access owners remain authoritative
+for their shared specifications. Do not write back to functions or source
+owners merely to assemble the PRD.
+
+Read current owner state from `<skill>/<skill>.json` and artifacts referenced by
+it. Use this precedence for every decision:
+
+1. current user instruction;
+2. confirmed owner evidence;
+3. unconfirmed owner evidence;
+4. conservative PRD-local AI completion.
+
+Use only the source owners declared for the chapter in the template. Never
+rewrite owner state or copy it into a parallel JSON ledger. Resolve naming
+differences into one product vocabulary while preserving the actual semantics.
+Do not average contradictory facts: state the adopted decision, reason, impact,
+and confirmation owner in the PRD.
+
+Encode sources directly on each chapter H2 as `data-prd-sources`; use
+`data-prd-provenance-ids` only for temporary completions in that chapter. List
+only sources actually used. Content quoted, summarized, reorganized, rewritten,
+or synthesized from existing Design Files is ordinary grounded PRD content and
+must not receive a purple rail. A direct, unchanged quotation may additionally
+use `prd-verbatim-source` with its exact `data-prd-source-ref`; publication
+verifies that quotation against the fixed source text.
+
+## Temporary completions and pending assumptions
+
+Create an `ai_provenance` state item only when the Producer must temporarily
+fill an unsupported product decision so the PRD remains structurally complete.
+Every item uses `operation: completion`, records its affected `section_ids`, a
+concise `description`, the source refs considered, and a non-null `assumption`
+with `decision`, `reason`, `impact`, and `decision_owner`. Wrap only that
+temporary content in a transparent
+`<div class="ai-provenance" data-provenance-id="AI-001">...</div>` purple left
+rail. A marker may cover adjacent paragraphs, a list, or a table, but must not
+contain grounded content merely because the Producer authored its wording.
+Include each pending assumption in the final “决策、待确认与追溯” chapter and
+mark repeated rendering with the same provenance ID.
+
+The PRD must remain implementable when design evidence is incomplete. Fill the
+smallest necessary semantic gap conservatively instead of blocking merely
+because an optional design Bundle has not run. Use an `operation: completion`
+item with its required `assumption`, keep its visible product content
+inside the provenance rail, and ask for confirmation rather than presenting
+the decision as user-approved.
+
+Do not invent customer-specific SLA, laws, commercial terms, real credentials,
+endpoint addresses, or irreversible commitments. Leave those as explicit open
+questions. Ordinary connective words do not need their own ledger item, but
+they must remain inside the marker for the generated passage they connect.
+
+An empty `ai_provenance` array is valid only when every normative product
+decision in the document is directly supported by available owner evidence.
+The existence of several upstream Bundles does not prove completeness. When
+business-data, business-rule, role, integration, notification, or acceptance
+evidence is absent, any concrete behavior supplied for that concern is a
+temporary completion and must use the purple marker and ledger. Never claim
+that all chapters have complete evidence merely because the core Bundles exist.
+For the business information, business rules, roles/security, integrations,
+notifications, and quality/acceptance chapters, absence of that chapter's
+authority Bundle means every concrete passage in the chapter is a temporary
+completion. Keep the complete generated passage—not only a disclaimer—inside
+declared `ai-provenance` rails. Structural headings may remain outside.
+
+## Visual evidence
+
+Follow the shared artifact contract’s visual directives. Place each process/page description beside its corresponding empty visual-item pair; the script fills that pair from exact owner files, never model-redrawn assets.
+
+## Writing workflow
+
+### 1. Establish the anchor
+
+Only when no document exists, prepare schema version 8 with the product title, requested detail level,
+`ai_provenance: []`, and `html_file: null`. Keep this in
+the WorkingCopy while assembling the document; do not publish an intermediate
+state. First write the template shell to
+`web_app_prd_assembly/prd.html`, replacing only its title placeholders. Keep
+the stylesheet, headings and visual markers intact. Do this before composing
+chapter prose: never generate the complete PRD in one write or edit call.
+Read owner states as needed per chapter; independent evidence reads may run
+together, but do not preload every visual artifact into model context.
+If a document already exists, use the interrupted-generation/revision path
+below instead of reseeding the shell or resetting its provenance.
+
+When reading a version 6 or 7 project, drop legacy `status`,
+`failure_reason`, and `source_digests`, migrate to version 8, and treat its `html_file` as accepted
+only when the referenced document is readable. Normalize the legacy
+Bundle-relative `prd.html` value to the project-relative
+`web_app_prd_assembly/prd.html` reference. Git publications provide history.
+
+### 2. Work chapter by chapter
+
+For each applicable template chapter:
+
+1. inspect only its declared source owners and referenced artifacts;
+2. extract product decisions, not schema telemetry;
+3. reconcile terminology and cross-chapter references;
+4. allocate an unused provenance ID and persist its assumption in the existing
+   `ai_provenance` array before writing an unsupported decision; use that same
+   ID in the passage and chapter heading, without marking grounded prose;
+5. make one bounded `edit` to `web_app_prd_assembly/prd.html`: an ordinary short
+   chapter, one functional requirement or a small related group, or one
+   process/page description with its empty visual-item pair. A large chapter
+   requires multiple edits, not a larger single output;
+6. keep the prescribed outer visual region pair verbatim. Within distributed
+   BPMN and Page regions, write the relevant prose and empty per-artifact
+   reference pairs in natural reading order; never author figure bytes yourself.
+
+Prefer targeted `edit` operations after the first write. Never restart a
+complete document because one chapter, marker, or visual directive fails.
+Use the template's unique guidance comment as the insertion anchor. For
+multi-part chapters, retain that comment until all required items are written;
+insert process/page items immediately before the corresponding existing outer
+visual end marker, preserving it for the next insertion. Keep each inserted
+HTML block balanced. Remove the chapter guidance only after checking its
+coverage, and remove inapplicable conditional chapters rather than filling
+them with invented requirements.
+
+Only one Producer writes the PRD. Do not create chapter fragment files,
+delegate concurrent edits to this HTML, or introduce a progress ledger.
+The existing template anchors and landed content are sufficient.
+
+### Interrupted generation or later revision
+
+Inspect the current canonical JSON and bounded portions of the existing HTML.
+Find remaining template guidance/title placeholders and compare the written
+functional requirements and process/page sections with the current owner
+records. Resume at the first unfinished item using a small edit; preserve
+completed prose, IDs, stylesheet and embedded visuals. Do not reset the
+provenance array or assume a missing tool result means its write did not land:
+check the file before retrying that insertion.
+
+An empty `data-prd-provenance-ids` is valid for grounded content, not an
+unfinished-work signal. Reconcile orphan provenance entries and missing rails
+left by interruption using the actual passage and existing ledger; do not
+allocate a second ID for the same temporary decision. For an existing accepted
+document, preserve its reference and edit only the requested content.
+
+If output was truncated, reduce the next edit's scope instead of repeating
+the same full chapter/document. Repeated truncation without landed progress
+must be reported as incomplete; do not claim success or loop indefinitely.
+
+### 3. Cross-check the product model
+
+Before finalization, verify at least:
+
+- no title placeholder or unfulfilled template guidance remains; required
+  chapters and applicable owner entities have actual prose, not just headings;
+- users, scenarios, roles, flows, pages, and acceptance use consistent names;
+- each capability has an outcome, priority, page or explicit non-UI path;
+- each state-changing action has actor/system, trigger, rule, result, and failure behavior;
+- object, field, rule, permission, integration, notification, and acceptance references resolve;
+- every active flow and completed page prototype has its template visual directive;
+- every purple temporary-completion marker matches exactly one non-null pending
+  assumption and the correct chapter;
+- grounded passages remain normal content and list their actual source owners.
+
+## Post-write Design projection self-check
+
+Before publication, review all chapters in bounded reads against the current
+owner evidence, without reading embedded image/SVG bytes into context. Compare the document headings, source
+annotations, provenance IDs, pending assumptions, and deterministic visuals
+with the pinned owner
+evidence. Repair one owned deterministic issue with
+at most one focused follow-up, then inspect the refreshed projection once more. Ask the user when a
+real product decision is required. If an owner Bundle or referenced artifact is
+missing, malformed, or unresolved, report that non-blocking evidence gap
+without editing the owner Bundle or retrying indefinitely. After publication
+enters Git history, G/R/A owns ongoing cross-Bundle drift checks.
+
+### 4. Finalize inside the same agentic loop
+
+Once prose and provenance are complete, run the shared contract’s file-mode finalization against the already-written HTML. Do not rewrite the document or transport visual bytes through model context.
+
+If the script reports diagnostics, preserve valid content, apply the smallest
+useful edit, and run it again. A repeated identical diagnostic with no file or
+state progress is a real failure and must be reported; do not launch an
+automatic full-document regeneration.
+
+After successful validation, persist that same state with its accepted
+`html_file` reference. Then call `design_publish({action:"complete"})` so the already-written state
+and HTML publish atomically. In the user-facing summary, report the canonical
+path and pending-assumption IDs. The Panel legend and document use the
+template-defined transparent light-purple left rail only for unsupported
+temporary completions that still need confirmation.

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/web_app_prd_assembly/reference/artifact-contract.md

@@ -0,0 +1,140 @@
+# PRD output contract
+
+Shared by normal assembly and reconstruction. State is `web_app_prd_assembly/web_app_prd_assembly.json`; document is `web_app_prd_assembly/prd.html`. This is a format/projection contract, not permission to fill missing product decisions. During reconstruction report absent evidence instead of inventing requirements to fill the template. If required evidence cannot be represented legally, report that limitation without bypassing validation.
+
+## Single source of structure
+
+Load the only PRD template with `read_skill_resource` from
+`reference/prd-template.html`. It is the sole authority for the complete HTML
+document shell and stylesheet, chapter IDs, chapter
+policy, allowed evidence owners, missing-evidence behavior, and visual directive
+locations. There is no second YAML template, hardcoded topic catalog, outline
+ledger, coverage database, or content manifest.
+
+Start from that HTML template and replace its title placeholders and chapter
+guidance comments with product content. Keep its document stylesheet byte-for-byte,
+use no additional `<style>` blocks or inline `style` attributes, and do not add
+presentation classes. The fixed shell deliberately renders a plain white,
+black-text, print-friendly document. The only authored semantic classes are the
+template's note/warning markers, the purple `ai-provenance` rail, and optional
+`prd-verbatim-source`; visual projection classes are written only by `prd.mjs`.
+
+`detail_level: concise` and `detail_level: detailed` share that structure.
+Concise compresses explanations and repeated rows; detailed expands all
+applicable records. `policy: required` chapters always appear. A
+`policy: conditional` chapter appears only when the product has that concern,
+the corresponding owner evidence exists, or the user explicitly requests it.
+
+## Visual evidence
+
+Use the template's `prd-visual:*:start/end` regions verbatim. Do not author
+parallel copies of function maps, BPMN XML/SVG, page maps, prototype
+screenshots, or style previews inside this Bundle.
+
+- `function_scope_map` projects all active functions once as a mind map: product
+  root, Epic branches, and function leaves.
+- `all_bpmn` projects every active canonical `.bpmn` artifact.
+- `page_map` projects the canonical page map.
+- `all_page_prototypes` captures every completed page prototype.
+- `design_preview` captures the representative design-style preview when present.
+
+Resolve these directives from the exact owner states and artifacts in the same
+Producer session. The Producer does not redraw them. It supplies the exact files
+to `prd.mjs materialize-visuals`, which replaces only the five prescribed visual
+regions and writes the transformed bytes back to the same canonical HTML path:
+
+- inside `all_bpmn`, place one empty
+  `<!-- prd-visual-item:flow_design/P-001.bpmn:start -->` and matching `:end`
+  pair inside a matching
+  `<section data-prd-entity-ref="flow_design/P-001.bpmn">` immediately after
+  the prose describing that exact process; repeat for every active process;
+- inside `all_page_prototypes`, place the corresponding empty
+  `prd-visual-item:page_design/pages/<page>.html` pair immediately after the
+  prose describing that exact page, inside a matching
+  `<section data-prd-entity-ref="page_design/pages/<page>.html">`; repeat for
+  every completed page;
+- do not collect all descriptions first and all visuals afterward. The Skill
+  owns document order and proximity; the script only fills reference pairs.
+
+- function and page maps are deterministic SVG projections of their canonical JSON;
+- the PRD page map is a reading projection rather than a copy of editor canvas
+  coordinates: it derives a primary navigation hierarchy from canonical
+  connections, renders primary routes prominently, and keeps secondary
+  cross-links visually subordinate. It does not mutate Page Design state;
+- each active BPMN is rendered temporarily during PRD assembly through the
+  standard `bpmn-js` viewer/exporter and embedded directly as vector SVG. Do not
+  persist a companion `.svg` file and do not redraw BPMN notation by hand;
+- each completed Page prototype and Design Style preview is rendered temporarily
+  from its exact source HTML at a 1440×900 desktop viewport.
+  Its landed `design_style/tokens.css` dependency is injected before rendering;
+  the resulting PNG is embedded directly in the PRD at full text width and a
+  16:10 aspect ratio. Do not persist a companion screenshot or use an iframe.
+
+Every rendered figure carries its exact project-relative
+`data-prd-source-ref`. The operation is idempotent and may read only files
+explicitly supplied through `input_files`; the Host reads their exact bytes so
+the model never copies or reconstructs file content. It never falls back to a
+summary, prompt, model-redrawn image, guessed BPMN layout, browser screenshot,
+or Provider runtime. Leave a region empty only when the corresponding owner
+state or referenced artifact does not exist. If canonical owner state references
+an artifact that is missing, malformed, or cannot be faithfully projected, the
+script fails and the Producer reports or repairs the evidence gap before
+publication. Git history binds the PRD publication to the source-file versions
+used for assembly.
+
+## Evidence markers and bounded writing
+
+Chapter H2 `data-prd-sources` lists only owners actually used from the template's
+allowed sources. `data-prd-provenance-ids` references temporary decisions in that
+chapter. Preserve grounded facts as grounded content; reconstruction cannot
+invent assumptions merely to satisfy a required chapter. Report an unsupported
+required representation instead of disguising it as a fact.
+
+When revising an existing PRD, retain its still-applicable ledger entries and
+markers with their original IDs. Quoting or reorganizing facts or inferences
+from other Design Files does not create a new purple marker merely because an
+AI authored that source. Ordinary forward assembly records a newly supplied
+unsupported product decision according to the Skill Body's completion policy;
+reconstruction does not supply such new decisions to fill evidence gaps.
+
+For a PRD-local temporary completion, the `ai_provenance` entry uses
+`operation: completion`, `section_ids`, `description`,
+source refs and `assumption` with `decision`, `reason`, `impact`, `decision_owner`.
+The corresponding HTML uses
+`<div class="ai-provenance" data-provenance-id="AI-001">...</div>` around only
+that content, with the same ID in the chapter and traceability section.
+A direct unchanged quotation may use `prd-verbatim-source` and its exact
+`data-prd-source-ref`. Validation checks those claims against supplied files.
+
+One Producer owns the complete document. Start from the shell, then make bounded
+edits per chapter or per function/process/page. Resume existing content rather
+than writing the whole PRD in one tool call. Preserve the template anchors until
+their content is complete; no parallel chapter files or concurrent authors of
+the same HTML. Read bounded prose regions, not the embedded images/SVG, and
+use file-mode scripts for transforms and final checks.
+
+## File-mode finalization
+
+Once the prose and provenance are complete, process the already-written HTML;
+do not rewrite it for finalization. First call `run_skill_script` with
+`path: "prd.mjs"`, `args: ["materialize-visuals"]`, and both `input_file` and
+`output_file` equal to `web_app_prd_assembly/prd.html`. Pass bounded
+`input_files`: every relevant canonical owner JSON plus every BPMN/Page/Design
+Style artifact referenced by those states,
+including `design_style/tokens.css` when a Page prototype or style preview uses
+the shared Design System tokens.
+The successful transform writes only the canonical HTML and returns a compact
+file receipt, so source HTML and generated document bytes do not pass through
+the model response.
+
+Then call `run_skill_script` with `args: ["validate-html-file"]` and the same
+`input_file` and the same `input_files`. Pass `input_context` containing the
+current `state` with `html_file: web_app_prd_assembly/prd.html` for this
+validation, and `template` equal to the exact template text. For a new document, keep the on-disk
+JSON reference null until this check succeeds. The script verifies source availability, complete
+visual coverage and source binding, iframe confinement, temporary-completion
+authority, and verbatim claims. It returns only validity and diagnostics; the
+complete HTML never returns through the model tool result.
+
+
+On diagnostics, repair the existing document in bounded edits and repeat the file checks. Set the accepted `html_file` only after validation, then run normal `design_validate` and `design_publish({action:"complete"})`. Never return a full document or embedded image bytes through model arguments.

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/web_app_prd_assembly/schema.yaml

@@ -0,0 +1,38 @@
+# Stable state for the single canonical Web App PRD HTML document. Execution
+# lifecycle and failures belong to Host attempts; this record retains only the
+# accepted artifact reference and temporary completion ledger.
+type: object
+knowledge: { role: metadata, source_kind: derived }
+additional_properties: false
+required:
+  - schema_version
+  - title
+  - detail_level
+  - ai_provenance
+  - html_file
+properties:
+  schema_version: { knowledge: { role: metadata }, type: enum, values: [8] }
+  title: { type: string }
+  detail_level: { type: enum, values: [concise, detailed] }
+  ai_provenance:
+    type: array
+    items:
+      type: object
+      additional_properties: false
+      required: [id, section_ids, operation, description, source_refs, assumption]
+      properties:
+        id: { type: string }
+        section_ids: { type: array, items: { type: string } }
+        operation: { type: enum, values: [completion] }
+        description: { type: string }
+        source_refs: { type: array, items: { type: string, knowledge: { role: reference } } }
+        assumption:
+          type: object
+          additional_properties: false
+          required: [decision, reason, impact, decision_owner]
+          properties:
+            decision: { type: string }
+            reason: { type: string }
+            impact: { type: string }
+            decision_owner: { type: string }
+  html_file: { type: enum, values: [web_app_prd_assembly/prd.html], nullable: true }

package/payload/overlays/qoder/authoring/studio-creators/source/packages/skills-web-app/bundles/web_app_prd_assembly/validation.yaml

@@ -0,0 +1,24 @@
+# Cheap state checks remain declarative. The HTML file, fixed HTML template,
+# provenance, visual-region, and source checks live in scripts/prd.mjs and
+# are run by the foreground Producer before publication.
+skill: web_app_prd_assembly
+
+rules:
+  - id: referenced_files_present
+    scope: [state]
+    code: web_app_prd_assembly.referenced_artifact_invalid
+    check:
+      referenced_files: ["html_file"]
+
+  - id: empty_title
+    scope: [completion]
+    code: web_app_prd_assembly.empty_title
+    message: "PRD title must not be empty."
+    check: { non_empty_string: title }
+
+  - id: completed_artifact_ref
+    scope: [completion]
+    code: web_app_prd_assembly.incomplete
+    message: "The PRD has no accepted HTML artifact reference."
+    repair_hint: "Validate and write web_app_prd_assembly/prd.html, then publish that file and html_file together."
+    check: { non_empty_string: html_file }