ai-delivery-workflow 0.2.2

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

@@ -0,0 +1,30 @@
+{
+  "task_id": "TASK-0001",
+  "iteration_id": "ITER-0001",
+  "node": "development",
+  "skill": "ai-delivery-develop-iteration",
+  "status": "queued",
+  "sequence": 1,
+  "depends_on": [],
+  "attempt": 1,
+  "goal": "",
+  "scope": [],
+  "input_artifacts": [],
+  "standards": [],
+  "branch": null,
+  "worktree": null,
+  "state_root": null,
+  "planned_outputs": [],
+  "actual_outputs": [],
+  "completed_steps": [],
+  "blockers": [],
+  "next_action": "",
+  "next_action_owner": "agent",
+  "evidence": [],
+  "created_at": null,
+  "started_at": null,
+  "updated_at": null,
+  "finished_at": null,
+  "archived_at": null,
+  "archive_path": null
+}

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

@@ -0,0 +1,10 @@
+{
+  "iteration_id": "ITER-0001",
+  "version_status": "released",
+  "release_id": "REL-0001",
+  "evidence": [],
+  "task_count": 0,
+  "archived_at": null,
+  "archive_path": null,
+  "tasks": []
+}

package/skills/ai-delivery-checkpoint-task/references/checkpoint-contract.md

@@ -0,0 +1,95 @@
+# Task Checkpoint Contract
+
+## Runtime Layout
+
+Portable, Git-tracked state:
+
+```text
+.workflow/control/
+  tasks/<task-id>.yaml
+  checkpoints/<task-id>/<checkpoint-id>.yaml
+  archives/versions/<version-id>/
+    version-manifest.json
+    tasks/<task-id>/task.json
+    tasks/<task-id>/checkpoints/...
+```
+
+Local ignored state:
+
+```text
+.workflow/delivery/runtime/
+  tasks/<task-id>.json
+  checkpoints/<task-id>/<timestamp>.json
+  events/<task-or-session-id>.jsonl
+  heartbeats/<task-or-session-id>.json
+  resumes/<task-id>.md
+  archive/
+    index/versions/<iteration-id>.json
+    index/tasks/<task-id>.json
+    versions/<iteration-id>/version-manifest.json
+    versions/<iteration-id>/tasks/<task-id>/...
+```
+
+Keep `.workflow/delivery/runtime/` local and ignored. Persist durable stage outputs and final evidence in `.workflow/iterations/<iteration-id>/<node-id>/`.
+
+`task-state.mjs` is the only runtime-state writer. Do not directly edit task JSON, checkpoint JSON, active-task markers, recovery output, or archive indexes. Formal workflow and artifact state belong to `.workflow/tools/state/state.mjs`; do not edit its YAML or JSONL streams directly.
+
+When the installed Evolution CLI exists, `init`, `activate`, `checkpoint`, `finish`, and `archive-version` emit idempotent schema 1 `task.before`, `task.after`, and `task.failed` events. An approved blocking `task.before` result stops the task command before mutation. Hook dispatch failures otherwise fail open as warnings and never replace checkpoint state as the completion authority.
+
+## Commands
+
+Resolve `scripts/task-state.mjs` relative to this skill directory when invoking the bundled script.
+
+```text
+node scripts/task-state.mjs init --task-id TASK-0001 --iteration-id ITER-0001 --node development --skill ai-delivery-develop-iteration --goal "Implement slice" --next-action "Derive work packages" --next-action-owner agent
+node scripts/task-state.mjs init --task-id TASK-0002 --iteration-id ITER-0001 --node test --skill ai-delivery-verify-candidate --goal "Verify candidate" --status queued --sequence 2 --depends-on TASK-0001 --next-action "Run candidate verification"
+node scripts/task-state.mjs recover --iteration-id ITER-0001
+node scripts/task-state.mjs activate --task-id TASK-0002
+node scripts/task-state.mjs checkpoint --task-id TASK-0001 --status checkpointed --completed-step "Public contract validated" --next-action "Create worktrees"
+node scripts/task-state.mjs finish --task-id TASK-0001 --status completed --next-action "Run candidate verification"
+node scripts/task-state.mjs finish --task-id TASK-0001 --status interrupted --next-action "Which user group is affected first?" --next-action-owner user
+node scripts/task-state.mjs recover --mark-interrupted --stale-minutes 15
+node scripts/task-state.mjs recover --include-closed
+node scripts/task-state.mjs archive-version --iteration-id ITER-0001 --version-status released --release-id REL-0001 --evidence "production-verification@1"
+node scripts/task-state.mjs archive-version --iteration-id VER-0002 --version-status release-ready --candidate-id CAND-0002 --evidence "candidate-verification@2"
+node scripts/task-state.mjs archive-version --iteration-id VER-0003 --version-status release-ready --candidate-id CAND-0003 --evidence "candidate-verification@3" --portable-only
+node scripts/task-state.mjs publish --task-id TASK-0001
+node scripts/task-state.mjs publish --task-id TASK-0001 --push
+```
+
+Every state transition writes both the local runtime snapshot and the portable task shard/checkpoint. `publish` refuses unrelated dirty paths, commits only the selected task scope, and does not push unless `--push` is explicit. When local runtime is missing, `recover` reconstructs an `agent`-owned task from shared shards; `user` and `external` wait states remain read-only until an explicit `activate` transfer. A revision or semantic-checksum mismatch is a hard conflict, not a last-writer-wins update.
+
+For an installed dual-repository project, `task-state.mjs` resolves `code_branch` and `code_commit` from the authoritative `.workflow/config/workspace.yaml` and its configured nested code Git root. The install manifest and task worktree are not workspace identity fallbacks. The task's workflow worktree or workflow branch must never be persisted as code identity. If the workspace configuration is missing, its code path is not a direct child, or the configured code root is not an independent Git repository, the mutation fails instead of recording a fallback identity.
+
+`blockers` represents current unresolved blockers. A `blocked` update replaces that list; any transition to another status clears it. Historical blocker text remains available in prior checkpoints and events.
+
+`next_action_owner` is required in persisted state and has exactly three values: `agent`, `user`, or `external`; only a truly absent field in a legacy snapshot defaults to `agent`, while explicit null, empty, boolean, numeric, or unknown values are invalid. `user` and `external` are zero-mutation wait states. `recover` may report shared wait state but must not hydrate local task or resume files for it. After the required input arrives, `activate` requires both `--next-action-owner agent` and a new idempotent `--next-action`; it may atomically hydrate a missing local runtime snapshot from the matching shared shard and transfer ownership in the same transition. Same-revision local and shared content must have identical semantic checksums. Evidence arrays are ordered sets: replaying an already recorded `--evidence` value does not append a duplicate.
+
+Pass `--state-root` when worktrees must write to one shared primary state directory. Pass `--worktree` during init so the script writes a local `.workflow/delivery/runtime/active-task.json` marker pointing to that state root. Later `checkpoint`, `finish`, and `recover` commands automatically use the marker's shared state root.
+
+Use `finish` only with `completed`, `blocked`, `interrupted`, `failed`, or `abandoned`. Use `checkpoint` for all other statuses.
+
+Register all known iteration tasks as `queued` before execution. `queued` registration does not write `.workflow/delivery/runtime/active-task.json`, so several future tasks may share a worktree safely. `activate` verifies that every `depends_on` task exists and is `completed`, changes the selected task to `running` or `preparing`, writes a new checkpoint, and creates the active task marker for Hook correlation.
+
+`finish` closes an individual task but does not archive it. Default recovery omits closed tasks so they do not consume resume context. Archive the entire planned version after version closeout marks it `release-ready`, after historical production verification marks it `released`, or when explicitly `abandoned`. A release-ready archive requires the immutable candidate ID and verification evidence; a released archive requires release ID and production evidence. Every task in that version must be closed. Archival first writes the portable version package, then removes that version from active shared task/checkpoint collections; `recover` never scans `.workflow/control/archives/`.
+
+## Hook Events
+
+The local Codex 0.144.2 CLI reports stable Hook support for `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, and `Stop`. The project template logs all of them synchronously with a short timeout.
+
+Hooks receive lifecycle JSON on stdin. Redact secrets, cap payload size, append JSONL, and update heartbeat atomically. A Hook may enforce mechanical policy, but it must not infer product completion or mutate approved artifacts.
+
+## Recovery Rules
+
+- Reconcile recorded branch, worktree, dirty files, heartbeat, and next action.
+- Stop without mutation when the recommended task's `next_action_owner` is `user` or `external`; only report the recorded question or wait condition.
+- Keep closed tasks in the current version until version archival, but exclude them from normal recovery output.
+- Determine iteration progress from all task snapshots, including the closed snapshots hidden from the normal task list.
+- Prefer an existing active or interrupted task during recovery. If none exists, recommend the lowest-sequence queued task whose dependencies are all `completed`.
+- Never activate a task with a missing, failed, abandoned, blocked, or otherwise incomplete dependency.
+- Use one portable version archive under `.workflow/control/archives/versions/`; runtime archive copies are disposable and non-authoritative. Pass `--portable-only` when no local detailed copy should be created.
+- Treat a stale `running` task as a recovery candidate, not automatically failed.
+- Resume only from a documented idempotent next action.
+- Re-read remote CI, registries, environments, and production before relying on cached status.
+- Never replay deployment, migration, payment, notification, or destructive steps without readback and authority.
+- Do not store full transcripts, chain-of-thought, credentials, secret values, cookies, or authorization headers.

package/skills/ai-delivery-checkpoint-task/references/checkpoint-recovery.zh-CN.md

@@ -0,0 +1,111 @@
+# Checkpoint 中断恢复机制
+
+## 目标
+
+一个迭代版本包含 10 个任务，前 5 个已经完成，会话在第 6 个开始前中断。下次启动时，AI 必须从持久化状态得出以下结论，而不是依赖聊天记录：
+
+- 迭代共有 10 个任务；
+- `TASK-01` 至 `TASK-05` 已完成；
+- 还有 5 个任务未完成；
+- `TASK-06` 的依赖已经满足；
+- 下一项推荐任务是 `TASK-06`。
+
+## 前提
+
+迭代规划产生的切片任务，以及开发阶段即时拆分出的技术任务，仍由各自正式 CSV 产物维护。Checkpoint 运行时不会替代这些正式计划，而是保存其可恢复执行状态。
+
+在执行一个任务组的第一项任务前，必须先登记该组的全部任务：
+
+```text
+node task-state.mjs init --task-id TASK-01 --iteration-id ITER-01 --node development --skill ai-delivery-develop-iteration --status queued --sequence 1 --goal "任务 1" --next-action "执行任务 1"
+node task-state.mjs init --task-id TASK-02 --iteration-id ITER-01 --node development --skill ai-delivery-develop-iteration --status queued --sequence 2 --depends-on TASK-01 --goal "任务 2" --next-action "执行任务 2"
+...
+node task-state.mjs init --task-id TASK-10 --iteration-id ITER-01 --node development --skill ai-delivery-develop-iteration --status queued --sequence 10 --depends-on TASK-09 --goal "任务 10" --next-action "执行任务 10"
+```
+
+`queued` 任务只登记状态，不占用 `.workflow/delivery/runtime/active-task.json` 活动任务标记。因此，可以安全地预先登记同一工作区中的 10 个任务。
+
+## 正常执行
+
+每个任务按以下顺序执行：
+
+1. `recover --iteration-id ITER-01` 读取迭代状态并取得 `recommended_task_id`。
+2. `activate --task-id <recommended_task_id>` 校验依赖并把任务变成 `running`。
+3. 在有意义的里程碑执行 `checkpoint`，记录已完成步骤、实际输出、证据和幂等下一动作。
+4. 交还控制权或发生可控中断前执行 `finish`，状态使用 `completed`、`blocked`、`failed` 或 `interrupted`。
+5. 下一个任务重新从 `recover` 开始，不能从聊天上下文猜测。
+
+示例：
+
+```text
+node task-state.mjs activate --task-id TASK-05
+node task-state.mjs checkpoint --task-id TASK-05 --status checkpointed --completed-step "测试通过" --evidence "test-result.json" --next-action "校验交付物"
+node task-state.mjs finish --task-id TASK-05 --status completed --actual-output "artifact-05.yaml" --next-action "恢复迭代并选择下一任务"
+```
+
+## 重启恢复
+
+新会话启动时执行：
+
+```text
+node task-state.mjs recover --iteration-id ITER-01
+```
+
+返回结果包含两层信息：
+
+- `tasks`：默认只包含未关闭任务，已完成任务不会占用恢复上下文；
+- `iterations`：使用全部任务快照计算的迭代进度摘要。
+
+前 5 个任务完成后的关键结果如下：
+
+```json
+{
+  "iteration_id": "ITER-01",
+  "total_tasks": 10,
+  "completed_tasks": 5,
+  "remaining_tasks": 5,
+  "ready_task_ids": ["TASK-06"],
+  "recommended_task_id": "TASK-06",
+  "recommended_status": "queued"
+}
+```
+
+然后执行：
+
+```text
+node task-state.mjs activate --task-id TASK-06
+```
+
+`activate` 只有在 `TASK-06` 的所有 `depends_on` 任务都存在且状态为 `completed` 时才会成功。缺失、失败、放弃、阻塞或尚未完成的依赖都会阻止激活。
+
+## 恢复选择规则
+
+`recover` 按以下顺序确定 `recommended_task_id`：
+
+1. 优先恢复 `preparing`、`running`、`checkpointed`、`pending-review`、`blocked` 或 `interrupted` 的已有任务；
+2. 没有活动任务时，从依赖全部完成的 `queued` 任务中选择；
+3. 按 `sequence` 从小到大排序，相同顺序再按 `task_id` 排序；
+4. 没有可执行任务时返回 `null`，并在 `waiting_tasks` 中列出缺失或未完成依赖。
+
+对于生产部署、数据库迁移、付款、通知或破坏性操作，即使任务被推荐，也必须先读取外部真实状态和授权，禁止自动重放。
+
+## 文件职责
+
+| 文件 | 是否持久 | 作用 |
+| --- | --- | --- |
+| 正式迭代计划和技术任务 CSV | 是 | 任务范围、顺序、依赖和交付要求的业务事实来源。 |
+| `.workflow/delivery/workflow-state.yaml` | 是 | 已验证流程节点、Gate 和版本状态。 |
+| `.workflow/delivery/runtime/tasks/<task-id>.json` | 当前版本本地保留 | 权威任务快照，包含 `sequence`、`depends_on`、状态、输出、证据和下一动作。 |
+| `.workflow/delivery/runtime/checkpoints/<task-id>/<时间戳>.json` | 当前版本本地保留 | 每次初始化、激活、里程碑、完成或中断时的不可变状态副本。 |
+| `.workflow/delivery/runtime/resumes/<task-id>.md` | 当前版本本地保留 | 面向 AI 和人的紧凑恢复摘要。 |
+| `.workflow/delivery/runtime/events/<task-id>.jsonl` | 当前版本本地保留 | 初始化、激活、checkpoint、完成和 Hook 的仅追加审计事件。 |
+| `.workflow/delivery/runtime/heartbeats/<task-id>.json` | 当前版本本地保留 | Hook 更新的最近活动心跳，只辅助判断中断，不能证明完成。 |
+| `.workflow/delivery/runtime/active-task.json` | 活动任务期间本地存在 | 将当前工作区和 Hook 关联到唯一活动任务；任务完成后删除。 |
+| `.workflow/control/archives/versions/<iteration-id>/` | 可携带版本归档 | 保存版本 Manifest、关闭任务和共享 checkpoint；归档完成后从活动集合移除，普通恢复不扫描此目录。 |
+| `.workflow/delivery/runtime/archive/versions/<iteration-id>/` | 可丢弃本地副本 | 可保存事件、心跳和恢复摘要等详细本地证据，不作为跨 clone 的权威归档。 |
+
+`.workflow/delivery/runtime/` 应加入 Git 忽略，但在当前项目本地必须保留到版本归档完成。不得忽略整个 `.workflow/`。需要跨机器恢复时，应将该目录保存到受控、加密且访问受限的状态存储，不能只依赖本机磁盘。
+
+## 自动化验证
+
+发行仓库的 `verification/checkpoint-task-state.test.mjs` 包含一个 10 任务场景：预先登记 10 个顺序依赖任务，完成前 5 个，执行恢复并断言推荐 `TASK-QUEUE-06`，随后成功激活第 6 个任务。该测试同时验证未满足依赖时不得提前启动后续任务。

package/skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SECRET_KEY = /^(authorization|cookie|set-cookie|password|passwd|secret|access[_-]?token|refresh[_-]?token|api[_-]?key|private[_-]?key)$/i;
+const MAX_STRING = 8_192;
+const MAX_EVENT = 64 * 1024;
+
+function now() {
+  return new Date().toISOString();
+}
+
+function findUp(start, relative) {
+  let current = path.resolve(start);
+  while (true) {
+    const candidate = path.join(current, relative);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function redact(value, key = "") {
+  if (SECRET_KEY.test(key)) return "[REDACTED]";
+  if (typeof value === "string") {
+    return value
+      .replace(/Bearer\s+[A-Za-z0-9._~+\/-]+=*/gi, "Bearer [REDACTED]")
+      .replace(/\bsk-[A-Za-z0-9_-]{12,}\b/g, "[REDACTED_TOKEN]")
+      .slice(0, MAX_STRING);
+  }
+  if (Array.isArray(value)) return value.slice(0, 100).map((item) => redact(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).slice(0, 200).map(([name, item]) => [name, redact(item, name)]));
+  }
+  return value;
+}
+
+function safeId(value) {
+  return String(value || "unassigned").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 128);
+}
+
+function atomicWrite(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  fs.renameSync(temp, file);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+try {
+  const currentProjectFile = findUp(process.cwd(), path.join(".workflow", "delivery", "project.yaml"));
+  const legacyProjectFile = currentProjectFile
+    ? null
+    : findUp(process.cwd(), path.join("delivery", "project.yaml"));
+  const projectFile = currentProjectFile || legacyProjectFile;
+  if (!projectFile) process.exit(0);
+  const projectRoot = currentProjectFile
+    ? path.dirname(path.dirname(path.dirname(projectFile)))
+    : path.dirname(path.dirname(projectFile));
+  const markerFile = path.join(projectRoot, ".workflow", "delivery", "runtime", "active-task.json");
+  const marker = fs.existsSync(markerFile) ? JSON.parse(fs.readFileSync(markerFile, "utf8")) : null;
+  const raw = await readStdin();
+  const input = raw.trim() ? JSON.parse(raw) : {};
+  const taskId = safeId(process.env.AI_DELIVERY_TASK_ID || marker?.task_id || input.turn_id || input.session_id);
+  const stateRoot = path.resolve(process.env.AI_DELIVERY_STATE_ROOT || marker?.state_root || projectRoot);
+  const workflowRoot = fs.existsSync(path.join(stateRoot, ".workflow", "delivery", "project.yaml"))
+    ? path.join(stateRoot, ".workflow")
+    : stateRoot;
+  if (input.schema_version === 1 && typeof input.event_type === "string") {
+    const evolutionProjectRoot = path.basename(workflowRoot) === ".workflow"
+      ? path.dirname(workflowRoot)
+      : projectRoot;
+    const evolutionCli = path.join(evolutionProjectRoot, ".workflow", "tools", "evolution", "evolve.mjs");
+    if (!fs.existsSync(evolutionCli)) throw new Error(`Evolution CLI is missing: ${evolutionCli}`);
+    const dispatched = spawnSync(process.execPath, [
+      evolutionCli,
+      "hook", "dispatch", "--input", "-", "--project", evolutionProjectRoot,
+    ], {
+      cwd: evolutionProjectRoot,
+      input: raw,
+      encoding: "utf8",
+      timeout: 15_000,
+      windowsHide: true,
+    });
+    if (dispatched.error || dispatched.status !== 0) {
+      throw new Error(dispatched.error?.message || dispatched.stderr || `Evolution Hook exited ${dispatched.status}`);
+    }
+    process.stdout.write(dispatched.stdout);
+    const outcome = JSON.parse(dispatched.stdout);
+    process.exit(outcome.decision === "block" ? 2 : 0);
+  }
+  const runtime = path.join(workflowRoot, "delivery", "runtime");
+  const event = redact({
+    at: now(),
+    task_id: taskId,
+    event_name: input.hook_event_name || input.hookEventName || "unknown",
+    session_id: input.session_id || null,
+    turn_id: input.turn_id || null,
+    agent_id: input.agent_id || null,
+    agent_type: input.agent_type || null,
+    tool_name: input.tool_name || null,
+    input_fields: Object.keys(input).sort(),
+    tool_input_fields: input.tool_input && typeof input.tool_input === "object"
+      ? Object.keys(input.tool_input).sort()
+      : [],
+  });
+  let line = JSON.stringify(event);
+  if (Buffer.byteLength(line, "utf8") > MAX_EVENT) {
+    line = JSON.stringify({ at: event.at, task_id: taskId, event_name: event.event_name, truncated: true });
+  }
+  const eventFile = path.join(runtime, "events", `${taskId}.jsonl`);
+  fs.mkdirSync(path.dirname(eventFile), { recursive: true });
+  fs.appendFileSync(eventFile, `${line}\n`, "utf8");
+  atomicWrite(path.join(runtime, "heartbeats", `${taskId}.json`), {
+    task_id: taskId,
+    updated_at: event.at,
+    event_name: event.event_name,
+    session_id: event.session_id,
+    turn_id: event.turn_id,
+    tool_name: event.tool_name,
+  });
+} catch (error) {
+  process.stderr.write(`ai-delivery hook logger: ${error.message}\n`);
+  process.exitCode = 1;
+}