diff --git a/presets/catalog.community.json b/presets/catalog.community.json index 6e7319d12b..d5e7e7f88b 100644 --- a/presets/catalog.community.json +++ b/presets/catalog.community.json @@ -670,22 +670,24 @@ "workflow-preset": { "name": "Workflow Preset", "id": "workflow-preset", - "version": "1.3.12", + "version": "2.0.0", "description": "Behavior-first specification, design artifacts, and agent-native handoff orchestration", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", - "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.12/spec-kit-workflow-preset-v1.3.12.zip", + "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip", "homepage": "https://github.com/bigsmartben/spec-kit-workflow-preset", "documentation": "https://github.com/bigsmartben/spec-kit-workflow-preset/blob/main/README.md", "license": "MIT", "requires": { - "speckit_version": ">=0.8.10.dev0" + "speckit_version": ">=0.12.7.dev0" }, "provides": { - "templates": 23, + "templates": 27, "commands": 8 }, "tags": [ + "architecture", + "constitution", "behavior", "bdd", "planning", diff --git a/presets/catalog.json b/presets/catalog.json index abf58ff8bb..af913f3fea 100644 --- a/presets/catalog.json +++ b/presets/catalog.json @@ -29,20 +29,22 @@ "workflow-preset": { "name": "Workflow Preset", "id": "workflow-preset", - "version": "1.3.12", + "version": "2.0.0", "description": "Behavior-first specification, design artifacts, and agent-native handoff orchestration", "author": "bigsmartben", "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset", "license": "MIT", "bundled": true, "requires": { - "speckit_version": ">=0.8.10.dev0" + "speckit_version": ">=0.12.7.dev0" }, "provides": { "commands": 8, - "templates": 23 + "templates": 27 }, "tags": [ + "architecture", + "constitution", "behavior", "bdd", "planning", diff --git a/presets/workflow-preset/AGENTS.md b/presets/workflow-preset/AGENTS.md index b1a159b9dc..eca0707260 100644 --- a/presets/workflow-preset/AGENTS.md +++ b/presets/workflow-preset/AGENTS.md @@ -21,7 +21,10 @@ This repository is a Spec Kit community preset named `workflow-preset`. - Planning design artifacts are optional and contextual: - `class-diagram.md` - `contracts/sequences.md` -- Validation strategy is derived by `/speckit.tasks` from behavior contracts, interface contracts, `research.md`, and `quickstart.md`; do not add standalone `test-plan.md` without intentionally updating the preset contract. +- Validation decisions stay in `research.md` and executable paths in + `quickstart.md`; plan closeout maps them into + `behavior/behavior-testability.md`, and `/speckit.tasks` derives concrete + tasks. Do not add standalone `test-plan.md`. - Do not move product requirements out of `spec.md`, domain model details out of `data-model.md`, interface schemas out of `contracts/`, or validation run guidance out of `quickstart.md`. ## Integration Boundary diff --git a/presets/workflow-preset/CHANGELOG.md b/presets/workflow-preset/CHANGELOG.md index 477c51faf3..bae0146c9e 100644 --- a/presets/workflow-preset/CHANGELOG.md +++ b/presets/workflow-preset/CHANGELOG.md @@ -2,14 +2,39 @@ ## 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. +## 2.0.0 - 2026-07-26 + +- Moved project Architecture generation into `/speckit.constitution`, which now + manages separate `constitution.md` and single-file `architecture.md` + lifecycles for greenfield, brownfield, and amendment runs. +- Added an explicit user-selected input agreement; UC, README, repository files, + and other conventional paths are no longer assumed prerequisites or evidence. +- Removed 4+1 reasoning from the target Architecture shape and added the + boundary -> concept -> technical evidence -> planning guardrail chain. +- Required `/speckit.plan` to project Architecture decisions, concepts, + boundaries, constraints, gaps, and validation implications into its normal + research, data model, contracts, plan, and quickstart outputs. + +## 1.4.1 - 2026-07-26 + +- Raised the minimum Spec Kit version to `0.12.7.dev0`, the first core version + that provides the requirement-gate Planning Readiness preflight consumed by + this preset. +- Restored runnable contract coverage for current wrapper, planning, template, + visual-readiness, documentation, and governance invariants. + +## 1.4.0 - 2026-07-26 + +- Separated requirement-stage Planning Readiness from plan-stage Behavior + Testability without adding commands or a `planning-readiness.md` artifact. +- Replaced the legacy combined behavior-testability checklist with + requirements, behavior, UX, security, NFR, and visual domain gates. +- Added BDD Plan closeout output at + `behavior/behavior-testability.md`; tasks now require its current READY + decision and derive fixture → validation/test → implementation → evidence + chains. +- Preserved provider-evidence blockers as intake responsibilities and made + legacy `checklists/behavior-testability.md` non-authoritative. ## 1.3.12 - 2026-07-01 diff --git a/presets/workflow-preset/README.md b/presets/workflow-preset/README.md index 9a158b1e45..46119ab46f 100644 --- a/presets/workflow-preset/README.md +++ b/presets/workflow-preset/README.md @@ -1,17 +1,28 @@ # Workflow Preset -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 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. +This Spec Kit community preset combines Constitution-managed project Architecture, behavior-first specification, design-aware planning, scoped change governance, and agent-native handoff orchestration. + +It wraps `/speckit.specify`, `/speckit.checklist`, `/speckit.clarify`, +`/speckit.constitution`, `/speckit.plan`, `/speckit.tasks`, and +`/speckit.analyze` with multi-domain requirement gates, Change Scope +Granularity, a single-file project Architecture lifecycle, Architecture-guided +planning, Phase 0 behavior projection, formal behavior contracts, plan-stage +Behavior Testability, optional design artifacts, and task-time validation +derivation. It replaces +`/speckit.implement` with a Core Agent, Vertical Planner Agent, and Worker Agent +orchestration contract that writes handoffs to disk. ## Goal `workflow-preset` turns a Spec Kit feature from a single broad implementation prompt into a staged workflow with stable design context and explicit worker boundaries. -The preset has four goals: +The preset has six goals: -- 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. +- Make requirements, behavior, UX, security, NFR, and visual readiness explicit + before planning without creating a Planning Readiness summary file. - Project accepted requirements into BDD, UIF intent, and fixture intent drafts during `/speckit.plan` Phase 0. +- Close planning with `behavior/behavior-testability.md`, which maps Required + Cases and formal planning decisions into Task Readiness. - 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. - Execute implementation through agent-native handoff orchestration so each worker receives explicit task IDs, lifecycle stage, vertical capability, context, read/write paths, validation commands, and receipt requirements. @@ -22,7 +33,8 @@ 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/UI/UX specification readiness checklist. +- Requirement enhancement keeps product requirements in `spec.md` and gates + planning with metadata-bearing domain checklists. - 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. @@ -34,34 +46,45 @@ The intent is not to add ceremony to simple features. The intent is to preserve 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. -- 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. +- Wraps `/speckit.clarify` so it resolves product-decision blockers in + `spec.md`, recomputes affected gates, and leaves provider evidence with + intake. +- 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 generate `requirements.md`, `behavior.md`, + `ux.md`, `security.md`, `nfr.md`, and `visual.md` requirement gates. - 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. -- 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. +- 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. - 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`. Governance capabilities: -- Wraps `/speckit.constitution` and the constitution template with Change Scope Granularity and Architecture SSOT governance. +- Wraps `/speckit.constitution` so one Constitution-stage lifecycle maintains separate `.specify/memory/constitution.md` and `.specify/memory/architecture.md` files. +- Establishes a user-confirmed input agreement for greenfield, brownfield, and amendment runs; no UC, README, or repository path is an automatic prerequisite or authority. +- Produces one five-section project Architecture through System Boundary -> Conceptual Model -> Technical Decisions & Evidence -> Planning Guardrails & Gaps reasoning, with no 4+1 views or secondary models. - Defines the fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail. These letters must not be renamed or expanded with alternate nouns. - Blocks constitution writes when a generated draft changes the fixed R/M/U/O mapping. -- Routes architecture decisions, domain facts, object design, flows, and interface contracts to architecture SSOT artifacts instead of embedding concrete implementation content in ratified constitution principles. +- Keeps durable governance in `constitution.md` and project-level boundaries, concepts, technical direction, evidence, constraints, and gaps in `architecture.md`. - Requires planning to lock M + U before execution maps units to concrete paths. - Treats unresolved U -> path mapping as a context gap instead of widening execution to repository-wide or broad module scope. 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 UI/UX specification readiness gates to pass before planning. +- Requires `/speckit.plan` to read project Architecture before writing and to preserve its decisions in `research.md`, concepts in `data-model.md`, boundaries in `contracts/`, and constraints or gaps in `plan.md` and `quickstart.md`. +- Stops planning and returns to `/speckit.constitution` when a feature conflicts with or requires changing project Architecture. +- Requires the runtime Planning Readiness aggregate to pass before planning; + no `planning-readiness.md` is generated. - 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 UI/UX specification readiness gates have passed. +- Consumes Phase 0 behavior drafts and must formalize them into + `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` after the + multi-domain Planning Readiness aggregate passes. - 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. @@ -69,19 +92,23 @@ 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 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. +- Generates `behavior/behavior-testability.md` at BDD Plan closeout with a Task + Derivation Matrix and READY/BLOCKED status. +- 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. - 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: -- Wraps `/speckit.tasks` so task generation can consume the design artifacts. +- Wraps `/speckit.tasks` so task generation requires READY + `behavior/behavior-testability.md` and consumes its Case mappings. - 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 UI setup, implementation, accessibility, and acceptance tasks from Required and Ready `UI-###` / `UX-###` requirements. -- Preserves UI/UX requirement IDs through implementation and acceptance tasks. +- 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. - Uses design artifacts to derive implementation, integration, orchestration, failure-handling, and validation tasks. -- Adds Final Code Review tasks for boundary, interface contract, UI/UX, data side-effect, behavior contract, and sequence consistency scopes when applicable. +- Adds Final Code Review tasks for boundary, interface contract, visual, data side-effect, behavior contract, sequence consistency, and asset binding scopes when applicable. - Preserves the existing checklist format and user-story organization. Analysis capabilities: @@ -103,8 +130,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 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. +- 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. - 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`. @@ -122,19 +149,21 @@ Context-load controls: ## Workflow -1. `/speckit.constitution` preserves Change Scope Granularity and Architecture SSOT governance when the project constitution is created or updated. +1. `/speckit.constitution` confirms greenfield, brownfield, or amendment inputs, then maintains separate Constitution and project Architecture files. 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 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, UI/UX requirement IDs, acceptance criteria, and evidence requirements. +4. `/speckit.checklist` evaluates requirements, behavior, UX, security, NFR, + and visual readiness directly from `spec.md`; `/speckit.clarify` repairs + product-decision blockers and re-evaluates affected gates. +5. `/speckit.plan` reads project Architecture, 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. 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, UI/UX consistency, sequence, implementation data side effects, and real e2e readiness. +13. Final Code Review checks boundary, contract, visual, asset binding, 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 @@ -143,6 +172,8 @@ Context-load controls: - It does not move product requirements out of `spec.md`. - It does not move API or message schemas out of `contracts/`. - It does not replace `data-model.md`, `research.md`, or `quickstart.md`. +- It does not generate 4+1, UML, C4, PoC code, or Architecture-consumption audit artifacts. +- It does not treat `uc.md` or any discovered conventional path as an automatic Constitution-stage input. - It does not infer UIF from built code; UIF remains a requirement and planning contract. - It does not provide a Python orchestration script, workflow shell runner, or integration adapter layer. - It does not allow Worker Agents to freely expand context by reading full planning documents when the digest is insufficient. @@ -152,7 +183,7 @@ Context-load controls: Release install: ```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.12/spec-kit-workflow-preset-v1.3.12.zip +specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip ``` Local development install: @@ -175,15 +206,50 @@ Run the behavior-first workflow: /speckit.analyze ``` -### Source-Agnostic UI/UX Requirements +At `/speckit.constitution`, identify the mode and selected inputs. For example: + +```text +/speckit.constitution Brownfield amendment. Use the existing constitution, +docs/platform-boundaries.md, and repository configuration under services/api/ +as authorized evidence. Exclude Git history. Update both Constitution and Architecture. +``` + +### External Intake And Visual SSOT -`workflow-preset` accepts explicit product text and confirmed product decisions without depending on how those requirements were collected. +Source capture and provider-specific intake are owned by the separate `spec-kit-intake` +extension. Install or run that extension when PRD, design, provider design, rendered HTML, +or test-case evidence must be captured or validated before this preset projects +requirements. ```text -confirmed product requirements -> /speckit.specify -> UI/UX Specification in spec.md +external intake evidence + visual SSOT refs + HTML SSOT refs + structured IR refs -> /speckit.specify -> baseline 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`. +`/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`. Then run agent-native orchestrated implementation: @@ -202,6 +268,7 @@ Run a single worker handoff directly: The core governance and planning workflow still owns its normal artifacts: - `.specify/memory/constitution.md` +- `.specify/memory/architecture.md` - `specs//plan.md` - `specs//research.md` - `specs//data-model.md` @@ -209,9 +276,20 @@ The core governance and planning workflow still owns its normal artifacts: - `specs//quickstart.md` - `specs//tasks.md` -This preset adds checklist artifacts: +This preset adds requirement-stage checklist artifacts: + +- `specs//checklists/behavior.md` +- `specs//checklists/ux.md` +- `specs//checklists/security.md` +- `specs//checklists/nfr.md` +- `specs//checklists/visual.md` -- `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: @@ -226,6 +304,10 @@ This preset adds planning-phase formal behavior contracts: - `specs//contracts/uif/` - `specs//contracts/behavior/` +This preset adds the plan-stage task-readiness artifact: + +- `specs//behavior/behavior-testability.md` + This preset adds optional/contextual planning artifacts: - `specs//class-diagram.md` @@ -256,29 +338,43 @@ Contract files packaged by the preset: Governance templates packaged by the preset: - `templates/constitution-template.md` -- `templates/spec-template.md` +- `templates/architecture-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 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. +`.specify/memory/architecture.md` is the project-level Architecture source for planning. It contains exactly Architecture Overview, System Boundary, Conceptual Model, Technical Decisions & Evidence, and Planning Guardrails & Gaps. Optional tables may be empty; an explicit Architecture goal, authorized source list, and owned boundary are required. For example, a payment boundary may own payment authorization but explicitly not own order fulfillment; feature `contracts/` must preserve that responsibility and dependency direction. + +`checklists/behavior.md` owns observable behavior and the Case Coverage Matrix; +`checklists/nfr.md` owns product-level non-functional readiness; and +`checklists/visual.md` owns the single Visual Fidelity Evidence Matrix. +Together with requirements, UX, and security gates they produce the runtime +Planning Readiness aggregate. Missing product decisions return to clarify; +provider evidence remains an intake blocker. `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. `contracts/bdd/`, `contracts/uif/`, and `contracts/behavior/` contain planning-phase formal behavior contracts. They are generated from Phase 0 drafts after planning has resolved fixture strategy, data model, interface contracts, and validation paths, unless planning records `N/A or blocker` for missing planning input. `contracts/behavior/scenario-instances.json` carries `case_coverage_blockers` for Required cases that cannot be formalized. Failure scenarios must be structured enough to constrain implementation, including error code, failure feedback, and state invariant, rollback, or compensation assertion references. +`behavior/behavior-testability.md` is generated at plan closeout. It maps every +Required Case to its Scenario, BDD/UIF contract, fixture, assertion, validation +level, research decision, quickstart path, and visual/NFR refs. `/speckit.tasks` +stops unless this artifact is current and READY. + `class-diagram.md` captures internal implementation object structure: classes, interfaces, abstract types, composition, dependencies, references, and design pattern participants. It is the object design map that helps implementation preserve boundaries between services, adapters, repositories, strategies, factories, controllers, coordinators, and extension points. `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 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. +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. 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, 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. +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. 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. @@ -345,7 +441,7 @@ Completed `[x]` tasks are not scheduled into new implementation handoffs. Runtime requirements: -- Spec Kit CLI `>=0.8.10.dev0` +- Spec Kit CLI `>=0.12.7.dev0` - An agent environment capable of running `/speckit.implement` in Core Agent, Vertical Planner Agent, and Worker Agent modes Development and release tooling: @@ -377,7 +473,7 @@ This repository owns preset artifact health: - publish or confirm the release artifact for a tag or manual release run; - create or update a `workflow-preset-release-v` integration PR in `bigsmartben/spec-kit` on tag releases or manual runs with `create_integration_pr=true`. -Manual release runs default to the next patch version when `version` is omitted. For example, a `preset.yml` version of `1.3.12` defaults to release version `1.3.13`. +Manual release runs default to the next patch version when `version` is omitted. For example, a `preset.yml` version of `2.0.0` defaults to release version `2.0.1`. The integration PR step requires a repository secret named `SPEC_KIT_FORK_PR_TOKEN` with permission to push branches and open pull requests in `bigsmartben/spec-kit`. If a tag release or manual `create_integration_pr=true` run reaches that step without the secret, the workflow fails fast instead of skipping integration PR creation. @@ -396,7 +492,7 @@ Release install smoke validation is intentionally owned by GitHub Actions, not b After tagging a release, validate archive installation: ```bash -specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.12/spec-kit-workflow-preset-v1.3.12.zip +specify preset add workflow-preset --from https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v2.0.0/spec-kit-workflow-preset-v2.0.0.zip ``` ## Source Rationale diff --git a/presets/workflow-preset/commands/speckit.analyze.md b/presets/workflow-preset/commands/speckit.analyze.md index f7ffae53be..9ea345bdc0 100644 --- a/presets/workflow-preset/commands/speckit.analyze.md +++ b/presets/workflow-preset/commands/speckit.analyze.md @@ -11,7 +11,10 @@ Check that tasks preserve the planned `M + U` scope. Report missing, widened, or Follow cross-agent protocol profile: `speckit.analyze.read_only_parallel_review`. -Analyze whether the feature artifacts close the `spec -> BDD/UIF intent -> contracts -> tasks` loop. This command checks planning consistency only; it does not inspect implementation code or infer interaction flows from built code. +Analyze whether the feature artifacts close the +`requirement gates -> BDD/UIF intent -> contracts -> behavior testability -> tasks` +loop. This command checks planning consistency only; it does not inspect +implementation code or infer interaction flows from built code. ## Analysis Performance Guardrails @@ -35,8 +38,16 @@ Check: - UIF API calls exist in contracts/api/. - behavior contracts cover scenarios, fixtures, and assertions. - tasks.md covers BDD, UIF, API, fixtures, and quickstart validation paths. -- case coverage is closed from checklist through implementation tasks. -- Required case types in `checklists/behavior-testability.md` map to behavior draft scenarios, formal behavior contracts, tasks, and quickstart validation paths. +- case coverage is closed from `checklists/behavior.md` through behavior drafts, + formal contracts, `behavior/behavior-testability.md`, and implementation + tasks. +- Required case types in `checklists/behavior.md` map to behavior draft + scenarios, formal behavior contracts, Task Derivation Matrix rows, tasks, + and quickstart validation paths. +- `behavior/behavior-testability.md` carries current spec/plan revisions and is + READY before tasks are considered complete. +- every Required Case maps to a fixture → validation/test → implementation → + evidence task chain. - positive, negative, boundary, permission, validation, and state_conflict case types are either covered or have `N/A or blocker` evidence. - failure scenarios declare error code, failure feedback, and state invariant, rollback, or compensation assertion. - quickstart validation paths cover Required failure scenarios. diff --git a/presets/workflow-preset/commands/speckit.checklist.md b/presets/workflow-preset/commands/speckit.checklist.md index eee3e26728..1809db2b6a 100644 --- a/presets/workflow-preset/commands/speckit.checklist.md +++ b/presets/workflow-preset/commands/speckit.checklist.md @@ -1,40 +1,104 @@ --- -description: Wrap core checklist generation with BDD, NFR, and UI/UX specification readiness gates. +description: Wrap core checklist generation with multi-domain requirement gates. strategy: wrap --- -## Checklist Purpose: "Unit Tests for English" - -This wrapper must not redefine core-owned User Input, Pre-Execution Checks, extension hooks, base path resolution, or core file handling. - -Checklists validate whether requirements are complete, clear, consistent, measurable, and ready for downstream planning. NOT for verification/testing: do not test implementation behavior, code execution, UI rendering, API responses, or whether the built system works. - -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 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. 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. - -## Readiness Gate Behavior - -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. - -Evaluate: - -- 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. - -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. - -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. - -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`. +## Multi-Domain Requirement Gate + +This wrapper extends the core spec-only checklist contract. It must not read +`plan.md` or `tasks.md`, create planning artifacts, redefine extension hooks, +or introduce a new command. + +Use `$ARGUMENTS` only to prioritize requirement-quality focus. The standard +domain evaluation is always: + +| Domain | Output | Template | +|---|---|---| +| requirements | `checklists/requirements.md` | core baseline | +| behavior | `checklists/behavior.md` | `requirement-behavior-gate-template` | +| UX | `checklists/ux.md` | `requirement-domain-gate-template` | +| security | `checklists/security.md` | `requirement-domain-gate-template` | +| NFR | `checklists/nfr.md` | `requirement-nfr-gate-template` | +| visual | `checklists/visual.md` | `requirement-visual-gate-template` | + +Every standard domain must be written as `APPLICABLE` or +`NOT_APPLICABLE` with a concrete reason. Every file uses the core +`Stage/Domain/Gate/Applicability/Status/Spec Revision` metadata contract. +Planning Readiness is aggregated in memory; do not create +`planning-readiness.md`. + +The legacy `checklists/behavior-testability.md` is not an input or output of +this command. Preserve an existing legacy file for migration history but never +update it or treat it as a current Gate. + +## Behavior Requirement Gate + +Write behavior requirement quality and the Case Coverage Matrix to +`checklists/behavior.md`. + +- Evaluate user-story readiness, observable acceptance behavior, and Given, + When, and Then requirement readiness. +- Use one row per story/capability and case type. +- Cover positive, negative, boundary, permission, validation, and + state_conflict. +- Use stable Case IDs. +- Status is `Required|Not Applicable|Unknown`. +- Required rows cite a `spec.md` section. +- Not Applicable requires rationale. +- Unknown becomes `[blocker:product-decision]` and blocks PASS. +- Scenario IDs and `case_coverage_blockers` remain `/speckit.plan` outputs. + +This gate checks whether behavior requirements are projectable. It does not +decide test level, fixtures, assertions, contracts, or Task Readiness. + +## NFR Requirement Gate + +Write NFR readiness to `checklists/nfr.md`. Evaluate performance, security and +privacy, reliability and recovery, accessibility, compliance and auditability, +observability, compatibility, data lifecycle, and cost or operational +constraints. + +Each dimension is `Required`, `Not Applicable`, or `Unknown`. Required items +need verifiable product-level criteria. Not Applicable needs a rationale. +Unknown items affecting planning are product-decision blockers. Do not require +technical designs or invent architecture. + +## Visual Requirement Gate + +Write visual readiness and the only Visual Fidelity Evidence Matrix to +`checklists/visual.md`. + +Apply the gate when `spec.md` contains a Visual & UI Specification, visual +requirements, visual/HTML/structured-IR SSOT refs, external intake refs, +provider blockers, pixel-perfect/brand-critical requirements, responsive +visual requirements, or UI visual acceptance requirements. + +Every visual item is `Required`, `Not Applicable`, `Unknown`, or +`[BLOCKED: PROVIDER_EVIDENCE]`. + +- Unknown product semantics become `[blocker:product-decision]`. +- Missing provider proof remains `[blocker:provider-evidence] [return:intake]`. +- Provider blockers must not be converted into clarify questions. +- Required items need source traceability and observable requirement text. +- The matrix records source refs, provider dependency, visual SSOT refs, HTML + SSOT refs, structured IR refs, other evidence refs, readiness input, + accepted exceptions, and blocker IDs. +- Responsive visual requirements block PASS only when required source-backed + state or viewport evidence is missing for a feature that depends on provider + evidence. + +Do not call provider tools, rebuild intake evidence, parse provider or HTML +artifacts, define screenshot comparison, visual diff, baseline capture, or +final visual review. + +## Recompute and Reporting + +Recompute generated sections using stable CHK/CASE/NFR/VIS IDs. Never append +duplicate status blocks, stale blockers, or repeated matrix rows. Preserve +unrelated manual notes. + +Report per-domain applicability/status, current spec revision, the in-memory +Planning Readiness aggregate, product-decision blockers, and provider-evidence +blockers separately. {CORE_TEMPLATE} - -## Behavior Checklist Reporting - -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 f250a0cf62..880f7a16da 100644 --- a/presets/workflow-preset/commands/speckit.clarify.md +++ b/presets/workflow-preset/commands/speckit.clarify.md @@ -1,5 +1,5 @@ --- -description: Wrap core clarification with spec-only ambiguity resolution. +description: Wrap core clarification with product-decision gate repair. strategy: wrap --- @@ -7,9 +7,16 @@ 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, UI/UX applicability, acceptance criteria, user roles, permissions, entity states, data semantics, exceptions, validation rules, or boundaries. +Use `spec.md` as the clarification source. Ask and record clarification only for requirement ambiguity that affects product behavior, constraints, non-functional requirement assumptions, visual/UI requirement coverage status, acceptance criteria, user roles, permissions, entity states, data semantics, exceptions, validation rules, or boundaries. -Do not read or update behavior draft artifacts. Product requirements stay in `spec.md`; update `spec.md` only after user-provided answers make the requirement clear. +Also read unchecked blockers from all metadata-bearing +`checklists/*.md` files with `Stage: requirements`, +`Gate: planning-readiness`, and `Status: BLOCKED`. +Prioritize `[blocker:product-decision]` items as the repair queue. Never ask a +question for `[blocker:provider-evidence]`; preserve its `[return:intake]` +route and keep Planning Readiness BLOCKED. + +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. ## Wrapper Input Additions @@ -21,46 +28,57 @@ Load the active `spec.md` through the core command. Official hooks still apply: ## Wrapper Outline Additions -### UI/UX Requirement Clarification Strategy +## Design Requirement Clarification Strategy -Scan `spec.md` first for `[NEEDS CLARIFICATION]`, UI/UX Applicability `Unknown`, and incomplete `UI-###` or `UX-###` requirements. +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. -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. +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. -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. +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. -Prioritize questions in this order: +Format recommendations as `**Recommended:** Option [X] - ` when a discrete 2-5 option choice is available. Keep the rationale short and decision-focused. For short-answer gaps, use `Suggested` and constrain answers to `<=5 words`. Accept `yes`, `recommended`, or `suggested` as approval of the shown recommendation. Question selection order: -1. 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. +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. -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. +After each accepted answer, write confirmed answers back into `spec.md` in the relevant Requirements, User Scenarios, Acceptance Criteria, Assumptions, Open Questions, or Visual & UI Specification, visual/responsive/state sections. Update affected visual/UI coverage status when the answer resolves an `Unknown` item. Ensure `## Clarifications`, `### Session YYYY-MM-DD`, and one `- Q: ... -> A: ...` bullet exist for the session. Save `spec.md` after each accepted answer. Do not create a separate provider-specific clarification document. -Do not generate checklist artifacts. `/speckit.checklist` remains responsible for checking requirement text quality and readiness. +Do not generate visual restoration checklists. Clarification fills requirement gaps in `spec.md`; `/speckit.checklist` remains responsible for checking requirement text quality and readiness. ## Validation after each write -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. +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. + +After each `spec.md` write, recompute affected requirement gates by stable +CHK/CASE/NFR/VIS IDs. Verify unaffected gate sources before stamping every gate +with the new spec SHA-256 revision. Replace generated status and blocker +sections; do not append duplicate IDs or stale blockers. Aggregate Planning +Readiness in memory and never create `planning-readiness.md`. -Do not update checklist artifacts. Report checklist impact as unresolved readiness context for `/speckit.checklist`. +Do not read or update the legacy `checklists/behavior-testability.md`. {CORE_TEMPLATE} ## Completion Report -Before finishing, report answered questions, `spec.md` sections updated, and any unresolved requirement ambiguity that still blocks checklist readiness. +Before finishing, report answered questions, `spec.md` sections updated, +recomputed gate files, aggregate Planning Readiness, and unresolved +product-decision versus provider-evidence blockers separately. ## Done When - [ ] No more than 5 high-impact questions were asked. - [ ] Each accepted answer was written back to `spec.md`. -- [ ] Any answered UI/UX applicability decision was updated in `spec.md`. +- [ ] Any answered visual/UI coverage status was updated in `spec.md`. - [ ] Validation after each write found no duplicate or contradictory clarification. -- [ ] Completion reported sections touched and remaining blockers. +- [ ] Affected requirement gates were recomputed using stable IDs and current spec revision. +- [ ] Provider-evidence blockers were preserved and routed to intake. +- [ ] No Planning Readiness summary artifact was created. +- [ ] Completion reported with sections touched and remaining blockers. diff --git a/presets/workflow-preset/commands/speckit.constitution.md b/presets/workflow-preset/commands/speckit.constitution.md index 7b25721ed7..af84a2f235 100644 --- a/presets/workflow-preset/commands/speckit.constitution.md +++ b/presets/workflow-preset/commands/speckit.constitution.md @@ -1,8 +1,33 @@ --- -description: Wrap core constitution updates with change scope granularity and architecture SSOT governance. +description: Wrap core constitution updates with change scope granularity and Constitution-managed architecture governance. strategy: wrap --- +## Constitution Stage Input Agreement + +Before writing either project-memory artifact, establish an explicit input agreement with the user: + +- project mode: `greenfield`, `brownfield`, or `amendment`; +- the goal of this Constitution-stage run; +- which user-selected sources are authoritative and the role of each source; +- which candidate sources are excluded; +- whether repository inspection is authorized and its exact scope; +- whether this run may update Constitution, Architecture, or both. + +Conversation input, UC/PRD/product documents, an existing Constitution or Architecture, repository evidence, and external constraints are all possible sources. No conventional path is mandatory. In particular, `uc.md`, `inception/product/uc.md`, `.specify/memory/uc.md`, README files, source code, tests, configuration, and directory names are candidate sources only until the user authorizes their role. + +If the agreement is absent, ambiguous, or insufficient for the requested update, stop and confirm it with the user before writing. Do not silently discover an input and promote it to authority. + +## Project Mode + +Apply the source rules for the agreed mode: + +- `greenfield`: derive prospective governance and Architecture from confirmed intent and selected project/product sources. Do not infer target Architecture from scaffolding. +- `brownfield`: inspect only the authorized repository scope. Keep observed current state, approved governance, target Architecture, and migration or unresolved gaps distinct. Existing code is evidence, not automatically a ratified principle or target decision. +- `amendment`: update the existing Constitution and/or Architecture baseline within the agreed scope. Preserve unaffected content and record the reason for each material Architecture change. + +If an existing `.specify/memory/architecture.md` uses the retired 4+1 or nine-section planning-contract format, report `ARCH_LEGACY_FORMAT`. Rewrite it only when the input agreement authorizes an Architecture update; never silently migrate it. + ## Change Scope Granularity Always preserve the Change Scope Granularity principle in `.specify/memory/constitution.md`. @@ -23,32 +48,77 @@ If a drafted constitution changes this mapping, discard the draft and report blo When producing the Sync Impact Report, report template or command file status only after checking the actual path. If a path cannot be checked, report `CONSTITUTION_TEMPLATE_STATUS_UNCHECKED`; do not report it as missing. If the root `.specify/templates/constitution-template.md` is still the core placeholder, do not treat that as the workflow-preset template being absent. Resolve or check `.specify/presets/workflow-preset/templates/constitution-template.md` before reporting preset template status. -## Architecture SSOT Boundary +## Separate Artifact Ownership + +The Constitution stage manages two independent project-memory files: + +```text +.specify/memory/constitution.md +.specify/memory/architecture.md +``` -Ratified constitution principles must be durable governance rules, not architecture fact storage. -Architecture decisions, domain facts, object design, flows, and interface contracts belong in their architecture SSOT artifacts: +- `constitution.md` stores durable governance principles. +- `architecture.md` stores project-level boundaries, concepts, technical direction, constraints, evidence, revisit conditions, and unresolved gaps. +- Architecture facts must not be embedded in ratified Constitution principles. +- Feature-local `research.md`, `data-model.md`, `contracts/`, `plan.md`, and `quickstart.md` consume and refine the project Architecture for one feature; they do not replace it. -- `specs//data-model.md`: domain model and domain facts. -- `specs//class-diagram.md`: object, module, adapter, and internal design structure. -- `specs//contracts/sequences.md`: cross-boundary flow, sequencing, async, retry, rollback, and failure paths. -- `specs//contracts/`: interface and message contracts. -- `specs//research.md`: architecture decisions and tradeoffs that need evidence. +## Architecture Lifecycle -Constitution updates MUST NOT capture, discover, extract, migrate, store, validate, or repair architecture facts. -If user input includes architecture facts, do not embed them in ratified principles. -In the Sync Impact Report, report blocker code `CONSTITUTION_ARCH_SSOT_GAP` and name the responsible workflow-preset SSOT artifact type when it can be classified. -Do not write concrete `specs//...` paths, check those paths, create or update those artifacts, or copy concrete implementation facts, temporary repository observations, or module responsibility inventories into ratified constitution principles. +When the input agreement authorizes an Architecture update, load the workflow-preset `architecture-template.md` and write exactly one Architecture artifact: `.specify/memory/architecture.md`. -## Architecture SSOT Compliance +Use one sequential reasoning chain, without 4+1: -Always preserve the Architecture SSOT Compliance principle in `.specify/memory/constitution.md`. +```text +System Boundary + -> Conceptual Model + -> Technical Decisions & Evidence + -> Planning Guardrails & Gaps +``` -Ratified constitution principles define the compliance rule only. Concrete architecture decisions, domain facts, object design, flows, and interface contracts MUST remain in their Architecture SSOT artifacts. +Render exactly these five top-level sections: -Planning outputs MUST comply with existing Architecture SSOT artifacts. Planning MUST NOT contradict, relocate, weaken, or silently replace architecture SSOT content. If planning cannot produce outputs that comply with existing Architecture SSOT artifacts, it must report a planning blocker instead of generating inconsistent artifacts. +1. `Architecture Overview` +2. `System Boundary` +3. `Conceptual Model` +4. `Technical Decisions & Evidence` +5. `Planning Guardrails & Gaps` + +Technical validation is evidence registration only. Record a candidate, conclusion, available evidence, and an explicit evidence gap or revisit condition when validation is still required. Do not create PoC code, application source, tests, migrations, build changes, deployment changes, secondary Architecture models, view files, or receipts. + +An Architecture update is ready only when it: + +- states the Architecture goal, authorized sources, and at least one explicit boundary with ownership and non-responsibility; +- defines applicable core concepts with stable meaning, ownership, relationships, lifecycle, and invariants; +- records established technical decisions with scope, consequence, evidence, and revisit conditions; +- gives every item marked `MUST_VALIDATE` a conclusion plus evidence or an explicit validation gap; +- states applicable planning constraints and unresolved gaps without requiring downstream inference; +- contains no invented product requirement, implementation plan, task breakdown, or unresolved ambiguity presented as fact. + +Optional tables may be empty when they are genuinely not applicable. Do not manufacture extension points, decisions, or open questions to fill the template. + +When the agreement excludes an Architecture update, do not modify `architecture.md`. Report whether the existing file is missing, legacy, ready, or blocked so the user understands whether `/speckit.plan` can proceed. + +## Architecture-Guided Planning + +Always preserve the Architecture-Guided Planning principle in `.specify/memory/constitution.md`. + +`/speckit.plan` MUST read `.specify/memory/architecture.md` before producing planning artifacts. + +- `research.md` MUST follow established technical decisions and evidence, unless an Architecture revisit condition is met. +- `data-model.md` MUST preserve defined concepts, ownership, relationships, lifecycle, and invariants. +- `contracts/` MUST preserve system boundaries, responsibilities, interface ownership, and dependency direction. +- `plan.md` and `quickstart.md` MUST carry forward applicable Architecture constraints, gaps, and validation implications. + +If any planning artifact conflicts with or requires changing the Architecture, planning MUST stop and return to the Constitution stage. {CORE_TEMPLATE} -## Change Scope Granularity Reporting +## Constitution Stage Reporting + +Before finishing, report: -Before finishing, report whether the constitution includes the Change Scope Granularity principle, still states `Planning locks M + U`, preserves the exact R/M/U/O letter mapping, routes architecture decisions, domain facts, object design, flows, and interface contracts to workflow-preset SSOT artifact types instead of embedding concrete implementation content in ratified principles, and requires planning outputs to comply with existing Architecture SSOT artifacts. +- the agreed project mode, goal, authorized and excluded sources, repository-inspection scope, and update scope; +- whether `constitution.md` preserves Change Scope Granularity, `Planning locks M + U`, and preserves the exact R/M/U/O letter mapping; +- whether Constitution facts and Architecture facts remain in their separate files; +- whether `architecture.md` was created, updated, preserved, missing, legacy, ready, or blocked; +- unresolved governance or Architecture gaps without presenting them as ratified facts. diff --git a/presets/workflow-preset/commands/speckit.implement.md b/presets/workflow-preset/commands/speckit.implement.md index 8a9faed240..9bf1260af9 100644 --- a/presets/workflow-preset/commands/speckit.implement.md +++ b/presets/workflow-preset/commands/speckit.implement.md @@ -20,19 +20,22 @@ 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. -## 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, +## Visual Implementation Boundary +- In `checklists/visual.md`: + 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, or edit upstream artifacts for execution. -- UI/UX worker receipts must reference the relevant `UI-###` or `UX-###` requirement ID and validation evidence. +- Visual worker receipts must reference the relevant Visual Item ID, `Requirement Status`, and evidence refs. ## Vertical Planner Agent - Read only `tasks.md`, `context-index.json`, and allowed planning artifacts. - Preserve order, dependencies, capability boundaries, and Change Scope Granularity. -- Put unresolved shard, context, path, UI/UX status, evidence, or fallback gaps into `context_gaps`. +- Put unresolved shard, context, asset, path, visual 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. @@ -42,11 +45,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 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. +- For visual/UI handoffs, validate task text and preserve visual/IR traceability refs. +- Use empty `completed_task_ids` when required provider evidence is unavailable. - Do not edit `tasks.md`. ## Contract References -- Runtime, shard, digest, path, dispatch, Worker Prompt, and receipt rules are source-owned here. +- Runtime, shard, digest, path, asset binding, 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`. @@ -54,7 +57,7 @@ description: Run implement orchestration. `validate_handoff_structure()`, `validate_dispatch_ready()`, `validate_receipt_structure()`, `validate_commit_ready()`. ## Runtime Stops -- Stop on missing handoff files, unlisted handoffs, non-empty `context_gaps`, schema mismatch, - current-role writes outside `allowed_write_paths`, or planning artifact updates. +- Stop on missing/unlisted handoffs, non-empty `context_gaps`, schema mismatch, + writes outside `allowed_write_paths`, or planning artifact updates. - Stop instead of inventing validation strategy, roles, requirements, contract updates, wider scope, or validation planning artifacts. diff --git a/presets/workflow-preset/commands/speckit.plan.md b/presets/workflow-preset/commands/speckit.plan.md index 076ebc6ab9..42fa396f3d 100644 --- a/presets/workflow-preset/commands/speckit.plan.md +++ b/presets/workflow-preset/commands/speckit.plan.md @@ -1,5 +1,5 @@ --- -description: Wrap the core planning workflow with Phase 0 behavior projection and optional design artifacts. +description: Wrap core planning with project Architecture consumption, Phase 0 behavior projection, formal contracts, and BDD Plan closeout. strategy: wrap --- @@ -9,13 +9,38 @@ Apply the constitution's Change Scope Granularity principle. During planning, lock the change scope to `M + U`: module/capability plus design object. Do not lock operation-level implementation details or concrete write paths. +## Architecture-Guided Planning + +Before Phase 0 preflight or any planning write, read: + +```text +.specify/memory/constitution.md +.specify/memory/architecture.md +``` + +If `architecture.md` is missing, uses the retired 4+1 or nine-section planning-contract format, lacks an Architecture goal or authorized sources, or has no explicit system boundary with ownership and non-responsibility, stop with a report-only/no-write failure and return to `/speckit.constitution`. + +Consume applicable Architecture content through the normal planning artifacts: + +- `research.md` MUST follow established technical decisions and evidence. If a documented revisit condition is met, record the evidence that triggered it; do not silently replace the Architecture decision. +- `data-model.md` MUST preserve defined concepts, ownership, relationships, lifecycle, and invariants. +- `contracts/` MUST preserve system boundaries, responsibilities, interface ownership, and dependency direction. +- `plan.md` and `quickstart.md` MUST carry forward applicable Architecture constraints, unresolved gaps, revisit conditions, and validation implications. + +An Architecture gap may shape or block planning, but must not be converted into an invented decision. If any planning artifact conflicts with or requires changing `.specify/memory/architecture.md`, stop planning and return to the Constitution stage. Do not repair or rewrite project Architecture from `/speckit.plan`. + +Planning artifacts demonstrate Architecture consumption in their normal content. Do not create a compliance matrix, consumption report, audit receipt, or separate traceability artifact. + ## Plan Agent Topology 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. +Plan Core Agent owns requirement-gate consumption, stage-local delegation, +conflict resolution, BDD Plan closeout, 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 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. +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. ## Design Artifact Policy @@ -32,15 +57,27 @@ Keep `plan.md` as summary/navigation. It must link generated design artifacts an Store service sequences only at `contracts/sequences.md`, even when there are no other contract files. Do not create a root-level `sequences.md`. -Validation strategy is not a standalone planning artifact. Planning-time validation decisions belong in `research.md`; executable validation paths belong in `quickstart.md`; concrete test and verification tasks belong in `tasks.md` through the tasks command. +Validation strategy is not a standalone planning document. Planning-time +validation decisions belong in `research.md`; executable validation paths belong in `quickstart.md`; BDD Plan closeout maps those decisions into +`behavior/behavior-testability.md`; concrete tasks belong in `tasks.md`. -## Phase 0 Preflight +## Phase 0 Gate Consumption -Before core research or design work, verify checklists/behavior-testability.md has passed: it must have `Gate Status: PASS` and `Blocking Items: none` or a `Blocking Items` section containing only `- none`. +Use the core plan command's read-only Planning Readiness preflight before any +planning write. This wrapper consumes: -If the checklist is missing, incomplete, has `Gate Status: BLOCKED`, or lists blocking items, stop with a report-only/no-write failure before planning artifacts are generated. Report an upstream gate failure with the missing checklist item or readiness gap. Do not create or update feature files, and must not create or update behavior artifacts. Return to `/speckit.checklist` or `/speckit.clarify` instead of repairing requirements inside planning. +- `checklists/requirements.md` +- `checklists/behavior.md` +- `checklists/ux.md` +- `checklists/security.md` +- `checklists/nfr.md` +- `checklists/visual.md` -Phase 0 preflight must not modify `spec.md`, ask clarification questions, create formal contracts, or bypass the checklist gate. +All standard domains must be evaluated, metadata must match the current spec +revision, and every applicable gate must PASS. Do not accept the legacy +`checklists/behavior-testability.md` as evidence. Missing, BLOCKED, malformed, +or stale gates produce the core report-only/no-write failure. Return product +decisions to `/speckit.clarify` and provider evidence to intake. ## Phase 0 Behavior Projection @@ -51,7 +88,11 @@ After Phase 0 preflight passes and before core research or design work, project - `behavior/uif.intent.json`: interaction intent extracted from accepted requirements. - `behavior/data-fixtures.intent.json`: data setup intent required by draft scenarios. -Required case types from `checklists/behavior-testability.md` must project into `behavior/behavior-scenarios.draft.json`. Do not continue with only positive scenarios when Required case types exist. If a Required case type cannot be projected without inventing requirements, stop with a report-only/no-write failure and return to `/speckit.checklist` or `/speckit.clarify`. +Required case types from `checklists/behavior.md` must project into +`behavior/behavior-scenarios.draft.json`. Do not continue with only positive +scenarios when Required case types exist. If a Required case type cannot be +projected without inventing requirements, stop without partial behavior writes +and return to `/speckit.checklist` or `/speckit.clarify`. Phase 0 behavior projection is a projection step, not a new requirement-discovery step: @@ -92,17 +133,22 @@ When `plan.md` has a design artifact/navigation section, include links to: - Data model: `./data-model.md` - Interface contracts: `./contracts/` - Validation path: `./quickstart.md` +- Behavior testability: `./behavior/behavior-testability.md` -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. +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. -## UI/UX Planning Responsibilities +## Visual Planning Responsibilities -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. +When visual requirements are in scope, planning must keep +`checklists/visual.md` and its Visual Fidelity Evidence Matrix as the upstream +readiness record and split visual carry-forward across the existing planning +outputs. -- `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. +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`. ## Behavior-First Planning Inputs @@ -115,13 +161,20 @@ Use the Phase 0 behavior projection drafts as planning inputs: Phase 1 outputs must cite applicable draft scenario IDs or record `N/A or blocker`. -During Phase 1, if behavior drafts exist and checklists/behavior-testability.md has passed, you must formalize them into formal behavior contracts: +During Phase 1, if behavior drafts exist and the requirement gates have passed, +you must formalize them into formal behavior contracts: - `contracts/bdd/`: acceptance-level BDD contracts. - `contracts/uif/`: Expected UIF contracts. - `contracts/behavior/`: scenario instance, fixture, and assertion contracts. -Required case types from `checklists/behavior-testability.md` must formalize into `contracts/behavior/scenario-instances.json`. Do not continue with only positive scenarios when Required case types exist. Map each Required Case ID to a Scenario ID or `case_coverage_blockers` entry. When a Required case type cannot be formalized, write `case_coverage_blockers` in `contracts/behavior/scenario-instances.json` and record `N/A or blocker` with the Case ID, missing planning input, and downstream contract path. +Required case types from `checklists/behavior.md` must formalize into +`contracts/behavior/scenario-instances.json`. Do not continue with only positive +scenarios when Required case types exist. Map each Required Case ID to a +Scenario ID or `case_coverage_blockers` entry. When a Required case type cannot +be formalized, write `case_coverage_blockers` in +`contracts/behavior/scenario-instances.json` and record `N/A or blocker` with +the Case ID, missing planning input, and downstream contract path. When formalizing BDD Draft into `contracts/bdd/*.feature`: @@ -143,6 +196,33 @@ BDD draft reasoning must feed the normal planning outputs: Keep `plan.md` as summary/navigation for these formal behavior contracts. Product requirements stay in `spec.md`, domain details stay in `data-model.md`, interface schemas stay in `contracts/`, and validation run guidance stays in `quickstart.md`. +## BDD Plan / Behavior Testability Closeout + +After Phase 1 contracts, `research.md`, and `quickstart.md` are complete, +generate `behavior/behavior-testability.md` from the +`behavior-testability-template`. + +Compute and record the current spec and plan SHA-256 revisions. Build one Task +Derivation Matrix row for every Required Case from `checklists/behavior.md`. +Each row maps: + +`Case ID → Scenario ID → BDD ref → UIF ref → fixture ref → assertion ref → +validation level → research decision → quickstart path → visual/NFR refs`. + +- UIF may be `N/A` only with a concrete non-UI reason. +- Visual or NFR may be N/A only by referencing the corresponding requirement + gate and rationale. +- Validation level is `unit`, `contract`, `integration`, or `e2e`. +- Every missing mapping gets a stable blocker ID. +- `Behavior Testability Status: READY` requires every Required Case to have a + complete derivation row and no blocking items. +- Otherwise set `Behavior Testability Status: BLOCKED`. + +Recompute generated sections by stable Case ID. Do not append duplicate Gate +Status blocks, retain resolved blockers, copy the legacy +`checklists/behavior-testability.md`, re-check requirement prose, call provider +intake, or ask product clarification. + {CORE_TEMPLATE} ## Design Artifact Reporting @@ -156,5 +236,7 @@ Also report where validation decisions were recorded: - `research.md`: selected test level, fixture strategy, mock/external-system strategy, and error-branch validation decisions required by behavior contracts. - `quickstart.md`: executable validation paths for the planned behavior contracts. +- `behavior/behavior-testability.md`: READY or BLOCKED, with Required Case + coverage and blocker IDs. Report unresolved design gaps separately from downstream tasks. Do not mark the planning run complete if a design artifact contains unresolved `NEEDS CLARIFICATION` items that block task generation. diff --git a/presets/workflow-preset/commands/speckit.specify.md b/presets/workflow-preset/commands/speckit.specify.md index 6444942e24..fbb873fddc 100644 --- a/presets/workflow-preset/commands/speckit.specify.md +++ b/presets/workflow-preset/commands/speckit.specify.md @@ -6,49 +6,54 @@ 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, UI/UX requirements, constraints, assumptions, and clarification markers required by the active template. +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. -Keep requirement text implementation-agnostic and scoped to product behavior. Focus on WHAT users need and WHY; avoid HOW to implement it. +Keep requirement text implementation-agnostic and scoped to product behavior. Non-functional requirements must be explicit product-level assumptions or constraints, including no-special-requirement or not-applicable statements when that is the confirmed requirement. ## Wrapper Input Additions +Treat product notes, PRDs, user prompts, 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 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. +Treat confirmed Visual Asset Registry refs as external source artifact inputs only. They describe visual media inventory such as icons, images, illustrations, fonts, motion, video, textures, source refs, variants, license status, fallback policy, and blocker status. ## Wrapper Preflight Additions +Before writing 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. -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. +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`. ## 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. -Determine whether the feature has a user-facing surface or interaction journey: +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`. -- `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]`. +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. -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. +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. -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. +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. -Limit `[NEEDS CLARIFICATION]` markers to the highest-impact unresolved product decisions. Record reasonable low-impact defaults in Assumptions. +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. -## Specification Quality Validation +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. -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. +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. + +## 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]`. + +## 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. {CORE_TEMPLATE} ## Completion Report - -Before finishing, report the `spec.md` sections created or updated, confirmed requirements, UI/UX applicability, and unresolved requirement ambiguities. +Before finishing, report the `spec.md` sections created or updated, confirmed requirements, visual SSOT refs preserved, provider blockers, and unresolved requirement ambiguities. ## Done When - -- [ ] 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. +- [ ] 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]`. - [ ] Product `[NEEDS CLARIFICATION]` markers are limited to high-impact unresolved decisions. -- [ ] Completion reported updated `spec.md` sections and remaining ambiguities. +- [ ] Provider readiness blockers remain `[BLOCKED: PROVIDER_EVIDENCE]`. +- [ ] Completion reported with updated `spec.md` sections and remaining blockers. diff --git a/presets/workflow-preset/commands/speckit.tasks.md b/presets/workflow-preset/commands/speckit.tasks.md index 8f2ba1c7ae..28a8f13278 100644 --- a/presets/workflow-preset/commands/speckit.tasks.md +++ b/presets/workflow-preset/commands/speckit.tasks.md @@ -7,6 +7,27 @@ strategy: wrap Preserve the planned `M + U` scope in task text when deriving implementation, validation, and integration tasks. Do not generate execution metadata or write-path fields. +## Behavior Testability Preflight + +Before writing `tasks.md`, require +`behavior/behavior-testability.md` with: + +- `Stage: plan` +- `Behavior Testability Status: READY` +- current `Spec Revision` and `Plan Revision` +- one complete Task Derivation Matrix row for every Required Case + +If the file is missing, stale, malformed, or BLOCKED, stop before writing +`tasks.md` and report its blocker IDs. The legacy +`checklists/behavior-testability.md` cannot satisfy this preflight. + +Use the Task Derivation Matrix as the primary task input. For each Required +Case, generate the ordered chain: + +```text +fixture → validation/test → implementation → evidence +``` + ## Task-Derivation Subagents Follow cross-agent protocol profile: `speckit.tasks.stage_local_derivation`. @@ -20,14 +41,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. -- 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. +- 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. Every subagent payload must declare: -- `assigned_scope`: the user story, contract group, UI/UX requirement group, review scope, or blocker-check scope assigned to the subagent. +- `assigned_scope`: the user story, contract group, visual item 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, UI/UX requirement IDs, or summary slices the subagent may inspect within allowed files. +- `allowed_sections`: the exact headings, table names, contract IDs, scenario IDs, Visual Item 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,8 +65,13 @@ 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` 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. +- `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. +- `behavior/behavior-testability.md`: Required Case to scenario, contract, + fixture, assertion, validation, quickstart, and Visual/NFR mapping. +- `checklists/visual.md` Visual Fidelity Readiness: `Requirement Status`, + readiness input, visual/IR traceability refs, blockers, and accepted + exceptions. - `contracts/bdd/`: formal BDD acceptance contracts. - `contracts/uif/`: Expected UIF interaction contracts. - `contracts/behavior/`: formal scenario instance, fixture, and assertion contracts. @@ -53,11 +79,18 @@ 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, 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. +`/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. + +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 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. +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. -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. +Missing Required case coverage is a coverage blocker, not silently skipped +work. If `behavior/behavior-testability.md` contains a Required Case without a +complete derivation row, report the blocker instead of generating a +complete-looking task list. ## Validation Task Derivation @@ -78,12 +111,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, UI/UX requirement ID, quickstart validation path, 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, quickstart validation path, visual/IR traceability ref, 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, applicable `UI-###` or `UX-###` requirement ID, required state and viewport coverage, accessibility behavior, quickstart validation path, and observable evidence. +- `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. - `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. @@ -97,31 +130,42 @@ 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/UX task taxonomy when a user story includes `contracts/uif/` or ready `UI-###` / `UX-###` requirements: +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: -- 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. +- 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. -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. +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]`. -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 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 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`, `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. +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`, +`behavior/behavior-testability.md`, `spec.md` visual acceptance requirements, +`spec.md` Client Asset Contract entries, and `checklists/visual.md` Visual +Fidelity 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 UI/UX Specification 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 Visual Fidelity Readiness to make execution pass. -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. +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. 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 d8057b2a81..37c349569b 100644 --- a/presets/workflow-preset/docs/extension-governance.md +++ b/presets/workflow-preset/docs/extension-governance.md @@ -21,10 +21,13 @@ 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 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. +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. ## Template And Command Ownership @@ -32,30 +35,34 @@ source-agnostic requirement, planning, task, and implementation artifacts. - commands own stage-local generation instructions. - Commands may name the inputs they consume, the outputs they write, and the local update rules for their own phase. -- Do not put downstream prohibitions in upstream commands. +- An upstream stage may define the explicit consumption contract for its direct + standard SDD downstream stage when both stages are wrapped by this preset. - Do not encode full output structures only inside command text when the output is intended to be durable or reused by later phases. Stage ownership: -- `/speckit.constitution`: constitution governance and project principles only. +- `/speckit.constitution`: durable Constitution governance plus the separate + project-level `.specify/memory/architecture.md` lifecycle. - `/speckit.specify`: requirement artifacts only. -- `/speckit.clarify`: requirement clarification 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.clarify`: product-decision clarification and affected requirement-gate recomputation only. +- `/speckit.checklist`: requirements, behavior, UX, security, NFR, and visual requirement gates only. +- `/speckit.plan`: Architecture-guided planning, Phase 0 behavior projection, + planning artifacts, formal contracts, and BDD Plan closeout. - `/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, 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. +`/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. -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. +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. -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. +Visual Fidelity readiness applies to external-intake-derived and product-side +visual requirements. `checklists/visual.md` and its Visual Fidelity Evidence +Matrix are the single visual requirement-readiness record. Provider evidence +gaps remain intake blockers. The matrix must not define visual validation work, +screenshot comparison, visual diff, baseline capture, or final visual review. ## Structured Artifact Rules @@ -111,23 +118,26 @@ Planning design artifacts remain optional and contextual: - `class-diagram.md` - `contracts/sequences.md` -Validation strategy is derived by `/speckit.tasks` from behavior contracts, -interface contracts, `research.md`, and `quickstart.md`. Do not add a -standalone `test-plan.md` artifact unless the preset contract is deliberately -changed for an audit or manual-review requirement. +Validation decisions are recorded in `research.md`, executable paths in +`quickstart.md`, and the BDD Plan closeout maps them to Required Cases in +`behavior/behavior-testability.md`. `/speckit.tasks` derives concrete tasks from +that READY mapping. Do not add a standalone `test-plan.md`. + +Planning Readiness is aggregated at runtime from metadata-bearing requirement +gates. It is not a durable artifact and must never be written as +`planning-readiness.md`. + +`behavior/behavior-testability.md` is a permitted planning artifact, not a test +strategy document. It contains the task-derivation matrix and READY/BLOCKED +decision; it must not duplicate requirement prose, provider intake, or +clarification. Keep product requirements in `spec.md`, including explicit NFR assumptions; 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 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. +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. ## Handoff Extension Rules @@ -150,11 +160,13 @@ 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 4d6cda543e..a572aa7843 100644 --- a/presets/workflow-preset/preset.yml +++ b/presets/workflow-preset/preset.yml @@ -2,14 +2,14 @@ schema_version: '1.0' preset: id: workflow-preset name: Workflow Preset - version: 1.3.12 - description: Behavior-first specification, design artifacts, and agent-native handoff - orchestration + version: 2.0.0 + description: Constitution-managed architecture, behavior-first specification, design + artifacts, and agent-native handoff orchestration author: bigsmartben repository: https://github.com/bigsmartben/spec-kit-workflow-preset license: MIT requires: - speckit_version: '>=0.8.10.dev0' + speckit_version: '>=0.12.7.dev0' provides: templates: - type: template @@ -21,16 +21,17 @@ provides: - type: template name: constitution-template file: templates/constitution-template.md - description: Add change scope granularity and architecture SSOT governance to - the constitution template + description: Add change scope granularity and Constitution-managed architecture + governance 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 + name: architecture-template + file: templates/architecture-template.md + description: Define the single-file project Architecture maintained by the Constitution + stage + replaces: architecture-template + strategy: replace - type: command name: speckit.specify file: commands/speckit.specify.md @@ -40,40 +41,39 @@ provides: - type: command name: speckit.clarify file: commands/speckit.clarify.md - description: Wrap core clarification with spec-only ambiguity resolution + description: Wrap core clarification with product-decision gate repair replaces: speckit.clarify strategy: wrap - type: command name: speckit.checklist file: commands/speckit.checklist.md - description: Wrap core checklist generation with BDD, NFR, and UI/UX specification - readiness gate + description: Wrap core checklist generation with multi-domain requirement gates replaces: speckit.checklist strategy: wrap - type: command name: speckit.constitution file: commands/speckit.constitution.md - description: Wrap core constitution updates with change scope granularity and - architecture SSOT governance + description: Manage separate Constitution and Architecture artifacts under one + project lifecycle replaces: speckit.constitution strategy: wrap - type: command name: speckit.analyze file: commands/speckit.analyze.md - description: Wrap core analysis with behavior-first vertical consistency checks + description: Trace requirement gates through BDD Plan and task derivation replaces: speckit.analyze strategy: wrap - type: command name: speckit.plan file: commands/speckit.plan.md - description: Wrap core planning with Phase 0 behavior projection and optional - design artifacts + description: Consume project Architecture through Phase 0 behavior projection, + formal contracts, and BDD Plan closeout replaces: speckit.plan strategy: wrap - type: command name: speckit.tasks file: commands/speckit.tasks.md - description: Wrap task generation with optional design artifact awareness + description: Require READY behavior testability and derive complete task chains replaces: speckit.tasks strategy: wrap - type: command @@ -107,10 +107,34 @@ provides: replaces: behavior-data-fixtures-intent-template strategy: replace - type: template - name: behavior-testability-checklist-template - file: templates/behavior/behavior-testability-checklist.md - description: Template for BDD, NFR, and UI/UX specification readiness gate output - replaces: behavior-testability-checklist-template + name: requirement-domain-gate-template + file: templates/requirements/domain-gate.md + description: Template for UX, security, and additional requirement-domain gates + replaces: requirement-domain-gate-template + strategy: replace + - type: template + name: requirement-behavior-gate-template + file: templates/requirements/behavior-gate.md + description: Template for observable behavior and case coverage readiness + replaces: requirement-behavior-gate-template + strategy: replace + - type: template + name: requirement-nfr-gate-template + file: templates/requirements/nfr-gate.md + description: Template for non-functional requirement readiness + replaces: requirement-nfr-gate-template + strategy: replace + - type: template + name: requirement-visual-gate-template + file: templates/requirements/visual-gate.md + description: Template for visual requirement and provider-evidence readiness + replaces: requirement-visual-gate-template + strategy: replace + - type: template + name: behavior-testability-template + file: templates/behavior/behavior-testability.md + description: Template for plan-stage behavior testability and task readiness + replaces: behavior-testability-template strategy: replace - type: template name: behavior-bdd-contract-template @@ -203,6 +227,8 @@ provides: replaces: speckit-implement-receipt-v1-schema strategy: replace tags: +- architecture +- constitution - behavior - bdd - planning diff --git a/presets/workflow-preset/templates/architecture-template.md b/presets/workflow-preset/templates/architecture-template.md new file mode 100644 index 0000000000..09c9840162 --- /dev/null +++ b/presets/workflow-preset/templates/architecture-template.md @@ -0,0 +1,51 @@ +# Project Architecture: [PROJECT] + +**Architecture Goal**: [State the project-level architecture outcome this artifact guides.] + +**Project Mode**: [greenfield | brownfield | amendment] + +**Last Updated**: [DATE] + +**Authorized Sources**: + +- [Source and its agreed role] + +**Excluded Sources**: + +- [Source or `None`] + +## Architecture Overview + +[Summarize the target architecture, the current-to-target distinction when applicable, and the reasoning scope. Do not include an implementation plan.] + +## System Boundary + +| Boundary | Owns | Does Not Own | External Relationship / Dependency Direction | Source | +|----------|------|--------------|----------------------------------------------|--------| +| [At least one explicit boundary] | [Responsibility] | [Explicit non-responsibility] | [Inbound/outbound relationship] | [Authorized source] | + +## Conceptual Model + +| Concept | Stable Meaning | Owner | Relationships | Lifecycle | Invariants | Source | +|---------|----------------|-------|---------------|-----------|------------|--------| + +## Technical Decisions & Evidence + +| Decision / Candidate | Scope | Conclusion | Consequence | Evidence Or Explicit Gap | Revisit Condition | Validation | +|----------------------|-------|------------|-------------|--------------------------|-------------------|------------| + +Use `MUST_VALIDATE` in the Validation column only when planning depends on evidence that is not yet sufficient. Such a row requires a current conclusion and either available evidence or an explicit validation gap. + +## Planning Guardrails & Gaps + +### Constraints + +| Constraint | Applies To | Planning Implication | Source | +|------------|------------|----------------------|--------| + +### Unresolved Gaps + +| Gap | Planning Impact | Resolution Owner / Trigger | Source | +|-----|-----------------|----------------------------|--------| + +Optional tables may remain empty when they are not applicable. Do not add placeholder facts or invented records. diff --git a/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md b/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md deleted file mode 100644 index adcb490aab..0000000000 --- a/presets/workflow-preset/templates/behavior/behavior-testability-checklist.md +++ /dev/null @@ -1,94 +0,0 @@ -# Behavior Testability Checklist - -## User Story Readiness -- [ ] Each applicable user story has observable acceptance behavior. -- [ ] Each story identifies the actor or system responsible for the behavior. -- [ ] Each story has enough context to distinguish primary, alternate, and exception behavior when applicable. - -## Acceptance Criteria Quality -- [ ] Acceptance criteria are observable and verifiable from `spec.md`. -- [ ] Acceptance criteria avoid implementation-only wording. -- [ ] Business rules include precise success, rejection, validation, permission, boundary, and state_conflict outcomes when applicable. - -## Scenario Coverage -- [ ] Primary success behavior is covered. -- [ ] Alternate and exception behavior is covered when applicable. -- [ ] Boundary, permission, validation, and state_conflict behavior is covered when applicable. - -## Case Coverage Matrix -For each user story or capability, record one row per story or capability case type. Status: Required|Not Applicable|Unknown. - -| Case ID | Story/Capability | Case Type | Status | Source `spec.md` section | Blocking Item ID | Rationale | -| --- | --- | --- | --- | --- | --- | --- | -| CASE-PERMISSION-001 | Example | permission | Required | `spec.md#...` | | reason | -| CASE-BOUNDARY-001 | Example | boundary | Not Applicable | `spec.md#...` | | reason | -| CASE-VALIDATION-001 | Example | validation | Unknown | `spec.md#...` | BI-... | missing rule | - -- [ ] Required case type must cite the source `spec.md` section. -- [ ] Each row must have a stable Case ID. -- [ ] Scenario IDs and `case_coverage_blockers` are assigned during `/speckit.plan`. -- [ ] Not Applicable requires rationale. -- [ ] Unknown must appear in Blocking Items. - -## Given Readiness -- [ ] Required roles and permissions are explicit. -- [ ] Required starting state, entity state, and data are explicit enough for later fixture setup. -- [ ] Required data does not depend on production-only records. - -## When Readiness -- [ ] Each trigger is an executable user action, request case, or system trigger. -- [ ] Required inputs, selections, uploads, and submitted values are explicit. - -## Then Readiness -- [ ] Each outcome maps to user feedback, business state, error semantics, or assertion intent. -- [ ] Failure outcomes include precise feedback or error semantics. - -## Non-Functional Requirement Readiness -- [ ] Performance - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Security and Privacy - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Reliability and Recovery - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Accessibility - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Compliance and Auditability - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Observability - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Compatibility - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Data Lifecycle - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Cost and Operational Constraints - Status: Required|Not Applicable|Unknown; requirement or rationale is explicitly declared in `spec.md`. -- [ ] Required NFR entries have verifiable product-level criteria without prescribing architecture. -- [ ] Unknown NFR entries that affect downstream design are listed as blocking items. - -## 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 -Blocking Items: -- none diff --git a/presets/workflow-preset/templates/behavior/behavior-testability.md b/presets/workflow-preset/templates/behavior/behavior-testability.md new file mode 100644 index 0000000000..fec51dec26 --- /dev/null +++ b/presets/workflow-preset/templates/behavior/behavior-testability.md @@ -0,0 +1,46 @@ +# Behavior Testability / Task Readiness + +**Stage**: plan +**Behavior Testability Status**: READY | BLOCKED +**Spec Revision**: sha256:[SPEC_CONTENT_HASH] +**Plan Revision**: sha256:[PLAN_CONTENT_HASH] + +## Input Revisions + +| Input | Revision / Reference | +|---|---| +| `spec.md` | sha256:[SPEC_CONTENT_HASH] | +| `plan.md` | sha256:[PLAN_CONTENT_HASH] | +| Requirement gates | [paths and revisions] | +| Behavior drafts | [paths] | +| Formal contracts | [paths] | +| `research.md` | [reference] | +| `quickstart.md` | [reference] | + +## Task Derivation Matrix + +One row per Required Case. Every row must either map to a complete task +derivation path or name a blocker. + +| Case ID | Scenario ID | BDD Ref | UIF Ref | Fixture Ref | Assertion Ref | Validation Level | Research Ref | Quickstart Path | Visual/NFR Refs | Blocker ID | +|---|---|---|---|---|---|---|---|---|---|---| +| CASE-001 | SCN-001 | contracts/bdd/example.feature | N/A: non-UI behavior | FIX-001 | AST-001 | unit | research.md#decision | quickstart.md#path | checklists/nfr.md#NFR-001 | none | + +Validation Level is one of `unit`, `contract`, `integration`, or `e2e`. +UIF may be `N/A` only with a reason. NFR or visual references may point to an +explicit Not Applicable gate result. + +## Blocking Items + +- none + +## Task Readiness Decision + +- READY only when every Required Case has a Scenario ID, formal BDD/behavior + contract, fixture, assertion, validation decision, and quickstart path, plus + UIF and Visual/NFR references when applicable. +- BLOCKED when any Required Case lacks that mapping or any referenced planning + input is missing or stale. + + diff --git a/presets/workflow-preset/templates/constitution-template.md b/presets/workflow-preset/templates/constitution-template.md index 70a2b30388..ae85a8fcc4 100644 --- a/presets/workflow-preset/templates/constitution-template.md +++ b/presets/workflow-preset/templates/constitution-template.md @@ -17,23 +17,22 @@ If U -> concrete paths cannot be determined, report a context gap. Do not widen This principle applies from planning onward. Requirement specification, clarification, and checklist readiness MUST NOT infer M/U/O boundaries. -## Architecture SSOT Boundary +## Constitution And Architecture Boundary -Ratified constitution principles are durable governance rules, not architecture fact storage. -Architecture decisions, domain facts, object design, flows, and interface contracts belong in their architecture SSOT artifacts: +The Constitution stage maintains separate project-memory artifacts: -- `specs//data-model.md`: domain model and domain facts. -- `specs//class-diagram.md`: object, module, adapter, and internal design structure. -- `specs//contracts/sequences.md`: cross-boundary flow, sequencing, async, retry, rollback, and failure paths. -- `specs//contracts/`: interface and message contracts. -- `specs//research.md`: architecture decisions and tradeoffs that need evidence. +- `.specify/memory/constitution.md` contains durable governance principles. +- `.specify/memory/architecture.md` contains project-level boundaries, concepts, technical direction, evidence, constraints, and gaps. -Constitution principles may reference these SSOT artifact types, but must not copy concrete implementation facts, temporary repository observations, or module responsibility inventories into ratified governance text. +Ratified Constitution principles MUST NOT copy concrete Architecture facts. Feature-local planning artifacts may refine Architecture for one feature, but MUST NOT silently replace project Architecture. -## Architecture SSOT Compliance +## Architecture-Guided Planning -Ratified constitution principles define the compliance rule only. Concrete architecture decisions, domain facts, object design, flows, and interface contracts MUST remain in their Architecture SSOT artifacts. +`/speckit.plan` MUST read `.specify/memory/architecture.md` before producing planning artifacts. -Planning outputs MUST comply with existing Architecture SSOT artifacts. -Planning MUST NOT contradict, relocate, weaken, or silently replace architecture SSOT content. -If planning cannot produce outputs that comply with existing Architecture SSOT artifacts, report a planning blocker instead of generating inconsistent artifacts. +- `research.md` MUST follow established technical decisions and evidence, unless an Architecture revisit condition is met. +- `data-model.md` MUST preserve defined concepts, ownership, relationships, lifecycle, and invariants. +- `contracts/` MUST preserve system boundaries, responsibilities, interface ownership, and dependency direction. +- `plan.md` and `quickstart.md` MUST carry forward applicable Architecture constraints, gaps, and validation implications. + +If any planning artifact conflicts with or requires changing the Architecture, planning MUST stop and return to the Constitution stage. diff --git a/presets/workflow-preset/templates/plan-template.md b/presets/workflow-preset/templates/plan-template.md index ed9a2967b1..f82b14ff4e 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` -## UI/UX Planning Navigation +## Visual fidelity 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` +- 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` diff --git a/presets/workflow-preset/templates/requirements/behavior-gate.md b/presets/workflow-preset/templates/requirements/behavior-gate.md new file mode 100644 index 0000000000..80203b61c5 --- /dev/null +++ b/presets/workflow-preset/templates/requirements/behavior-gate.md @@ -0,0 +1,42 @@ +# Behavior Requirement Gate + +**Purpose**: Validate observable behavior and case coverage before behavior projection +**Stage**: requirements +**Domain**: behavior +**Gate**: planning-readiness +**Applicability**: APPLICABLE +**Status**: PASS | BLOCKED +**Spec Revision**: sha256:[SPEC_CONTENT_HASH] + +## User Story Readiness + +- [ ] CHK-BEH-001 [blocker:product-decision] [spec:STORY] Does each applicable story define observable acceptance behavior? + +## Given / When / Then Readiness + +- [ ] CHK-BEH-002 [blocker:product-decision] [spec:SECTION] Are roles, permissions, starting state, and required data explicit? +- [ ] CHK-BEH-003 [blocker:product-decision] [spec:SECTION] Is each trigger an executable user action, request case, or system event? +- [ ] CHK-BEH-004 [blocker:product-decision] [spec:SECTION] Does each outcome define feedback, business state, error semantics, or assertion intent? + +## Case Coverage Matrix + +One row per story or capability case type. Status: +`Required|Not Applicable|Unknown`. Each row has a stable Case ID. A Required +case cites its source `spec.md` section. Not Applicable requires rationale. +Unknown appears in Blocking Items. + +| Case ID | Story/Capability | Case Type | Status | Source `spec.md` section | Blocking Item ID | Rationale | +|---|---|---|---|---|---|---| +| CASE-[STORY]-POS-001 | [story] | positive | Required | [section] | none | [reason] | +| CASE-[STORY]-NEG-001 | [story] | negative | Unknown | [section] | BLK-BEH-001 | [reason] | + +Evaluate positive, negative, boundary, permission, validation, and +state_conflict case types. Scenario IDs and `case_coverage_blockers` are +assigned during `/speckit.plan`. + +## Blocking Items + +- none + + diff --git a/presets/workflow-preset/templates/requirements/domain-gate.md b/presets/workflow-preset/templates/requirements/domain-gate.md new file mode 100644 index 0000000000..bd3cfff012 --- /dev/null +++ b/presets/workflow-preset/templates/requirements/domain-gate.md @@ -0,0 +1,29 @@ +# [DOMAIN] Requirement Gate + +**Purpose**: Validate [DOMAIN] requirement quality before planning +**Stage**: requirements +**Domain**: [DOMAIN_ID] +**Gate**: planning-readiness +**Applicability**: APPLICABLE | NOT_APPLICABLE +**Status**: PASS | BLOCKED +**Spec Revision**: sha256:[SPEC_CONTENT_HASH] +**Applicability Reason**: [Required when NOT_APPLICABLE] + +## Requirement Completeness + +- [ ] CHK-[DOMAIN]-001 [blocker:product-decision] [spec:SECTION] Is the applicable [DOMAIN] behavior completely specified? + +## Requirement Clarity + +- [ ] CHK-[DOMAIN]-002 [blocker:product-decision] [spec:SECTION] Are ambiguous [DOMAIN] terms quantified or bounded? + +## Requirement Traceability + +- [ ] CHK-[DOMAIN]-003 [spec:SECTION] Does each applicable requirement cite its source section? + +## Blocking Items + +- none + + diff --git a/presets/workflow-preset/templates/requirements/nfr-gate.md b/presets/workflow-preset/templates/requirements/nfr-gate.md new file mode 100644 index 0000000000..b135c01189 --- /dev/null +++ b/presets/workflow-preset/templates/requirements/nfr-gate.md @@ -0,0 +1,33 @@ +# Non-Functional Requirement Gate + +**Purpose**: Validate product-level NFR declarations before planning +**Stage**: requirements +**Domain**: nfr +**Gate**: planning-readiness +**Applicability**: APPLICABLE | NOT_APPLICABLE +**Status**: PASS | BLOCKED +**Spec Revision**: sha256:[SPEC_CONTENT_HASH] +**Applicability Reason**: [Required when NOT_APPLICABLE] + +## NFR Coverage Matrix + +Each dimension must be `Required`, `Not Applicable`, or `Unknown`. Required +dimensions need verifiable product-level criteria. Not Applicable needs a +rationale. Unknown items affecting design are blockers. Do not prescribe +architecture. + +| NFR ID | Dimension | Status | Source `spec.md` section | Criterion / Rationale | Blocking Item ID | +|---|---|---|---|---|---| +| NFR-PERF-001 | Performance | [status] | [section] | [criterion] | [id/none] | +| NFR-SEC-001 | Security and Privacy | [status] | [section] | [criterion] | [id/none] | +| NFR-REL-001 | Reliability and Recovery | [status] | [section] | [criterion] | [id/none] | +| NFR-A11Y-001 | Accessibility | [status] | [section] | [criterion] | [id/none] | +| NFR-COMP-001 | Compliance and Auditability | [status] | [section] | [criterion] | [id/none] | +| NFR-OBS-001 | Observability | [status] | [section] | [criterion] | [id/none] | +| NFR-COMPAT-001 | Compatibility | [status] | [section] | [criterion] | [id/none] | +| NFR-DATA-001 | Data Lifecycle | [status] | [section] | [criterion] | [id/none] | +| NFR-COST-001 | Cost and Operational Constraints | [status] | [section] | [criterion] | [id/none] | + +## Blocking Items + +- none diff --git a/presets/workflow-preset/templates/requirements/visual-gate.md b/presets/workflow-preset/templates/requirements/visual-gate.md new file mode 100644 index 0000000000..9e1183e6dd --- /dev/null +++ b/presets/workflow-preset/templates/requirements/visual-gate.md @@ -0,0 +1,37 @@ +# Visual Requirement Gate + +**Purpose**: Validate visual/UI requirements and cited evidence before planning +**Stage**: requirements +**Domain**: visual +**Gate**: planning-readiness +**Applicability**: APPLICABLE | NOT_APPLICABLE +**Status**: PASS | BLOCKED +**Spec Revision**: sha256:[SPEC_CONTENT_HASH] +**Applicability Reason**: [Required when NOT_APPLICABLE] + +## Visual Fidelity Readiness + +Every identified visual/UI requirement uses `Required`, `Not Applicable`, +`Unknown`, or `[BLOCKED: PROVIDER_EVIDENCE]`. Required items need observable +requirement text. Unknown items become product-decision blockers. Provider +evidence gaps remain intake blockers and are never converted to clarification. + +## Visual Fidelity Evidence Matrix + +This is the single visual planning-readiness record. + +| Visual Item ID | 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 | Accepted Exception Refs | +|---|---|---|---|---|---|---|---|---|---|---| +| VIS-001 | [section] | [status] | [yes/no] | [refs] | [refs] | [refs] | [refs] | [input] | [id/none] | [refs/none] | + +Record state, responsive, accessibility, component mapping, asset/fallback, and +accepted-exception coverage when applicable. Responsive visual requirements +block PASS only when required source-backed state or viewport evidence is +missing for a feature that depends on provider evidence. + +Do not call provider tools, re-parse provider artifacts, define screenshot +comparison, visual diff, baseline capture, or final visual review. + +## Blocking Items + +- none diff --git a/presets/workflow-preset/templates/spec-template.md b/presets/workflow-preset/templates/spec-template.md deleted file mode 100644 index a5056d7a2b..0000000000 --- a/presets/workflow-preset/templates/spec-template.md +++ /dev/null @@ -1,53 +0,0 @@ -{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 6e7cf39b38..3c0fec6367 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 product decisions, and existing requirement context selected by core Spec Kit behavior. +- `input_scope`: user prompt, product notes, confirmed external intake refs, visual SSOT refs, HTML SSOT refs, structured IR refs, screenshots, and visual proof refs. - `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 assumptions, UI/UX Applicability, stable `UI-###` and `UX-###` IDs, and observable acceptance criteria. +- `output_contract`: stakeholder-readable requirements with explicit source-backed facts, assumptions, visual/UI status, and provider blockers. - `validation_gate`: specification quality validation in `/speckit.specify`. -- `stop_conditions`: missing feature description, unsupported inference, or unresolved product decisions that prevent a testable specification. +- `stop_conditions`: missing feature description, unsupported inference, or provider evidence treated as product semantics. - `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, ready UI/UX requirement rows, and review scopes. +- `input_scope`: user stories, behavior contracts, interface contracts, research decisions, quickstart validation paths, visual readiness rows, visual/IR traceability refs, 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, Blocked or Unknown UI/UX readiness, or unresolved task-derivation `context_gaps`. +- `stop_conditions`: missing Required case coverage, missing required provider evidence, 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 5ef4f6e0da..37ebdc7ef4 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 a relevant BDD scenario, behavior assertion, API contract, UIF path, `UI-###` or `UX-###` requirement ID, quickstart validation path, or captured command output +- 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 - 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 -- 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` +- 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 - 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, 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 +- 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 - 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, 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` +- 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` diff --git a/presets/workflow-preset/tests/test_preset_contract.py b/presets/workflow-preset/tests/test_preset_contract.py index fef5f2f63f..a98d8f2e56 100644 --- a/presets/workflow-preset/tests/test_preset_contract.py +++ b/presets/workflow-preset/tests/test_preset_contract.py @@ -42,8 +42,26 @@ TASKS_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.tasks.md" IMPLEMENT_COMMAND_PATH = REPO_ROOT / "commands" / "speckit.implement.md" CONSTITUTION_TEMPLATE_PATH = REPO_ROOT / "templates" / "constitution-template.md" +ARCHITECTURE_TEMPLATE_PATH = REPO_ROOT / "templates" / "architecture-template.md" PLAN_TEMPLATE_PATH = REPO_ROOT / "templates" / "plan-template.md" -SPEC_TEMPLATE_PATH = REPO_ROOT / "templates" / "spec-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", + "历史版本", + "旧版兼容", + "兼容旧版", + "回退视觉规则", +) 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" @@ -82,10 +100,10 @@ / "templates" / "behavior" / "data-fixtures-intent.json", - "behavior-testability-checklist-template": REPO_ROOT + "behavior-testability-template": REPO_ROOT / "templates" / "behavior" - / "behavior-testability-checklist.md", + / "behavior-testability.md", "behavior-bdd-contract-template": REPO_ROOT / "templates" / "behavior" / "bdd-contract.feature", "behavior-uif-expected-template": REPO_ROOT / "templates" / "behavior" / "uif-expected.json", "behavior-scenario-instances-template": REPO_ROOT @@ -95,6 +113,24 @@ "behavior-data-fixtures-template": REPO_ROOT / "templates" / "behavior" / "data-fixtures.json", "behavior-assertions-template": REPO_ROOT / "templates" / "behavior" / "assertions.json", } +REQUIREMENT_TEMPLATE_PATHS = { + "requirement-domain-gate-template": REPO_ROOT + / "templates" + / "requirements" + / "domain-gate.md", + "requirement-behavior-gate-template": REPO_ROOT + / "templates" + / "requirements" + / "behavior-gate.md", + "requirement-nfr-gate-template": REPO_ROOT + / "templates" + / "requirements" + / "nfr-gate.md", + "requirement-visual-gate-template": REPO_ROOT + / "templates" + / "requirements" + / "visual-gate.md", +} HANDOFF_CLI_PATH = REPO_ROOT / "scripts" / "speckit-implement-handoff.py" BUILD_SCRIPT_PATH = REPO_ROOT / "scripts" / "build-task-shards.py" RUN_SCRIPT_PATH = REPO_ROOT / "scripts" / "run-orchestrated-implement.py" @@ -473,15 +509,119 @@ def minimal_exception_behavior_assertions_with_intent(intent: str) -> dict: class PresetContractTests(unittest.TestCase): + def test_requirement_gate_and_clarify_repair_contract(self) -> None: + checklist = CHECKLIST_COMMAND_PATH.read_text(encoding="utf-8") + clarify = CLARIFY_COMMAND_PATH.read_text(encoding="utf-8") + + for path in ( + "checklists/requirements.md", + "checklists/behavior.md", + "checklists/ux.md", + "checklists/security.md", + "checklists/nfr.md", + "checklists/visual.md", + ): + self.assertIn(path, checklist) + self.assertIn("Planning Readiness is aggregated in memory", checklist) + self.assertIn("do not create\n`planning-readiness.md`", checklist) + self.assertIn("Case Coverage Matrix", checklist) + self.assertIn("Visual Fidelity Evidence Matrix", checklist) + self.assertIn("[blocker:provider-evidence] [return:intake]", checklist) + self.assertIn("Recompute generated sections using stable", checklist) + self.assertIn("legacy `checklists/behavior-testability.md`", checklist) + + self.assertIn("[blocker:product-decision]", clarify) + self.assertIn("[blocker:provider-evidence]", clarify) + self.assertIn("preserve its `[return:intake]`", clarify) + self.assertIn("recompute affected requirement gates", clarify) + self.assertIn("never create `planning-readiness.md`", clarify) + + def test_bdd_plan_task_readiness_contract(self) -> None: + plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") + tasks = TASKS_COMMAND_PATH.read_text(encoding="utf-8") + analyze = ANALYZE_COMMAND_PATH.read_text(encoding="utf-8") + + self.assertIn("Phase 0 Gate Consumption", plan) + self.assertIn("Required case types from `checklists/behavior.md`", plan) + self.assertIn("BDD Plan / Behavior Testability Closeout", plan) + self.assertIn("generate `behavior/behavior-testability.md`", plan) + self.assertIn("Behavior Testability Status: READY", plan) + self.assertIn("Task\nDerivation Matrix", plan) + self.assertIn("UIF may be `N/A` only with a concrete non-UI reason", plan) + self.assertIn("Do not accept the legacy", plan) + + self.assertIn("Behavior Testability Preflight", tasks) + self.assertIn("Behavior Testability Status: READY", tasks) + self.assertIn("stop before writing\n`tasks.md`", tasks) + self.assertIn("Task Derivation Matrix as the primary task input", tasks) + self.assertIn("fixture → validation/test → implementation → evidence", tasks) + + self.assertIn( + "requirement gates -> BDD/UIF intent -> contracts -> behavior testability -> tasks", + analyze, + ) + self.assertIn("`behavior/behavior-testability.md` carries current spec/plan revisions", analyze) + + def test_requirement_and_behavior_testability_templates_contract(self) -> None: + for path in (*REQUIREMENT_TEMPLATE_PATHS.values(), *BEHAVIOR_TEMPLATE_PATHS.values()): + self.assertTrue(path.exists(), path) + + behavior_gate = REQUIREMENT_TEMPLATE_PATHS[ + "requirement-behavior-gate-template" + ].read_text(encoding="utf-8") + nfr_gate = REQUIREMENT_TEMPLATE_PATHS[ + "requirement-nfr-gate-template" + ].read_text(encoding="utf-8") + visual_gate = REQUIREMENT_TEMPLATE_PATHS[ + "requirement-visual-gate-template" + ].read_text(encoding="utf-8") + task_readiness = BEHAVIOR_TEMPLATE_PATHS[ + "behavior-testability-template" + ].read_text(encoding="utf-8") + + self.assertIn("**Stage**: requirements", behavior_gate) + self.assertIn("Case Coverage Matrix", behavior_gate) + self.assertIn("positive, negative, boundary, permission, validation", behavior_gate) + self.assertIn("NFR Coverage Matrix", nfr_gate) + self.assertIn("Not Applicable", nfr_gate) + self.assertIn("Visual Fidelity Evidence Matrix", visual_gate) + self.assertIn("[BLOCKED: PROVIDER_EVIDENCE]", visual_gate) + + self.assertIn("Behavior Testability / Task Readiness", task_readiness) + self.assertIn("**Stage**: plan", task_readiness) + self.assertIn("**Behavior Testability Status**: READY | BLOCKED", task_readiness) + self.assertIn("**Spec Revision**", task_readiness) + self.assertIn("**Plan Revision**", task_readiness) + self.assertIn("Task Derivation Matrix", task_readiness) + self.assertIn("| Case ID | Scenario ID | BDD Ref | UIF Ref | Fixture Ref | Assertion Ref |", task_readiness) + self.assertFalse( + (REPO_ROOT / "templates" / "behavior" / "behavior-testability-checklist.md").exists() + ) + + def test_public_docs_define_two_stage_ownership(self) -> None: + readme = README_PATH.read_text(encoding="utf-8") + governance = EXTENSION_GOVERNANCE_PATH.read_text(encoding="utf-8") + + self.assertIn("multi-domain requirement gates", readme) + self.assertIn("no `planning-readiness.md` is generated", readme) + self.assertIn("`behavior/behavior-testability.md` is generated at plan closeout", readme) + self.assertIn("provider evidence remains an intake blocker", readme) + + self.assertIn("requirement-gate recomputation only", governance) + self.assertIn("requirements, behavior, UX, security, NFR, and visual requirement gates", governance) + self.assertIn("BDD Plan closeout", governance) + self.assertIn("must never be written as\n`planning-readiness.md`", governance) + self.assertIn("`behavior/behavior-testability.md` is a permitted planning artifact", governance) + def test_preset_manifest_contract(self) -> None: data = yaml.safe_load(PRESET_PATH.read_text(encoding="utf-8")) self.assertEqual("1.0", data["schema_version"]) self.assertEqual("workflow-preset", data["preset"]["id"]) self.assertEqual("Workflow Preset", data["preset"]["name"]) - self.assertEqual("1.3.12", data["preset"]["version"]) + self.assertEqual("2.0.0", data["preset"]["version"]) self.assertEqual( - "Behavior-first specification, design artifacts, and agent-native handoff orchestration", + "Constitution-managed architecture, behavior-first specification, design artifacts, and agent-native handoff orchestration", data["preset"]["description"], ) self.assertEqual("bigsmartben", data["preset"]["author"]) @@ -490,14 +630,14 @@ def test_preset_manifest_contract(self) -> None: data["preset"]["repository"], ) self.assertEqual("MIT", data["preset"]["license"]) - self.assertEqual(">=0.8.10.dev0", data["requires"]["speckit_version"]) + self.assertEqual(">=0.12.7.dev0", data["requires"]["speckit_version"]) self.assertEqual( - ["behavior", "bdd", "planning", "implementation", "handoff"], + ["architecture", "constitution", "behavior", "bdd", "planning", "implementation", "handoff"], data["tags"], ) provides = data["provides"]["templates"] - self.assertEqual(31, len(provides)) + self.assertEqual(35, 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) @@ -522,11 +662,11 @@ 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"]) + architecture_template = entries["architecture-template"] + self.assertEqual("template", architecture_template["type"]) + self.assertEqual("templates/architecture-template.md", architecture_template["file"]) + self.assertEqual("architecture-template", architecture_template["replaces"]) + self.assertEqual("replace", architecture_template["strategy"]) for command_name in ("speckit.plan", "speckit.tasks"): command = entries[command_name] @@ -536,7 +676,7 @@ def test_preset_manifest_contract(self) -> None: self.assertEqual("wrap", command["strategy"]) self.assertEqual( - "Wrap core planning with Phase 0 behavior projection and optional design artifacts", + "Consume project Architecture through Phase 0 behavior projection, formal contracts, and BDD Plan closeout", entries["speckit.plan"]["description"], ) self.assertEqual( @@ -544,13 +684,16 @@ def test_preset_manifest_contract(self) -> None: entries["speckit.specify"]["description"], ) self.assertEqual( - "Wrap core clarification with spec-only ambiguity resolution", + "Wrap core clarification with product-decision gate repair", entries["speckit.clarify"]["description"], ) self.assertEqual( - "Wrap core checklist generation with BDD, NFR, and UI/UX specification readiness gate", + "Wrap core checklist generation with multi-domain requirement gates", entries["speckit.checklist"]["description"], ) + for template_name in (*REQUIREMENT_TEMPLATE_PATHS, "behavior-testability-template"): + self.assertIn(template_name, entries) + self.assertNotIn("behavior-testability-checklist-template", entries) for command_name in ( "speckit.specify", @@ -581,11 +724,11 @@ def test_preset_manifest_contract(self) -> None: self.assertNotIn(implement_only_term, specify_command) self.assertEqual( - "Wrap core constitution updates with change scope granularity and architecture SSOT governance", + "Manage separate Constitution and Architecture artifacts under one project lifecycle", entries["speckit.constitution"]["description"], ) self.assertEqual( - "Add change scope granularity and architecture SSOT governance to the constitution template", + "Add change scope granularity and Constitution-managed architecture governance", entries["constitution-template"]["description"], ) @@ -655,6 +798,14 @@ def test_plan_command_wrapper_contract(self) -> None: self.assertIn("validation decisions belong in `research.md`", command) self.assertIn("executable validation paths belong in `quickstart.md`", command) self.assertIn("final report must list generated artifacts", command) + self.assertIn("## Architecture-Guided Planning", command) + self.assertIn(".specify/memory/architecture.md", command) + self.assertIn("`research.md` MUST follow established technical decisions and evidence", command) + self.assertIn("`data-model.md` MUST preserve defined concepts", command) + self.assertIn("`contracts/` MUST preserve system boundaries", command) + self.assertIn("`plan.md` and `quickstart.md` MUST carry forward", command) + self.assertIn("return to the Constitution stage", command) + self.assertIn("Do not create a compliance matrix", command) self.assertIn("Plan Agent Topology", command) self.assertIn( "Follow cross-agent protocol profile: `speckit.plan.stage_local_planning`", @@ -666,7 +817,7 @@ def test_plan_command_wrapper_contract(self) -> None: "Formal Contract Agent", "Design Artifact Agent", "Validation Planning Agent", - "UI/UX Planning Agent", + "Visual Planning Agent", ): self.assertIn(agent_role, command) self.assertIn("Each payload declares assigned scope, allowed reads, allowed sections, and output contract", command) @@ -686,42 +837,49 @@ def test_plan_template_navigation_contract(self) -> None: self.assertIn("./contracts/", template) self.assertIn("./quickstart.md", template) - def test_plan_ui_ux_substage_enhancement_contract(self) -> None: + def test_plan_visual_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 ( - "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", + "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", ): self.assertIn(term, command) for term in ( - "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`", + "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`", ): self.assertIn(term, template) for document in (readme, governance): self.assertIn("research.md", document) - self.assertIn("UI/UX", document) - self.assertIn("contracts", document) - self.assertIn("contracts/sequences.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( "fixed R/M/U/O model: R is Repository / Workspace, M is Module / Capability, U is Unit / Design Object, and O is Operation / Detail", @@ -731,14 +889,13 @@ def test_plan_ui_ux_substage_enhancement_contract(self) -> None: "Blocks constitution writes when a generated draft changes the fixed R/M/U/O mapping", readme, ) - self.assertIn( - "Routes architecture decisions, domain facts, object design, flows, and interface contracts to architecture SSOT artifacts instead of embedding concrete implementation content in ratified constitution principles", - readme, - ) + self.assertIn("single-file project Architecture lifecycle", readme) + self.assertIn("System Boundary -> Conceptual Model", readme) def test_constitution_change_scope_granularity_contract(self) -> None: command = CONSTITUTION_COMMAND_PATH.read_text(encoding="utf-8") template = CONSTITUTION_TEMPLATE_PATH.read_text(encoding="utf-8") + architecture = ARCHITECTURE_TEMPLATE_PATH.read_text(encoding="utf-8") exact_mapping = [ "R: Repository / Workspace. Environment only; too broad for scoped changes.", @@ -779,58 +936,49 @@ def test_constitution_change_scope_granularity_contract(self) -> None: self.assertIn("CONSTITUTION_TEMPLATE_STATUS_UNCHECKED", command) self.assertIn("do not report it as missing", command) self.assertIn("do not treat that as the workflow-preset template being absent", command) - self.assertIn("Architecture SSOT Boundary", command) - self.assertIn("Architecture SSOT Compliance", command) - self.assertIn("Ratified constitution principles must be durable governance rules, not architecture fact storage", command) - self.assertIn( - "Architecture decisions, domain facts, object design, flows, and interface contracts belong in their architecture SSOT artifacts", - command, - ) - self.assertIn("specs//data-model.md", command) - self.assertIn("specs//class-diagram.md", command) - self.assertIn("specs//contracts/sequences.md", command) - self.assertIn("specs//contracts/", command) - self.assertIn("specs//research.md", command) - self.assertIn( - "MUST NOT capture, discover, extract, migrate, store, validate, or repair architecture facts", - command, - ) - self.assertIn("do not embed them in ratified principles", command) - self.assertIn("name the responsible workflow-preset SSOT artifact type", command) - self.assertIn("Do not write concrete `specs//...` paths", command) - self.assertIn("check those paths", command) - self.assertIn("create or update those artifacts", command) - self.assertIn("CONSTITUTION_ARCH_SSOT_GAP", command) - self.assertIn("copy concrete implementation facts", command) - self.assertIn("Planning outputs MUST comply with existing Architecture SSOT artifacts", command) - self.assertIn("MUST NOT contradict, relocate, weaken, or silently replace architecture SSOT content", command) - self.assertIn("requires planning outputs to comply with existing Architecture SSOT artifacts", command) - self.assertIn( - "routes architecture decisions, domain facts, object design, flows, and interface contracts to workflow-preset SSOT artifact types", - command, - ) - self.assertNotIn("unless the current Spec Kit context already provides an existing feature path", command) - self.assertNotIn("required existing SSOT path is absent", command) + self.assertIn("Constitution Stage Input Agreement", command) + for mode in ("greenfield", "brownfield", "amendment"): + self.assertIn(mode, command) + self.assertIn("No conventional path is mandatory", command) + self.assertIn("candidate sources only until the user authorizes their role", command) + self.assertIn("Existing code is evidence", command) + self.assertIn("ARCH_LEGACY_FORMAT", command) + self.assertIn("Separate Artifact Ownership", command) + self.assertIn(".specify/memory/constitution.md", command) + self.assertIn(".specify/memory/architecture.md", command) + self.assertIn("write exactly one Architecture artifact", command) + self.assertIn("without 4+1", command) + self.assertIn("Technical validation is evidence registration only", command) + self.assertIn("Optional tables may be empty", command) + self.assertIn("Do not create PoC code", command) + self.assertIn("Architecture-Guided Planning", command) + self.assertIn("`/speckit.plan` MUST read", command) + self.assertIn("planning MUST stop and return to the Constitution stage", command) self.assertIn("The R/M/U/O letter mapping is fixed", template) - self.assertIn("Architecture SSOT Boundary", template) - self.assertIn("Architecture SSOT Compliance", template) - self.assertIn("Ratified constitution principles are durable governance rules, not architecture fact storage", template) - self.assertIn( - "Architecture decisions, domain facts, object design, flows, and interface contracts belong in their architecture SSOT artifacts", - template, - ) - self.assertIn("specs//data-model.md", template) - self.assertIn("specs//class-diagram.md", template) - self.assertIn("specs//contracts/sequences.md", template) - self.assertIn("specs//contracts/", template) - self.assertIn("specs//research.md", template) - self.assertIn("may reference these SSOT artifact types", template) - self.assertIn( - "must not copy concrete implementation facts, temporary repository observations, or module responsibility inventories", - template, + self.assertIn("Constitution And Architecture Boundary", template) + self.assertIn("Feature-local planning artifacts may refine Architecture", template) + self.assertIn("Architecture-Guided Planning", template) + self.assertIn("`research.md` MUST follow established technical decisions", template) + self.assertIn("`contracts/` MUST preserve system boundaries", template) + + expected_sections = [ + "Architecture Overview", + "System Boundary", + "Conceptual Model", + "Technical Decisions & Evidence", + "Planning Guardrails & Gaps", + ] + self.assertEqual( + expected_sections, + re.findall(r"^## (.+)$", architecture, flags=re.MULTILINE), ) - self.assertIn("Planning outputs MUST comply with existing Architecture SSOT artifacts", template) - self.assertIn("Planning MUST NOT contradict, relocate, weaken, or silently replace architecture SSOT content", template) + self.assertIn("**Architecture Goal**", architecture) + self.assertIn("**Authorized Sources**", architecture) + self.assertIn("Does Not Own", architecture) + self.assertIn("Evidence Or Explicit Gap", architecture) + self.assertIn("MUST_VALIDATE", architecture) + self.assertIn("Optional tables may remain empty", architecture) + self.assertNotIn("4+1", architecture) def test_change_scope_granularity_stage_references(self) -> None: plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") @@ -881,7 +1029,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, validation, and review task definition in `tasks.md`", tasks) + self.assertIn("`/speckit.tasks` owns implementation, non-visual 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) @@ -892,7 +1040,7 @@ def test_tasks_command_wrapper_contract(self) -> None: for agent_role in ( "Story Task Agent", "Contract Validation Agent", - "UI/UX Task Agent", + "Visual Task Agent", "Review Task Agent", ): self.assertIn(agent_role, tasks) @@ -925,27 +1073,28 @@ 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`, `ui_ux`, `data_side_effect`, `behavior_contract`, and `sequence_consistency`", tasks) + self.assertIn("`boundary`, `interface_contract`, `visual`, `data_side_effect`, `behavior_contract`, `sequence_consistency`, and `asset_binding`", tasks) self.assertIn("Checked sources include", tasks) self.assertIn("`contracts/uif/`", tasks) - self.assertIn("`spec.md` UI/UX requirements", tasks) - self.assertIn("UI/UX Specification Readiness", tasks) + self.assertIn("`spec.md` Client Asset Contract entries", tasks) + self.assertIn("Visual Fidelity 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 UI/UX Specification Readiness", tasks) + self.assertIn("no implementation task changed `spec.md`, `contracts/`, readiness checklists, or Visual Fidelity Readiness", tasks) self.assertIn("UI consistency review", 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("implemented UI states and viewport behavior", tasks) + self.assertIn("visual/IR traceability refs", tasks) + self.assertIn("UI/visual task taxonomy", tasks) self.assertIn("story-local task granularity", 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("`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("report a readiness blocker instead of generating an ambiguous task", tasks) - self.assertIn("required state, viewport, and accessibility coverage", 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("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) @@ -976,94 +1125,269 @@ 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) self.assertIn("strategy: wrap", command) + for command in (specify, clarify): self.assertIn( "This wrapper must not redefine core-owned User Input, Pre-Execution Checks, extension hooks, base path resolution, or core file handling.", command, ) - + self.assertIn("This wrapper extends the core spec-only checklist contract", checklist) + self.assertIn("must not read\n`plan.md` or `tasks.md`", checklist) + self.assertIn("Planning Readiness is aggregated in memory", checklist) + + 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 ( - "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", + "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", "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 ( - "## 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 |", + "confirmed external intake facts", + "visual 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", + "status `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", + ): + 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("recompute affected requirement gates", clarify) + self.assertIn("Replace generated status and blocker", 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) + self.assertNotIn(forbidden, clarify) 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", + "Multi-Domain Requirement Gate", + "Use `$ARGUMENTS` only to prioritize requirement-quality focus", + "Stage/Domain/Gate/Applicability/Status/Spec Revision", + "The legacy `checklists/behavior-testability.md` is not an input or output", + "Behavior Requirement Gate", + "Case Coverage Matrix", + "positive, negative, boundary, permission, validation, and", + "state_conflict", + "stable Case IDs", + "Scenario IDs and `case_coverage_blockers` remain `/speckit.plan` outputs", + "This gate checks whether behavior requirements are projectable", + "NFR Requirement Gate", + "verifiable product-level criteria", + "Do not require", + "technical designs or invent architecture", + "Recompute generated sections using stable CHK/CASE/NFR/VIS IDs", + "Never append", + "duplicate status blocks, stale blockers, or repeated matrix rows", ): - self.assertIn(term, clarify) - + self.assertIn(term, checklist) for term in ( - '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", - "BDD/NFR/UI/UX readiness status", + "Visual Requirement Gate", + "Visual & UI Specification", + "Apply the gate when `spec.md` contains a Visual & UI Specification", + "Every visual item is", + "`[BLOCKED: PROVIDER_EVIDENCE]`", + "Unknown product semantics become `[blocker:product-decision]`", + "Missing provider proof remains `[blocker:provider-evidence] [return:intake]`", + "Provider blockers must not be converted into clarify questions", + "visual SSOT refs", + "external intake refs", + "structured IR refs", + "Visual Fidelity Evidence Matrix", + "source traceability", + "readiness input", + "Responsive visual requirements block PASS only when required source-backed", + "Do not call provider tools, rebuild intake evidence", ): self.assertIn(term, checklist) - 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) + 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("Planning Readiness aggregate", checklist) + self.assertIn("provider-evidence\nblockers separately", checklist) + return + self.assertIn("PASS", checklist) + self.assertIn("BLOCKED", checklist) + self.assertIn("product-decision blockers, and provider-evidence", checklist) def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: plan = PLAN_COMMAND_PATH.read_text(encoding="utf-8") @@ -1090,31 +1414,45 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "UIFPath", "FeedbackView", "BehaviorAssertion", - "Required case types from `checklists/behavior-testability.md`", - "must project into `behavior/behavior-scenarios.draft.json`", - "must formalize into `contracts/behavior/scenario-instances.json`", - "Do not continue with only positive scenarios when Required case types exist", - "Map each Required Case ID to a Scenario ID or `case_coverage_blockers` entry", + "Required case types from `checklists/behavior.md`", + "must project into", + "`behavior/behavior-scenarios.draft.json`", + "must formalize into", + "`contracts/behavior/scenario-instances.json`", + "Do not continue with only positive", + "scenarios when Required case types exist", + "Map each Required Case ID to a", + "Scenario ID or `case_coverage_blockers` entry", "write `case_coverage_blockers`", - "record `N/A or blocker` with the Case ID", + "record `N/A or blocker` with", + "the Case ID, missing planning input", ): self.assertIn(term, plan) + self.assertIn("BDD Plan closeout", plan) + self.assertIn("behavior/behavior-testability.md", plan) + return + for term in ( - "Phase 0 Preflight", + "Phase 0 Gate Consumption", "Phase 0 Behavior Projection", - "checklists/behavior-testability.md has passed", - "Blocking Items: none` or a `Blocking Items` section containing only `- none`", + "read-only Planning Readiness preflight", "before core research or design work", - "UI/UX Planning Responsibilities", - "accepted `UI-###` and `UX-###` requirements", - "Applicability is `Required` and Readiness is `Ready`", - "If a row is `Unknown` or `Blocked`", + "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", "report-only/no-write upstream gate failure", - "Do not project `Not Applicable` rows into planning outputs", + "Do not project `Not Applicable` rows into visual planning outputs", "behavior/behavior-scenarios.draft.json", "report-only/no-write failure", - "must not create or update behavior artifacts", + "Do not create or update partial behavior artifacts", "Do not discover new requirement problems", "Do not ask clarification questions", "Do not modify `spec.md`", @@ -1126,14 +1464,23 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: self.assertNotIn("empty, or records only an upstream gate failure", plan) self.assertNotIn("behavior/open-questions.json", plan) self.assertNotIn("test-plan.md", plan) + self.assertIn("BDD Plan closeout", plan) + self.assertIn("behavior/behavior-testability.md", plan) + return for term in ( "contracts/bdd/", "contracts/uif/", "contracts/behavior/", - "`spec.md` UI/UX requirements", - "`checklists/behavior-testability.md` UI/UX Specification Readiness", - "`UI-###` and `UX-###` requirements", + "`spec.md` visual acceptance requirements", + "`checklists/visual.md` Visual Fidelity Readiness", + "HTML SSOT refs", + "structured IR refs", + "screenshot refs", + "visual proof refs", + "visual SSOT refs", + "external evidence refs", + "visual fidelity requirements", "test-first", "existing checklist format and user-story organization", "For each BehaviorScenarioInstance", @@ -1143,18 +1490,20 @@ 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/UX task taxonomy", + "UI/visual task taxonomy", "`ui_acceptance`", "UI acceptance task", + "viewport/state requirement refs", "required state and viewport coverage", - "accessibility behavior", + "visual/IR traceability ref", "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, validation, and review task definition in `tasks.md`", + "`/speckit.tasks` owns implementation, non-visual 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", @@ -1163,35 +1512,56 @@ def test_behavior_first_plan_and_tasks_awareness_contract(self) -> None: "`ui_acceptance`", "`data_side_effect_validation`", "`integration_e2e_validation`", - "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", + "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", "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 journeys, navigation, states, viewport behavior", - "UI/UX task taxonomy", + "implemented UI states and viewport behavior", + "UI/visual task taxonomy", "story-local task granularity", - "`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", + "`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", "report a readiness blocker instead of generating an ambiguous task", - "Generate UI/UX tasks only from Required and Ready checklist rows", + "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", "Review evidence binding", "bounded repair permission", "final review scope taxonomy", - "`boundary`, `interface_contract`, `ui_ux`, `data_side_effect`, `behavior_contract`, and `sequence_consistency`", + "`boundary`, `interface_contract`, `visual`, `data_side_effect`, `behavior_contract`, `sequence_consistency`, and `asset_binding`", "boundary review", - "no implementation task changed `spec.md`, `contracts/`, readiness checklists, or UI/UX Specification Readiness", + "no implementation task changed `spec.md`, `contracts/`, readiness checklists, or Visual Fidelity 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) @@ -1211,14 +1581,29 @@ 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 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("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("planned `U` design object", cross_agent) self.assertIn("specific source, test, fixture, configuration, or receipt paths", cross_agent) @@ -1254,7 +1639,10 @@ def test_analyze_command_owns_vertical_consistency_contract(self) -> None: self.assertIn("{CORE_TEMPLATE}", analyze) self.assertIn("strategy: wrap", analyze) self.assertIn("vertical consistency", analyze) - self.assertIn("spec -> BDD/UIF intent -> contracts -> tasks", analyze) + self.assertIn( + "requirement gates -> BDD/UIF intent -> contracts -> behavior testability -> tasks", + analyze, + ) self.assertIn("spec.md user stories have BDD coverage", analyze) self.assertIn("BDD Given steps map to fixtures", analyze) self.assertIn("BDD When steps map to UIF events or API requests", analyze) @@ -1268,7 +1656,8 @@ def test_analyze_command_owns_vertical_consistency_contract(self) -> None: self.assertIn("behavior contracts cover scenarios, fixtures, and assertions", analyze) self.assertIn("tasks.md covers BDD, UIF, API, fixtures, and quickstart validation paths", analyze) self.assertIn("case coverage", analyze) - self.assertIn("Required case types in `checklists/behavior-testability.md`", analyze) + self.assertIn("Required case types in `checklists/behavior.md`", analyze) + self.assertIn("`behavior/behavior-testability.md` carries current spec/plan revisions", analyze) self.assertIn("case types are either covered or have `N/A or blocker` evidence", analyze) self.assertIn( "failure scenarios declare error code, failure feedback, and state invariant, rollback, or compensation assertion", @@ -1321,71 +1710,31 @@ def test_behavior_first_templates_exist_and_are_decoupled(self) -> None: self.assertIn("Feature:", BEHAVIOR_TEMPLATE_PATHS["behavior-bdd-draft-template"].read_text()) self.assertIn("Feature:", BEHAVIOR_TEMPLATE_PATHS["behavior-bdd-contract-template"].read_text()) - self.assertIn( - "Behavior Testability Checklist", - BEHAVIOR_TEMPLATE_PATHS["behavior-testability-checklist-template"].read_text(), - ) - behavior_checklist_template = BEHAVIOR_TEMPLATE_PATHS[ - "behavior-testability-checklist-template" + behavior_testability = BEHAVIOR_TEMPLATE_PATHS[ + "behavior-testability-template" ].read_text(encoding="utf-8") - self.assertIn("Case Coverage Matrix", behavior_checklist_template) - self.assertIn("one row per story or capability case type", behavior_checklist_template) - self.assertIn("Status: Required|Not Applicable|Unknown", behavior_checklist_template) - self.assertIn("| Case ID | Story/Capability | Case Type | Status | Source `spec.md` section | Blocking Item ID | Rationale |", behavior_checklist_template) - self.assertIn( - "Required case type must cite the source `spec.md` section", - behavior_checklist_template, - ) - self.assertIn( - "Each row must have a stable Case ID", - behavior_checklist_template, - ) - self.assertIn( - "Scenario IDs and `case_coverage_blockers` are assigned during `/speckit.plan`", - behavior_checklist_template, - ) - self.assertIn("Not Applicable requires rationale", behavior_checklist_template) - self.assertIn("Unknown must appear in Blocking Items", behavior_checklist_template) - self.assertIn("Non-Functional Requirement Readiness", behavior_checklist_template) - self.assertIn("Status: Required|Not Applicable|Unknown", behavior_checklist_template) - self.assertIn("Performance", behavior_checklist_template) - self.assertIn("Security and Privacy", behavior_checklist_template) - self.assertIn("Reliability and Recovery", behavior_checklist_template) - self.assertIn("Accessibility", behavior_checklist_template) - self.assertIn("Compliance and Auditability", behavior_checklist_template) - self.assertIn("Observability", behavior_checklist_template) - self.assertIn("Compatibility", behavior_checklist_template) - self.assertIn("Data Lifecycle", behavior_checklist_template) - 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("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("**Stage**: plan", behavior_testability) + self.assertIn("**Behavior Testability Status**: READY | BLOCKED", behavior_testability) + self.assertIn("| Case ID | Scenario ID | BDD Ref | UIF Ref | Fixture Ref | Assertion Ref |", behavior_testability) + self.assertIn("Task Derivation Matrix", behavior_testability) + for path in REQUIREMENT_TEMPLATE_PATHS.values(): + self.assertTrue(path.exists(), path) + behavior_gate = REQUIREMENT_TEMPLATE_PATHS[ + "requirement-behavior-gate-template" + ].read_text(encoding="utf-8") + nfr_gate = REQUIREMENT_TEMPLATE_PATHS["requirement-nfr-gate-template"].read_text( + encoding="utf-8" ) - self.assertIn( - "Required UI/UX requirements describe observable user outcomes rather than implementation details", - 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) - self.assertNotIn( - "No unchecked BDD readiness item blocks `/speckit.plan`", - behavior_checklist_template, + visual_gate = REQUIREMENT_TEMPLATE_PATHS[ + "requirement-visual-gate-template" + ].read_text(encoding="utf-8") + self.assertIn("Case Coverage Matrix", behavior_gate) + self.assertIn("`Required|Not Applicable|Unknown`", behavior_gate) + self.assertIn("NFR Coverage Matrix", nfr_gate) + self.assertIn("Visual Fidelity Evidence Matrix", visual_gate) + self.assertIn("**Status**: PASS | BLOCKED", visual_gate) + self.assertFalse( + (REPO_ROOT / "templates" / "behavior" / "behavior-testability-checklist.md").exists() ) self.assertFalse((REPO_ROOT / "templates" / "behavior" / "open-questions.json").exists()) self.assertFalse( @@ -1424,49 +1773,60 @@ def test_behavior_first_templates_exist_and_are_decoupled(self) -> None: ) self.assertIn('"intent": "state_invariant"', assertions_template) - def test_ui_ux_specification_readiness_contract(self) -> None: + def test_visual_fidelity_screenshot_evidence_gate_contract(self) -> None: command = CHECKLIST_COMMAND_PATH.read_text(encoding="utf-8") - template = BEHAVIOR_TEMPLATE_PATHS[ - "behavior-testability-checklist-template" + template = REQUIREMENT_TEMPLATE_PATHS[ + "requirement-visual-gate-template" ].read_text(encoding="utf-8") for term in ( - "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", + "Write visual readiness and the only Visual Fidelity Evidence Matrix to", + "`checklists/visual.md`", + "[blocker:product-decision]", + "[blocker:provider-evidence] [return:intake]", + "Provider blockers must not be converted into clarify questions", + "Do not call provider tools, rebuild intake evidence, parse provider or HTML", + "define screenshot comparison, visual diff, baseline capture, or", + "final visual review", + "Planning Readiness aggregate", ): self.assertIn(term, command) - self.assertNotIn("## UI/UX Coverage Matrix", command) - self.assertNotIn( - "| Requirement ID | Source `spec.md` Section | Applicability | Readiness |", - 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) for term in ( - "UI/UX Specification Readiness", - "UI/UX Coverage Matrix", - "Source `spec.md` section", - "Applicability", - "Readiness", - "States Covered", - "Responsive Coverage", - "Accessibility Coverage", - "Blocking Items", - "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", + "**Stage**: requirements", + "**Domain**: visual", + "**Gate**: planning-readiness", + "**Applicability**: APPLICABLE | NOT_APPLICABLE", + "**Status**: PASS | BLOCKED", + "Visual Fidelity Evidence Matrix", + "single visual planning-readiness record", + "Provider Evidence Dependency", + "Visual SSOT Refs", + "HTML SSOT Refs", + "Structured IR Refs", + "Other Evidence Refs", + "Readiness Input", + "Accepted Exception Refs", + "Unknown items become product-decision blockers", + "evidence gaps remain intake blockers and are never converted to clarification", + "Do not call provider tools, re-parse provider artifacts, define screenshot", + "comparison, visual diff, baseline capture, or final visual review", + "## Blocking Items", ): self.assertIn(term, template) self.assertEqual( len( re.findall( - r"^## UI/UX Coverage Matrix$", + r"^## Visual Fidelity Evidence Matrix$", template, flags=re.MULTILINE, ) @@ -1475,10 +1835,39 @@ def test_ui_ux_specification_readiness_contract(self) -> None: ) self.assertEqual( template.count( - "| Requirement ID | Source `spec.md` Section | Applicability | Readiness | States Covered | Responsive Coverage | Accessibility Coverage | Blocking Item ID |" + "| Visual Item ID | 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 | Accepted Exception Refs |" + ), + 1, + ) + self.assertEqual( + template.count( + "This is the single visual planning-readiness record" ), 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") @@ -1512,21 +1901,23 @@ 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, dispatch, Worker Prompt, and receipt rules are source-owned here", + "Runtime, shard, digest, path, asset binding, 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`", - "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", + "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", "Follow cross-agent protocol profile: `speckit.implement.persistent_handoff_orchestration`", "Manual Worker Queue", "validate_manifest_structure()", @@ -3462,7 +3853,7 @@ def test_validate_receipt_contract_accepts_behavior_evidence_references(self) -> RECEIPT_PATH, ) - def test_validate_receipt_contract_rejects_generic_ui_ux_evidence(self) -> None: + def test_validate_receipt_contract_rejects_generic_visual_evidence(self) -> None: handoff = minimal_handoff( shard_id="S01-ui-01", vertical_capability="ui", @@ -3475,12 +3866,12 @@ def test_validate_receipt_contract_rejects_generic_ui_ux_evidence(self) -> None: f"{FEATURE_PATH}/quickstart.md", ] handoff["task_text"] = [ - "T010 ui_acceptance for UI/UX Requirement ID UI-001 with Applicability Required and Readiness Ready" + "T010 ui_acceptance for Visual Item ID VUI-001 with Requirement Status Required and structured IR ref ir/refund.json" ] receipt_path = f"{HANDOFF_DIR}/results/S01-ui-01.json" handoff["task_status_update"]["receipt_path"] = receipt_path - with self.assertRaisesRegex(ValueError, "UI/UX requirement ID"): + with self.assertRaisesRegex(ValueError, "Visual Item ID"): validate_receipt_contract( handoff, minimal_receipt( @@ -3491,7 +3882,7 @@ def test_validate_receipt_contract_rejects_generic_ui_ux_evidence(self) -> None: receipt_path, ) - def test_validate_receipt_contract_accepts_ui_ux_evidence_references(self) -> None: + def test_validate_receipt_contract_accepts_visual_evidence_references(self) -> None: handoff = minimal_handoff( shard_id="S01-ui-01", vertical_capability="ui", @@ -3504,7 +3895,7 @@ def test_validate_receipt_contract_accepts_ui_ux_evidence_references(self) -> No f"{FEATURE_PATH}/quickstart.md", ] handoff["task_text"] = [ - "T010 ui_acceptance for UI/UX Requirement ID UI-001 with Applicability Required and Readiness Ready" + "T010 ui_acceptance for Visual Item ID VUI-001 with Requirement Status Required and structured IR ref ir/refund.json" ] receipt_path = f"{HANDOFF_DIR}/results/S01-ui-01.json" handoff["task_status_update"]["receipt_path"] = receipt_path @@ -3515,7 +3906,7 @@ def test_validate_receipt_contract_accepts_ui_ux_evidence_references(self) -> No shard_id="S01-ui-01", changed_paths=[f"{FEATURE_PATH}/src/ui/refund.tsx"], validation_evidence=[ - "UI/UX Requirement ID UI-001 verified against the accepted error state and quickstart.md#refund-ui" + "Visual Item ID VUI-001 Requirement Status Required verified with structured IR ref ir/refund.json and quickstart.md#visual-refund" ], ), receipt_path, @@ -3636,31 +4027,66 @@ def test_readme_contract(self) -> None: self.assertNotIn("core compatibility fixes", readme) self.assertIn("must formalize", readme) self.assertIn("N/A or blocker", readme) - self.assertIn("The preset has four goals:", readme) - self.assertIn("BDD readiness gate", readme) - self.assertIn("NFR readiness", 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("The preset has six goals:", readme) + self.assertIn("requirements, behavior, UX, security, NFR, and visual readiness", readme) + self.assertIn("runtime Planning Readiness aggregate", readme) + self.assertIn("Visual Fidelity Evidence Matrix", readme) + self.assertIn("behavior/behavior-testability.md", readme) + self.assertIn("Spec Kit CLI `>=0.12.7.dev0`", readme) + return + 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 Evidence Matrix", 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("visual requirements", readme) + self.assertIn("They cannot upgrade product semantics", readme) + self.assertIn("visual requirements", readme) + self.assertIn("Visual Fidelity Evidence Matrix", readme) + self.assertIn("source traceability", 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("explicit non-functional requirement declarations", readme) self.assertIn("Required, Not Applicable, or Unknown", readme) self.assertIn("missing or unverifiable NFR assumptions", readme) @@ -3668,6 +4094,17 @@ 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", @@ -3696,7 +4133,7 @@ def test_readme_contract(self) -> None: self.assertNotIn("run-orchestrated-implement.py", readme) self.assertNotIn("speckit-implement-handoff.py", readme) self.assertNotIn("--dry-run true --run-id manual", readme) - self.assertIn("Spec Kit CLI `>=0.8.10.dev0`", readme) + self.assertIn("Spec Kit CLI `>=0.12.7.dev0`", readme) self.assertIn("python3 -m pip install -r requirements-dev.txt", readme) self.assertIn("Preset CI Boundary", readme) self.assertIn("SPEC_KIT_FORK_PR_TOKEN", readme) @@ -3761,7 +4198,7 @@ def test_cross_agent_subagent_contract_document(self) -> None: self.assertTrue(CROSS_AGENT_SUBAGENTS_PATH.exists()) document = CROSS_AGENT_SUBAGENTS_PATH.read_text(encoding="utf-8") - self.assertLessEqual(len(document.splitlines()), 160) + self.assertLessEqual(len(document.splitlines()), 180) required_terms = [ "Follow cross-agent protocol profile: `speckit.implement.persistent_handoff_orchestration`", "Codex", @@ -3810,15 +4247,10 @@ 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 a relevant BDD scenario", + "validation_evidence references to relevant BDD scenario", "behavior assertion", "API contract", - "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`", + "quickstart path", "receipt path not equal to handoff `task_status_update.receipt_path`", "task_type: code_review", "review_conclusion", @@ -3857,32 +4289,40 @@ def test_extension_governance_document_contract(self) -> None: self.assertTrue(EXTENSION_GOVERNANCE_PATH.exists()) document = EXTENSION_GOVERNANCE_PATH.read_text(encoding="utf-8") - self.assertLessEqual(len(document.splitlines()), 160) + self.assertLessEqual(len(document.splitlines()), 180) required_terms = [ "Preset Extension Governance", "templates own stable artifact shapes", "commands own stage-local generation instructions", "structured JSON artifacts require schemas", "validators/", - "Do not put downstream prohibitions in upstream commands", - "Source acquisition, tool-specific extraction, normalization, authentication", - "consumes explicit product text and confirmed product decisions", + "An upstream stage may define the explicit consumption contract for its direct", + "Source intake artifacts belong in an extension, not this preset", + "External intake owns source capture", + "rendered HTML SSOT bundles", "Behavior-first extension rule", "BDD and UIF artifacts need independent templates", - "`/speckit.constitution`: constitution governance and project principles only", - "`/speckit.checklist`: checklist artifacts and BDD/NFR/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", + "`/speckit.constitution`: durable Constitution governance plus the separate", + "`/speckit.checklist`: requirements, behavior, UX, security, NFR, and visual requirement 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", + "single visual requirement-readiness record", + "`checklists/visual.md`", + "Provider evidence\ngaps remain intake blockers", + "accepted exception refs", + "The matrix must not define visual validation work", + "screenshot comparison, visual diff, baseline capture, or final visual review", + "Provider tools, provider execution, hooks, adapter scripts", + "External design extraction is not a clarification responsibility", "NFR readiness belongs in `spec.md` product requirements", - "`/speckit.plan`: Phase 0 behavior projection, planning artifacts, and formal contracts", - "`/speckit.tasks` owns implementation, UI/UX acceptance, contract validation, data-side-effect validation, integration/e2e validation, and code review task definition in `tasks.md`", + "`/speckit.plan`: Architecture-guided planning, Phase 0 behavior projection", + "`/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", - "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", + "must not invent validation strategy, visual validation work, lifecycle roles, requirements, contract updates, or wider scope during execution", "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", @@ -3901,18 +4341,17 @@ def test_extension_governance_document_contract(self) -> None: ] for term in forbidden_terms: self.assertNotIn(term, 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()) + 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, + ) 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 3c618404ef..691239b277 100644 --- a/presets/workflow-preset/validators/speckit_implement_contract.py +++ b/presets/workflow-preset/validators/speckit_implement_contract.py @@ -300,13 +300,16 @@ def _handoff_requires_traceable_validation_evidence(handoff: dict[str, Any]) -> "BehaviorScenarioInstance", "BDD scenario", "behavior assertion", - "UI/UX Requirement ID", - "UI-", - "UX-", - "ui_setup", - "ui_implementation", - "ui_accessibility", + "Visual Item ID", + "Requirement Status", + "visual_setup", + "visual_implementation", "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"): @@ -323,9 +326,15 @@ def _receipt_references_traceable_validation_evidence(receipt: dict[str, Any]) - "AST-", "BDD", "UIF-", - "UI-", - "UX-", - "UI/UX Requirement ID", + "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", "quickstart validation", "contracts/bdd/", "contracts/uif/", @@ -817,7 +826,8 @@ 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, UI/UX requirement ID, " + "behavior assertion, API contract, UIF path, Visual Item ID, " + "visual SSOT ref, HTML SSOT ref, structured IR ref, Client Asset Contract entry, " "or quickstart path" ) diff --git a/tests/test_presets.py b/tests/test_presets.py index b390a1716e..da98a9b54b 100644 --- a/tests/test_presets.py +++ b/tests/test_presets.py @@ -4650,7 +4650,7 @@ def test_workflow_preset_catalog_matches_manifest(self): assert catalog_updated_at >= datetime(2026, 6, 18, tzinfo=timezone.utc) assert entry["bundled"] is True - assert entry["version"] == "1.3.12" + assert entry["version"] == "2.0.0" assert entry["version"] == manifest["preset"]["version"] assert entry["repository"] == manifest["preset"]["repository"] assert entry["requires"]["speckit_version"] == manifest["requires"]["speckit_version"]