ai-delivery-workflow 0.2.2

package/skills/ai-delivery-review-change/references/review-contract.md

@@ -0,0 +1,20 @@
+# Change Review Contract
+
+## Severity
+
+- `critical`: likely production compromise, data loss, or inability to release safely.
+- `high`: incorrect required behavior, security boundary failure, or material architecture violation.
+- `medium`: meaningful defect or maintainability risk that should block this package.
+- `low`: non-blocking improvement supported by an approved source.
+
+## Finding Shape
+
+Record finding ID, severity, title, file and line, evidence, violated artifact or standard ID, impact, and required correction.
+
+## Decision
+
+Return `pass` only when no blocking findings remain and required checks ran. Return `fail` for confirmed blocking findings and `blocked` when evidence or execution prerequisites are missing.
+
+Do not broaden the change under review, author replacement code, or approve your own implementation context.
+
+For UI-bearing work, pin the UI handoff, aligned product reconciliation, experience-change set, and task mapping checksums. Report missing, extra, or incorrectly actioned `experience_change_id` rows as blocking specification findings.

package/skills/ai-delivery-triage-failure/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ai-delivery-triage-failure
+description: Classify delivery and test failures by root owning stage and create evidence-backed return routes. Use for failed tests, environment failures, ambiguous requirements, design omissions, architecture constraints, planning gaps, release mismatches, deployment failures, or production verification incidents.
+---
+
+# Triage Failure
+
+Classify ownership without fixing the defect.
+
+## Artifact Location
+
+Write every triage report, defect route, evidence index, and workflow document produced by this skill under project `.workflow/`, defaulting version-scoped outputs to `.workflow/iterations/<iteration-id>/<node-id>/`. Raw external evidence may remain in controlled systems only when immutable references and checksums are recorded in `.workflow/`.
+
+## Task State
+
+1. Invoke `$ai-delivery-checkpoint-task` before preflight to recover or initialize the task snapshot.
+2. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
+3. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+
+## Workflow
+
+1. Preserve the candidate, environment, input, command, expected result, actual result, logs, and timestamps.
+2. Reproduce or establish why reproduction is blocked.
+3. Identify the earliest source artifact whose correction would prevent the failure.
+4. Assign one primary route and any impacted downstream artifacts.
+5. Avoid routing every symptom to development.
+
+Use these primary routes:
+
+- ambiguous or contradictory behavior: product definition;
+- missing or incorrect interaction state: experience design;
+- infeasible boundary, contract, quality target, or migration model: architecture;
+- omitted or incorrectly ordered slice: iteration planning;
+- invalid seam, oracle, case, data, or environment requirement: test design;
+- product code or implementation defect: development;
+- CI/CD, environment, IaC, configuration, observability, or backup defect: platform preparation;
+- incomplete or mismatched release inventory: release preparation;
+- execution deviation from an approved package: deployment;
+- invalid verification signal or threshold: production verification.
+
+## Output
+
+Create a stable defect ID, severity, evidence, root-owner stage, affected artifact IDs, required correction, required revalidation scope, and status. Mark impacted downstream artifacts stale; do not alter their content.
+
+Read [failure-routing-contract.md](references/failure-routing-contract.md).

package/skills/ai-delivery-triage-failure/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Triage Test Failure"
+  short_description: "Classify test failures and route them to the owning stage"
+  default_prompt: "Use $ai-delivery-triage-failure to classify and route the observed failure."

package/skills/ai-delivery-triage-failure/references/failure-routing-contract.md

@@ -0,0 +1,13 @@
+# Failure Routing Contract
+
+`defects.csv`:
+
+`defect_id,candidate_id,title,severity,failure_class,root_stage,evidence_ref,required_correction,revalidation_scope,status`
+
+`defect-artifacts.csv`:
+
+`defect_id,artifact_id,impact_type`
+
+Use failure classes `product`, `experience`, `architecture`, `planning`, `test-design`, `implementation`, `platform`, `release`, `deployment`, `production-verification`, `flaky`, and `blocked`.
+
+Route to the earliest incorrect source, not the latest visible symptom. Mark all dependent artifacts stale but leave correction to the owning producer.

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

@@ -0,0 +1,37 @@
+---
+name: ai-delivery-validate-artifacts
+description: Validate AI delivery artifacts, registries, baselines, CSV relationships, versions, approvals, standards pins, and handoff contracts. Use before every stage transition, after an artifact change, when workflow state is inconsistent, or when a downstream skill rejects its inputs.
+---
+
+# Validate Delivery Artifacts
+
+Validate contracts without repairing producer-owned content.
+
+## Artifact Location
+
+Require every workflow document to resolve under project `.workflow/` unless it is an explicit exception in `STD-ARTIFACT-PATH-001`. Write validation reports under `.workflow/iterations/<iteration-id>/<node-id>/`, and reject unapproved workflow documents placed at the project root or beside source code.
+
+## Task State
+
+1. Invoke `$ai-delivery-checkpoint-task` before preflight to recover or initialize the task snapshot.
+2. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
+3. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+
+## Validation Order
+
+1. Parse files with format-aware parsers. Validate UTF-8 CSV headers and quoting, YAML structure, Markdown-required sections, OpenAPI or JSON Schema syntax, and referenced native artifacts.
+2. Verify stable ID syntax and uniqueness within type.
+3. Verify every registry file path, artifact version, input reference, standards pin, approval, and checksum.
+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, canvases, prototype files/elements, slices, tasks, tests, release items, and deployment evidence as applicable.
+9. For UI-bearing scope, validate the human tool-selection Gate, executable low-fidelity runtime, mandatory `UX-LF`, `UX-VS`, and `UX-UI` human decisions, stable page numbering, one-main-page-family-per-canvas rule, explicit file/terminal relations, adjustment history, impact propagation, and aligned `product-prototype-reconciliation.yaml`.
+10. Verify complete prototype-set membership and that UI handoff, experience confirmation, architecture validation, test validation, planning, development, and verification all reference the same product reconciliation, experience-change checksum, set checksum, and relevant member IDs, versions, source revisions, review-bundle checksums, management/review catalog checksums, impact-assessment checksums, and receipt checksums. Require downstream work to consume only `ready-for-development` changes.
+
+## 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.

package/skills/ai-delivery-validate-artifacts/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Validate Delivery Artifacts"
+  short_description: "Validate artifact contracts, IDs, references, and baselines"
+  default_prompt: "Use $ai-delivery-validate-artifacts to validate the current delivery artifacts."

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

@@ -0,0 +1,44 @@
+# Artifact Contract
+
+## Required Metadata
+
+Record artifact ID, type, version, iteration ID, status, producer skill, input artifact IDs and versions, standards IDs and versions, validation results, approval state when required, relative path, and checksum when frozen.
+
+## Formats
+
+- Markdown: narrative and human review.
+- CSV: flat tabular records and normalized association tables.
+- YAML: state, registry, manifests, controlled mappings, and approvals.
+- OpenAPI or JSON Schema: executable interface and data contracts.
+- Mermaid or native design references: diagrams and visual models.
+- Native source and test files: implementation evidence.
+
+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
+
+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;
+- 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.
+
+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.
+
+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.
+
+## Status Rules
+
+Approved or frozen artifacts are immutable. Changes create a new version, mark downstream dependents stale, and run impact analysis. A handoff is valid only when required inputs exist, references resolve, required approvals pass, standards are pinned, and the producer-specific required set is complete.

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

@@ -0,0 +1,56 @@
+---
+name: ai-delivery-verify-candidate
+description: Independently verify an immutable iteration or release candidate against approved requirements, architecture, prototypes, selected version lineage, and delivery materials in a reproducible environment. Use after iteration development and platform readiness converge, during R05 release verification, after a candidate fix, or when regression scope must be recalculated.
+---
+
+# Verify Candidate
+
+Validate the assembled system independently. Never modify product code, migrations, infrastructure, or configuration while acting as verifier.
+
+## 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.
+
+## Task State
+
+1. Invoke `$ai-delivery-checkpoint-task` before preflight to recover or initialize the task snapshot.
+2. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
+3. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+
+## Select Scope
+
+Require `scope: iteration` or `scope: release`. For iteration scope, verify one planned candidate and produce the evidence consumed by version closeout. For release scope, verify the exact aggregated release candidate, selected continuous version closure, environment/configuration snapshot, migrations, and release material index.
+
+## 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 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.
+
+## 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.
+
+## Decide
+
+Aggregate evidence, coverage, defects, untested scope, flaky or blocked checks, and residual risk. Use `$ai-delivery-triage-failure` for every failure. A failing validator records and routes defects; it never patches the candidate.
+
+Produce:
+
+- independent test cases and automation;
+- execution logs and evidence;
+- requirement, feature, experience-change, page, canvas, prototype-file/element, risk, and test coverage matrices;
+- defect CSV with severity and reproduction evidence;
+- specialty test results as applicable;
+- untested scope and residual risks;
+- one candidate decision: `pass`, `fail`, or `blocked`;
+- 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.
+
+## 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`.

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

@@ -0,0 +1,4 @@
+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/defect-artifacts.csv

@@ -0,0 +1 @@
+defect_id,artifact_id,impact_type

package/skills/ai-delivery-verify-candidate/assets/verification-template/defects.csv

@@ -0,0 +1 @@
+defect_id,candidate_id,title,severity,failure_class,root_stage,evidence_ref,required_correction,revalidation_scope,status

package/skills/ai-delivery-verify-candidate/assets/verification-template/test-work-packages.csv

@@ -0,0 +1 @@
+test_task_id,candidate_id,risk_id,test_type,objective,public_seam,environment_id,data_ref,evidence_ref,status

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

@@ -0,0 +1,23 @@
+# Candidate Verification Contract
+
+## 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.
+
+## Test Work Packages
+
+`test-work-packages.csv`:
+
+`test_task_id,candidate_id,risk_id,test_type,objective,public_seam,environment_id,data_ref,evidence_ref,status`
+
+Create test types only when justified by changed or adjacent risk.
+
+## Candidate Decision
+
+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.
+
+## Independence
+
+Derive additional cases from approved requirements, architecture risks, historical defects, and observed boundaries. Do not repair code or relax expected results to match implementation.

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

@@ -0,0 +1,50 @@
+---
+name: ai-delivery-verify-production
+description: Independently verify an R08 production deployment, decide release success from approved technical and business signals, trigger pre-authorized rollback to the previous stable image digest, and hand off release archive. Use immediately after every production deployment or rollback attempt, including same-version redeploys.
+---
+
+# Verify Production
+
+Keep deployment execution separate from release success.
+
+## Artifact Location
+
+Write production verification reports, signal snapshots, rollback decisions, and release decisions to `.workflow/releases/<release-id>/R09-production-verification/`. External observability data may remain in controlled systems only when immutable references and timestamps are recorded in `.workflow/`.
+
+## Task State
+
+1. Invoke `$ai-delivery-checkpoint-task` before preflight to recover or initialize the task snapshot.
+2. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
+3. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+
+## Preflight
+
+Read the approved release package, deployment record, previous stable release, verification thresholds, rollback authorization, observability state, and target environment. Confirm that the deployed identities match the manifest.
+
+## Verify
+
+1. Run health, readiness, production smoke, core journey, data-integrity, authorization, and security checks.
+2. Observe logs, errors, latency, traffic, resources, queues, and approved business sanity signals for the defined window.
+3. Verify alerts, dashboards, audit records, configuration, migrations, and actual delivery items.
+4. Compare objective results with release thresholds and record evidence.
+
+## Decide And Roll Back
+
+- Mark `released` only when all mandatory checks pass.
+- For a pre-authorized objective technical failure, instruct the deployment system to restore the previous stable image by immutable digest. Do not create a rollback branch, reset Git, rebuild old code, or move a Tag.
+- Restore only approved compatible configuration or feature flags. Execute data or infrastructure recovery only from the approved release plan.
+- When old-image compatibility is unproven or data recovery is irreversible, stop and request the approved manual recovery decision.
+- For ambiguous business-signal degradation with healthy technical signals, pause for human judgment.
+
+After successful release verification, invoke `$ai-delivery-manage-git` to fast-forward code-repository `main` to the exact deployed, tagged commit. Record the release decision only in the workflow repository. For same-version redeploy, allow code `main` to remain at the same commit. After rollback, keep code `main` unchanged and retain the failed release, version, and Tags. Do not update `production_version_id` or `production_release_id` in R09; hand the verified identities to R10, which records them through the formal `release-archived` transition.
+
+## Outputs
+
+- production verification report and evidence;
+- release decision and observation window;
+- rollback deployment record and rollback verification when applicable;
+- residual risks, incident or defect routes, and final production version;
+- release archive handoff or rework status.
+- final production version, release ID, and immutable release evidence for `R10-release-archive`.
+
+Read [production-verification-contract.md](references/production-verification-contract.md) and use `assets/production-verification-template/`.

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

@@ -0,0 +1,4 @@
+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-verify-production/assets/production-verification-template/production-verification.md

@@ -0,0 +1,15 @@
+# Production Verification
+
+## Release And Deployment Identity
+
+## Mandatory Checks
+
+## Observation Window And Signals
+
+## Actual Delivery Reconciliation
+
+## Decision
+
+## Rollback And Rollback Verification
+
+## Residual Risk And Routes

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

@@ -0,0 +1,14 @@
+# Production Verification Contract
+
+## Required Evidence
+
+Record deployment and release IDs, actual artifact digests, health and readiness, critical journey smoke results, data integrity, authorization, logs, errors, latency, resources, queues, alerts, dashboards, business sanity signals, observation window, and final decision.
+
+## Decisions
+
+- `released`: mandatory thresholds pass; fast-forward `main` to the exact deployed tagged commit, or keep the identical commit for same-version redeploy, then hand off R10 archive.
+- `rolled-back`: an authorized technical threshold fails; redeploy the previous stable image digest and verify it.
+- `blocked`: rollback compatibility, recovery authority, or evidence is insufficient.
+- `human-decision`: business signals are ambiguous while technical signals remain healthy.
+
+Never create a rollback branch, move a release Tag, reset `main`, or rebuild the previous image.