ai-delivery-workflow 0.4.0 → 0.5.1

package/lib/project-repair.mjs

@@ -0,0 +1,217 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { atomicWrite, filesUnder } from "./fs-utils.mjs";
+
+function toPosix(value) {
+  return value.replaceAll("\\", "/");
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function treeDigest(root) {
+  const hash = crypto.createHash("sha256");
+  for (const file of filesUnder(root)) {
+    hash.update(toPosix(path.relative(root, file)));
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function readStructured(file, label) {
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const value = path.extname(file).toLowerCase() === ".json" ? JSON.parse(text) : parseYaml(text);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected a mapping");
+    return value;
+  } catch (error) {
+    throw new Error(`Cannot read ${label} (${toPosix(file)}): ${error.message}`);
+  }
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function uniqueSorted(values) {
+  return [...new Set((Array.isArray(values) ? values : []).map(String))].sort();
+}
+
+function unsignedRepairRecord(record) {
+  const unsigned = { ...record };
+  delete unsigned.record_checksum;
+  return unsigned;
+}
+
+function readRepairTransactions(project) {
+  const directory = path.join(project, ".workflow", "control", "repairs", "transactions");
+  const records = [];
+  let previousChecksum = null;
+  for (const file of filesUnder(directory).filter((item) => item.endsWith(".json"))) {
+    const record = readStructured(file, "repair transaction");
+    if (record.schema_version !== 1
+      || !Number.isInteger(record.sequence)
+      || record.sequence !== records.length + 1
+      || record.previous_checksum !== previousChecksum
+      || record.record_checksum !== sha256(stableJson(unsignedRepairRecord(record)))) {
+      throw new Error(`Repair transaction chain is invalid: ${toPosix(path.relative(project, file))}.`);
+    }
+    records.push(record);
+    previousChecksum = record.record_checksum;
+  }
+  return records;
+}
+
+function archiveIterationId(value) {
+  const iterationId = String(value || "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(iterationId)) {
+    throw new Error(`Invalid archive iteration ID: ${iterationId || "missing"}.`);
+  }
+  return iterationId;
+}
+
+function verifiedArchiveInvalidations(project, records) {
+  for (const record of records.filter((item) => item.transaction_type === "archive-invalidation")) {
+    const iterationId = archiveIterationId(record.target?.iteration_id);
+    const expectedArchivePath = `.workflow/control/archives/versions/${iterationId}`;
+    const expectedManifestPath = `${expectedArchivePath}/version-manifest.json`;
+    if (record.target.archive_path !== expectedArchivePath
+      || record.target.manifest_path !== expectedManifestPath
+      || !/^[a-f0-9]{64}$/.test(record.target.archive_sha256 || "")
+      || !/^[a-f0-9]{64}$/.test(record.target.manifest_sha256 || "")) {
+      throw new Error(`Archive invalidation target is invalid: ${record.transaction_id}.`);
+    }
+    const archiveDirectory = path.join(project, ...expectedArchivePath.split("/"));
+    const manifestFile = path.join(project, ...expectedManifestPath.split("/"));
+    if (!fs.existsSync(manifestFile)
+      || treeDigest(archiveDirectory) !== record.target.archive_sha256
+      || sha256(fs.readFileSync(manifestFile)) !== record.target.manifest_sha256) {
+      throw new Error(`Invalidated archive ${iterationId} bytes changed after ${record.transaction_id}.`);
+    }
+  }
+}
+
+function repairTransactionPath(sequence, transactionId) {
+  return `.workflow/control/repairs/transactions/${String(sequence).padStart(6, "0")}-${transactionId}.json`;
+}
+
+export function repairProject(project, options = {}) {
+  const root = path.resolve(project);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${root}`);
+  }
+  const iterationId = archiveIterationId(options.invalidateArchive);
+  const reason = String(options.reason || "").trim();
+  const actor = String(options.actor || "").trim();
+  const evidence = uniqueSorted(options.evidence);
+  if (!reason) throw new Error("Archive invalidation requires --reason.");
+  if (!actor.startsWith("human:")) {
+    throw new Error("Archive invalidation requires an explicit human actor through --actor human:<identity>.");
+  }
+  if (evidence.length < 2) {
+    throw new Error("Archive invalidation requires at least two --evidence values for RCA and recovery evidence.");
+  }
+  const archiveDirectory = path.join(root, ".workflow", "control", "archives", "versions", iterationId);
+  const manifestFile = path.join(archiveDirectory, "version-manifest.json");
+  if (!fs.existsSync(manifestFile)) throw new Error(`Version archive not found: ${iterationId}.`);
+  const manifest = readStructured(manifestFile, "version archive manifest");
+  if (manifest.iteration_id !== iterationId) {
+    throw new Error(`Version archive identity mismatch: expected ${iterationId}, found ${manifest.iteration_id || "missing"}.`);
+  }
+  const target = {
+    iteration_id: iterationId,
+    archive_path: toPosix(path.relative(root, archiveDirectory)),
+    manifest_path: toPosix(path.relative(root, manifestFile)),
+    manifest_sha256: sha256(fs.readFileSync(manifestFile)),
+    archive_sha256: treeDigest(archiveDirectory),
+    original_bytes_preserved: true,
+  };
+  const identity = { transaction_type: "archive-invalidation", target, correction: { actor, reason, evidence } };
+  const idempotencyKey = `archive-invalidation:${iterationId}:${sha256(stableJson(identity))}`;
+  const existingTransactions = readRepairTransactions(root);
+  verifiedArchiveInvalidations(root, existingTransactions);
+  const existing = existingTransactions.find((record) => record.idempotency_key === idempotencyKey);
+  const sequence = existing?.sequence || existingTransactions.length + 1;
+  const transactionId = existing?.transaction_id || `REPAIR-${sha256(idempotencyKey).slice(0, 16).toUpperCase()}`;
+  const transactionPath = repairTransactionPath(sequence, transactionId);
+  const report = {
+    command: "repair",
+    action: "archive-invalidation",
+    dry_run: Boolean(options.dryRun),
+    applied: false,
+    forward_only: true,
+    original_bytes_preserved: true,
+    target,
+    actor,
+    reason,
+    evidence,
+    transaction: {
+      transaction_id: transactionId,
+      path: transactionPath,
+      previous_checksum: existing?.previous_checksum || existingTransactions.at(-1)?.record_checksum || null,
+    },
+    eligibility: existing
+      ? { iteration_id: iterationId, current: "invalidated", source_transaction_id: transactionId }
+      : { iteration_id: iterationId, current: "eligible", source_transaction_id: null },
+  };
+  if (report.dry_run || existing) return report;
+
+  const repairRoot = path.join(root, ".workflow", "control", "repairs");
+  const lockFile = path.join(repairRoot, ".repair.lock");
+  fs.mkdirSync(repairRoot, { recursive: true });
+  let lock;
+  try {
+    lock = fs.openSync(lockFile, "wx");
+  } catch (error) {
+    throw new Error(`Repair transaction is locked by another writer: ${error.message}`);
+  }
+  try {
+    const currentTransactions = readRepairTransactions(root);
+    const duplicate = currentTransactions.find((record) => record.idempotency_key === idempotencyKey);
+    if (duplicate) {
+      report.transaction.transaction_id = duplicate.transaction_id;
+      report.transaction.path = repairTransactionPath(duplicate.sequence, duplicate.transaction_id);
+      report.eligibility = { iteration_id: iterationId, current: "invalidated", source_transaction_id: duplicate.transaction_id };
+      return report;
+    }
+    if (currentTransactions.length !== existingTransactions.length
+      || (currentTransactions.at(-1)?.record_checksum || null) !== (existingTransactions.at(-1)?.record_checksum || null)) {
+      throw new Error("Repair transaction revision changed during apply; rerun the command.");
+    }
+    if (treeDigest(archiveDirectory) !== target.archive_sha256
+      || sha256(fs.readFileSync(manifestFile)) !== target.manifest_sha256) {
+      throw new Error(`Version archive changed during repair apply: ${iterationId}.`);
+    }
+    const transaction = {
+      schema_version: 1,
+      sequence,
+      transaction_id: transactionId,
+      transaction_type: "archive-invalidation",
+      idempotency_key: idempotencyKey,
+      occurred_at: new Date().toISOString(),
+      target,
+      correction: { actor, reason, evidence },
+      previous_checksum: existingTransactions.at(-1)?.record_checksum || null,
+    };
+    transaction.record_checksum = sha256(stableJson(transaction));
+    atomicWrite(path.join(root, ...transactionPath.split("/")), `${JSON.stringify(transaction, null, 2)}\n`);
+    report.applied = true;
+    report.transaction.previous_checksum = transaction.previous_checksum;
+    report.eligibility = { iteration_id: iterationId, current: "invalidated", source_transaction_id: transactionId };
+    return report;
+  } finally {
+    if (lock !== undefined) fs.closeSync(lock);
+    fs.rmSync(lockFile, { force: true });
+  }
+}

package/lib/toml-hooks.mjs

@@ -14,7 +14,6 @@ export const HOOK_EVENTS = [
 ];
 
 const HOOK_COMMAND = "node .workflow/tools/hooks/hook-event.mjs";
-const LEGACY_HOOK_COMMAND = "node .ai-delivery/hooks/hook-event.mjs";
 
 function hookBlock(event, newline) {
   return [
@@ -102,9 +101,8 @@ export function mergeHookConfig(existing, { force = false } = {}) {
   const newline = existing.includes("\r\n") ? "\r\n" : "\n";
   let text = existing.trimEnd();
   const actions = [];
-  if (text.includes(LEGACY_HOOK_COMMAND)) {
-    text = text.replaceAll(LEGACY_HOOK_COMMAND, HOOK_COMMAND);
-    actions.push("migrate AI delivery Hook command into .workflow/tools");
+  if (text.includes("node .ai-delivery/hooks/hook-event.mjs")) {
+    throw new Error("Unsupported legacy Hook command; remove the .ai-delivery handler before installing the current Hook.");
   }
   if (force) {
     const refreshed = removeDeliveryHandlerBlocks(text);

package/lib/workflow-manager-governance.mjs

@@ -24,7 +24,6 @@ export const WORKFLOW_MANAGER_GOVERNANCE_SCHEMA_VERSION = "workflow-manager.gove
 const RELATIONS_FILE = ".workflow/control/relations.yaml";
 const SETTINGS_FILE = ".workflow/config/manager-settings.json";
 const RECEIPTS_ROOT = ".workflow/control/receipts";
-const EVENTS_FILE = ".workflow/control/events/workflow-manager-events.jsonl";
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,191}$/;
 const SAFE_ENTITY_TYPE = /^[a-z][a-z0-9-]{0,63}$/;
 const RELATION_TYPES = new Set([
@@ -59,18 +58,6 @@ function contained(root, relative) {
   return absolute;
 }
 
-function atomicWrite(file, content) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(temporary, content, { encoding: "utf8", flag: "wx" });
-  try {
-    fs.renameSync(temporary, file);
-  } catch (error) {
-    fs.rmSync(temporary, { force: true });
-    throw error;
-  }
-}
-
 function requireHuman(actor) {
   if (!/^human:[A-Za-z0-9._@/-]+$/.test(String(actor || ""))) {
     throw new Error("Governed confirmation requires actor human:<identity>");
@@ -92,16 +79,13 @@ function receiptFiles(root) {
 
 function replay(root, action, input, subject = null) {
   if (!input.idempotency_key) return null;
-  const legacyRequestChecksum = checksum({ action, input });
-  const governedRequestChecksum = workflowManagerRequestChecksum(action, input, subject);
+  const expectedRequestChecksum = workflowManagerRequestChecksum(action, input, subject);
   for (const file of receiptFiles(root)) {
     try {
       const receipt = JSON.parse(fs.readFileSync(file, "utf8"));
       if (receipt.action !== action || receipt.idempotency_key !== input.idempotency_key) continue;
-      const legacy = receipt.request_checksum === legacyRequestChecksum;
-      const governed = receipt.request_checksum === governedRequestChecksum
-        && (receipt.subject ?? null) === subject;
-      if (!legacy && !governed) {
+      if (receipt.request_checksum !== expectedRequestChecksum
+          || (receipt.subject ?? null) !== subject) {
         throw new Error("Idempotency key was already used for a different request");
       }
       return receipt;
@@ -112,34 +96,6 @@ function replay(root, action, input, subject = null) {
   return null;
 }
 
-function record(root, action, input, detail = {}) {
-  const timestamp = new Date().toISOString();
-  const receipt = {
-    schema_version: 1,
-    receipt_id: `WMG-${crypto.randomUUID()}`,
-    action,
-    actor: input.actor,
-    idempotency_key: input.idempotency_key || null,
-    request_checksum: checksum({ action, input }),
-    applied_at: timestamp,
-    ...detail,
-  };
-  receipt.receipt_checksum = checksum(receipt);
-  atomicWrite(contained(root, `${RECEIPTS_ROOT}/${receipt.receipt_id}.json`), `${JSON.stringify(receipt, null, 2)}\n`);
-  const event = {
-    schema_version: 1,
-    event_id: `WME-${crypto.randomUUID()}`,
-    type: `workflow-manager.${action}`,
-    occurred_at: timestamp,
-    receipt_id: receipt.receipt_id,
-    subject: detail.subject || null,
-  };
-  const eventFile = contained(root, EVENTS_FILE);
-  fs.mkdirSync(path.dirname(eventFile), { recursive: true });
-  fs.appendFileSync(eventFile, `${JSON.stringify(event)}\n`, "utf8");
-  return { receipt, event };
-}
-
 function relationsDocument(root) {
   const file = contained(root, RELATIONS_FILE);
   if (!fs.existsSync(file)) return { file, document: { schema_version: 1, revision: 0, relations: [] }, checksum: null };

package/lib/workspace.mjs

@@ -4,7 +4,6 @@ import { spawnSync } from "node:child_process";
 import { parse as parseYaml, stringify as stringifyYaml } from "./yaml-runtime.mjs";
 
 export const WORKSPACE_CONFIG = path.join(".workflow", "config", "workspace.yaml");
-export const LEGACY_WORKSPACE_CONFIG = path.join(".ai-delivery", "workspace.yaml");
 
 function toPosix(value) {
   return value.replaceAll("\\", "/");
@@ -114,7 +113,7 @@ function initializeWorkflowRepository(workspaceRoot, branch, remote, heads, acti
     const current = gitBranch(workspaceRoot);
     if (current !== branch) {
       if (gitHasCommit(workspaceRoot)) {
-        throw new Error(`Existing workflow repository must already use ${branch}; automatic migration is not supported.`);
+        throw new Error(`Existing workflow repository must already use ${branch}; automatic branch changes are not supported.`);
       }
       if (!dryRun) runGit(workspaceRoot, ["symbolic-ref", "HEAD", `refs/heads/${branch}`]);
     }
@@ -172,7 +171,7 @@ export function validateCodePath(workspaceRoot, codePath = "code") {
   if (!normalized || normalized.includes("/") || normalized === "." || normalized === "..") {
     throw new Error("Code path must be a relative direct child directory.");
   }
-  if (new Set([".git", ".workflow", ".ai-delivery", ".agents", ".codex"]).has(normalized)) {
+  if (new Set([".git", ".workflow", ".agents", ".codex"]).has(normalized)) {
     throw new Error(`Reserved code path: ${normalized}`);
   }
   const absolute = path.resolve(workspaceRoot, normalized);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
   "type": "module",
   "repository": {
@@ -22,7 +22,7 @@
     "skills"
   ],
   "scripts": {
-    "test": "node --test verification/*.test.mjs",
+    "test": "node --test --test-concurrency=4 verification/*.test.mjs",
     "manager:build": "npm --prefix manager run build",
     "skills:validate": "node bin/validate-skills.mjs",
     "audit:generate": "node audit/generate-all.mjs",

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/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Assemble Release"
-  short_description: "Validate version lineage and aggregate release materials"
+interface:
+  display_name: "Assemble Release"
+  short_description: "Validate version lineage and aggregate release materials"
   default_prompt: "Use $ai-delivery-assemble-release to validate both repositories, calculate the version closure, and assemble its candidate."

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/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/06-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.