From be1e554b39cac403591a057777b75e536c003eef Mon Sep 17 00:00:00 2001 From: bigben <245982990@qq.com> Date: Sun, 26 Jul 2026 16:33:29 +0800 Subject: [PATCH] refactor(workflow-preset): decouple UI/UX specification Assisted-by: Codex (model: GPT-5, autonomous) --- presets/catalog.community.json | 2 +- presets/catalog.json | 2 +- presets/workflow-preset/CHANGELOG.md | 9 + presets/workflow-preset/README.md | 91 +- .../commands/speckit.checklist.md | 64 +- .../commands/speckit.clarify.md | 44 +- .../commands/speckit.implement.md | 26 +- .../workflow-preset/commands/speckit.plan.md | 17 +- .../commands/speckit.specify.md | 47 +- .../workflow-preset/commands/speckit.tasks.md | 54 +- .../docs/extension-governance.md | 34 +- presets/workflow-preset/preset.yml | 10 +- .../behavior-testability-checklist.md | 65 +- .../templates/plan-template.md | 10 +- .../templates/spec-template.md | 53 + .../contracts/speckit-cross-agent-protocol.md | 10 +- .../speckit-cross-agent-subagents.md | 12 +- .../tests/test_preset_contract.py | 918 +++++------------- .../validators/speckit_implement_contract.py | 30 +- 19 files changed, 531 insertions(+), 967 deletions(-) create mode 100644 presets/workflow-preset/templates/spec-template.md diff --git a/presets/catalog.community.json b/presets/catalog.community.json index f1c21d6649..6e7319d12b 100644 --- a/presets/catalog.community.json +++ b/presets/catalog.community.json @@ -682,7 +682,7 @@ "speckit_version": ">=0.8.10.dev0" }, "provides": { - "templates": 22, + "templates": 23, "commands": 8 }, "tags": [ diff --git a/presets/catalog.json b/presets/catalog.json index 199c02544e..abf58ff8bb 100644 --- a/presets/catalog.json +++ b/presets/catalog.json @@ -40,7 +40,7 @@ }, "provides": { "commands": 8, - "templates": 22 + "templates": 23 }, "tags": [ "behavior", diff --git a/presets/workflow-preset/CHANGELOG.md b/presets/workflow-preset/CHANGELOG.md index 0a863478d4..477c51faf3 100644 --- a/presets/workflow-preset/CHANGELOG.md +++ b/presets/workflow-preset/CHANGELOG.md @@ -2,6 +2,15 @@ ## Unreleased +- Added a wrapping `spec-template` as the single owner of the source-agnostic + `UI/UX Specification` structure, including stable `UI-###` and `UX-###` + requirements. +- Removed design-provider and intake-evidence dependencies from runtime + commands, templates, validators, protocols, and public documentation. +- Separated UI/UX Applicability (`Required`, `Not Applicable`, `Unknown`) from + specification Readiness (`Ready`, `Blocked`) across checklist, planning, + task, implementation, and receipt contracts. + ## 1.3.12 - 2026-07-01 - Added a shared cross-agent protocol contract with command profiles for specify, plan, tasks, analyze, and implement, while keeping persistent handoff orchestration scoped to `/speckit.implement`. diff --git a/presets/workflow-preset/README.md b/presets/workflow-preset/README.md index 3780b1e685..9a158b1e45 100644 --- a/presets/workflow-preset/README.md +++ b/presets/workflow-preset/README.md @@ -2,7 +2,7 @@ This Spec Kit community preset combines behavior-first specification, design-aware planning, scoped change governance, and agent-native handoff orchestration. -It wraps `/speckit.specify`, `/speckit.clarify`, `/speckit.checklist`, `/speckit.constitution`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.analyze` with BDD, NFR, and applicable Visual Fidelity readiness gates, Change Scope Granularity and Architecture SSOT governance, Phase 0 behavior projection, optional design artifacts for internal object design and service sequencing, visual restoration traceability, and task-time validation strategy derivation. It replaces `/speckit.implement` with a Core Agent, Vertical Planner Agent, and Worker Agent orchestration contract that writes handoffs to disk. +It wraps `/speckit.specify`, `/speckit.clarify`, `/speckit.checklist`, `/speckit.constitution`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.analyze` with BDD, NFR, and UI/UX specification readiness gates, Change Scope Granularity and Architecture SSOT governance, Phase 0 behavior projection, optional design artifacts for internal object design and service sequencing, and task-time validation strategy derivation. It replaces `/speckit.implement` with a Core Agent, Vertical Planner Agent, and Worker Agent orchestration contract that writes handoffs to disk. ## Goal @@ -10,7 +10,7 @@ It wraps `/speckit.specify`, `/speckit.clarify`, `/speckit.checklist`, `/speckit The preset has four goals: -- Make BDD/NFR/applicable Visual Fidelity readiness explicit before planning by checking `spec.md` for observable, verifiable behavior, explicit non-functional requirement declarations, and design evidence when relevant. +- Make BDD/NFR/UI/UX readiness explicit before planning by checking `spec.md` for observable, verifiable behavior, explicit non-functional requirement declarations, and complete UI/UX requirements when relevant. - Project accepted requirements into BDD, UIF intent, and fixture intent drafts during `/speckit.plan` Phase 0. - Preserve richer planning intent so downstream tasks and implementation do not lose object design, service-flow, or validation decisions. - Keep implementation scope explicit by applying Change Scope Granularity from planning onward: M + U boundaries are locked before execution maps them to concrete paths and O-level edits. @@ -22,7 +22,7 @@ Large Spec Kit features can overload the implementation phase. A single `/specki `workflow-preset` reduces that failure mode in three complementary ways: -- Requirement enhancement keeps product requirements in `spec.md` and gates planning with a BDD/NFR/applicable Visual Fidelity readiness checklist. +- Requirement enhancement keeps product requirements in `spec.md` and gates planning with a BDD/NFR/UI/UX specification readiness checklist. - Scope governance keeps broad repository context from becoming implementation scope by applying the R/M/U/O model once planning begins. - Plan enhancement projects accepted behavior drafts, then gives object design, service sequencing, and validation intent stable homes before tasks are generated. - Implement handoff orchestration slices work by lifecycle and vertical capability, then gives each Worker Agent a compact digest, scoped paths, validation commands, and a receipt contract instead of the full planning corpus. @@ -35,14 +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. -- Consumes confirmed product facts, external intake facts, visual SSOT refs, HTML SSOT refs, structured IR 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. +- Adds a wrapping `spec-template` that owns the stable source-agnostic `UI/UX Specification` shape. +- Assigns stable `UX-###` IDs to journeys, navigation, feedback, and usability outcomes and `UI-###` IDs to surfaces, states, responsive behavior, accessibility, content, and observable visual outcomes. +- Wraps `/speckit.checklist` to add `checklists/behavior-testability.md` as a BDD readiness gate, NFR readiness gate, and UI/UX specification 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 visual requirements for source traceability, external intake readiness status when cited, HTML SSOT refs, structured IR refs, evidence refs, provider blocker status, and visual fidelity scope before planning. -- Preserves stable visual SSOT refs, HTML SSOT refs, structured IR 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. +- Adds a UI/UX Coverage Matrix that keeps requirement Applicability (`Required | Not Applicable | Unknown`) separate from specification Readiness (`Ready | Blocked`). +- Checks experience goals, navigation, interaction feedback, UI states, responsive behavior, accessibility, content, visual hierarchy, and objective acceptance criteria before planning. - 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`. @@ -58,11 +57,11 @@ Governance capabilities: Planning capabilities: - Wraps `/speckit.plan` to run Phase 0 preflight, Phase 0 behavior projection, and optional/contextual design artifacts when useful. -- Requires the BDD, NFR, and applicable Visual Fidelity readiness gates to pass before planning. +- Requires the BDD, NFR, and UI/UX specification readiness gates to pass before planning. - Treats Phase 0 preflight failures as report-only/no-write failures. - Writes `behavior/bdd.draft.feature`, `behavior/behavior-scenarios.draft.json`, `behavior/uif.intent.json`, and `behavior/data-fixtures.intent.json` during Phase 0 behavior projection. - Projects Required case coverage into `behavior/behavior-scenarios.draft.json` instead of allowing Required cases to disappear behind positive-only drafts. -- Consumes Phase 0 behavior drafts and must formalize them into `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` when the BDD, NFR, and applicable Visual Fidelity readiness gates have passed. +- Consumes Phase 0 behavior drafts and must formalize them into `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` when the BDD, NFR, and UI/UX specification readiness gates have passed. - Requires failure scenarios in `contracts/behavior/` to carry an explicit trigger, case kind, error code, failure feedback, and state invariant, rollback, or compensation assertion reference. - Records `N/A or blocker` and `case_coverage_blockers` when behavior drafts cannot be formalized. - Keeps `plan.md` focused on technical decisions and navigation. @@ -70,8 +69,7 @@ Planning capabilities: - Stores internal object design in `class-diagram.md`. - 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 carries forward visual/IR source refs, readiness inputs, accepted exceptions, related contract paths, and unresolved blockers; contracts formalize visual interaction and state constraints; contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing. -- For visual restoration work, visual SSOT refs carry requirement traceability while Client Asset Contract entries carry local asset binding expectations. +- When UI/UX requirements are in scope, `research.md` records planning decisions, contracts formalize accepted interaction and state constraints, and `contracts/sequences.md` records UI state flow only when it affects cross-boundary sequencing. - 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: @@ -80,10 +78,10 @@ Task generation capabilities: - Uses formal BDD, UIF, and behavior contracts to derive test-first fixture, acceptance test, implementation, and verification tasks. - Treats missing Required failure behavior scenarios as blockers instead of generating complete-looking happy-path-only tasks. - Performs test strategy derivation from BDD contracts, Expected UIF contracts, behavior contracts, interface contracts, `research.md`, and `quickstart.md` without writing a separate strategy artifact. -- Derives paired UI implementation and acceptance tasks when UIF contracts, Visual Fidelity Readiness rows, visual acceptance requirements, or Client Asset Contract entries apply. -- Preserves visual/IR traceability refs on UI implementation, asset binding, and non-visual acceptance tasks without generating visual validation, screenshot comparison, visual diff, baseline capture, or final visual review work. +- Derives UI setup, implementation, accessibility, and acceptance tasks from Required and Ready `UI-###` / `UX-###` requirements. +- Preserves UI/UX requirement IDs through implementation and acceptance tasks. - Uses design artifacts to derive implementation, integration, orchestration, failure-handling, and validation tasks. -- Adds Final Code Review tasks for boundary, interface contract, visual, data side-effect, behavior contract, sequence consistency, and asset binding scopes when applicable. +- Adds Final Code Review tasks for boundary, interface contract, UI/UX, data side-effect, behavior contract, and sequence consistency scopes when applicable. - Preserves the existing checklist format and user-story organization. Analysis capabilities: @@ -105,8 +103,8 @@ Implementation capabilities: - Keeps manifest, handoff, and receipt JSON contracts in standalone schema files. - Splits implement gates into manifest structure, handoff structure, dispatch readiness, receipt structure, and commit readiness validation. - Requires behavior-linked `validation_evidence` in worker receipts when behavior contracts are in handoff context. -- Requires Final Code Review receipts to include post-implementation data side-effect review, visual consistency review, and asset binding review of actual implementation diffs before task status commit when those scopes apply. -- Requires Final Code Review receipts to reconcile implemented UI states, viewport behavior, visual/IR traceability refs, and Client Asset Contract bindings when UI or asset scopes apply. +- Requires Final Code Review receipts to include post-implementation data side-effect review and UI/UX consistency review of actual implementation diffs before task status commit when those scopes apply. +- Requires Final Code Review receipts to reconcile implemented journeys, UI states, viewport behavior, accessibility behavior, content, and visible results with accepted `UI-###` and `UX-###` requirements. - Assigns every handoff a lifecycle stage and vertical capability such as `domain-model`, `api-contract`, `persistence`, `service-flow`, `ui`, `test-validation`, `documentation`, `integration`, or `cleanup`. - Supports direct single-shard execution with `Use handoff JSON `. - Blocks worker execution when generated context has unresolved `context_gaps`. @@ -127,16 +125,16 @@ Context-load controls: 1. `/speckit.constitution` preserves Change Scope Granularity and Architecture SSOT governance when the project constitution is created or updated. 2. `/speckit.specify` keeps the core requirements output in `spec.md`. 3. `/speckit.clarify` resolves requirement ambiguity in `spec.md`. -4. `/speckit.checklist` checks BDD, NFR, and applicable Visual Fidelity readiness directly from `spec.md` and blocks planning when readiness gaps remain. +4. `/speckit.checklist` checks BDD, NFR, and UI/UX specification readiness directly from `spec.md` and blocks planning when readiness gaps remain. 5. `/speckit.plan` applies Change Scope Granularity, runs Phase 0 preflight, performs Phase 0 behavior projection, formalizes behavior drafts into contracts, and adds design artifacts when they help implementation. -6. `/speckit.tasks` reads the core plan outputs, optional design artifacts, behavior contracts, interface contracts, `research.md`, and `quickstart.md`, then produces executable tasks with inline test level, data strategy, visual/IR traceability refs, asset binding, non-visual acceptance, and evidence requirements. +6. `/speckit.tasks` reads the core plan outputs, optional design artifacts, behavior contracts, interface contracts, `research.md`, and `quickstart.md`, then produces executable tasks with inline test level, data strategy, UI/UX requirement IDs, acceptance criteria, and evidence requirements. 7. `/speckit.analyze` checks vertical consistency across requirements, behavior drafts, contracts, and tasks. 8. `/speckit.implement` enters Core Agent mode when no handoff path is provided. 9. The Core Agent writes `context-index.json` and dispatches one Vertical Planner Agent per active vertical capability. 10. Vertical Planner Agents produce shard plans, handoff drafts, context digest drafts, and allowed path derivations. 11. The Core Agent assembles final handoffs and writes `handoff-manifest.json`. 12. Worker Agents run only from persisted handoff JSON files and write receipts. -13. Final Code Review checks boundary, contract, visual, asset binding, sequence, implementation data side effects, and real e2e readiness. +13. Final Code Review checks boundary, contract, UI/UX consistency, sequence, implementation data side effects, and real e2e readiness. 14. The Core Agent reviews receipts, updates `tasks.md`, runs integration verification, and reports closeout status. ## Non-Goals @@ -177,42 +175,15 @@ Run the behavior-first workflow: /speckit.analyze ``` -### External Intake And Visual SSOT +### Source-Agnostic UI/UX Requirements -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. +`workflow-preset` accepts explicit product text and confirmed product decisions without depending on how those requirements were collected. ```text -external intake evidence + visual SSOT refs + HTML SSOT refs + structured IR refs -> /speckit.specify -> baseline spec.md +confirmed product requirements -> /speckit.specify -> UI/UX Specification in spec.md ``` -`/speckit.specify` does not perform intake, call provider tools, parse HTML SSOT bundles, re-parse structured IR artifacts, or decide provider source readiness. It consumes confirmed source-backed facts and preserves visual SSOT refs, HTML SSOT refs, structured IR refs, evidence refs, state/viewport refs, -screenshots, visual proof refs, and Client Asset Contract facts in `spec.md`. -Missing product decisions become `[NEEDS CLARIFICATION]`; missing provider or intake evidence for a feature that depends on that evidence becomes `[BLOCKED: PROVIDER_EVIDENCE]`; features that do not depend on HTML SSOT, structured IR, or provider evidence are `Not Applicable`. - -### Provider Evidence Refs - -Screenshots, visual proof refs, HTML SSOT refs, structured IR refs, and provider artifacts are evidence refs, not intake execution. This preset only references them through `spec.md` visual requirements and the Visual Fidelity Evidence Matrix. - -Evidence refs can support layout, density, state, viewport, asset, and visual facts when source-backed. They cannot upgrade product semantics such as permissions, business effects, validation rules, or data ownership into confirmed requirements. - -The Visual Fidelity Evidence Matrix is the single visual readiness record. It records requirement status, source refs, HTML SSOT refs, structured IR refs, other evidence refs, provider blocker status, accepted exception refs, Gate Status, and Blocking Items. It does not define visual validation work, screenshot comparison, visual diff, baseline capture, or final visual review. - -### Provider Design And HTML SSOT Input - -Use the `spec-kit-intake` extension for provider design, HTML SSOT, or structured IR capture: - -```text -/speckit.intake.visual-design -/speckit.intake.figma2htmlssot -``` - -The intake extension owns source capture, provider evidence, raw provider metadata, -node inventory parity, rendered HTML visual SSOT bundles, structured IR artifacts, -source-side readiness, and blocker codes. This preset consumes only the confirmed -artifact refs, readiness inputs, blocker status, and traceability refs written or cited in `spec.md`. +UI/UX Applicability uses `Required`, `Not Applicable`, or `Unknown`. The checklist evaluates specification Readiness separately as `Ready` or `Blocked`. Unresolved product decisions return to `/speckit.clarify`. Then run agent-native orchestrated implementation: @@ -242,13 +213,6 @@ This preset adds checklist artifacts: - `specs//checklists/behavior-testability.md` -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: - `specs//behavior/bdd.draft.feature` @@ -292,16 +256,15 @@ Contract files packaged by the preset: Governance templates packaged by the preset: - `templates/constitution-template.md` +- `templates/spec-template.md` Packaged contract validators: - `validators/speckit_implement_contract.py` -Source intake templates, provider design contracts, visual requirements schemas, HTML SSOT bundle contracts, structured IR 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, visual SSOT refs, HTML SSOT refs, structured IR 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 and is the single visual readiness record for source section, requirement status, provider-evidence dependency, HTML SSOT refs, structured IR refs, other evidence refs, readiness input, blocking item ID, and accepted exception refs. Missing Required case coverage, Unknown case applicability, missing required provider evidence, or missing NFR criteria blocks planning when it affects downstream behavior projection or design. +`checklists/behavior-testability.md` is the BDD, NFR, and UI/UX specification readiness gate. It checks `spec.md` before planning so behavior, NFRs, and source-agnostic UI/UX 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 UI/UX Coverage Matrix keeps Applicability separate from Readiness and checks states, responsive behavior, accessibility, content, visual hierarchy, and acceptance criteria. Missing Required case coverage, Unknown applicability, Blocked UI/UX readiness, 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. @@ -311,11 +274,11 @@ Source intake templates, provider design contracts, visual requirements schemas, `contracts/sequences.md` captures service-call, command, event, external-system, retry, rollback, compensation, async, and failure-path sequencing. It is the flow design map that helps implementation preserve call order, service boundaries, async behavior, idempotency, compensation, and error propagation. Sequences always live at this path, even when there are no other contract files. -For visual planning, research.md carries forward visual/IR source refs, readiness inputs, accepted exception refs, unresolved blocker refs, related contracts, and quickstart paths. contracts formalize visual interaction and state constraints by linking accepted visual items to Expected UIF, behavior scenarios, assertions, and supporting API/data schemas. contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing, async results, retries, rollback, compensation, or error propagation; it does not redefine layout, tokens, screenshot matrices, visual readiness, or visual validation strategy. +For UI/UX planning, `research.md` records implementation decisions needed by accepted `UI-###` and `UX-###` requirements. Contracts formalize observable interaction, feedback, state, responsive, and accessibility constraints. `contracts/sequences.md` records UI state flow only when it affects cross-boundary sequencing, async results, retries, rollback, compensation, or error propagation. 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 UI implementation, non-visual acceptance, 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, visual SSOT refs, HTML SSOT refs, structured IR refs, external evidence refs, readiness inputs, 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, accepted UI/UX requirement IDs, required states, viewport behavior, accessibility behavior, quickstart paths, and behavior contracts when present, so Worker Agents can preserve object boundaries, service flows, user experience intent, and validation intent without reading full planning documents by default. See `commands/speckit.implement.md` for runtime handoff orchestration rules, and `schemas/` plus `validators/speckit_implement_contract.py` for the machine-checked manifest, handoff, receipt, dispatch, and commit contracts. diff --git a/presets/workflow-preset/commands/speckit.checklist.md b/presets/workflow-preset/commands/speckit.checklist.md index d0569ef6da..eee3e26728 100644 --- a/presets/workflow-preset/commands/speckit.checklist.md +++ b/presets/workflow-preset/commands/speckit.checklist.md @@ -1,5 +1,5 @@ --- -description: Wrap core checklist generation with BDD, NFR, and Visual Fidelity readiness gate. +description: Wrap core checklist generation with BDD, NFR, and UI/UX specification readiness gates. strategy: wrap --- @@ -11,64 +11,30 @@ Checklists validate whether requirements are complete, clear, consistent, measur CORE PRINCIPLE - Test the Requirements, Not the Implementation. Checklist questions must use requirement-quality forms such as "Are ... specified?", "Is ... quantified?", "Can ... be objectively verified?", or "Are ... requirements consistent?" -Use `$ARGUMENTS` as checklist intent. Generate dynamic clarifying questions with no pre-baked catalog only when the answer changes BDD, NFR, or Visual Fidelity checklist content. Use Q1/Q2/Q3 for initial questions and Q4/Q5 only for justified follow-up gaps. +Use `$ARGUMENTS` as checklist intent. Generate dynamic clarifying questions with no pre-baked catalog only when the answer changes BDD, NFR, or UI/UX specification checklist content. Use Q1/Q2/Q3 for initial questions and Q4/Q5 only for justified follow-up gaps. -For `checklists/behavior-testability.md`, create the file when absent; otherwise append or update without deleting existing checklist content. Before finishing, report the full path, item count, update mode, focus areas, depth level, actor/timing, must-have items, readiness status, and blockers. +For `checklists/behavior-testability.md`, create the file when absent; otherwise append or update without deleting existing checklist content. Resolve `behavior-testability-checklist-template` through the normal template stack and treat it as the only stable authority for checklist headings, item wording, matrices, columns, and status enums. Do not reproduce those structures in this command. -## BDD Readiness Gate +## Readiness Gate Behavior -Create or update `checklists/behavior-testability.md` as checklist artifacts only. This checklist is the plan-entry quality gate for BDD readiness and must evaluate requirements directly from `spec.md`; it must not depend on behavior drafts. +Populate the resolved checklist template directly from `spec.md`. The checklist is the plan-entry quality gate and must not depend on behavior drafts or implementation artifacts. -Include these sections: +Evaluate: -- User Story Readiness -- Acceptance Criteria Quality -- Scenario Coverage -- Case Coverage Matrix -- Given Readiness -- When Readiness -- Then Readiness -- Visual Fidelity Readiness -- Visual Fidelity Evidence Matrix -- Non-Functional Requirement Readiness -- Gate Status -- Blocking Items +- observable and independently testable user-story behavior; +- primary, alternate, exception, boundary, permission, validation, and state-conflict coverage when applicable; +- explicit Given starting conditions, When triggers, and Then outcomes; +- product-level non-functional requirement applicability and verifiability; +- UI/UX requirement applicability, observable acceptance criteria, required states, responsive behavior, accessibility, content, and visual hierarchy. -Check that each applicable user story has observable acceptance behavior, each acceptance criterion is verifiable, and primary, alternate, exception, boundary, permission, validation, and state_conflict paths are covered when applicable. +For UI/UX rows, keep requirement applicability (`Required | Not Applicable | Unknown`) separate from specification readiness (`Ready | Blocked`). Use the stable `UI-###` or `UX-###` requirement ID from `spec.md`. `Unknown` applicability and incomplete Required requirements must appear in Blocking Items when they prevent downstream planning. -Build a Case Coverage Matrix with one row per story or capability case type. Use case status: Required|Not Applicable|Unknown. Cover positive, negative, boundary, permission, validation, and state_conflict case types. Each row must have a stable Case ID. Required rows must cite the source `spec.md` section. Scenario IDs and `case_coverage_blockers` are assigned during `/speckit.plan`. Not Applicable requires rationale. Unknown must appear in Blocking Items. Required case type without observable acceptance behavior blocks PASS. +Set `Gate Status: PASS` only when every applicable readiness item is checked and `Blocking Items: none`. Otherwise set `Gate Status: BLOCKED` and list each requirement-quality gap that prevents behavior projection or planning. -Check Given readiness from `spec.md`: required roles, permissions, starting state, entity state, and data are explicit enough for later fixture setup. - -Check When readiness from `spec.md`: each trigger is an executable user action, request case, or system trigger. - -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 `Visual & UI Specification`, visual requirements, visual SSOT refs, HTML SSOT refs, structured IR 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. -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, HTML SSOT refs, structured IR refs, evidence refs, provider blocker status, 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. Record requirement status, dependency on provider evidence, visual SSOT refs, HTML SSOT refs, structured IR refs, other evidence refs, readiness input, blocker status, and accepted exception refs. -The Visual Fidelity Evidence Matrix records visual planning readiness, traceability refs, provider blocker status, accepted exception refs, Gate Status, and Blocking Items; it must not define visual validation work, screenshot comparison, visual diff, baseline capture, or final visual review. -Use one Visual Fidelity Evidence Matrix as the single visual readiness record; do not duplicate visual readiness decisions outside the matrix and Blocking Items. -Read visual facts from `spec.md` and cited evidence refs; do not call provider tools, re-extract external intake evidence, parse HTML SSOT bundles, re-parse structured IR artifacts, 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 required source-backed state or viewport evidence is missing for a feature that depends on provider evidence. -Screenshots support visual facts but do not create product semantics. - -Check Non-Functional Requirement Readiness from `spec.md`: applicable performance, security and privacy, reliability and recovery, accessibility, compliance and auditability, observability, compatibility, data lifecycle, and cost or operational constraints are explicitly declared in `spec.md` as `Required`, `Not Applicable`, or `Unknown`. - -For each NFR dimension, require either verifiable product-level criteria, a `Not Applicable` rationale, or an `Unknown` marker that identifies what must be clarified. Do not require technical designs such as SLAs, RTO/RPO formulas, cache layers, queues, deployment topology, or infrastructure choices unless the product requirement already states them. - -Treat these NFR readiness gaps as blocking items: Required but missing from `spec.md`; Required but not verifiable from product-level criteria; Unknown and affects downstream design. Do not block planning for NFR dimensions marked `Not Applicable` with a rationale or for dimensions with explicit no-special-requirement statements. - -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 the external intake extension, not `/speckit.clarify`. +Unchecked readiness items that prevent downstream planning return to `/speckit.clarify` or `/speckit.specify`. Do not repair requirements inside the checklist command and do not proceed to `/speckit.plan`. {CORE_TEMPLATE} ## Behavior Checklist Reporting -Before finishing, report the BDD, NFR, and Visual Fidelity readiness status and call out unchecked items that block planning. +Before finishing, report the full checklist path, item count, update mode, focus areas, depth level, actor/timing, must-have items, BDD/NFR/UI/UX readiness status, Gate Status, and Blocking Items. diff --git a/presets/workflow-preset/commands/speckit.clarify.md b/presets/workflow-preset/commands/speckit.clarify.md index 7c06a15ce8..f250a0cf62 100644 --- a/presets/workflow-preset/commands/speckit.clarify.md +++ b/presets/workflow-preset/commands/speckit.clarify.md @@ -7,9 +7,9 @@ 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, visual/UI requirement coverage status, 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, UI/UX applicability, 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. +Do not read or update behavior draft artifacts. Product requirements stay in `spec.md`; update `spec.md` only after user-provided answers make the requirement clear. ## Wrapper Input Additions @@ -21,35 +21,35 @@ Load the active `spec.md` through the core command. Official hooks still apply: ## Wrapper Outline Additions -## Design Requirement Clarification Strategy +### UI/UX Requirement Clarification Strategy -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. +Scan `spec.md` first for `[NEEDS CLARIFICATION]`, UI/UX Applicability `Unknown`, and incomplete `UI-###` or `UX-###` requirements. -Do not call provider tools. Do not re-extract design facts, re-parse provider design links, parse HTML SSOT bundles, re-parse structured IR artifacts, 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` product-decision 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. Present exactly one question at a time and do not reveal future queued questions. -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. For short-answer gaps, use `Suggested` and constrain answers to `<=5 words`. Accept `yes`, `recommended`, or `suggested` as approval of the shown recommendation. -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: +Prioritize questions in this order: -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. product-side acceptance evidence and accepted exception approval flow. +1. UI/UX applicability: Required, Not Applicable, or Unknown. +2. Target users, experience goals, and critical journeys. +3. Information architecture, navigation, and recovery paths. +4. Required default, loading, empty, error, disabled, success, hover, and focus states. +5. Interaction feedback, validation behavior, and error semantics. +6. Responsive reflow, scrolling, safe areas, viewport support, and long-content handling. +7. Keyboard, focus, semantics, contrast, announcements, and other accessibility behavior. +8. Required copy, visual hierarchy, iconography, imagery, and numeric or date formatting. +9. Objective UI/UX acceptance criteria. -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. +After each accepted answer, write confirmed answers back into the relevant `spec.md` requirement, scenario, acceptance criterion, assumption, or UI/UX section. Update Applicability when the answer resolves an `Unknown` decision. Ensure `## Clarifications`, `### Session YYYY-MM-DD`, and one `- Q: ... -> A: ...` bullet exist for the session. Save `spec.md` after each accepted answer. -Do not generate visual restoration checklists. Clarification fills requirement gaps in `spec.md`; `/speckit.checklist` remains responsible for checking requirement text quality and readiness. +Do not generate checklist artifacts. `/speckit.checklist` remains responsible for checking requirement text quality and readiness. ## Validation after each write -Run validation after EACH write plus final pass. Confirm the accepted answer appears once in `spec.md`, Total asked questions is at most 5, the targeted ambiguity is removed or replaced, no contradictory earlier statement remains, and heading structure is preserved. +Run validation after each write plus a final pass. Confirm the accepted answer appears once in `spec.md`, no more than 5 questions were asked, the targeted ambiguity is removed or replaced, no contradictory earlier statement remains, and heading structure is preserved. -Do not update checklist artifacts. After each `spec.md` write, report checklist impact as unresolved readiness context for `/speckit.checklist`. +Do not update checklist artifacts. Report checklist impact as unresolved readiness context for `/speckit.checklist`. {CORE_TEMPLATE} @@ -61,6 +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`. +- [ ] Any answered UI/UX applicability decision was updated in `spec.md`. - [ ] Validation after each write found no duplicate or contradictory clarification. -- [ ] Completion reported with sections touched and remaining blockers. +- [ ] Completion reported sections touched and remaining blockers. diff --git a/presets/workflow-preset/commands/speckit.implement.md b/presets/workflow-preset/commands/speckit.implement.md index 767ee39b01..8a9faed240 100644 --- a/presets/workflow-preset/commands/speckit.implement.md +++ b/presets/workflow-preset/commands/speckit.implement.md @@ -20,21 +20,19 @@ description: Run implement orchestration. - If isolation is unavailable or unknown, write the manifest and handoffs, then stop with `Manual Worker Queue` entries: `1. /speckit.implement Use handoff JSON `. - Consume planner outputs and worker receipts, not worker conversation history. -## Visual Implementation Boundary -- Visual Fidelity Readiness `Requirement Status` is `Required` or `Required` plus an accepted exception. - This is the `/speckit.tasks` visual task input filter. -- 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; - do not repair provider evidence in `/speckit.implement`. -- `/speckit.implement` must not discover visual requirements, repair Visual Fidelity Readiness evidence, +## UI/UX Implementation Boundary +- UI/UX Specification Readiness must declare Applicability `Required` and Readiness `Ready`. + This is the `/speckit.tasks` UI/UX task input filter. +- Do not create handoffs or worker instructions for rows with Applicability `Not Applicable` + or `Unknown`, or with Readiness `Blocked`. +- Route `Unknown` or `Blocked` rows back to `/speckit.clarify` or `/speckit.checklist`. +- `/speckit.implement` must not discover UI/UX requirements, repair readiness, or edit upstream artifacts for execution. -- Visual worker receipts must reference the relevant Visual Item ID, `Requirement Status`, and evidence refs. +- UI/UX worker receipts must reference the relevant `UI-###` or `UX-###` requirement ID and validation evidence. ## Vertical Planner Agent - Read only `tasks.md`, `context-index.json`, and allowed planning artifacts. - Preserve order, dependencies, capability boundaries, and Change Scope Granularity. -- Put unresolved shard, context, asset, path, visual status, evidence, or fallback gaps into `context_gaps`. +- Put unresolved shard, context, path, UI/UX status, evidence, or fallback gaps into `context_gaps`. - Emit drafts that validate against the handoff schema before Core assembly. ## Worker Agent - Reject non-existent handoff paths. @@ -44,11 +42,11 @@ description: Run implement orchestration. - Select Implementation Worker or Code Review Worker by `task_type`. - Visual/UI implementation is implementation work; UI consistency review is code review. - Write `task_status_update.receipt_path` as `speckit.implement.receipt.v1`. -- For visual/UI handoffs, validate task text and preserve visual/IR traceability refs. -- Use empty `completed_task_ids` when required provider evidence is unavailable. +- For UI/UX handoffs, validate task text and preserve `UI-###` or `UX-###` requirement references. +- Use empty `completed_task_ids` when required UI/UX validation evidence is unavailable. - Do not edit `tasks.md`. ## Contract References -- Runtime, shard, digest, path, asset binding, dispatch, Worker Prompt, and receipt rules are source-owned here. +- Runtime, shard, digest, path, dispatch, Worker Prompt, and receipt rules are source-owned here. - Schemas: `schemas/speckit.implement.manifest.v1.schema.json`, `schemas/speckit.implement.handoff.v2.schema.json`, `schemas/speckit.implement.receipt.v1.schema.json`. diff --git a/presets/workflow-preset/commands/speckit.plan.md b/presets/workflow-preset/commands/speckit.plan.md index 31816d53ce..076ebc6ab9 100644 --- a/presets/workflow-preset/commands/speckit.plan.md +++ b/presets/workflow-preset/commands/speckit.plan.md @@ -15,7 +15,7 @@ Follow cross-agent protocol profile: `speckit.plan.stage_local_planning`. Plan Core Agent owns checklist preflight, stage-local delegation, conflict resolution, and final writes to planning artifacts. Delegated agents return bounded drafts, source refs, blockers, and `context_gaps`; Plan Core Agent consumes those outputs rather than subagent conversation history. -Use only planning-local roles: Behavior Projection Agent, Formal Contract Agent, Design Artifact Agent, Validation Planning Agent, and Visual Planning Agent. Each payload declares assigned scope, allowed reads, allowed sections, and output contract. If runtime subagents are unavailable, Plan Core Agent processes one assigned scope at a time with the same boundaries and final-write ownership. +Use only planning-local roles: Behavior Projection Agent, Formal Contract Agent, Design Artifact Agent, Validation Planning Agent, and UI/UX Planning Agent. Each payload declares assigned scope, allowed reads, allowed sections, and output contract. If runtime subagents are unavailable, Plan Core Agent processes one assigned scope at a time with the same boundaries and final-write ownership. ## Design Artifact Policy @@ -93,17 +93,16 @@ 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, source refs, visual SSOT refs, HTML SSOT refs, structured IR refs, screenshot refs, visual proof refs, and other external evidence refs already accepted by `spec.md` and the readiness checklist. +When UI/UX requirements are in scope, keep `plan.md` navigation linked to accepted `UI-###` and `UX-###` requirements, related interaction contracts, planning decisions, and acceptance paths. -## Visual Planning Responsibilities +## UI/UX 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. +Use `checklists/behavior-testability.md` as the upstream UI/UX specification-readiness record. Carry forward only rows whose Applicability is `Required` and Readiness is `Ready`. If a row is `Unknown` or `Blocked`, stop with a report-only/no-write upstream gate failure and return to `/speckit.checklist` or `/speckit.clarify`. Do not project `Not Applicable` rows into planning outputs. -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`: carry forward visual and IR planning inputs for each relevant Visual Item ID or visual SSOT ref. Record source refs, HTML SSOT refs, structured IR refs, readiness status, accepted exception refs, unresolved blocker refs, external evidence refs, related quickstart path, and related UIF or behavior contract path. Do not define visual validation strategy, screenshot comparison, visual diff, baseline capture, or final visual review work; do not copy the Visual Fidelity Evidence Matrix into `research.md`, create new visual requirements, call provider tools, rebuild external intake evidence, or 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`. +- `research.md`: record planning decisions needed to satisfy accepted UI/UX requirements, including platform constraints, interaction tradeoffs, viewport support, accessibility approach, and unresolved implementation blockers. Do not create new product requirements or change accepted applicability. +- `contracts/uif/` and `contracts/behavior/`: formalize accepted interaction, feedback, state, responsive, and accessibility constraints when they affect observable behavior. Reference the applicable `UI-###` or `UX-###` requirement IDs. +- `contracts/sequences.md`: add UI interaction sequences and responsive branch triggers only when UI states affect cross-boundary order, async callbacks, retries, rollback, compensation, or error propagation. Keep visual style, typography, color, spacing, and layout details outside sequence contracts. +- `quickstart.md`: define executable acceptance paths for applicable UI/UX requirements without changing their product meaning. ## Behavior-First Planning Inputs diff --git a/presets/workflow-preset/commands/speckit.specify.md b/presets/workflow-preset/commands/speckit.specify.md index fbb873fddc..6444942e24 100644 --- a/presets/workflow-preset/commands/speckit.specify.md +++ b/presets/workflow-preset/commands/speckit.specify.md @@ -6,54 +6,49 @@ strategy: wrap Follow cross-agent protocol profile: `speckit.specify.single_core`. ## Spec-Only Requirement Policy + 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, visual and UI requirements, constraints, assumptions, and any clarification markers required by the core template. +Preset-added requirement output writes only `spec.md`. Product requirements stay in `spec.md`: user stories, acceptance criteria, functional requirements, non-functional requirements, UI/UX requirements, constraints, assumptions, and clarification markers required by the active 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. +Keep requirement text implementation-agnostic and scoped to product behavior. Focus on WHAT users need and WHY; avoid HOW to implement it. ## Wrapper Input Additions -Treat product notes, PRDs, user prompts, confirmed external intake facts, visual SSOT refs, HTML SSOT refs, structured IR 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. +Treat explicit user-provided product text, notes, and confirmed decisions as the feature description. If the core feature description is empty, follow the core command error path. ## Wrapper Preflight Additions -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 SSOT bundles, re-parse structured IR artifacts, decide provider source readiness, or generate provider artifact instances. -Classify gaps by ownership: missing product decisions become `[NEEDS CLARIFICATION]`; missing provider or intake evidence for a feature that depends on that evidence becomes `[BLOCKED: PROVIDER_EVIDENCE]`; features that do not depend on HTML SSOT, structured IR, or provider evidence are `Not Applicable`. +Resolve the active `spec-template` through the normal preset/template stack. Use its UI/UX section as the only stable UI/UX output structure; do not reproduce the template's headings, table columns, status enums, or examples inside this command. ## Wrapper Outline Additions -Specification Projection Policy: write one implementation-agnostic `spec.md` from confirmed product facts, explicit product constraints, and source-backed external intake facts. - -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`. - -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. - -For visual requirements, preserve visual SSOT refs, HTML SSOT refs, structured IR 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. -Promote only confirmed product facts and source-backed visual, layout, state, interaction, responsive, accessibility, and acceptance facts with source refs. Do not promote provider evidence gaps into product requirements or `[NEEDS CLARIFICATION]` markers. +Determine whether the feature has a user-facing surface or interaction journey: -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. +- `Required`: populate every applicable UI/UX field defined by the active template. +- `Not Applicable`: record a concrete product-level rationale in `spec.md`. +- `Unknown`: record the unresolved product decision with `[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. +Write only confirmed product requirements. Assign stable `UX-###` IDs to journey, navigation, feedback, and usability requirements, and stable `UI-###` IDs to surface, state, responsive, accessibility, content, and observable visual requirements. -When visual SSOT, HTML SSOT, structured IR, or provider evidence 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. +Requirements must describe observable user outcomes. Do not invent framework components, DOM structure, CSS selectors, component props, code organization, asset packaging, or other implementation decisions. -## 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]`. +Limit `[NEEDS CLARIFICATION]` markers to the highest-impact unresolved product decisions. Record reasonable low-impact defaults in Assumptions. ## Specification Quality Validation -Validate that requirement text is stakeholder-readable, testable, implementation-agnostic, and explicit about assumptions, NFR applicability, visual evidence source refs, provider blockers, and unresolved product decisions. + +Validate that the completed requirement text is stakeholder-readable, testable, implementation-agnostic, and explicit about applicability, assumptions, UI states, responsive behavior, accessibility, content, acceptance criteria, and unresolved product decisions. {CORE_TEMPLATE} ## Completion Report -Before finishing, report the `spec.md` sections created or updated, confirmed requirements, visual SSOT refs preserved, provider blockers, and unresolved requirement ambiguities. + +Before finishing, report the `spec.md` sections created or updated, confirmed requirements, UI/UX applicability, and unresolved requirement ambiguities. ## Done When -- [ ] Confirmed requirement facts, visual SSOT refs, HTML SSOT refs, structured IR 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]`. + +- [ ] The active spec template supplied the stable UI/UX artifact shape. +- [ ] Functional, non-functional, and UI/UX requirement coverage is present or explicitly marked Not Applicable or Unknown. +- [ ] Applicable UI/UX requirements have stable `UI-###` or `UX-###` IDs and observable acceptance criteria. - [ ] 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. +- [ ] Completion reported updated `spec.md` sections and remaining ambiguities. diff --git a/presets/workflow-preset/commands/speckit.tasks.md b/presets/workflow-preset/commands/speckit.tasks.md index ab9940ba31..8f2ba1c7ae 100644 --- a/presets/workflow-preset/commands/speckit.tasks.md +++ b/presets/workflow-preset/commands/speckit.tasks.md @@ -20,14 +20,14 @@ Use these subagent roles only for task derivation: - Tasks Core Agent: orchestration, scope partitioning, blocker aggregation, deduplication, final checklist assembly, and preservation of the planned `M + U` scope. - Story Task Agent: story-local implementation, fixture, validation, evidence, and integration task chains. - Contract Validation Agent: interface contract, BDD, behavior contract, UIF `api_call`, sequence, external-system, data side-effect, retry, rollback, and quickstart validation task derivation. -- Visual Task Agent: visual readiness, UIF `user_event`, Client Asset Contract, UI implementation, non-visual UI acceptance, asset binding, provider blocker routing, and traceability preservation. -- Review Task Agent: final review tasks for `boundary`, `interface_contract`, `visual`, `data_side_effect`, `behavior_contract`, `sequence_consistency`, and `asset_binding` scopes. +- UI/UX Task Agent: UI/UX readiness, UIF `user_event`, UI implementation, accessibility, responsive behavior, state coverage, acceptance, and requirement traceability. +- Review Task Agent: final review tasks for `boundary`, `interface_contract`, `ui_ux`, `data_side_effect`, `behavior_contract`, and `sequence_consistency` scopes. Every subagent payload must declare: -- `assigned_scope`: the user story, contract group, visual item group, review scope, or blocker-check scope assigned to the subagent. +- `assigned_scope`: the user story, contract group, UI/UX requirement group, review scope, or blocker-check scope assigned to the subagent. - `allowed_read_paths`: the exact files, directories, or glob groups the subagent may read. -- `allowed_sections`: the exact headings, table names, contract IDs, scenario IDs, Visual Item IDs, or summary slices the subagent may inspect within allowed files. +- `allowed_sections`: the exact headings, table names, contract IDs, scenario IDs, UI/UX requirement IDs, or summary slices the subagent may inspect within allowed files. - `output_contract`: the required draft shape, including task candidates, evidence refs, source refs, blockers, and `context_gaps`. Subagents must not read full `spec.md`, `plan.md`, `research.md`, or `contracts/` trees unless the payload explicitly lists those files or directories in `allowed_read_paths` and lists the permitted headings, IDs, or contract groups in `allowed_sections`. Prefer scoped excerpts, extracted summaries, contract IDs, scenario IDs, and readiness rows over whole-file reads. A subagent that needs context outside its declared payload must return a `context_gaps` entry instead of widening its own reads. @@ -44,9 +44,8 @@ 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, source refs, visual SSOT refs, HTML SSOT refs, structured IR refs, screenshot refs, visual proof 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: `Requirement Status`, readiness input, visual/IR traceability refs, blockers, and accepted exceptions. +- `spec.md` UI/UX requirements: accepted `UI-###` and `UX-###` requirements for journeys, navigation, feedback, states, responsive behavior, accessibility, content, and observable visual outcomes. +- `checklists/behavior-testability.md` UI/UX Specification Readiness: Applicability, Readiness, coverage, and Blocking Items for each UI/UX requirement. - `contracts/bdd/`: formal BDD acceptance contracts. - `contracts/uif/`: Expected UIF interaction contracts. - `contracts/behavior/`: formal scenario instance, fixture, and assertion contracts. @@ -54,13 +53,9 @@ If any listed file exists under FEATURE_DIR, task generation must consume it as Use these inputs to derive implementation, integration, orchestration, failure-handling, and non-visual validation tasks. For behavior contracts, derive test-first task chains in user-story order: fixture setup, BDD/E2E or contract test, implementation, and verification evidence. Keep task output in the existing checklist format and user-story organization. -`/speckit.tasks` owns implementation, non-visual validation, and review task definition in `tasks.md`. Task derivation must not invent validation strategy, visual validation work, add lifecycle roles, change requirements, update contracts, or widen scope. +`/speckit.tasks` owns implementation, validation, and review task definition in `tasks.md`. Task derivation must not invent validation strategy, add lifecycle roles, change requirements, update contracts, or widen scope. -For Client Asset Contract entries, derive asset preparation, binding, implementation, and non-visual acceptance 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, external intake artifacts, HTML SSOT refs, structured IR refs, or provider evidence artifacts; if required provider evidence is missing for a dependent feature, report `[BLOCKED: PROVIDER_EVIDENCE]` instead of deriving complete-looking UI tasks. - -Use each Visual Fidelity Readiness row's `Requirement Status` as the visual task input filter. Generate UI implementation, asset binding, and non-visual acceptance 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, repair evidence, re-parse provider artifacts, or define visual validation strategy; it only decomposes visual specifications that already passed the readiness gate. +Use UI/UX Specification Readiness as the only UI/UX planning-readiness source. Generate UI/UX tasks only for rows whose Applicability is `Required` and Readiness is `Ready`. Do not generate implementation, validation, acceptance, or review tasks for `Not Applicable`, `Unknown`, or `Blocked` rows. Route `Unknown` and `Blocked` requirement rows back to `/speckit.clarify` or `/speckit.checklist`. `/speckit.tasks` only decomposes UI/UX specifications that 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. @@ -83,12 +78,12 @@ Use this fixture strategy and external-system execution mode taxonomy: - External-system validation must use mock or sandbox unless `research.md` and `quickstart.md` explicitly require a real-system validation path. - Add a separate validation task for high-risk, non-functional, external-system, async, retry, rollback, permission, validation, state_conflict, negative, boundary, or error behavior. -Evidence binding: every generated test or validation task must name at least one relevant BDD scenario, behavior assertion, API contract, UIF path, quickstart validation path, visual/IR traceability ref, or command output. +Evidence binding: every generated test or validation task must name at least one relevant BDD scenario, behavior assertion, API contract, UIF path, UI/UX requirement ID, quickstart validation path, or command output. Generate explicit validation tasks from this validation task taxonomy instead of relying on final code review for primary validation responsibility: - `contract_validation`: contract ref, implementation surface, validation command, and evidence; report a blocker when mapping is unavailable. -- `ui_acceptance`: user-facing UIF path or BDD scenario, Visual Item ID when applicable, Visual Fidelity Readiness row, viewport/state requirement refs, accepted exception refs, quickstart validation path, and non-visual evidence. +- `ui_acceptance`: user-facing UIF path or BDD scenario, applicable `UI-###` or `UX-###` requirement ID, required state and viewport coverage, accessibility behavior, quickstart validation path, and observable evidence. - `data_side_effect_validation`: affected entity or state transition, expected write behavior, rollback/compensation/retry/migration/backfill or invariant assertion when applicable, and validation evidence. - `integration_e2e_validation`: user-visible journey or cross-boundary flow, scenario/assertion refs, external-system strategy, quickstart validation path, and captured command output. @@ -102,34 +97,31 @@ 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 only this UI/visual task taxonomy when a user story includes `contracts/uif/`, visual acceptance requirements, Visual Fidelity Readiness rows, or Client Asset Contract entries: +Use only this UI/UX task taxonomy when a user story includes `contracts/uif/` or ready `UI-###` / `UX-###` requirements: -- Maintain story-local task granularity: `visual_setup` -> `visual_implementation` -> `ui_acceptance` or `asset_binding` as needed. Do not create a separate visual lifecycle phase. -- `visual_setup`: prepare UI fixtures, viewport configuration when required by accepted requirements, client resource setup, asset variants, fallback policy mapping, and source ref wiring. -- `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. -- `ui_acceptance`: verify a user-facing UIF path or BDD scenario without screenshot comparison, visual diff, baseline capture, or final visual review. It may assert user action, feedback, page state, accessibility behavior, and visible result described by accepted requirements. -- `asset_binding`: when a Client Asset Contract applies, bind source assets, variants, license or authorization refs, fallback policy, code paths, and missing-asset blockers. -- `visual_setup`, `visual_implementation`, `ui_acceptance`, and `asset_binding` are the only visual/UI task types. -- Visual/UI tasks must name concrete source, test, fixture, configuration, asset paths, and visual/IR traceability refs when derivable; otherwise report a readiness blocker instead of generating an ambiguous 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 SSOT ref, HTML SSOT ref, structured IR ref, accepted exception ref, quickstart validation path, API contract, or captured command output. -- Missing required provider evidence, Client Asset Contract entries, asset variants, fallback policy, HTML SSOT refs, or structured IR refs are Visual Fidelity Readiness blockers when the feature depends on them. +- Maintain story-local task granularity: `ui_setup` -> `ui_implementation` -> `ui_accessibility` and/or `ui_acceptance` as needed. Do not create a separate UI/UX lifecycle phase. +- `ui_setup`: prepare UI fixtures, viewport configuration, test data, and user-visible content required by accepted requirements. +- `ui_implementation`: implement accepted journeys, navigation, states, interaction feedback, responsive behavior, content, and observable visual outcomes. +- `ui_accessibility`: implement and validate keyboard, focus, semantics, contrast, announcement, and error behavior required by accepted requirements. +- `ui_acceptance`: verify the relevant UIF path, BDD scenario, or UI/UX requirement through user action, feedback, page state, responsive behavior, accessibility behavior, and visible result. +- UI/UX tasks must name the applicable `UI-###` or `UX-###` requirement ID, concrete implementation surface, test or fixture path, and validation path when derivable; otherwise report a readiness blocker instead of generating an ambiguous task. +- UI acceptance tasks must verify the same UIF path, UI/UX requirement ID, scenario ID, or quickstart validation path as the implementation task, including required state, viewport, and accessibility coverage. -For each applicable Visual Fidelity Readiness row with `Requirement Status` `Required` or `Required` plus an accepted exception, generate UI implementation and non-visual acceptance work only when it follows from ready requirements and contracts. Do not generate visual validation, screenshot comparison, visual diff, baseline capture, final visual review, or visual tasks for rows with `Requirement Status` `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`. +Generate UI/UX tasks only from Required and Ready checklist rows. Not Applicable rows create no tasks; Unknown or Blocked rows remain upstream requirement-quality blockers. -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. +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 UI/UX Specification Readiness to make implementation pass; report a blocker if implementation requires requirement or contract changes. When persistence, migrations, external writes, retries, rollback, or compensation are in scope, include a data-side-effect validation task before final code review. The task must name the affected entity, expected mutation behavior, invariant or rollback/compensation assertion, and evidence source. ## Final Code Review -When generating `tasks.md`, append the final phase after user-story tasks in the same checklist format. Use this final review scope taxonomy when applicable: `boundary`, `interface_contract`, `visual`, `data_side_effect`, `behavior_contract`, `sequence_consistency`, and `asset_binding`. Checked sources include `class-diagram.md`, `contracts/sequences.md`, `contracts/`, `contracts/uif/`, `research.md`, `quickstart.md`, `spec.md` visual acceptance requirements, `spec.md` Client Asset Contract entries, and `checklists/behavior-testability.md` Visual Fidelity Readiness, plus data side-effect review and real-system e2e environment readiness. +When generating `tasks.md`, append the final phase after user-story tasks in the same checklist format. Use this final review scope taxonomy when applicable: `boundary`, `interface_contract`, `ui_ux`, `data_side_effect`, `behavior_contract`, and `sequence_consistency`. Checked sources include `class-diagram.md`, `contracts/sequences.md`, `contracts/`, `contracts/uif/`, `research.md`, `quickstart.md`, `spec.md` UI/UX requirements, and `checklists/behavior-testability.md` UI/UX Specification Readiness, plus data side-effect review and real-system e2e environment readiness. Code review task text must require review of runtime database writes and other persistent data changes, including field-level update/delete behavior, bulk writes, soft deletes, ORM whole-object saves, migrations/backfills, retries, rollback/compensation, and external-system writes. Do not generate field-level mutation allowlists or pre-implementation data-write gates in normal tasks. -Code review task text must require boundary review: task scope stays within planned `M + U`, implementation matches the referenced contracts, validation evidence covers quickstart or contract paths, and no implementation task changed `spec.md`, `contracts/`, readiness checklists, or Visual Fidelity Readiness to make execution pass. +Code review task text must require boundary review: task scope stays within planned `M + U`, implementation matches the referenced contracts, validation evidence covers quickstart or contract paths, and no implementation task changed `spec.md`, `contracts/`, readiness checklists, or UI/UX Specification Readiness to make execution pass. -Code review task text may require UI consistency review when UI or visual acceptance was in scope. The review must reconcile implemented UI states and viewport behavior with accepted requirements, Visual Fidelity Readiness, UIF paths, visual/IR traceability refs, and Client Asset Contract bindings, variants, and fallback policy; it must not require screenshot comparison, visual diff, baseline capture, or final visual review. +Code review task text may require UI consistency review when UI/UX acceptance was in scope. The review must reconcile implemented journeys, navigation, states, viewport behavior, accessibility behavior, content, and visible results with accepted `UI-###` and `UX-###` requirements, readiness rows, and UIF paths. Review evidence binding: final review tasks must name concrete review scope, source artifacts, implementation surfaces, and evidence refs. If review scope exposes drift from the plan, sequences, contracts, or data-side-effect expectations, express it as review evidence, bounded repair permission, or a blocker. If resolving the drift would require changing `spec.md`, `contracts/`, `research.md`, `quickstart.md`, readiness checklists, or planning artifacts, record a blocker instead of treating the change as implementation work. Real-system e2e environment gaps must remain visible as evidence gaps instead of treated as passing evidence. diff --git a/presets/workflow-preset/docs/extension-governance.md b/presets/workflow-preset/docs/extension-governance.md index 83b06a5d87..d8057b2a81 100644 --- a/presets/workflow-preset/docs/extension-governance.md +++ b/presets/workflow-preset/docs/extension-governance.md @@ -21,13 +21,10 @@ 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. -Source intake artifacts belong in an extension, not this preset. External intake owns source capture, provider evidence, provider metadata, rendered HTML SSOT bundles, structured IR artifacts, -source-side readiness, and blocker codes. This preset may consume confirmed -external intake artifact refs, visual SSOT refs, HTML SSOT refs, structured IR refs, -source refs, coverage gaps, readiness inputs, accepted exception refs, and provider blockers already cited in `spec.md`. -External evidence refs are consumed as source, readiness, blocker, and traceability inputs only. Provider tools, provider execution, hooks, adapter scripts, -and authentication are external integration concerns and remain outside this -preset. +Source acquisition, tool-specific extraction, normalization, authentication, +and source-readiness evaluation are outside this preset. `workflow-preset` +consumes explicit product text and confirmed product decisions, then owns only +source-agnostic requirement, planning, task, and implementation artifacts. ## Template And Command Ownership @@ -44,18 +41,21 @@ Stage ownership: - `/speckit.constitution`: constitution governance and project principles only. - `/speckit.specify`: requirement artifacts only. - `/speckit.clarify`: requirement clarification only. -- `/speckit.checklist`: checklist artifacts and BDD/NFR/Visual Fidelity readiness gates only. +- `/speckit.checklist`: checklist artifacts and BDD/NFR/UI/UX specification readiness gates only. - `/speckit.plan`: Phase 0 behavior projection, planning artifacts, and formal contracts. - `/speckit.tasks`: `tasks.md` only. - `/speckit.analyze`: vertical consistency checks across requirements, behavior drafts, contracts, and tasks only. - `/speckit.implement`: implementation handoff execution only. -`/speckit.tasks` owns implementation, non-visual acceptance, 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, visual validation work, lifecycle roles, requirements, contract updates, or wider scope during execution. +`/speckit.tasks` owns implementation, UI/UX acceptance, 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, lifecycle roles, requirements, contract updates, or wider scope during execution. -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. +The wrapping `spec-template` owns the stable `UI/UX Specification` shape. +`/speckit.specify` decides applicability and fills that shape; it must not +duplicate headings, fields, matrix columns, status enums, or examples. -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 with Source `spec.md` section, Requirement Status, provider-evidence dependency, visual SSOT refs, HTML SSOT refs, structured IR refs, other evidence refs, readiness input, Blocking Item ID, and accepted exception refs. It records visual planning readiness, traceability refs, provider blocker status, accepted exception refs, checklist Gate Status, and checklist Blocking Items. It must not define visual validation work, screenshot comparison, visual diff, baseline capture, or final visual review. Source-side intake readiness remains separate: an intake extension may prove raw metadata completeness, source coverage, node inventory parity, HTML SSOT coverage, structured IR coverage, and blocker lint errors, but that proof is not re-run by this preset. +UI/UX requirement Applicability uses `Required`, `Not Applicable`, or `Unknown`. +Checklist Readiness uses `Ready` or `Blocked` as a separate dimension. The +UI/UX Coverage Matrix is the only UI/UX specification-readiness matrix. ## Structured Artifact Rules @@ -121,7 +121,13 @@ NFR readiness belongs in `spec.md` product requirements rather than downstream 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/IR source refs, readiness inputs, accepted exception refs, related contract paths, and unresolved blocker refs only; it must not duplicate the Visual Fidelity Evidence Matrix or define visual validation strategy, screenshot comparison, visual diff, baseline capture, or final visual review. contracts formalize visual interaction and state constraints by referencing accepted visual items, source refs, structured IR 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. +For UI/UX planning, `research.md` records implementation decisions needed by +accepted `UI-###` and `UX-###` requirements. Contracts formalize interaction, +feedback, state, responsive, and accessibility constraints. +`contracts/sequences.md` records UI state flow only when it affects +cross-boundary sequencing, async callbacks, retry, rollback, compensation, or +error propagation; it must not define visual style, typography, color, spacing, +or layout details. ## Handoff Extension Rules @@ -144,13 +150,11 @@ Do not bump preset version or release archive URLs until release preparation. Unreleased behavior belongs under `## Unreleased` in `CHANGELOG.md`. ## Verification - After changing preset commands, templates, schemas, validators, governance docs, or public documentation, run: ```bash python3 -m unittest tests/test_preset_contract.py ``` - If the system Python lacks development dependencies, use a local virtual environment and the same unittest command from that environment. diff --git a/presets/workflow-preset/preset.yml b/presets/workflow-preset/preset.yml index f4cf90105f..4d6cda543e 100644 --- a/presets/workflow-preset/preset.yml +++ b/presets/workflow-preset/preset.yml @@ -25,6 +25,12 @@ provides: the constitution template replaces: constitution-template strategy: wrap + - type: template + name: spec-template + file: templates/spec-template.md + description: Add source-agnostic UI/UX requirements to the feature specification + replaces: spec-template + strategy: wrap - type: command name: speckit.specify file: commands/speckit.specify.md @@ -40,7 +46,7 @@ provides: - type: command name: speckit.checklist file: commands/speckit.checklist.md - description: Wrap core checklist generation with BDD, NFR, and Visual Fidelity + description: Wrap core checklist generation with BDD, NFR, and UI/UX specification readiness gate replaces: speckit.checklist strategy: wrap @@ -103,7 +109,7 @@ provides: - type: template name: behavior-testability-checklist-template file: templates/behavior/behavior-testability-checklist.md - description: Template for BDD, NFR, and Visual Fidelity readiness gate output + description: Template for BDD, NFR, and UI/UX specification readiness gate output replaces: behavior-testability-checklist-template strategy: replace - type: template diff --git a/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md b/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md index 271a5a1deb..adcb490aab 100644 --- a/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md +++ b/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md @@ -56,40 +56,37 @@ For each user story or capability, record one row per story or capability case t - [ ] Required NFR entries have verifiable product-level criteria without prescribing architecture. - [ ] Unknown NFR entries that affect downstream design are listed as blocking items. -## Visual Fidelity Readiness -- [ ] Apply this section when `spec.md` contains `Visual & UI Specification`, visual requirements, visual SSOT refs, HTML SSOT refs, structured IR 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. -- [ ] Visual requirements record external intake readiness status when cited, visual SSOT refs, HTML SSOT refs, structured IR refs, other evidence refs, and provider blocker status when provider evidence is required. -- [ ] Visual Fidelity Evidence Matrix rows cite source `spec.md` sections, traceability refs, readiness inputs, blocking item IDs, and accepted exception refs. -- [ ] Visual Fidelity Evidence Matrix is the only artifact that records visual planning readiness, provider blocker status, traceability refs, accepted exception refs, Gate Status, and Blocking Items. -- [ ] Visual Fidelity Evidence Matrix reads visual facts from `spec.md` and cited evidence refs; it does not call provider tools, re-extract external intake evidence, parse HTML SSOT bundles, re-parse structured IR artifacts, rebuild provider matrices, define visual validation work, 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 | Requirement Status | Depends on Provider Evidence | HTML SSOT Refs | Structured IR Refs | Other Evidence Refs | Readiness Input | Blocking Item ID | Accepted Exception Refs | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| VIS-001 | `spec.md#...` | Required|Not Applicable|Unknown|[BLOCKED: PROVIDER_EVIDENCE] | yes|no | html-ssot/... or none | ir/... or none | provider/screenshot refs or none | ready|blocked|not-applicable | BI-... or none | EX-... or none | - -- [ ] Requirement Status is declared for each visual requirement. -- [ ] Provider-dependent rows cite HTML SSOT refs, structured IR refs, visual SSOT refs, or other external intake artifact refs when available. -- [ ] Missing required provider or intake evidence sets Gate Status: BLOCKED, uses `[BLOCKED: PROVIDER_EVIDENCE]`, and lists the item in Blocking Items. -- [ ] Rows that do not depend on HTML SSOT, structured IR, or provider evidence are marked `Not Applicable` with rationale. -- [ ] Product decision gaps use `Unknown` or `[NEEDS CLARIFICATION]` only when product requirements are missing, not when provider evidence is unavailable. -- [ ] Responsive visual requirements block PASS only when required source-backed state or viewport evidence is missing for a feature that depends on provider evidence. -- [ ] Layout, spacing, typography, colors, effects, assets, and clipping requirements are explicit. -- [ ] Required client visual assets have source refs, asset source strategy, required variants, fallback policy, and blocker status. -- [ ] Required component mappings and variant coverage are explicit or marked as blocking clarification items. -- [ ] Default, hover, focus, active, disabled, loading, empty, and error states are explicit or marked as missing. -- [ ] Required breakpoints, reflow rules, scrolling, minimum widths, safe areas, and responsive behavior is explicit. -- [ ] Copy, icons, images, fonts, numeric formats, and placeholder content are explicit. -- [ ] Keyboard, focus, semantics, contrast, ARIA, form error behavior, and accessibility requirements are explicit. -- [ ] Accepted exceptions are defined as traceable exception refs and rationale. +## UI/UX Specification Readiness + +- [ ] Apply this section when `spec.md` marks UI/UX Applicability as Required or Unknown. +- [ ] UI/UX Applicability is declared as `Required`, `Not Applicable`, or `Unknown`. +- [ ] Not Applicable includes a concrete product-level rationale. +- [ ] Unknown applicability appears in Blocking Items when it affects downstream planning. +- [ ] Every applicable requirement has a stable `UI-###` or `UX-###` ID. +- [ ] Required UI/UX requirements describe observable user outcomes rather than implementation details. +- [ ] Experience goals and critical journeys are explicit. +- [ ] Information architecture and navigation outcomes are explicit when applicable. +- [ ] Interaction feedback, validation behavior, and recovery outcomes are explicit. +- [ ] Required default, loading, empty, error, disabled, success, hover, and focus states are explicit. +- [ ] Responsive reflow, scrolling, safe-area, viewport, and long-content behavior are explicit. +- [ ] Keyboard, focus, semantics, contrast, announcements, and error accessibility behavior are explicit. +- [ ] Required copy, visual hierarchy, typography, color use, iconography, imagery, and formatting are explicit. +- [ ] Every Required UI/UX requirement has an objective acceptance criterion. + +## UI/UX Coverage Matrix + +| Requirement ID | Source `spec.md` Section | Applicability | Readiness | States Covered | Responsive Coverage | Accessibility Coverage | Blocking Item ID | +| --- | --- | --- | --- | --- | --- | --- | --- | +| UI-001 | `spec.md#...` | Required | Ready|Blocked | default, error | mobile, desktop | keyboard, announcement | BI-... or none | + +- [ ] Applicability uses only `Required`, `Not Applicable`, or `Unknown`. +- [ ] Readiness uses only `Ready` or `Blocked`. +- [ ] Applicability and Readiness are evaluated independently. +- [ ] Every Required row cites its source `spec.md` section. +- [ ] Missing observable requirement text, required states, responsive behavior, accessibility behavior, content rules, or acceptance criteria sets Readiness to Blocked and lists a Blocking Item ID. +- [ ] Unknown applicability sets Readiness to Blocked when the unresolved decision prevents planning. +- [ ] Not Applicable rows include rationale and do not create implementation work. +- [ ] UI/UX Coverage Matrix is the only UI/UX specification-readiness matrix. ## Gate Status Gate Status: PASS|BLOCKED diff --git a/presets/workflow-preset/templates/plan-template.md b/presets/workflow-preset/templates/plan-template.md index f82b14ff4e..ed9a2967b1 100644 --- a/presets/workflow-preset/templates/plan-template.md +++ b/presets/workflow-preset/templates/plan-template.md @@ -12,9 +12,9 @@ - Interface contracts: `./contracts/` - Validation path: `./quickstart.md` -## Visual fidelity navigation +## UI/UX Planning Navigation -- Visual/IR source refs and readiness inputs: `./research.md` -- Visual interaction contracts: `./contracts/uif/` and `./contracts/behavior/` -- Visual flow sequences: `./contracts/sequences.md` -- Non-visual acceptance execution: `./quickstart.md` +- UI/UX planning decisions: `./research.md` +- Interaction contracts: `./contracts/uif/` and `./contracts/behavior/` +- Cross-boundary UI flows: `./contracts/sequences.md` +- UI/UX acceptance paths: `./quickstart.md` diff --git a/presets/workflow-preset/templates/spec-template.md b/presets/workflow-preset/templates/spec-template.md new file mode 100644 index 0000000000..a5056d7a2b --- /dev/null +++ b/presets/workflow-preset/templates/spec-template.md @@ -0,0 +1,53 @@ +{CORE_TEMPLATE} + +## UI/UX Specification + +**Applicability**: Required | Not Applicable | Unknown + + + +### Experience Goals + +- **UX-001**: [User goal and measurable experience outcome] + +### Information Architecture and Navigation + +- **UX-002**: [Required destination, navigation path, or content hierarchy] + +### Interaction and Feedback + +- **UX-003**: [User action and the observable feedback or recovery outcome] + +### UI States + +- **UI-001**: [Required default, loading, empty, error, disabled, success, or other state] + +### Responsive Behavior + +- **UI-002**: [Observable reflow, scrolling, safe-area, or viewport behavior] + +### Accessibility + +- **UI-003**: [Keyboard, focus, semantics, contrast, announcement, or error behavior] + +### Content and Visual Requirements + +- **UI-004**: [Required copy, hierarchy, typography, color use, iconography, imagery, or formatting] + +### UI/UX Acceptance Criteria + +| Requirement ID | Surface or Journey | Observable Requirement | Applicable States | Viewports | Acceptance Criterion | Status | +| --- | --- | --- | --- | --- | --- | --- | +| UI-001 | [surface or journey] | [observable requirement] | [states or N/A] | [viewports or N/A] | [objective acceptance criterion] | Required | diff --git a/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md b/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md index 3c0fec6367..6e7cf39b38 100644 --- a/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md +++ b/presets/workflow-preset/tests/contracts/speckit-cross-agent-protocol.md @@ -21,12 +21,12 @@ Every command profile defines these fields: ### `speckit.specify.single_core` - `stage`: requirement projection. - `owner_agent`: Specify Core Agent. -- `input_scope`: user prompt, product notes, confirmed external intake refs, visual SSOT refs, HTML SSOT refs, structured IR refs, screenshots, and visual proof refs. +- `input_scope`: user prompt, product notes, confirmed product decisions, and existing requirement context selected by core Spec Kit behavior. - `allowed_reads`: command inputs and existing requirement context selected by core Spec Kit behavior. - `allowed_writes`: `spec.md` only. -- `output_contract`: stakeholder-readable requirements with explicit source-backed facts, assumptions, visual/UI status, and provider blockers. +- `output_contract`: stakeholder-readable requirements with explicit assumptions, UI/UX Applicability, stable `UI-###` and `UX-###` IDs, and observable acceptance criteria. - `validation_gate`: specification quality validation in `/speckit.specify`. -- `stop_conditions`: missing feature description, unsupported inference, or provider evidence treated as product semantics. +- `stop_conditions`: missing feature description, unsupported inference, or unresolved product decisions that prevent a testable specification. - `fallback`: single-core execution; no persistent handoff, receipt, or worker queue. ### `speckit.plan.stage_local_planning` @@ -43,12 +43,12 @@ Every command profile defines these fields: ### `speckit.tasks.stage_local_derivation` - `stage`: task derivation. - `owner_agent`: Tasks Core Agent. -- `input_scope`: user stories, behavior contracts, interface contracts, research decisions, quickstart validation paths, visual readiness rows, visual/IR traceability refs, and review scopes. +- `input_scope`: user stories, behavior contracts, interface contracts, research decisions, quickstart validation paths, ready UI/UX requirement rows, and review scopes. - `allowed_reads`: scoped derivation payloads; no full artifact tree unless the payload explicitly lists it. - `allowed_writes`: `tasks.md` only. - `output_contract`: task candidates, evidence refs, source refs, blockers, and `context_gaps`. - `validation_gate`: task-derivation blocker aggregation and existing checklist format. -- `stop_conditions`: missing Required case coverage, missing required provider evidence, or unresolved task-derivation `context_gaps`. +- `stop_conditions`: missing Required case coverage, Blocked or Unknown UI/UX readiness, or unresolved task-derivation `context_gaps`. - `fallback`: Tasks Core Agent processes one assigned scope at a time; no handoff, receipt, write-path metadata, or worker dispatch. ### `speckit.analyze.read_only_parallel_review` 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 37ebdc7ef4..5ef4f6e0da 100644 --- a/presets/workflow-preset/tests/contracts/speckit-cross-agent-subagents.md +++ b/presets/workflow-preset/tests/contracts/speckit-cross-agent-subagents.md @@ -70,7 +70,7 @@ Use `agent-runtime=` as a prompt hint. The manifest re - Write only allowed_write_paths; directory authorization includes files below the directory - 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, quickstart path, Visual Item ID, Requirement Status, UIF path, visual SSOT ref, HTML SSOT ref, structured IR ref, Client Asset Contract entry, quickstart validation path, or captured command output +- write receipt_path as speckit.implement.receipt.v1 with validation_evidence references to a relevant BDD scenario, behavior assertion, API contract, UIF path, `UI-###` or `UX-###` requirement ID, 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 ## Worker Prompts @@ -119,7 +119,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/UI task types `visual_setup`, `visual_implementation`, `ui_acceptance`, or `asset_binding`; 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 +- UI/UX shard candidates must come only from `tasks.md` task types `ui_setup`, `ui_implementation`, `ui_accessibility`, or `ui_acceptance`; preserve the UI/UX Specification Readiness filter from `/speckit.tasks`: only Applicability `Required` plus Readiness `Ready` is executable; do not create UI/UX shards for `Not Applicable`, `Unknown`, or `Blocked`; route unresolved rows back to `/speckit.clarify` or `/speckit.checklist` - infer `vertical_capability` from task section heading, task text, referenced paths - group candidates only when lifecycle dependencies, vertical_capability, and allowed_write_paths match - serial shards with explicit dependencies may declare shared write paths; same dispatch layer must not overlap allowed_write_paths @@ -130,9 +130,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, Visual Item ID, Requirement Status, accepted exception rule, visual SSOT refs, HTML SSOT refs, structured IR 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 required HTML SSOT refs, missing structured IR refs, missing asset variants, or missing fallback policy become `context_gaps`, not implementation scope +- include behavior contract constraints, applicable `UI-###` and `UX-###` requirements, Applicability, Readiness, required states, viewport behavior, accessibility behavior, content rules, and acceptance criteria +- UI/UX task context maps only Required and Ready requirements to implementation, test, fixture, configuration, and validation paths +- UI/UX Applicability mismatches, `Unknown`, `Blocked`, missing required states, missing responsive behavior, missing accessibility behavior, or missing acceptance criteria become `context_gaps`, not implementation scope - record unresolved required context as `context_gaps` ## Path and Receipt Rules (Path Rules) @@ -143,4 +143,4 @@ vertical_capability: - receipt changed_paths may equal an allowed write path or be inside an allowed directory - implementation changed_paths require at least one Code Review Receipt before task_commit - code review uses the union of all Code Review Receipts to cover implementation changed_paths -- Receipt Rejection: mismatched `shard_id`; `task_ids` outside handoff; `completed_task_ids` outside handoff; 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, quickstart path, Visual Item ID, Requirement Status, UIF path, visual SSOT ref, HTML SSOT ref, structured IR ref, Client Asset Contract entry, quickstart/contract validation command evidence; receipt path not equal to handoff `task_status_update.receipt_path`; missing `task_type: code_review`, `review_conclusion.checked_sources`, `data_side_effect_review`, `consistency_repairs`, or needed `deferred_validation_todos` +- Receipt Rejection: mismatched `shard_id`; `task_ids` outside handoff; `completed_task_ids` outside handoff; 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, UIF path, `UI-###` or `UX-###` requirement ID, quickstart/contract validation command evidence; receipt path not equal to handoff `task_status_update.receipt_path`; missing `task_type: code_review`, `review_conclusion.checked_sources`, `data_side_effect_review`, `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 a8bbe3975e..fef5f2f63f 100644 --- a/presets/workflow-preset/tests/test_preset_contract.py +++ b/presets/workflow-preset/tests/test_preset_contract.py @@ -43,24 +43,7 @@ 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" -CANONICAL_RESPONSIVE_VISUAL_RULE = ( - "Responsive visual requirements block PASS only when required source-backed " - "state or viewport evidence is missing for a feature that depends on provider evidence" -) -FORBIDDEN_VISUAL_COMPAT_TERMS = ( - "legacy visual", - "previous-version", - "previous version", - "backward-compatible", - "backward compatible", - "fallback visual", - "fallback visual rule", - "compatibility mode", - "历史版本", - "旧版兼容", - "兼容旧版", - "回退视觉规则", -) +SPEC_TEMPLATE_PATH = REPO_ROOT / "templates" / "spec-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" @@ -514,7 +497,7 @@ def test_preset_manifest_contract(self) -> None: ) provides = data["provides"]["templates"] - self.assertEqual(30, len(provides)) + self.assertEqual(31, 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) @@ -539,6 +522,12 @@ def test_preset_manifest_contract(self) -> None: self.assertEqual("constitution-template", constitution_template["replaces"]) self.assertEqual("wrap", constitution_template["strategy"]) + spec_template = entries["spec-template"] + self.assertEqual("template", spec_template["type"]) + self.assertEqual("templates/spec-template.md", spec_template["file"]) + self.assertEqual("spec-template", spec_template["replaces"]) + self.assertEqual("wrap", spec_template["strategy"]) + for command_name in ("speckit.plan", "speckit.tasks"): command = entries[command_name] self.assertEqual("command", command["type"]) @@ -559,7 +548,7 @@ def test_preset_manifest_contract(self) -> None: entries["speckit.clarify"]["description"], ) self.assertEqual( - "Wrap core checklist generation with BDD, NFR, and Visual Fidelity readiness gate", + "Wrap core checklist generation with BDD, NFR, and UI/UX specification readiness gate", entries["speckit.checklist"]["description"], ) @@ -677,7 +666,7 @@ def test_plan_command_wrapper_contract(self) -> None: "Formal Contract Agent", "Design Artifact Agent", "Validation Planning Agent", - "Visual Planning Agent", + "UI/UX Planning Agent", ): self.assertIn(agent_role, command) self.assertIn("Each payload declares assigned scope, allowed reads, allowed sections, and output contract", command) @@ -697,49 +686,42 @@ def test_plan_template_navigation_contract(self) -> None: self.assertIn("./contracts/", template) self.assertIn("./quickstart.md", template) - def test_plan_visual_substage_enhancement_contract(self) -> None: + def test_plan_ui_ux_substage_enhancement_contract(self) -> None: command = PLAN_COMMAND_PATH.read_text(encoding="utf-8") template = PLAN_TEMPLATE_PATH.read_text(encoding="utf-8") readme = README_PATH.read_text(encoding="utf-8") governance = EXTENSION_GOVERNANCE_PATH.read_text(encoding="utf-8") for term in ( - "Visual Planning Responsibilities", - "visual and IR planning inputs", - "Visual Item ID", - "HTML SSOT refs", - "structured IR refs", - "readiness status", - "unresolved blocker refs", - "do not copy the Visual Fidelity Evidence Matrix into `research.md`", - "rebuild provider evidence matrices", - "Do not define visual validation strategy", - "visual_item_refs", - "viewport_matrix_refs", - "state_matrix_refs", - "visual_proof_refs", - "accepted_exception_refs", - "UI interaction sequence", - "visual state handoff points", - "responsive branch trigger refs", + "UI/UX Planning Responsibilities", + "accepted `UI-###` and `UX-###` requirements", + "Applicability is `Required` and Readiness is `Ready`", + "return to `/speckit.checklist` or `/speckit.clarify`", + "Do not project `Not Applicable` rows", + "interaction tradeoffs", + "viewport support", + "accessibility approach", + "Reference the applicable `UI-###` or `UX-###` requirement IDs", + "UI interaction sequences", + "responsive branch triggers", + "executable acceptance paths", ): self.assertIn(term, command) for term in ( - "Visual fidelity navigation", - "Visual/IR source refs and readiness inputs: `./research.md`", - "Visual interaction contracts: `./contracts/uif/` and `./contracts/behavior/`", - "Visual flow sequences: `./contracts/sequences.md`", - "Non-visual acceptance execution: `./quickstart.md`", + "UI/UX Planning Navigation", + "UI/UX planning decisions: `./research.md`", + "Interaction contracts: `./contracts/uif/` and `./contracts/behavior/`", + "Cross-boundary UI flows: `./contracts/sequences.md`", + "UI/UX acceptance paths: `./quickstart.md`", ): self.assertIn(term, template) for document in (readme, governance): self.assertIn("research.md", document) - self.assertIn("visual/IR source refs", document) - self.assertIn("contracts formalize visual interaction and state constraints", document) - self.assertIn("contracts/sequences.md records visual state flow only when it affects cross-boundary sequencing", document) - self.assertNotIn("research.md records visual validation decisions", document) + self.assertIn("UI/UX", document) + self.assertIn("contracts", document) + self.assertIn("contracts/sequences.md", document) self.assertIn( "fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail", @@ -899,7 +881,7 @@ def test_tasks_command_wrapper_contract(self) -> None: self.assertIn("strategy: wrap", tasks) self.assertIn("implementation, integration, orchestration", tasks) self.assertIn("existing checklist format and user-story organization", tasks) - self.assertIn("`/speckit.tasks` owns implementation, non-visual validation, and review task definition in `tasks.md`", tasks) + self.assertIn("`/speckit.tasks` owns implementation, validation, and review task definition in `tasks.md`", tasks) self.assertIn("must not invent validation strategy", tasks) self.assertIn("change requirements, update contracts, or widen scope", tasks) self.assertIn("Task-Derivation Subagents", tasks) @@ -910,7 +892,7 @@ def test_tasks_command_wrapper_contract(self) -> None: for agent_role in ( "Story Task Agent", "Contract Validation Agent", - "Visual Task Agent", + "UI/UX Task Agent", "Review Task Agent", ): self.assertIn(agent_role, tasks) @@ -943,28 +925,27 @@ def test_tasks_command_wrapper_contract(self) -> None: self.assertIn("Final Code Review", tasks) self.assertIn("append the final phase after user-story tasks", tasks) self.assertIn("final review scope taxonomy", tasks) - self.assertIn("`boundary`, `interface_contract`, `visual`, `data_side_effect`, `behavior_contract`, `sequence_consistency`, and `asset_binding`", tasks) + self.assertIn("`boundary`, `interface_contract`, `ui_ux`, `data_side_effect`, `behavior_contract`, and `sequence_consistency`", tasks) self.assertIn("Checked sources include", tasks) self.assertIn("`contracts/uif/`", tasks) - self.assertIn("`spec.md` Client Asset Contract entries", tasks) - self.assertIn("Visual Fidelity Readiness", tasks) + self.assertIn("`spec.md` UI/UX requirements", tasks) + self.assertIn("UI/UX Specification Readiness", tasks) self.assertIn("data side-effect review", tasks) self.assertIn("field-level update/delete", tasks) self.assertIn("runtime database writes", tasks) self.assertIn("boundary review", tasks) self.assertIn("task scope stays within planned `M + U`", tasks) - self.assertIn("no implementation task changed `spec.md`, `contracts/`, readiness checklists, or Visual Fidelity Readiness", tasks) + self.assertIn("no implementation task changed `spec.md`, `contracts/`, readiness checklists, or UI/UX Specification Readiness", tasks) self.assertIn("UI consistency review", tasks) - self.assertIn("implemented UI states and viewport behavior", tasks) - self.assertIn("visual/IR traceability refs", tasks) - self.assertIn("UI/visual task taxonomy", tasks) + self.assertIn("implemented journeys, navigation, states, viewport behavior", tasks) + self.assertIn("accepted `UI-###` and `UX-###` requirements", tasks) + self.assertIn("UI/UX task taxonomy", tasks) self.assertIn("story-local task granularity", tasks) - self.assertIn("`visual_setup` -> `visual_implementation` -> `ui_acceptance` or `asset_binding`", tasks) - self.assertIn("Do not create a separate visual lifecycle phase", tasks) - self.assertIn("Visual/UI tasks must name concrete source, test, fixture, configuration, asset paths, and visual/IR traceability refs", tasks) + self.assertIn("`ui_setup` -> `ui_implementation` -> `ui_accessibility` and/or `ui_acceptance`", tasks) + self.assertIn("Do not create a separate UI/UX lifecycle phase", tasks) + self.assertIn("UI/UX tasks must name the applicable `UI-###` or `UX-###` requirement ID", tasks) self.assertIn("report a readiness blocker instead of generating an ambiguous task", tasks) - self.assertIn("Client Asset Contract bindings, variants, and fallback policy", tasks) - self.assertIn("screenshot comparison, visual diff, baseline capture, or final visual review", tasks) + self.assertIn("required state, viewport, and accessibility coverage", tasks) self.assertIn("real-system e2e environment readiness", tasks) self.assertIn("Review evidence binding", tasks) self.assertIn("concrete review scope, source artifacts, implementation surfaces, and evidence refs", tasks) @@ -995,6 +976,10 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: specify = SPECIFY_COMMAND_PATH.read_text(encoding="utf-8") clarify = CLARIFY_COMMAND_PATH.read_text(encoding="utf-8") checklist = CHECKLIST_COMMAND_PATH.read_text(encoding="utf-8") + spec_template = SPEC_TEMPLATE_PATH.read_text(encoding="utf-8") + checklist_template = BEHAVIOR_TEMPLATE_PATHS[ + "behavior-testability-checklist-template" + ].read_text(encoding="utf-8") for command in (specify, clarify, checklist): self.assertIn("{CORE_TEMPLATE}", command) @@ -1004,305 +989,81 @@ def test_behavior_first_command_wrapper_contracts(self) -> None: command, ) - self.assertIn("Spec-Only Requirement Policy", specify) - self.assertIn("Wrapper Input Additions", specify) - self.assertIn("Wrapper Preflight Additions", specify) - self.assertIn("Wrapper Outline Additions", specify) - self.assertNotIn("## User Input", specify) - self.assertNotIn("## Pre-Execution Checks", specify) - 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", - "Focus on WHAT users need and WHY", - "Avoid HOW to implement", - "Limit [NEEDS CLARIFICATION] markers to the highest-impact unresolved product decisions", + "Spec-Only Requirement Policy", + "Preset-added requirement output writes only `spec.md`", + "Resolve the active `spec-template`", + "only stable UI/UX output structure", + "`Required`: populate every applicable UI/UX field", + "`Not Applicable`: record a concrete product-level rationale", + "`Unknown`: record the unresolved product decision", + "stable `UX-###` IDs", + "stable `UI-###` IDs", + "observable user outcomes", "Specification Quality Validation", "Done When", ): self.assertIn(term, specify) + self.assertNotIn("## User Input", specify) + self.assertNotIn("## Pre-Execution Checks", specify) + self.assertNotIn("## UI/UX Specification", specify) + self.assertNotIn( + "| Requirement ID | Surface or Journey | Observable Requirement |", + specify, + ) + + self.assertIn("{CORE_TEMPLATE}", spec_template) for term in ( - "confirmed external intake facts", - "visual SSOT refs", - "HTML SSOT refs", - "structured IR refs", - "evidence refs", - "does not perform intake", - "call provider tools", - "parse HTML SSOT bundles", - "re-parse structured IR artifacts", - "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", - "HTML SSOT refs", - "structured IR refs", - "state and viewport refs", - "Client Asset Contract facts", - "asset source strategy", - "required variants", - "fallback policy", - "blocker status", - "Promote only confirmed product facts and 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", - "missing product decisions become `[NEEDS CLARIFICATION]`", - "missing provider or intake evidence for a feature that depends on that evidence becomes `[BLOCKED: PROVIDER_EVIDENCE]`", - "features that do not depend on HTML SSOT, structured IR, or provider evidence are `Not Applicable`", - "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", - "Do not promote provider evidence gaps into product requirements or `[NEEDS CLARIFICATION]` markers", - "[NEEDS CLARIFICATION]", - "visual SSOT refs preserved", + "## UI/UX Specification", + "**Applicability**: Required | Not Applicable | Unknown", + "### Experience Goals", + "### Information Architecture and Navigation", + "### Interaction and Feedback", + "### UI States", + "### Responsive Behavior", + "### Accessibility", + "### Content and Visual Requirements", + "### UI/UX Acceptance Criteria", + "| Requirement ID | Surface or Journey | Observable Requirement | Applicable States | Viewports | Acceptance Criterion | Status |", ): - self.assertIn(term, specify) - self.assertLessEqual(len(specify.splitlines()), 70) - for forbidden in ( - "/speckit.plan", - "/speckit.checklist", - "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", - "behavior/data-fixtures.intent.json", - "behavior/open-questions.json", - "formal behavior contracts", - "interface schemas", - "validation commands", - "task plans", - "design artifacts", - "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) - self.assertNotIn("contracts/uif/", specify) - - self.assertIn("Spec-Only Clarification Policy", clarify) - self.assertIn("Wrapper Input Additions", clarify) - self.assertIn("Wrapper Preflight Additions", clarify) - self.assertIn("Wrapper Outline Additions", clarify) - self.assertNotIn("## User Input", clarify) - self.assertNotIn("## Pre-Execution Checks", clarify) - self.assertIn("Use `spec.md` as the clarification source", clarify) - 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("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("Do not call provider tools", clarify) - self.assertIn("Do not re-extract design facts", clarify) - self.assertIn("re-parse provider design links", clarify) - self.assertIn("parse HTML SSOT bundles", clarify) - self.assertIn("re-parse structured IR artifacts", 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) - self.assertIn("Do NOT output them all at once", clarify) - self.assertIn("Never reveal future queued questions", clarify) - self.assertIn("Maximum of 5 total questions", clarify) - self.assertIn("Format recommendations as `**Recommended:** Option [X] - `", clarify) - self.assertIn("Keep the rationale short and decision-focused", clarify) - self.assertNotIn("", clarify) - self.assertIn("Suggested", clarify) - self.assertIn("2-5", clarify) - self.assertIn("<=5 words", clarify) - self.assertIn("yes", clarify) - self.assertIn("recommended", clarify) - self.assertIn("suggested", clarify) - self.assertIn("Save `spec.md` after each accepted answer", clarify) - self.assertIn("## Clarifications", clarify) - 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) - self.assertIn("no contradictory earlier statement remains", clarify) - self.assertIn("Do not update checklist artifacts", clarify) - self.assertIn("report checklist impact as unresolved readiness context", clarify) - self.assertNotIn("FEATURE_DIR/checklists/requirements.md", clarify) - self.assertNotIn("Only toggle the `[ ]`/`[x]` marker", clarify) - self.assertIn("hooks.before_clarify", clarify) - 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) - self.assertIn("component reuse constraints", clarify) - self.assertIn("data semantics", clarify) - self.assertIn("acceptance evidence", clarify) - self.assertIn("accepted exception approval flow", 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", - "behavior/behavior-scenarios.draft.json", - "behavior/uif.intent.json", - "behavior/data-fixtures.intent.json", - "behavior/open-questions.json", - "use_provider_tool", - "get_design_context", - "fetch provider design URL", - "read provider design URL", - "Provider Evidence Packet", - "Design Requirement" + " Intake", - "Inferred from Structure", - "update checklists/behavior-testability.md", + self.assertIn(term, spec_template) + + for term in ( + "Use `spec.md` as the clarification source", + "UI/UX Requirement Clarification Strategy", + "UI/UX Applicability `Unknown`", + "incomplete `UI-###` or `UX-###` requirements", + "Ask at most 5 high-impact questions", + "exactly one question at a time", + "Responsive reflow", + "accessibility behavior", + "Objective UI/UX acceptance criteria", + "Save `spec.md` after each accepted answer", + "Do not generate checklist artifacts", ): - self.assertNotIn(forbidden, clarify) - - self.assertIn('Checklist Purpose: "Unit Tests for English"', checklist) - self.assertIn("NOT for verification/testing", checklist) - self.assertIn("CORE PRINCIPLE - Test the Requirements, Not the Implementation", checklist) - self.assertIn("Checklist questions must use requirement-quality forms", checklist) - self.assertIn("$ARGUMENTS", checklist) - self.assertIn("dynamic clarifying questions", checklist) - self.assertIn("no pre-baked catalog", checklist) - self.assertIn("Q1/Q2/Q3", checklist) - self.assertIn("Q4/Q5", checklist) - self.assertIn("create the file when absent", checklist) - self.assertIn("append or update without deleting existing checklist content", checklist) - self.assertIn("update mode", checklist) - self.assertIn("full path", checklist) - self.assertIn("item count", checklist) - self.assertIn("focus areas", checklist) - self.assertIn("depth level", checklist) - self.assertIn("actor/timing", checklist) - self.assertIn("must-have items", checklist) - self.assertIn("BDD Readiness Gate", checklist) - self.assertIn("checklists/behavior-testability.md", checklist) - self.assertIn("directly from `spec.md`", checklist) - self.assertIn("plan-entry quality gate", checklist) - self.assertIn("Do not proceed to `/speckit.plan`", checklist) - self.assertIn("Requirement ambiguity returns to `/speckit.clarify` or `/speckit.specify`", checklist) - self.assertIn("User Story Readiness", checklist) - self.assertIn("Acceptance Criteria Quality", checklist) - self.assertIn("Scenario Coverage", checklist) - self.assertIn("Case Coverage Matrix", checklist) - self.assertIn("one row per story or capability case type", checklist) - self.assertIn("case status: Required|Not Applicable|Unknown", checklist) - self.assertIn("Each row must have a stable Case ID", checklist) - self.assertIn("Required rows must cite the source `spec.md` section", checklist) - self.assertIn("Scenario IDs and `case_coverage_blockers` are assigned during `/speckit.plan`", checklist) - self.assertIn("Not Applicable requires rationale", checklist) - self.assertIn("Unknown must appear in Blocking Items", checklist) - self.assertIn("Required case type without observable acceptance behavior blocks PASS", checklist) - self.assertIn("Given Readiness", checklist) - self.assertIn("When Readiness", checklist) - self.assertIn("Then Readiness", checklist) - self.assertIn("Non-Functional Requirement Readiness", checklist) - self.assertIn("Required", checklist) - self.assertIn("Not Applicable", checklist) - self.assertIn("Unknown", checklist) - self.assertIn("performance, security and privacy, reliability and recovery", checklist) - self.assertIn("accessibility, compliance and auditability, observability", checklist) - self.assertIn("compatibility, data lifecycle, and cost or operational constraints", checklist) - self.assertIn("explicitly declared in `spec.md`", checklist) - self.assertIn("verifiable product-level criteria", checklist) - self.assertIn("Do not require technical designs", checklist) - self.assertIn("Required but missing", checklist) - self.assertIn("Required but not verifiable", checklist) - self.assertIn("Unknown and affects downstream design", checklist) + self.assertIn(term, clarify) + for term in ( - "Visual Fidelity Readiness", - "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", - "HTML SSOT refs", - "structured IR refs", - "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", - "external intake readiness status when cited", - "visual SSOT refs", - "provider blocker status", - "source traceability", - "readiness input", - "BDD, NFR, and Visual Fidelity readiness gate", - "accepted exception refs", + 'Checklist Purpose: "Unit Tests for English"', + "NOT for verification/testing", + "CORE PRINCIPLE - Test the Requirements, Not the Implementation", + "Resolve `behavior-testability-checklist-template`", + "only stable authority for checklist headings", + "Do not reproduce those structures in this command", + "Populate the resolved checklist template directly from `spec.md`", + "keep requirement applicability", + "separate from specification readiness", + "Gate Status: PASS", "Gate Status: BLOCKED", - "state, responsive, accessibility, component mapping, and accepted exception", - CANONICAL_RESPONSIVE_VISUAL_RULE, - "Use one Visual Fidelity Evidence Matrix as the single visual readiness record", - "Do not add historical visual rules or alternate visual decision paths", + "BDD/NFR/UI/UX readiness status", ): self.assertIn(term, checklist) - for term in ( - "| Visual Item ID | Source `spec.md` section | Requirement Status | Fidelity Scope | Screenshot Level | Evidence Refs | Visual Proof Required | Blocking Item ID | Exception Rule |", - "Screenshot evidence level", - "declared visual proof required", - "proof level sufficiency", - "screenshot sufficiency", - "raw metadata completeness", - "metadata index completeness proof", - "node inventory parity", - "blocker lint errors", - "Responsive visual readiness must record viewport-specific evidence or set Gate Status: BLOCKED", - ): - self.assertNotIn(term, checklist) - self.assertIn("Gate Status", checklist) - self.assertIn("PASS", checklist) - self.assertIn("BLOCKED", checklist) - self.assertIn("Blocking Items", checklist) - self.assertIn("checklist artifacts only", checklist) - self.assertIn("BDD, NFR, and Visual Fidelity readiness status", checklist) - self.assertIn( - "Provider evidence readiness blockers return to the external intake extension, not `/speckit.clarify`", + self.assertNotIn("## UI/UX Coverage Matrix", checklist) + self.assertNotIn( + "| Requirement ID | Source `spec.md` Section | Applicability | Readiness |", checklist, ) + self.assertIn("## UI/UX Coverage Matrix", checklist_template) def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") @@ -1345,18 +1106,12 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "checklists/behavior-testability.md has passed", "Blocking Items: none` or a `Blocking Items` section containing only `- none`", "before core research or design work", - "visual fidelity scope", - "source refs", - "HTML SSOT refs", - "structured IR refs", - "screenshot refs", - "visual proof refs", - "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", + "UI/UX Planning Responsibilities", + "accepted `UI-###` and `UX-###` requirements", + "Applicability is `Required` and Readiness is `Ready`", + "If a row is `Unknown` or `Blocked`", "report-only/no-write upstream gate failure", - "Do not project `Not Applicable` rows into visual planning outputs", + "Do not project `Not Applicable` rows into planning outputs", "behavior/behavior-scenarios.draft.json", "report-only/no-write failure", "must not create or update behavior artifacts", @@ -1376,15 +1131,9 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "contracts/bdd/", "contracts/uif/", "contracts/behavior/", - "`spec.md` visual acceptance requirements", - "`checklists/behavior-testability.md` Visual Fidelity Readiness", - "HTML SSOT refs", - "structured IR refs", - "screenshot refs", - "visual proof refs", - "visual SSOT refs", - "external evidence refs", - "visual fidelity requirements", + "`spec.md` UI/UX requirements", + "`checklists/behavior-testability.md` UI/UX Specification Readiness", + "`UI-###` and `UX-###` requirements", "test-first", "existing checklist format and user-story organization", "For each BehaviorScenarioInstance", @@ -1394,20 +1143,18 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "verification evidence task", "Expected UIF contract step with type `user_event`", "Expected UIF contract step with type `api_call`", - "UI/visual task taxonomy", + "UI/UX task taxonomy", "`ui_acceptance`", "UI acceptance task", - "viewport/state requirement refs", "required state and viewport coverage", - "visual/IR traceability ref", + "accessibility behavior", "For each quickstart validation path", "derive the validation level", "fixture strategy, external-system execution mode", "inline evidence requirement", "Planning Input Taxonomy", - "`/speckit.tasks` owns implementation, non-visual validation, and review task definition in `tasks.md`", + "`/speckit.tasks` owns implementation, validation, and review task definition in `tasks.md`", "must not invent validation strategy", - "visual validation work", "validation level taxonomy", "fixture strategy and external-system execution mode taxonomy", "Evidence binding", @@ -1416,56 +1163,35 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "`ui_acceptance`", "`data_side_effect_validation`", "`integration_e2e_validation`", - "Client Asset Contract", - "derive asset preparation, binding, implementation, and non-visual acceptance 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 UI implementation, asset binding, and non-visual acceptance 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, repair evidence, re-parse provider artifacts, or define visual validation strategy", - "only decomposes visual specifications that already passed the readiness gate", - "Do not create a second readiness rule", - "HTML SSOT refs", - "structured IR refs", - "external intake artifacts", + "Use UI/UX Specification Readiness as the only UI/UX planning-readiness source", + "Applicability is `Required` and Readiness is `Ready`", + "Do not generate implementation, validation, acceptance, or review tasks for `Not Applicable`, `Unknown`, or `Blocked` rows", + "Route `Unknown` and `Blocked` requirement rows back", + "only decomposes UI/UX specifications that passed the readiness gate", "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`", "For each BehaviorScenarioInstance with type", "derive fixture, contract or BDD test, implementation, and verification evidence tasks", "UI consistency review", - "implemented UI states and viewport behavior", - "UI/visual task taxonomy", + "implemented journeys, navigation, states, viewport behavior", + "UI/UX task taxonomy", "story-local task granularity", - "`visual_setup` -> `visual_implementation` -> `ui_acceptance` or `asset_binding`", - "`asset_binding`", - "`visual_setup`, `visual_implementation`, `ui_acceptance`, and `asset_binding` are the only visual/UI task types", - "without screenshot comparison, visual diff, baseline capture, or final visual review", - "empty/error/loading/disabled/hover/focus states", - "license or authorization refs", - "Do not create a separate visual lifecycle phase", - "Visual/UI tasks must name concrete source, test, fixture, configuration, asset paths, and visual/IR traceability refs", + "`ui_setup` -> `ui_implementation` -> `ui_accessibility` and/or `ui_acceptance`", + "`ui_accessibility`", + "Do not create a separate UI/UX lifecycle phase", + "UI/UX tasks must name the applicable `UI-###` or `UX-###` requirement ID", "report a readiness blocker instead of generating an ambiguous task", - "Do not generate visual validation, screenshot comparison, visual diff, baseline capture, final visual review, or visual tasks for rows with `Requirement Status` `Not Applicable`, `Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`", - "Client Asset Contract bindings, variants, and fallback policy", + "Generate UI/UX tasks only from Required and Ready checklist rows", "Review evidence binding", "bounded repair permission", "final review scope taxonomy", - "`boundary`, `interface_contract`, `visual`, `data_side_effect`, `behavior_contract`, `sequence_consistency`, and `asset_binding`", + "`boundary`, `interface_contract`, `ui_ux`, `data_side_effect`, `behavior_contract`, and `sequence_consistency`", "boundary review", - "no implementation task changed `spec.md`, `contracts/`, readiness checklists, or Visual Fidelity Readiness", + "no implementation task changed `spec.md`, `contracts/`, readiness checklists, or UI/UX Specification Readiness", ): self.assertIn(term, tasks) - self.assertNotIn("task_type: visual_verification", tasks) - self.assertNotIn("`visual_validation`", tasks) - self.assertNotIn("`visual_verification`", tasks) - self.assertNotIn("`final_visual_review`", tasks) - self.assertNotIn("visual regression tests", tasks) self.assertNotIn("task_type: interface_validation", tasks) self.assertNotIn("task_type: data_side_effect_validation", tasks) self.assertNotIn("test-plan.md", tasks) @@ -1485,29 +1211,14 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: self.assertIn("BDD scenario", cross_agent) self.assertIn("behavior assertion", cross_agent) self.assertIn("API contract", cross_agent) - self.assertIn("quickstart path", cross_agent) - self.assertIn("visual fidelity requirements", cross_agent) - self.assertIn("visual SSOT refs", cross_agent) - self.assertIn("HTML SSOT refs", cross_agent) - self.assertIn("structured IR 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/UI 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 required HTML SSOT refs", cross_agent) - self.assertIn("missing structured IR refs", cross_agent) - self.assertNotIn("final_visual_review tasks", cross_agent) - self.assertNotIn("Visual Review Worker", cross_agent) - self.assertNotIn("`visual_validation`", cross_agent) - self.assertNotIn("`visual_verification`", cross_agent) - self.assertNotIn("`final_visual_review`", cross_agent) + self.assertIn("quickstart validation path", cross_agent) + self.assertIn("`UI-###` or `UX-###` requirement ID", cross_agent) + self.assertIn("UI/UX shard candidates", cross_agent) + self.assertIn("Applicability `Required` plus Readiness `Ready` is executable", cross_agent) + self.assertIn("do not create UI/UX shards for `Not Applicable`, `Unknown`, or `Blocked`", cross_agent) + self.assertIn("route unresolved rows back to `/speckit.clarify` or `/speckit.checklist`", cross_agent) + self.assertIn("required states", cross_agent) + self.assertIn("accessibility behavior", cross_agent) self.assertIn("planned `U` design object", cross_agent) self.assertIn("specific source, test, fixture, configuration, or receipt paths", cross_agent) @@ -1648,24 +1359,27 @@ def test_behavior_first_templates_exist_and_are_decoupled(self) -> None: self.assertIn("Cost and Operational Constraints", behavior_checklist_template) 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("UI/UX Specification Readiness", behavior_checklist_template) + self.assertIn( + "UI/UX Applicability is declared as `Required`, `Not Applicable`, or `Unknown`", + behavior_checklist_template, + ) + self.assertIn( + "Every applicable requirement has a stable `UI-###` or `UX-###` ID", + behavior_checklist_template, + ) self.assertIn( - "external intake readiness status when cited, visual SSOT refs, HTML SSOT refs, structured IR refs, other evidence refs, and provider blocker status", + "Required UI/UX requirements describe observable user outcomes rather than implementation details", behavior_checklist_template, ) - self.assertNotIn("raw metadata completeness", behavior_checklist_template) - self.assertNotIn("metadata index completeness proof", behavior_checklist_template) - self.assertNotIn("node inventory parity", behavior_checklist_template) - self.assertNotIn("blocker lint errors", behavior_checklist_template) - 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("Experience goals and critical journeys are explicit", behavior_checklist_template) + self.assertIn("Interaction feedback, validation behavior, and recovery outcomes are explicit", behavior_checklist_template) + self.assertIn("Responsive reflow, scrolling, safe-area, viewport, and long-content behavior are explicit", behavior_checklist_template) + self.assertIn("Keyboard, focus, semantics, contrast, announcements, and error accessibility behavior are explicit", behavior_checklist_template) + self.assertIn("Every Required UI/UX requirement has an objective acceptance criterion", behavior_checklist_template) + self.assertIn("UI/UX Coverage Matrix", behavior_checklist_template) + self.assertIn("Applicability and Readiness are evaluated independently", behavior_checklist_template) + self.assertIn("Readiness uses only `Ready` or `Blocked`", 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) @@ -1710,81 +1424,49 @@ def test_behavior_first_templates_exist_and_are_decoupled(self) -> None: ) self.assertIn('"intent": "state_invariant"', assertions_template) - def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: + def test_ui_ux_specification_readiness_contract(self) -> None: command = CHECKLIST_COMMAND_PATH.read_text(encoding="utf-8") template = BEHAVIOR_TEMPLATE_PATHS[ "behavior-testability-checklist-template" ].read_text(encoding="utf-8") for term in ( - "Use the behavior-testability checklist template as the visual gate authority", - "external intake readiness status when cited", - "Visual Fidelity Evidence Matrix records visual planning readiness", - "traceability refs", - "provider blocker status", - "accepted exception refs", - "Read visual facts from `spec.md` and cited evidence refs", - "do not call provider tools", - "re-extract external intake evidence", - "parse HTML SSOT bundles", - "re-parse structured IR artifacts", - "rebuild provider matrices", - "another visual readiness path", - CANONICAL_RESPONSIVE_VISUAL_RULE, - "Use one Visual Fidelity Evidence Matrix as the single visual readiness record", - "Do not add historical visual rules or alternate visual decision paths", - "Blocking Items", + "Resolve `behavior-testability-checklist-template`", + "only stable authority for checklist headings", + "Do not reproduce those structures in this command", + "Populate the resolved checklist template directly from `spec.md`", + "keep requirement applicability", + "separate from specification readiness", + "Gate Status: PASS", + "Gate Status: BLOCKED", ): self.assertIn(term, command) - for term in ( - "| 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", - "blocker lint errors", - "Responsive visual readiness must record viewport-specific evidence or set Gate Status: BLOCKED", - ): - self.assertNotIn(term, command) + self.assertNotIn("## UI/UX Coverage Matrix", command) + self.assertNotIn( + "| Requirement ID | Source `spec.md` Section | Applicability | Readiness |", + command, + ) for term in ( - "HTML SSOT refs", - "structured IR refs", - "Other Evidence Refs", - "Readiness Input", - "Accepted Exception Refs", - "Provider-dependent rows cite HTML SSOT refs", - "Missing required provider or intake evidence sets Gate Status: BLOCKED", - "Rows that do not depend on HTML SSOT, structured IR, or provider evidence are marked `Not Applicable` with rationale", - "Product decision gaps use `Unknown` or `[NEEDS CLARIFICATION]` only when product requirements are missing", - "Visual Fidelity Evidence Matrix is the only artifact that records visual planning readiness", - "does not call provider tools", - "re-extract external intake evidence", - "parse HTML SSOT bundles", - "re-parse structured IR artifacts", - "rebuild provider matrices", - "another visual readiness path", - CANONICAL_RESPONSIVE_VISUAL_RULE, - "Visual Fidelity Evidence Matrix", + "UI/UX Specification Readiness", + "UI/UX Coverage Matrix", "Source `spec.md` section", - "Requirement Status", - "Requirement Status is declared for each visual requirement", - "Other Evidence Refs", - "Accepted Exception Refs", - "lists the item in Blocking Items", + "Applicability", + "Readiness", + "States Covered", + "Responsive Coverage", + "Accessibility Coverage", "Blocking Items", - "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", + "Applicability and Readiness are evaluated independently", + "Readiness uses only `Ready` or `Blocked`", + "Every Required row cites its source `spec.md` section", + "UI/UX Coverage Matrix is the only UI/UX specification-readiness matrix", ): self.assertIn(term, template) - self.assertIn( - "Required client visual assets have source refs, asset source strategy, required variants, fallback policy, and blocker status.", - template, - ) self.assertEqual( len( re.findall( - r"^## Visual Fidelity Evidence Matrix$", + r"^## UI/UX Coverage Matrix$", template, flags=re.MULTILINE, ) @@ -1793,40 +1475,10 @@ def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: ) self.assertEqual( template.count( - "| Visual Item ID | Source `spec.md` section | Requirement Status | Depends on Provider Evidence | HTML SSOT Refs | Structured IR Refs | Other Evidence Refs | Readiness Input | Blocking Item ID | Accepted Exception Refs |" + "| Requirement ID | Source `spec.md` Section | Applicability | Readiness | States Covered | Responsive Coverage | Accessibility Coverage | Blocking Item ID |" ), 1, ) - self.assertEqual( - template.count( - "Use one Visual Fidelity Evidence Matrix as the single visual readiness record" - ), - 1, - ) - self.assertEqual(template.count(CANONICAL_RESPONSIVE_VISUAL_RULE), 1) - for forbidden in ( - "Screenshot evidence level", - "visual proof refs", - "L0|L1|L2|L3", - "declared visual proof required", - "proof level sufficiency", - "screenshot sufficiency", - "Missing screenshot evidence sets Gate Status: BLOCKED", - "High-fidelity requirements without L3 screenshot evidence set Gate Status: BLOCKED", - "Pixel-perfect requirements without L3 screenshot evidence set Gate Status: BLOCKED", - "L3 Visual Baseline", - "Responsive visual readiness must record viewport-specific evidence or set Gate Status: BLOCKED", - "Responsive visual readiness records viewport-specific evidence or sets Gate Status: BLOCKED", - "Screenshot Coverage Matrix", - "Visual Proof Matrix", - "Visual Restoration Checklist", - ): - self.assertNotIn(forbidden, template) - - for document in (command, template): - lowered = document.lower() - for forbidden in FORBIDDEN_VISUAL_COMPAT_TERMS: - self.assertNotIn(forbidden, lowered) def test_implement_command_is_agent_native_handoff_orchestrator(self) -> None: command = IMPLEMENT_COMMAND_PATH.read_text(encoding="utf-8") @@ -1860,23 +1512,21 @@ def test_implement_command_is_agent_native_handoff_orchestrator(self) -> None: "speckit.implement.receipt.v1.schema.json", "validators/speckit_implement_contract.py", "Use only this command, implement schemas, and implement validators as runtime contract sources", - "Runtime, shard, digest, path, asset binding, dispatch, Worker Prompt, and receipt rules are source-owned here", + "Runtime, shard, digest, path, dispatch, Worker Prompt, and receipt rules are source-owned here", "Use handoff JSON ", "allowed_read_paths", "allowed_write_paths", "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", - "do not repair provider evidence in `/speckit.implement`", - "`/speckit.implement` must not discover visual requirements, repair Visual Fidelity Readiness evidence", - "Visual worker receipts must reference the relevant Visual Item ID", + "UI/UX Implementation Boundary", + "UI/UX task input filter", + "Applicability `Required` and Readiness `Ready`", + "Do not create handoffs or worker instructions for rows with Applicability `Not Applicable`", + "or `Unknown`, or with Readiness `Blocked`", + "Route `Unknown` or `Blocked` rows back to `/speckit.clarify` or `/speckit.checklist`", + "`/speckit.implement` must not discover UI/UX requirements, repair readiness", + "UI/UX worker receipts must reference the relevant `UI-###` or `UX-###` requirement ID", "Follow cross-agent protocol profile: `speckit.implement.persistent_handoff_orchestration`", "Manual Worker Queue", "validate_manifest_structure()", @@ -3812,7 +3462,7 @@ def test_validate_receipt_contract_accepts_behavior_evidence_references(self) -> RECEIPT_PATH, ) - def test_validate_receipt_contract_rejects_generic_visual_evidence(self) -> None: + def test_validate_receipt_contract_rejects_generic_ui_ux_evidence(self) -> None: handoff = minimal_handoff( shard_id="S01-ui-01", vertical_capability="ui", @@ -3825,12 +3475,12 @@ def test_validate_receipt_contract_rejects_generic_visual_evidence(self) -> None f"{FEATURE_PATH}/quickstart.md", ] handoff["task_text"] = [ - "T010 ui_acceptance for Visual Item ID VUI-001 with Requirement Status Required and structured IR ref ir/refund.json" + "T010 ui_acceptance for UI/UX Requirement ID UI-001 with Applicability Required and Readiness Ready" ] 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"): + with self.assertRaisesRegex(ValueError, "UI/UX requirement ID"): validate_receipt_contract( handoff, minimal_receipt( @@ -3841,7 +3491,7 @@ def test_validate_receipt_contract_rejects_generic_visual_evidence(self) -> None receipt_path, ) - def test_validate_receipt_contract_accepts_visual_evidence_references(self) -> None: + def test_validate_receipt_contract_accepts_ui_ux_evidence_references(self) -> None: handoff = minimal_handoff( shard_id="S01-ui-01", vertical_capability="ui", @@ -3854,7 +3504,7 @@ def test_validate_receipt_contract_accepts_visual_evidence_references(self) -> N f"{FEATURE_PATH}/quickstart.md", ] handoff["task_text"] = [ - "T010 ui_acceptance for Visual Item ID VUI-001 with Requirement Status Required and structured IR ref ir/refund.json" + "T010 ui_acceptance for UI/UX Requirement ID UI-001 with Applicability Required and Readiness Ready" ] receipt_path = f"{HANDOFF_DIR}/results/S01-ui-01.json" handoff["task_status_update"]["receipt_path"] = receipt_path @@ -3865,7 +3515,7 @@ def test_validate_receipt_contract_accepts_visual_evidence_references(self) -> N 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 structured IR ref ir/refund.json and quickstart.md#visual-refund" + "UI/UX Requirement ID UI-001 verified against the accepted error state and quickstart.md#refund-ui" ], ), receipt_path, @@ -3989,63 +3639,28 @@ def test_readme_contract(self) -> None: self.assertIn("The preset has four goals:", readme) self.assertIn("BDD readiness gate", readme) self.assertIn("NFR readiness", readme) - self.assertIn("BDD/NFR/applicable Visual Fidelity", readme) - self.assertIn("External Intake And Visual SSOT", readme) - self.assertIn("spec-kit-intake", readme) - self.assertIn("external intake evidence + visual SSOT refs + HTML SSOT refs + structured IR refs -> /speckit.specify -> baseline spec.md", readme) - self.assertIn("does not perform intake", readme) - self.assertIn("parse HTML SSOT bundles", readme) - self.assertIn("re-parse structured IR artifacts", readme) - self.assertIn("decide provider source readiness", readme) - self.assertIn("visual SSOT refs", readme) - self.assertIn("HTML SSOT refs", readme) - self.assertIn("structured IR refs", readme) - self.assertIn("visual/IR traceability refs", readme) - self.assertIn("non-visual acceptance", readme) - self.assertIn("external evidence refs", readme) - self.assertIn("source-backed facts", readme) - self.assertIn("Missing product decisions become `[NEEDS CLARIFICATION]`", readme) - self.assertIn("missing provider or intake evidence for a feature that depends on that evidence becomes `[BLOCKED: PROVIDER_EVIDENCE]`", readme) - self.assertIn("features that do not depend on HTML SSOT, structured IR, or provider evidence are `Not Applicable`", readme) - self.assertIn("speckit.intake.visual-design", readme) - self.assertIn("speckit.intake.figma2htmlssot", readme) - self.assertNotIn("speckit.intake.html-ssot", readme) - self.assertIn("Visual Fidelity readiness gate", readme) - self.assertIn("Screenshots, visual proof refs, HTML SSOT refs, structured IR refs, and provider artifacts are evidence refs, not intake execution", readme) - self.assertNotIn("L0 No Screenshot", readme) - self.assertNotIn("L1 Key Screenshots", readme) - self.assertNotIn("L2 State + Viewport Matrix", readme) - self.assertNotIn("L3 Visual Baseline", readme) - self.assertIn("pixel-perfect", readme) - self.assertIn("They cannot upgrade product semantics", readme) - self.assertIn( - "product-side visual requirements such as pixel-perfect, brand-critical, responsive visual, or UI visual acceptance requirements", - readme, - ) - self.assertIn("Visual Fidelity Evidence Matrix", readme) - self.assertIn("one row per visual requirement", readme) - self.assertIn("single visual readiness record", readme) - self.assertIn("provider blocker status", readme) - self.assertIn("accepted exception refs", readme) - self.assertIn("It does not define visual validation work, screenshot comparison, visual diff, baseline capture, or final visual review", readme) - self.assertNotIn("proof sufficiency", readme) - self.assertNotIn("screenshot sufficiency", readme) - self.assertNotIn("visual implementation review", readme) - self.assertNotIn("visual proof evidence", readme) - self.assertNotIn("visual proof, asset binding, and evidence requirements", readme) - self.assertIn("The intake extension owns source capture", readme) - self.assertIn("HTML SSOT bundle contracts", readme) - self.assertIn("structured IR contracts", readme) - self.assertIn("source-side validators live in the `spec-kit-intake` extension", readme) - self.assertIn("[BLOCKED: PROVIDER_EVIDENCE]", readme) - self.assertNotIn( - "writes or marks it as `[NEEDS CLARIFICATION]`", - readme, - ) - self.assertIn("source-side readiness", readme) - self.assertIn("artifact refs, readiness inputs, blocker status, and traceability refs", readme) - self.assertIn("clarifies evidence-derived gaps already written in `spec.md`", readme) - self.assertIn("does not call provider tools", readme) + self.assertIn("BDD/NFR/UI/UX specification readiness", readme) + self.assertIn("Source-Agnostic UI/UX Requirements", readme) + self.assertIn("confirmed product requirements -> /speckit.specify -> UI/UX Specification in spec.md", readme) + self.assertIn("explicit product text and confirmed product decisions", readme) + self.assertIn("UI/UX Coverage Matrix", readme) + self.assertIn("Applicability (`Required | Not Applicable | Unknown`)", readme) + self.assertIn("Readiness (`Ready | Blocked`)", readme) + self.assertIn("stable `UX-###` IDs", readme) + self.assertIn("`UI-###` IDs", readme) + self.assertIn("Unresolved product decisions return to `/speckit.clarify`", readme) + for forbidden in ( + "Figma", + "provider", + "external intake", + "Visual SSOT", + "HTML SSOT", + "structured IR", + "visual proof", + "Client Asset Contract", + "[BLOCKED: PROVIDER_EVIDENCE]", + ): + self.assertNotIn(forbidden.lower(), readme.lower()) self.assertIn("explicit non-functional requirement declarations", readme) self.assertIn("Required, Not Applicable, or Unknown", readme) self.assertIn("missing or unverifiable NFR assumptions", readme) @@ -4053,17 +3668,6 @@ def test_readme_contract(self) -> None: self.assertIn("Case Coverage Matrix", readme) self.assertIn("case coverage", readme) self.assertIn("Required, Not Applicable, or Unknown", readme) - lowered = readme.lower() - for forbidden in FORBIDDEN_VISUAL_COMPAT_TERMS: - self.assertNotIn(forbidden, lowered) - self.assertNotIn( - "Responsive visual readiness must record viewport-specific evidence or set Gate Status: BLOCKED", - readme, - ) - self.assertNotIn( - "Responsive visual readiness records viewport-specific evidence or sets Gate Status: BLOCKED", - readme, - ) self.assertIn("failure scenarios", readme) self.assertIn( "error code, failure feedback, and state invariant, rollback, or compensation assertion", @@ -4206,10 +3810,15 @@ def test_cross_agent_subagent_contract_document(self) -> None: "Do not dispatch workers", "Reject non-existent handoff paths", "Reject handoffs not listed in `handoff-manifest.json`", - "validation_evidence references to relevant BDD scenario", + "validation_evidence references to a relevant BDD scenario", "behavior assertion", "API contract", - "quickstart path", + "quickstart validation path", + "`UI-###` or `UX-###` requirement ID", + "UI/UX shard candidates", + "Applicability `Required` plus Readiness `Ready` is executable", + "do not create UI/UX shards for `Not Applicable`, `Unknown`, or `Blocked`", + "route unresolved rows back to `/speckit.clarify` or `/speckit.checklist`", "receipt path not equal to handoff `task_status_update.receipt_path`", "task_type: code_review", "review_conclusion", @@ -4256,42 +3865,24 @@ def test_extension_governance_document_contract(self) -> None: "structured JSON artifacts require schemas", "validators/", "Do not put downstream prohibitions in upstream commands", - "Source intake artifacts belong in an extension, not this preset", - "External intake owns source capture", - "rendered HTML SSOT bundles", + "Source acquisition, tool-specific extraction, normalization, authentication", + "consumes explicit product text and confirmed product decisions", "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", - "external intake artifact refs", - "visual SSOT refs", - "HTML SSOT refs", - "structured IR refs", - "External evidence refs are consumed as source, readiness, blocker, and traceability inputs only", - "Visual Fidelity Evidence Matrix", - "one row per visual requirement", - "Source `spec.md` section", - "Requirement Status", - "provider-evidence dependency", - "other evidence refs", - "readiness input", - "Blocking Item ID", - "accepted exception refs", - "single visual readiness record", - "records visual planning readiness", - "traceability refs", - "provider blocker status", - "must not define visual validation work, screenshot comparison, visual diff, baseline capture, or final visual review", - "checklist Gate Status", - "checklist Blocking Items", - "Source-side intake readiness remains separate", - "Provider tools, provider execution, hooks, adapter scripts", - "External design extraction is not a clarification responsibility", + "`/speckit.checklist`: checklist artifacts and BDD/NFR/UI/UX specification readiness gates only", + "The wrapping `spec-template` owns the stable `UI/UX Specification` shape", + "`/speckit.specify` decides applicability and fills that shape", + "UI/UX requirement Applicability uses `Required`, `Not Applicable`, or `Unknown`", + "Checklist Readiness uses `Ready` or `Blocked` as a separate dimension", + "UI/UX Coverage Matrix is the only UI/UX specification-readiness matrix", "NFR readiness belongs in `spec.md` product requirements", "`/speckit.plan`: Phase 0 behavior projection, planning artifacts, and formal contracts", - "`/speckit.tasks` owns implementation, non-visual acceptance, contract validation, data-side-effect validation, integration/e2e validation, and code review task definition in `tasks.md`", + "`/speckit.tasks` owns implementation, UI/UX acceptance, 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", - "must not invent validation strategy, visual validation work, lifecycle roles, requirements, contract updates, or wider scope during execution", + "must not invent validation strategy, lifecycle roles, requirements, contract updates, or wider scope during execution", + "For UI/UX planning, `research.md` records implementation decisions", + "accepted `UI-###` and `UX-###` requirements", "Handoff extensions must update schema, validator, command, and cross-agent documentation together", "Do not bump preset version or release archive URLs until release preparation", "Use extensions, not presets, for new tooling", @@ -4310,17 +3901,18 @@ def test_extension_governance_document_contract(self) -> None: ] for term in forbidden_terms: self.assertNotIn(term, document) - lowered = document.lower() - for forbidden in FORBIDDEN_VISUAL_COMPAT_TERMS: - self.assertNotIn(forbidden, lowered) - self.assertNotIn( - "Responsive visual readiness must record viewport-specific evidence or set Gate Status: BLOCKED", - document, - ) - self.assertNotIn( - "Responsive visual readiness records viewport-specific evidence or sets Gate Status: BLOCKED", - document, - ) + for forbidden in ( + "Figma", + "provider", + "external intake", + "Visual SSOT", + "HTML SSOT", + "structured IR", + "visual proof", + "Client Asset Contract", + "[BLOCKED: PROVIDER_EVIDENCE]", + ): + self.assertNotIn(forbidden.lower(), document.lower()) def test_agents_references_extension_governance(self) -> None: agents = AGENTS_PATH.read_text(encoding="utf-8") diff --git a/presets/workflow-preset/validators/speckit_implement_contract.py b/presets/workflow-preset/validators/speckit_implement_contract.py index 691239b277..3c618404ef 100644 --- a/presets/workflow-preset/validators/speckit_implement_contract.py +++ b/presets/workflow-preset/validators/speckit_implement_contract.py @@ -300,16 +300,13 @@ def _handoff_requires_traceable_validation_evidence(handoff: dict[str, Any]) -> "BehaviorScenarioInstance", "BDD scenario", "behavior assertion", - "Visual Item ID", - "Requirement Status", - "visual_setup", - "visual_implementation", + "UI/UX Requirement ID", + "UI-", + "UX-", + "ui_setup", + "ui_implementation", + "ui_accessibility", "ui_acceptance", - "asset_binding", - "visual SSOT ref", - "HTML SSOT ref", - "structured IR ref", - "Client Asset Contract", ) values: list[str] = [] for key in ("allowed_read_paths", "allowed_write_paths", "task_text"): @@ -326,15 +323,9 @@ def _receipt_references_traceable_validation_evidence(receipt: dict[str, Any]) - "AST-", "BDD", "UIF-", - "Visual Item ID", - "Requirement Status", - "visual SSOT ref", - "visual SSOT refs", - "HTML SSOT ref", - "HTML SSOT refs", - "structured IR ref", - "structured IR refs", - "Client Asset Contract", + "UI-", + "UX-", + "UI/UX Requirement ID", "quickstart validation", "contracts/bdd/", "contracts/uif/", @@ -826,8 +817,7 @@ def validate_receipt_structure( ) and not _receipt_references_traceable_validation_evidence(receipt): raise ValueError( "receipt validation_evidence must reference relevant BDD scenario, " - "behavior assertion, API contract, UIF path, Visual Item ID, " - "visual SSOT ref, HTML SSOT ref, structured IR ref, Client Asset Contract entry, " + "behavior assertion, API contract, UIF path, UI/UX requirement ID, " "or quickstart path" )