ai-delivery-workflow 0.2.2

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +1,7 @@
+# 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.
+
+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.

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

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const ELIGIBLE_STATUSES = new Set(["release-ready", "released", "included-in-release"]);
+
+function parseArgs(argv) {
+  const options = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const key = argv[index];
+    if (!key.startsWith("--")) throw new Error(`Unexpected argument: ${key}`);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      options.set(key, true);
+      continue;
+    }
+    options.set(key, next);
+    index += 1;
+  }
+  return options;
+}
+
+function required(options, name) {
+  const value = options.get(name);
+  if (value === undefined || value === true || String(value).trim() === "") {
+    throw new Error(`Missing required option: ${name}`);
+  }
+  return String(value).trim();
+}
+
+function readLineage(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read lineage JSON ${file}: ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.versions) || !parsed.versions.length) {
+    throw new Error("Lineage must contain a non-empty versions array.");
+  }
+  return parsed;
+}
+
+function repositoriesFromWorkspace(workspaceRoot) {
+  const root = path.resolve(workspaceRoot);
+  const file = path.join(root, ".workflow", "config", "workspace.yaml");
+  const text = fs.readFileSync(file, "utf8");
+  const section = (name) => text.match(new RegExp(`^${name}:\\s*\\r?\\n((?:[ \\t]+.*(?:\\r?\\n|$))*)`, "m"))?.[1] || "";
+  const value = (body, name) => {
+    const raw = body.match(new RegExp(`^\\s+${name}:\\s*(.+?)\\s*$`, "m"))?.[1]?.replace(/^['"]|['"]$/g, "");
+    return raw && raw !== "null" ? raw : null;
+  };
+  const codeSection = section("code_repository");
+  const workflowSection = section("workflow_repository");
+  const rawPath = value(codeSection, "path");
+  if (!rawPath) throw new Error(`Workspace configuration is missing code_repository.path: ${file}`);
+  const codePath = rawPath;
+  const codeRepo = path.resolve(root, codePath);
+  const relative = path.relative(root, codeRepo);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Workspace code repository path is invalid: ${codePath}`);
+  }
+  const repoId = value(codeSection, "repo_id");
+  return {
+    codeRepo,
+    workflowRepo: root,
+    repoId,
+    codeRemote: value(codeSection, "remote"),
+    workflowRemote: value(workflowSection, "remote"),
+  };
+}
+
+function orderedVersions(versions) {
+  const byId = new Map();
+  const successor = new Map();
+  for (const version of versions) {
+    if (!version?.version_id) throw new Error("Every lineage entry requires version_id.");
+    if (byId.has(version.version_id)) throw new Error(`Duplicate version ID: ${version.version_id}`);
+    byId.set(version.version_id, version);
+  }
+  for (const version of versions) {
+    if (version.predecessor_id !== null && version.predecessor_id !== undefined && version.predecessor_id !== "") {
+      if (!byId.has(version.predecessor_id)) {
+        throw new Error(`Version ${version.version_id} has missing predecessor ${version.predecessor_id}.`);
+      }
+      if (successor.has(version.predecessor_id)) {
+        throw new Error(`Version lineage branches after ${version.predecessor_id}; releases require one cumulative line.`);
+      }
+      successor.set(version.predecessor_id, version.version_id);
+    }
+  }
+  const roots = versions.filter((version) => version.predecessor_id === null
+    || version.predecessor_id === undefined
+    || version.predecessor_id === "");
+  if (roots.length !== 1) throw new Error(`Version lineage requires exactly one root; found ${roots.length}.`);
+
+  const ordered = [];
+  const visited = new Set();
+  let current = roots[0];
+  while (current) {
+    if (visited.has(current.version_id)) throw new Error(`Version lineage contains a cycle at ${current.version_id}.`);
+    visited.add(current.version_id);
+    ordered.push(current);
+    current = byId.get(successor.get(current.version_id));
+  }
+  if (visited.size !== versions.length) throw new Error("Version lineage is disconnected or cyclic.");
+  return ordered;
+}
+
+function git(repo, args) {
+  const result = spawnSync("git", args, { cwd: repo, encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) throw new Error(`Git validation failed: git ${args.join(" ")}: ${result.stderr.trim()}`);
+  return result.stdout.trim();
+}
+
+function validateRemoteTag(remote, tag, expectedCommit) {
+  if (!remote) return;
+  const reference = `refs/tags/${tag}`;
+  const result = spawnSync("git", ["ls-remote", "--tags", remote, reference, `${reference}^{}`], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    throw new Error(`Remote tag validation failed for ${tag}: ${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 tag ${tag}: ${remote}`);
+  if (!commits.includes(expectedCommit.toLowerCase())) {
+    throw new Error(`Remote tag ${tag} does not resolve to expected commit ${expectedCommit}.`);
+  }
+}
+
+function validateAdjacentAncestry(repo, selected, currentProduction, commitField, label) {
+  const chain = currentProduction
+    ? [currentProduction, ...selected.filter((version) => version.version_id !== currentProduction.version_id)]
+    : selected;
+  for (let index = 1; index < chain.length; index += 1) {
+    const predecessor = chain[index - 1];
+    const successor = chain[index];
+    const result = spawnSync(
+      "git",
+      ["merge-base", "--is-ancestor", predecessor[commitField], successor[commitField]],
+      { cwd: repo, encoding: "utf8", windowsHide: true },
+    );
+    if (result.status !== 0) {
+      throw new Error(
+        `${label} ancestry edge ${predecessor.version_id} -> ${successor.version_id} is not cumulative.`,
+      );
+    }
+  }
+}
+
+function validateGit(repo, selected, currentProduction, remote) {
+  for (const version of selected) {
+    const resolved = git(repo, ["rev-list", "-n", "1", version.version_ready_tag]);
+    if (resolved.toLowerCase() !== version.candidate_commit.toLowerCase()) {
+      throw new Error(`Tag ${version.version_ready_tag} does not resolve to candidate commit ${version.candidate_commit}.`);
+    }
+    validateRemoteTag(remote, version.version_ready_tag, version.candidate_commit);
+  }
+  validateAdjacentAncestry(repo, selected, currentProduction, "candidate_commit", "Code");
+}
+
+function validateWorkflowGit(repo, selected, currentProduction, remote) {
+  for (const version of selected) {
+    const resolved = git(repo, ["rev-list", "-n", "1", version.workflow_ready_tag]);
+    if (resolved.toLowerCase() !== version.workflow_commit.toLowerCase()) {
+      throw new Error(`Workflow tag ${version.workflow_ready_tag} does not resolve to workflow commit ${version.workflow_commit}.`);
+    }
+    validateRemoteTag(remote, version.workflow_ready_tag, version.workflow_commit);
+    if (path.isAbsolute(version.artifact_manifest) || version.artifact_manifest.replaceAll("\\", "/").split("/").includes("..")) {
+      throw new Error(`Version ${version.version_id} has an invalid workflow manifest path.`);
+    }
+    const manifest = git(repo, ["show", `${version.workflow_ready_tag}:${version.artifact_manifest.replaceAll("\\", "/")}`]);
+    const checksum = crypto.createHash("sha256").update(manifest.endsWith("\n") ? manifest : `${manifest}\n`).digest("hex");
+    if (checksum.toLowerCase() !== version.artifact_sha256.toLowerCase()) {
+      throw new Error(`Workflow manifest checksum mismatch for ${version.version_id}.`);
+    }
+  }
+  validateAdjacentAncestry(repo, selected, currentProduction, "workflow_commit", "Workflow");
+}
+
+export function planRelease(lineage, request, options = {}) {
+  const ordered = orderedVersions(lineage.versions);
+  const targetIndex = ordered.findIndex((version) => version.version_id === request.target_version);
+  if (targetIndex < 0) throw new Error(`Target version is not in the cumulative line: ${request.target_version}`);
+
+  const currentId = lineage.current_production_version || null;
+  const currentIndex = currentId === null ? -1 : ordered.findIndex((version) => version.version_id === currentId);
+  if (currentId !== null && currentIndex < 0) {
+    throw new Error(`Current production version is not in the cumulative line: ${currentId}`);
+  }
+  if (targetIndex < currentIndex) {
+    throw new Error(`Target ${request.target_version} is older than current production ${currentId}; use image rollback instead.`);
+  }
+
+  const target = ordered[targetIndex];
+  const newlyIncluded = ordered.slice(currentIndex + 1, targetIndex + 1);
+  const releaseEvidence = targetIndex === currentIndex ? [target] : newlyIncluded;
+  const dependencyClosure = ordered.slice(0, targetIndex + 1);
+  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"}.`);
+    }
+    if (!version.candidate_id || !version.candidate_commit || !version.artifact_manifest || !version.artifact_sha256) {
+      throw new Error(`Version ${version.version_id} is missing immutable candidate or material identity.`);
+    }
+    if (!version.version_ready_tag) {
+      throw new Error(`Version ${version.version_id} requires an immutable version-ready tag.`);
+    }
+    if (!version.workflow_commit || !version.workflow_ready_tag) {
+      throw new Error(`Version ${version.version_id} requires an immutable workflow-ready tag and commit.`);
+    }
+    if (options.repoId && version.repo_id !== options.repoId) {
+      throw new Error(`Version ${version.version_id} references repository ${version.repo_id || "missing"}; expected ${options.repoId}.`);
+    }
+  }
+
+  if (!options.skipGit) {
+    validateGit(
+      path.resolve(options.repo || process.cwd()),
+      dependencyClosure,
+      null,
+      options.codeRemote || null,
+    );
+    validateWorkflowGit(
+      path.resolve(options.workflowRepo || process.cwd()),
+      dependencyClosure,
+      null,
+      options.workflowRemote || null,
+    );
+  }
+
+  return {
+    schema_version: 1,
+    release_id: request.release_id,
+    product_id: lineage.product_id,
+    requested_by: request.requested_by,
+    rationale: request.rationale,
+    target_environment: "production",
+    current_production_version: currentId,
+    target_version: target.version_id,
+    mode: targetIndex === currentIndex ? "same-version-redeploy" : "incremental",
+    newly_included_versions: newlyIncluded.map((version) => version.version_id),
+    dependency_closure: dependencyClosure.map((version) => version.version_id),
+    target: {
+      version_id: target.version_id,
+      candidate_id: target.candidate_id,
+      candidate_commit: target.candidate_commit,
+      version_ready_tag: target.version_ready_tag,
+      workflow_commit: target.workflow_commit,
+      workflow_ready_tag: target.workflow_ready_tag,
+      artifact_manifest: target.artifact_manifest,
+      artifact_sha256: target.artifact_sha256,
+      repo_id: target.repo_id || options.repoId || null,
+    },
+    requires_fresh_environment_snapshot: true,
+    requires_fresh_verification: true,
+    requires_fresh_approval: true,
+    rollback_strategy: "previous-immutable-image-digest",
+  };
+}
+
+function main(argv) {
+  const options = parseArgs(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 };
+  const result = planRelease(readLineage(lineageFile), {
+    release_id: required(options, "--release-id"),
+    target_version: required(options, "--target"),
+    requested_by: required(options, "--requested-by"),
+    rationale: required(options, "--rationale"),
+  }, {
+    repo: options.get("--repo") || configured.codeRepo,
+    workflowRepo: options.get("--workflow-repo") || configured.workflowRepo,
+    repoId: configured.repoId,
+    codeRemote: configured.codeRemote,
+    workflowRemote: configured.workflowRemote,
+    skipGit: options.get("--skip-git") === true,
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

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

@@ -0,0 +1,59 @@
+---
+name: ai-delivery-bootstrap
+description: Inspect a project before normal AI delivery execution, classify empty, brownfield, initialized, interrupted, and inconsistent states, safely install missing project-scoped workflow files, generate draft repository context, and route the next skill or recoverable task. Use at the beginning of a new conversation, in an unfamiliar repository, after a restart or interruption, when delivery tracking files may be absent, or when the correct next workflow node is unknown.
+---
+
+# Bootstrap AI Delivery
+
+Establish enough verified project context to resume or begin work without relying on chat history.
+
+## Dual-Repository Workspace
+
+Treat the directory containing `.workflow/config/workspace.yaml` as the workflow repository and resolve the single code repository only from `code_repository.path`. Never infer a second code root or run code Git commands from the workflow root. Require the workflow Git root to ignore the exact code child path while keeping `.workflow/` tracked. On restart, prefer `.workflow/control/tasks/*.yaml` and the newest shared checkpoint when local runtime is absent; stop when local and shared revisions disagree.
+
+## Artifact Location
+
+Write every workflow document produced by this skill under project `.workflow/`. Place version-scoped node outputs in `.workflow/iterations/<iteration-id>/<node-id>/` unless an approved contract assigns `.workflow/delivery/`, `.workflow/standards/`, `.workflow/product/`, `.workflow/architecture/`, or `.workflow/experience/`. Do not relocate source code, automated test source, repository configuration, or non-document build artifacts.
+
+## Inspect First
+
+1. Locate the project root without creating files.
+2. After `init`, run `node .workflow/tools/bootstrap/bootstrap.mjs inspect` from the project root. Use packaged `ai-delivery inspect <project-root>` only before a project-local runtime exists.
+3. Read the returned `state`, errors, runtime recommendation, codebase summary, both Git states, shared checkpoint state, sync warnings, and recommended skill.
+4. Do not mutate the project before this classification.
+
+## Natural-Language Entry
+
+Treat ordinary user messages such as “开始”, “继续”, “下一步”, “现在做到哪了”, a direct product idea, or an explicit release request as sufficient intent. Select and invoke every required project Skill and CLI internally. Never ask the user to type a Skill name or run a workflow command. Ask the user only for business facts, material review, an explicit Gate decision, or authority for an external side effect.
+
+## First Task Identity
+
+When inspection returns `workflow-ready`, there are no task shards, and the formal registry has no delivery artifact:
+
+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.
+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.
+
+## Route By State
+
+- `empty-uninitialized`: use packaged `ai-delivery bootstrap` because no project-local runtime exists, read the generated report, then invoke `$ai-delivery-define-product`. Ask one business question at a time; do not invent the initial need.
+- `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.
+
+## 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.
+
+## Resume Boundary
+
+Codex lifecycle Hooks provide audit and heartbeat data only. Versioned Evolution Hooks may return `pass`, `warn`, or an approved `block`, but they never select or complete tasks and never mutate formal workflow state. A bootstrap report may recommend recovery, but `$ai-delivery-checkpoint-task` remains authoritative for task order, dependency readiness, worktree reconciliation, and idempotent continuation. Route pending feedback and extension evaluation to `$ai-delivery-evolve-workflow` only at a task, version, or explicit review safe point.
+
+Read [bootstrap-contract.md](references/bootstrap-contract.md) for classifications, generated artifacts, safety constraints, and handoff requirements.

package/skills/ai-delivery-bootstrap/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bootstrap AI Delivery"
+  short_description: "Inspect project state and route the next workflow action"
+  default_prompt: "Use $ai-delivery-bootstrap to inspect the dual-repository workspace, recover shared checkpoints, or initialize the minimum delivery context."

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

@@ -0,0 +1,70 @@
+# Bootstrap Contract
+
+## Classification
+
+Return exactly one state:
+
+- `empty-uninitialized`: no complete workflow installation and no source, test, manifest, build, deployment, or infrastructure evidence;
+- `codebase-uninitialized`: no complete workflow installation and at least one codebase evidence file;
+- `workflow-ready`: complete, parseable project-scoped installation with no resumable task;
+- `workflow-interrupted`: complete installation with a preparing, running, checkpointed, pending-review, blocked, or interrupted task;
+- `workflow-inconsistent`: partial installation, malformed required file, project identity mismatch, missing installed skill, or missing task dependency.
+
+Ignore `.git`, project workflow directories, dependency caches, generated builds, coverage, virtual environments, and vendor directories when deciding whether product code exists. Exclude secret and private-key files from context artifacts.
+
+## Read-Only Inspection
+
+After installation, `node .workflow/tools/bootstrap/bootstrap.mjs inspect` is the self-contained entrypoint and must not write project files. Before installation, the packaged `ai-delivery inspect <project-root>` provides the same contract. Report:
+
+- installation presence and missing required files;
+- project and iteration identity;
+- artifact, active-node, blocked-node, and pending-Gate counts;
+- active, queued, dependency-ready, and recommended task identity, including `next_action_owner`;
+- code evidence, technologies, file categories, and sensitive-file exclusion count;
+- Git repository, branch, HEAD, and dirty paths when available;
+- errors, warnings, recommended skill, action, and whether user input is required.
+
+## Bootstrap Mutation
+
+`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 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.
+
+For a newly initialized project or a ready project without a recoverable task, create one timestamped run under:
+
+```text
+.workflow/delivery/bootstrap/
+  latest.yaml
+  runs/<bootstrap-run-id>/
+    project-state-report.yaml
+    repository-baseline.yaml
+    codebase-inventory.csv
+    context-index.csv
+    adoption-assessment.md
+    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.
+
+## Artifact Meaning
+
+- `project-state-report.yaml`: classification inputs, result, runtime state, errors, and recommendation.
+- `repository-baseline.yaml`: observed Git identity, technologies, file categories, and candidate commands.
+- `codebase-inventory.csv`: normalized observed manifests, source, tests, build, configuration, deployment, and infrastructure files.
+- `context-index.csv`: path, category, technology, purpose, size, checksum, read priority, and scan status.
+- `adoption-assessment.md`: Chinese human-readable gaps and the boundary between observed behavior and approved intent.
+- `bootstrap-plan.yaml`: proposed next tasks, sequence, dependencies, and owning skills. It is planning input, not registered runtime state.
+
+## Handoff
+
+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 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.
+
+For a brownfield project, first let the user correct the observed repository context, then use product discovery to establish intended behavior. Do not route directly to development because code exists.
+
+For a ready project without runtime tasks, use formal artifact and Gate state. A bootstrap diagnostic artifact does not count as delivery progress and must not prevent routing an otherwise empty project to product discovery.

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

@@ -0,0 +1,63 @@
+---
+name: ai-delivery-checkpoint-task
+description: Persist, checkpoint, finish, recover, and archive version-scoped AI delivery task state independently of chat history, while correlating Codex lifecycle Hook events with the active task. Use before and after every delivery-stage execution, at meaningful milestones, before compaction or interruption, after a crash or restart, when a release-ready, released, or abandoned planned version must be archived, and whenever recorded state must be reconciled with Git and workspace reality.
+---
+
+# Checkpoint Delivery Task
+
+Treat explicit task snapshots as authoritative. Treat Hook events as an audit trail and heartbeat, never as proof that a stage completed.
+
+## Artifact Location
+
+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.
+
+## Start Or Resume
+
+1. Locate the project root and shared state root.
+2. At iteration planning, register every known iteration task as `queued`, including its stable `sequence` and `depends_on` task IDs. When a later node derives a dynamic task group, register that complete group before executing its first task. This lets a restart distinguish completed work from work that has not started.
+3. Read Bootstrap's `next_action_owner` before any recovery. Only when it is `agent`, run `scripts/task-state.mjs recover --iteration-id <iteration-id>` if runtime state exists and use `iterations[].recommended_task_id`; do not infer the next task from chat history. For `user` or `external`, apply the zero-mutation boundary in step 6 instead.
+4. Compare the recommended task, branch, worktree, dirty paths, artifacts, dependencies, and evidence with reality.
+5. Mark a stale `running` task `interrupted` only after reconciliation.
+6. Read `next_action_owner` before activation. Activate a recommended `queued`, `preparing`, `checkpointed`, `blocked`, or `interrupted` task only when the owner is `agent`. When it is `user`, ask exactly the recorded question and make no workflow, task, checkpoint, artifact, or Git mutation. When it is `external`, report the recorded wait condition without mutation. After the required input arrives, transfer ownership through `activate` with `--next-action-owner agent` and a new idempotent `--next-action`; this command atomically hydrates a missing local runtime snapshot from the shared shard before continuing.
+7. Create or update the task snapshot before any stage mutation. Include goal, scope, input artifact versions, standards, branch, worktree, planned outputs, completed steps, blockers, and next action.
+8. Refuse to start when the snapshot cannot be written atomically.
+9. Publish one task with `task-state.mjs publish --task-id <id>`. It may commit only that task shard, its checkpoints, and task-owned artifacts; refuse unrelated dirty paths. Push only when the user explicitly supplies `--push`.
+
+Use statuses `queued`, `preparing`, `running`, `checkpointed`, `pending-review`, `blocked`, `interrupted`, `completed`, `failed`, and `abandoned`.
+
+## 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.
+
+## Finish
+
+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.
+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.
+
+## Archive A Version
+
+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.
+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.
+
+## Hook Boundary
+
+Use `scripts/hook-event.mjs` for redacted lifecycle events and heartbeats. It also dispatches schema 1 Evolution events to the guarded Evolution CLI. Copy it into `.workflow/tools/hooks/` and merge `assets/codex-hook-config.toml` into project `.codex/config.toml`. Require normal Codex Hook trust review; never bypass Hook trust. Trial warnings fail open; only checksum-approved blocking extensions may stop a transition.
+
+## Writer Boundary
+
+Use `scripts/task-state.mjs` as the only writer for runtime task snapshots, checkpoints, recovery state, active-task markers, and version archives. Use `.workflow/tools/state/state.mjs` as the only writer for formal workflow, artifact, and Gate state. Use `.workflow/tools/evolution/evolve.mjs` as the only writer for feedback, proposal, extension, experiment, and evolution-decision state. Never hand-edit controlled files or let a Hook mutate formal state. If a script fails, stop and repair the cause.
+
+Read [checkpoint-contract.md](references/checkpoint-contract.md) for commands, state fields, recovery rules, and the verified Codex 0.144.2 event set. Read [checkpoint-recovery.zh-CN.md](references/checkpoint-recovery.zh-CN.md) for the ten-task interruption example and file responsibilities. Use the templates in `assets/runtime-template/`.

package/skills/ai-delivery-checkpoint-task/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Checkpoint Delivery Task"
+  short_description: "Persist task checkpoints, hook events, and resume context"
+  default_prompt: "Use $ai-delivery-checkpoint-task to start, checkpoint, publish, finish, or recover a shared delivery task."

package/skills/ai-delivery-checkpoint-task/assets/codex-hook-config.toml

@@ -0,0 +1,92 @@
+[features]
+hooks = true
+
+[[hooks.SessionStart]]
+matcher = ""
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.UserPromptSubmit]]
+matcher = ""
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.PreToolUse]]
+matcher = ""
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.PermissionRequest]]
+matcher = ""
+[[hooks.PermissionRequest.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.PostToolUse]]
+matcher = ""
+[[hooks.PostToolUse.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.PreCompact]]
+matcher = ""
+[[hooks.PreCompact.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.PostCompact]]
+matcher = ""
+[[hooks.PostCompact.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.SubagentStart]]
+matcher = ""
+[[hooks.SubagentStart.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.SubagentStop]]
+matcher = ""
+[[hooks.SubagentStop.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false
+
+[[hooks.Stop]]
+matcher = ""
+[[hooks.Stop.hooks]]
+type = "command"
+command = "node .workflow/tools/hooks/hook-event.mjs"
+commandWindows = "node .workflow/tools/hooks/hook-event.mjs"
+timeout = 5
+async = false

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

@@ -0,0 +1,15 @@
+# Task Recovery
+
+## Objective
+
+## Recorded State
+
+## Reconciled Workspace And Git State
+
+## Completed Work And Evidence
+
+## Blockers And Risks
+
+## Next Idempotent Action
+
+## Actions Requiring Fresh Readback Or Human Authority