diff --git a/.github/workflows/community-smoke.yml b/.github/workflows/community-smoke.yml index 27cc6ed7bc..06720d89e6 100644 --- a/.github/workflows/community-smoke.yml +++ b/.github/workflows/community-smoke.yml @@ -81,7 +81,6 @@ jobs: test -f .specify/presets/workflow-preset/schemas/speckit.behavior.scenario-instances.v1.schema.json test -f .specify/presets/workflow-preset/schemas/speckit.behavior.data-fixtures.v1.schema.json test -f .specify/presets/workflow-preset/schemas/speckit.behavior.assertions.v1.schema.json - test -f .specify/presets/workflow-preset/schemas/speckit.design.visual-item-matrix.v1.schema.json test -f .specify/presets/workflow-preset/schemas/speckit.implement.manifest.v1.schema.json test -f .specify/presets/workflow-preset/schemas/speckit.implement.handoff.v2.schema.json test -f .specify/presets/workflow-preset/schemas/speckit.implement.receipt.v1.schema.json diff --git a/.github/workflows/workflow-preset-integration.yml b/.github/workflows/workflow-preset-integration.yml index 684aeee41f..8094bebd6f 100644 --- a/.github/workflows/workflow-preset-integration.yml +++ b/.github/workflows/workflow-preset-integration.yml @@ -117,7 +117,7 @@ jobs: test -f .specify/presets/workflow-preset/preset.yml test -f .specify/presets/workflow-preset/templates/plan-template.md test -f .specify/presets/workflow-preset/templates/constitution-template.md - test -f .specify/presets/workflow-preset/schemas/speckit.design.visual-item-matrix.v1.schema.json + test -f .specify/presets/workflow-preset/schemas/speckit.implement.receipt.v1.schema.json test -f .specify/templates/tasks-template.md test -f .specify/presets/workflow-preset/commands/speckit.constitution.md test -f .specify/presets/workflow-preset/commands/speckit.plan.md diff --git a/presets/catalog.community.json b/presets/catalog.community.json index 19561d118b..9d13af001b 100644 --- a/presets/catalog.community.json +++ b/presets/catalog.community.json @@ -683,7 +683,7 @@ "speckit_version": ">=0.8.10.dev0" }, "provides": { - "templates": 27, + "templates": 22, "commands": 8 }, "tags": [ diff --git a/presets/catalog.json b/presets/catalog.json index 011f8f60f0..4073fd714a 100644 --- a/presets/catalog.json +++ b/presets/catalog.json @@ -40,7 +40,7 @@ }, "provides": { "commands": 8, - "templates": 27 + "templates": 22 }, "tags": [ "behavior", diff --git a/presets/workflow-preset/CHANGELOG.md b/presets/workflow-preset/CHANGELOG.md index 3e4d33cbbe..5db39ecac1 100644 --- a/presets/workflow-preset/CHANGELOG.md +++ b/presets/workflow-preset/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- Migrated product, design, provider, and HTML intake ownership out of the workflow preset and into the external `spec-kit-intake` extension; the preset now consumes external intake refs and visual SSOT refs while retaining `spec.md` projection and Visual Fidelity readiness. - Added constitution governance coverage for the fixed R/M/U/O mapping and Architecture SSOT boundary, with preset manifest, documentation, contract tests, and install smoke checks aligned to the constitution template. - Fixed the preset artifact integration workflow to update both bundled and community catalog metadata before opening the `bigsmartben/spec-kit` fork PR. @@ -17,7 +18,7 @@ - Hardened implement receipt completion gates so deferred validation or unapproved code review cannot mark `tasks.md` items complete. - Added Final Code Review visual consistency checks for implemented UI states, viewport behavior, visual proof evidence, and Client Asset Contract bindings. - Clarified that `/speckit.tasks` defines validation, visual verification, contract validation, data-side-effect validation, integration/e2e validation, and scope-aware code review tasks, while `/speckit.implement` only executes those tasks and records receipt evidence without inventing validation strategy or widening scope. -- Added Visual Item Matrix and Visual Restoration Trace fields so Figma/provider evidence can carry stable UI/UX restoration refs into `spec.md` and Visual Fidelity readiness. +- Added Visual Item Matrix and Visual Restoration Trace fields so provider evidence can carry stable UI/UX restoration refs into `spec.md` and Visual Fidelity readiness. - Added a normalized Visual Item Matrix JSON schema and validator checks for deterministic UI/UX restoration intake. - Added validator coverage that rejects full provider Visual Item Matrix copies inside Design Requirement Intake Visual Restoration Trace rows. - Clarified that provider evidence artifacts may record screenshot/proof refs and provider blockers, while only the checklist Visual Fidelity Evidence Matrix decides visual planning readiness, proof sufficiency, Gate Status, Blocking Items, and accepted exception rules. @@ -31,15 +32,15 @@ ## 1.3.7 -- Generalized Figma-derived requirement handling into provider-neutral Design Requirement Intake and Requirement Merge templates while keeping Figma MCP execution outside the preset. +- Generalized provider-derived requirement handling into provider-neutral Design Requirement Intake and Requirement Merge templates while keeping provider tool execution outside the preset. - Added a row-per-case Case Coverage Matrix to make positive, negative, boundary, permission, validation, and state_conflict applicability explicit before planning. - Hardened failure behavior scenarios so permission, validation, state_conflict, and other error paths require structured request cases, error responses, failure feedback, and assertions before tasks are generated. - Hardened UI task generation so UI implementation and acceptance tasks are paired with explicit state coverage, viewport coverage, visual proof refs, screenshot refs, and readiness blockers for missing visual or asset evidence. ## 1.3.6 -- Added a Figma Evidence Packet input template and Figma intake contract for Figma-derived specifications without adding Figma MCP execution to the preset. -- Hardened Figma intake readiness with raw metadata completeness, metadata index proof, node inventory parity, and blocker lint gates before writing Figma-derived requirements. +- Added a Provider Evidence Packet input template and provider intake contract for provider-derived specifications without adding provider tool execution to the preset. +- Hardened provider intake readiness with raw metadata completeness, metadata index proof, node inventory parity, and blocker lint gates before writing provider-derived requirements. ## 1.3.4 diff --git a/presets/workflow-preset/README.md b/presets/workflow-preset/README.md index 5f87d87445..2f5a654370 100644 --- a/presets/workflow-preset/README.md +++ b/presets/workflow-preset/README.md @@ -35,13 +35,13 @@ Requirement capabilities: - Wraps `/speckit.specify` so it produces or updates `spec.md` only. - Wraps `/speckit.clarify` so it resolves requirement ambiguity in `spec.md` only. -- Treats Product Requirement + Design Requirement as the requirement inputs for `spec.md`; Figma is a Design Requirement provider, not a core SDD stage. -- When Design Requirement Intake or a Figma Evidence Packet has already been written into `spec.md`, `/speckit.clarify` clarifies design-derived gaps already written in `spec.md` and does not call Figma. +- Consumes confirmed product facts, external intake facts, visual SSOT refs, and evidence refs when projecting requirements into `spec.md`. +- When external intake evidence or visual SSOT refs have already been projected into `spec.md`, `/speckit.clarify` clarifies evidence-derived gaps already written in `spec.md` and does not call provider tools. - Wraps `/speckit.checklist` to add `checklists/behavior-testability.md` as a BDD readiness gate, NFR readiness gate, and applicable Visual Fidelity readiness gate. - Checks user stories, acceptance criteria, Given/When/Then readiness, roles, permissions, states, data, validation, boundary, exception, state_conflict behavior, and non-functional requirements directly from `spec.md`. - Adds a Case Coverage Matrix with one row per story or capability case type so positive, negative, boundary, permission, validation, and state_conflict cases are marked Required, Not Applicable, or Unknown before planning. -- Checks design-derived requirements for source traceability, provider readiness status, evidence refs, blockers, and visual fidelity scope before planning. -- Preserves stable Visual Item ID trace refs from provider evidence through Design Requirement Intake, `spec.md`, and the Visual Fidelity Evidence Matrix. +- Checks visual requirements for source traceability, external intake readiness status when cited, evidence refs, blockers, and visual fidelity scope before planning. +- Preserves stable visual SSOT refs and evidence refs through `spec.md` and the Visual Fidelity Evidence Matrix. - Records Client Asset Contract facts in `spec.md` for asset source strategy, required variants, fallback policy, and blocker status. - Requires NFR dimensions to be marked Required, Not Applicable, or Unknown in product language before planning. - Blocks planning when readiness gaps or missing or unverifiable NFR assumptions must return to `/speckit.clarify` or `/speckit.specify`. @@ -71,7 +71,7 @@ Planning capabilities: - Stores service, command, event, async, retry, rollback, and failure-path flows in `contracts/sequences.md`. - Records validation decisions in `research.md` and validation paths in `quickstart.md`. - When visual requirements are in scope, research.md records visual validation decisions, contracts formalize visual interaction and state constraints, and contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing. -- For visual restoration work, Visual Item IDs carry requirement traceability while Client Asset Contract entries carry local asset binding expectations. +- For visual restoration work, visual SSOT refs carry requirement traceability while Client Asset Contract entries carry local asset binding expectations. - Keeps product requirements in `spec.md`, domain facts in `data-model.md`, interface schemas in `contracts/`, and executable validation guidance in `quickstart.md`. Task generation capabilities: @@ -151,7 +151,7 @@ Context-load controls: Release install: ```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.11/spec-kit-workflow-preset-v1.3.11.zip +specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.10/spec-kit-workflow-preset-v1.3.10.zip ``` Local development install: @@ -174,29 +174,24 @@ Run the behavior-first workflow: /speckit.analyze ``` -### Design Requirement Input +### External Intake And Visual SSOT -The SDD requirement model is: +Source capture and provider-specific intake are owned by the separate `spec-kit-intake` +extension. Install or run that extension when PRD, design, provider design, rendered HTML, +or test-case evidence must be captured or validated before this preset projects +requirements. ```text -Product Requirement + Design Requirement -> Requirement Merge -> baseline spec.md +external intake evidence + visual SSOT refs -> /speckit.specify -> baseline spec.md ``` -Design Requirement Intake is provider-neutral. Figma is a Design Requirement -provider for the current toolchain; other providers can supply screenshots, -prototype documents, design-system documentation, or other design evidence. -Requirement Merge resolves Product Requirement and Design Requirement inputs -into `spec.md` while leaving unresolved conflicts as `[NEEDS CLARIFICATION]`. -For UI/UX restoration, provider evidence should preserve stable Visual Item ID -trace refs from frame/node evidence through Design Requirement Intake, `spec.md`, -and the Visual Fidelity Evidence Matrix. -`/speckit.specify` does not translate Figma variants into code props or decide -component reuse. It records observed states, requirement-level component roles, -and explicit use constraints only when the input evidence already states them. +`/speckit.specify` does not perform intake, call provider tools, parse HTML SSOT bundles, or decide provider source readiness. It consumes confirmed source-backed facts and preserves visual SSOT refs, evidence refs, state/viewport refs, +screenshots, visual proof refs, and Client Asset Contract facts in `spec.md`. +Product semantics implied only by provider evidence remain `[NEEDS CLARIFICATION]`. ### Screenshot Evidence -Screenshot is evidence, not intake. Screenshots are optional but strongly recommended provider evidence for UI work, and Design Requirement Intake only references them while recording structured design facts. +Screenshot is evidence, not intake. Screenshots are optional but strongly recommended visual evidence for UI work, and this preset only references them through `spec.md` visual requirements and evidence refs. In other words, screenshots are provider evidence and visual proof. L0-L3 screenshot evidence levels: @@ -217,33 +212,19 @@ The Visual Fidelity Evidence Matrix is the single visual readiness record; visua Provider evidence artifacts may record screenshot refs, proof refs, coverage gaps, and provider blockers as source facts, but only the Visual Fidelity Evidence Matrix decides visual planning readiness, proof sufficiency, accepted exception rules, Gate Status, and Blocking Items. Ordinary UI screenshots remain recommended unless `spec.md` declares visual proof required. -### Figma Provider Input +### Provider Design And HTML SSOT Input -Some runtime environments support direct Figma URL input when the runtime agent has Figma MCP access: +Use the `spec-kit-intake` extension for provider design or HTML SSOT capture: ```text -/speckit.specify +/speckit.intake.visual-design +/speckit.intake.html-ssot ``` -The preset does not extract from the URL. When the runtime agent or external -Figma intake has extracted provider evidence into a Figma Evidence Packet, the -preset can consume the qualified evidence before writing `spec.md`. The preset -defines the packet format, Design Requirement ownership rules, and Figma -provider source readiness contract; it does not provide Figma MCP connection, authentication, or execution. -The preset defines the required design intake and provider readiness artifact structure and ready gate; -the runtime agent or external Figma intake calls Figma MCP and writes -`figma-metadata.part-*.xml`, `figma-metadata.index.yaml`, and -`figma-node-inventory.yaml`. The preset consumes qualified evidence and does -not generate the artifact instances. -Figma-derived requirements are ready only when the packet records raw metadata -completeness, metadata index completeness proof, node inventory parity, and no -blocker lint errors. -For visual fidelity work, the external intake can additionally provide a -normalized `speckit.design.visual_item_matrix.v1` JSON artifact validated by -`schemas/speckit.design.visual-item-matrix.v1.schema.json`; this improves field -determinism for Visual Item IDs, variant/state evidence, explicit component use -constraints, screenshot refs, blockers, and spec targets without replacing raw -Figma evidence. +The intake extension owns source capture, provider evidence, raw provider metadata, +node inventory parity, rendered HTML visual SSOT bundles, source-side readiness, +and blocker codes. This preset consumes only the confirmed evidence refs written +or cited in `spec.md`. The Visual Fidelity Evidence Matrix remains the only planning readiness gate. Then run agent-native orchestrated implementation: @@ -273,12 +254,12 @@ This preset adds checklist artifacts: - `specs//checklists/behavior-testability.md` -Design requirement intake and provider artifact instances are written by the -runtime agent, external design intake, or provider-specific intake. The preset -defines their required structure and consumes the qualified evidence from -`spec.md` after `/speckit.specify` writes confirmed requirements or records -`[BLOCKED: PROVIDER_EVIDENCE]`; it does not generate the artifact instances. -Provider evidence blockers do not become `[NEEDS CLARIFICATION]`. +Source intake artifacts and provider artifact instances are written by +`spec-kit-intake` or another external intake extension. This preset consumes the +qualified evidence refs from `spec.md` after `/speckit.specify` writes confirmed +requirements or records `[BLOCKED: PROVIDER_EVIDENCE]`; it does not define or +generate the artifact instances. Provider evidence blockers do not become +`[NEEDS CLARIFICATION]`. This preset adds Phase 0 behavior artifacts: @@ -316,38 +297,23 @@ Contract files packaged by the preset: - `schemas/speckit.behavior.scenario-instances.v1.schema.json` - `schemas/speckit.behavior.data-fixtures.v1.schema.json` - `schemas/speckit.behavior.assertions.v1.schema.json` -- `schemas/speckit.design.visual-item-matrix.v1.schema.json` - `schemas/speckit.implement.manifest.v1.schema.json` - `schemas/speckit.implement.handoff.v2.schema.json` - `schemas/speckit.implement.receipt.v1.schema.json` -Governance and input evidence templates packaged by the preset: +Governance templates packaged by the preset: - `templates/constitution-template.md` -- `templates/design-requirement-intake-template.md` -- `templates/requirement-merge-report-template.md` -- `templates/figma-evidence-packet-template.md` -- `templates/figma-intake-contract.md` Development-only contract helpers: - `validators/speckit_implement_contract.py` -The validator helpers include a Design Requirement Intake trace check that rejects full provider Visual Item Matrix copies inside Visual Restoration Trace rows, keeping the trace requirement-facing and minimal. +Source intake templates, provider design contracts, visual requirements schemas, HTML SSOT bundle contracts, and source-side validators live in the `spec-kit-intake` extension. ## Artifact Roles -`checklists/behavior-testability.md` is the BDD, NFR, and applicable Visual Fidelity readiness gate. It checks `spec.md` before planning so behavior, NFRs, design-derived evidence, and product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements are ready for behavior projection and planning. Its Case Coverage Matrix uses one row per story or capability case type; rows mark Required, Not Applicable, or Unknown, cite source sections, and list Blocker IDs while Scenario IDs remain a `/speckit.plan` output. Its Visual Fidelity Evidence Matrix uses one row per visual requirement or visual proof obligation and is the single visual readiness record for source section, fidelity scope, screenshot level, evidence refs, visual proof requirement, blocking item ID, and exception rule. Missing Required case coverage, Unknown case applicability, or missing NFR criteria blocks planning when it affects downstream behavior projection or design. - -`templates/design-requirement-intake-template.md` defines the provider-neutral Design Requirement Intake shape for page inventory, hierarchy, user paths, component states, visual tokens, layout, responsive, motion, state coverage, visual acceptance requirements, Visual Restoration Trace rows, screenshot traceability, and traceability. - -`templates/requirement-merge-report-template.md` defines how Product Requirement and Design Requirement inputs are reconciled before baseline `spec.md` generation. It records merge rules, product-owned facts, design-owned facts, design requirement promotion rules, conflicts, clarification outputs, and the `spec.md` handoff. - -`templates/figma-evidence-packet-template.md` defines how Figma-derived provider evidence is normalized before Design Requirement Intake and `/speckit.specify` write requirements. It separates observed design facts, Visual Item Matrix rows, screenshot evidence, structural inferences, missing requirements, and excluded scope so Figma evidence does not get treated as complete product behavior. It references Figma provider source readiness contract results for raw metadata completeness, metadata index completeness proof, node inventory parity, and blocker lint errors before Figma-derived requirements can be treated as provider-ready. It does not decide visual planning readiness. - -`templates/figma-intake-contract.md` defines the raw Figma provider source readiness contract for `figma-metadata.part-*.xml`, `figma-metadata.index.yaml`, and `figma-node-inventory.yaml`. It owns raw metadata completeness, metadata index completeness proof, node inventory parity, blocker lint errors, and the ready gate; the Evidence Packet references those results as normalized provider input for `spec.md`. - -`schemas/speckit.design.visual-item-matrix.v1.schema.json` defines the normalized Visual Item Matrix JSON contract for machine-checkable UI/UX restoration intake. It validates field shape for visual item source refs, fidelity scope, observed variant/state evidence, explicit component/copy/drawing constraints, screenshot refs, visual proof level, blockers, and spec requirement targets while raw Figma evidence remains the source of truth. +`checklists/behavior-testability.md` is the BDD, NFR, and applicable Visual Fidelity readiness gate. It checks `spec.md` before planning so behavior, NFRs, visual SSOT refs, external evidence refs, and product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements are ready for behavior projection and planning. Its Case Coverage Matrix uses one row per story or capability case type; rows mark Required, Not Applicable, or Unknown, cite source sections, and list Blocker IDs while Scenario IDs remain a `/speckit.plan` output. Its Visual Fidelity Evidence Matrix uses one row per visual requirement or visual proof obligation and is the single visual readiness record for source section, fidelity scope, screenshot level, evidence refs, visual proof requirement, blocking item ID, and exception rule. Missing Required case coverage, Unknown case applicability, or missing NFR criteria blocks planning when it affects downstream behavior projection or design. `behavior/bdd.draft.feature` captures Phase 0 behavior projection in readable Given/When/Then form. `behavior/behavior-scenarios.draft.json`, `behavior/uif.intent.json`, and `behavior/data-fixtures.intent.json` make the same draft behavior machine-readable enough for planning formalization. @@ -361,7 +327,7 @@ For visual planning, research.md records visual validation decisions by Visual I Test strategy derivation happens during `/speckit.tasks`. The command derives unit, contract, integration, and end-to-end validation work from BDD contracts, Expected UIF contracts, behavior contracts, interface contracts, `research.md`, and `quickstart.md`, then writes the strategy inline on the relevant `tasks.md` checklist items. It also defines visual verification, contract validation, data-side-effect validation, integration/e2e validation, and scope-aware code review tasks in `tasks.md`; `/speckit.implement` executes those tasks and records receipt evidence without inventing validation strategy, changing requirements, updating contracts, or widening scope. -The handoff context digest includes relevant design constraints, visual fidelity requirements, screenshot refs, visual proof refs, Design Requirement trace refs, validation decisions, quickstart paths, and behavior contracts when present, so Worker Agents can preserve object boundaries, service flows, visual intent, and validation intent without reading full planning documents by default. +The handoff context digest includes relevant design constraints, visual fidelity requirements, screenshot refs, visual proof refs, visual SSOT refs, external evidence refs, validation decisions, quickstart paths, and behavior contracts when present, so Worker Agents can preserve object boundaries, service flows, visual intent, and validation intent without reading full planning documents by default. See `tests/contracts/speckit-cross-agent-subagents.md` for the cross-platform subagent mapping, worker prompt, parallel dispatch rules, and minimal handoff/receipt contract. @@ -479,7 +445,7 @@ Release install smoke validation is intentionally owned by GitHub Actions, not b After tagging a release, validate archive installation: ```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.11/spec-kit-workflow-preset-v1.3.11.zip +specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.10/spec-kit-workflow-preset-v1.3.10.zip ``` ## Source Rationale diff --git a/presets/workflow-preset/commands/speckit.checklist.md b/presets/workflow-preset/commands/speckit.checklist.md index eca3940db9..e3c7edf886 100644 --- a/presets/workflow-preset/commands/speckit.checklist.md +++ b/presets/workflow-preset/commands/speckit.checklist.md @@ -44,14 +44,16 @@ Check When readiness from `spec.md`: each trigger is an executable user action, Check Then readiness from `spec.md`: each outcome maps to feedback, business state, error semantics, or assertion intent. -Check Visual Fidelity Readiness when `spec.md` contains design-derived requirements, a design source, provider evidence blockers, or provider-specific design evidence requests. Also apply it when `spec.md` contains product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements. +Check Visual Fidelity Readiness when `spec.md` contains `Visual & UI Specification`, visual requirements, visual SSOT refs, external intake refs, provider evidence blockers, or provider-specific evidence requests. Also apply it when `spec.md` contains product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements. Use the behavior-testability checklist template as the visual gate authority. -Require source traceability, provider readiness status, evidence refs, and blockers, and clear visual requirements for state, responsive, accessibility, component mapping, and accepted exception coverage. -Build a Visual Fidelity Evidence Matrix with one row per visual requirement or visual proof obligation. Record Screenshot evidence level, declared visual proof required, provider evidence refs or screenshot refs, and any Gate Status: BLOCKED item in Blocking Items. +Check Visual/UI Coverage from `spec.md`: `Visual & UI Specification` exists when a visual or UI surface applies; otherwise `spec.md` records a Not Applicable rationale. Every identified visual/UI requirement must use status `Required`, `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`. +Require source traceability, external intake readiness status when cited, evidence refs, and blockers, and clear visual requirements for state, responsive, accessibility, component mapping, and accepted exception coverage. +Build a Visual Fidelity Evidence Matrix with one row per visual requirement or visual proof obligation. Record requirement status, Screenshot evidence level, declared visual proof required, visual SSOT refs, evidence refs, screenshot refs, and any Gate Status: BLOCKED item in Blocking Items. The Visual Fidelity Evidence Matrix alone decides visual planning readiness, proof level sufficiency, screenshot sufficiency, accepted exception rules, Gate Status, and Blocking Items. Use one Visual Fidelity Evidence Matrix as the single visual readiness record; do not duplicate visual evidence decisions outside the matrix and Blocking Items. -Read visual facts from `spec.md` and evidence refs; do not call Figma, re-extract Figma evidence, rebuild provider matrices, or create another visual readiness path. +Read visual facts from `spec.md` and evidence refs; do not call provider tools, re-extract external intake evidence, parse HTML SSOT bundles, rebuild provider matrices, or create another visual readiness path. Do not add historical visual rules or alternate visual decision paths. +Unknown visual/UI coverage status must appear in Blocking Items and block PASS when it affects downstream behavior projection or design. Required visual/UI requirements without observable requirement text block PASS. `[BLOCKED: PROVIDER_EVIDENCE]` items remain provider evidence blockers and return to the external intake extension. Responsive visual requirements block PASS only when they are complex, multi-state, or declare L2 or L3 visual proof; missing viewport-specific evidence then sets Gate Status: BLOCKED and lists the item in Blocking Items. Screenshots support visual facts but do not create product semantics. @@ -63,7 +65,7 @@ Treat these NFR readiness gaps as blocking items: Required but missing from `spe Set `Gate Status: PASS` only when every applicable readiness item is checked and `Blocking Items: none`. Otherwise set `Gate Status: BLOCKED` and list each unchecked readiness item that prevents behavior projection or downstream planning. -Unchecked readiness items that prevent behavior projection or downstream planning are blocking items. Do not proceed to `/speckit.plan`. Requirement ambiguity returns to `/speckit.clarify` or `/speckit.specify` to resolve missing requirements before planning. Provider evidence readiness blockers return to `/speckit.specify` or provider intake, not `/speckit.clarify`. +Unchecked readiness items that prevent behavior projection or downstream planning are blocking items. Do not proceed to `/speckit.plan`. Requirement ambiguity returns to `/speckit.clarify` or `/speckit.specify` to resolve missing requirements before planning. Provider evidence readiness blockers return to the external intake extension, not `/speckit.clarify`. {CORE_TEMPLATE} diff --git a/presets/workflow-preset/commands/speckit.clarify.md b/presets/workflow-preset/commands/speckit.clarify.md index dba2365bcf..74f0659f5f 100644 --- a/presets/workflow-preset/commands/speckit.clarify.md +++ b/presets/workflow-preset/commands/speckit.clarify.md @@ -7,7 +7,7 @@ strategy: wrap This wrapper must not redefine core-owned User Input, Pre-Execution Checks, extension hooks, base path resolution, or core file handling. -Use `spec.md` as the clarification source. Ask and record clarification only for requirement ambiguity that affects product behavior, constraints, non-functional requirement assumptions, acceptance criteria, user roles, permissions, entity states, data semantics, exceptions, validation rules, or boundaries. +Use `spec.md` as the clarification source. Ask and record clarification only for requirement ambiguity that affects product behavior, constraints, non-functional requirement assumptions, visual/UI requirement coverage status, acceptance criteria, user roles, permissions, entity states, data semantics, exceptions, validation rules, or boundaries. Do not read or update behavior draft artifacts. Do not use behavior drafts as clarification inputs, and do not open a separate behavior-question channel. Product requirements stay in `spec.md`; update `spec.md` only after user-provided answers make the requirement clear. @@ -23,24 +23,25 @@ Load the active `spec.md` through the core command. Official hooks still apply: ## Design Requirement Clarification Strategy -When `spec.md` was created from Design Requirement Intake or provider-specific evidence such as a Figma Evidence Packet, prioritize clarification questions for design-derived gaps already written in `spec.md`. Scan `spec.md` first for `Missing / Needs Clarification`, `[NEEDS CLARIFICATION]`, `Inferred from Structure`, and gaps about provider-unprovided states, responsive behavior, business rules, permissions, and error handling. +When `spec.md` was created from external intake evidence or visual SSOT refs, prioritize clarification questions for evidence-derived gaps already written in `spec.md`. Scan `spec.md` first for `[NEEDS CLARIFICATION]`, visual/UI coverage status `Unknown`, and gaps about provider-unprovided states, responsive behavior, business rules, permissions, and error handling. -Do not call Figma MCP. Do not re-extract design facts, re-parse Figma links, or turn clarification into a Figma extraction step. `/speckit.specify` owns writing qualified evidence-backed design-derived requirements and trace refs into `spec.md`; it does not write raw Figma evidence into `spec.md`. `/speckit.clarify` only selects high-impact questions from existing `spec.md` gaps and records confirmed answers. Do not ask the user to fix provider extraction artifacts. +Do not call provider tools. Do not re-extract design facts, re-parse provider design links, parse HTML SSOT bundles, or turn clarification into an intake step. External intake owns source capture and provider readiness; `/speckit.specify` only projects confirmed evidence-backed requirements and trace refs into `spec.md`. `/speckit.clarify` only selects high-impact questions from existing `spec.md` gaps and records confirmed answers. Do not ask the user to fix provider extraction artifacts. Ask at most 5 high-impact questions whose answers materially affect requirements, implementation planning, or validation readiness. Maximum of 5 total questions. Present EXACTLY ONE question at a time. Do NOT output them all at once. Never reveal future queued questions. Format recommendations as `**Recommended:** Option [X] - ` when a discrete 2-5 option choice is available. Keep the rationale short and decision-focused. For short-answer gaps, use `Suggested` and constrain answers to `<=5 words`. Accept `yes`, `recommended`, or `suggested` as approval of the shown recommendation. Question selection order: -1. Required frames, states, and breakpoints for acceptance. -2. visual fidelity scope: pixel-perfect, design-system faithful, or functional equivalent. -3. missing UI states such as loading, empty, error, disabled, hover, and focus. -4. responsive behavior, scrolling, safe areas, and long-copy handling. -5. required component reuse constraints explicitly stated in `spec.md`. -6. data semantics for mock copy, API-backed copy, and interface-driven values. -7. Prototype-uncovered navigation, dialogs, recovery paths, and failure handling. -8. acceptance evidence, visual-difference tolerance, and exception approval flow. +1. Visual/UI coverage status: Required, Not Applicable, Unknown, or `[BLOCKED: PROVIDER_EVIDENCE]`. +2. Required frames, states, and breakpoints for acceptance. +3. visual fidelity scope: pixel-perfect, design-system faithful, or functional equivalent. +4. missing UI states such as loading, empty, error, disabled, hover, and focus. +5. responsive behavior, scrolling, safe areas, and long-copy handling. +6. required component reuse constraints explicitly stated in `spec.md`. +7. data semantics for mock copy, API-backed copy, and interface-driven values. +8. Prototype-uncovered navigation, dialogs, recovery paths, and failure handling. +9. acceptance evidence, visual-difference tolerance, and exception approval flow. -After each accepted answer, write confirmed answers back into `spec.md` in the relevant Requirements, User Scenarios, Acceptance Criteria, Assumptions, Open Questions, or visual/responsive/state sections. Ensure `## Clarifications`, `### Session YYYY-MM-DD`, and one `- Q: ... -> A: ...` bullet exist for the session. Save `spec.md` after each accepted answer. Do not create a separate Figma clarification document. +After each accepted answer, write confirmed answers back into `spec.md` in the relevant Requirements, User Scenarios, Acceptance Criteria, Assumptions, Open Questions, or Visual & UI Specification, visual/responsive/state sections. Update affected visual/UI coverage status when the answer resolves an `Unknown` item. Ensure `## Clarifications`, `### Session YYYY-MM-DD`, and one `- Q: ... -> A: ...` bullet exist for the session. Save `spec.md` after each accepted answer. Do not create a separate provider-specific clarification document. Do not generate visual restoration checklists. Clarification fills requirement gaps in `spec.md`; `/speckit.checklist` remains responsible for checking requirement text quality and readiness. @@ -60,5 +61,6 @@ Before finishing, report answered questions, `spec.md` sections updated, and any - [ ] No more than 5 high-impact questions were asked. - [ ] Each accepted answer was written back to `spec.md`. +- [ ] Any answered visual/UI coverage status was updated in `spec.md`. - [ ] Validation after each write found no duplicate or contradictory clarification. - [ ] Completion reported with sections touched and remaining blockers. diff --git a/presets/workflow-preset/commands/speckit.implement.md b/presets/workflow-preset/commands/speckit.implement.md index 877990abd9..b3a6a9d9f0 100644 --- a/presets/workflow-preset/commands/speckit.implement.md +++ b/presets/workflow-preset/commands/speckit.implement.md @@ -1,57 +1,57 @@ --- -description: Run agent-native implement orchestration or execute one worker handoff. +description: Run implement orchestration. --- ## Input -```text -$ARGUMENTS -``` -Optional runtime hint: `agent-runtime=`. +`$ARGUMENTS`; runtime hint: `agent-runtime=`. ## Mode - Core mode: no handoff JSON path in `$ARGUMENTS`. - Worker mode: `.json` handoff path in `$ARGUMENTS` or `Use handoff JSON `. -- Forbidden: external dispatch scripts, workflow runners, inline worker execution. +- Forbidden: dispatch scripts, workflow runners, inline worker execution. ## Authority -- Core Agent is the orchestrator: build `context-index.json`, assemble `handoff-manifest.json`, - dispatch isolated runs, review receipts, update `tasks.md` only during task commit, - and run integration verification. -- Vertical Planner Agent is the capability planner: plan exactly one `vertical_capability`, - produce shard plans plus handoff/context digest drafts, and never execute implementation - or write the final manifest. -- Worker Agent is the handoff executor: execute exactly one handoff and never edit `tasks.md`, - create handoffs, or dispatch workers. +- Core Agent: build `context-index.json` and `handoff-manifest.json`; dispatch, review receipts. +- Core Agent updates `tasks.md` during task commit and runs integration verification. +- Vertical Planner Agent: plan one `vertical_capability`, draft shard plans plus handoff/context digests, never execute. +- Worker Agent: execute exactly one handoff; never edit `tasks.md`, create handoffs, or dispatch workers. ## Core Agent -- Follow the lifecycle and runtime isolation contract in `tests/contracts/speckit-cross-agent-subagents.md`. -- Map planned `U` design objects to concrete source, test, fixture, configuration, - and receipt paths before worker execution. -- Use `isolated_subagent` only when the runtime provides isolated subagent/subsession execution. -- Otherwise use manifest `execution_mode: manual_fresh_worker_session`. +- Follow `tests/contracts/speckit-cross-agent-subagents.md`. +- Map planned `U` design objects to concrete source, test, fixture, configuration, and receipt paths. +- Use `isolated_subagent` only with isolated subagent/subsession execution; otherwise use `manual_fresh_worker_session`. - If isolation is unavailable or unknown, write the manifest and handoffs, then stop with Worker-mode instructions. - Consume planner outputs and worker receipts, not worker conversation history. +## Visual Implementation Boundary +- Execute only incomplete `tasks.md` visual items; preserve the `/speckit.tasks` visual task input filter. +- Visual Fidelity Readiness `Requirement Status` is `Required` or `Required` plus an accepted exception. +- Accepted exceptions cite the exception rule in task text, context digest, and receipt evidence. +- Do not create handoffs or worker instructions for visual rows with `Requirement Status` `Not Applicable`, + `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`. +- Route `Unknown` visual rows back to `/speckit.clarify`; + route `[BLOCKED: PROVIDER_EVIDENCE]` visual rows to the external intake extension. +- `/speckit.implement` must not discover visual requirements, repair Visual Fidelity Readiness evidence, + or edit upstream artifacts to make visual work executable. +- Visual worker receipts must reference the relevant Visual Item ID, `Requirement Status`, and evidence refs. ## Vertical Planner Agent - Read only `tasks.md`, `context-index.json`, and allowed planning artifacts. - Preserve `tasks.md` order, lifecycle dependencies, capability boundaries, and Change Scope Granularity. -- Put unresolved shard, context, asset binding, or path ambiguity into `context_gaps`. +- Put unresolved shard, context, asset binding, path, visual status, evidence, asset, or fallback gaps + into `context_gaps`. - Emit drafts that validate against the handoff schema before Core assembly. ## Worker Agent - Reject non-existent handoff paths. - Reject handoffs not listed in `handoff-manifest.json`. -- Verify `contract_type` is `speckit.implement.handoff.v2`. -- Load `context_digest_path` before editing. -- Stop before editing when `context_gaps` is not empty. -- Execute only `task_ids`. -- Read only `allowed_read_paths`. -- Write only `allowed_write_paths`. +- Verify `contract_type` is `speckit.implement.handoff.v2`; load `context_digest_path`; stop on `context_gaps`. +- Execute only `task_ids`; read only `allowed_read_paths`; write only `allowed_write_paths`. - Write `task_status_update.receipt_path` as `speckit.implement.receipt.v1`. +- For visual handoffs, validate assigned task text; use empty `completed_task_ids` when visual evidence is unavailable. - Do not edit `tasks.md`. ## Contract References -- Runtime, shard, context digest, path, asset binding, dispatch, Worker Prompt, - and review receipt rules: `tests/contracts/speckit-cross-agent-subagents.md`. -- Manifest schema: `schemas/speckit.implement.manifest.v1.schema.json`. -- Handoff schema: `schemas/speckit.implement.handoff.v2.schema.json`. -- Receipt schema: `schemas/speckit.implement.receipt.v1.schema.json`. +- Runtime, shard, digest, path, asset binding, dispatch, Worker Prompt, receipt rules: + `tests/contracts/speckit-cross-agent-subagents.md`. +- Schemas: `schemas/speckit.implement.manifest.v1.schema.json`, + `schemas/speckit.implement.handoff.v2.schema.json`, + `schemas/speckit.implement.receipt.v1.schema.json`. - Cross-field validation: `validators/speckit_implement_contract.py`. ## Runtime Stops - Stop on missing handoff files, unlisted handoffs, non-empty `context_gaps`, schema mismatch, - write paths outside `allowed_write_paths`, or attempts to update planning artifacts from Worker mode. + writes outside `allowed_write_paths`, or planning artifact updates. - Stop instead of inventing validation strategy, adding lifecycle roles, changing requirements, - updating contracts, widening scope, or adding standalone validation planning artifacts. + updating contracts, widening scope, or adding validation planning artifacts. diff --git a/presets/workflow-preset/commands/speckit.plan.md b/presets/workflow-preset/commands/speckit.plan.md index 1427eb7870..23e69e8442 100644 --- a/presets/workflow-preset/commands/speckit.plan.md +++ b/presets/workflow-preset/commands/speckit.plan.md @@ -85,13 +85,15 @@ When `plan.md` has a design artifact/navigation section, include links to: - Interface contracts: `./contracts/` - Validation path: `./quickstart.md` -When visual requirements are in scope, keep `plan.md` navigation linked to visual fidelity scope, screenshot refs, visual proof refs, and Design Requirement trace refs already accepted by `spec.md` and the readiness checklist. +When visual requirements are in scope, keep `plan.md` navigation linked to visual fidelity scope, screenshot refs, visual proof refs, and external visual SSOT refs already accepted by `spec.md` and the readiness checklist. ## Visual Planning Responsibilities -When visual requirements are in scope, planning must keep the Visual Fidelity Evidence Matrix as the upstream readiness record and split visual carry-forward across the existing planning outputs: +When visual requirements are in scope, planning must keep the Visual Fidelity Evidence Matrix as the upstream readiness record and split visual carry-forward across the existing planning outputs. -- `research.md`: add Visual validation decisions for each relevant Visual Item ID. Record selected test level, fixture or asset strategy, viewport/state coverage strategy, visual regression or baseline proof strategy, screenshot refs, visual proof refs, Design Requirement trace refs, related quickstart validation path, and related UIF or behavior contract path. Do not copy the Visual Fidelity Evidence Matrix into `research.md`, do not create new visual requirements, do not call Figma or other provider tools, and do not rebuild provider evidence matrices. +Use the Visual Fidelity Evidence Matrix `Requirement Status` as the visual planning input filter. Carry forward only visual rows with status `Required` or an accepted exception rule. Rows with status `Unknown` or `[BLOCKED: PROVIDER_EVIDENCE]` must already have blocked checklist PASS; if encountered during planning, stop with a report-only/no-write upstream gate failure and return to `/speckit.checklist`, `/speckit.clarify`, or the external intake extension as appropriate. Do not project `Not Applicable` rows into visual planning outputs. + +- `research.md`: add Visual validation decisions for each relevant Visual Item ID or visual SSOT ref. Record selected test level, fixture or asset strategy, viewport/state coverage strategy, visual regression or baseline proof strategy, screenshot refs, visual proof refs, external evidence refs, related quickstart validation path, and related UIF or behavior contract path. Do not copy the Visual Fidelity Evidence Matrix into `research.md`, do not create new visual requirements, do not call provider tools, do not rebuild external intake evidence, and do not rebuild provider evidence matrices. - `contracts/uif/` and `contracts/behavior/`: formalize accepted visual interaction and state constraints only when they affect observable behavior. Expected UIF contracts may carry visual_item_refs, viewport_matrix_refs, state_matrix_refs, visual_proof_refs, and accepted_exception_refs. Behavior contracts may reference visual assertion IDs or blockers when a visual state cannot be formalized without inventing requirements. Interface contracts in `contracts/` may model only API or data fields needed to support UI states, assets, or feedback; they must not contain layout rules or screenshot proof decisions. - `contracts/sequences.md`: add UI interaction sequence, visual state handoff points, responsive branch trigger refs, and visual proof references only when visual states affect cross-boundary order, async callbacks, retries, rollback, compensation, or error propagation. Keep visual style, tokens, layout breakpoints, screenshot matrices, and validation commands out of `contracts/sequences.md`. diff --git a/presets/workflow-preset/commands/speckit.specify.md b/presets/workflow-preset/commands/speckit.specify.md index 574e714574..47562690e0 100644 --- a/presets/workflow-preset/commands/speckit.specify.md +++ b/presets/workflow-preset/commands/speckit.specify.md @@ -7,45 +7,36 @@ strategy: wrap This wrapper must not redefine core-owned User Input, Pre-Execution Checks, extension hooks, base path resolution, or core file handling. Preset-added requirement output writes only `spec.md`. -Product requirements stay in `spec.md`: user stories, acceptance criteria, functional requirements, non-functional requirements, constraints, assumptions, and any clarification markers required by the core template. +Product requirements stay in `spec.md`: user stories, acceptance criteria, functional requirements, non-functional requirements, visual and UI requirements, constraints, assumptions, and any clarification markers required by the core template. Keep requirement text implementation-agnostic and scoped to product behavior. Non-functional requirements must be explicit product-level assumptions or constraints, including no-special-requirement or not-applicable statements when that is the confirmed requirement. ## Wrapper Input Additions -Treat product notes, PRDs, user prompts, design evidence, provider source packets, screenshots, visual proof, and source refs as input to the same feature description. If the core feature description is empty, follow the core command error path. +Treat product notes, PRDs, user prompts, confirmed external intake facts, visual SSOT refs, evidence refs, screenshots, and visual proof refs as input to the same feature description. If the core feature description is empty, follow the core command error path. + +Treat confirmed Visual Asset Registry refs as external source artifact inputs only. They describe visual media inventory such as icons, images, illustrations, fonts, motion, video, textures, source refs, variants, license status, fallback policy, and blocker status. ## Wrapper Preflight Additions -Before writing design-derived requirements, check whether provider evidence is ready. This preset consumes qualified provider evidence; it does not call Figma MCP and does not generate provider artifact instances. +Before writing evidence-derived requirements, consume only confirmed external intake facts or explicit user-provided requirement text. This preset does not perform intake, call provider tools, parse HTML bundles, decide provider source readiness, or generate provider artifact instances. -For Figma-derived evidence, require a ready Figma Evidence Packet and Figma provider source readiness contract: raw metadata completeness, metadata index completeness proof, node inventory parity, and no blocker lint errors. If evidence is not ready, write explicit non-design requirements only and record Provider evidence readiness blockers as `[BLOCKED: PROVIDER_EVIDENCE]`; provider blockers must not become product `[NEEDS CLARIFICATION]` items. +If external intake or visual SSOT evidence is missing or blocked, write explicit non-evidence requirements only and record source readiness blockers as `[BLOCKED: PROVIDER_EVIDENCE]`; provider blockers must not become product `[NEEDS CLARIFICATION]` items. ## Wrapper Outline Additions -Design Requirement Input Policy: run specification as staged intake and merge work without changing this command's write scope: - -### Stage 0: Product Requirement Intake -Product intake input: PRD, user prompt, product notes, and explicit product constraints. Product intake output: product-owned requirement facts in `spec.md`, including stories, functional requirements, non-functional requirements, assumptions, and product `[NEEDS CLARIFICATION]` markers. +Specification Projection Policy: write one implementation-agnostic `spec.md` from confirmed product facts, explicit product constraints, and source-backed external intake facts. -### Stage 1: Design Requirement Intake -Design intake input: provider-neutral design evidence, provider source packets, screenshots, visual proof, and source refs. Design intake output: evidence-backed design facts recorded only in `spec.md`, including stable Visual Item ID trace refs, observed variant/state facts, and Client Asset Contract facts: source refs, asset source strategy, required variants, fallback policy, and blocker status. +When visual or UI requirements apply, write a `Visual & UI Specification` section inside `spec.md` for observable visual and UI requirements only. When no visual or UI surface applies, record a Not Applicable rationale in `spec.md`. -If the design source is a Figma URL and a ready packet is supplied by a runtime agent or external Figma intake that has Figma MCP access: +Every identified visual or UI requirement must be recorded with status `Required`, `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`; do not silently omit low-evidence visual or UI requirements. -- Require a ready Figma Evidence Packet before writing design-derived requirements. -- Use the Figma provider source readiness contract; the preset defines the required design intake and provider readiness artifact structure and ready gate. -- Treat the runtime agent or external Figma intake as the source of artifact instances; this command consumes qualified evidence, does not call Figma MCP, and does not generate the artifact instances. -- If the packet is not ready, do not write design-derived requirements from that evidence. Write only explicit non-design requirements and record Provider evidence readiness blockers as `[BLOCKED: PROVIDER_EVIDENCE]`. +For visual requirements, preserve visual SSOT refs, evidence refs, state and viewport refs, visual proof refs, and Client Asset Contract facts: source refs, asset source strategy, required variants, fallback policy, and blocker status. -Use `Observed from Figma` as design evidence. Treat `Inferred from Structure`, `Missing / Needs Clarification`, and `Out of Scope` as interpretation, unresolved requirements, and excluded evidence respectively. -Screenshots support visual facts only; screenshots must not create product semantics. Screenshot-implied business rules stay `[NEEDS CLARIFICATION]`. -Do not invent code props, code state names, component reuse decisions, self-drawing bans, or copy restrictions from Figma structure. Record component use, no-self-draw, and no-new-copy constraints only when product input or qualified provider evidence states them explicitly. +Promote only source-backed visual, layout, state, interaction, responsive, accessibility, and acceptance facts with source refs. Product semantics implied only by provider evidence stay `[NEEDS CLARIFICATION]`. -If Figma MCP access is unavailable, Continue to write only `spec.md` and record `[BLOCKED: PROVIDER_EVIDENCE]` for the missing Figma Evidence Packet, screenshots, or design facts. +Treat Component State Matrix content as Visual & UI Specification requirements, not visual assets. Record observable states, visual feedback, and interaction outcomes; do not turn them into framework component names or implementation contracts. -### Stage 2: Requirement Merge -Merge input: product facts from Stage 0 plus qualified design facts from Stage 1. Merge output: confirmed baseline requirements, conflicts, assumptions, clarification markers, and provider blockers recorded in `spec.md`. Apply Design Requirement Promotion Rules: promote only evidence-backed visual, layout, state, interaction, responsive, accessibility, and acceptance facts with source refs; preserve Visual Item ID trace refs for visual requirements. Product semantics implied only by provider evidence stay `[NEEDS CLARIFICATION]`. +Do not invent code props, code state names, component reuse decisions, self-drawing bans, copy restrictions, DOM structure, CSS selectors, component props, generated code organization, asset binding, or packaging strategy from external visual evidence. -### Stage 3: Generate baseline spec.md -Baseline spec output: one implementation-agnostic `spec.md` contract containing confirmed product requirements, qualified design-derived requirements, source refs, `[NEEDS CLARIFICATION]`, and `[BLOCKED: PROVIDER_EVIDENCE]` items. +When visual SSOT refs are blocked or unavailable, keep explicit visual or UI requirement coverage in `spec.md`, mark evidence-derived coverage as `[BLOCKED: PROVIDER_EVIDENCE]`, and do not invent missing visual facts. ## Official Style Alignment Focus on WHAT users need and WHY. Avoid HOW to implement. Limit [NEEDS CLARIFICATION] markers to the highest-impact unresolved product decisions; record low-impact gaps in Assumptions and provider readiness gaps as `[BLOCKED: PROVIDER_EVIDENCE]`. @@ -56,10 +47,11 @@ Validate that requirement text is stakeholder-readable, testable, implementation {CORE_TEMPLATE} ## Completion Report -Before finishing, provide a stage-wise report and report the `spec.md` sections created or updated, confirmed requirements, provider blockers, and unresolved requirement ambiguities. +Before finishing, report the `spec.md` sections created or updated, confirmed requirements, visual SSOT refs preserved, provider blockers, and unresolved requirement ambiguities. ## Done When -- [ ] Stage 0-3 intake and merge decisions are reflected in `spec.md`. +- [ ] Confirmed requirement facts, visual SSOT refs, and applicable Client Asset Contract facts are reflected in `spec.md`. +- [ ] Functional, non-functional, and visual/UI requirement coverage is present or explicitly marked Not Applicable, Unknown, or `[BLOCKED: PROVIDER_EVIDENCE]`. - [ ] Product `[NEEDS CLARIFICATION]` markers are limited to high-impact unresolved decisions. - [ ] Provider readiness blockers remain `[BLOCKED: PROVIDER_EVIDENCE]`. - [ ] Completion reported with updated `spec.md` sections and remaining blockers. diff --git a/presets/workflow-preset/commands/speckit.tasks.md b/presets/workflow-preset/commands/speckit.tasks.md index 91e14fb944..380183dd8c 100644 --- a/presets/workflow-preset/commands/speckit.tasks.md +++ b/presets/workflow-preset/commands/speckit.tasks.md @@ -15,9 +15,9 @@ If any listed file exists under FEATURE_DIR, task generation must consume it as - `contracts/sequences.md`: service, command, event, async, retry, rollback, and failure-path flows. - `research.md`: selected validation level, fixture strategy, external-system execution mode, and error-branch validation decisions. - `quickstart.md`: executable validation paths and evidence collection guidance. -- `spec.md` visual acceptance requirements: visual fidelity requirements, screenshot refs, visual proof refs, and Design Requirement trace refs. +- `spec.md` visual acceptance requirements: visual fidelity requirements, screenshot refs, visual proof refs, visual SSOT refs, and external evidence refs. - `spec.md` Client Asset Contract: asset source strategy, required variants, fallback policy, and blocker status. -- `checklists/behavior-testability.md` Visual Fidelity Readiness: passed visual proof level, blockers, and accepted exceptions. +- `checklists/behavior-testability.md` Visual Fidelity Readiness: `Requirement Status`, passed visual proof level, blockers, and accepted exceptions. - `contracts/bdd/`: formal BDD acceptance contracts. - `contracts/uif/`: Expected UIF interaction contracts. - `contracts/behavior/`: formal scenario instance, fixture, and assertion contracts. @@ -29,7 +29,9 @@ Use these inputs to derive implementation, integration, orchestration, failure-h For Client Asset Contract entries, derive asset preparation, binding, implementation, and validation tasks in dependency order. Missing required client visual assets are readiness blockers. -Use Visual Fidelity Readiness as the only visual planning readiness source. Do not create a second readiness rule from Screenshot Coverage Matrix, Visual Item Matrix, Visual Restoration Trace, or provider evidence artifacts; if required visual evidence is missing, report a readiness blocker instead of deriving complete-looking UI tasks. +Use Visual Fidelity Readiness as the only visual planning readiness source. Do not create a second readiness rule from screenshot coverage, external intake artifacts, HTML SSOT bundles, or provider evidence artifacts; if required visual evidence is missing, report a readiness blocker instead of deriving complete-looking UI tasks. + +Use each Visual Fidelity Readiness row's `Requirement Status` as the visual task input filter. Generate visual tasks only for rows with status `Required` or `Required` plus an accepted exception; tasks for accepted exceptions must cite the exception rule. Do not generate implementation, validation, verification, evidence, asset binding, UI acceptance, or review tasks for `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]` rows. Route `Unknown` rows back to `/speckit.clarify`; route `[BLOCKED: PROVIDER_EVIDENCE]` rows to the external intake extension. `/speckit.tasks` must not discover visual requirements or repair evidence; it only decomposes visual specifications that already passed the readiness gate. Missing Required case coverage is a coverage blocker, not silently skipped work. If `checklists/behavior-testability.md` marks a case type Required but the matching BDD or behavior contract is absent and no `Not Applicable` rationale or `case_coverage_blockers` entry exists, report the missing case instead of generating a complete-looking task list. @@ -71,16 +73,24 @@ Behavior traceability must be explicit: - For each Expected UIF contract step with type `api_call`, create the backend/API or contract task that provides the declared method and path. - For each quickstart validation path, create a validation task that can collect evidence for the relevant scenario IDs and assertions. -Use this visual task taxonomy when a user story includes `contracts/uif/`, visual acceptance requirements, Visual Fidelity Readiness rows, or Client Asset Contract entries: - -- Maintain story-local task granularity: `visual_setup` -> `visual_validation` -> `visual_implementation` -> `visual_evidence`. Do not create a separate visual lifecycle phase. -- `visual_setup`, `visual_validation`, `visual_implementation`, and `visual_evidence` tasks may cover visual fixtures, client assets, viewport/state setup, concrete components, views, interaction paths, visual items, asset variants, fallback behavior, screenshot refs, visual proof refs, command output, or visual diff results. +Use only this visual task taxonomy when a user story includes `contracts/uif/`, visual acceptance requirements, Visual Fidelity Readiness rows, or Client Asset Contract entries: + +- Maintain story-local task granularity: `visual_setup` -> `visual_validation` -> `visual_implementation` -> `visual_evidence` -> `final_visual_review`. Do not create a separate visual lifecycle phase. +- `visual_setup`: prepare visual fixtures, viewport configuration, screenshot baseline paths, client resource setup, asset variants, fallback policy mapping, and other visual validation prerequisites. +- `visual_validation`: create or configure the validation path before implementation, including visual regression tests, UI acceptance checks, screenshot comparison, state or viewport coverage validation, and accessibility check entrypoints. +- `visual_implementation`: implement the visual or UI behavior, including page or component states, interaction feedback, responsive layout, asset binding, empty/error/loading/disabled/hover/focus states, and fallback behavior. +- `visual_evidence`: collect delivery evidence, including screenshot refs, visual proof refs, command output, visual diff results, and quickstart validation evidence. +- `ui_acceptance`: verify a user-facing UIF path or BDD scenario, including user action, feedback, page state, and visible result. +- `visual_verification`: verify visual-spec fidelity by Visual Item ID, `Requirement Status`, viewport/state coverage, proof level, screenshot refs, and visual proof refs. +- `asset_binding`: when a Client Asset Contract applies, bind source assets, variants, license or authorization refs, fallback policy, code paths, and missing-asset blockers. +- `final_visual_review`: require final review of implemented UI states, viewport behavior, Visual Fidelity Readiness rows, UIF paths, screenshot refs, visual proof refs, and Client Asset Contract bindings without changing `spec.md`, contracts, readiness checklists, or planning artifacts. +- `visual_setup`, `visual_validation`, `visual_implementation`, `visual_evidence`, `ui_acceptance`, `visual_verification`, `asset_binding`, and `final_visual_review` are the only visual task types. - Visual tasks must name concrete source, test, fixture, configuration, or asset paths when derivable; otherwise report a readiness blocker instead of generating an ambiguous visual task. - UI acceptance tasks must verify the same UIF path, Visual Item ID, scenario ID, asset contract entry, or quickstart validation path as the implementation task, including required state and viewport coverage when responsive visual behavior is in scope. - UI acceptance evidence must reference at least one relevant UIF path, BDD or behavior scenario, visual proof ref, screenshot ref, quickstart validation path, API contract, or captured command output. - Missing visual proof refs, screenshot refs, viewport/state coverage, Client Asset Contract entries, asset variants, or fallback policy are Visual Fidelity Readiness blockers. -For each applicable Visual Fidelity Readiness row, generate a paired visual verification or UI acceptance task unless the row is Not Applicable or blocked. +For each applicable Visual Fidelity Readiness row with `Requirement Status` `Required` or `Required` plus an accepted exception, generate paired `visual_validation` and `visual_evidence` work; use `ui_acceptance` or `visual_verification` as concrete validation or evidence task types when they best match the UIF path, BDD scenario, or visual item. Do not generate visual tasks for rows with `Requirement Status` `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`. When an implementation task depends on `contracts/`, include a paired contract validation task that names the contract ref, expected implementation surface, validation command or quickstart path, and evidence requirement. Do not instruct implementers to modify `spec.md`, `contracts/`, readiness checklists, or Visual Fidelity Readiness to make implementation pass; report a blocker if implementation requires requirement or contract changes. diff --git a/presets/workflow-preset/docs/extension-governance.md b/presets/workflow-preset/docs/extension-governance.md index 6e2995f5bb..a313cb4943 100644 --- a/presets/workflow-preset/docs/extension-governance.md +++ b/presets/workflow-preset/docs/extension-governance.md @@ -1,11 +1,9 @@ # Preset Extension Governance - This document is the repository-level rule set for extending `workflow-preset`. It exists to keep preset changes aligned with Spec Kit's preset model and this repository's contract tests. ## Source Of Truth - - `preset.yml` declares every packaged command, template, schema, and script. - `commands/` contains stage-local LLM instructions. - `templates/` contains stable artifact shapes. @@ -23,15 +21,14 @@ a new capability outside the existing Spec Kit workflow. Do not reintroduce Python orchestration, workflow shell dispatch, integration adapter scripts, or worker dispatch from scripts. -Evidence templates: packaged evidence templates are allowed preset artifacts. -Intake contract templates are also allowed when they define input shape, -completeness gates, and blocker lint rules without executing an external system. -Design Requirement Intake and Requirement Merge templates may define -provider-neutral design facts and merge reports. Figma is a provider-specific design source; -Screenshot is provider evidence and visual proof. -Screenshots must not become the primary Design Requirement Intake carrier or a source of product semantics. -Provider evidence artifacts may record screenshot refs, visual proof refs, coverage gaps, and provider evidence blockers as source facts. They must not decide visual planning readiness, proof sufficiency, accepted exception rules, checklist Gate Status, or checklist Blocking Items. -Figma MCP execution, hooks, adapter scripts, and authentication are external integration concerns and remain outside this preset. +Source intake artifacts belong in an extension, not this preset. External intake owns source capture, provider evidence, provider metadata, rendered HTML SSOT bundles, +source-side readiness, and blocker codes. This preset may consume confirmed +external intake refs, visual SSOT refs, screenshot refs, visual proof refs, +coverage gaps, and provider blockers already cited in `spec.md`. +External evidence refs must not decide visual planning readiness, proof sufficiency, accepted exception rules, checklist Gate Status, or checklist +Blocking Items. Provider tools, provider execution, hooks, adapter scripts, +and authentication are external integration concerns and remain outside this +preset. ## Template And Command Ownership @@ -56,10 +53,10 @@ Stage ownership: `/speckit.tasks` owns implementation, validation, visual verification, contract validation, data-side-effect validation, integration/e2e validation, and code review task definition in `tasks.md`. `/speckit.implement` may execute those tasks and record receipt evidence, but it must not invent validation strategy, add lifecycle roles, change requirements, update contracts, or widen scope during execution. -When Design Requirement Intake or a Figma Evidence Packet has already been written into `spec.md`, `/speckit.clarify` may clarify those requirement gaps from `spec.md`, but extraction remains outside clarification. -external design extraction is not a clarification responsibility. +When external intake evidence or visual SSOT refs have already been projected into `spec.md`, `/speckit.clarify` may clarify those requirement gaps from `spec.md`, but extraction remains outside clarification. +External design extraction is not a clarification responsibility. -Visual Fidelity readiness applies to design-derived and product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements. The Visual Fidelity Evidence Matrix is the single visual readiness record and uses one row per visual requirement or visual proof obligation with Source `spec.md` section, Fidelity Scope, Screenshot Level, Evidence Refs, Visual Proof Required, Blocking Item ID, and Exception Rule. It is the only artifact that decides visual planning readiness, visual proof level sufficiency, screenshot sufficiency, accepted exception rules, checklist Gate Status, and checklist Blocking Items. Provider source readiness remains separate: provider intake may prove raw metadata completeness, metadata index completeness proof, node inventory parity, and blocker lint errors, but that proof is not the Visual Fidelity readiness gate. Responsive visual requirements block PASS only when they are complex, multi-state, or declare L2 or L3 visual proof. +Visual Fidelity readiness applies to external-intake-derived and product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements. The Visual Fidelity Evidence Matrix is the single visual readiness record and uses one row per visual requirement or visual proof obligation with Source `spec.md` section, Fidelity Scope, Screenshot Level, Evidence Refs, Visual Proof Required, Blocking Item ID, and Exception Rule. It is the only artifact that decides visual planning readiness, visual proof level sufficiency, screenshot sufficiency, accepted exception rules, checklist Gate Status, and checklist Blocking Items. Source-side intake readiness remains separate: an intake extension may prove raw metadata completeness, source coverage, node inventory parity, HTML SSOT coverage, and blocker lint errors, but that proof is not the Visual Fidelity readiness gate. Responsive visual requirements block PASS only when they are complex, multi-state, or declare L2 or L3 visual proof. ## Structured Artifact Rules @@ -108,6 +105,7 @@ planning guesses. Keep domain model details in `data-model.md`, interface schemas in `contracts/`, and validation run guidance in `quickstart.md`. For visual planning, research.md records visual validation decisions only and must not duplicate the Visual Fidelity Evidence Matrix; contracts formalize visual interaction and state constraints by referencing accepted visual items, visual proof refs, and accepted exception refs; contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing, async callbacks, retry, rollback, compensation, or error propagation, and must not define visual style, tokens, layout breakpoints, screenshot matrices, or validation commands. + ## Handoff Extension Rules Handoff extensions must update schema, validator, command, and cross-agent documentation together. diff --git a/presets/workflow-preset/preset.yml b/presets/workflow-preset/preset.yml index c0d01dbeea..f44e4a89b9 100644 --- a/presets/workflow-preset/preset.yml +++ b/presets/workflow-preset/preset.yml @@ -25,33 +25,6 @@ provides: the constitution template replaces: constitution-template strategy: wrap - - type: template - name: figma-evidence-packet-template - file: templates/figma-evidence-packet-template.md - description: Define the Figma Evidence Packet input format for Figma-derived specifications - replaces: figma-evidence-packet-template - strategy: replace - - type: template - name: figma-intake-contract-template - file: templates/figma-intake-contract.md - description: Define the Figma provider source readiness contract for raw metadata - readiness - replaces: figma-intake-contract-template - strategy: replace - - type: template - name: design-requirement-intake-template - file: templates/design-requirement-intake-template.md - description: Define the Design Requirement Intake format for provider-neutral - design facts - replaces: design-requirement-intake-template - strategy: replace - - type: template - name: requirement-merge-report-template - file: templates/requirement-merge-report-template.md - description: Define the Requirement Merge report format before baseline spec.md - generation - replaces: requirement-merge-report-template - strategy: replace - type: command name: speckit.specify file: commands/speckit.specify.md @@ -205,12 +178,6 @@ provides: description: Schema for formal behavior assertions replaces: speckit-behavior-assertions-v1-schema strategy: replace - - type: template - name: speckit-design-visual-item-matrix-v1-schema - file: schemas/speckit.design.visual-item-matrix.v1.schema.json - description: Schema for normalized design visual item matrix intake - replaces: speckit-design-visual-item-matrix-v1-schema - strategy: replace - type: template name: speckit-implement-manifest-v1-schema file: schemas/speckit.implement.manifest.v1.schema.json diff --git a/presets/workflow-preset/schemas/speckit.design.visual-item-matrix.v1.schema.json b/presets/workflow-preset/schemas/speckit.design.visual-item-matrix.v1.schema.json deleted file mode 100644 index e79c970c42..0000000000 --- a/presets/workflow-preset/schemas/speckit.design.visual-item-matrix.v1.schema.json +++ /dev/null @@ -1,184 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "speckit.design.visual-item-matrix.v1.schema.json", - "title": "Spec Kit Design Visual Item Matrix", - "type": "object", - "additionalProperties": false, - "required": ["contract_type", "source", "readiness", "visual_items"], - "properties": { - "contract_type": { - "const": "speckit.design.visual_item_matrix.v1" - }, - "source": { - "type": "object", - "additionalProperties": false, - "required": ["provider", "source_refs"], - "properties": { - "provider": {"enum": ["figma", "screenshot", "design_doc", "other"]}, - "source_refs": { - "type": "array", - "minItems": 1, - "items": {"type": "string", "minLength": 1} - }, - "capture_timestamp": {"type": "string", "minLength": 1} - } - }, - "readiness": { - "type": "object", - "additionalProperties": false, - "required": [ - "status", - "raw_metadata_complete", - "node_inventory_coverage", - "parity_passed", - "blocker_lint_errors" - ], - "properties": { - "status": {"enum": ["PASS", "BLOCKED"]}, - "raw_metadata_complete": {"type": "boolean"}, - "node_inventory_coverage": {"type": "number", "minimum": 0, "maximum": 100}, - "parity_passed": {"type": "boolean"}, - "blocker_lint_errors": { - "type": "array", - "items": {"type": "string", "minLength": 1} - } - } - }, - "visual_items": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "additionalProperties": false, - "required": [ - "id", - "source_refs", - "requirement_target", - "ui_surface", - "fidelity_scope", - "variant_state_evidence", - "component_requirement_role", - "component_use_constraint", - "constraint_source_refs", - "copy_content_constraint", - "drawing_asset_constraint", - "required_states", - "required_viewport_coverage", - "screenshot_refs", - "visual_proof_level", - "allowed_deviations", - "blockers", - "spec_requirement_target" - ], - "properties": { - "id": {"type": "string", "minLength": 1}, - "source_refs": { - "type": "array", - "minItems": 1, - "items": {"type": "string", "minLength": 1} - }, - "requirement_target": {"type": "string", "minLength": 1}, - "ui_surface": {"type": "string", "minLength": 1}, - "fidelity_scope": { - "enum": [ - "functional-equivalent", - "design-system-faithful", - "pixel-perfect", - "brand-critical", - "responsive-visual" - ] - }, - "layout_facts": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "typography_facts": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "color_token_facts": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "effect_facts": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "asset_refs": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "variant_state_evidence": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": false, - "required": ["source_refs", "observed_state_or_role", "confidence"], - "properties": { - "variant_ref": {"type": "string", "minLength": 1}, - "source_refs": { - "type": "array", - "minItems": 1, - "items": {"type": "string", "minLength": 1} - }, - "observed_state_or_role": {"type": "string", "minLength": 1}, - "confidence": {"enum": ["high", "medium", "low"]} - } - } - }, - "component_requirement_role": {"type": "string", "minLength": 1}, - "component_use_constraint": { - "enum": [ - "visual-reference-only", - "must-reuse-existing", - "figma-export-required", - "unspecified" - ] - }, - "constraint_source_refs": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "copy_content_constraint": { - "enum": [ - "no-new-copy", - "figma-copy-required", - "product-copy-required", - "unspecified" - ] - }, - "drawing_asset_constraint": { - "enum": [ - "no-self-draw", - "figma-export-required", - "existing-asset-required", - "unspecified" - ] - }, - "required_states": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "required_viewport_coverage": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "screenshot_refs": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "visual_proof_level": {"enum": ["L0", "L1", "L2", "L3"]}, - "allowed_deviations": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "blockers": { - "type": "array", - "items": {"type": "string", "minLength": 1} - }, - "spec_requirement_target": {"type": "string", "minLength": 1} - } - } - } - } -} diff --git a/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md b/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md index f488cfebbf..2b908b0e79 100644 --- a/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md +++ b/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md @@ -57,23 +57,28 @@ For each user story or capability, record one row per story or capability case t - [ ] Unknown NFR entries that affect downstream design are listed as blocking items. ## Visual Fidelity Readiness -- [ ] Apply this section when `spec.md` contains design-derived requirements, a design source, provider evidence blockers, or provider-specific design evidence requests. Also apply it when `spec.md` contains product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements. +- [ ] Apply this section when `spec.md` contains `Visual & UI Specification`, visual requirements, visual SSOT refs, external intake refs, provider evidence blockers, or provider-specific evidence requests. Also apply it when `spec.md` contains product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements. +- [ ] `Visual & UI Specification` exists when a visual or UI surface applies; otherwise `spec.md` records a Not Applicable rationale. +- [ ] Every identified visual/UI requirement uses status `Required`, `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`. +- [ ] Unknown visual/UI coverage status appears in Blocking Items when it affects downstream behavior projection or design. +- [ ] Required visual/UI requirements have observable requirement text in `spec.md`. - [ ] Design-derived requirements identify the design source, provider source refs, and required fidelity. -- [ ] Design-derived requirements record provider readiness status, evidence refs, and blockers when provider evidence is required. +- [ ] Visual requirements record external intake readiness status when cited, evidence refs, visual SSOT refs, and blockers when provider evidence is required. - [ ] Visual Fidelity Evidence Matrix rows cite source `spec.md` sections, evidence refs, required screenshot level, blocking item IDs, and accepted exception rules. - [ ] Visual Fidelity Evidence Matrix is the only artifact that decides visual planning readiness, proof level sufficiency, screenshot sufficiency, accepted exception rules, Gate Status, and Blocking Items. -- [ ] Visual Fidelity Evidence Matrix reads visual facts from `spec.md` and evidence refs; it does not call Figma, re-extract provider evidence, rebuild provider matrices, or create another visual readiness path. +- [ ] Visual Fidelity Evidence Matrix reads visual facts from `spec.md` and evidence refs; it does not call provider tools, re-extract external intake evidence, parse HTML SSOT bundles, rebuild provider matrices, or create another visual readiness path. - [ ] Use one Visual Fidelity Evidence Matrix as the single visual readiness record; do not duplicate visual evidence decisions outside the matrix and Blocking Items. - [ ] Do not add historical visual rules or alternate visual decision paths. ## Visual Fidelity Evidence Matrix -| Visual Item ID | Source `spec.md` section | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule | -| --- | --- | --- | --- | --- | --- | --- | --- | -| VIS-001 | `spec.md#...` | functional-equivalent|design-system-faithful|pixel-perfect|brand-critical|responsive-visual | L0|L1|L2|L3 | provider/screenshot refs or none | yes|no | BI-... or none | EX-... or none | +| Visual Item ID | Source `spec.md` section | Requirement Status | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| VIS-001 | `spec.md#...` | Required|Not Applicable|Unknown|[BLOCKED: PROVIDER_EVIDENCE] | functional-equivalent|design-system-faithful|pixel-perfect|brand-critical|responsive-visual | L0|L1|L2|L3 | provider/screenshot refs or none | yes|no | BI-... or none | EX-... or none | +- [ ] Requirement Status is declared for each visual requirement or visual proof obligation. - [ ] Screenshot evidence level is declared when screenshots are required: L0|L1|L2|L3. -- [ ] visual proof refs point to provider evidence or screenshot sources. +- [ ] visual proof refs point to visual SSOT evidence, external intake evidence, or screenshot sources. - [ ] declared visual proof required is recorded when `spec.md` makes screenshot-backed visual proof mandatory. - [ ] Ordinary UI visual requirements may use L1 Key Screenshots; `spec.md` visual proof requirements require L1 or higher. - [ ] L2 State + Viewport Matrix covers key page, state, and viewport combinations for complex UI, responsive, or multi-state requirements. diff --git a/presets/workflow-preset/templates/design-requirement-intake-template.md b/presets/workflow-preset/templates/design-requirement-intake-template.md deleted file mode 100644 index 5d9a4fe0d7..0000000000 --- a/presets/workflow-preset/templates/design-requirement-intake-template.md +++ /dev/null @@ -1,160 +0,0 @@ -# Design Requirement Intake - -Purpose: normalize provider-neutral design requirements before Requirement Merge writes `spec.md`. - -## Design Sources - -- Source type: -- Source URL or path: -- Provider Evidence: -- Capture timestamp: -- Required fidelity: - -## Page Inventory - -- Page or screen: -- Purpose: -- Source refs: - -## Page Hierarchy - -- Navigation structure: -- Parent / child relationships: -- Modal, drawer, or overlay relationships: - -## User Paths - -- Entry point: -- Interaction path: -- Destination or outcome: -- Missing path evidence: - -## Component Inventory - -- Component: -- Required variants: -- Source refs: -- Existing code constraint, only if explicitly provided: - -## Component States - -- Default: -- Hover / focus / active: -- Disabled: -- Loading: -- Empty: -- Error: -- Success: - -## Interaction Rules - -- User action: -- System response: -- Validation or guard: -- Feedback: - -## Visual Tokens - -- Typography: -- Color: -- Spacing: -- Radius: -- Effects: -- Assets: - -## Layout Rules - -- Grid or alignment: -- Sizing: -- Scroll behavior: -- Clipping: -- Safe areas: - -## Responsive Rules - -- Breakpoints: -- Reflow behavior: -- Minimum and maximum widths: -- Long-copy handling: - -## Motion Rules - -- Transition: -- Duration: -- Easing: -- Reduced-motion requirement: - -## State Coverage - -- Covered states: -- Missing states: -- Items marked `[NEEDS CLARIFICATION]`: - -## Visual Acceptance Requirements - -- Required fidelity: -- Visual difference tolerance: -- Accepted exceptions: -- Accessibility requirements: - -## Visual Restoration Trace - -Use one row per accepted Visual Item ID from provider evidence. Each row records the minimum facts needed to preserve UI/UX intent without re-reading provider tools. -Do not copy the full provider Visual Item Matrix. Record only requirement-level facts promoted toward `spec.md`, supporting evidence refs, and unresolved provider or requirement gaps. Visual Restoration Trace must not decide visual planning readiness, proof sufficiency, accepted exception rules, checklist Gate Status, or checklist Blocking Items. - -- Visual Item ID: -- Provider source refs: -- Requirement ID: -- UI surface: -- Fidelity scope: functional-equivalent|design-system-faithful|pixel-perfect|brand-critical|responsive-visual -- Layout constraints: -- Typography constraints: -- Color/token constraints: -- Effect constraints: -- Asset bindings: -- Requirement-level component role: -- Variant/state coverage: -- Component use constraint: visual-reference-only|must-reuse-existing|figma-export-required|unspecified -- Constraint source refs: -- Copy/content constraint: no-new-copy|figma-copy-required|product-copy-required|unspecified -- Drawing/asset constraint: no-self-draw|figma-export-required|existing-asset-required|unspecified -- Required states: -- Required viewport coverage: -- Screenshot refs: -- Visual proof refs: -- Allowed deviations: -- Blocking item: - -## Client Asset Contract - -- Asset ID: -- Required resource type: -- Source refs: -- Asset source strategy: -- Required variants: -- Fallback policy: -- Blocker status: - -## Screenshot Traceability - -Design Requirement Intake remains provider-neutral. - -Screenshot-derived visual facts must include screenshot refs; screenshots must not create product semantics. -Keep screenshot files in provider evidence or `sources/`; -record only requirement-level references here. -Screenshot Traceability records supported facts and unsupported assumptions only. It must not create an independent visual readiness decision. - -- Requirement ID: -- Screenshot refs: -- Visual proof refs: -- Supported visual facts: -- Unsupported assumptions: -- Confidence: - -## Traceability - -- Requirement ID: -- Visual Item ID: -- Source refs: -- Confidence: -- Provider notes: diff --git a/presets/workflow-preset/templates/figma-evidence-packet-template.md b/presets/workflow-preset/templates/figma-evidence-packet-template.md deleted file mode 100644 index dec1bccbf6..0000000000 --- a/presets/workflow-preset/templates/figma-evidence-packet-template.md +++ /dev/null @@ -1,182 +0,0 @@ -# Figma Evidence Packet - -Purpose: normalize Figma design evidence before Design Requirement Intake and -`/speckit.specify`. Readiness gate: `templates/figma-intake-contract.md`. - -## Figma Source - -- File URL: -- Page / Frame / Node IDs: -- Design version / timestamp: -- Target platform: -- Required fidelity: - -## Extraction Context - -- Runtime agent: -- Figma MCP availability: -- Screenshots captured: -- Variables / styles captured: -- Component metadata captured: - -## Screenshot Evidence - -Screenshot evidence must declare L0-L3 coverage and coverage gaps. Screenshots are visual proof, not the primary Design Requirement Intake carrier. -Constraint: screenshot-derived visual facts require screenshot refs and must not replace Design Requirement Intake. -Screenshot evidence and the Screenshot Coverage Matrix record coverage facts and gaps only. They must not decide visual planning readiness, proof sufficiency, accepted exception rules, checklist Gate Status, or checklist Blocking Items. - -- Screenshot level: L0|L1|L2|L3 -- L0: no screenshot evidence -- L1: static screenshot reference -- L2: viewport or state screenshot coverage -- L3: visual diff baseline or approved visual proof -- L3 applies to high-fidelity, pixel-perfect, brand-critical, design-system, or visual regression work - -## Screenshot Coverage Matrix - -- Requirement ID: -- Screenshot level: -- Screenshot refs: -- Frame / node refs: -- Viewport: -- State: -- Capture timestamp: -- Design version: -- Redaction required: -- Baseline usage: -- Missing coverage: -- Blocking item: -- Visual baseline usage: none|manual review|visual diff - -## Figma Intake Readiness - -Figma Intake Readiness is provider source readiness only. It proves raw Figma metadata and inventory completeness before evidence can be consumed; it is separate from Visual Fidelity planning readiness, which is decided only by the checklist Visual Fidelity Evidence Matrix. - -- figma-metadata.part-*.xml: -- figma-metadata.index.yaml: -- figma-node-inventory.yaml: -- raw metadata completeness: -- metadata index completeness proof: -- node inventory parity: -- blocker lint errors: -- ready gate: PASS|BLOCKED - -## Evidence Record Format - -Record schema for observed, inferred, missing, and out-of-scope facts. - -- Fact ID: -- Evidence type: Observed|Inferred|Missing|Out of Scope -- Source refs: file/page/frame/node/component/screenshot -- Raw Figma value: -- Normalized requirement: -- Confidence: -- Spec target: - -## Observed from Figma - -- Layout hierarchy: -- Spacing / sizing / grid: -- Typography: -- Colors / tokens: -- Effects: -- Assets: -- Components / variants: -- Prototype links: - -## Inferred from Structure - -- Likely navigation: -- Likely grouping: -- Likely content priority: -- Confidence notes: - -## Missing / Needs Clarification - -- Business semantics: -- Dynamic states: -- Responsive behavior: -- Permissions: -- Validation: -- Error handling: -- Data source: -- Analytics / tracking: -- Items marked `[NEEDS CLARIFICATION]`: - -## Out of Scope - -- Figma content not included in this extraction: -- Runtime behavior not represented by the selected frames: -- Explicit exclusions: - -## Visual Facts for Spec - -- Layout and spacing: -- Typography and color: -- Assets and content: -- States observed or missing: -- Responsive evidence: -- Accessibility evidence: -- Accepted exceptions: - -## Visual Item Matrix - -Use one row per restorable UI surface, component, state, or visual proof obligation. -Visual Item IDs must be stable enough to carry into Design Requirement Intake, `spec.md`, and the Visual Fidelity Evidence Matrix. -The Visual Item Matrix records provider-normalized visual facts, observed state and viewport evidence, proof refs, and provider evidence blockers. It must not decide visual planning readiness, proof level sufficiency, accepted exception rules, checklist Gate Status, or checklist Blocking Items. - -- Visual Item ID: -- Figma frame/node refs: -- Requirement target: -- UI surface: -- Required fidelity: functional-equivalent|design-system-faithful|pixel-perfect|brand-critical|responsive-visual -- Layout facts: -- Typography facts: -- Color/token facts: -- Effect facts: -- Asset refs: -- Variant/state evidence: -- Component requirement role: -- Component use constraint: visual-reference-only|must-reuse-existing|figma-export-required|unspecified -- Constraint source refs: -- Copy/content constraint: no-new-copy|figma-copy-required|product-copy-required|unspecified -- Drawing/asset constraint: no-self-draw|figma-export-required|existing-asset-required|unspecified -- Required states: -- Required viewport coverage: -- Screenshot refs: -- Visual proof level: L0|L1|L2|L3 -- Allowed deviations: -- Blockers: -- Spec requirement target: - -## Client Asset Inventory - -- Asset ID: -- Asset role: -- Resource type: image|icon|video|lottie|svg|font -- Figma node/component ref: -- Asset source strategy: figma_export_required|code_asset|existing_repo_asset|remote_runtime_asset -- Export/use contract: -- Required variants: -- Fallback policy: -- Blocker status: - -## Component Mapping - -- Figma component -> requirement-level component role: -- Variant -> observed state or semantic role: -- Existing code component constraint, only if explicitly provided: -- Visual-reference-only components: -- Must-reuse-existing components: -- No self-draw / no new copy constraints: -- Missing mappings or constraints: - -## Spec Handoff Notes - -- Supported requirement sections: -- Clarification items that must remain unresolved: -- Source refs required in `spec.md`: - -## Open Questions - -- [NEEDS CLARIFICATION] diff --git a/presets/workflow-preset/templates/figma-intake-contract.md b/presets/workflow-preset/templates/figma-intake-contract.md deleted file mode 100644 index 9c25a53621..0000000000 --- a/presets/workflow-preset/templates/figma-intake-contract.md +++ /dev/null @@ -1,122 +0,0 @@ -# Figma Intake Contract - -Required Figma intake artifacts and readiness gates. The runtime agent or -external Figma intake performs extraction before Design Requirement Intake -consumes provider evidence. - -## Raw Metadata Shards - -`figma-metadata.part-*.xml` must preserve raw get_metadata output. - -- Do not summarize, rewrite, compress into prose, or replace real nodes with - natural language. -- Cover the complete descendant subtree for every selected frame or node. -- Treat truncation as failed evidence. - -Each part must be listed with: - -- path: -- byte_size: -- sha256: -- root_node_ids: -- node_count: -- truncated: - -## Metadata Index Completeness - -`figma-metadata.index.yaml` must prove source identity, shard integrity, and -selected subtree completeness. - -Required source fields: - -- file_url: -- file_key: -- page_id: -- selected_node_ids: -- captured_at: -- mcp_tool: get_metadata -- design_version_or_timestamp: - -Required completeness fields: - -- selected_subtree_complete: -- raw_metadata_complete: -- expected_root_node_ids: -- captured_root_node_ids: -- missing_root_node_ids: -- gap_count: -- gaps: - -## Node Inventory Parity - -`figma-node-inventory.yaml` must reconcile inventory with raw metadata. - -Required parity fields: - -- raw_node_count: -- inventory_node_count: -- excluded_node_count: -- missing_node_count: -- duplicate_node_count: -- truncated_raw_evidence: -- node_inventory_coverage: 100% -- parity_passed: true - -Required parity rules: - -- inventory_node_count + excluded_node_count + missing_node_count == raw_node_count -- duplicate_node_count == 0 -- missing_node_count == 0 -- truncated_raw_evidence == false -- parity_passed equals count balance, no duplicates, no missing nodes, and no truncation - -## Evidence Readiness Gate - -Figma intake is ready only when all conditions pass. This gate is provider source readiness only; it proves raw Figma metadata and node inventory completeness. -It must not decide Visual Fidelity planning readiness, proof sufficiency, accepted exception rules, checklist Gate Status, or checklist Blocking Items. - -- raw_metadata_complete: true -- node_inventory_coverage: 100% -- parity_passed: true -- No blocker lint errors - -## Normalized Visual Item Matrix - -When UI/UX visual fidelity is in scope, the external intake should also write a -normalized `speckit.design.visual_item_matrix.v1` JSON artifact that conforms to -`schemas/speckit.design.visual-item-matrix.v1.schema.json`. -This JSON is derived from the raw metadata shards, metadata index, node -inventory, screenshots, and qualified provider notes. It must not replace raw provider evidence. - -The normalized matrix carries Visual Item IDs, source refs, observed variant/state evidence, requirement-level component roles, explicit component use constraints, asset/copy/drawing constraints, screenshot refs, visual proof level, blockers, and `spec.md` requirement targets. -Its blockers are provider evidence blockers, not checklist Blocking Items, and -the matrix must not create a second visual readiness gate. -Explicit constraints such as must-reuse-existing, no-self-draw, or no-new-copy -must include constraint source refs. - -## Blocker Lint Errors - -- FIGMA_RAW_METADATA_MISSING -- FIGMA_RAW_METADATA_SUMMARY_SUBSTITUTION -- FIGMA_RAW_METADATA_TRUNCATED -- FIGMA_SELECTED_SUBTREE_INCOMPLETE -- FIGMA_METADATA_INDEX_MISSING -- FIGMA_METADATA_PARITY_FAILED -- FIGMA_READY_WITHOUT_COMPLETENESS_PROOF - -## Gap Rules - -Record a gap instead of passing silently when raw metadata is missing, -summarized, truncated, incomplete, missing parity proof, missing nodes, duplicate -nodes, or marked ready without completeness proof. - -## Preset Boundary - -Preset boundary: - -- must not call Figma MCP -- must not fetch Figma URLs -- must not write `figma-metadata.part-*.xml` -- must not run adapter scripts -- must not authenticate to Figma -- must not generate artifact instances diff --git a/presets/workflow-preset/templates/requirement-merge-report-template.md b/presets/workflow-preset/templates/requirement-merge-report-template.md deleted file mode 100644 index 3e4222b409..0000000000 --- a/presets/workflow-preset/templates/requirement-merge-report-template.md +++ /dev/null @@ -1,71 +0,0 @@ -# Requirement Merge Report - -Purpose: normalize Product Requirement and Design Requirement merge decisions for baseline `spec.md`. - -## Product Requirement Inputs - -- Source: -- Intake artifact: -- Confirmed product facts: -- Open product gaps: - -## Design Requirement Inputs - -- Source: -- Intake artifact: -- Confirmed design facts: -- Open design gaps: - -## Merge Rules - -Product Requirement owns: - -- business goals -- user roles and permissions -- data semantics -- validation rules -- interface semantics -- exception handling -- non-functional requirements - -Design Requirement owns: - -- page structure -- information hierarchy -- interaction paths -- component states -- visual tokens -- layout and responsive behavior -- motion behavior -- visual acceptance requirements - -## Design Requirement Promotion Rules - -- Promote observed design facts with source refs to design requirements. -- Promote confirmed design facts to design requirements. -- Inferred design facts remain assumptions or `[NEEDS CLARIFICATION]`. -- Missing design facts remain `[NEEDS CLARIFICATION]`. -- Promote screenshot-supported visual facts only as visual requirements with screenshot refs. -- Screenshot-implied business rules must remain `[NEEDS CLARIFICATION]`. - -## Conflict Resolution - -- Conflict ID: -- Product requirement source: -- Design requirement source: -- Resolution: -- Clarification needed: - -## Clarification Outputs - -- Item: -- Target `spec.md` section: -- Marker: `[NEEDS CLARIFICATION]` -- Blocking impact: - -## Baseline Spec Handoff - -- `spec.md` sections to create or update: -- Confirmed requirements: -- Unresolved requirement ambiguities: -- Source refs required in `spec.md`: diff --git a/presets/workflow-preset/tests/contracts/speckit-cross-agent-subagents.md b/presets/workflow-preset/tests/contracts/speckit-cross-agent-subagents.md index 1468ed8221..16c009bb08 100644 --- a/presets/workflow-preset/tests/contracts/speckit-cross-agent-subagents.md +++ b/presets/workflow-preset/tests/contracts/speckit-cross-agent-subagents.md @@ -2,9 +2,8 @@ ## Purpose Reduce implementation-stage context load and reasoning drift by turning broad `/speckit.implement` work into persisted, capability-scoped handoffs. Workers receive only task-local context, allowed paths, validation commands, and receipt obligations. ## Files and Schemas -- `handoffs/implement//handoff-manifest.json`, `planner-outputs/`, `context-index.json` -- `handoffs/implement//.json`, `.context.md`, `results/.json` -- `schemas/speckit.implement.manifest.v1.schema.json`, `schemas/speckit.implement.handoff.v2.schema.json`, `schemas/speckit.implement.receipt.v1.schema.json` +- `handoffs/implement//handoff-manifest.json`, `planner-outputs/`, `context-index.json`, `.json`, `.context.md`, `results/.json` +- schemas: `schemas/speckit.implement.manifest.v1.schema.json`, `schemas/speckit.implement.handoff.v2.schema.json`, `schemas/speckit.implement.receipt.v1.schema.json` - Handoff records `planner_outputs` and `draft_source` fields. ## Authority - Only Vertical Planner Agents may produce shard plans and digest drafts. @@ -38,8 +37,7 @@ Use `agent-runtime=` as a prompt hint. The manifest re - review receipts - commit `tasks.md` - during task_commit, mark `[x]` only for receipt completed_task_ids that passed receipt review, required code review, and integration verification with no deferred_validation_todos -- run integration verification -- report closeout +- run integration verification and report closeout ## Vertical Planner Agent - one `vertical_capability` - produce shard plans, handoff drafts, context digest drafts @@ -56,12 +54,12 @@ Use `agent-runtime=` as a prompt hint. The manifest re - Execute only task_ids - Read only allowed_read_paths - Write only allowed_write_paths -- write receipt_path as speckit.implement.receipt.v1 with validation_evidence references to relevant BDD scenario, behavior assertion, API contract, or quickstart path +- write receipt_path as speckit.implement.receipt.v1 with validation_evidence references to relevant BDD scenario, behavior assertion, API contract, quickstart path, Visual Item ID, Requirement Status, UIF path, screenshot ref, visual proof ref, Client Asset Contract entry, quickstart validation path, or captured command output - use empty completed_task_ids when the handoff is blocked, validation is deferred, required evidence is missing, or code review status is not approved - Code Review Receipts use task_type: code_review, review_conclusion.checked_sources, data_side_effect_review, consistency_repairs, deferred_validation_todos, and quickstart/contract validation command evidence - review actual implementation diff data side effects, including runtime database writes and field-level update/delete behavior - repair implementation drift against existing design, sequence, or contract constraints, or high-risk data side effects, only inside allowed_write_paths; upstream requirement, contract, checklist, or planning artifact gaps become blockers or todos instead of repair edits; real e2e gaps become todos -- must not edit tasks.md, create handoffs, dispatch workers +- must not discover visual requirements, repair Visual Fidelity Readiness evidence, edit `spec.md`, contracts, readiness checklists, or planning artifacts to make visual work executable; must not edit tasks.md, create handoffs, dispatch workers ## Worker Prompt ```text Worker Agent. @@ -74,9 +72,9 @@ Handoff JSON: - Write only allowed_write_paths - Do not edit tasks.md - Do not dispatch workers -- Write receipt_path as speckit.implement.receipt.v1 with validation_evidence references to relevant BDD scenario, behavior assertion, API contract, or quickstart path +- Write receipt_path as speckit.implement.receipt.v1 with validation_evidence references to relevant BDD scenario, behavior assertion, API contract, quickstart path, Visual Item ID, Requirement Status, UIF path, screenshot ref, visual proof ref, Client Asset Contract entry, quickstart validation path, or captured command output - Use empty completed_task_ids when the handoff is blocked, validation is deferred, required evidence is missing, or code review status is not approved -- For Code Review tasks, echo task_type: code_review; add review_conclusion.checked_sources and data_side_effect_review; review actual implementation diff runtime database writes and field-level update/delete behavior; include quickstart/contract validation command evidence; repair only authorized implementation drift; record upstream artifact gaps and real e2e todos +- For Code Review tasks, echo task_type: code_review; add review_conclusion.checked_sources and data_side_effect_review; review actual implementation diff runtime database writes and field-level update/delete behavior; include quickstart/contract validation command evidence; repair only authorized implementation drift; record upstream artifact gaps and real e2e todos; for final_visual_review tasks, verify implemented UI states, viewport behavior, Visual Fidelity Readiness, UIF paths, screenshot refs, visual proof refs, and Client Asset Contract bindings without changing upstream artifacts ``` ## Planner Prompt ```text @@ -96,6 +94,7 @@ vertical_capability: - one incomplete `tasks.md` checklist item maps to one candidate shard - ignore completed `[x]` checklist items - preserve `tasks.md` order +- visual shard candidates must come only from `tasks.md` visual task types `visual_setup`, `visual_validation`, `visual_implementation`, `visual_evidence`, `ui_acceptance`, `visual_verification`, `asset_binding`, or `final_visual_review`; preserve the Visual Fidelity Readiness `Requirement Status` filter from `/speckit.tasks`: only `Required` or `Required` plus an accepted exception is executable; do not create visual shards for `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`; route `Unknown` back to `/speckit.clarify` and `[BLOCKED: PROVIDER_EVIDENCE]` to the external intake extension - infer `vertical_capability` from task section heading, task text, referenced paths - group candidates only when lifecycle dependencies, vertical_capability, and allowed_write_paths match - shard IDs use `S<2-digit-sequence>--<2-digit-sequence>` @@ -104,8 +103,9 @@ vertical_capability: - include document headings from `context-index.json` - include only sections referenced by assigned task paths or vertical_capability - include relevant `class-diagram.md`, `contracts/sequences.md`, `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` constraints, plus research.md validation decisions and quickstart.md validation paths from `research.md` and `quickstart.md` -- include behavior contract constraints, visual fidelity requirements, screenshot refs, visual proof refs, Design Requirement trace refs, and Client Asset Contract entries -- asset binding maps required Client Asset Contract items to local asset paths or code asset mappings; missing required client visual assets, mappings, variants, or fallbacks become `context_gaps` +- include behavior contract constraints, visual fidelity requirements, Visual Item ID, Requirement Status, accepted exception rule, screenshot refs, visual proof refs, visual SSOT refs, external evidence refs, and Client Asset Contract entries +- asset binding maps only executable Required or accepted-exception Client Asset Contract items to local asset paths or code asset mappings; missing required client visual assets, mappings, variants, or fallbacks become `context_gaps` +- visual `Requirement Status` mismatches, `Unknown`, `[BLOCKED: PROVIDER_EVIDENCE]`, missing visual proof refs, missing screenshot refs, missing asset variants, or missing fallback policy become `context_gaps`, not implementation scope - record unresolved required context as `context_gaps` ## Path Rules - derive `allowed_write_paths` from paths referenced by assigned task text, planned `U` design object, and specific source, test, fixture, configuration, or receipt paths @@ -119,5 +119,6 @@ vertical_capability: - non-empty `completed_task_ids` with `deferred_validation_todos` - non-empty `completed_task_ids` on Code Review Receipts whose `review_conclusion.status` is not approved - empty `validation_evidence` or missing relevant BDD scenario, behavior assertion, API contract, or quickstart path reference +- visual handoff receipt missing relevant Visual Item ID, Requirement Status, UIF path, screenshot ref, visual proof ref, Client Asset Contract entry, quickstart validation path, or captured command output - receipt 路径不等于 handoff 中声明的 `task_status_update.receipt_path` - Code Review Receipts missing `task_type: code_review`, `review_conclusion.checked_sources`, `data_side_effect_review`, quickstart/contract validation command evidence, in-scope `consistency_repairs`, or needed `deferred_validation_todos` diff --git a/presets/workflow-preset/tests/test_preset_contract.py b/presets/workflow-preset/tests/test_preset_contract.py index ddfd05ccea..c4f282d5bf 100644 --- a/presets/workflow-preset/tests/test_preset_contract.py +++ b/presets/workflow-preset/tests/test_preset_contract.py @@ -13,8 +13,6 @@ validate_behavior_case_coverage, validate_behavior_contract_bundle, validate_behavior_draft_contract, - validate_design_requirement_intake_trace_contract, - validate_visual_item_matrix_contract, validate_implement_contract, validate_handoff_contract, validate_manifest_contract, @@ -39,10 +37,6 @@ IMPLEMENT_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.implement.md" CONSTITUTION_TEMPLATE_PATH = REPO_ROOT / "templates" / "constitution-template.md" PLAN_TEMPLATE_PATH = REPO_ROOT / "templates" / "plan-template.md" -FIGMA_EVIDENCE_PACKET_TEMPLATE_PATH = ( - REPO_ROOT / "templates" / "figma-evidence-packet-template.md" -) - CANONICAL_RESPONSIVE_VISUAL_RULE = ( "Responsive visual requirements block PASS only when they are complex, " "multi-state, or declare L2 or L3 visual proof" @@ -61,13 +55,6 @@ "兼容旧版", "回退视觉规则", ) -FIGMA_INTAKE_CONTRACT_TEMPLATE_PATH = REPO_ROOT / "templates" / "figma-intake-contract.md" -DESIGN_REQUIREMENT_INTAKE_TEMPLATE_PATH = ( - REPO_ROOT / "templates" / "design-requirement-intake-template.md" -) -REQUIREMENT_MERGE_REPORT_TEMPLATE_PATH = ( - REPO_ROOT / "templates" / "requirement-merge-report-template.md" -) REQUIREMENTS_DEV_PATH = REPO_ROOT / "requirements-dev.txt" MANIFEST_SCHEMA_PATH = REPO_ROOT / "schemas" / "speckit.implement.manifest.v1.schema.json" HANDOFF_SCHEMA_PATH = REPO_ROOT / "schemas" / "speckit.implement.handoff.v2.schema.json" @@ -95,9 +82,6 @@ / "schemas" / "speckit.behavior.assertions.v1.schema.json", } -VISUAL_ITEM_MATRIX_SCHEMA_PATH = ( - REPO_ROOT / "schemas" / "speckit.design.visual-item-matrix.v1.schema.json" -) BEHAVIOR_TEMPLATE_PATHS = { "behavior-bdd-draft-template": REPO_ROOT / "templates" / "behavior" / "bdd-draft.feature", "behavior-scenarios-draft-template": REPO_ROOT @@ -489,77 +473,6 @@ def minimal_behavior_assertions() -> dict: } -def minimal_visual_item_matrix() -> dict: - return { - "contract_type": "speckit.design.visual_item_matrix.v1", - "source": { - "provider": "figma", - "source_refs": ["figma://file/page/frame/node"], - "capture_timestamp": "2026-06-22T00:00:00Z", - }, - "readiness": { - "status": "PASS", - "raw_metadata_complete": True, - "node_inventory_coverage": 100, - "parity_passed": True, - "blocker_lint_errors": [], - }, - "visual_items": [ - { - "id": "VI-001", - "source_refs": ["figma://file/page/frame/node"], - "requirement_target": "Home screen header", - "ui_surface": "HomePage", - "fidelity_scope": "design-system-faithful", - "layout_facts": ["Header is aligned to the top safe area."], - "typography_facts": ["Title uses the observed display style."], - "color_token_facts": ["Primary action uses the observed brand token."], - "effect_facts": [], - "asset_refs": [], - "variant_state_evidence": [ - { - "variant_ref": "component=Button,state=disabled", - "source_refs": ["figma://component/button-disabled"], - "observed_state_or_role": "disabled", - "confidence": "high", - } - ], - "component_requirement_role": "primary action", - "component_use_constraint": "unspecified", - "constraint_source_refs": [], - "copy_content_constraint": "unspecified", - "drawing_asset_constraint": "unspecified", - "required_states": ["default", "disabled"], - "required_viewport_coverage": ["desktop"], - "screenshot_refs": ["screenshots/home-desktop.png"], - "visual_proof_level": "L1", - "allowed_deviations": [], - "blockers": [], - "spec_requirement_target": "spec.md#visual-requirements", - } - ], - } - - -def minimal_design_requirement_intake_trace() -> dict: - return { - "visual_restoration_trace": [ - { - "visual_item_id": "VI-001", - "provider_source_refs": ["figma://file/page/frame/node"], - "requirement_id": "FR-001", - "ui_surface": "HomePage", - "fidelity_scope": "design-system-faithful", - "promoted_requirement_facts": [ - "Header preserves the accepted hierarchy and primary action role." - ], - "supporting_evidence_refs": ["figma-evidence-packet.md#VI-001"], - "unresolved_gaps": [], - } - ] - } - - def minimal_exception_behavior_assertions() -> dict: return minimal_exception_behavior_assertions_with_intent("state_invariant") @@ -577,7 +490,7 @@ def test_preset_manifest_contract(self) -> None: self.assertEqual("1.0", data["schema_version"]) self.assertEqual("workflow-preset", data["preset"]["id"]) self.assertEqual("Workflow Preset", data["preset"]["name"]) - self.assertEqual("1.3.11", data["preset"]["version"]) + self.assertEqual("1.3.10", data["preset"]["version"]) self.assertEqual( "Behavior-first specification, design artifacts, and agent-native handoff orchestration", data["preset"]["description"], @@ -595,10 +508,18 @@ def test_preset_manifest_contract(self) -> None: ) provides = data["provides"]["templates"] - self.assertEqual(35, len(provides)) + self.assertEqual(30, len(provides)) entries = {entry["name"]: entry for entry in provides} self.assertNotIn("behavior-open-questions-template", entries) self.assertNotIn("speckit-behavior-open-questions-v1-schema", entries) + for migrated_entry in ( + "provider-evidence-packet-template", + "provider-intake-contract-template", + "design-requirement" + "-intake-template", + "requirement-merge" + "-report-template", + "speckit-design-visual" + "-item-matrix-v1-schema", + ): + self.assertNotIn(migrated_entry, entries) plan_template = entries["plan-template"] self.assertEqual("template", plan_template["type"]) @@ -612,52 +533,6 @@ def test_preset_manifest_contract(self) -> None: self.assertEqual("constitution-template", constitution_template["replaces"]) self.assertEqual("wrap", constitution_template["strategy"]) - figma_packet_template = entries["figma-evidence-packet-template"] - self.assertEqual("template", figma_packet_template["type"]) - self.assertEqual( - "templates/figma-evidence-packet-template.md", - figma_packet_template["file"], - ) - self.assertEqual( - "figma-evidence-packet-template", - figma_packet_template["replaces"], - ) - self.assertEqual("replace", figma_packet_template["strategy"]) - self.assertIn("Figma Evidence Packet", figma_packet_template["description"]) - - figma_intake_contract = entries["figma-intake-contract-template"] - self.assertEqual("template", figma_intake_contract["type"]) - self.assertEqual("templates/figma-intake-contract.md", figma_intake_contract["file"]) - self.assertEqual("figma-intake-contract-template", figma_intake_contract["replaces"]) - self.assertEqual("replace", figma_intake_contract["strategy"]) - self.assertIn("Figma provider source readiness contract", figma_intake_contract["description"]) - - design_intake_template = entries["design-requirement-intake-template"] - self.assertEqual("template", design_intake_template["type"]) - self.assertEqual( - "templates/design-requirement-intake-template.md", - design_intake_template["file"], - ) - self.assertEqual( - "design-requirement-intake-template", - design_intake_template["replaces"], - ) - self.assertEqual("replace", design_intake_template["strategy"]) - self.assertIn("Design Requirement Intake", design_intake_template["description"]) - - merge_report_template = entries["requirement-merge-report-template"] - self.assertEqual("template", merge_report_template["type"]) - self.assertEqual( - "templates/requirement-merge-report-template.md", - merge_report_template["file"], - ) - self.assertEqual( - "requirement-merge-report-template", - merge_report_template["replaces"], - ) - self.assertEqual("replace", merge_report_template["strategy"]) - self.assertIn("Requirement Merge", merge_report_template["description"]) - for command_name in ("speckit.plan", "speckit.tasks"): command = entries[command_name] self.assertEqual("command", command["type"]) @@ -747,16 +622,6 @@ def test_preset_manifest_contract(self) -> None: self.assertEqual(schema_name, schema["replaces"]) self.assertEqual("replace", schema["strategy"]) - visual_matrix_schema = entries["speckit-design-visual-item-matrix-v1-schema"] - self.assertEqual("template", visual_matrix_schema["type"]) - self.assertEqual( - "schemas/speckit.design.visual-item-matrix.v1.schema.json", - visual_matrix_schema["file"], - ) - self.assertIn("normalized design visual item matrix", visual_matrix_schema["description"]) - self.assertEqual("speckit-design-visual-item-matrix-v1-schema", visual_matrix_schema["replaces"]) - self.assertEqual("replace", visual_matrix_schema["strategy"]) - self.assertNotIn("scripts", data["provides"]) self.assertNotIn("files", data["provides"]) self.assertNotIn("workflows", data["provides"]) @@ -1077,6 +942,7 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: self.assertIn("Preset-added requirement output writes only `spec.md`", specify) self.assertIn("Product requirements stay in `spec.md`", specify) self.assertIn("non-functional requirements", specify) + self.assertIn("visual and UI requirements", specify) self.assertIn("report the `spec.md` sections created or updated", specify) for term in ( "Official Style Alignment", @@ -1088,66 +954,56 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: ): self.assertIn(term, specify) for term in ( - "Design Requirement Input Policy", - "Stage 0: Product Requirement Intake", - "Product intake input", - "Product intake output", - "Stage 1: Design Requirement Intake", - "Design intake input", - "Design intake output", - "recorded only in `spec.md`", - "stable Visual Item ID trace refs", - "observed variant/state facts", - "provider-neutral design evidence", + "confirmed external intake facts", + "visual SSOT refs", + "evidence refs", + "does not perform intake", + "call provider tools", + "parse HTML bundles", + "decide provider source readiness", + "generate provider artifact instances", + "Specification Projection Policy", + "source-backed external intake facts", + "Visual Asset Registry", + "external source artifact inputs", + "visual media inventory", + "license status", + "Visual & UI Specification", + "observable visual and UI requirements", + "write a `Visual & UI Specification` section", + "Not Applicable rationale", + "Every identified visual or UI requirement must be recorded", + "`Required`, `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`", + "do not silently omit low-evidence visual or UI requirements", "source refs", - "Stage 2: Requirement Merge", - "Merge input", - "Merge output", - "Design Requirement Promotion Rules", - "preserve Visual Item ID trace refs for visual requirements", - "conflicts", - "provider blockers", - "Stage 3: Generate baseline spec.md", - "Baseline spec output", - "Figma Evidence Packet", - "Figma provider source readiness contract", - "ready packet is supplied by a runtime agent or external Figma intake that has Figma MCP access", - "runtime agent or external Figma intake", - "does not call Figma MCP", - "preset defines the required design intake and provider readiness artifact structure", - "does not generate the artifact instances", - "ready gate", - "not ready", - "do not write design-derived requirements", - "metadata index completeness proof", - "Provider evidence readiness blockers", - "[BLOCKED: PROVIDER_EVIDENCE]", - "must not become product `[NEEDS CLARIFICATION]` items", - "blocker lint errors", - "Observed from Figma", - "Inferred from Structure", - "Missing / Needs Clarification", - "Out of Scope", - "[NEEDS CLARIFICATION]", - "Screenshots support visual facts only", - "screenshots must not create product semantics", + "state and viewport refs", "Client Asset Contract facts", "asset source strategy", "required variants", "fallback policy", "blocker status", - "Screenshot-implied business rules", - "Do not invent code props, code state names, component reuse decisions, self-drawing bans, or copy restrictions from Figma structure", - "Record component use, no-self-draw, and no-new-copy constraints only when product input or qualified provider evidence states them explicitly", - "Continue to write only `spec.md`", - "stage-wise report", + "Promote only source-backed visual, layout, state, interaction, responsive, accessibility, and acceptance facts", + "Component State Matrix content as Visual & UI Specification requirements, not visual assets", + "observable states, visual feedback, and interaction outcomes", + "Product semantics implied only by provider evidence stay `[NEEDS CLARIFICATION]`", + "DOM structure", + "CSS selectors", + "component props", + "provider blockers", + "[BLOCKED: PROVIDER_EVIDENCE]", + "keep explicit visual or UI requirement coverage in `spec.md`", + "Functional, non-functional, and visual/UI requirement coverage", + "must not become product `[NEEDS CLARIFICATION]` items", + "[NEEDS CLARIFICATION]", + "visual SSOT refs preserved", ): self.assertIn(term, specify) self.assertLessEqual(len(specify.splitlines()), 70) for forbidden in ( "/speckit.plan", "/speckit.checklist", - "`[NEEDS CLARIFICATION]` item requesting a filled Figma Evidence Packet", + "Visual Fidelity Evidence Matrix", + "`[NEEDS CLARIFICATION]` item requesting a filled Provider Evidence Packet", "behavior/bdd.draft.feature", "behavior/behavior-scenarios.draft.json", "behavior/uif.intent.json", @@ -1161,6 +1017,15 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: "local asset path", "asset hash", "allowed_write_paths", + "Design intake input", + "Provider Evidence Packet readiness", + "Requirement Merge Report", + "raw get_metadata", + "Stage 0:", + "Stage 1:", + "Stage 2:", + "Stage 3:", + "Observed from provider design", ): self.assertNotIn(forbidden, specify) self.assertNotIn("contracts/bdd/", specify) @@ -1176,18 +1041,20 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: self.assertIn("Do not read or update behavior draft artifacts", clarify) self.assertIn("Product requirements stay in `spec.md`", clarify) self.assertIn("non-functional requirement assumptions", clarify) + self.assertIn("visual/UI requirement coverage status", clarify) self.assertIn("only after user-provided answers", clarify) self.assertIn("Design Requirement Clarification Strategy", clarify) - self.assertIn("Design Requirement Intake", clarify) - self.assertIn("Figma Evidence Packet", clarify) - self.assertIn("provider-specific evidence", clarify) - self.assertIn("Missing / Needs Clarification", clarify) + self.assertIn("external intake evidence", clarify) + self.assertIn("visual SSOT refs", clarify) + self.assertIn("evidence-derived gaps", clarify) + self.assertIn("visual/UI coverage status `Unknown`", clarify) self.assertIn("[NEEDS CLARIFICATION]", clarify) - self.assertIn("Inferred from Structure", clarify) - self.assertIn("Do not call Figma MCP", clarify) + self.assertIn("Do not call provider tools", clarify) self.assertIn("Do not re-extract design facts", clarify) - self.assertIn("qualified evidence-backed design-derived requirements and trace refs", clarify) - self.assertIn("does not write raw Figma evidence into `spec.md`", clarify) + self.assertIn("re-parse provider design links", clarify) + self.assertIn("parse HTML SSOT bundles", clarify) + self.assertIn("External intake owns source capture and provider readiness", clarify) + self.assertIn("confirmed evidence-backed requirements and trace refs", clarify) self.assertIn("Do not ask the user to fix provider extraction artifacts", clarify) self.assertIn("Ask at most 5 high-impact questions", clarify) self.assertIn("Present EXACTLY ONE question at a time", clarify) @@ -1208,6 +1075,7 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: self.assertIn("### Session YYYY-MM-DD", clarify) self.assertIn("Q:", clarify) self.assertIn("A:", clarify) + self.assertIn("provider-specific clarification document", clarify) self.assertIn("Validation after each write", clarify) self.assertIn("after EACH write plus final pass", clarify) self.assertIn("Total asked", clarify) @@ -1220,6 +1088,7 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: self.assertIn("hooks.after_clarify", clarify) self.assertIn("EXECUTE_COMMAND", clarify) self.assertIn("Completion Report", clarify) + self.assertIn("Visual/UI coverage status: Required, Not Applicable, Unknown, or `[BLOCKED: PROVIDER_EVIDENCE]`", clarify) self.assertIn("visual fidelity scope", clarify) self.assertIn("missing UI states", clarify) self.assertIn("responsive behavior", clarify) @@ -1227,6 +1096,8 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: self.assertIn("data semantics", clarify) self.assertIn("acceptance evidence", clarify) self.assertIn("write confirmed answers back into `spec.md`", clarify) + self.assertIn("Update affected visual/UI coverage status", clarify) + self.assertIn("Any answered visual/UI coverage status was updated in `spec.md`", clarify) self.assertIn("Do not generate visual restoration checklists", clarify) for forbidden in ( "behavior/bdd.draft.feature", @@ -1234,10 +1105,13 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: "behavior/uif.intent.json", "behavior/data-fixtures.intent.json", "behavior/open-questions.json", - "use_figma", + "use_provider_tool", "get_design_context", - "fetch Figma URL", - "read Figma URL", + "fetch provider design URL", + "read provider design URL", + "Provider Evidence Packet", + "Design Requirement" + " Intake", + "Inferred from Structure", "update checklists/behavior-testability.md", ): self.assertNotIn(forbidden, clarify) @@ -1296,12 +1170,22 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: self.assertIn("Unknown and affects downstream design", checklist) for term in ( "Visual Fidelity Readiness", - "design-derived requirements", - "design source, provider evidence blockers, or provider-specific design evidence requests", + "Visual & UI Specification", + "Check Visual/UI Coverage from `spec.md`", + "Every identified visual/UI requirement must use status", + "`Required`, `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`", + "requirement status", + "Unknown visual/UI coverage status must appear in Blocking Items", + "Required visual/UI requirements without observable requirement text block PASS", + "`[BLOCKED: PROVIDER_EVIDENCE]` items remain provider evidence blockers", + "visual SSOT refs", + "external intake refs", + "provider evidence blockers", "product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements", "Visual Fidelity Evidence Matrix", "Use the behavior-testability checklist template as the visual gate authority", - "provider readiness status, evidence refs, and blockers", + "external intake readiness status when cited", + "visual SSOT refs, evidence refs", "source traceability", "Screenshot evidence level", "BDD, NFR, and Visual Fidelity readiness gate", @@ -1314,7 +1198,7 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: ): self.assertIn(term, checklist) for term in ( - "| Visual Item ID | Source `spec.md` section | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule |", + "| Visual Item ID | Source `spec.md` section | Requirement Status | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule |", "raw metadata completeness", "metadata index completeness proof", "node inventory parity", @@ -1329,7 +1213,7 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: self.assertIn("checklist artifacts only", checklist) self.assertIn("BDD, NFR, and Visual Fidelity readiness status", checklist) self.assertIn( - "Provider evidence readiness blockers return to `/speckit.specify` or provider intake, not `/speckit.clarify`", + "Provider evidence readiness blockers return to the external intake extension, not `/speckit.clarify`", checklist, ) @@ -1377,7 +1261,12 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "visual fidelity scope", "screenshot refs", "visual proof refs", - "Design Requirement trace refs", + "external visual SSOT refs", + "Visual Fidelity Evidence Matrix `Requirement Status`", + "Carry forward only visual rows with status `Required` or an accepted exception rule", + "Rows with status `Unknown` or `[BLOCKED: PROVIDER_EVIDENCE]` must already have blocked checklist PASS", + "report-only/no-write upstream gate failure", + "Do not project `Not Applicable` rows into visual planning outputs", "behavior/behavior-scenarios.draft.json", "report-only/no-write failure", "must not create or update behavior artifacts", @@ -1401,6 +1290,8 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "`checklists/behavior-testability.md` Visual Fidelity Readiness", "screenshot refs", "visual proof refs", + "visual SSOT refs", + "external evidence refs", "visual fidelity requirements", "test-first", "existing checklist format and user-story organization", @@ -1436,9 +1327,17 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "derive asset preparation, binding, implementation, and validation tasks", "Missing required client visual assets are readiness blockers", "Use Visual Fidelity Readiness as the only visual planning readiness source", + "`Requirement Status` as the visual task input filter", + "Generate visual tasks only for rows with status `Required` or `Required` plus an accepted exception", + "tasks for accepted exceptions must cite the exception rule", + "Do not generate implementation, validation, verification, evidence, asset binding, UI acceptance, or review tasks for `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]` rows", + "Route `Unknown` rows back to `/speckit.clarify`", + "route `[BLOCKED: PROVIDER_EVIDENCE]` rows to the external intake extension", + "`/speckit.tasks` must not discover visual requirements or repair evidence", + "only decomposes visual specifications that already passed the readiness gate", "Do not create a second readiness rule", - "Screenshot Coverage Matrix", - "Visual Restoration Trace", + "HTML SSOT bundles", + "external intake artifacts", "Do not generate execution metadata or write-path fields.", "Missing Required case coverage is a coverage blocker, not silently skipped work", "`negative`, `boundary`, `permission`, `validation`, or `state_conflict`", @@ -1449,9 +1348,19 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "visual task taxonomy", "story-local task granularity", "`visual_setup` -> `visual_validation` -> `visual_implementation` -> `visual_evidence`", + "`visual_setup` -> `visual_validation` -> `visual_implementation` -> `visual_evidence` -> `final_visual_review`", + "`asset_binding`", + "`final_visual_review`", + "`visual_setup`, `visual_validation`, `visual_implementation`, `visual_evidence`, `ui_acceptance`, `visual_verification`, `asset_binding`, and `final_visual_review` are the only visual task types", + "visual regression tests", + "screenshot comparison", + "accessibility check entrypoints", + "empty/error/loading/disabled/hover/focus states", + "license or authorization refs", "Do not create a separate visual lifecycle phase", "Visual tasks must name concrete source, test, fixture, configuration, or asset paths", "report a readiness blocker instead of generating an ambiguous visual task", + "Do not generate visual tasks for rows with `Requirement Status` `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`", "Client Asset Contract bindings, variants, and fallback policy", "Review evidence binding", "bounded repair permission", @@ -1486,11 +1395,22 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: self.assertIn("visual fidelity requirements", cross_agent) self.assertIn("screenshot refs", cross_agent) self.assertIn("visual proof refs", cross_agent) - self.assertIn("Design Requirement trace refs", cross_agent) + self.assertIn("visual SSOT refs", cross_agent) self.assertIn("Client Asset Contract", cross_agent) self.assertIn("asset binding", cross_agent) self.assertIn("local asset paths or code asset mappings", cross_agent) self.assertIn("missing required client visual assets", cross_agent) + self.assertIn("Visual Item ID", cross_agent) + self.assertIn("Requirement Status", cross_agent) + self.assertIn("visual shard candidates must come only from `tasks.md` visual task types", cross_agent) + self.assertIn("only `Required` or `Required` plus an accepted exception is executable", cross_agent) + self.assertIn("do not create visual shards for `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`", cross_agent) + self.assertIn("route `Unknown` back to `/speckit.clarify`", cross_agent) + self.assertIn("`[BLOCKED: PROVIDER_EVIDENCE]` to the external intake extension", cross_agent) + self.assertIn("missing visual proof refs", cross_agent) + self.assertIn("missing screenshot refs", cross_agent) + self.assertIn("final_visual_review tasks", cross_agent) + self.assertIn("must not discover visual requirements, repair Visual Fidelity Readiness evidence", cross_agent) self.assertIn("planned `U` design object", cross_agent) self.assertIn("specific source, test, fixture, configuration, or receipt paths", cross_agent) @@ -1632,9 +1552,13 @@ def test_behavior_first_templates_exist_and_are_decoupled(self) -> None: self.assertIn("explicitly declared in `spec.md`", behavior_checklist_template) self.assertIn("without prescribing architecture", behavior_checklist_template) self.assertIn("Visual Fidelity Readiness", behavior_checklist_template) + self.assertIn("Visual & UI Specification", behavior_checklist_template) + self.assertIn("Every identified visual/UI requirement uses status", behavior_checklist_template) + self.assertIn("Unknown visual/UI coverage status appears in Blocking Items", behavior_checklist_template) + self.assertIn("Required visual/UI requirements have observable requirement text", behavior_checklist_template) self.assertIn("Design-derived requirements", behavior_checklist_template) self.assertIn( - "provider readiness status, evidence refs, and blockers", + "external intake readiness status when cited, evidence refs, visual SSOT refs, and blockers", behavior_checklist_template, ) self.assertNotIn("raw metadata completeness", behavior_checklist_template) @@ -1644,6 +1568,7 @@ def test_behavior_first_templates_exist_and_are_decoupled(self) -> None: self.assertIn("component mappings and variant coverage", behavior_checklist_template) self.assertIn("responsive behavior is explicit", behavior_checklist_template) self.assertIn("accessibility requirements are explicit", behavior_checklist_template) + self.assertIn("Requirement Status", behavior_checklist_template) self.assertIn("Gate Status: PASS|BLOCKED", behavior_checklist_template) self.assertIn("Blocking Items:", behavior_checklist_template) self.assertIn("none", behavior_checklist_template) @@ -1688,228 +1613,6 @@ def test_behavior_first_templates_exist_and_are_decoupled(self) -> None: ) self.assertIn('"intent": "state_invariant"', assertions_template) - def test_figma_evidence_packet_template_contract(self) -> None: - self.assertTrue(FIGMA_EVIDENCE_PACKET_TEMPLATE_PATH.exists()) - document = FIGMA_EVIDENCE_PACKET_TEMPLATE_PATH.read_text(encoding="utf-8") - - required_terms = [ - "Figma Evidence Packet", - "Figma Source", - "Extraction Context", - "Screenshot Evidence", - "Screenshot Coverage Matrix", - "visual proof", - "Screenshot evidence must declare L0-L3 coverage and coverage gaps", - "not the primary Design Requirement Intake carrier", - "Screenshot evidence and the Screenshot Coverage Matrix record coverage facts and gaps only", - "must not decide visual planning readiness", - "proof sufficiency", - "checklist Gate Status", - "checklist Blocking Items", - "Screenshot level: L0|L1|L2|L3", - "L0: no screenshot evidence", - "L1: static screenshot reference", - "L2: viewport or state screenshot coverage", - "L3: visual diff baseline or approved visual proof", - "high-fidelity", - "pixel-perfect", - "brand-critical", - "visual regression", - "Screenshot refs", - "Viewport", - "State", - "Capture timestamp", - "Design version", - "Redaction required", - "Baseline usage", - "Missing coverage", - "Blocking item", - "Visual baseline usage: none|manual review|visual diff", - "Observed from Figma", - "Inferred from Structure", - "Missing / Needs Clarification", - "Out of Scope", - "Figma Intake Readiness", - "Figma Intake Readiness is provider source readiness only", - "separate from Visual Fidelity planning readiness", - "Visual Facts for Spec", - "Visual Item Matrix", - "one row per restorable UI surface, component, state, or visual proof obligation", - "provider-normalized visual facts", - "provider evidence blockers", - "proof level sufficiency", - "Visual Item ID", - "Figma frame/node refs", - "Requirement target", - "UI surface", - "Required fidelity: functional-equivalent|design-system-faithful|pixel-perfect|brand-critical|responsive-visual", - "Layout facts", - "Typography facts", - "Color/token facts", - "Effect facts", - "Asset refs", - "Variant/state evidence", - "Component requirement role", - "Component use constraint: visual-reference-only|must-reuse-existing|figma-export-required|unspecified", - "Constraint source refs", - "Copy/content constraint: no-new-copy|figma-copy-required|product-copy-required|unspecified", - "Drawing/asset constraint: no-self-draw|figma-export-required|existing-asset-required|unspecified", - "Required states", - "Required viewport coverage", - "Visual proof level: L0|L1|L2|L3", - "Allowed deviations", - "Spec requirement target", - "Client Asset Inventory", - "Asset ID", - "Asset role", - "Resource type: image|icon|video|lottie|svg|font", - "Figma node/component ref", - "Asset source strategy: figma_export_required|code_asset|existing_repo_asset|remote_runtime_asset", - "Export/use contract", - "Required variants", - "Fallback policy", - "Blocker status", - "Component Mapping", - "Figma component -> requirement-level component role", - "Variant -> observed state or semantic role", - "Existing code component constraint, only if explicitly provided", - "Visual-reference-only components", - "Must-reuse-existing components", - "No self-draw / no new copy constraints", - "Spec Handoff Notes", - "Open Questions", - "Frame / Node IDs", - "Required fidelity", - "[NEEDS CLARIFICATION]", - ] - for term in required_terms: - self.assertIn(term, document) - - forbidden_terms = [ - "Figma MCP authentication", - "run a script", - "implementation test", - "test-plan.md", - "Endpoint / Client Requirements", - "Acceptance Criteria", - ] - for term in forbidden_terms: - self.assertNotIn(term, document) - - def test_design_requirement_intake_template_contract(self) -> None: - self.assertTrue(DESIGN_REQUIREMENT_INTAKE_TEMPLATE_PATH.exists()) - document = DESIGN_REQUIREMENT_INTAKE_TEMPLATE_PATH.read_text(encoding="utf-8") - - required_terms = [ - "Design Requirement Intake", - "Design Sources", - "Provider Evidence", - "Page Inventory", - "Page Hierarchy", - "User Paths", - "Component Inventory", - "Existing code constraint, only if explicitly provided", - "Component States", - "Interaction Rules", - "Visual Tokens", - "Layout Rules", - "Responsive Rules", - "Motion Rules", - "State Coverage", - "Visual Acceptance Requirements", - "Visual Restoration Trace", - "accepted Visual Item ID", - "Do not copy the full provider Visual Item Matrix", - "Record only requirement-level facts promoted toward `spec.md`", - "must not decide visual planning readiness", - "checklist Gate Status", - "checklist Blocking Items", - "Provider source refs", - "Fidelity scope: functional-equivalent|design-system-faithful|pixel-perfect|brand-critical|responsive-visual", - "Layout constraints", - "Typography constraints", - "Color/token constraints", - "Effect constraints", - "Asset bindings", - "Requirement-level component role", - "Variant/state coverage", - "Component use constraint: visual-reference-only|must-reuse-existing|figma-export-required|unspecified", - "Constraint source refs", - "Copy/content constraint: no-new-copy|figma-copy-required|product-copy-required|unspecified", - "Drawing/asset constraint: no-self-draw|figma-export-required|existing-asset-required|unspecified", - "Required viewport coverage", - "Client Asset Contract", - "Asset ID", - "Required resource type", - "Asset source strategy", - "Required variants", - "Fallback policy", - "Blocker status", - "Screenshot Traceability", - "Design Requirement Intake remains provider-neutral", - "Visual proof refs", - "Supported visual facts", - "Unsupported assumptions", - "Screenshot-derived visual facts must include screenshot refs", - "screenshots must not create product semantics", - "Screenshot Traceability records supported facts and unsupported assumptions only", - "must not create an independent visual readiness decision", - "Traceability", - "Visual Item ID", - "Source refs", - "[NEEDS CLARIFICATION]", - ] - for term in required_terms: - self.assertIn(term, document) - - forbidden_terms = [ - "Figma MCP authentication", - "raw get_metadata", - "node coordinate dump", - "implementation test", - "test-plan.md", - "Endpoint / Client Requirements", - ] - for term in forbidden_terms: - self.assertNotIn(term, document) - - def test_requirement_merge_report_template_contract(self) -> None: - self.assertTrue(REQUIREMENT_MERGE_REPORT_TEMPLATE_PATH.exists()) - document = REQUIREMENT_MERGE_REPORT_TEMPLATE_PATH.read_text(encoding="utf-8") - - required_terms = [ - "Requirement Merge Report", - "Product Requirement Inputs", - "Design Requirement Inputs", - "Merge Rules", - "Product Requirement owns", - "Design Requirement owns", - "Conflict Resolution", - "Clarification Outputs", - "Baseline Spec Handoff", - "Design Requirement Promotion Rules", - "Promote screenshot-supported visual facts", - "Screenshot-implied business rules", - "Promote observed", - "Promote confirmed", - "Inferred", - "Missing", - "spec.md", - "[NEEDS CLARIFICATION]", - ] - for term in required_terms: - self.assertIn(term, document) - - forbidden_terms = [ - "Figma-only", - "directly call Figma MCP", - "generate tasks", - "write implementation", - "test-plan.md", - ] - for term in forbidden_terms: - self.assertNotIn(term, document) - def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: command = CHECKLIST_COMMAND_PATH.read_text(encoding="utf-8") template = BEHAVIOR_TEMPLATE_PATHS[ @@ -1918,13 +1621,15 @@ def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: for term in ( "Use the behavior-testability checklist template as the visual gate authority", - "provider readiness status, evidence refs, and blockers", + "external intake readiness status when cited", "Visual Fidelity Evidence Matrix alone decides visual planning readiness", "proof level sufficiency", "screenshot sufficiency", "accepted exception rules", "Read visual facts from `spec.md` and evidence refs", - "do not call Figma", + "do not call provider tools", + "re-extract external intake evidence", + "parse HTML SSOT bundles", "rebuild provider matrices", "another visual readiness path", CANONICAL_RESPONSIVE_VISUAL_RULE, @@ -1934,7 +1639,7 @@ def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: ): self.assertIn(term, command) for term in ( - "| Visual Item ID | Source `spec.md` section | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule |", + "| Visual Item ID | Source `spec.md` section | Requirement Status | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule |", "raw metadata completeness", "metadata index completeness proof", "node inventory parity", @@ -1952,8 +1657,9 @@ def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: "proof level sufficiency", "screenshot sufficiency", "accepted exception rules", - "does not call Figma", - "re-extract provider evidence", + "does not call provider tools", + "re-extract external intake evidence", + "parse HTML SSOT bundles", "rebuild provider matrices", "another visual readiness path", "Missing screenshot evidence sets Gate Status: BLOCKED", @@ -1962,12 +1668,14 @@ def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: CANONICAL_RESPONSIVE_VISUAL_RULE, "Visual Fidelity Evidence Matrix", "Source `spec.md` section", + "Requirement Status", + "Requirement Status is declared for each visual requirement or visual proof obligation", "Evidence Refs", "Exception Rule", "lists the item in Blocking Items", "Pixel-perfect", "Blocking Items", - "provider readiness status, evidence refs, and blockers", + "external intake readiness status when cited", "Use one Visual Fidelity Evidence Matrix as the single visual readiness record", "Do not add historical visual rules or alternate visual decision paths", ): @@ -1988,7 +1696,7 @@ def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: ) self.assertEqual( template.count( - "| Visual Item ID | Source `spec.md` section | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule |" + "| Visual Item ID | Source `spec.md` section | Requirement Status | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule |" ), 1, ) @@ -2013,69 +1721,6 @@ def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: for forbidden in FORBIDDEN_VISUAL_COMPAT_TERMS: self.assertNotIn(forbidden, lowered) - def test_figma_intake_contract_metadata_lint_rules(self) -> None: - self.assertTrue(FIGMA_INTAKE_CONTRACT_TEMPLATE_PATH.exists()) - document = FIGMA_INTAKE_CONTRACT_TEMPLATE_PATH.read_text(encoding="utf-8") - - required_sections = [ - "## Raw Metadata Shards", - "## Metadata Index Completeness", - "## Node Inventory Parity", - "## Evidence Readiness Gate", - "## Normalized Visual Item Matrix", - "## Blocker Lint Errors", - "## Gap Rules", - "## Preset Boundary", - ] - for section in required_sections: - self.assertIn(section, document) - - metadata_fields = [ - "figma-metadata.part-*.xml", - "figma-metadata.index.yaml", - "figma-node-inventory.yaml", - "raw get_metadata", - "byte_size", - "sha256", - "selected_subtree_complete", - "raw_metadata_complete", - "expected_root_node_ids", - "captured_root_node_ids", - "missing_root_node_ids", - "inventory_node_count + excluded_node_count + missing_node_count == raw_node_count", - "duplicate_node_count == 0", - "missing_node_count == 0", - "truncated_raw_evidence == false", - "node_inventory_coverage: 100%", - "parity_passed: true", - "provider source readiness only", - "Visual Fidelity planning readiness", - "proof sufficiency", - "checklist Gate Status", - "checklist Blocking Items", - "FIGMA_RAW_METADATA_MISSING", - "FIGMA_RAW_METADATA_SUMMARY_SUBSTITUTION", - "FIGMA_RAW_METADATA_TRUNCATED", - "FIGMA_SELECTED_SUBTREE_INCOMPLETE", - "FIGMA_METADATA_INDEX_MISSING", - "FIGMA_METADATA_PARITY_FAILED", - "FIGMA_READY_WITHOUT_COMPLETENESS_PROOF", - "speckit.design.visual_item_matrix.v1", - "schemas/speckit.design.visual-item-matrix.v1.schema.json", - "must not replace raw provider evidence", - "provider evidence blockers, not checklist Blocking Items", - "must not create a second visual readiness gate", - "observed variant/state evidence", - "requirement-level component roles", - "Explicit constraints such as must-reuse-existing, no-self-draw, or no-new-copy", - "constraint source refs", - "Required Figma intake artifacts and readiness gates", - "must not call Figma MCP", - "must not generate artifact instances", - ] - for field in metadata_fields: - self.assertIn(field, document) - def test_implement_command_is_agent_native_handoff_orchestrator(self) -> None: command = IMPLEMENT_COMMAND_PATH.read_text(encoding="utf-8") cross_agent = CROSS_AGENT_SUBAGENTS_PATH.read_text(encoding="utf-8") @@ -2114,6 +1759,15 @@ def test_implement_command_is_agent_native_handoff_orchestrator(self) -> None: "context_gaps", "task_status_update", "Do not edit `tasks.md`", + "Visual Implementation Boundary", + "visual task input filter", + "Visual Fidelity Readiness `Requirement Status` is `Required` or `Required` plus an accepted exception", + "Do not create handoffs or worker instructions for visual rows", + "`Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`", + "Route `Unknown` visual rows back to `/speckit.clarify`", + "route `[BLOCKED: PROVIDER_EVIDENCE]` visual rows to the external intake extension", + "`/speckit.implement` must not discover visual requirements, repair Visual Fidelity Readiness evidence", + "Visual worker receipts must reference the relevant Visual Item ID", ] for term in command_terms: self.assertIn(term, command) @@ -2278,87 +1932,6 @@ def test_behavior_first_schema_contracts_accept_minimal_examples(self) -> None: self.assertEqual(contract_type, schema["properties"]["contract_type"]["const"]) Draft202012Validator(schema).validate(examples[contract_type]) - def test_visual_item_matrix_schema_accepts_minimal_example(self) -> None: - schema = json.loads(VISUAL_ITEM_MATRIX_SCHEMA_PATH.read_text(encoding="utf-8")) - - self.assertEqual("object", schema["type"]) - self.assertIn("required", schema) - self.assertIn("properties", schema) - self.assertEqual( - "speckit.design.visual_item_matrix.v1", - schema["properties"]["contract_type"]["const"], - ) - self.assertIn("visual_items", schema["required"]) - Draft202012Validator(schema).validate(minimal_visual_item_matrix()) - - def test_visual_item_matrix_schema_rejects_missing_source_refs(self) -> None: - schema = json.loads(VISUAL_ITEM_MATRIX_SCHEMA_PATH.read_text(encoding="utf-8")) - matrix = minimal_visual_item_matrix() - matrix["visual_items"][0]["source_refs"] = [] - - with self.assertRaises(ValidationError): - Draft202012Validator(schema).validate(matrix) - - def test_visual_item_matrix_schema_accepts_responsive_visual_scope(self) -> None: - schema = json.loads(VISUAL_ITEM_MATRIX_SCHEMA_PATH.read_text(encoding="utf-8")) - matrix = minimal_visual_item_matrix() - matrix["visual_items"][0]["fidelity_scope"] = "responsive-visual" - - Draft202012Validator(schema).validate(matrix) - - def test_visual_item_matrix_validator_enforces_readiness_gate(self) -> None: - matrix = minimal_visual_item_matrix() - validate_visual_item_matrix_contract(matrix) - - matrix["readiness"]["node_inventory_coverage"] = 99 - with self.assertRaisesRegex(ValueError, "node_inventory_coverage 100"): - validate_visual_item_matrix_contract(matrix) - - def test_visual_item_matrix_validator_requires_sources_for_explicit_constraints(self) -> None: - matrix = minimal_visual_item_matrix() - matrix["visual_items"][0]["component_use_constraint"] = "must-reuse-existing" - - with self.assertRaisesRegex(ValueError, "constraint_source_refs"): - validate_visual_item_matrix_contract(matrix) - - def test_visual_item_matrix_validator_requires_l3_for_high_fidelity(self) -> None: - matrix = minimal_visual_item_matrix() - matrix["visual_items"][0]["fidelity_scope"] = "pixel-perfect" - - with self.assertRaisesRegex(ValueError, "requires L3 proof"): - validate_visual_item_matrix_contract(matrix) - - def test_design_requirement_intake_trace_validator_accepts_minimal_trace(self) -> None: - validate_design_requirement_intake_trace_contract( - minimal_design_requirement_intake_trace() - ) - - def test_design_requirement_intake_trace_validator_rejects_full_provider_matrix_copy(self) -> None: - intake = minimal_design_requirement_intake_trace() - intake["visual_restoration_trace"][0]["visual_item_matrix"] = minimal_visual_item_matrix() - - with self.assertRaisesRegex(ValueError, "must not copy full provider Visual Item Matrix"): - validate_design_requirement_intake_trace_contract(intake) - - def test_design_requirement_intake_trace_validator_rejects_provider_field_copy(self) -> None: - intake = minimal_design_requirement_intake_trace() - intake["visual_restoration_trace"][0].update( - { - "layout_facts": ["copied provider layout fact"], - "typography_facts": ["copied provider typography fact"], - "variant_state_evidence": [ - { - "variant_ref": "state=disabled", - "source_refs": ["figma://component/button-disabled"], - "observed_state_or_role": "disabled", - } - ], - } - ) - - with self.assertRaisesRegex(ValueError, "must record only requirement-level facts"): - validate_design_requirement_intake_trace_contract(intake) - def test_behavior_draft_schema_rejects_empty_given_when_then(self) -> None: schema = json.loads( BEHAVIOR_SCHEMA_PATHS["speckit.behavior.scenarios.draft.v1"].read_text( @@ -3904,6 +3477,65 @@ def test_validate_receipt_contract_accepts_behavior_evidence_references(self) -> RECEIPT_PATH, ) + def test_validate_receipt_contract_rejects_generic_visual_evidence(self) -> None: + handoff = minimal_handoff( + shard_id="S01-ui-01", + vertical_capability="ui", + allowed_write_paths=[f"{FEATURE_PATH}/src/ui/refund.tsx", f"{HANDOFF_DIR}/results/S01-ui-01.json"], + ) + handoff["allowed_read_paths"] = [ + TASKS_PATH, + f"{FEATURE_PATH}/checklists/behavior-testability.md", + f"{FEATURE_PATH}/contracts/uif/refund.json", + f"{FEATURE_PATH}/quickstart.md", + ] + handoff["task_text"] = [ + "T010 visual_verification for Visual Item ID VUI-001 with Requirement Status Required" + ] + receipt_path = f"{HANDOFF_DIR}/results/S01-ui-01.json" + handoff["task_status_update"]["receipt_path"] = receipt_path + + with self.assertRaisesRegex(ValueError, "Visual Item ID"): + validate_receipt_contract( + handoff, + minimal_receipt( + shard_id="S01-ui-01", + changed_paths=[f"{FEATURE_PATH}/src/ui/refund.tsx"], + validation_evidence=["unit tests passed"], + ), + receipt_path, + ) + + def test_validate_receipt_contract_accepts_visual_evidence_references(self) -> None: + handoff = minimal_handoff( + shard_id="S01-ui-01", + vertical_capability="ui", + allowed_write_paths=[f"{FEATURE_PATH}/src/ui/refund.tsx", f"{HANDOFF_DIR}/results/S01-ui-01.json"], + ) + handoff["allowed_read_paths"] = [ + TASKS_PATH, + f"{FEATURE_PATH}/checklists/behavior-testability.md", + f"{FEATURE_PATH}/contracts/uif/refund.json", + f"{FEATURE_PATH}/quickstart.md", + ] + handoff["task_text"] = [ + "T010 visual_verification for Visual Item ID VUI-001 with Requirement Status Required" + ] + receipt_path = f"{HANDOFF_DIR}/results/S01-ui-01.json" + handoff["task_status_update"]["receipt_path"] = receipt_path + + validate_receipt_contract( + handoff, + minimal_receipt( + shard_id="S01-ui-01", + changed_paths=[f"{FEATURE_PATH}/src/ui/refund.tsx"], + validation_evidence=[ + "Visual Item ID VUI-001 Requirement Status Required verified with screenshot ref quickstart.md#visual-refund" + ], + ), + receipt_path, + ) + def test_handoff_schema_rejects_worker_that_can_update_tasks_md(self) -> None: schema = json.loads(HANDOFF_SCHEMA_PATH.read_text(encoding="utf-8")) handoff = minimal_handoff() @@ -4021,22 +3653,21 @@ def test_readme_contract(self) -> None: self.assertIn("BDD readiness gate", readme) self.assertIn("NFR readiness", readme) self.assertIn("BDD/NFR/applicable Visual Fidelity", readme) - self.assertIn("Design Requirement Intake", readme) - self.assertIn("Requirement Merge", readme) - self.assertIn("Product Requirement + Design Requirement", readme) - self.assertIn("rejects full provider Visual Item Matrix copies inside Visual Restoration Trace rows", readme) - self.assertIn("stable Visual Item ID", readme) - self.assertIn("does not translate Figma variants into code props", readme) - self.assertIn("requirement-level component roles", readme) - self.assertIn("Visual Restoration Trace rows", readme) - self.assertIn("Visual Item Matrix rows", readme) - self.assertIn("Figma is a Design Requirement provider", readme) - self.assertIn("Figma Evidence Packet", readme) - self.assertIn("direct Figma URL input", readme) - self.assertIn("runtime agent has Figma MCP access", readme) + self.assertIn("External Intake And Visual SSOT", readme) + self.assertIn("spec-kit-intake", readme) + self.assertIn("external intake evidence + visual SSOT refs -> /speckit.specify -> baseline spec.md", readme) + self.assertIn("does not perform intake", readme) + self.assertIn("parse HTML SSOT bundles", readme) + self.assertIn("decide provider source readiness", readme) + self.assertIn("visual SSOT refs", readme) + self.assertIn("external evidence refs", readme) + self.assertIn("source-backed facts", readme) + self.assertIn("Product semantics implied only by provider evidence remain `[NEEDS CLARIFICATION]`", readme) + self.assertIn("speckit.intake.visual-design", readme) + self.assertIn("speckit.intake.html-ssot", readme) self.assertIn("Visual Fidelity readiness gate", readme) self.assertIn("Screenshot is evidence, not intake", readme) - self.assertIn("optional but strongly recommended provider evidence", readme) + self.assertIn("optional but strongly recommended visual evidence", readme) self.assertIn("L0 No Screenshot", readme) self.assertIn("L1 Key Screenshots", readme) self.assertIn("L2 State + Viewport Matrix", readme) @@ -4054,29 +3685,21 @@ def test_readme_contract(self) -> None: self.assertIn("Visual Fidelity Evidence Matrix", readme) self.assertIn("visual requirement or visual proof obligation", readme) self.assertIn("single visual readiness record", readme) - self.assertIn("Provider evidence artifacts may record screenshot refs", readme) self.assertIn("only the Visual Fidelity Evidence Matrix decides visual planning readiness", readme) self.assertIn("proof sufficiency", readme) self.assertIn("accepted exception rules", readme) - self.assertIn("preset defines the required design intake and provider readiness artifact structure", readme) - self.assertIn("runtime agent or external Figma intake", readme) - self.assertIn("does not generate the artifact instances", readme) + self.assertIn("The intake extension owns source capture", readme) + self.assertIn("HTML SSOT bundle contracts", readme) + self.assertIn("source-side validators live in the `spec-kit-intake` extension", readme) self.assertIn("[BLOCKED: PROVIDER_EVIDENCE]", readme) - self.assertIn("Provider evidence blockers do not become `[NEEDS CLARIFICATION]`", readme) self.assertNotIn( "writes or marks it as `[NEEDS CLARIFICATION]`", readme, ) - self.assertIn("raw metadata completeness", readme) - self.assertIn("node inventory parity", readme) - self.assertIn("speckit.design.visual_item_matrix.v1", readme) - self.assertIn("schemas/speckit.design.visual-item-matrix.v1.schema.json", readme) - self.assertIn("raw Figma evidence remains the source of truth", readme) - self.assertIn("provider-ready", readme) - self.assertIn("It does not decide visual planning readiness", readme) - self.assertIn("does not provide Figma MCP connection, authentication, or execution", readme) - self.assertIn("clarifies design-derived gaps already written in `spec.md`", readme) - self.assertIn("does not call Figma", readme) + self.assertIn("source-side readiness", readme) + self.assertIn("The Visual Fidelity Evidence Matrix remains the only planning readiness gate", readme) + self.assertIn("clarifies evidence-derived gaps already written in `spec.md`", readme) + self.assertIn("does not call provider tools", readme) self.assertIn("explicit non-functional requirement declarations", readme) self.assertIn("Required, Not Applicable, or Unknown", readme) self.assertIn("missing or unverifiable NFR assumptions", readme) @@ -4138,7 +3761,8 @@ def test_readme_contract(self) -> None: self.assertIn("## 1.0.3", changelog) self.assertIn("Final Code Review", changelog) self.assertIn("structured code review receipts", changelog) - self.assertIn("rejects full provider Visual Item Matrix copies inside Design Requirement Intake Visual Restoration Trace rows", changelog) + self.assertIn("Migrated product, design, provider, and HTML intake ownership out of the workflow preset", changelog) + self.assertIn("external intake refs and visual SSOT refs", changelog) self.assertIn("/speckit.tasks` defines validation, visual verification, contract validation, data-side-effect validation, integration/e2e validation", changelog) self.assertIn("/speckit.implement` only executes those tasks and records receipt evidence", changelog) self.assertIn("agent-native handoff orchestration", changelog) @@ -4236,18 +3860,16 @@ def test_extension_governance_document_contract(self) -> None: "structured JSON artifacts require schemas", "validators/", "Do not put downstream prohibitions in upstream commands", - "Design Requirement Intake", - "Requirement Merge", - "Figma is a provider-specific design source", + "Source intake artifacts belong in an extension, not this preset", + "External intake owns source capture", + "rendered HTML SSOT bundles", "Behavior-first extension rule", "BDD and UIF artifacts need independent templates", "`/speckit.constitution`: constitution governance and project principles only", "`/speckit.checklist`: checklist artifacts and BDD/NFR/Visual Fidelity readiness gates only", - "Figma Evidence Packet", - "Screenshot is provider evidence", - "Screenshots must not become the primary Design Requirement Intake carrier", - "Provider evidence artifacts may record screenshot refs, visual proof refs", - "They must not", + "external intake refs", + "visual SSOT refs", + "External evidence refs must not", "decide visual planning readiness", "proof sufficiency", "Visual Fidelity Evidence Matrix", @@ -4267,10 +3889,9 @@ def test_extension_governance_document_contract(self) -> None: "accepted exception rules", "checklist Gate Status", "checklist Blocking Items", - "Provider source readiness remains separate", - "packaged evidence templates are allowed preset artifacts", - "Figma MCP execution, hooks, adapter scripts, and authentication", - "external design extraction is not a clarification responsibility", + "Source-side intake readiness remains separate", + "Provider tools, provider execution, hooks, adapter scripts", + "External design extraction is not a clarification responsibility", "NFR readiness belongs in `spec.md` product requirements", "`/speckit.plan`: Phase 0 behavior projection, planning artifacts, and formal contracts", "`/speckit.tasks` owns implementation, validation, visual verification, contract validation, data-side-effect validation, integration/e2e validation, and code review task definition in `tasks.md`", diff --git a/presets/workflow-preset/validators/speckit_implement_contract.py b/presets/workflow-preset/validators/speckit_implement_contract.py index dfb013b8e8..d817c8b9ca 100644 --- a/presets/workflow-preset/validators/speckit_implement_contract.py +++ b/presets/workflow-preset/validators/speckit_implement_contract.py @@ -22,41 +22,6 @@ ) CASE_TYPES = {"positive", "negative", "boundary", "permission", "validation", "state_conflict"} FAILURE_CASE_TYPES = {"negative", "permission", "validation", "state_conflict"} -EXPLICIT_COMPONENT_USE_CONSTRAINTS = { - "visual-reference-only", - "must-reuse-existing", - "figma-export-required", -} -EXPLICIT_COPY_CONSTRAINTS = { - "no-new-copy", - "figma-copy-required", - "product-copy-required", -} -EXPLICIT_DRAWING_CONSTRAINTS = { - "no-self-draw", - "figma-export-required", - "existing-asset-required", -} -PROVIDER_MATRIX_COPY_KEYS = { - "figma_frame_node_refs", - "requirement_target", - "layout_facts", - "typography_facts", - "color_token_facts", - "effect_facts", - "variant_state_evidence", - "visual_proof_level", - "spec_requirement_target", -} -FULL_PROVIDER_MATRIX_KEYS = { - "source", - "readiness", - "visual_items", - "visual_item_matrix", - "provider_visual_item_matrix", -} - - def _duplicate_ids(items: list[dict[str, Any]], *, key: str, context: str) -> set[str]: seen: set[str] = set() duplicates: set[str] = set() @@ -315,78 +280,7 @@ def validate_behavior_case_coverage( raise ValueError(f"Required case {context} missing quickstart.md evidence") -def validate_visual_item_matrix_contract(matrix: dict[str, Any]) -> None: - readiness = matrix.get("readiness", {}) - if readiness.get("status") == "PASS": - if readiness.get("raw_metadata_complete") is not True: - raise ValueError("visual item matrix PASS requires raw_metadata_complete") - if readiness.get("node_inventory_coverage") != 100: - raise ValueError("visual item matrix PASS requires node_inventory_coverage 100") - if readiness.get("parity_passed") is not True: - raise ValueError("visual item matrix PASS requires parity_passed") - if readiness.get("blocker_lint_errors"): - raise ValueError("visual item matrix PASS requires no blocker_lint_errors") - - visual_items = matrix.get("visual_items", []) - if not visual_items: - raise ValueError("visual item matrix must include visual_items") - _duplicate_ids(visual_items, key="id", context="visual item matrix") - - for item in visual_items: - item_id = item.get("id", "") - explicit_component = item.get("component_use_constraint") in EXPLICIT_COMPONENT_USE_CONSTRAINTS - explicit_copy = item.get("copy_content_constraint") in EXPLICIT_COPY_CONSTRAINTS - explicit_drawing = item.get("drawing_asset_constraint") in EXPLICIT_DRAWING_CONSTRAINTS - if (explicit_component or explicit_copy or explicit_drawing) and not item.get( - "constraint_source_refs" - ): - raise ValueError( - f"visual item {item_id} explicit constraints require constraint_source_refs" - ) - - if item.get("fidelity_scope") in {"pixel-perfect", "brand-critical"}: - if item.get("visual_proof_level") != "L3": - raise ValueError( - f"visual item {item_id} pixel-perfect or brand-critical requires L3 proof" - ) - if not item.get("screenshot_refs"): - raise ValueError( - f"visual item {item_id} pixel-perfect or brand-critical requires screenshot_refs" - ) - - -def validate_design_requirement_intake_trace_contract(intake: dict[str, Any]) -> None: - rows = intake.get("visual_restoration_trace", []) - if rows in (None, []): - return - if not isinstance(rows, list): - raise ValueError("visual restoration trace must be a list") - - _duplicate_ids(rows, key="visual_item_id", context="visual restoration trace") - - for row in rows: - item_id = row.get("visual_item_id", "") - copied_structures = FULL_PROVIDER_MATRIX_KEYS.intersection(row) - if copied_structures: - raise ValueError( - f"visual restoration trace {item_id} must not copy full provider Visual Item Matrix" - ) - - copied_provider_fields = PROVIDER_MATRIX_COPY_KEYS.intersection(row) - if len(copied_provider_fields) >= 3: - raise ValueError( - f"visual restoration trace {item_id} must record only requirement-level facts" - ) - - if not row.get("requirement_id") and not row.get("spec_requirement_ref"): - raise ValueError(f"visual restoration trace {item_id} missing requirement reference") - if not row.get("supporting_evidence_refs") and not row.get("provider_source_refs"): - raise ValueError( - f"visual restoration trace {item_id} missing supporting evidence refs" - ) - - -def _handoff_has_behavior_contract_context(handoff: dict[str, Any]) -> bool: +def _handoff_requires_traceable_validation_evidence(handoff: dict[str, Any]) -> bool: markers = ( "contracts/bdd/", "contracts/uif/", @@ -394,6 +288,19 @@ def _handoff_has_behavior_contract_context(handoff: dict[str, Any]) -> bool: "BehaviorScenarioInstance", "BDD scenario", "behavior assertion", + "Visual Item ID", + "Requirement Status", + "visual_setup", + "visual_validation", + "visual_implementation", + "visual_evidence", + "ui_acceptance", + "visual_verification", + "asset_binding", + "final_visual_review", + "screenshot ref", + "visual proof ref", + "Client Asset Contract", ) values: list[str] = [] for key in ("allowed_read_paths", "allowed_write_paths", "task_text"): @@ -404,11 +311,20 @@ def _handoff_has_behavior_contract_context(handoff: dict[str, Any]) -> bool: return any(marker in haystack for marker in markers) -def _receipt_references_behavior_evidence(receipt: dict[str, Any]) -> bool: +def _receipt_references_traceable_validation_evidence(receipt: dict[str, Any]) -> bool: markers = ( "SCN-", "AST-", "BDD", + "UIF-", + "Visual Item ID", + "Requirement Status", + "screenshot ref", + "screenshot refs", + "visual proof ref", + "visual proof refs", + "Client Asset Contract", + "quickstart validation", "contracts/bdd/", "contracts/uif/", "contracts/behavior/", @@ -817,12 +733,14 @@ def validate_receipt_contract( if not receipt.get("validation_evidence"): raise ValueError("receipt validation_evidence must not be empty") - if _handoff_has_behavior_contract_context( + if _handoff_requires_traceable_validation_evidence( handoff - ) and not _receipt_references_behavior_evidence(receipt): + ) and not _receipt_references_traceable_validation_evidence(receipt): raise ValueError( "receipt validation_evidence must reference relevant BDD scenario, " - "behavior assertion, API contract, or quickstart path" + "behavior assertion, API contract, UIF path, Visual Item ID, " + "screenshot ref, visual proof ref, Client Asset Contract entry, " + "or quickstart path" ) for path in receipt.get("changed_paths", []): diff --git a/tests/test_presets.py b/tests/test_presets.py index c8f26ea3aa..884a3776f2 100644 --- a/tests/test_presets.py +++ b/tests/test_presets.py @@ -4677,7 +4677,7 @@ def test_workflow_preset_integration_release_payload_contract(self): assert "test -f .specify/templates/tasks-template.md" in workflow_text assert ( "test -f .specify/presets/workflow-preset/schemas/" - "speckit.design.visual-item-matrix.v1.schema.json" + "speckit.implement.receipt.v1.schema.json" ) in workflow_text def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self): @@ -4719,7 +4719,7 @@ def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self): assert "registry_version == manifest_version" in verify_run assert ( "test -f .specify/presets/workflow-preset/schemas/" - "speckit.design.visual-item-matrix.v1.schema.json" + "speckit.implement.receipt.v1.schema.json" ) in verify_run assert ( 'for extension_id in arch discovery intake preview repository-governance; do'