ai-delivery-workflow 0.2.2

package/lib/project-bootstrap.mjs

@@ -0,0 +1,927 @@
+import crypto from "node:crypto";
+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";
+import { executeDeliveryStateCommand } from "./delivery-state.mjs";
+import { inspectGitRepository, readWorkspaceConfiguration } from "./workspace.mjs";
+
+const IGNORED_DIRECTORIES = new Set([
+  ".git",
+  ".agents",
+  ".codex",
+  ".ai-delivery",
+  ".workflow",
+  ".idea",
+  ".vscode",
+  "node_modules",
+  "vendor",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".tmp",
+  ".tools",
+  ".venv",
+  "venv",
+  "__pycache__",
+  "target",
+]);
+const VALID_NEXT_ACTION_OWNERS = new Set(["agent", "user", "external"]);
+
+const SOURCE_EXTENSIONS = new Map([
+  [".c", "C"],
+  [".cc", "C++"],
+  [".cpp", "C++"],
+  [".cs", "C#"],
+  [".css", "CSS"],
+  [".go", "Go"],
+  [".h", "C/C++"],
+  [".html", "HTML"],
+  [".java", "Java"],
+  [".js", "JavaScript"],
+  [".jsx", "React"],
+  [".kt", "Kotlin"],
+  [".kts", "Kotlin"],
+  [".mjs", "JavaScript"],
+  [".php", "PHP"],
+  [".py", "Python"],
+  [".rb", "Ruby"],
+  [".rs", "Rust"],
+  [".scss", "SCSS"],
+  [".sql", "SQL"],
+  [".svelte", "Svelte"],
+  [".swift", "Swift"],
+  [".tf", "Terraform"],
+  [".ts", "TypeScript"],
+  [".tsx", "React"],
+  [".vue", "Vue"],
+]);
+
+const MANIFESTS = new Map([
+  ["package.json", "Node.js"],
+  ["pyproject.toml", "Python"],
+  ["requirements.txt", "Python"],
+  ["poetry.lock", "Python"],
+  ["go.mod", "Go"],
+  ["cargo.toml", "Rust"],
+  ["gemfile", "Ruby"],
+  ["composer.json", "PHP"],
+  ["pom.xml", "Java"],
+  ["build.gradle", "Gradle"],
+  ["build.gradle.kts", "Gradle"],
+]);
+
+const WORKFLOW_REQUIRED_FILES = [
+  ".workflow/config/workspace.yaml",
+  ".workflow/config/install-manifest.json",
+  ".codex/config.toml",
+  "AGENTS.md",
+  ".workflow/tools/state/state.mjs",
+  ".workflow/tools/evolution/evolve.mjs",
+  ".workflow/tools/hooks/hook-event.mjs",
+  ".workflow/delivery/project.yaml",
+  ".workflow/delivery/workflow-state.yaml",
+  ".workflow/delivery/artifact-registry.yaml",
+  ".workflow/delivery/standards-baseline.yaml",
+  ".workflow/standards/index.yaml",
+  ".gitattributes",
+];
+const LEGACY_WORKFLOW_REQUIRED_FILES = [
+  ".ai-delivery/workspace.yaml",
+  ".ai-delivery/install-manifest.json",
+  ".codex/config.toml",
+  "AGENTS.md",
+  ".ai-delivery/state/state.mjs",
+  ".ai-delivery/hooks/hook-event.mjs",
+  "delivery/project.yaml",
+  "delivery/workflow-state.yaml",
+  "delivery/artifact-registry.yaml",
+  "delivery/standards-baseline.yaml",
+  "standards/index.yaml",
+];
+const ESSENTIAL_STARTUP_SKILLS = [
+  "ai-delivery-bootstrap",
+  "ai-delivery-checkpoint-task",
+  "ai-delivery-evolve-workflow",
+  "ai-delivery-orchestrate",
+];
+
+const ACTIVE_TASK_STATUSES = new Set([
+  "preparing",
+  "running",
+  "checkpointed",
+  "pending-review",
+  "blocked",
+  "interrupted",
+]);
+const CLOSED_TASK_STATUSES = new Set(["completed", "failed", "abandoned"]);
+
+function toPosix(value) {
+  return value.replaceAll("\\", "/");
+}
+
+function exists(root, relativePath) {
+  return fs.existsSync(path.join(root, relativePath));
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, content, "utf8");
+  fs.renameSync(temporary, file);
+}
+
+function sha256File(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function isSensitiveFile(name) {
+  const lower = name.toLowerCase();
+  if (lower === ".env" || (lower.startsWith(".env.") && !/\.(example|sample|template)$/.test(lower))) {
+    return true;
+  }
+  return /\.(pem|p12|pfx|key|keystore|jks)$/.test(lower)
+    || /(^|[-_.])(credential|credentials|secret|secrets)([-_.]|$)/.test(lower);
+}
+
+function classifyFile(relativePath) {
+  const normalized = toPosix(relativePath);
+  const name = path.basename(relativePath).toLowerCase();
+  const extension = path.extname(name);
+  if (MANIFESTS.has(name)) {
+    return { category: "manifest", technology: MANIFESTS.get(name), purpose: "依赖与项目清单", priority: "high" };
+  }
+  if (/^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|uv\.lock|go\.sum|cargo\.lock)$/.test(name)) {
+    return { category: "lockfile", technology: "dependency-management", purpose: "依赖锁定", priority: "high" };
+  }
+  if (name === "dockerfile" || name.startsWith("dockerfile.")) {
+    return { category: "deployment", technology: "Docker", purpose: "容器构建", priority: "high" };
+  }
+  if (/^(compose|docker-compose).*\.(ya?ml)$/.test(name)) {
+    return { category: "deployment", technology: "Docker Compose", purpose: "服务编排", priority: "high" };
+  }
+  if (extension === ".tf") {
+    return { category: "infrastructure", technology: "Terraform", purpose: "基础设施定义", priority: "high" };
+  }
+  if (/(^|\/)(test|tests|spec|specs)(\/|$)/i.test(normalized)
+    || /\.(test|spec)\.[^.]+$/i.test(name)) {
+    return { category: "test", technology: SOURCE_EXTENSIONS.get(extension) || extension.slice(1), purpose: "自动化测试", priority: "medium" };
+  }
+  if (SOURCE_EXTENSIONS.has(extension)) {
+    return { category: "source", technology: SOURCE_EXTENSIONS.get(extension), purpose: "源代码", priority: "medium" };
+  }
+  if (/^(makefile|cmakelists\.txt|justfile)$/.test(name)
+    || /^(webpack|vite|rollup|eslint|prettier|tsconfig|babel)\..+/.test(name)) {
+    return { category: "build", technology: "build-tooling", purpose: "构建或工程配置", priority: "high" };
+  }
+  if (/\.(ya?ml|json|toml|ini|conf|config|properties)$/.test(name)) {
+    return { category: "configuration", technology: extension.slice(1).toUpperCase(), purpose: "配置", priority: "medium" };
+  }
+  if (/\.(md|mdx|rst|txt)$/.test(name)) {
+    return { category: "documentation", technology: "documentation", purpose: "文档", priority: "low" };
+  }
+  return { category: "other", technology: extension ? extension.slice(1) : "unknown", purpose: "其他项目文件", priority: "low" };
+}
+
+function scanProjectFiles(root, maxFiles = 10_000) {
+  const files = [];
+  const warnings = [];
+  let sensitiveFileCount = 0;
+  let truncated = false;
+
+  function visit(directory) {
+    if (truncated) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch (error) {
+      warnings.push(`无法读取目录：${toPosix(path.relative(root, directory)) || "."} (${error.code || error.message})`);
+      return;
+    }
+    for (const entry of entries) {
+      if (files.length >= maxFiles) {
+        truncated = true;
+        break;
+      }
+      const absolute = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name.toLowerCase())) visit(absolute);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (isSensitiveFile(entry.name)) {
+        sensitiveFileCount += 1;
+        continue;
+      }
+      const relative = toPosix(path.relative(root, absolute));
+      const stat = fs.statSync(absolute);
+      files.push({
+        path: relative,
+        absolute,
+        size_bytes: stat.size,
+        ...classifyFile(relative),
+      });
+    }
+  }
+
+  visit(root);
+  const codeFiles = files.filter((file) =>
+    new Set(["manifest", "source", "test", "build", "deployment", "infrastructure"]).has(file.category));
+  const technologyCategories = new Set([
+    "manifest",
+    "source",
+    "test",
+    "build",
+    "deployment",
+    "infrastructure",
+  ]);
+  const technologies = [...new Set(files
+    .filter((file) => technologyCategories.has(file.category)
+      && file.technology
+      && file.technology !== "unknown")
+    .map((file) => file.technology))].sort();
+  const categories = Object.fromEntries(
+    [...new Set(files.map((file) => file.category))]
+      .sort()
+      .map((category) => [category, files.filter((file) => file.category === category).length]),
+  );
+  return {
+    files,
+    summary: {
+      has_code: codeFiles.length > 0,
+      scanned_file_count: files.length,
+      code_evidence_count: codeFiles.length,
+      sensitive_file_count: sensitiveFileCount,
+      truncated,
+      technologies,
+      categories,
+    },
+    warnings,
+  };
+}
+
+function gitState(root) {
+  const run = (args) => spawnSync("git", args, { cwd: root, encoding: "utf8", windowsHide: true });
+  const topLevel = run(["rev-parse", "--show-toplevel"]);
+  if (topLevel.status !== 0) return { repository: false };
+  const branch = run(["branch", "--show-current"]);
+  const head = run(["rev-parse", "HEAD"]);
+  const status = run(["status", "--porcelain=v1"]);
+  return {
+    repository: true,
+    root: toPosix(topLevel.stdout.trim()),
+    branch: branch.stdout.trim() || null,
+    head: head.status === 0 ? head.stdout.trim() : null,
+    dirty_paths: status.stdout.split(/\r?\n/).filter(Boolean).map((line) => toPosix(line.slice(3))),
+  };
+}
+
+function readStructuredFile(file, format, errors) {
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    return format === "json" ? JSON.parse(text) : parseYaml(text);
+  } catch (error) {
+    errors.push(`${toPosix(file)}: ${error.message}`);
+    return null;
+  }
+}
+
+function compareTasks(left, right) {
+  const leftSequence = Number.isInteger(left.sequence) ? left.sequence : Number.MAX_SAFE_INTEGER;
+  const rightSequence = Number.isInteger(right.sequence) ? right.sequence : Number.MAX_SAFE_INTEGER;
+  return leftSequence - rightSequence || String(left.task_id).localeCompare(String(right.task_id));
+}
+
+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 taskStateChecksum(task, root) {
+  const comparable = { ...task };
+  const stateRoot = path.resolve(root, comparable.state_root || ".");
+  comparable.state_root = process.platform === "win32" ? stateRoot.toLowerCase() : stateRoot;
+  if (comparable.worktree) {
+    const worktree = path.resolve(stateRoot, comparable.worktree);
+    comparable.worktree = process.platform === "win32" ? worktree.toLowerCase() : worktree;
+  }
+  for (const key of ["code_branch", "code_commit"]) delete comparable[key];
+  return crypto.createHash("sha256").update(JSON.stringify(stableValue(comparable))).digest("hex");
+}
+
+function inspectRuntime(root, errors, workflowRoot = ".workflow") {
+  const localDirectory = path.join(root, workflowRoot, "delivery", "runtime", "tasks");
+  const sharedDirectory = path.join(root, workflowRoot, "control", "tasks");
+  const normalizeTaskOwner = (task) => {
+    const owner = task.next_action_owner === undefined ? "agent" : task.next_action_owner;
+    if (!VALID_NEXT_ACTION_OWNERS.has(owner)) {
+      errors.push(`任务 ${task.task_id || "unknown"} 的 next_action_owner 无效: ${owner}`);
+      return { ...task, next_action_owner: null };
+    }
+    return { ...task, next_action_owner: owner };
+  };
+  const readTasks = (directory) => fs.existsSync(directory)
+    ? fs.readdirSync(directory)
+      .filter((name) => /\.(json|ya?ml)$/i.test(name))
+      .map((name) => readStructuredFile(
+        path.join(directory, name),
+        name.endsWith(".json") ? "json" : "yaml",
+        errors,
+      ))
+      .filter(Boolean)
+      .map(normalizeTaskOwner)
+    : [];
+  const localTasks = readTasks(localDirectory);
+  const sharedTasks = readTasks(sharedDirectory);
+  const localById = new Map(localTasks.map((task) => [task.task_id, task]));
+  const sharedById = new Map(sharedTasks.map((task) => [task.task_id, task]));
+  for (const [taskId, local] of localById) {
+    const shared = sharedById.get(taskId);
+    if (shared && Number(local.shared_revision || 0) !== Number(shared.shared_revision || 0)) {
+      errors.push(`任务 ${taskId} 的本机 revision ${local.shared_revision || 0} 与共享 revision ${shared.shared_revision || 0} 冲突`);
+    } else if (shared && taskStateChecksum(local, root) !== taskStateChecksum(shared, root)) {
+      errors.push(`任务 ${taskId} 的本机与共享内容在 revision ${local.shared_revision || 0} 发生分叉`);
+    }
+  }
+  const tasks = [...new Map([
+    ...sharedTasks.map((task) => [task.task_id, task]),
+    ...localTasks.map((task) => [task.task_id, task]),
+  ]).values()].sort(compareTasks);
+  const tasksById = new Map(tasks.map((task) => [task.task_id, task]));
+  const dependencyErrors = [];
+  const queued = tasks.filter((task) => task.status === "queued");
+  const ready = queued.filter((task) => {
+    for (const dependencyId of task.depends_on || []) {
+      const dependency = tasksById.get(dependencyId);
+      if (!dependency) {
+        dependencyErrors.push(`${task.task_id} 缺少依赖任务 ${dependencyId}`);
+        return false;
+      }
+      if (dependency.status !== "completed") return false;
+    }
+    return true;
+  });
+  const active = tasks.filter((task) => ACTIVE_TASK_STATUSES.has(task.status));
+  const recommended = [...active, ...ready].sort(compareTasks)[0] || null;
+  const checkpointRoot = path.join(root, workflowRoot, "control", "checkpoints");
+  let sharedCheckpointCount = 0;
+  const countCheckpoints = (directory) => {
+    if (!fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) countCheckpoints(absolute);
+      else if (entry.isFile() && /\.(json|ya?ml)$/i.test(entry.name)) sharedCheckpointCount += 1;
+    }
+  };
+  countCheckpoints(checkpointRoot);
+  return {
+    task_count: tasks.length,
+    closed_task_count: tasks.filter((task) => CLOSED_TASK_STATUSES.has(task.status)).length,
+    active_task_ids: active.map((task) => task.task_id),
+    queued_task_ids: queued.map((task) => task.task_id),
+    ready_task_ids: ready.map((task) => task.task_id),
+    recommended_task_id: recommended?.task_id || null,
+    recommended_iteration_id: recommended?.iteration_id || null,
+    recommended_status: recommended?.status || null,
+    next_action: recommended?.next_action || null,
+    next_action_owner: recommended?.next_action_owner || null,
+    source: localTasks.length ? "local-and-shared" : sharedTasks.length ? "shared" : "none",
+    local_task_count: localTasks.length,
+    shared_task_count: sharedTasks.length,
+    shared_checkpoint_count: sharedCheckpointCount,
+    dependency_errors: [...new Set(dependencyErrors)],
+  };
+}
+
+function recommendationFor(state, workflow, runtime) {
+  if (state === "empty-uninitialized") {
+    return {
+      skill: "ai-delivery-bootstrap",
+      action: "初始化项目级工作流，然后调用 ai-delivery-define-product 逐项收集首个产品需求。",
+      requires_user_input: true,
+    };
+  }
+  if (state === "codebase-uninitialized") {
+    return {
+      skill: "ai-delivery-bootstrap",
+      action: "初始化项目级工作流，生成存量代码上下文，再调用 ai-delivery-define-product 核对业务意图。",
+      requires_user_input: true,
+    };
+  }
+  if (state === "workflow-inconsistent") {
+    return {
+      skill: "ai-delivery-bootstrap",
+      action: "停止自动流转，审阅缺失或冲突项并形成修复决定；不得自动使用 force 覆盖。",
+      requires_user_input: true,
+    };
+  }
+  if (state === "workflow-interrupted" || runtime.recommended_task_id) {
+    const awaitingUser = runtime.next_action_owner === "user";
+    const awaitingExternal = runtime.next_action_owner === "external";
+    return {
+      skill: "ai-delivery-checkpoint-task",
+      action: awaitingUser || awaitingExternal
+        ? runtime.next_action
+        : `恢复并核对任务 ${runtime.recommended_task_id || "unknown"}，只继续其幂等 next_action。`,
+      requires_user_input: awaitingUser,
+      mutation_allowed: !awaitingUser && !awaitingExternal,
+    };
+  }
+  const initial = workflow.delivery_artifact_count === 0
+    && !(workflow.active_nodes?.length)
+    && !(workflow.pending_gates?.length);
+  if (initial) {
+    return {
+      skill: "ai-delivery-define-product",
+      action: "开始产品发现，一次询问一个业务决策并形成 Discovery Gate A 草稿。",
+      requires_user_input: true,
+    };
+  }
+  return {
+    skill: "ai-delivery-orchestrate",
+    action: "依据 workflow-state、artifact-registry 和 Gate 状态推导下一节点。",
+    requires_user_input: Boolean(workflow.pending_gates?.length),
+  };
+}
+
+export function inspectProjectState(target) {
+  const root = path.resolve(target);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${root}`);
+  }
+  const workspaceRecord = readWorkspaceConfiguration(root, { optional: true });
+  const inferredCodeRoot = fs.existsSync(path.join(root, "code")) ? path.join(root, "code") : root;
+  const codeRoot = workspaceRecord?.codeRoot || inferredCodeRoot;
+  const codebase = scanProjectFiles(codeRoot);
+  const errors = [];
+  const currentIndicators = WORKFLOW_REQUIRED_FILES.filter((file) => exists(root, file));
+  const legacyIndicators = LEGACY_WORKFLOW_REQUIRED_FILES.filter((file) => exists(root, file));
+  const currentStateIndicators = WORKFLOW_REQUIRED_FILES.filter((file) =>
+    file.startsWith(".workflow/delivery/") || file === ".workflow/standards/index.yaml")
+    .filter((file) => exists(root, file));
+  const legacyStateIndicators = LEGACY_WORKFLOW_REQUIRED_FILES.filter((file) =>
+    file.startsWith("delivery/") || file === "standards/index.yaml")
+    .filter((file) => exists(root, file));
+  const legacyLayout = currentStateIndicators.length === 0 && legacyStateIndicators.length > 0;
+  const requiredFiles = legacyLayout ? LEGACY_WORKFLOW_REQUIRED_FILES : WORKFLOW_REQUIRED_FILES;
+  const workflowRoot = legacyLayout ? "." : ".workflow";
+  const workflowIndicators = requiredFiles.filter((file) => exists(root, file));
+  const missingFiles = requiredFiles.filter((file) => !exists(root, file));
+  const installation = {
+    detected: currentIndicators.length > 0 || legacyIndicators.length > 0,
+    complete: workflowIndicators.length === requiredFiles.length,
+    workflow_root: workflowRoot,
+    legacy_layout: legacyLayout,
+    present_files: workflowIndicators,
+    missing_files: missingFiles,
+    installed_skill_count: 0,
+    missing_skills: [],
+  };
+  const workflow = {
+    project_id: null,
+    iteration_id: null,
+    artifact_count: 0,
+    delivery_artifact_count: 0,
+    active_nodes: [],
+    blocked_nodes: [],
+    pending_gates: [],
+  };
+  let runtime = {
+    task_count: 0,
+    active_task_ids: [],
+    queued_task_ids: [],
+    ready_task_ids: [],
+    recommended_task_id: null,
+    dependency_errors: [],
+  };
+
+  if (legacyLayout) {
+    errors.push("检测到旧版 delivery/ 与 standards/ 布局；迁移到 .workflow/ 后才能继续执行。");
+  }
+  if (currentStateIndicators.length > 0 && legacyStateIndicators.length > 0) {
+    errors.push("同时检测到 .workflow 和旧版 delivery/standards 状态；必须人工确定唯一权威根。");
+  }
+
+  if (installation.complete) {
+    if (legacyLayout) {
+      errors.push("检测到旧版 delivery/ 与 standards/ 布局；迁移到 .workflow/ 后才能继续执行。");
+    }
+    if (currentStateIndicators.length > 0 && legacyStateIndicators.length > 0) {
+      errors.push("同时检测到 .workflow 和旧版 delivery/standards 状态；必须人工确定唯一权威根。");
+    }
+    const manifest = readStructuredFile(path.join(
+      root,
+      legacyLayout ? ".ai-delivery/install-manifest.json" : ".workflow/config/install-manifest.json",
+    ), "json", errors);
+    const stateRoot = path.join(root, workflowRoot);
+    const project = readStructuredFile(path.join(stateRoot, "delivery", "project.yaml"), "yaml", errors);
+    const workflowState = readStructuredFile(path.join(stateRoot, "delivery", "workflow-state.yaml"), "yaml", errors);
+    const registry = readStructuredFile(path.join(stateRoot, "delivery", "artifact-registry.yaml"), "yaml", errors);
+    readStructuredFile(path.join(stateRoot, "delivery", "standards-baseline.yaml"), "yaml", errors);
+    readStructuredFile(path.join(stateRoot, "standards", "index.yaml"), "yaml", errors);
+    if (manifest) {
+      const installedSkills = Array.isArray(manifest.installed_skills) ? manifest.installed_skills : [];
+      installation.installed_skill_count = installedSkills.length;
+      installation.missing_skills = [...new Set([...installedSkills, ...ESSENTIAL_STARTUP_SKILLS])]
+        .filter((name) => !exists(root, `.agents/skills/${name}/SKILL.md`));
+      if (manifest.scope !== "workspace") errors.push("安装清单 scope 必须为 workspace");
+      if (!installedSkills.length) errors.push("安装清单未登记任何 skill");
+    }
+    if (project && workflowState) {
+      workflow.project_id = project.project_id || null;
+      workflow.iteration_id = workflowState.iteration_id || project.current_iteration_id || null;
+      workflow.active_nodes = Array.isArray(workflowState.active_nodes) ? workflowState.active_nodes : [];
+      workflow.blocked_nodes = Array.isArray(workflowState.blocked_nodes) ? workflowState.blocked_nodes : [];
+      workflow.pending_gates = Array.isArray(workflowState.pending_gates) ? workflowState.pending_gates : [];
+      if (project.project_id !== workflowState.project_id) {
+        errors.push(`${workflowRoot}/delivery/project.yaml 与 workflow-state.yaml 的 project_id 不一致`);
+      }
+    }
+    if (!registry || !Array.isArray(registry.artifacts)) {
+      errors.push(`${workflowRoot}/delivery/artifact-registry.yaml 必须包含 artifacts 数组`);
+    } else {
+      workflow.artifact_count = registry.artifacts.length;
+      workflow.delivery_artifact_count = registry.artifacts.filter((artifact) =>
+        !new Set(["project-state-report", "bootstrap-plan", "repository-observation-baseline"])
+          .has(artifact?.artifact_type)).length;
+    }
+    runtime = inspectRuntime(root, errors, workflowRoot);
+    errors.push(...runtime.dependency_errors);
+    if (installation.missing_skills.length) {
+      errors.push(`缺少项目级 skills：${installation.missing_skills.join(", ")}`);
+    }
+  }
+
+  let state;
+  if (!installation.detected) {
+    state = codebase.summary.has_code ? "codebase-uninitialized" : "empty-uninitialized";
+  } else if (!installation.complete || errors.length) {
+    state = "workflow-inconsistent";
+  } else if (runtime.active_task_ids.length) {
+    state = "workflow-interrupted";
+  } else {
+    state = "workflow-ready";
+  }
+  const recommendation = recommendationFor(state, workflow, runtime);
+  const codeGit = inspectGitRepository(codeRoot);
+  const workflowGit = inspectGitRepository(root);
+  const syncWarnings = [];
+  if (workflowGit.sync_status === "uncommitted") {
+    syncWarnings.push("工作流仓库存在未提交的共享状态或物料，其他协作者尚不可见。可以按任务范围 publish 后再交接。");
+  } else if (workflowGit.sync_status === "unpushed") {
+    syncWarnings.push("工作流仓库存在未推送提交，其他工作区尚不可见。");
+  }
+  return {
+    schema_version: 2,
+    project_root: toPosix(root),
+    workspace: workspaceRecord?.configuration || {
+      workflow_repository: { path: "." },
+      code_repository: { repo_id: "app", path: toPosix(path.relative(root, codeRoot)) || "." },
+    },
+    detected_at: new Date().toISOString(),
+    state,
+    installation,
+    workflow,
+    runtime,
+    codebase: codebase.summary,
+    git: codeGit,
+    workflow_git: workflowGit,
+    recommendation,
+    errors,
+    warnings: [...codebase.warnings, ...syncWarnings],
+  };
+}
+
+function csvCell(value) {
+  const text = value === null || value === undefined ? "" : String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+function toCsv(headers, rows) {
+  return `${[
+    headers.join(","),
+    ...rows.map((row) => headers.map((header) => csvCell(row[header])).join(",")),
+  ].join("\n")}\n`;
+}
+
+function packageCommands(root, files) {
+  const commands = [];
+  const manager = files.some((file) => file.path === "pnpm-lock.yaml")
+    ? "pnpm"
+    : files.some((file) => file.path === "yarn.lock") ? "yarn" : "npm";
+  for (const file of files.filter((item) => path.basename(item.path).toLowerCase() === "package.json")) {
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(file.absolute, "utf8"));
+      for (const script of Object.keys(packageJson.scripts || {}).sort()) {
+        commands.push({
+          working_directory: toPosix(path.dirname(file.path)) === "." ? "." : toPosix(path.dirname(file.path)),
+          command: manager === "yarn" ? `yarn ${script}` : `${manager} run ${script}`,
+          source: file.path,
+        });
+      }
+    } catch {
+      // The project state report already records malformed structured files when they are workflow-owned.
+    }
+  }
+  return commands;
+}
+
+function taskPlanFor(initialState, result) {
+  if (initialState === "empty-uninitialized") {
+    return [
+      { task_id: "BOOTSTRAP-NEXT-01", sequence: 1, skill: "ai-delivery-define-product", objective: "向用户收集初始产品问题、目标用户和成功标准", status: "queued", depends_on: [] },
+      { task_id: "BOOTSTRAP-NEXT-02", sequence: 2, skill: "ai-delivery-define-product", objective: "形成 Discovery Gate A 草稿并提交人工确认", status: "queued", depends_on: ["BOOTSTRAP-NEXT-01"] },
+    ];
+  }
+  if (initialState === "codebase-uninitialized") {
+    return [
+      { task_id: "BOOTSTRAP-NEXT-01", sequence: 1, skill: "ai-delivery-bootstrap", objective: "人工核对存量代码清单、技术栈和可执行命令", status: "queued", depends_on: [] },
+      { task_id: "BOOTSTRAP-NEXT-02", sequence: 2, skill: "ai-delivery-define-product", objective: "核对代码当前行为与真实产品意图，形成产品发现草稿", status: "queued", depends_on: ["BOOTSTRAP-NEXT-01"] },
+    ];
+  }
+  return [{
+    task_id: "BOOTSTRAP-NEXT-01",
+    sequence: 1,
+    skill: result.recommendation.skill,
+    objective: result.recommendation.action,
+    status: "queued",
+    depends_on: [],
+  }];
+}
+
+function adoptionMarkdown(initialState, scan, result) {
+  const gaps = [];
+  let artifactTypes = [];
+  try {
+    const registry = parseYaml(fs.readFileSync(
+      path.join(result.project_root, ".workflow", "delivery", "artifact-registry.yaml"),
+      "utf8",
+    ));
+    artifactTypes = (registry?.artifacts || []).map((artifact) => artifact.artifact_type || "");
+  } catch {
+    artifactTypes = [];
+  }
+  if (!artifactTypes.some((type) => /product.*baseline/.test(type))) gaps.push("缺少经确认的产品基线。");
+  if (!artifactTypes.some((type) => /architecture.*baseline/.test(type))) gaps.push("缺少经确认的架构基线。");
+  if (scan.summary.has_code && !scan.summary.categories.test) gaps.push("未发现可识别的自动化测试文件，需人工核对测试入口。");
+  if (!result.git.repository) gaps.push("当前目录不是有效 Git 仓库，分支和提交身份不可用。");
+  return `# 存量项目接入评估
+
+## 探测结论
+
+- 初始状态：\`${initialState}\`
+- 当前状态：\`${result.state}\`
+- 扫描文件：${scan.summary.scanned_file_count}
+- 代码证据：${scan.summary.code_evidence_count}
+- 检测技术：${scan.summary.technologies.join("、") || "未识别"}
+- 排除的敏感文件：${scan.summary.sensitive_file_count}
+
+## 上下文边界
+
+本报告只描述代码和仓库的可观察现状。代码行为不是已批准产品需求，自动归纳内容均保持 \`draft\`，必须通过产品和架构流程核对后才能成为正式基线。
+
+## 当前缺口
+
+${gaps.length ? gaps.map((gap) => `- ${gap}`).join("\n") : "- 未发现基础接入缺口；仍需按正式 Gate 验证产物。"}
+
+## 推荐动作
+
+${result.recommendation.action}
+`;
+}
+
+function registerBootstrapReport(root, entry) {
+  const yaml = {
+    parse: parseYaml,
+    stringify: (value) => stringifyYaml(value, { lineWidth: 0 }),
+  };
+  const inspected = executeDeliveryStateCommand(["inspect", "--project", root], { yaml });
+  executeDeliveryStateCommand([
+    "artifact", "register",
+    "--project", root,
+    "--expected-revision", String(inspected.artifact_registry.revision),
+    "--id", entry.artifact_id,
+    "--artifact-type", entry.artifact_type,
+    "--path", entry.path,
+    "--node", "00-bootstrap",
+    "--status", entry.status,
+    "--version", String(entry.version),
+    "--producer-skill", entry.producer_skill,
+  ], { yaml });
+}
+
+function writeBootstrapArtifacts(root, initialState, result, sourceScan = null) {
+  const configuredCodeRoot = path.resolve(root, result.workspace?.code_repository?.path || "code");
+  const scan = sourceScan || scanProjectFiles(configuredCodeRoot);
+  const stamp = new Date().toISOString().replace(/[-:.Z]/g, "");
+  const runId = `BOOTSTRAP-${stamp}`;
+  const artifactSuffix = stamp;
+  const relativeRunDirectory = `.workflow/delivery/bootstrap/runs/${runId}`;
+  const runDirectory = path.join(root, relativeRunDirectory);
+  fs.mkdirSync(runDirectory, { recursive: true });
+
+  const contextHeaders = ["path", "category", "technology", "purpose", "size_bytes", "sha256", "read_priority", "scan_status"];
+  const contextRows = scan.files.map((file) => ({
+    path: file.path,
+    category: file.category,
+    technology: file.technology,
+    purpose: file.purpose,
+    size_bytes: file.size_bytes,
+    sha256: file.size_bytes <= 10 * 1024 * 1024 ? sha256File(file.absolute) : "",
+    read_priority: file.priority,
+    scan_status: file.size_bytes <= 10 * 1024 * 1024 ? "indexed" : "large-file-not-hashed",
+  }));
+  const inventoryHeaders = ["inventory_id", "item_type", "name", "path", "technology", "role", "evidence", "status"];
+  const inventoryRows = scan.files
+    .filter((file) => file.category !== "other")
+    .map((file, index) => ({
+      inventory_id: `INV-${String(index + 1).padStart(4, "0")}`,
+      item_type: file.category,
+      name: path.basename(file.path),
+      path: file.path,
+      technology: file.technology,
+      role: file.purpose,
+      evidence: file.path,
+      status: "observed",
+    }));
+
+  const contextFile = path.join(runDirectory, "context-index.csv");
+  const inventoryFile = path.join(runDirectory, "codebase-inventory.csv");
+  const repositoryFile = path.join(runDirectory, "repository-baseline.yaml");
+  const assessmentFile = path.join(runDirectory, "adoption-assessment.md");
+  const planFile = path.join(runDirectory, "bootstrap-plan.yaml");
+  atomicWrite(contextFile, toCsv(contextHeaders, contextRows));
+  atomicWrite(inventoryFile, toCsv(inventoryHeaders, inventoryRows));
+  atomicWrite(repositoryFile, stringifyYaml({
+    artifact_id: `REPOSITORY-BASELINE-${artifactSuffix}`,
+    artifact_type: "repository-observation-baseline",
+    version: 1,
+    status: "draft",
+    producer_skill: "ai-delivery-bootstrap",
+    detected_at: result.detected_at,
+    repository: result.git,
+    codebase: scan.summary,
+    command_candidates: packageCommands(root, scan.files),
+    constraints: [
+      "Observed code is not an approved product requirement.",
+      "Commands are candidates until executed and verified.",
+      "Sensitive files are excluded from generated context.",
+    ],
+  }, { lineWidth: 0 }));
+  atomicWrite(assessmentFile, adoptionMarkdown(initialState, scan, result));
+  atomicWrite(planFile, stringifyYaml({
+    artifact_id: `BOOTSTRAP-PLAN-${artifactSuffix}`,
+    artifact_type: "bootstrap-plan",
+    version: 1,
+    status: "draft",
+    producer_skill: "ai-delivery-bootstrap",
+    initial_state: initialState,
+    resulting_state: result.state,
+    recommended_skill: result.recommendation.skill,
+    tasks: taskPlanFor(initialState, result),
+  }, { lineWidth: 0 }));
+
+  const relatedArtifacts = {
+    repository_baseline: {
+      ref: `${relativeRunDirectory}/repository-baseline.yaml`,
+      checksum: sha256File(repositoryFile),
+    },
+    codebase_inventory: {
+      ref: `${relativeRunDirectory}/codebase-inventory.csv`,
+      checksum: sha256File(inventoryFile),
+    },
+    context_index: {
+      ref: `${relativeRunDirectory}/context-index.csv`,
+      checksum: sha256File(contextFile),
+    },
+    adoption_assessment: {
+      ref: `${relativeRunDirectory}/adoption-assessment.md`,
+      checksum: sha256File(assessmentFile),
+    },
+    bootstrap_plan: {
+      ref: `${relativeRunDirectory}/bootstrap-plan.yaml`,
+      checksum: sha256File(planFile),
+    },
+  };
+  const reportFile = path.join(runDirectory, "project-state-report.yaml");
+  const report = {
+    artifact_id: `PROJECT-STATE-${artifactSuffix}`,
+    artifact_type: "project-state-report",
+    version: 1,
+    status: "draft",
+    producer_skill: "ai-delivery-bootstrap",
+    detected_at: result.detected_at,
+    initial_state: initialState,
+    resulting_state: result.state,
+    installation: result.installation,
+    workflow: result.workflow,
+    runtime: result.runtime,
+    codebase: result.codebase,
+    git: result.git,
+    recommendation: result.recommendation,
+    errors: result.errors,
+    warnings: result.warnings,
+    related_artifacts: relatedArtifacts,
+  };
+  atomicWrite(reportFile, stringifyYaml(report, { lineWidth: 0 }));
+  const reportChecksum = sha256File(reportFile);
+  const reportRef = `${relativeRunDirectory}/project-state-report.yaml`;
+  atomicWrite(path.join(root, ".workflow", "delivery", "bootstrap", "latest.yaml"), stringifyYaml({
+    run_id: runId,
+    state: result.state,
+    report_ref: reportRef,
+    report_algorithm: "sha256",
+    report_checksum: reportChecksum,
+    recommended_skill: result.recommendation.skill,
+    recommended_task_id: result.runtime.recommended_task_id,
+    updated_at: result.detected_at,
+  }, { lineWidth: 0 }));
+  registerBootstrapReport(root, {
+    artifact_id: report.artifact_id,
+    artifact_type: report.artifact_type,
+    version: 1,
+    status: "draft",
+    producer_skill: "ai-delivery-bootstrap",
+    path: reportRef,
+    checksum_algorithm: "sha256",
+    checksum: reportChecksum,
+  });
+  return {
+    run_id: runId,
+    report_ref: reportRef,
+    report_checksum: reportChecksum,
+    related_artifacts: relatedArtifacts,
+  };
+}
+
+export function bootstrapProject(packageRoot, target, options = {}) {
+  const root = path.resolve(target);
+  const { dryRun = false, force = false, packageVersion = "0.0.0", initProject = null } = options;
+  const initial = inspectProjectState(root);
+  const initialCodeRoot = path.resolve(root, initial.workspace?.code_repository?.path || "code");
+  const initialCodebaseScan = new Set(["empty-uninitialized", "codebase-uninitialized"]).has(initial.state)
+    ? scanProjectFiles(fs.existsSync(initialCodeRoot) ? initialCodeRoot : root)
+    : null;
+  const actions = [];
+  if (initial.state === "workflow-inconsistent") {
+    return {
+      initial_state: initial.state,
+      resulting_state: initial.state,
+      initialized: false,
+      artifacts_written: false,
+      actions,
+      inspection: initial,
+      message: "Workflow state is inconsistent; review the reported conflicts before mutation.",
+    };
+  }
+  if (new Set(["empty-uninitialized", "codebase-uninitialized"]).has(initial.state)) {
+    if (typeof initProject !== "function") {
+      throw new Error("Project-local bootstrap cannot install missing workflow files; run init once before using the local entrypoint.");
+    }
+    const initialization = initProject(packageRoot, root, { dryRun, force, packageVersion });
+    actions.push(...initialization.actions);
+    if (dryRun) {
+      return {
+        initial_state: initial.state,
+        resulting_state: initial.state,
+        initialized: false,
+        artifacts_written: false,
+        actions,
+        inspection: initial,
+        message: "Dry run completed; no project files were written.",
+      };
+    }
+  }
+  const result = inspectProjectState(root);
+  const hasRecommendedTask = result.state === "workflow-interrupted"
+    || Boolean(result.runtime.recommended_task_id);
+  const shouldDeferToRecovery = hasRecommendedTask && result.runtime.next_action_owner === "agent";
+  const shouldDeferToUser = hasRecommendedTask && result.runtime.next_action_owner === "user";
+  const shouldDeferToExternal = hasRecommendedTask && result.runtime.next_action_owner === "external";
+  const artifacts = dryRun || hasRecommendedTask
+    ? null
+    : writeBootstrapArtifacts(root, initial.state, result, initialCodebaseScan);
+  return {
+    initial_state: initial.state,
+    resulting_state: result.state,
+    initialized: new Set(["empty-uninitialized", "codebase-uninitialized"]).has(initial.state) && !dryRun,
+    artifacts_written: Boolean(artifacts),
+    deferred_to_recovery: shouldDeferToRecovery,
+    deferred_to_user: shouldDeferToUser,
+    deferred_to_external: shouldDeferToExternal,
+    actions,
+    inspection: result,
+    artifacts,
+    message: shouldDeferToUser
+      ? result.runtime.next_action
+      : shouldDeferToExternal
+        ? `Wait for external input: ${result.runtime.next_action}`
+        : shouldDeferToRecovery
+          ? `Resume task ${result.runtime.recommended_task_id} before any bootstrap mutation.`
+          : "Project bootstrap completed.",
+  };
+}