ai-delivery-workflow 0.5.0 → 0.6.0

package/lib/fs-utils.mjs

@@ -35,19 +35,3 @@ export function assertPathInside(root, target) {
   if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) return target;
   throw new Error(`Path resolves outside the project: ${target} -> ${realAncestor}`);
 }
-
-export function resolveContainedRelativePath(root, relative, allowedPrefixes = []) {
-  const value = String(relative || "");
-  if (!value || value.includes("\\") || value.includes("\0")
-    || path.posix.isAbsolute(value) || path.posix.normalize(value) !== value
-    || value === ".." || value.startsWith("../")) {
-    throw new Error(`Invalid migration path: ${value || "missing"}.`);
-  }
-  if (allowedPrefixes.length && !allowedPrefixes.some((prefix) =>
-    value === prefix || value.startsWith(`${prefix}/`))) {
-    throw new Error(`Migration path is outside its allowed area: ${value}.`);
-  }
-  const target = path.resolve(root, ...value.split("/"));
-  assertPathInside(root, target);
-  return target;
-}

package/lib/project-bootstrap.mjs

@@ -8,13 +8,13 @@ import {
   stableValue,
   withFormalStateReadLock,
 } from "./delivery-state.mjs";
+import { readConfirmationSummary } from "./communication-confirmation.mjs";
 import { inspectGitRepository, readWorkspaceConfiguration } from "./workspace.mjs";
 
 const IGNORED_DIRECTORIES = new Set([
   ".git",
   ".agents",
   ".codex",
-  ".ai-delivery",
   ".workflow",
   ".idea",
   ".vscode",
@@ -33,6 +33,50 @@ const IGNORED_DIRECTORIES = new Set([
   "target",
 ]);
 const VALID_NEXT_ACTION_OWNERS = new Set(["agent", "user", "external"]);
+const CODEBASE_DOCUMENTATION_FILES = [
+  { path: "AGENTS.md", kind: "agent-entrypoint" },
+  { path: "CODEBASE_GUIDE.md", kind: "maintainer-guide" },
+  { path: "docs/CODEBASE_INDEX.md", kind: "navigation-index" },
+];
+const CODEBASE_DOCUMENTATION_STATUS = new Set(["observed", "approved", "stale"]);
+
+export function inspectConfirmationSummaries(root) {
+  const base = path.join(root, ".workflow", "iterations");
+  const summaries = [];
+  const errors = [];
+  if (!fs.existsSync(base)) return { status: "absent", summaries, errors };
+  const visit = (directory) => {
+    let entries;
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch (error) {
+      errors.push(`${toPosix(path.relative(root, directory))}: ${error.message}`);
+      return;
+    }
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && entry.name === "confirmation-summary.yaml") {
+        try {
+          const result = readConfirmationSummary(absolute);
+          summaries.push({
+            path: toPosix(path.relative(root, absolute)),
+            checksum: sha256File(absolute),
+            summary_id: result.summary.summary_id,
+            version: result.summary.version,
+            frontier: result.validation.frontier,
+            blocked_proposals: result.validation.blocked_proposals,
+            valid: result.validation.valid,
+            errors: result.validation.errors,
+          });
+          if (!result.validation.valid) errors.push(...result.validation.errors.map((item) => `${toPosix(path.relative(root, absolute))}: ${item}`));
+        } catch (error) {
+          errors.push(`${toPosix(path.relative(root, absolute))}: ${error.message}`);
+        }
+      }
+    }
+  };
+  visit(base);
+  return { status: errors.length ? "invalid" : summaries.length ? "valid" : "absent", summaries, errors };
+}
 
 const SOURCE_EXTENSIONS = new Map([
   [".c", "C"],
@@ -94,19 +138,6 @@ const WORKFLOW_REQUIRED_FILES = [
   ".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",
@@ -269,6 +300,199 @@ function scanProjectFiles(root, maxFiles = 10_000) {
   };
 }
 
+function hasSensitiveContent(text) {
+  return /BEGIN (?:RSA|OPENSSH|EC|DSA) PRIVATE KEY|(?:AKIA|ASIA)[A-Z0-9]{16}|(?:ghp|github_pat)_[A-Za-z0-9_]{20,}/.test(text)
+    || /(?:password|secret|token|api[_-]?key)\s*[:=]\s*["'][^"']{8,}["']/i.test(text);
+}
+
+function documentationMetadata(text) {
+  const status = text.match(/(?:^|\|)\s*(?:状态|项目状态)\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim().toLowerCase() || null;
+  const sourceCommit = text.match(/(?:适用代码提交|对应代码提交|source_commit)\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || text.match(/`source_commit`\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || null;
+  const lastReviewed = text.match(/(?:最后核对|last_reviewed)\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || text.match(/`last_reviewed`\s*\|\s*`?([^|\n`]+)`?/m)?.[1]?.trim()
+    || null;
+  return { status, source_commit: sourceCommit, last_reviewed: lastReviewed };
+}
+
+function documentationPathEntries(text) {
+  const entries = [];
+  let header = null;
+  for (const [index, line] of text.split(/\r?\n/).entries()) {
+    if (!line.trim().startsWith("|")) continue;
+    const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
+    if (!cells.length) continue;
+    if (cells.some((cell) => /^(路径|文件)$/.test(cell))) {
+      header = cells;
+      continue;
+    }
+    if (!header || cells.every((cell) => /^:?-{3,}:?$/.test(cell))) continue;
+    const pathIndex = header.findIndex((cell) => /^(路径|文件)$/.test(cell));
+    if (pathIndex < 0 || !cells[pathIndex]) continue;
+    entries.push({ value: cells[pathIndex].replaceAll("`", "").trim(), line: index + 1 });
+  }
+  return entries;
+}
+
+function documentationLinks(text) {
+  return [...text.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map((match) => match[1].trim());
+}
+
+export function inspectCodebaseDocumentation(root, git = inspectGitRepository(root)) {
+  const files = [];
+  const errors = [];
+  const warnings = [];
+  const missing = [];
+  const invalid = [];
+  const stale = [];
+  const statuses = [];
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return {
+      status: "missing",
+      files: [],
+      missing: CODEBASE_DOCUMENTATION_FILES.map((item) => item.path),
+      invalid: [],
+      stale: [],
+      sensitive_file_count: 0,
+      errors: [],
+      warnings: ["代码仓库目录不存在，无法发现项目说明书和索引。"],
+    };
+  }
+
+  for (const expected of CODEBASE_DOCUMENTATION_FILES) {
+    const absolute = path.join(root, expected.path);
+    if (!fs.existsSync(absolute)) {
+      missing.push(expected.path);
+      continue;
+    }
+    let stat;
+    try {
+      stat = fs.lstatSync(absolute);
+    } catch (error) {
+      invalid.push({ path: expected.path, reason: `无法读取文件：${error.code || error.message}` });
+      continue;
+    }
+    if (stat.isSymbolicLink()) {
+      invalid.push({ path: expected.path, reason: "说明文件不能是符号链接" });
+      continue;
+    }
+    if (!stat.isFile()) {
+      invalid.push({ path: expected.path, reason: "说明路径必须是普通文件" });
+      continue;
+    }
+    let text;
+    try {
+      text = fs.readFileSync(absolute, "utf8");
+    } catch (error) {
+      invalid.push({ path: expected.path, reason: `无法读取文件：${error.code || error.message}` });
+      continue;
+    }
+    const metadata = documentationMetadata(text);
+    const record = { path: expected.path, kind: expected.kind, ...metadata, bytes: stat.size };
+    files.push(record);
+    if (expected.kind !== "agent-entrypoint") {
+      if (!metadata.status) invalid.push({ path: expected.path, reason: "缺少 status/状态字段" });
+      if (!metadata.source_commit) invalid.push({ path: expected.path, reason: "缺少 source_commit/适用代码提交字段" });
+      if (!metadata.last_reviewed) invalid.push({ path: expected.path, reason: "缺少 last_reviewed/最后核对字段" });
+    }
+    if (metadata.status && !CODEBASE_DOCUMENTATION_STATUS.has(metadata.status)) {
+      invalid.push({ path: expected.path, reason: `status 无效：${metadata.status}` });
+    }
+    if (metadata.status) statuses.push(metadata.status);
+    if (hasSensitiveContent(text)) {
+      invalid.push({ path: expected.path, reason: "疑似包含凭据、私钥或敏感值" });
+    }
+    if (git?.head && metadata.source_commit && !/^<.*>$/.test(metadata.source_commit)
+      && metadata.source_commit !== "-" && metadata.source_commit !== git.head) {
+      stale.push({ path: expected.path, reason: `source_commit ${metadata.source_commit} 与当前 HEAD ${git.head} 不一致` });
+    }
+    if (expected.kind === "maintainer-guide") {
+      for (const heading of ["项目概览", "快速开始", "仓库地图", "工程分层", "工程约定", "变更工作流", "风险和保护边界", "文档维护"]) {
+        if (!new RegExp(`^## .*${heading}`, "m").test(text)) {
+          invalid.push({ path: expected.path, reason: `缺少章节：${heading}` });
+        }
+      }
+    }
+    if (expected.kind === "navigation-index") {
+      for (const field of ["路径", "职责", "主要入口", "关联测试", "风险", "状态", "source_commit", "last_reviewed"]) {
+        if (!text.includes(field)) invalid.push({ path: expected.path, reason: `缺少索引字段：${field}` });
+      }
+      for (const entry of documentationPathEntries(text)) {
+        const value = entry.value;
+        if (!value || value === "-" || /^<.*>$/.test(value) || value.includes("*")) continue;
+        if (path.isAbsolute(value) || value.split("/").includes("..")) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行路径越界：${value}` });
+          continue;
+        }
+        const target = path.resolve(root, value);
+        const relative = path.relative(root, target);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行路径越界：${value}` });
+          continue;
+        }
+        if (!fs.existsSync(target)) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行引用路径不存在：${value}` });
+          continue;
+        }
+        if (fs.lstatSync(target).isSymbolicLink()) {
+          invalid.push({ path: expected.path, reason: `第 ${entry.line} 行引用符号链接：${value}` });
+        }
+      }
+    }
+    const seenPaths = new Set();
+    for (const entry of documentationPathEntries(text)) {
+      if (/^<.*>$/.test(entry.value) || entry.value === "-" || entry.value.includes("*")) continue;
+      if (seenPaths.has(entry.value)) {
+        invalid.push({ path: expected.path, reason: `第 ${entry.line} 行重复索引路径：${entry.value}` });
+      }
+      seenPaths.add(entry.value);
+    }
+    for (const link of documentationLinks(text)) {
+      const targetValue = link.split(/[?#]/, 1)[0];
+      if (!targetValue || targetValue.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(targetValue)) continue;
+      if (path.isAbsolute(targetValue) || targetValue.split("/").includes("..")) {
+        invalid.push({ path: expected.path, reason: `Markdown 链接越界：${link}` });
+        continue;
+      }
+      const target = path.resolve(root, path.dirname(expected.path), targetValue);
+      const relative = path.relative(root, target);
+      if (relative.startsWith("..") || path.isAbsolute(relative) || !fs.existsSync(target)) {
+        invalid.push({ path: expected.path, reason: `Markdown 链接路径不存在：${link}` });
+      }
+    }
+  }
+
+  if (missing.length) warnings.push(`缺少代码仓库说明文件：${missing.join(", ")}`);
+  if (invalid.length) errors.push(...invalid.map((item) => `${item.path}: ${item.reason}`));
+  if (stale.length) warnings.push(...stale.map((item) => `${item.path}: ${item.reason}`));
+  const hasTemplatePlaceholders = files.some((file) => file.source_commit?.startsWith("<") || file.status === null);
+  if (new Set(statuses).size > 1) {
+    errors.push(`代码仓库说明文档状态冲突：${[...new Set(statuses)].join(", ")}`);
+  }
+  const status = invalid.length || errors.length
+    ? "invalid"
+    : stale.length
+      ? "stale"
+      : missing.length
+        ? "missing"
+        : statuses.some((value) => value === "stale")
+          ? "stale"
+          : hasTemplatePlaceholders || statuses.some((value) => value === "observed")
+          ? "observed"
+          : "approved";
+  return {
+    status,
+    files,
+    missing,
+    invalid,
+    stale,
+    sensitive_file_count: invalid.filter((item) => item.reason.includes("敏感值")).length,
+    errors,
+    warnings,
+  };
+}
+
 function gitState(root) {
   const run = (args) => spawnSync("git", args, { cwd: root, encoding: "utf8", windowsHide: true });
   const topLevel = run(["rev-parse", "--show-toplevel"]);
@@ -306,13 +530,13 @@ function normalizeInspectedScope(value, fallbackScopeId = null) {
 }
 
 function inspectWorkflowScopes(workflowState, errors) {
-  const schemaVersion = Number(workflowState?.schema_version || 1);
-  const development = schemaVersion >= 2
-    ? normalizeInspectedScope(workflowState.development_state)
-    : normalizeInspectedScope(workflowState, workflowState.iteration_id ?? null);
-  const release = schemaVersion >= 2
-    ? normalizeInspectedScope(workflowState.release_state)
-    : normalizeInspectedScope(null);
+  if (Number(workflowState?.schema_version) !== 2
+    || !workflowState?.development_state || !workflowState?.release_state) {
+    errors.push("formal state must use schema 2 with development_state and release_state scopes");
+    return { development: normalizeInspectedScope(null), release: normalizeInspectedScope(null) };
+  }
+  const development = normalizeInspectedScope(workflowState.development_state);
+  const release = normalizeInspectedScope(workflowState.release_state);
 
   for (const [scopeName, scope] of [["development", development], ["release", release]]) {
     for (const conflict of findIncompatibleNodeStates(scope)) {
@@ -505,23 +729,15 @@ export function inspectProjectState(target) {
   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")
+  const unsupportedIndicators = [".ai-delivery", ".ai-delivery-task", "delivery", "standards"]
     .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 workflowRoot = ".workflow";
+  const workflowIndicators = WORKFLOW_REQUIRED_FILES.filter((file) => exists(root, file));
+  const missingFiles = WORKFLOW_REQUIRED_FILES.filter((file) => !exists(root, file));
   const installation = {
-    detected: currentIndicators.length > 0 || legacyIndicators.length > 0,
-    complete: workflowIndicators.length === requiredFiles.length,
+    detected: currentIndicators.length > 0 || unsupportedIndicators.length > 0,
+    complete: workflowIndicators.length === WORKFLOW_REQUIRED_FILES.length,
     workflow_root: workflowRoot,
-    legacy_layout: legacyLayout,
     present_files: workflowIndicators,
     missing_files: missingFiles,
     installed_skill_count: 0,
@@ -556,25 +772,13 @@ export function inspectProjectState(target) {
     dependency_errors: [],
   };
 
-  if (legacyLayout) {
-    errors.push("检测到旧版 delivery/ 与 standards/ 布局；迁移到 .workflow/ 后才能继续执行。");
-  }
-  if (currentStateIndicators.length > 0 && legacyStateIndicators.length > 0) {
-    errors.push("同时检测到 .workflow 和旧版 delivery/standards 状态；必须人工确定唯一权威根。");
+  if (unsupportedIndicators.length) {
+    errors.push(`检测到不受支持的旧工作流路径：${unsupportedIndicators.join(", ")}。当前项目只接受 .workflow/ 布局。`);
   }
 
   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 manifest = readStructuredFile(path.join(root, ".workflow/config/install-manifest.json"), "json", errors);
+    const stateRoot = path.join(root, ".workflow");
     let project = null;
     let workflowState = null;
     let registry = null;
@@ -583,13 +787,10 @@ export function inspectProjectState(target) {
       workflowState = readStructuredFile(path.join(stateRoot, "delivery", "workflow-state.yaml"), "yaml", errors);
       registry = readStructuredFile(path.join(stateRoot, "delivery", "artifact-registry.yaml"), "yaml", errors);
     };
-    if (legacyLayout) readFormalState();
-    else {
-      try {
-        withFormalStateReadLock(root, readFormalState);
-      } catch (error) {
-        errors.push(error.message);
-      }
+    try {
+      withFormalStateReadLock(root, readFormalState);
+    } catch (error) {
+      errors.push(error.message);
     }
     readStructuredFile(path.join(stateRoot, "delivery", "standards-baseline.yaml"), "yaml", errors);
     readStructuredFile(path.join(stateRoot, "standards", "index.yaml"), "yaml", errors);
@@ -630,8 +831,19 @@ export function inspectProjectState(target) {
     }
   }
 
+  const codeGit = inspectGitRepository(codeRoot);
+  const documentation = inspectCodebaseDocumentation(codeRoot, codeGit);
+  const confirmations = inspectConfirmationSummaries(root);
+  if (confirmations.errors.length) errors.push(...confirmations.errors);
+  codebase.summary.documentation = documentation;
+  codebase.summary.confirmations = confirmations;
+  errors.push(...documentation.errors);
+  const documentationWarnings = documentation.warnings;
+
   let state;
-  if (!installation.detected) {
+  if (errors.length) {
+    state = "workflow-inconsistent";
+  } else if (!installation.detected) {
     state = codebase.summary.has_code ? "codebase-uninitialized" : "empty-uninitialized";
   } else if (!installation.complete || errors.length) {
     state = "workflow-inconsistent";
@@ -641,7 +853,6 @@ export function inspectProjectState(target) {
     state = "workflow-ready";
   }
   const recommendation = recommendationFor(state, workflow, runtime);
-  const codeGit = inspectGitRepository(codeRoot);
   const workflowGit = inspectGitRepository(root);
   const syncWarnings = [];
   if (workflowGit.sync_status === "uncommitted") {
@@ -662,11 +873,12 @@ export function inspectProjectState(target) {
     workflow,
     runtime,
     codebase: codebase.summary,
+    confirmations,
     git: codeGit,
     workflow_git: workflowGit,
     recommendation,
     errors,
-    warnings: [...codebase.warnings, ...syncWarnings],
+    warnings: [...codebase.warnings, ...documentationWarnings, ...syncWarnings],
   };
 }
 
@@ -738,6 +950,10 @@ function adoptionMarkdown(initialState, scan, result) {
   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 仓库，分支和提交身份不可用。");
+  const documentation = result.codebase.documentation;
+  if (documentation?.status === "missing") gaps.push("代码仓库说明书或导航索引缺失，需要在维护者确认后补齐。");
+  if (documentation?.status === "invalid") gaps.push("代码仓库说明书或导航索引存在结构、路径或敏感内容问题，Bootstrap 已阻止将其视为可信上下文。");
+  if (documentation?.status === "stale") gaps.push("代码仓库说明书或导航索引相对当前提交过期，需要更新 source_commit 并重新审阅。");
   return `# 存量项目接入评估
 
 ## 探测结论
@@ -749,6 +965,14 @@ function adoptionMarkdown(initialState, scan, result) {
 - 检测技术：${scan.summary.technologies.join("、") || "未识别"}
 - 排除的敏感文件：${scan.summary.sensitive_file_count}
 
+## 代码仓库说明书与导航
+
+- 状态：\`${documentation?.status || "missing"}\`
+- 已发现：${(documentation?.files || []).filter((item) => item.status !== "missing").map((item) => item.path).join("、") || "无"}
+- 缺失：${(documentation?.missing || []).join("、") || "无"}
+- 失效：${(documentation?.invalid || []).map((item) => item.path).join("、") || "无"}
+- 过期：${(documentation?.stale || []).map((item) => item.path).join("、") || "无"}
+
 ## 上下文边界
 
 本报告只描述代码和仓库的可观察现状。代码行为不是已批准产品需求，自动归纳内容均保持 \`draft\`，必须通过产品和架构流程核对后才能成为正式基线。
@@ -814,6 +1038,7 @@ function writeBootstrapArtifacts(root, initialState, result, sourceScan = null)
     detected_at: result.detected_at,
     repository: result.git,
     codebase: scan.summary,
+    documentation: result.codebase.documentation,
     command_candidates: packageCommands(root, scan.files),
     constraints: [
       "Observed code is not an approved product requirement.",
@@ -870,6 +1095,8 @@ function writeBootstrapArtifacts(root, initialState, result, sourceScan = null)
     workflow: result.workflow,
     runtime: result.runtime,
     codebase: result.codebase,
+    documentation: result.codebase.documentation,
+    confirmations: result.confirmations,
     git: result.git,
     recommendation: result.recommendation,
     errors: result.errors,