ai-delivery-workflow 0.2.2 → 0.4.0

package/skills/ai-delivery-validate-artifacts/references/artifact-contract.md

@@ -15,29 +15,29 @@ Record artifact ID, type, version, iteration ID, status, producer skill, input a
 
 Use UTF-8 CSV, fixed headers, stable IDs, controlled enums, parser-safe quoting, and no merged cells, colors, formulas, or delimiter-packed relationship fields.
 
-## Prototype Handoff Set
+## Prototype Handoff
 
 For visual or interactive terminals, require:
 
-- a versioned prototype set with one member manifest per independently versioned review bundle;
-- a valid human tool-selection receipt per member, with one actually available authoring tool selected before source authoring;
-- stable page, canvas, prototype-file, and file-terminal catalogs with normalized relationships;
-- an executable low-fidelity prototype with a passing human `UX-LF` receipt;
-- a checksummed visual system, design tokens, selected UI framework, component-state matrix, and passing human `UX-VS` receipt;
+- one exact immutable Prototype revision with checksummed source, review bundle, Review Shell, Visual Standard, review evidence, and normalized catalogs;
+- a valid human tool-selection receipt for the Prototype, with one actually available authoring tool selected before source authoring;
+- stable terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs with normalized relationships;
+- a production-compatible runnable Prototype with passing human `UX-VS` and `UX-UI` receipts;
+- a checksummed design-reference selection, runnable HTML Visual Reference and manifest, visual system, design tokens, selected UI framework/component system/icon library, pinned component registry/configuration, selected components, checksummed local adaptations, component-state matrix, license/upstream attribution, complete scoped design-input checksum list, an unexpired human `UX-VS` receipt, and a passing `ai-delivery visual-standard validate` report;
 - a runnable formal UI with a passing human `UX-UI` receipt;
 - checksummed review sessions, comments, complete adjustment log, experience/requirement change sets, and impact assessment;
 - an aligned `product-prototype-reconciliation.yaml` and a `ui-handoff.yaml` whose development readiness is `ready-for-development`;
-- each member manifest with immutable source revision, SHA-256 review bundle, and checksums for linked traceability and state catalogs;
-- normalized feature/acceptance/terminal/flow/page/canvas/file/screen/state-to-prototype-element traceability;
-- one source confirmation per set member against product and initial architecture inputs;
-- one architecture validation receipt per set member before architecture reconciliation exits;
-- one test validation receipt per relevant set member before test design exits.
+- the Prototype revision with immutable source revision, SHA-256 source and review-bundle tree checksums, and checksums for every linked catalog;
+- normalized feature/acceptance/terminal/flow/Page/Review Scene/state-to-prototype-element traceability;
+- one source confirmation for the Prototype revision against product and initial architecture inputs;
+- one architecture validation receipt for the Prototype revision before architecture reconciliation exits;
+- one test validation receipt for the Prototype revision before test design exits.
 
-Validate main page IDs against `^P[0-9]{2,}$` and child IDs against `^P[0-9]{2,}-[0-9]{2,}$`; require child `parent_page_id` to match its main-page prefix. Verify derived display labels, uniqueness, no ID reuse, and `retired` preservation. Reject third-level page IDs. Require each canvas to contain exactly one main-page family. Require file splits when terminal, authoring tool, permission, freeze/review lifecycle, or independent delivery boundaries differ.
+Validate main Page IDs against `^P[0-9]{2,}$` and child IDs against `^P[0-9]{2,}-[0-9]{2,}$`; require child `parent_page_id` to match its main-page prefix. Verify derived display labels, uniqueness, no ID reuse, and `retired` preservation. Reject third-level Page IDs. Verify that every Review Scene belongs to one Page, every trigger targets an explicit scene, and every prototype or production route resolves through normalized foreign keys.
 
 Require tool selections `valid/selected`, all applicable staged Gate decisions approved by a human, and impact assessments `valid/ready-for-finalization`. Require each Gate's latest session `approved`, every comment terminal, every adjustment revision-linked, every semantic impact reconciled with product and rebaselined before final freeze, and the approved formal UI revision to match the final manifest. Only a genuinely non-visual terminal may mark these visual Gates `not-applicable`, with product-terminal evidence and rationale.
 
-Require the same set identity/checksum and complete relevant member identities, revisions, bundle/management/review/impact checksums, and receipt checksums in all downstream references. Require source confirmations `valid/confirmed-for-handoff` and architecture/test receipts `valid/accepted`. Reject ambiguous set cardinality, mutable URL-only evidence, missing members or receipts, checksum mismatches, silent downstream edits, and confirmed prototypes with blocking issues.
+Require the same Prototype revision/checksum, source revision/checksum, review-bundle checksum, UI Mapping checksum, normalized catalog checksums, review/impact checksums, and receipt checksums in all downstream references. Require source confirmation `valid/confirmed-for-handoff` and architecture/test receipts `valid/accepted`. Resolve affected Page, Review Scene, UI component, frontend source, and acceptance identities from explicit UI Mapping rows. Reject ambiguous or conflicting references, mutable URL-only evidence, missing receipts, checksum mismatches, silent downstream edits, and confirmed Prototypes with blocking issues. Never infer any relationship from a file name or row order.
 
 ## Status Rules
 

package/skills/ai-delivery-verify-candidate/SKILL.md

@@ -9,7 +9,11 @@ Validate the assembled system independently. Never modify product code, migratio
 
 ## Artifact Location
 
-Write iteration-scope outputs to `.workflow/iterations/<version-id>/11-candidate-verification/` and release-scope outputs to `.workflow/releases/<release-id>/R05-release-verification/`. Candidate binaries and images remain immutable in their artifact stores and are referenced by digest.
+Write iteration-scope outputs to `.workflow/iterations/<version-id>/05-candidate-assurance/` and release-scope outputs to `.workflow/releases/<release-id>/R05-release-verification/`. Candidate binaries and images remain immutable in their artifact stores and are referenced by digest.
+
+## Development Node
+
+Iteration scope runs inside `05-candidate-assurance` against the bound candidate recorded when the node attempt starts. Pass that exact `candidate_id` when registering assurance artifacts; never retarget an active attempt. If any repair changes code, migration, configuration, IaC, dependency, build, or digest, return to `04-implementation`, select a new immutable candidate, and begin a new Candidate Assurance attempt. Release scope remains in `R05-release-verification`.
 
 ## Task State
 
@@ -25,14 +29,17 @@ Require `scope: iteration` or `scope: release`. For iteration scope, verify one
 
 Read `.workflow/config/workspace.yaml` first. Resolve and verify every `repo_id`, `code_commit`, optional `code_tag`, `source_path`, and SHA-256 against the configured nested code repository; stop when a candidate references the workflow repository or another code repository.
 
-Read the candidate manifest, approved baselines, exact ready UI handoff, aligned product reconciliation, experience/requirement change sets, task-to-experience-change traceability, exact prototype set and relevant member manifests/review bundles, tool-selection and page/canvas/file catalogs, interaction/component-state contracts, review/impact records, prototype source confirmations, architecture and test receipts, overall test strategy, public iteration test contract, prior defects, actual change inventory, applicable standards, test environment evidence, and candidate commit and artifact digests. Require source confirmations `valid/confirmed-for-handoff` and architecture/test receipts `valid/accepted`. Stop if the environment or candidate is mutable, any relevant member receipt is missing or non-passing, any planned `ready-for-development` change lacks implementation evidence, or any handoff/set/member identity, management/review/impact checksum, or review-bundle checksum is mismatched.
+Read `candidate-manifest.yaml` first and require it to pin the exact ready UI handoff, aligned `product-prototype-reconciliation.yaml`, Prototype revision, source revision, source tree, review bundle, UI Mapping, and task traceability identities/checksums for UI-bearing scope. Then read the approved baselines, experience/requirement change sets, task-to-experience-change traceability, normalized terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs, interaction/component-state contracts, review/impact records, prototype source confirmation, architecture and test receipts, overall test strategy, public iteration test contract, prior defects, actual change inventory, applicable standards, test environment evidence, and candidate commit and artifact digests. Require source confirmation `valid/confirmed-for-handoff` and architecture/test receipts `valid/accepted`. Stop if the environment or candidate is mutable, a candidate binding field, required receipt, or catalog reference is missing or non-passing, any planned `ready-for-development` change lacks implementation evidence, or any Prototype revision, UI Mapping, handoff, reconciliation, traceability, review/impact, source, or review-bundle identity/checksum conflicts. Never infer a relationship from a file name or catalog order.
+
+For UI-bearing scope, also require the candidate manifest to pin the exact frozen Mock Scenario Pack. Create `ui-acceptance-request.yaml`, run `ai-delivery ui-acceptance plan`, execute its exact Scene/viewport matrix in the pinned Playwright environment, write `ui-acceptance-results.yaml` plus checksummed evidence, and run `ai-delivery ui-acceptance verify` before deciding. Use approved Visual Standard breakpoints or the `390x844`, `768x1024`, and `1440x900` defaults with default maximum diff ratio `0.001`. Produce exact-viewport PNGs and a transparent RGBA changed-pixel mask, plus deterministic JSON protocol envelopes matching every request selector and response in the plan's frozen contract expectation. This work remains inside `05-candidate-assurance`. A Product Backend Mock can drive deterministic rendering but never satisfies real backend or end-to-end acceptance; bind the exact candidate, non-Mock environment, immutable deployment digest, contract result, and end-to-end result in separate real product backend evidence when the plan requires it.
 
 ## Plan Independent Verification
 
 1. Analyze changed and adjacent risks without relying only on developer-authored tests.
-2. Derive additional edge, negative, cross-component, end-to-end, exploratory, regression, security, performance, accessibility, compatibility, migration, recovery, and page/canvas/file/element-level prototype-conformance work as applicable.
-3. Create only test roles justified by risk. Keep every role independent from implementation.
-4. Invoke `$ai-delivery-execute-test` for each test work package.
+2. Resolve affected Pages, Review Scenes, UI components, frontend sources, and acceptance criteria through the pinned UI Mapping, then derive additional edge, negative, cross-component, end-to-end, exploratory, regression, security, performance, accessibility, compatibility, migration, recovery, and mapped prototype-conformance work as applicable.
+3. For each affected UI Scene, execute deterministic rendering and interaction at every approved breakpoint. Compare against the exact Prototype with the approved pixel ratio and retain reviewable prototype/candidate/diff images. Block on WCAG 2.2 AA, keyboard, focus, touch-target, text-overflow, responsive, recovery, protocol, or Mock authority failures.
+4. Create only test roles justified by risk. Keep every role independent from implementation.
+5. Invoke `$ai-delivery-execute-test` for each test work package.
 
 ## Decide
 
@@ -42,7 +49,7 @@ Produce:
 
 - independent test cases and automation;
 - execution logs and evidence;
-- requirement, feature, experience-change, page, canvas, prototype-file/element, risk, and test coverage matrices;
+- requirement, feature, experience-change, Page, Review Scene, prototype-element, UI Mapping, UI component, frontend-source, acceptance, risk, and test coverage matrices;
 - defect CSV with severity and reproduction evidence;
 - specialty test results as applicable;
 - untested scope and residual risks;

package/skills/ai-delivery-verify-candidate/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Verify Candidate"
-  short_description: "Independently verify a release candidate and route failures"
+interface:
+  display_name: "Verify Candidate"
+  short_description: "Independently verify a release candidate and route failures"
   default_prompt: "Use $ai-delivery-verify-candidate to verify the current candidate and its repository identity."

package/skills/ai-delivery-verify-candidate/assets/verification-template/ui-acceptance-request.yaml

@@ -0,0 +1,19 @@
+schema_version: 1
+artifact_type: ui-acceptance-request
+iteration_id: ITER-0001
+candidate_id: CANDIDATE-0001
+node_attempt: 1
+experience_ref: .workflow/experience
+prototype_revision_ref: prototype/revisions/PROTOTYPE-REVISION-0001/prototype-revision.yaml
+mock_scenario_pack_ref: mock-scenario-packs/MOCK-SCENARIO-PACK-0001.yaml
+test_strategy:
+  ref: .workflow/iterations/ITER-0001/03-delivery-readiness/test-strategy.yaml
+  algorithm: sha256
+  checksum: REPLACE_WITH_SHA256
+runner:
+  engine: playwright
+  package_version: REPLACE_WITH_EXACT_VERSION
+  browser: chromium
+  browser_version: REPLACE_WITH_EXACT_VERSION
+  environment_image: REPLACE_WITH_PINNED_IMAGE
+  environment_digest: sha256:REPLACE_WITH_64_HEX_DIGEST

package/skills/ai-delivery-verify-candidate/assets/verification-template/ui-acceptance-results.yaml

@@ -0,0 +1,53 @@
+schema_version: 1
+artifact_type: ui-acceptance-results
+iteration_id: ITER-0001
+status: pending
+decision: blocked
+plan_checksum: REPLACE_WITH_SHA256
+candidate:
+  candidate_id: CANDIDATE-0001
+  manifest_checksum: REPLACE_WITH_SHA256
+  node_attempt: 1
+prototype_revision:
+  artifact_id: PROTOTYPE-REVISION-0001
+  checksum: REPLACE_WITH_SHA256
+  source_revision: REPLACE_WITH_IMMUTABLE_SOURCE_REVISION
+  review_bundle_checksum: REPLACE_WITH_SHA256
+  ui_mapping_checksum: REPLACE_WITH_SHA256
+mock_scenario_pack:
+  artifact_id: MOCK-SCENARIO-PACK-0001
+  checksum: REPLACE_WITH_SHA256
+runner:
+  engine: playwright
+  package_version: REPLACE_WITH_EXACT_VERSION
+  browser: chromium
+  browser_version: REPLACE_WITH_EXACT_VERSION
+  environment_image: REPLACE_WITH_PINNED_IMAGE
+  environment_digest: sha256:REPLACE_WITH_64_HEX_DIGEST
+mock_boundary:
+  product_backend_mock_used_for_rendering: false
+  product_backend_mock_accepted_as_real_backend_evidence: false
+real_product_backend_acceptance:
+  status: pending
+  source: real-product-backend
+  candidate:
+    candidate_id: CANDIDATE-0001
+    manifest_checksum: REPLACE_WITH_SHA256
+    node_attempt: 1
+  environment:
+    environment_id: REPLACE_WITH_NON_MOCK_ENVIRONMENT_ID
+    deployment_ref: REPLACE_WITH_IMMUTABLE_DEPLOYMENT_REF
+    deployment_digest: sha256:REPLACE_WITH_64_HEX_DIGEST
+    product_backend_mock_enabled: false
+  evidence:
+    ref: .workflow/iterations/ITER-0001/05-candidate-assurance/real-product-backend.json
+    algorithm: sha256
+    checksum: REPLACE_WITH_SHA256
+candidate_assurance:
+  node: 05-candidate-assurance
+  node_attempt: 1
+  candidate_id: CANDIDATE-0001
+# One result is required for every plan execution. Every evidence object uses ref/algorithm/checksum.
+# Visual evidence uses exact-viewport PNGs; diff.png is an RGBA mask (alpha 0 unchanged, alpha >0 changed).
+# Protocol request/response evidence is JSON exactly matching the frozen expectation emitted by plan.
+executions: []

package/skills/ai-delivery-verify-candidate/references/candidate-verification-contract.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-Require `iteration` or `release`. Iteration scope verifies one planned-version candidate for `12-version-closeout`. Release scope verifies the exact `R04-release-candidate`, selected version closure, release material index, environment/configuration snapshot, migrations, rollback compatibility, and target tag before R06.
+Require `iteration` or `release`. Iteration scope writes under `05-candidate-assurance`, verifies the exact candidate bound to that node attempt, and produces evidence for `06-version-closeout`. Every registered iteration assurance artifact carries the bound `candidate_id`; candidate-changing repair requires a new candidate and node attempt. Release scope verifies the exact `R04-release-candidate`, selected version closure, release material index, environment/configuration snapshot, migrations, rollback compatibility, and target tag before R06.
 
 ## Test Work Packages
 
@@ -16,7 +16,15 @@ Create test types only when justified by changed or adjacent risk.
 
 Return `pass` only when mandatory gates pass, blocking defects are absent, required coverage is evidenced, and untested scope is acceptable under approved policy. Return `fail` for candidate defects and `blocked` for unavailable prerequisites.
 
-For UI-bearing scope, require one exact ready UI handoff, aligned product reconciliation, experience-change set, prototype-set identity/checksum, and a complete relevant member set across manifests, tool-selection and page/canvas/file catalogs, review/impact records, source confirmations, architecture receipts, test receipts, iteration plan, work packages, and candidate traceability. Verify every planned `experience_change_id` has the declared implementation action and independent behavior, visual-regression, responsive, and accessibility evidence as applicable. Verify matching management/review/impact checksums and applicable page/canvas/file/element identities and states through every delivered terminal. Route requirement conflicts to product, prototype defects to experience, feasibility conflicts to architecture, testability gaps to test design, and implementation differences to development.
+For UI-bearing scope, require `candidate-manifest.yaml` to pin one exact ready UI handoff, aligned product reconciliation, Prototype revision/checksum, source revision/checksum, review-bundle checksum, UI Mapping checksum, and both task traceability checksums. Verify these bindings against the experience-change set, normalized catalogs, review/impact records, source confirmation, architecture receipt, test receipt, iteration plan, work packages, and candidate traceability before deriving tests. Resolve every affected Page, Review Scene, UI component, frontend source, and acceptance criterion from the pinned UI Mapping. Verify every planned `experience_change_id` has the declared implementation action and independent behavior, visual-regression, responsive, and accessibility evidence as applicable. Verify matching references and checksums through every delivered terminal; reject missing or conflicting candidate fields or references and never infer relationships from file names or row order. Route requirement conflicts to product, prototype defects to experience, feasibility conflicts to architecture, testability gaps to test design, and implementation differences to development.
+
+## UI Acceptance
+
+UI Acceptance is mandatory inside iteration `05-candidate-assurance`; it is not another formal node. The candidate manifest pins the frozen Mock Scenario Pack in addition to the Prototype and UI Mapping. Run `ai-delivery ui-acceptance plan <workspace> --request <request>` before browser execution, then `ai-delivery ui-acceptance verify <workspace> --request <request> --results <results>` before a passing decision. Both commands are read-only.
+
+The plan must bind the active node attempt, exact immutable candidate manifest checksum, approved unexpired Visual Standard whose checksum is identical to the frozen Prototype revision, frozen Prototype revision, current approved Page receipts, candidate traceability, complete UI Mapping, frozen Scenario Pack, approved test strategy, and exact Playwright/browser/image versions. Revalidate the Scenario Pack candidate checksum, human confirmation, Prototype binding, mapping, protocol contracts, and checksummed Microcks admin export artifacts instead of trusting its status field. It expands every affected Review Scene across the approved Visual Standard breakpoints; absent an approved override, use `390x844`, `768x1024`, and `1440x900`, with `max_diff_pixel_ratio: 0.001`.
+
+The results must cover the plan exactly and bind checksummed prototype/candidate/diff PNG screenshots, deterministic fixture and Scenario identity, interactions, WCAG 2.2 AA with no violations, keyboard, focus, touch-target, text-overflow, responsive, recovery, and protocol request/response evidence. Prototype and candidate PNG dimensions equal the exact viewport; the diff is a non-interlaced 8-bit RGBA mask where transparent pixels are unchanged and non-transparent pixels are changed. Decode the PNGs, compare prototype and candidate pixels, require the mask to identify the same pixels, and recompute changed-pixel counts and ratio independently. Protocol evidence is deterministic JSON equal to the request and response expectation derived from both the frozen approved contract and its checksummed Microcks admin export artifact, including path/query/header dispatcher values and a named request body when the contract uses them. External Dependency Mock use requires explicit approval in the test strategy. Product Backend Mock may render a Scene but is always marked ineligible as real backend or end-to-end evidence; require a separate checksummed `real-product-backend` result whenever it was used. That result and its JSON evidence bind the exact candidate, a named non-Mock environment, immutable deployment digest, `product_backend_mock_enabled: false`, and passing contract plus end-to-end checks. Any candidate manifest checksum change invalidates the plan, returns work to `04-implementation`, selects a new immutable candidate, and starts a new Candidate Assurance attempt.
 
 ## Independence
 

package/skills/ai-delivery-verify-production/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Verify Production"
-  short_description: "Verify production health and trigger image-based rollback"
+interface:
+  display_name: "Verify Production"
+  short_description: "Verify production health and trigger image-based rollback"
   default_prompt: "Use $ai-delivery-verify-production to verify production and advance only the configured code repository when successful."

package/skills/ai-delivery-design-experience/assets/experience-template/low-fidelity-confirmation.yaml

@@ -1,32 +0,0 @@
-artifact_id: LOW-FIDELITY-CONFIRMATION-0001
-artifact_type: low-fidelity-interaction-confirmation
-version: 1
-iteration_id: ITER-0001
-status: pending
-producer_skill: ai-delivery-design-experience
-prototype_artifact_id: PROTOTYPE-0001
-prototype_fidelity: low-fidelity-interactive
-interaction_runtime: executable
-source_revision: LF-REVISION-0001
-review_entrypoint: prototype/low-fidelity/index.html
-interaction_contract_ref: interaction-contract.csv
-interaction_contract_checksum: REPLACE_WITH_SHA256
-experience_change_set_ref: experience-change-set.csv
-experience_change_set_checksum: REPLACE_WITH_SHA256
-checks:
-  executable_entrypoint: pending
-  layout_coverage: pending
-  interaction_coverage: pending
-  state_changes: pending
-  validation_and_errors: pending
-  responsive_behavior: pending
-  no_dead_controls: pending
-human_approval:
-  required: true
-  approver: null
-  decided_at: null
-  decision: pending
-  approved_source_revision: null
-decision: pending
-blocking_issues: []
-evidence: []