ai-delivery-workflow 0.3.0 → 0.5.0

package/skills/ai-delivery-execute-test/SKILL.md

@@ -9,7 +9,11 @@ Observe and report. Do not repair the candidate, change test expectations to mak
 
 ## Artifact Location
 
-Write every test report, log index, evidence manifest, and workflow document produced by this skill under project `.workflow/`, defaulting version-scoped outputs to `.workflow/iterations/<iteration-id>/<node-id>/`. Raw external logs may remain in controlled systems only when their immutable references and checksums are recorded in `.workflow/`.
+Write every test report, log index, evidence manifest, and workflow document produced by this skill under project `.workflow/`. Iteration candidate tests stay in `.workflow/iterations/<iteration-id>/05-candidate-assurance/`; release tests stay in `.workflow/releases/<release-id>/R05-release-verification/`. Raw external logs may remain in controlled systems only when their immutable references and checksums are recorded in `.workflow/`.
+
+## Development Node
+
+For iteration scope, this Skill executes an independent test phase inside `05-candidate-assurance` against the node attempt's bound candidate and cannot mutate it. Test rounds do not create formal nodes. Any candidate-changing correction returns through `04-implementation` before a new assurance attempt. Release scope remains part of `R05-release-verification`.
 
 ## Task State
 
@@ -19,7 +23,7 @@ Write every test report, log index, evidence manifest, and workflow document pro
 
 ## Workflow
 
-1. Read the work package, approved source artifacts, candidate identity, environment identity, applicable standards, evidence requirements, and exact page/canvas/file/element references for UI or prototype-conformance scope.
+1. Read the work package, approved source artifacts, candidate identity, environment identity, applicable standards, evidence requirements, exact Prototype revision and UI Mapping checksums, and terminal/Page/Review Scene/prototype-element/UI component/frontend-source/acceptance references for UI or prototype-conformance scope. Reject missing or conflicting references and never infer relationships from file names or row order.
 2. Confirm prerequisites and isolate test data.
 3. Derive additional cases from independent requirements and risk sources when allowed.
 4. Execute through public interfaces and retain reproducible commands, inputs, outputs, timestamps, and environment references.

package/skills/ai-delivery-execute-work-package/SKILL.md

@@ -9,7 +9,11 @@ Implement only the assigned package. Do not broaden scope, choose a different st
 
 ## Artifact Location
 
-Write every work-package document, TDD record, evidence manifest, and handoff record produced by this skill under project `.workflow/`, defaulting version-scoped outputs to `.workflow/iterations/<iteration-id>/<node-id>/`. Source code, automated test source, and non-document build artifacts remain in their declared modification scopes.
+Write every work-package document, TDD record, evidence manifest, and handoff record produced by this skill under project `.workflow/`, defaulting version-scoped outputs to `.workflow/iterations/<iteration-id>/04-implementation/`. Source code, automated test source, and non-document build artifacts remain in their declared modification scopes.
+
+## Development Node
+
+This Skill executes implementation and approved repair phases for a stable logical task inside `04-implementation`. It never creates a separate formal node for a work package, review round, fix round, or retry. Preserve the task ID across attempts and apply only the approved `change_set_id` when repairing review findings.
 
 ## Task State
 
@@ -19,15 +23,17 @@ Write every work-package document, TDD record, evidence manifest, and handoff re
 
 ## Preflight
 
-1. Read the work package, source baselines, applicable standards, confirmed test seam, repository instructions, and exact UI handoff, product reconciliation, experience-change mapping, prototype-set/member revisions, management/review/impact checksums, and page/canvas/file/element mappings when the package is UI-bearing. Require every mapped change to be `ready-for-development` and its action to be one of `create|update|remove|migrate|no-code`.
+1. Read the work package, source baselines, applicable standards, confirmed test seam, repository instructions, and exact UI handoff, `product-prototype-reconciliation.yaml`, experience-change mapping, Prototype revision/checksum, frontend scope checksum, UI Mapping checksum, normalized catalog and review/impact checksums, and terminal/Page/Review Scene/prototype-element/UI component/frontend-source/acceptance mappings when the package is UI-bearing. Require every mapped change to be `ready-for-development` and its action to be one of `create|update|remove|migrate|no-code`.
 2. Verify the current branch and worktree with `$ai-delivery-manage-git`.
 3. Inspect the current code and tests before planning edits.
-4. Stop on missing dependencies, prototype or page/canvas/file identity mismatch, overlapping ownership, ambiguous acceptance behavior, or an infeasible architecture. Return evidence to the orchestrator.
+4. Stop on missing dependencies, missing or conflicting Prototype revision or UI Mapping references, overlapping ownership, ambiguous acceptance behavior, or an infeasible architecture. Never infer relationships from file names or row order. Return evidence to the orchestrator.
 
 ## TDD Loop
 
 For one vertical behavior at a time:
 
+Before the first write to each production UI file in a behavior or approved repair, run `ai-delivery frontend-guard check-file <workspace> --path <exact-path>`. Proceed only when the current Prototype approval and UI Mapping or revision-bound ownership covers that path. This applies equally to copy, style, responsive, accessibility, Page/route addition or removal, and defect correction.
+
 1. Write a behavior test through the confirmed public interface.
 2. Run it and retain evidence that it fails for the expected reason.
 3. Implement the minimum behavior needed to pass.
@@ -42,6 +48,7 @@ Perform cleanup or refactoring only from a Green checkpoint and expose it to ind
 ## Finish
 
 - Run architecture-specified format, lint, type, build, test, migration, and security commands.
+- Run `ai-delivery frontend-guard verify-diff <workspace> --base <fixed-base> --head <candidate-head>` for a UI-bearing package and retain the independent Git diff report; local Hook success is not evidence.
 - Update task-to-experience-change traceability and advance implemented rows through the state CLI; update technical documentation, configuration catalogs, and migration/rollback notes when affected.
 - Record deviations and TDD exceptions explicitly.
 - Commit only files in the allowed scope and produce a review packet with commands and evidence.

package/skills/ai-delivery-execute-work-package/references/work-package-contract.md

@@ -5,7 +5,7 @@ A package is executable only when it declares:
 - stable task, iteration, and slice IDs;
 - objective and observable completion behavior;
 - approved source and standards references;
-- exact ready UI handoff, aligned product reconciliation, actionable experience-change IDs with create/update/remove/migrate/no-code actions, prototype-set identity/checksum, relevant member IDs/revisions/review-bundle checksums, management/review/impact checksums, and page/canvas/file/element IDs when UI-bearing;
+- exact ready UI handoff, aligned `product-prototype-reconciliation.yaml`, actionable experience-change IDs with create/update/remove/migrate/no-code actions, Prototype revision/checksum, source and review-bundle checksums, UI Mapping and normalized catalog checksums, review/impact checksums, and terminal/Page/Review Scene/prototype-element/UI component/frontend-source/acceptance IDs when UI-bearing;
 - required capability role;
 - allowed and forbidden modification scope;
 - predecessor outputs;

package/skills/ai-delivery-manage-git/SKILL.md

@@ -27,7 +27,7 @@ Write every Git decision, transition record, scope declaration, and workflow doc
 - `line/<product-id>`: latest verified cumulative development lineage, which may remain ahead of production;
 - `version/<version-id>-<slug>`: one planned cumulative version;
 - `work/<version-id>/<task-id>-<slug>`: one dynamic technical work package;
-- `release/<release-id>-<slug>`: one explicit user-requested release candidate;
+- `release/<release-id>-<slug>`: one explicit user-requested release candidate, created from the frozen `main` snapshot and, for incremental release, integrated with exactly one target `version-ready` Tag;
 - `release-fix/<release-id>/<defect-id>`: one isolated release-candidate correction;
 - `hotfix/<hotfix-id>-<slug>`: urgent correction from the current production Tag.
 
@@ -45,13 +45,15 @@ Reject environment branches (`dev`, `sit`, `staging`, `production`), `rollback-*
 ## Release Operations
 
 1. At planned-version closeout, create immutable code `version-ready/<version-id>/rN`, fast-forward code `line/<product-id>`, commit workflow materials, then create workflow `workflow-ready/<version-id>/rN`; stop without changing code `main`.
-2. Serialize production release transitions only after explicit user release intent.
-3. Create `release/<release-id>-<slug>` from the selected target's exact version-ready Tag. Never merge each intermediate Tag or build from a movable line/version branch head.
-4. Apply any release-only correction on `release-fix/*`, create a new release candidate, and repeat impacted verification.
-5. Freeze and Tag the exact tested release commit before production deployment. Never move or reuse a release Tag.
+2. Serialize production release transitions only after explicit user release intent. At R00, record the exact `main` commit as the production-base snapshot and hold that snapshot for the whole candidate.
+3. Create `release/<release-id>-<slug>` at the recorded `main` snapshot. At R04, for incremental release merge exactly one selected target `version-ready` Tag with `--no-ff`; the resulting merge commit is the release candidate. For same-version redeploy, require the target Tag to be already reachable from the snapshot and use the snapshot itself as the candidate without a new merge. Never merge intermediate Tags or build from a movable line/version branch head.
+4. During candidate assembly, verification, approval, and deployment, any change to `main` makes the candidate stale. Stop, preserve its evidence, and recreate the release branch and candidate from a new `main` snapshot.
+5. Apply any release-only correction on `release-fix/*` from the active candidate, merge it into a new candidate, and repeat impacted verification. Freeze and Tag the exact tested candidate before production deployment; never move or reuse a release Tag.
 6. Promote the same artifact digest through environments; Git branches do not select environment state.
-7. After successful production verification, fast-forward `main` to the exact deployed commit. Same-version redeploy may leave `main` unchanged.
-8. After failed deployment and image rollback, keep `main` unchanged and preserve failed release and version Tags.
+7. After successful production verification, fast-forward `main` to the exact deployed release candidate commit. Before R10 archive, synchronise every deployed `release-fix` commit into `line/<product-id>` through the protected Git operation and record a sync receipt; if the commit is already reachable from line, record an explicit no-op receipt. Candidates that omit a production-successful fix are stale.
+8. Same-version redeploy may leave `main` unchanged when it already names the deployed commit. After failed deployment or image rollback, keep `main` and `line` unchanged, preserve failed release/version Tags, and do not create a rollback branch.
+
+Use the package-delivered `scripts/release-git.mjs` interface for these protected transitions. `create-candidate` requires `--release-id`, `--release-branch`, `--expected-main`, one `--source-tag`, its `--source-commit`, `--receipt`, and `--apply`. `promote` additionally requires `--production-verification <R09-production-verification/production-verification.json>`; the JSON must bind the release ID, `decision: released`, R00 main commit, verified candidate commit, and deployed commit. `sync-release-fix` requires that same `--production-verification`, a schema-2 product-line `--candidate-inventory <predecessor-R10 JSON>`, and, with `--apply`, a distinct unused `--successor-candidate-inventory <new-R10 JSON>`. The inventory binds `product_id`, `line_branch`, the active candidate, and every candidate's own `release_id`, commit, and status. The script, not a caller-supplied stale list, derives product-line-wide `stale_candidate_ids` and `candidate_status_updates` for selectable candidates that omit the successful fix, then writes the immutable successor inventory and binds both inventory paths and checksums in its receipt. Every action returns a structured JSON receipt; omitting `--apply` produces a zero-write plan, and an already-reconciled fix returns an explicit idempotent receipt rather than silently succeeding.
 
 ## Hotfix Operations
 

package/skills/ai-delivery-manage-git/references/git-policy.md

@@ -23,15 +23,19 @@ Use stable delivery IDs, not human names or dynamic AI roles.
 
 ## Cumulative Version Policy
 
-Create every next planned version from the current product line head. Close a verified version by creating immutable `version-ready/<version-id>/rN` and fast-forwarding `line/<product-id>` to it. Historical version tags and manifests never change. A correction after closeout normally becomes the next planned version.
+`product-id` is the stable product-line identity established when the project is bootstrapped. Create `line/<product-id>` once, from the current `main`, when the product begins its first planned version. Create every later planned version from the current line head. Close a verified version by creating immutable `version-ready/<version-id>/rN` and fast-forwarding `line/<product-id>` to it. Historical version tags and manifests never change. A correction after closeout normally becomes the next planned version.
 
 `main` represents current successful production, while `line/<product-id>` represents the latest verified cumulative development. The line may advance through any number of release-ready versions without changing production.
 
 ## Release Policy
 
-Create a release branch only after explicit user release intent. Build it from the exact target version-ready Tag. Verify every adjacent code and workflow commit edge from current production through the target; a direct production-to-target check does not prove the middle versions. Use intermediate versions for lineage and material closure, not repeated code merges.
+Create a release branch only after explicit user release intent. At R00, capture the exact current `main` head as the immutable `expected_main` base. Verify every adjacent code and workflow commit edge from current production through the target; a direct production-to-target check does not prove the middle versions. The captured main commit must still be the production head. In an incremental release it must be an ancestor of the exact target immutable version-ready Tag; in a same-version redeploy the target Tag must already be an ancestor of or equal to the captured main commit.
 
-After successful production verification, fast-forward `main` to the deployed release commit. For same-version redeploy, record a new release ID and Tag while allowing `main` to remain unchanged.
+At R04, create `release/<release-id>-<slug>` from `expected_main`. For incremental release, merge exactly one target Tag with `--no-ff` and bind all later verification, approval, deployment, and release Tags to that result merge commit. For same-version redeploy, when the target Tag is already contained by `expected_main`, bind them to the snapshot itself and record no new merge. Use intermediate versions for lineage and material closure, not repeated code merges. A main change during candidate work makes the candidate stale; preserve it and start a new R00 request rather than changing its base.
+
+After successful production verification, fast-forward `main` only from the recorded `expected_main` to the exact deployed candidate commit. `promote` must receive the immutable R09 `production-verification.json` decision, whose `schema_version` is `1`, `operation` is `production-verification-decision`, `release_id` is exact, `decision` is `released`, and `expected_main_commit`, `verified_release_commit`, and `deployed_commit` are full immutable object IDs. The promotion receipt retains the evidence path and SHA-256. For same-version redeploy, record a new release ID and Tag while allowing `main` to remain unchanged only when it already equals the exact candidate. A failed or rolled-back release does not advance `main`.
+
+Create a release-fix only from the active candidate. When its deployed candidate has passed production verification, synchronize the exact fix commit into `line/<product-id>` before R10 archive through the protected operation. Supply the released R09 decision and a schema-2 immutable candidate inventory scoped to that product line: `scope: product-line`, `product_id`, `line_branch`, active candidate ID/commit, and a unique `candidates` list whose records each retain `candidate_id`, `release_id`, `candidate_commit`, and `status`. The root has no `release_id`; the active and verified candidate records must belong to the operation's release ID. The operation derives, rather than accepts, stale candidates across the product-line inventory: it emits `candidate_status_updates` with `status: stale` for selectable candidates that do not contain the fix, while already `stale` or `released` candidates are not rewritten. With `--apply`, provide a distinct `--successor-candidate-inventory` path. The operation writes that successor without changing its predecessor, records its path/checksum in the receipt, and updates the successor's statuses and active candidate pointer. A later fix starts from the latest immutable successor. Record the release ID, source ref/commit, verified release commit, old/new line heads, merge strategy, evidence hashes, predecessor/successor inventories, derived stale candidate IDs/status updates, and result. If the line already contains the fix, record an explicit idempotent no-op receipt and require the exact same successor inventory.
 
 ## Environment And Rollback Policy