ai-delivery-workflow 0.2.2

package/lib/skill-validator.mjs

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+const ALLOWED_FRONTMATTER_KEYS = new Set([
+  "name",
+  "description",
+  "license",
+  "allowed-tools",
+  "metadata",
+]);
+const REQUIRED_INTERFACE_FIELDS = ["display_name", "short_description", "default_prompt"];
+
+function readText(file, errors, relative) {
+  if (!fs.existsSync(file)) {
+    errors.push(`${relative} is required`);
+    return null;
+  }
+  return fs.readFileSync(file, "utf8");
+}
+
+function parseMapping(text, errors, relative) {
+  try {
+    const value = parseYaml(text);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      errors.push(`${relative} must contain a YAML mapping`);
+      return null;
+    }
+    return value;
+  } catch (error) {
+    errors.push(`${relative} contains invalid YAML: ${error.message}`);
+    return null;
+  }
+}
+
+function validateSkill(skillDirectory, repositoryRoot, documents) {
+  const errors = [];
+  const directoryName = path.basename(skillDirectory);
+  const relativeSkill = path.relative(repositoryRoot, skillDirectory).replaceAll("\\", "/");
+  const skillFile = path.join(skillDirectory, "SKILL.md");
+  const skillText = readText(skillFile, errors, `${relativeSkill}/SKILL.md`);
+
+  if (skillText !== null) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(skillText);
+    if (!match) {
+      errors.push(`${relativeSkill}/SKILL.md has invalid YAML frontmatter delimiters`);
+    } else {
+      const frontmatter = parseMapping(match[1], errors, `${relativeSkill}/SKILL.md frontmatter`);
+      if (frontmatter) {
+        for (const key of Object.keys(frontmatter)) {
+          if (!ALLOWED_FRONTMATTER_KEYS.has(key)) {
+            errors.push(`${relativeSkill}/SKILL.md has unexpected frontmatter key: ${key}`);
+          }
+        }
+
+        const name = typeof frontmatter.name === "string" ? frontmatter.name.trim() : "";
+        const description = typeof frontmatter.description === "string"
+          ? frontmatter.description.trim()
+          : "";
+
+        if (!name) errors.push(`${relativeSkill}/SKILL.md is missing non-empty name`);
+        if (!description) errors.push(`${relativeSkill}/SKILL.md is missing non-empty description`);
+        if (name && !/^[a-z0-9-]+$/.test(name)) {
+          errors.push(`${relativeSkill}/SKILL.md name must use lowercase hyphen-case`);
+        }
+        if (name && (name.startsWith("-") || name.endsWith("-"))) {
+          errors.push(`${relativeSkill}/SKILL.md name must not start or end with a hyphen`);
+        }
+        if ((name && name.includes("--")) || directoryName.includes("--")) {
+          errors.push(`${relativeSkill}/SKILL.md name must not contain consecutive hyphens`);
+        }
+        if (name && name.length > 64) {
+          errors.push(`${relativeSkill}/SKILL.md name must not exceed 64 characters`);
+        }
+        if (name && name !== directoryName) {
+          errors.push(`${relativeSkill}/SKILL.md frontmatter name must match directory name`);
+        }
+        if (description.includes("<") || description.includes(">")) {
+          errors.push(`${relativeSkill}/SKILL.md description must not contain angle brackets`);
+        }
+        if (description.length > 1024) {
+          errors.push(`${relativeSkill}/SKILL.md description must not exceed 1024 characters`);
+        }
+      }
+    }
+  }
+
+  const metadataRelative = `${relativeSkill}/agents/openai.yaml`;
+  const metadataText = readText(path.join(skillDirectory, "agents", "openai.yaml"), errors, metadataRelative);
+  if (metadataText !== null) {
+    const metadata = parseMapping(metadataText, errors, metadataRelative);
+    if (metadata) {
+      const interfaceMetadata = metadata.interface;
+      if (!interfaceMetadata || typeof interfaceMetadata !== "object" || Array.isArray(interfaceMetadata)) {
+        errors.push(`${metadataRelative} must contain an interface mapping`);
+      } else {
+        for (const field of REQUIRED_INTERFACE_FIELDS) {
+          if (typeof interfaceMetadata[field] !== "string" || !interfaceMetadata[field].trim()) {
+            errors.push(`${metadataRelative} interface.${field} must be a non-empty string`);
+          }
+        }
+        if (typeof interfaceMetadata.default_prompt === "string"
+          && !interfaceMetadata.default_prompt.includes(`$${directoryName}`)) {
+          errors.push(`${metadataRelative} default_prompt must reference $${directoryName}`);
+        }
+      }
+    }
+  }
+
+  if (!documents.manual.includes(`$${directoryName}`)) {
+    errors.push(`docs/PROJECT-MANUAL.zh-CN.md must reference $${directoryName}`);
+  }
+  if (!documents.fileReference.includes(directoryName)) {
+    errors.push(`docs/FILE-REFERENCE.zh-CN.md must reference ${directoryName}`);
+  }
+
+  return errors;
+}
+
+export function validateSkillRepository(repositoryRoot, { expectedSkillCount = 25 } = {}) {
+  const root = path.resolve(repositoryRoot);
+  const errors = [];
+  const skillsRoot = path.join(root, "skills");
+  const manualPath = path.join(root, "docs", "PROJECT-MANUAL.zh-CN.md");
+  const fileReferencePath = path.join(root, "docs", "FILE-REFERENCE.zh-CN.md");
+  const documents = {
+    manual: readText(manualPath, errors, "docs/PROJECT-MANUAL.zh-CN.md") ?? "",
+    fileReference: readText(fileReferencePath, errors, "docs/FILE-REFERENCE.zh-CN.md") ?? "",
+  };
+
+  if (!fs.existsSync(skillsRoot)) {
+    errors.push("skills/ is required");
+    return { valid: false, skillCount: 0, errors };
+  }
+
+  const skillDirectories = fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(skillsRoot, entry.name))
+    .sort((left, right) => left.localeCompare(right));
+
+  if (skillDirectories.length !== expectedSkillCount) {
+    errors.push(`skills/ must contain exactly ${expectedSkillCount} directories; found ${skillDirectories.length}`);
+  }
+  for (const skillDirectory of skillDirectories) {
+    errors.push(...validateSkill(skillDirectory, root, documents));
+  }
+
+  return {
+    valid: errors.length === 0,
+    skillCount: skillDirectories.length,
+    errors,
+  };
+}

package/lib/toml-hooks.mjs

@@ -0,0 +1,97 @@
+import { parse } from "smol-toml";
+
+export const HOOK_EVENTS = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "PreCompact",
+  "PostCompact",
+  "SubagentStart",
+  "SubagentStop",
+  "Stop",
+];
+
+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 [
+    `[[hooks.${event}]]`,
+    'matcher = ""',
+    `[[hooks.${event}.hooks]]`,
+    'type = "command"',
+    `command = "${HOOK_COMMAND}"`,
+    `commandWindows = "${HOOK_COMMAND}"`,
+    "timeout = 5",
+    "async = false",
+    "",
+  ].join(newline);
+}
+
+function hasDeliveryHandler(config, event) {
+  const matchers = config.hooks?.[event];
+  if (!Array.isArray(matchers)) return false;
+  return matchers.some((matcher) => Array.isArray(matcher.hooks) && matcher.hooks.some((handler) =>
+    handler?.command === HOOK_COMMAND || handler?.commandWindows === HOOK_COMMAND));
+}
+
+function replaceFeatureHooksFalse(text) {
+  const header = /^\s*\[features\]\s*$/m.exec(text);
+  if (!header) throw new Error("Could not locate [features] for forced hooks replacement.");
+  const sectionStart = header.index + header[0].length;
+  const nextHeader = /^\s*\[/m.exec(text.slice(sectionStart));
+  const sectionEnd = nextHeader ? sectionStart + nextHeader.index : text.length;
+  const section = text.slice(sectionStart, sectionEnd);
+  const assignment = /^(\s*hooks\s*=\s*)false(\s*(?:#.*)?)$/m;
+  if (!assignment.test(section)) throw new Error("Could not locate features.hooks = false for forced replacement.");
+  return `${text.slice(0, sectionStart)}${section.replace(assignment, "$1true$2")}${text.slice(sectionEnd)}`;
+}
+
+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");
+  }
+  let config = text ? parse(text) : {};
+
+  if (config.features?.hooks === false && !force) {
+    throw new Error('Existing .codex/config.toml sets features.hooks = false; enable it or rerun with --force.');
+  }
+
+  if (!config.features) {
+    text += `${text ? newline.repeat(2) : ""}[features]${newline}hooks = true`;
+    actions.push("enable Codex hooks feature");
+  } else if (config.features.hooks === undefined) {
+    const section = /^\s*\[features\]\s*$/m;
+    if (!section.test(text)) throw new Error("Could not locate the parsed [features] section.");
+    text = text.replace(section, (line) => `${line}${newline}hooks = true`);
+    actions.push("enable Codex hooks feature");
+  } else if (config.features.hooks === false) {
+    text = replaceFeatureHooksFalse(text);
+    actions.push("replace features.hooks = false");
+  }
+
+  config = parse(text);
+  for (const event of HOOK_EVENTS) {
+    if (hasDeliveryHandler(config, event)) continue;
+    text += `${newline.repeat(2)}${hookBlock(event, newline).trimEnd()}`;
+    actions.push(`register ${event} Hook`);
+    config = parse(text);
+  }
+
+  parse(`${text}${newline}`);
+  return { text: `${text}${newline}`, actions };
+}
+
+export function inspectHookConfig(text) {
+  const config = parse(text);
+  return {
+    hooksEnabled: config.features?.hooks === true,
+    registeredEvents: HOOK_EVENTS.filter((event) => hasDeliveryHandler(config, event)),
+  };
+}

package/lib/workspace.mjs

@@ -0,0 +1,302 @@
+import fs from "node:fs";
+import path from "node:path";
+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("\\", "/");
+}
+
+function samePath(left, right) {
+  return path.resolve(left).toLowerCase() === path.resolve(right).toLowerCase();
+}
+
+function canonicalRemote(value) {
+  if (!value) return null;
+  const text = String(value).trim();
+  if (path.isAbsolute(text) || text.startsWith(".") || fs.existsSync(text)) {
+    return toPosix(path.resolve(text)).replace(/\/$/, "").toLowerCase();
+  }
+  return text.replaceAll("\\", "/").replace(/\/$/, "");
+}
+
+function runGit(cwd, args) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) {
+    throw new Error(`Git command failed in ${cwd}: git ${args.join(" ")}: ${result.stderr.trim()}`);
+  }
+  return result.stdout.trim();
+}
+
+export function gitTopLevel(directory) {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: directory,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  return result.status === 0 ? path.resolve(result.stdout.trim()) : null;
+}
+
+export function gitCommonDirectory(directory) {
+  const result = spawnSync("git", ["rev-parse", "--git-common-dir"], {
+    cwd: directory,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  return result.status === 0 ? path.resolve(directory, result.stdout.trim()) : null;
+}
+
+export function normalizeWorkspaceId(value, workspaceRoot) {
+  const explicit = value !== undefined && value !== null && String(value).trim() !== "";
+  const candidate = explicit
+    ? String(value).trim()
+    : path.basename(path.resolve(workspaceRoot)).toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/^-+|-+$/g, "");
+  if (!/^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/.test(candidate)) {
+    throw new Error("Workspace ID must be 1-64 lowercase ASCII letters, digits, dots, underscores, or hyphens.");
+  }
+  return candidate;
+}
+
+function gitBranch(directory) {
+  const result = spawnSync("git", ["branch", "--show-current"], {
+    cwd: directory, encoding: "utf8", windowsHide: true,
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function gitHasCommit(directory) {
+  return spawnSync("git", ["rev-parse", "--verify", "HEAD"], {
+    cwd: directory, encoding: "utf8", windowsHide: true,
+  }).status === 0;
+}
+
+function remoteHeads(remote) {
+  if (!remote) return new Set();
+  const result = spawnSync("git", ["ls-remote", "--heads", remote], {
+    encoding: "utf8", windowsHide: true,
+  });
+  if (result.status !== 0) throw new Error(`Cannot inspect remote ${remote}: ${result.stderr.trim()}`);
+  return new Set(result.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.split(/\s+/)[1]?.replace("refs/heads/", "")));
+}
+
+function originUrl(directory) {
+  const result = spawnSync("git", ["remote", "get-url", "origin"], {
+    cwd: directory, encoding: "utf8", windowsHide: true,
+  });
+  return result.status === 0 ? result.stdout.trim() || null : null;
+}
+
+function ensureOrigin(directory, remote) {
+  if (!remote) return originUrl(directory);
+  const existing = originUrl(directory);
+  if (existing && canonicalRemote(existing) !== canonicalRemote(remote)) {
+    throw new Error(`Repository origin conflicts with configured remote: ${existing} != ${remote}`);
+  }
+  if (!existing) runGit(directory, ["remote", "add", "origin", remote]);
+  return remote;
+}
+
+function initializeWorkflowRepository(workspaceRoot, branch, remote, heads, actions, dryRun) {
+  const gitEntry = path.join(workspaceRoot, ".git");
+  if (!fs.existsSync(gitEntry)) {
+    actions.push(`initialize workflow Git repository on ${branch}`);
+    if (dryRun) return;
+    runGit(workspaceRoot, ["init", "-b", branch]);
+  } else {
+    if (!fs.statSync(gitEntry).isDirectory()) throw new Error("Workflow repository must use an independent .git directory, not a linked worktree.");
+    const root = gitTopLevel(workspaceRoot);
+    if (!root || !samePath(root, workspaceRoot)) throw new Error("Workspace root must be its own Git repository.");
+    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.`);
+      }
+      if (!dryRun) runGit(workspaceRoot, ["symbolic-ref", "HEAD", `refs/heads/${branch}`]);
+    }
+  }
+  if (dryRun || !remote) return;
+  ensureOrigin(workspaceRoot, remote);
+  if (heads.has(branch)) {
+    runGit(workspaceRoot, ["fetch", "origin", `refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+    if (!gitHasCommit(workspaceRoot)) {
+      runGit(workspaceRoot, ["checkout", "-B", branch, "--track", `origin/${branch}`]);
+    } else {
+      runGit(workspaceRoot, ["branch", "--set-upstream-to", `origin/${branch}`, branch]);
+    }
+  }
+}
+
+function initializeCodeRepository(workspaceRoot, code, remote, heads, actions, dryRun) {
+  if (!fs.existsSync(code.absolute)) {
+    if (remote && heads.size) {
+      actions.push(`clone code repository main into ${code.relative}/`);
+      if (!dryRun) runGit(workspaceRoot, ["clone", "--branch", "main", remote, code.relative]);
+    } else {
+      actions.push(`create code repository ${code.relative}/ on main`);
+      if (!dryRun) {
+        fs.mkdirSync(code.absolute, { recursive: true });
+        runGit(code.absolute, ["init", "-b", "main"]);
+        ensureOrigin(code.absolute, remote);
+      }
+    }
+    return;
+  }
+  if (!fs.statSync(code.absolute).isDirectory()) throw new Error(`Code path is not a directory: ${code.absolute}`);
+  const entries = fs.readdirSync(code.absolute);
+  const nestedRoot = gitTopLevel(code.absolute);
+  if (!nestedRoot || !samePath(nestedRoot, code.absolute)) {
+    if (entries.length) throw new Error(`Code directory is non-empty and not a Git repository: ${code.absolute}`);
+    actions.push(`initialize existing empty code directory ${code.relative}/ on main`);
+    if (!dryRun) {
+      runGit(code.absolute, ["init", "-b", "main"]);
+      ensureOrigin(code.absolute, remote);
+    }
+    return;
+  }
+  if (!dryRun) {
+    if (!fs.statSync(path.join(code.absolute, ".git")).isDirectory()) {
+      throw new Error("Code repository must use an independent .git directory, not a linked worktree.");
+    }
+    ensureOrigin(code.absolute, remote);
+  }
+}
+
+export function validateCodePath(workspaceRoot, codePath = "code") {
+  if (!codePath || path.isAbsolute(codePath)) throw new Error("Code path must be a relative direct child directory.");
+  const normalized = toPosix(path.normalize(codePath)).replace(/^\.\//, "").replace(/\/$/, "");
+  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)) {
+    throw new Error(`Reserved code path: ${normalized}`);
+  }
+  const absolute = path.resolve(workspaceRoot, normalized);
+  const relative = path.relative(path.resolve(workspaceRoot), absolute);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Code path escapes the workspace.");
+  if (fs.existsSync(absolute) && fs.lstatSync(absolute).isSymbolicLink()) {
+    throw new Error(`Code path must not be a symbolic link: ${absolute}`);
+  }
+  return { relative: normalized, absolute };
+}
+
+export function initializeGitWorkspace(workspaceRoot, options = {}) {
+  const {
+    codePath = "code", codeId = "app", codeRemote = null, workflowRemote = null,
+    sharedRemote = null, workspaceId: requestedWorkspaceId = null, dryRun = false,
+  } = options;
+  if (sharedRemote && (codeRemote || workflowRemote)) {
+    throw new Error("--shared-remote cannot be combined with --code-remote or --workflow-remote.");
+  }
+  const workspaceId = normalizeWorkspaceId(requestedWorkspaceId, workspaceRoot);
+  const resolvedWorkflowRemote = sharedRemote || workflowRemote || null;
+  const resolvedCodeRemote = sharedRemote || codeRemote || null;
+  const workflowBranch = `workflow/${workspaceId}`;
+  const code = validateCodePath(workspaceRoot, codePath);
+  const actions = [];
+  const workflowHeads = remoteHeads(resolvedWorkflowRemote);
+  const codeHeads = canonicalRemote(resolvedWorkflowRemote) === canonicalRemote(resolvedCodeRemote)
+    ? workflowHeads : remoteHeads(resolvedCodeRemote);
+  if (resolvedCodeRemote && codeHeads.size && !codeHeads.has("main")) {
+    throw new Error(`Code remote is non-empty but does not contain required main branch: ${resolvedCodeRemote}`);
+  }
+
+  initializeWorkflowRepository(workspaceRoot, workflowBranch, resolvedWorkflowRemote, workflowHeads, actions, dryRun);
+  initializeCodeRepository(workspaceRoot, code, resolvedCodeRemote, codeHeads, actions, dryRun);
+
+  if (!dryRun) {
+    const workflowGit = gitTopLevel(workspaceRoot);
+    const codeGit = gitTopLevel(code.absolute);
+    if (!workflowGit || !codeGit || samePath(workflowGit, codeGit)) {
+      throw new Error("Workflow and code repositories must have different Git roots.");
+    }
+    const workflowCommon = gitCommonDirectory(workspaceRoot);
+    const codeCommon = gitCommonDirectory(code.absolute);
+    if (!workflowCommon || !codeCommon || samePath(workflowCommon, codeCommon)) {
+      throw new Error("Workflow and code repositories must use independent Git common directories.");
+    }
+  }
+  const actualWorkflowRemote = dryRun ? resolvedWorkflowRemote : originUrl(workspaceRoot);
+  const actualCodeRemote = dryRun ? resolvedCodeRemote : originUrl(code.absolute);
+
+  return {
+    actions,
+    configuration: {
+      schema_version: 2,
+      workspace_id: workspaceId,
+      repository_layout: "independent-git-roots",
+      shared_remote: Boolean(actualWorkflowRemote && actualCodeRemote
+        && canonicalRemote(actualWorkflowRemote) === canonicalRemote(actualCodeRemote)),
+      workflow_repository: { path: ".", remote: actualWorkflowRemote, branch: workflowBranch },
+      code_repository: {
+        repo_id: codeId,
+        path: code.relative,
+        remote: actualCodeRemote,
+        default_branch: "main",
+      },
+    },
+  };
+}
+
+export function readWorkspaceConfiguration(workspaceRoot, options = {}) {
+  const file = path.join(workspaceRoot, options.configurationPath || WORKSPACE_CONFIG);
+  if (!fs.existsSync(file)) {
+    if (options.optional) return null;
+    throw new Error(`Workspace configuration is missing: ${file}`);
+  }
+  const configuration = parseYaml(fs.readFileSync(file, "utf8"));
+  if (configuration?.schema_version !== 2
+    || configuration?.repository_layout !== "independent-git-roots"
+    || !configuration?.workspace_id
+    || configuration?.workflow_repository?.branch !== `workflow/${configuration.workspace_id}`
+    || !configuration?.code_repository?.repo_id
+    || !configuration?.code_repository?.path) {
+    throw new Error(`Workspace configuration is invalid: ${file}`);
+  }
+  const code = validateCodePath(workspaceRoot, configuration.code_repository.path);
+  return { file, configuration, codeRoot: code.absolute };
+}
+
+export function workspaceConfigurationText(configuration) {
+  return stringifyYaml(configuration, { lineWidth: 0 });
+}
+
+export function inspectGitRepository(repositoryRoot) {
+  const topLevel = gitTopLevel(repositoryRoot);
+  if (!topLevel || !samePath(topLevel, repositoryRoot)) return { repository: false };
+  const run = (args) => spawnSync("git", args, { cwd: repositoryRoot, encoding: "utf8", windowsHide: true });
+  const branch = run(["branch", "--show-current"]);
+  const head = run(["rev-parse", "HEAD"]);
+  const status = run(["status", "--porcelain=v1"]);
+  const upstream = run(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+  let ahead = null;
+  let behind = null;
+  if (upstream.status === 0) {
+    const divergence = run(["rev-list", "--left-right", "--count", "HEAD...@{upstream}"]);
+    if (divergence.status === 0) {
+      const [aheadText, behindText] = divergence.stdout.trim().split(/\s+/);
+      ahead = Number(aheadText);
+      behind = Number(behindText);
+    }
+  }
+  const dirtyPaths = status.stdout.split(/\r?\n/).filter(Boolean).map((line) => toPosix(line.slice(3)));
+  return {
+    repository: true,
+    root: toPosix(topLevel),
+    branch: branch.stdout.trim() || "main",
+    head: head.status === 0 ? head.stdout.trim() : null,
+    dirty_paths: dirtyPaths,
+    upstream: upstream.status === 0 ? upstream.stdout.trim() : null,
+    ahead,
+    behind,
+    sync_status: dirtyPaths.length
+      ? "uncommitted"
+      : ahead > 0 ? "unpushed"
+        : behind > 0 ? "behind"
+          : upstream.status === 0 ? "synchronized" : "no-upstream",
+  };
+}

package/lib/yaml-runtime.mjs

@@ -0,0 +1,18 @@
+let yamlModule;
+
+try {
+  yamlModule = await import("yaml");
+} catch (packageError) {
+  try {
+    yamlModule = await import(new URL("../state/vendor/yaml/dist/index.js", import.meta.url));
+  } catch {
+    throw packageError;
+  }
+}
+
+const yaml = yamlModule.default || yamlModule;
+
+export const parse = yaml.parse;
+export const parseDocument = yaml.parseDocument;
+export const isSeq = yaml.isSeq;
+export const stringify = yaml.stringify;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ai-delivery-workflow",
+  "version": "0.2.2",
+  "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/hzr1348/work-flow.git"
+  },
+  "homepage": "https://gitee.com/hzr1348/work-flow",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "ai-delivery": "bin/ai-delivery.mjs"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "lib",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node --test verification/*.test.mjs",
+    "skills:validate": "node bin/validate-skills.mjs",
+    "audit:generate": "node audit/generate-all.mjs",
+    "audit:verify": "node verification/audit/verify-audit.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "smol-toml": "1.7.0",
+    "yaml": "2.8.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,27 @@
+---
+name: ai-delivery-assemble-release
+description: Calculate a selected release target's continuous cumulative version closure, validate immutable version-ready tags and Git ancestry, and aggregate checksummed cross-version delivery materials into a release candidate. Use during R01-R04 after an explicit release request, including multi-version releases and same-version redeploys.
+---
+
+# Assemble Release
+
+Produce a deterministic release selection and auditable material package. Do not approve or deploy it.
+
+## 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.
+
+## 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.
+
+Same-version redeploy reuses immutable application identities but regenerates the release-scoped indexes, snapshots, verification, approval, deployment, and archive evidence.
+
+Read [release-assembly-contract.md](references/release-assembly-contract.md) before aggregation.

package/skills/ai-delivery-assemble-release/agents/openai.yaml

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

@@ -0,0 +1,22 @@
+schema_version: 2
+release_id: "REL-0001"
+release_candidate_id: "RC-0001"
+mode: "incremental"
+target_version: "VER-0005"
+source_tag: "version-ready/VER-0005/r1"
+repository:
+  repo_id: "app"
+  source_path: "code"
+  code_commit: "<git-sha>"
+  code_tag: "version-ready/VER-0005/r1"
+workflow_identity:
+  workflow_commit: "<workflow-git-sha>"
+  workflow_tag: "workflow-ready/VER-0005/r1"
+  version_manifest_sha256: "<sha256>"
+commit: "<git-sha>"
+image_digest: "sha256:<digest>"
+material_index_sha256: "<sha256>"
+configuration_baseline_sha256: "<sha256>"
+migration_set_sha256: "<sha256>"
+rollback_image_digest: "sha256:<previous-digest>"
+status: "immutable"

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

@@ -0,0 +1,9 @@
+schema_version: 1
+release_id: "REL-0001"
+source_tag: "version-ready/VER-0005/r1"
+source_commit: "<git-sha>"
+release_branch: "release/REL-0001-short-slug"
+production_branch: "main"
+line_branch: "line/PRODUCT-001"
+merge_intermediate_tags: false
+rollback_branch_allowed: false