ai-delivery-workflow 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
   "type": "module",
   "repository": {
@@ -23,6 +23,7 @@
   ],
   "scripts": {
     "test": "node --test verification/*.test.mjs",
+    "manager:build": "npm --prefix manager run build",
     "skills:validate": "node bin/validate-skills.mjs",
     "audit:generate": "node audit/generate-all.mjs",
     "audit:verify": "node verification/audit/verify-audit.mjs",
@@ -37,5 +38,8 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "playwright-core": "^1.55.0"
+  }
 }

package/skills/ai-delivery-assemble-release/SKILL.md

@@ -9,19 +9,21 @@ Produce a deterministic release selection and auditable material package. Do not
 
 ## Select The Version Closure
 
-1. Build a JSON lineage input from registered version-closeout manifests. Include exactly one predecessor, status, candidate ID/commit, code Tag, workflow commit, workflow Tag, manifest path, and checksum per version.
-2. Run `node scripts/plan-release.mjs --lineage <file> --release-id <id> --target <version> --requested-by <actor> --rationale <text> --workspace <workspace-root>`.
-3. Preserve the JSON result as the source for `R01-version-selection`. Do not use `--skip-git` outside isolated contract tests.
-4. Block on missing predecessors, branching, cycles, disconnected lineage, stale/ineligible versions, wrong `repo_id`, missing code or workflow Tags, workflow manifest checksum drift, backward targets, or any failed adjacent code/workflow ancestry edge. Checking only production-to-target reachability is insufficient.
+1. Read the immutable R00 release request first. It must name the production branch and record the exact request-time `main` snapshot commit (`expected_main`); it is the release base for this release ID.
+2. Build a JSON lineage input from registered version-closeout manifests. Include exactly one predecessor, status, candidate ID/commit, code Tag, workflow commit, workflow Tag, manifest path, and checksum per version.
+3. Run `node scripts/plan-release.mjs --lineage <file> --release-id <id> --target <version> --requested-by <actor> --rationale <text> --workspace <workspace-root>`. Its captured `release_base` must equal the R00 snapshot. Do not use `--skip-git` outside isolated contract tests.
+4. Preserve the JSON result as the source for `R01-version-selection`. The target's `version-ready/<version-id>/rN` value is an immutable Tag, never a branch.
+5. Block on missing predecessors, branching, cycles, disconnected lineage, stale/ineligible versions, wrong `repo_id`, missing code or workflow Tags, workflow manifest checksum drift, backward targets, a changed production branch, or any failed adjacent code/workflow ancestry edge. For an incremental release, the release base must be an ancestor of the target Tag; for a same-version redeploy, the target Tag must already be an ancestor of or equal to the release base. Checking only production-to-target reachability is insufficient.
 
 ## Aggregate Materials
 
 1. Copy the assets into `.workflow/releases/<release-id>/R03-material-aggregation/` and `R04-release-candidate/`.
 2. Add every actual requirement, product, architecture, prototype, source, image, configuration, migration, infrastructure, test, security, risk, operations, rollback, and observability item to `release-material-index.csv`. Code entries require `repo_id`, `code_commit`, optional `code_tag`, `source_path`, source version, original workflow path, and SHA-256.
-3. Record every selected version and immutable identity in `version-inclusion.csv`. Intermediate versions provide traceability; build the release branch from only the exact target tag.
-4. Create `release/<release-id>-<slug>` at the target tag. Apply release-only fixes through `release-fix/<release-id>/<defect-id>`, create a new candidate, and repeat affected verification.
-5. Freeze `release-candidate-manifest.yaml` with the branch commit, image digest, material index checksum, environment/configuration snapshot requirements, and rollback image.
+3. Record every selected version and immutable identity in `version-inclusion.csv`. Intermediate versions provide traceability only; do not merge their Tags into the release branch.
+4. At R04 invoke `$ai-delivery-manage-git`'s controlled `scripts/release-git.mjs create-candidate` operation with `--release-id`, `--release-branch`, R00 `--expected-main`, exactly one `--source-tag` and its immutable `--source-commit`, plus `--receipt <path> --apply`. For an incremental release it creates `release/<release-id>-<slug>` at that snapshot and merges that one Tag with `--no-ff`; for a same-version redeploy whose target is already reachable from the snapshot, it records the snapshot itself as the candidate with no new merge. It returns the only authoritative candidate receipt. Omitting `--apply` is a zero-write plan. Do not substitute a movable line/version branch head, cherry-picks, or repeated Tag merges.
+5. Apply a release-only correction from the active candidate through `release-fix/<release-id>/<defect-id>`. A fix produces a new exact candidate identity and repeats all affected verification; it never rewrites historical version-ready Tags or manifests.
+6. Freeze `release-candidate-manifest.yaml` with the request-time `main` base, exact source Tag/commit, integration commit, branch commit, image digest, material index checksum, environment/configuration snapshot requirements, rollback image, and any release-fix identities.
 
-Same-version redeploy reuses immutable application identities but regenerates the release-scoped indexes, snapshots, verification, approval, deployment, and archive evidence.
+Same-version redeploy reuses immutable application identities but regenerates the release-scoped indexes, snapshots, verification, approval, deployment, and archive evidence. A release-fix still advances the product-line candidate inventory through a distinct immutable successor; it never rewrites the predecessor inventory.
 
 Read [release-assembly-contract.md](references/release-assembly-contract.md) before aggregation.

package/skills/ai-delivery-assemble-release/assets/release-candidate-manifest.yaml

@@ -1,14 +1,25 @@
-schema_version: 2
+schema_version: 3
 release_id: "REL-0001"
 release_candidate_id: "RC-0001"
 mode: "incremental"
 target_version: "VER-0005"
-source_tag: "version-ready/VER-0005/r1"
+release_branch: "release/REL-0001-short-slug"
+release_base:
+  production_branch: "main"
+  commit: "<git-sha>"
+  captured_at: "<RFC3339>"
+release_merge:
+  strategy: "no-ff-single-version-ready-tag"
+  merge_created: true # False when a same-version target is already in the release base.
+  source_tag: "version-ready/VER-0005/r1"
+  source_commit: "<git-sha>"
+  commit: "<git-sha>" # Null when merge_created is false.
+  candidate_receipt_ref: ".workflow/releases/REL-0001/R04-release-candidate/candidate-receipt.json"
 repository:
   repo_id: "app"
   source_path: "code"
-  code_commit: "<git-sha>"
-  code_tag: "version-ready/VER-0005/r1"
+  code_commit: "<git-sha>" # Exact candidate commit: incremental merge result or same-version release base, never a mutable branch head.
+  code_tag: "release/REL-0001/r1"
 workflow_identity:
   workflow_commit: "<workflow-git-sha>"
   workflow_tag: "workflow-ready/VER-0005/r1"
@@ -19,4 +30,5 @@ material_index_sha256: "<sha256>"
 configuration_baseline_sha256: "<sha256>"
 migration_set_sha256: "<sha256>"
 rollback_image_digest: "sha256:<previous-digest>"
+release_fixes: []
 status: "immutable"

package/skills/ai-delivery-assemble-release/assets/release-git-plan.yaml

@@ -1,9 +1,99 @@
-schema_version: 1
+schema_version: 2
 release_id: "REL-0001"
-source_tag: "version-ready/VER-0005/r1"
-source_commit: "<git-sha>"
-release_branch: "release/REL-0001-short-slug"
+product_id: "PRODUCT-001"
 production_branch: "main"
-line_branch: "line/PRODUCT-001"
-merge_intermediate_tags: false
+release_branch: "release/REL-0001-short-slug"
+release_base:
+  expected_main: "<git-sha>"
+  captured_at: "<RFC3339>"
+  request_artifact: ".workflow/releases/REL-0001/R00-release-request/release-request.yaml"
+target_version:
+  version_id: "VER-0005"
+  source_tag: "version-ready/VER-0005/r1"
+  source_commit: "<git-sha>"
+  source_relation_to_release_base: "incremental: target-descends-from-release-base; same-version-redeploy: target-already-in-release-base"
+candidate_operation:
+  command: "release-git.mjs create-candidate"
+  required_arguments:
+    - "--release-id REL-0001"
+    - "--release-branch release/REL-0001-short-slug"
+    - "--expected-main <git-sha>"
+    - "--source-tag version-ready/VER-0005/r1"
+    - "--source-commit <git-sha>"
+    - "--receipt <path>"
+    - "--apply"
+  merge_strategy: "no-ff-single-version-ready-tag"
+  merge_created: true # False when a same-version target is already in the release base.
+  merge_intermediate_tags: false
+  release_candidate_commit: null
+  receipt_fields:
+    - "operation: create-release-candidate"
+    - "release_base_commit"
+    - "source_ref"
+    - "source_commit"
+    - "candidate_commit"
+    - "status: planned | applied | idempotent"
+  receipt_ref: null
+  status: "pending-controlled-git-operation"
+promotion_operation:
+  command: "release-git.mjs promote"
+  required_arguments:
+    - "--release-id REL-0001"
+    - "--release-branch release/REL-0001-short-slug"
+    - "--expected-main <git-sha>"
+    - "--verified-release-commit <git-sha>"
+    - "--production-verification .workflow/releases/REL-0001/R09-production-verification/production-verification.json"
+    - "--receipt <path>"
+    - "--apply"
+  verified_release_commit: null
+  receipt_fields:
+    - "operation: promote-release-candidate"
+    - "production_verification.path"
+    - "production_verification.sha256"
+    - "old_main_head"
+    - "new_main_head"
+    - "status: planned | applied | idempotent"
+  receipt_ref: null
+  status: "pending-production-verification"
+release_fix_synchronization:
+  line_branch: "line/PRODUCT-001"
+  command: "release-git.mjs sync-release-fix"
+  required_arguments:
+    - "--release-id REL-0001"
+    - "--source-ref release-fix/REL-0001/DEFECT-001"
+    - "--source-commit <git-sha>"
+    - "--verified-release-commit <git-sha>"
+    - "--expected-line <git-sha>"
+    - "--production-verification .workflow/releases/REL-0001/R09-production-verification/production-verification.json"
+    - "--candidate-inventory .workflow/releases/REL-0001/R10-release-archive/candidate-inventory.json"
+    - "--successor-candidate-inventory .workflow/releases/REL-0001/R10-release-archive/candidate-inventory-successor.json"
+    - "--receipt <path>"
+    - "--apply"
+  required_before_archive: true
+  expected_line: "<git-sha>"
+  candidate_inventory_contract:
+    schema_version: 2
+    scope: "product-line"
+    product_id: "PRODUCT-001"
+    line_branch: "line/PRODUCT-001"
+    root_release_id: forbidden
+    candidate_fields:
+      - "candidate_id"
+      - "release_id"
+      - "candidate_commit"
+      - "status"
+    successor_is_immutable: true
+  receipt_fields:
+    - "operation: synchronize-release-fix-to-line"
+    - "old_line_head"
+    - "new_line_head"
+    - "stale_candidate_ids"
+    - "candidate_status_updates"
+    - "production_verification.sha256"
+    - "candidate_inventory.sha256"
+    - "successor_candidate_inventory.path"
+    - "successor_candidate_inventory.sha256"
+    - "successor_candidate_inventory_write.status"
+    - "status: planned | applied | idempotent"
+  receipt_refs: []
 rollback_branch_allowed: false

package/skills/ai-delivery-assemble-release/assets/release-material-index.csv

@@ -1,2 +1,2 @@
 item_id,category,source_version_id,artifact_id,repo_id,code_commit,code_tag,source_path,original_workflow_path,sha256,target_environment,apply_order,verification,rollback_or_recovery
-ITEM-0001,container-image,VER-0001,ART-IMAGE-0001,app,<git-sha>,version-ready/VER-0001/r1,code,.workflow/iterations/VER-0001/12-version-closeout/version-manifest.yaml,<sha256>,production,10,verify image digest,deploy previous immutable image digest
+ITEM-0001,container-image,VER-0001,ART-IMAGE-0001,app,<git-sha>,version-ready/VER-0001/r1,code,.workflow/iterations/VER-0001/06-version-closeout/version-manifest.yaml,<sha256>,production,10,verify image digest,deploy previous immutable image digest

package/skills/ai-delivery-assemble-release/assets/version-inclusion.csv

@@ -1,2 +1,2 @@
-sequence,version_id,predecessor_version_id,candidate_id,candidate_commit,version_ready_tag,manifest_path,manifest_sha256,inclusion_type
-1,VER-0001,,CAND-0001,<git-sha>,version-ready/VER-0001/r1,.workflow/iterations/VER-0001/12-version-closeout/version-manifest.yaml,<sha256>,dependency-closure
+sequence,version_id,predecessor_version_id,candidate_id,candidate_commit,version_ready_tag,manifest_path,manifest_sha256,inclusion_type,release_code_role
+1,VER-0001,,CAND-0001,<git-sha>,version-ready/VER-0001/r1,.workflow/iterations/VER-0001/06-version-closeout/version-manifest.yaml,<sha256>,dependency-closure,incremental-target-tag-merged-once-or-same-version-already-reachable

package/skills/ai-delivery-assemble-release/references/release-assembly-contract.md

@@ -1,7 +1,21 @@
 # Release Assembly Contract
 
-Treat the target version tag as the only code source for a release candidate. Never assemble code by merging every intermediate tag and never use a movable branch head as the source.
+## Candidate Identity
+
+At R00, freeze the exact request-time production branch head as `expected_main`. A release candidate is not a checkout of the target Tag. For an incremental release, the controlled Git operation creates `release/<release-id>-<slug>` at that exact commit, confirms that `main` still equals it and that it is an ancestor of the selected target, then merges exactly one target `version-ready/<version-id>/rN` Tag with `--no-ff`. The resulting merge commit is the release-candidate identity. For a same-version redeploy, the selected target Tag must already be an ancestor of or equal to `expected_main`; no merge is created and the exact snapshot commit is the release-candidate identity.
+
+The target Tag is immutable and resolves to the target version's `candidate_commit`. Never merge every intermediate Tag, use a movable branch head, or replace the single incremental target merge with cherry-picks. Intermediate versions appear only in the continuous dependency closure and material traceability. If `main` moves after R00 or before candidate acceptance, preserve the abandoned evidence as `stale` and start a new release request/snapshot; do not retarget the existing release branch.
+
+`release-git.mjs create-candidate` receives `--release-id`, `--release-branch`, `--expected-main`, `--source-tag`, the resolved `--source-commit`, `--receipt`, and explicit `--apply`. Its receipt records `operation: create-release-candidate`, `release_id`, production branch, release branch, `release_base_commit`, `source_ref`, `source_commit`, `candidate_commit`, whether a merge was created, merge strategy, and `planned`, `applied`, or `idempotent` status. The candidate commit, not the branch's later head, is what R05 through R09 verify, approve, deploy, Tag, and ultimately promote.
+
+## Materials And Closure
 
 The material index is exhaustive for actual changes and contains stable item ID, category, source version, source artifact ID/path/checksum, target environment, application order, verification, and rollback/recovery action. Do not record secret values.
 
-Require every adjacent version in the full dependency closure through the target, including already produced history, to descend from its predecessor in both the code repository (`candidate_commit`) and workflow repository (`workflow_commit`). Production-to-target reachability alone cannot prove that an intermediate version is included. Repeat the full closure check for same-version redeploy. A production hotfix must first be synchronized into `line/<product-id>`; candidates that do not contain it are `stale`. When current production equals target, emit `same-version-redeploy`, an empty newly included range, and a fresh release identity.
+Require every adjacent version in the full dependency closure through the target, including already produced history, to descend from its predecessor in both the code repository (`candidate_commit`) and workflow repository (`workflow_commit`). Production-to-target reachability alone cannot prove that an intermediate version is included. Repeat the full closure check for same-version redeploy. When current production equals target, emit `same-version-redeploy`, an empty newly included range, and a fresh release identity.
+
+## Release-Fix Reconciliation
+
+Create `release-fix/<release-id>/<defect-id>` only from the active release candidate. After the corrected candidate has passed affected verification and production verification has decided `released`, freeze the R09 `production-verification.json` decision and a schema-2 R10 product-line `candidate-inventory.json` before synchronizing its fix commit into `line/<product-id>` through the protected `sync-release-fix` operation. The inventory has `scope: product-line`, `product_id`, `line_branch`, active candidate ID/commit, and all product-line candidate records. Each record retains its own `release_id`, ID, commit, and status; the root has no release ID. The operation checks that the active and verified records belong to the release being synchronized, derives stale updates instead of accepting a stale-candidate argument, and writes a separate immutable successor inventory rather than updating the source snapshot. Record its JSON receipt with the release ID, source ref/commit, verified release commit, old/new line heads, merge strategy, predecessor/successor inventory evidence bindings, derived stale candidate IDs/status updates, and status.
+
+Invoke it with `--candidate-inventory <predecessor>` and, for `--apply`, a distinct unused `--successor-candidate-inventory <successor>`. If the fix commit is already reachable from the line, `release-git.mjs sync-release-fix` returns `status: idempotent` with unchanged old/new line heads rather than changing history, and only accepts the exact already-written successor on replay. Historical version-ready Tags and manifests remain immutable. The receipt marks every selectable candidate in the product line that does not contain a production-successful fix `stale`; it cannot be selected until recreated from current lineage. Subsequent synchronization begins from that successor inventory.

package/skills/ai-delivery-assemble-release/scripts/plan-release.mjs

@@ -69,6 +69,7 @@ function repositoriesFromWorkspace(workspaceRoot) {
     codeRepo,
     workflowRepo: root,
     repoId,
+    productionBranch: value(codeSection, "default_branch") || "main",
     codeRemote: value(codeSection, "remote"),
     workflowRemote: value(workflowSection, "remote"),
   };
@@ -134,6 +135,72 @@ function validateRemoteTag(remote, tag, expectedCommit) {
   }
 }
 
+function validateRemoteBranch(remote, branch, expectedCommit) {
+  if (!remote) return;
+  const reference = `refs/heads/${branch}`;
+  const result = spawnSync("git", ["ls-remote", "--heads", remote, reference], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    throw new Error(`Remote branch validation failed for ${branch}: ${result.stderr.trim()}`);
+  }
+  const commits = result.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.split(/\s+/)[0].toLowerCase());
+  if (!commits.length) throw new Error(`Remote is missing production branch ${branch}: ${remote}`);
+  if (!commits.includes(expectedCommit.toLowerCase())) {
+    throw new Error(
+      `Remote production branch ${branch} drifted from the captured main commit ${expectedCommit}; refresh the release request.`,
+    );
+  }
+}
+
+function validateReleaseBase(repo, branch, currentProduction, remote) {
+  const reference = `refs/heads/${branch}`;
+  const commit = git(repo, ["rev-parse", "--verify", `${reference}^{commit}`]);
+  validateRemoteBranch(remote, branch, commit);
+  if (currentProduction) {
+    const result = spawnSync(
+      "git",
+      ["merge-base", "--is-ancestor", currentProduction.candidate_commit, commit],
+      { cwd: repo, encoding: "utf8", windowsHide: true },
+    );
+    if (result.status !== 0) {
+      throw new Error(
+        `Production branch ${branch} is not descended from current production ${currentProduction.version_id}; refusing a divergent release base.`,
+      );
+    }
+  }
+  return commit;
+}
+
+function validateTargetContainsReleaseBase(repo, branch, releaseBase, target) {
+  if (releaseBase.toLowerCase() === String(target.candidate_commit).toLowerCase()) {
+    throw new Error(
+      `Target ${target.version_ready_tag} equals captured production branch ${branch} commit ${releaseBase}; an incremental release target must strictly descend from the R00 main snapshot.`,
+    );
+  }
+  const targetAlreadyReachable = spawnSync(
+    "git",
+    ["merge-base", "--is-ancestor", target.candidate_commit, releaseBase],
+    { cwd: repo, encoding: "utf8", windowsHide: true },
+  );
+  if (targetAlreadyReachable.status === 0) {
+    throw new Error(
+      `Target ${target.version_ready_tag} is already reachable from captured production branch ${branch} commit ${releaseBase}; an incremental release target must strictly descend from the R00 main snapshot.`,
+    );
+  }
+  const result = spawnSync(
+    "git",
+    ["merge-base", "--is-ancestor", releaseBase, target.candidate_commit],
+    { cwd: repo, encoding: "utf8", windowsHide: true },
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      `Captured production branch ${branch} commit ${releaseBase} is not an ancestor of target ${target.version_ready_tag}; recreate the version candidate before release.`,
+    );
+  }
+}
+
 function validateAdjacentAncestry(repo, selected, currentProduction, commitField, label) {
   const chain = currentProduction
     ? [currentProduction, ...selected.filter((version) => version.version_id !== currentProduction.version_id)]
@@ -199,9 +266,21 @@ export function planRelease(lineage, request, options = {}) {
   }
 
   const target = ordered[targetIndex];
+  const sameVersionRedeploy = targetIndex === currentIndex;
   const newlyIncluded = ordered.slice(currentIndex + 1, targetIndex + 1);
-  const releaseEvidence = targetIndex === currentIndex ? [target] : newlyIncluded;
+  const releaseEvidence = sameVersionRedeploy ? [target] : newlyIncluded;
   const dependencyClosure = ordered.slice(0, targetIndex + 1);
+  const productionBranch = options.productionBranch || "main";
+  const currentProduction = currentIndex < 0 ? null : ordered[currentIndex];
+  let releaseBaseCommit = null;
+  if (!sameVersionRedeploy
+    && currentProduction?.candidate_commit
+    && target.candidate_commit
+    && String(currentProduction.candidate_commit).toLowerCase() === String(target.candidate_commit).toLowerCase()) {
+    throw new Error(
+      `Incremental target ${target.version_id} reuses current production ${currentProduction.version_id} candidate commit; use same-version redeploy instead.`,
+    );
+  }
   for (const version of releaseEvidence) {
     if (!ELIGIBLE_STATUSES.has(version.status)) {
       throw new Error(`Version ${version.version_id} is not eligible for release: ${version.status || "missing status"}.`);
@@ -221,6 +300,20 @@ export function planRelease(lineage, request, options = {}) {
   }
 
   if (!options.skipGit) {
+    releaseBaseCommit = validateReleaseBase(
+      path.resolve(options.repo || process.cwd()),
+      productionBranch,
+      currentProduction,
+      options.codeRemote || null,
+    );
+    if (!sameVersionRedeploy) {
+      validateTargetContainsReleaseBase(
+        path.resolve(options.repo || process.cwd()),
+        productionBranch,
+        releaseBaseCommit,
+        target,
+      );
+    }
     validateGit(
       path.resolve(options.repo || process.cwd()),
       dependencyClosure,
@@ -244,7 +337,7 @@ export function planRelease(lineage, request, options = {}) {
     target_environment: "production",
     current_production_version: currentId,
     target_version: target.version_id,
-    mode: targetIndex === currentIndex ? "same-version-redeploy" : "incremental",
+    mode: sameVersionRedeploy ? "same-version-redeploy" : "incremental",
     newly_included_versions: newlyIncluded.map((version) => version.version_id),
     dependency_closure: dependencyClosure.map((version) => version.version_id),
     target: {
@@ -262,6 +355,29 @@ export function planRelease(lineage, request, options = {}) {
     requires_fresh_verification: true,
     requires_fresh_approval: true,
     rollback_strategy: "previous-immutable-image-digest",
+    release_base: {
+      branch: productionBranch,
+      commit: releaseBaseCommit,
+      status: releaseBaseCommit ? "captured" : "pending-git-validation",
+      target_relation: sameVersionRedeploy
+        ? "target-already-in-release-base"
+        : "target-must-descend-from-release-base",
+    },
+    release_merge: {
+      strategy: sameVersionRedeploy ? "target-already-in-release-base" : "no-ff-single-version-ready-tag",
+      source_tag: target.version_ready_tag,
+      source_commit: target.candidate_commit,
+      merge_commit: null,
+      merge_created: !sameVersionRedeploy,
+      status: "pending-controlled-git-operation",
+    },
+    release_candidate: {
+      commit: sameVersionRedeploy ? releaseBaseCommit : null,
+      identity_source: sameVersionRedeploy
+        ? "release-base-when-target-already-reachable"
+        : "release-branch-head-after-merge",
+      status: "pending-controlled-git-operation",
+    },
   };
 }
 
@@ -270,7 +386,14 @@ function main(argv) {
   const lineageFile = path.resolve(required(options, "--lineage"));
   const configured = options.get("--workspace")
     ? repositoriesFromWorkspace(options.get("--workspace"))
-    : { codeRepo: process.cwd(), workflowRepo: process.cwd(), repoId: null, codeRemote: null, workflowRemote: null };
+    : {
+      codeRepo: process.cwd(),
+      workflowRepo: process.cwd(),
+      repoId: null,
+      productionBranch: "main",
+      codeRemote: null,
+      workflowRemote: null,
+    };
   const result = planRelease(readLineage(lineageFile), {
     release_id: required(options, "--release-id"),
     target_version: required(options, "--target"),
@@ -280,6 +403,7 @@ function main(argv) {
     repo: options.get("--repo") || configured.codeRepo,
     workflowRepo: options.get("--workflow-repo") || configured.workflowRepo,
     repoId: configured.repoId,
+    productionBranch: options.get("--production-branch") || configured.productionBranch || "main",
     codeRemote: configured.codeRemote,
     workflowRemote: configured.workflowRemote,
     skipGit: options.get("--skip-git") === true,

package/skills/ai-delivery-bootstrap/SKILL.md

@@ -32,8 +32,8 @@ When inspection returns `workflow-ready`, there are no task shards, and the form
 
 1. Run `node .workflow/tools/bootstrap/bootstrap.mjs bootstrap` to create the observed bootstrap context.
 2. Start development scope `INIT-0001` through the formal state CLI.
-3. Register `TASK-INIT-0001-00` for `00-bootstrap` and `TASK-INIT-0001-01` for `01-product-discovery`, with the latter depending on the former.
-4. Finish the bootstrap task only after its report and handoff evidence are registered, then activate the discovery task.
+3. Register `TASK-INIT-0001-00` for `00-bootstrap` and `TASK-INIT-0001-01` for `01-product-shaping`, with the latter depending on the former.
+4. Finish the bootstrap task only after its report and handoff evidence are registered, then activate the Product Shaping task.
 5. Let `task-state.mjs` resolve `code_branch` and `code_commit` from the authoritative `.workflow/config/workspace.yaml`; never use the install manifest copy or record the workflow Git identity as code identity.
 
 The first product question is the safe stopping point. Do not invent the initial business need and do not leave product artifacts outside an initialized task.
@@ -44,13 +44,13 @@ The first product question is the safe stopping point. Do not invent the initial
 - `codebase-uninitialized`: use packaged `ai-delivery bootstrap`, review the repository baseline, inventory, context index, and adoption assessment, then invoke `$ai-delivery-define-product` to distinguish observed behavior from intended product behavior.
 - `workflow-interrupted`: do not write bootstrap artifacts. If `runtime.next_action_owner` is `user`, return the recorded `next_action` as the single business question and perform no recovery, activation, checkpoint, task, artifact, or Git mutation. If it is `external`, report the recorded wait condition without mutation. Only an `agent`-owned next action may invoke `$ai-delivery-checkpoint-task recover`, reconcile reality, inspect the pending Evolution queue without applying changes mid-task, and continue `recommended_task_id`. When required input arrives, transfer ownership with both `--next-action-owner agent` and a new idempotent `--next-action`.
 - `workflow-ready`: when a queued task is recommended, first apply the same `next_action_owner` boundary; activate it through `$ai-delivery-checkpoint-task` only when the owner is `agent`. Otherwise use the reported specialist skill or `$ai-delivery-orchestrate` to derive the next development node. Treat `release-ready` versions as completed development evidence, not implicit release intent. Route to `$ai-delivery-orchestrate-release` only when the user explicitly requests a release.
-- `workflow-inconsistent`: stop automatic mutation, run the available project/package doctor internally, report exact conflicts, and obtain a repair decision. Never use `--force` unless the user explicitly approves replacing the reported managed files.
+- `workflow-inconsistent`: stop automatic mutation, run the available project/package doctor internally, report exact conflicts, and obtain a repair decision. An installed project must use packaged `upgrade --dry-run` for managed installation drift and `migrate --dry-run` for legacy schema, task grouping, anchor, or archive conflicts rather than repeat `init`. Structural migration copies legacy-root workflow material, adds explicit task attempts, and preserves lifecycle and scope facts; grouping ambiguities require a source-checksum-bound `--decisions` document with a `human:` actor and rationale. Route an approved premature-archive correction through packaged `repair --invalidate-archive` with a human actor, reason, RCA evidence, and recovery evidence; the original archive remains immutable. Use `upgrade --force` only when the user explicitly approves replacing the reported managed files.
 
 ## Brownfield Rules
 
 Treat repository scans as observations, not approved product or architecture truth. Keep generated artifacts `draft`. Exclude secrets, dependency/build directories, workflow internals, and files outside the project. Verify inferred commands before recording them as supported.
 
-Do not replace existing product, architecture, test, or release baselines. Register the project-state report, preserve every timestamped bootstrap run, and update only the `.workflow/delivery/bootstrap/latest.yaml` pointer.
+Do not replace existing product, architecture, test, or release baselines. Keep the project-state report and related observations outside the formal artifact registry while they remain working drafts, preserve every timestamped bootstrap run, and update only the `.workflow/delivery/bootstrap/latest.yaml` pointer.
 
 ## Resume Boundary
 

package/skills/ai-delivery-bootstrap/references/bootstrap-contract.md

@@ -28,6 +28,8 @@ After installation, `node .workflow/tools/bootstrap/bootstrap.mjs inspect` is th
 
 `ai-delivery bootstrap <project-root>` may initialize only `empty-uninitialized` and `codebase-uninitialized` projects through the project-scoped installer. Preserve existing code and configuration. On partial or conflicting installation, return `workflow-inconsistent` without writes. `--force` is allowed only after explicit user approval.
 
+For an installed legacy or conflicting state, keep Bootstrap read-only. Use packaged `migrate --dry-run` to report schema conversion, semantic task groups and ambiguities, state/archive conflicts, verified anchors, and exact file changes. A legacy root migration copies `delivery/`, `control/`, and `standards/` into `.workflow/` while preserving source bytes; flat task shards gain explicit attempts with checksummed rollback backups. Resolve grouping ambiguities only through a checksum-bound `--decisions` document with a `human:` actor and rationale. Migration must not activate or close tasks, infer completion, change scope, or rewrite legacy events. Incorrect archives require the separate packaged `repair --invalidate-archive` forward transaction with an explicit human actor, reason, RCA evidence, and recovery evidence; the original archive bytes remain authoritative history.
+
 For an uninitialized project, generate repository inventory and context artifacts from the first read-only scan snapshot. Do not let installer-generated `AGENTS.md`, `.gitignore`, Hook, skill, standard, or delivery files contaminate the observed pre-install codebase baseline.
 
 When an active or dependency-ready runtime task exists, defer to its task contract and write no bootstrap artifacts. An `agent`-owned next action routes to checkpoint recovery. A `user`-owned next action returns the recorded question verbatim and forbids all task, checkpoint, artifact, formal-state, and Git mutation until the user answers. An `external`-owned next action reports the wait condition and also forbids mutation. Read-only inspection must return `mutation_allowed: false` for the latter two cases.
@@ -46,7 +48,7 @@ For a newly initialized project or a ready project without a recoverable task, c
     bootstrap-plan.yaml
 ```
 
-Register `project-state-report.yaml` through `.workflow/tools/state/state.mjs artifact register`. Keep every generated artifact `draft`. Bootstrap code must call the shared formal-state module and must not parse and rewrite the registry itself.
+Keep every generated artifact `draft` and do not register it in the formal artifact registry. `project-state-report.yaml` remains discoverable through the checksummed `.workflow/delivery/bootstrap/latest.yaml` pointer until a later workflow node creates an immutable semantic revision. Bootstrap code must not parse or rewrite the registry itself.
 
 ## Artifact Meaning
 
@@ -61,7 +63,7 @@ Register `project-state-report.yaml` through `.workflow/tools/state/state.mjs ar
 
 Natural-language startup is the public user interface. The AI must translate “开始”, “继续”, “下一步”, status questions, product ideas, and release intent into internal Skill and CLI calls; it must never delegate workflow command selection or execution to the user.
 
-For a ready installation with no formal delivery artifact and no task shard, initialize the deterministic `INIT-0001` bootstrap/discovery task pair before writing product material. This is runtime state, unlike the draft tasks in `bootstrap-plan.yaml`. Resolve every shared task's code identity from the nested repository configured by `.workflow/config/workspace.yaml`, never from the install manifest or workflow repository.
+For a ready installation with no formal delivery artifact and no task shard, initialize the deterministic `INIT-0001` Bootstrap/Product Shaping task pair before writing product material. This is runtime state, unlike the draft tasks in `bootstrap-plan.yaml`. Resolve every shared task's code identity from the nested repository configured by `.workflow/config/workspace.yaml`, never from the install manifest or workflow repository.
 
 For an empty project, hand off to `$ai-delivery-define-product` and ask for the problem to solve, target users, and success measure one decision at a time.
 

package/skills/ai-delivery-checkpoint-task/SKILL.md

@@ -11,6 +11,10 @@ Treat explicit task snapshots as authoritative. Treat Hook events as an audit tr
 
 Write portable task state to `.workflow/control/tasks/<task-id>.yaml` and `.workflow/control/checkpoints/<task-id>/<checkpoint-id>.yaml`. Keep only PID, heartbeat, temporary locks, raw Hook events, and unshared context under ignored `.workflow/delivery/runtime/`. Keep durable node documents under `.workflow/iterations/<iteration-id>/<node-id>/`; runtime snapshots never replace registered delivery artifacts. Resolve code branch and commit from `.workflow/config/workspace.yaml` and the nested code repository.
 
+## Legacy Node Boundary
+
+Legacy development nodes are read-only compatibility. `inspect` remains a strictly read-only diagnosis path for historical tasks. `init`, `activate`, `checkpoint`, `finish`, and `archive-version` reject legacy task targets before mutation or Hook dispatch; `recover` refuses to materialize them and `publish` refuses to share them. New tasks use only the `development-seven-node` route, while `R00-release-request` through `R10-release-archive` remain writable.
+
 ## Start Or Resume
 
 1. Locate the project root and shared state root.
@@ -25,6 +29,16 @@ Write portable task state to `.workflow/control/tasks/<task-id>.yaml` and `.work
 
 Use statuses `queued`, `preparing`, `running`, `checkpointed`, `pending-review`, `blocked`, `interrupted`, `completed`, `failed`, and `abandoned`.
 
+## Stable Logical Tasks And Attempts
+
+Keep one stable logical task identity while iteration, node, skill, goal, scope, responsibility, dependencies, and acceptance remain unchanged. Register those fields with `init`, including repeatable `--scope` and `--acceptance` values plus `--responsibility`; every new task is initialized as `queued`, and any other requested status is rejected. Repeating the same `init` is zero-write and idempotent; attempting to register the same logical contract under another task ID is rejected. If any logical contract field changes, create a new task ID and link it with `--derived-from <task-id>` or `--supersedes <task-id>`; never encode planning, review, triage, repair, test, or version rounds in a new task-name suffix.
+
+A queued task has no attempt and cannot be checkpointed or finished; `activate --phase <phase>` creates attempt `A1`. Phase status is derived from the task transition, and `--phase-status` is not supported. Record planning, implementation, review, triage, repair, test, verification, and handoff as structured phases. Entering a review phase captures its immutable `review_subject_baseline`; later approval fails if Git changed during feedback collection. Record a review or test finding with `--finding-json <json>`; finding records are append-only, and the latest record with the same ID is its current task-level conclusion. Close feedback collection in the review phase with `--change-set-json <json>` containing `change_set_id`, `approval_actor`, `rationale`, exact `finding_ids`, repository-relative `allowed_files`, `expected_evidence`, `review_axes`, and `collection_decision`. The CLI promotes the pinned subject to `repair_baseline`, persists the canonical `feedback_collection`, and computes its SHA-256 `collection_checksum`; a caller-supplied checksum is optional and must match. A `resolved` record must reference an existing open finding and recorded approved change set, be written during concentrated rereview in the review phase, carry the expected evidence, and declare `changed_files` exactly equal to the real Git changes since approval and within the allowed files. `completed` is refused while any current blocking finding is still `open`. Optionally attribute elapsed time with paired `--time-category <category> --elapsed-minutes <minutes>`. A failed attempt cannot satisfy dependencies. Retry the unchanged task only with `activate --new-attempt --phase repair`; this creates the next attempt under the same task ID. A later task becomes dependency-ready only after the logical task itself reaches `completed`.
+
+During review, finish feedback collection across the pinned subject before any repair begins. Group every current open finding into one immutable approved `--change-set-json` record; the executor applies only that set in a repair phase and records its evidence before concentrated rereview. Never interleave code changes with feedback collection or add an unapproved finding or file to the active set.
+
+Run `scripts/task-state.mjs inspect --task-id <task-id> --include-closed` for strict read-only diagnosis. It returns source reconciliation, dependency state, attempt totals, current phase, and time by category without hydrating runtime, writing a resume, checkpointing, or changing Git state.
+
 ## Checkpoint
 
 Checkpoint after every externally meaningful milestone, before a long command, after test or review evidence, before context compaction, and before returning control. Keep `next_action` concrete and idempotent and set `next_action_owner` to `agent`, `user`, or `external`. Store decisions in their owning product, architecture, design, standard, or release artifact rather than in runtime notes alone. Repeated evidence references are idempotent and must remain unique.
@@ -33,7 +47,7 @@ Checkpoint after every externally meaningful milestone, before a long command, a
 
 1. Validate expected outputs and update the artifact registry through `.workflow/tools/state/state.mjs`.
 2. Record evidence, actual outputs, residual blockers, and the next workflow action.
-3. Atomically set `completed`, `blocked`, `failed`, `interrupted`, or explicitly `abandoned`. Treat `completed`, `failed`, and `abandoned` as closed tasks and omit them from default recovery output without archiving them individually.
+3. Atomically set `completed`, `blocked`, `failed`, `interrupted`, or explicitly `abandoned`. Closed statuses `completed`, `failed`, and `abandoned` may be written only by `finish`, never `checkpoint`. Treat them as closed for historical counts and archival eligibility. Default recovery omits `completed` and `abandoned`, but returns `failed` as retryable work until a new attempt completes or the version is abandoned.
 4. After the task snapshot succeeds, update formal workflow state only through `.workflow/tools/state/state.mjs`, then run its `verify` command.
 5. Invoke `$ai-delivery-evolve-workflow evaluate --safe-point task` after the task and formal-state writes are complete. Apply any newly eligible extension only to the next task; do not change the task that just finished.
 6. Never mark production deployment complete from a Hook event.
@@ -43,14 +57,14 @@ Checkpoint after every externally meaningful milestone, before a long command, a
 1. Use the iteration version as the archive unit; never archive one completed task independently.
 2. Require version status `release-ready`, `released`, or `abandoned` and at least one completion evidence reference. Require `candidate_id` for `release-ready`; require `release_id` for `released`.
 3. Refuse archival while any version task is queued, preparing, running, checkpointed, pending review, blocked, or interrupted.
-4. Write the portable archive manifest, task snapshots, and shared checkpoints under `.workflow/control/archives/versions/<version-id>/`. Retain detailed local event, heartbeat, and recovery copies under ignored runtime by default; use `--portable-only` to omit that disposable, non-authoritative copy.
+4. Before writing any archive file, require `state.mjs snapshot references` to project the target version from the latest trusted version-boundary anchor. Fail closed unless it returns the scope manifest, selected candidate, Gate decisions, and history anchor. Then write the portable archive manifest, task snapshots, and shared checkpoints under `.workflow/control/archives/versions/<version-id>/`. The manifest references checksummed task summary files and the complete referenced attempt values within that archive, plus every formal projection by relative path and checksum rather than copying their bodies. Retain detailed local event, heartbeat, and recovery copies under ignored runtime by default; use `--portable-only` to omit that disposable, non-authoritative copy.
 5. Only after the portable archive is complete, remove the version's shards from `.workflow/control/tasks/` and `.workflow/control/checkpoints/` and remove local active records. Normal recovery scans active collections only and must not load archived details, even with `--include-closed`.
 
 ## Recover
 
 Use shared shards and the newest shared checkpoint as the portable recovery source. If local runtime is absent and `next_action_owner` is `agent`, `recover` restores it from shared state. For `user` or `external`, report the wait state without hydration; after the input arrives, `activate` performs the atomic hydration and owner transfer. If local and shared revisions or semantic checksums differ, stop for reconciliation. Inspect both Git repositories before resuming. Report pending `.workflow/delivery/runtime/evolution/pending/` events, but defer their evaluation until the recovered task reaches a safe point.
 
-Generate a compact recovery report from snapshots, checkpoints, Hook events, Git, and workspace state. Return only non-closed tasks by default; use `--include-closed` only for an explicit audit. For each iteration, report total, completed, closed, remaining, active, queued, dependency-ready, and waiting tasks plus one deterministic `recommended_task_id`. Prefer an interrupted or active task; otherwise choose the lowest-sequence queued task whose dependencies are all `completed`. Resume only idempotent steps. Re-read production and external systems before any deployment recovery; never replay production deployment automatically.
+Generate a compact recovery report from snapshots, checkpoints, Hook events, Git, and workspace state. Return active work and failed tasks in `retryable_task_ids` by default; use `--include-closed` only when completed or abandoned details are required for an explicit audit. For each iteration, report total, completed, closed, remaining, active, retryable, queued, dependency-ready, and waiting tasks plus one deterministic `recommended_task_id`. Prefer an interrupted or active task, then the lowest-sequence failed task requiring `activate --new-attempt --phase repair`, then the lowest-sequence queued task whose dependencies are all `completed`. Resume only idempotent steps. Re-read production and external systems before any deployment recovery; never replay production deployment automatically.
 
 ## Hook Boundary
 

package/skills/ai-delivery-checkpoint-task/assets/runtime-template/task.json

@@ -6,9 +6,15 @@
   "status": "queued",
   "sequence": 1,
   "depends_on": [],
-  "attempt": 1,
+  "attempt": 0,
+  "attempts": [],
+  "change_sets": [],
   "goal": "",
+  "responsibility": "",
   "scope": [],
+  "acceptance": [],
+  "derived_from": null,
+  "supersedes": null,
   "input_artifacts": [],
   "standards": [],
   "branch": null,