ai-delivery-workflow 0.5.1 → 0.7.0

package/skills/ai-delivery-validate-artifacts/SKILL.md

@@ -5,6 +5,8 @@ description: Validate AI delivery artifacts, registries, baselines, CSV relation
 
 # Validate Delivery Artifacts
 
+When validation finds an unresolved decision, read the version-scoped `confirmation-summary.yaml` and validate it with `../ai-delivery-orchestrate/scripts/confirmation-state.mjs`. Report the owning producer and keep the handoff blocked; validators do not decide business or risk acceptance.
+
 Validate contracts without repairing producer-owned content.
 
 ## Artifact Location
@@ -25,16 +27,19 @@ Require every workflow document to resolve under project `.workflow/` unless it
 4. Verify all association-table foreign keys and reject ad hoc multi-value cells where an association CSV is required.
 5. Verify required artifact sets for the target handoff.
 6. Verify baseline immutability, version increments, stale flags, and downstream impact declarations.
-7. Verify status transitions and human gates.
-8. Verify traceability from product goals through features, terminals, stories, acceptance criteria, Pages, Review Scenes, prototype elements, UI Mapping rows, UI components, frontend sources, Slices, tasks, tests, release items, and deployment evidence as applicable.
-9. For UI-bearing scope, validate the human tool-selection Gate, mandatory `UX-VS` and `UX-UI` human decisions, production-compatible runnable Prototype, stable Page and Review Scene identities, normalized terminal/trigger/route relations, Review Units, adjustment history, impact propagation, and aligned `product-prototype-reconciliation.yaml`. Validate that Workflow Manager evidence names the same checksummed target used by the Gate, uses its loopback origin and allowlisted review action, and contains no target revision drift; before `UX-VS`, its only content target is the Visual Reference, and afterward it is one exact Prototype revision.
-10. Validate every Prototype Page review receipt as an immutable checksummed YAML record under `.workflow/delivery/reviews/prototype-pages/<revision-id>/`. Reject an invalid or extra field, file-path/identity mismatch, actor, timestamp, receipt checksum, Prototype revision checksum, Page checksum, Scene checksum, or evidence checksum. Derive status from the current revision or its checksum-validated `previous_revision` ancestor chain, nearest ancestor first; reject inheritance from descendants or unrelated revisions. Carry forward only when the selected prior decision is approved and the complete Page checksum is identical; preserve a later changes-requested decision on that ancestor, and derive stale after any evidence change. Require the final Page receipt and approved `UX-UI` Gate decision to reference each other through the same actor, iteration, Prototype revision, and receipt checksum, and reject any later receipt unless a new pending `UX-UI` request exists.
-11. Verify that UI handoff, experience confirmation, architecture validation, test validation, planning, development, and verification all pin the same exact Prototype revision/checksum, source revision/checksum, review-bundle checksum, UI Mapping checksum, normalized catalog checksums, product reconciliation, experience-change checksum, review/impact checksums, and receipt checksums. Resolve every affected Page, Review Scene, UI component, frontend source, and acceptance criterion through explicit normalized foreign keys. Reject missing or conflicting references. Never infer relationships from file names or row order. Require downstream work to consume only `ready-for-development` changes.
-12. For every UI-bearing code handoff, validate the revision-bound `frontend-change-scope.yaml` checksum and its code root, non-empty frontend roots and extensions, shared component ownership, and file-only route registry ownership with the exact approved candidate-file SHA-256. Cross-check every active UI Mapping and ownership source against those roots and extensions; a declared source that would be skipped invalidates the scope. Run `ai-delivery frontend-guard verify-diff` with the handoff's fixed base and candidate head; require the independent Git diff to have current approved Page receipts and exact UI Mapping or scope coverage, and read changed route registries from the fixed candidate Git object rather than the mutable worktree. Reject Hook-only evidence, unmapped new or removed UI files, unapproved route-registry content, pending/changes-requested/stale Pages, and scope or revision drift.
-13. Before Candidate Assurance can pass a UI-bearing candidate, require successful `ui-acceptance plan` and `ui-acceptance verify` reports bound to the active attempt and immutable candidate checksum. Check exact Page/Scene/viewport coverage, pinned Playwright environment, visual diff counts and evidence, interaction and WCAG 2.2 AA checks, keyboard/focus/touch-target/text-overflow/responsive/recovery results, protocol evidence, Scenario Pack authority, and separate real backend evidence whenever Product Backend Mock rendered a Scene. Candidate checksum drift requires a new `04-implementation` candidate and Candidate Assurance attempt.
+7. For every `02-solution-design` handoff, validate the shared `product-impact-assessment.yaml`. Require a stable product-baseline binding, controlled decision, affected-asset IDs, return node, and checksums for every input/evidence reference. `product-update-required` and `clarification-required` are blocking until `01-product-shaping` supplies a valid aligned reconciliation and a successor product baseline; `no-impact` and `architecture-only` require explicit evidence that product scope, terminals, terminology, acceptance, and non-functional requirements are unchanged.
+8. Verify status transitions and human gates.
+9. Verify traceability from product goals through features, terminals, stories, acceptance criteria, Pages, Review Scenes, prototype elements, UI Mapping rows, UI components, frontend sources, Slices, tasks, tests, release items, and deployment evidence as applicable.
+10. For UI-bearing scope, validate the human tool-selection Gate, mandatory `UX-VS` and `UX-UI` human decisions, production-compatible runnable Prototype, stable Page and Review Scene identities, normalized terminal/trigger/route relations, Review Units, adjustment history, impact propagation, and aligned `product-prototype-reconciliation.yaml`. Validate that Workflow Manager evidence names the same checksummed target used by the Gate, uses its loopback origin and allowlisted review action, and contains no target revision drift; before `UX-VS`, its only content target is the Visual Reference, and afterward it is one exact Prototype revision.
+11. Validate every Prototype Page review receipt as an immutable checksummed YAML record under `.workflow/delivery/reviews/prototype-pages/<revision-id>/`. Reject an invalid or extra field, file-path/identity mismatch, actor, timestamp, receipt checksum, Prototype revision checksum, Page checksum, Scene checksum, or evidence checksum. Derive status from the current revision or its checksum-validated `previous_revision` ancestor chain, nearest ancestor first; reject inheritance from descendants or unrelated revisions. Carry forward only when the selected prior decision is approved and the complete Page checksum is identical; preserve a later changes-requested decision on that ancestor, and derive stale after any evidence change. Require the final Page receipt and approved `UX-UI` Gate decision to reference each other through the same actor, iteration, Prototype revision, and receipt checksum, and reject any later receipt unless a new pending `UX-UI` request exists.
+12. Verify that UI handoff, experience confirmation, architecture validation, test validation, planning, development, and verification all pin the same exact Prototype revision/checksum, source revision/checksum, review-bundle checksum, UI Mapping checksum, normalized catalog checksums, product reconciliation, product impact assessment, experience-change checksum, review/impact checksums, and receipt checksums. Resolve every affected Page, Review Scene, UI component, frontend source, and acceptance criterion through explicit normalized foreign keys. Reject missing or conflicting references. Never infer relationships from file names or row order. Require downstream work to consume only `ready-for-development` changes.
+13. For every UI-bearing code handoff, validate the revision-bound `frontend-change-scope.yaml` checksum and its code root, non-empty frontend roots and extensions, shared component ownership, and file-only route registry ownership with the exact approved candidate-file SHA-256. Cross-check every active UI Mapping and ownership source against those roots and extensions; a declared source that would be skipped invalidates the scope. Run `ai-delivery frontend-guard verify-diff` with the handoff's fixed base and candidate head; require the independent Git diff to have current approved Page receipts and exact UI Mapping or scope coverage, and read changed route registries from the fixed candidate Git object rather than the mutable worktree. Reject Hook-only evidence, unmapped new or removed UI files, unapproved route-registry content, pending/changes-requested/stale Pages, and scope or revision drift.
+14. Before Candidate Assurance can pass a UI-bearing candidate, require successful `ui-acceptance plan` and `ui-acceptance verify` reports bound to the active attempt and immutable candidate checksum. Check exact Page/Scene/viewport coverage, pinned Playwright environment, visual diff counts and evidence, interaction and WCAG 2.2 AA checks, keyboard/focus/touch-target/text-overflow/responsive/recovery results, protocol evidence, Scenario Pack authority, and separate real backend evidence whenever Product Backend Mock rendered a Scene. Candidate checksum drift requires a new `04-implementation` candidate and Candidate Assurance attempt.
 
 ## Output
 
 Report findings first with severity, artifact ID, location, violated rule, evidence, and owning producer. Return one decision: `valid`, `invalid`, or `blocked`. Never rewrite an invalid artifact while acting as validator; route it to the producer.
 
 Read [artifact-contract.md](references/artifact-contract.md) for required metadata, statuses, formats, and handoff sets.
+
+Validate any present `confirmation-summary.yaml` with `confirmation-state.mjs validate` and report its frontier and blocked proposals. This check is read-only and additive; it never mutates the summary or formal state.

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

@@ -26,6 +26,7 @@ For visual or interactive terminals, require:
 - 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;
+- a checksummed shared `product-impact-assessment.yaml` for any `02-solution-design` handoff, with a resolved or superseded result before development readiness;
 - an aligned `product-prototype-reconciliation.yaml` and a `ui-handoff.yaml` whose development readiness is `ready-for-development`;
 - 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;
@@ -35,7 +36,7 @@ For visual or interactive terminals, require:
 
 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 tool selections `valid/selected`, all applicable staged Gate decisions approved by a human, Prototype impact assessments `valid/ready-for-finalization`, and shared product impact assessments `resolved` or `superseded`. 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 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.
 

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

@@ -5,6 +5,8 @@ description: Independently verify an immutable iteration or release candidate ag
 
 # Verify Candidate
 
+When candidate assurance needs exception, residual-risk, or release-recommendation input, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`. Do not turn missing evidence into a confirmation; unresolved records keep the candidate `blocked`.
+
 Validate the assembled system independently. Never modify product code, migrations, infrastructure, or configuration while acting as verifier.
 
 ## Artifact Location
@@ -27,9 +29,9 @@ Require `scope: iteration` or `scope: release`. For iteration scope, verify one
 
 ## Preflight
 
-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 `.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. Validate `AGENTS.md`, `CODEBASE_GUIDE.md`, and `docs/CODEBASE_INDEX.md` against that same candidate commit, retaining missing/invalid/stale findings as candidate evidence. A stale handbook/index cannot be presented as candidate functionality passing; route it to implementation or an explicit maintainer acceptance.
 
-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.
+Read `candidate-manifest.yaml` first and require it to pin the exact ready UI handoff, aligned `product-prototype-reconciliation.yaml`, resolved or superseded `product-impact-assessment.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, product impact assessment, 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.
 
@@ -54,6 +56,7 @@ Produce:
 - specialty test results as applicable;
 - untested scope and residual risks;
 - one candidate decision: `pass`, `fail`, or `blocked`;
+- codebase handbook/index identity and structural validation receipt;
 - iteration closeout recommendation or release recommendation, matching the selected scope.
 
 Read [candidate-verification-contract.md](references/candidate-verification-contract.md) and use `assets/verification-template/` for reports.
@@ -61,3 +64,5 @@ Read [candidate-verification-contract.md](references/candidate-verification-cont
 ## Handoff
 
 Route failures to their producer. Hand a passing iteration candidate to `$ai-delivery-close-version`. Hand a passing release candidate back to `$ai-delivery-orchestrate-release` for `R06-release-preparation`.
+
+Read and validate the iteration confirmation summary. Candidate assurance may ask only about explicit exceptions, residual-risk acceptance, or release recommendation; unresolved product, architecture, or terminology decisions return to their owning node and keep the candidate blocked.

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

@@ -16,7 +16,7 @@ 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 `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.
+For UI-bearing scope, require `candidate-manifest.yaml` to pin one exact ready UI handoff, aligned product reconciliation, resolved or superseded product impact assessment, 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
 

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

@@ -5,6 +5,10 @@ description: Independently verify an R08 production deployment, decide release s
 
 # Verify Production
 
+Apply the shared confirmation protocol from `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`; production exceptions and residual-risk acceptance must be recorded in the confirmation summary before closeout.
+
+Record production verification exceptions, rollback acceptance, and residual-risk decisions in the release confirmation summary; link them to the immutable deployment evidence before closeout.
+
 Keep deployment execution separate from release success.
 
 ## Artifact Location