ai-delivery-workflow 0.2.2

package/lib/project-installer.mjs

@@ -0,0 +1,1184 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { isSeq, parse as parseYaml, parseDocument } from "yaml";
+import { inspectHookConfig, mergeHookConfig } from "./toml-hooks.mjs";
+import {
+  LEGACY_WORKSPACE_CONFIG,
+  WORKSPACE_CONFIG,
+  gitCommonDirectory,
+  gitTopLevel,
+  initializeGitWorkspace,
+  readWorkspaceConfiguration,
+  workspaceConfigurationText,
+} from "./workspace.mjs";
+
+const require = createRequire(import.meta.url);
+const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const MANAGED_START = "<!-- ai-delivery:start -->";
+const MANAGED_END = "<!-- ai-delivery:end -->";
+const IGNORE_ENTRIES = [".workflow/delivery/runtime/"];
+const GIT_ATTRIBUTE_ENTRIES = [
+  "/.workflow/** text=auto eol=lf",
+  "/.agents/skills/ai-delivery-*/** text=auto eol=lf",
+  "/.codex/config.toml text eol=lf",
+  "/AGENTS.md text eol=lf",
+  "/.gitignore text eol=lf",
+  "/.gitattributes text eol=lf",
+];
+const OBSOLETE_IGNORE_ENTRIES = new Set([".ai-delivery-task", ".ai-delivery/backups/"]);
+const INSTALL_MANIFEST = path.join(".workflow", "config", "install-manifest.json");
+const ACTIVE_TASK = path.join(".workflow", "delivery", "runtime", "active-task.json");
+const LEGACY_ACTIVE_TASK = ".ai-delivery-task";
+const WORKFLOW_CONTENT_DIRECTORIES = ["product", "architecture", "experience", "iterations", "releases"];
+const CONTROL_DIRECTORIES = ["tasks", "checkpoints", "artifacts", "gates", "versions", "releases", "events", "archives"];
+const ESSENTIAL_STARTUP_SKILLS = [
+  "ai-delivery-assemble-release",
+  "ai-delivery-bootstrap",
+  "ai-delivery-checkpoint-task",
+  "ai-delivery-close-version",
+  "ai-delivery-evolve-workflow",
+  "ai-delivery-orchestrate",
+  "ai-delivery-orchestrate-release",
+];
+const DELIVERY_SKILLS = Object.freeze([
+  "ai-delivery-assemble-release",
+  "ai-delivery-bootstrap",
+  "ai-delivery-checkpoint-task",
+  "ai-delivery-close-version",
+  "ai-delivery-define-product",
+  "ai-delivery-deploy-production",
+  "ai-delivery-design-architecture",
+  "ai-delivery-design-experience",
+  "ai-delivery-design-tests",
+  "ai-delivery-develop-iteration",
+  "ai-delivery-evolve-workflow",
+  "ai-delivery-execute-test",
+  "ai-delivery-execute-work-package",
+  "ai-delivery-manage-git",
+  "ai-delivery-manage-standards",
+  "ai-delivery-orchestrate",
+  "ai-delivery-orchestrate-release",
+  "ai-delivery-plan-iteration",
+  "ai-delivery-prepare-platform",
+  "ai-delivery-prepare-release",
+  "ai-delivery-review-change",
+  "ai-delivery-triage-failure",
+  "ai-delivery-validate-artifacts",
+  "ai-delivery-verify-candidate",
+  "ai-delivery-verify-production",
+]);
+
+function comparePackageVersions(left, right) {
+  const parse = (value) => {
+    const match = String(value || "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+    if (!match) return null;
+    return {
+      core: match.slice(1, 4).map(Number),
+      prerelease: match[4] ? match[4].split(".") : [],
+    };
+  };
+  const current = parse(left);
+  const previous = parse(right);
+  if (!current || !previous) return null;
+  for (let index = 0; index < 3; index += 1) {
+    if (current.core[index] !== previous.core[index]) {
+      return current.core[index] > previous.core[index] ? 1 : -1;
+    }
+  }
+  if (!current.prerelease.length && !previous.prerelease.length) return 0;
+  if (!current.prerelease.length) return 1;
+  if (!previous.prerelease.length) return -1;
+  const length = Math.max(current.prerelease.length, previous.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const currentPart = current.prerelease[index];
+    const previousPart = previous.prerelease[index];
+    if (currentPart === undefined) return -1;
+    if (previousPart === undefined) return 1;
+    if (currentPart === previousPart) continue;
+    const currentNumeric = /^\d+$/.test(currentPart);
+    const previousNumeric = /^\d+$/.test(previousPart);
+    if (currentNumeric && previousNumeric) return Number(currentPart) > Number(previousPart) ? 1 : -1;
+    if (currentNumeric !== previousNumeric) return currentNumeric ? -1 : 1;
+    return currentPart > previousPart ? 1 : -1;
+  }
+  return 0;
+}
+
+function isInside(candidate, root) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function samePath(left, right) {
+  const normalize = (value) => path.resolve(value).replaceAll("\\", "/").toLowerCase();
+  return normalize(left) === normalize(right);
+}
+
+function validateTarget(target, options = {}) {
+  if (!fs.existsSync(target) && options.create) fs.mkdirSync(target, { recursive: true });
+  if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${target}`);
+  }
+  const home = path.resolve(os.homedir());
+  const globalRoots = [path.join(home, ".codex"), path.join(home, ".agents")];
+  if (samePath(target, home) || globalRoots.some((root) => isInside(target, root))) {
+    throw new Error(`Refusing a global installation target: ${target}`);
+  }
+}
+
+function validateManagedPath(target, destination) {
+  const realTarget = fs.realpathSync(target);
+  let existingAncestor = destination;
+  while (!fs.existsSync(existingAncestor)) {
+    const parent = path.dirname(existingAncestor);
+    if (parent === existingAncestor) break;
+    existingAncestor = parent;
+  }
+  const realAncestor = fs.realpathSync(existingAncestor);
+  if (!isInside(realAncestor, realTarget)) {
+    throw new Error(`Managed path resolves outside the project: ${destination} -> ${realAncestor}`);
+  }
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, content, "utf8");
+  fs.renameSync(temp, file);
+}
+
+function filesUnder(root) {
+  if (!fs.existsSync(root)) return [];
+  const files = [];
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) files.push(absolute);
+    }
+  };
+  visit(root);
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function normalizedManagedContent(file) {
+  const content = fs.readFileSync(file);
+  return content.includes(0) ? content : Buffer.from(content.toString("utf8").replaceAll("\r\n", "\n"));
+}
+
+function managedFilesEqual(left, right) {
+  return normalizedManagedContent(left).equals(normalizedManagedContent(right));
+}
+
+function directoryDigest(root) {
+  const hash = crypto.createHash("sha256");
+  for (const file of filesUnder(root)) {
+    hash.update(path.relative(root, file).replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(normalizedManagedContent(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function managedFileDigest(file) {
+  return crypto.createHash("sha256").update(normalizedManagedContent(file)).digest("hex");
+}
+
+function sourceSetDigest(sources) {
+  const hash = crypto.createHash("sha256");
+  for (const item of [...sources].sort((left, right) => left.relative.localeCompare(right.relative))) {
+    hash.update(item.relative.replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(normalizedManagedContent(item.source));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function packagedSkillNames(packageRoot) {
+  const sourceSkills = path.join(packageRoot, "skills");
+  const actual = fs.readdirSync(sourceSkills, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith("ai-delivery-"))
+    .map((entry) => entry.name)
+    .sort();
+  if (JSON.stringify(actual) !== JSON.stringify(DELIVERY_SKILLS)) {
+    throw new Error(`Package skill inventory must be the fixed ${DELIVERY_SKILLS.length} skills.`);
+  }
+  return [...DELIVERY_SKILLS];
+}
+
+function mergeManagedMarkdown(existing, managedTemplate) {
+  const body = managedTemplate.trim();
+  const block = `${MANAGED_START}\n${body}\n${MANAGED_END}`;
+  const start = existing.indexOf(MANAGED_START);
+  const end = existing.indexOf(MANAGED_END);
+  if (start === -1 && end === -1) return `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}\n`;
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error("AGENTS.md contains an incomplete ai-delivery managed block.");
+  }
+  return `${existing.slice(0, start)}${block}${existing.slice(end + MANAGED_END.length)}`.replace(/\s*$/, "\n");
+}
+
+function mergeGitignore(existing, requiredEntries = []) {
+  const lines = existing.split(/\r?\n/)
+    .filter((line) => !OBSOLETE_IGNORE_ENTRIES.has(line.trim()));
+  const additions = [...IGNORE_ENTRIES, ...requiredEntries]
+    .filter((entry) => !lines.some((line) => line.trim() === entry));
+  const retained = lines.join("\n").trimEnd();
+  if (!additions.length) return retained ? `${retained}\n` : "";
+  return `${retained}${retained ? "\n" : ""}${additions.join("\n")}\n`;
+}
+
+function mergeGitattributes(existing) {
+  const lines = existing.split(/\r?\n/);
+  const additions = GIT_ATTRIBUTE_ENTRIES
+    .filter((entry) => !lines.some((line) => line.trim() === entry));
+  const retained = lines.join("\n").trimEnd();
+  if (!additions.length) return retained ? `${retained}\n` : "";
+  return `${retained}${retained ? "\n" : ""}${additions.join("\n")}\n`;
+}
+
+function ignoresWholeWorkflow(existing) {
+  return existing.split(/\r?\n/)
+    .map((line) => line.trim())
+    .some((line) => new Set([".workflow", ".workflow/", "/.workflow", "/.workflow/"]).has(line));
+}
+
+function mergeStandardsIndex(existing, template) {
+  const defaults = parseYaml(template)?.standards;
+  if (!Array.isArray(defaults)) throw new Error("Packaged standards/index.yaml is invalid.");
+  const document = parseDocument(existing || "standards: []\n");
+  if (document.errors.length) throw new Error(`Existing standards/index.yaml is invalid: ${document.errors[0].message}`);
+  let standards = document.get("standards", true);
+  if (!standards) {
+    document.set("standards", []);
+    standards = document.get("standards", true);
+  }
+  if (!isSeq(standards)) throw new Error("Existing standards/index.yaml must contain a standards sequence.");
+  const existingValues = document.toJS().standards || [];
+  const added = [];
+  for (const standard of defaults) {
+    const current = existingValues.find((item) => item?.id === standard.id);
+    if (current) {
+      for (const key of ["version", "status", "path"]) {
+        if (current[key] !== standard[key]) {
+          throw new Error(`Standard ${standard.id} conflicts on ${key}; resolve it through standards governance.`);
+        }
+      }
+      continue;
+    }
+    standards.add(document.createNode(standard));
+    added.push(standard.id);
+  }
+  return { text: document.toString(), added };
+}
+
+function copyMissingTree(source, destination, actions, dryRun) {
+  for (const sourceFile of filesUnder(source)) {
+    const relative = path.relative(source, sourceFile);
+    const destinationFile = path.join(destination, relative);
+    if (fs.existsSync(destinationFile)) continue;
+    actions.push(`create ${path.relative(path.dirname(destination), destinationFile)}`);
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(destinationFile), { recursive: true });
+      fs.copyFileSync(sourceFile, destinationFile);
+    }
+  }
+}
+
+function backupAndRemove(target, destination, backupRoot, actions, dryRun) {
+  const relative = path.relative(target, destination);
+  if (!isInside(destination, target)) throw new Error(`Managed path escapes project: ${destination}`);
+  actions.push(`back up and replace ${relative}`);
+  if (dryRun) return false;
+  const backup = path.join(backupRoot, relative);
+  fs.mkdirSync(path.dirname(backup), { recursive: true });
+  fs.cpSync(destination, backup, { recursive: true });
+  fs.rmSync(destination, { recursive: true, force: true });
+  return true;
+}
+
+function backupAndReplace(target, destination, source, backupRoot, actions, dryRun) {
+  if (!backupAndRemove(target, destination, backupRoot, actions, dryRun)) return;
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.cpSync(source, destination, { recursive: true });
+}
+
+function stateRuntimeSources(packageRoot, sourceTemplate) {
+  const yamlRoot = path.dirname(require.resolve("yaml/package.json"));
+  if (!fs.existsSync(yamlRoot)) {
+    throw new Error(`The packaged YAML runtime is missing: ${yamlRoot}`);
+  }
+  return [
+    {
+      source: path.join(sourceTemplate, ".workflow", "tools", "state", "state.mjs"),
+      relative: "state.mjs",
+    },
+    {
+      source: path.join(packageRoot, "lib", "delivery-state.mjs"),
+      relative: "delivery-state.mjs",
+    },
+    ...filesUnder(yamlRoot).map((source) => ({
+      source,
+      relative: path.join("vendor", "yaml", path.relative(yamlRoot, source)),
+    })),
+  ];
+}
+
+function evolutionRuntimeSources(packageRoot, sourceTemplate) {
+  return [
+    {
+      source: path.join(sourceTemplate, ".workflow", "tools", "evolution", "evolve.mjs"),
+      relative: "evolve.mjs",
+    },
+    {
+      source: path.join(packageRoot, "lib", "evolution.mjs"),
+      relative: "evolution-runtime.mjs",
+    },
+  ];
+}
+
+function bootstrapRuntimeSources(packageRoot, sourceTemplate) {
+  return [
+    {
+      source: path.join(sourceTemplate, ".workflow", "tools", "bootstrap", "bootstrap.mjs"),
+      relative: "bootstrap.mjs",
+    },
+    ...["project-bootstrap.mjs", "workspace.mjs", "yaml-runtime.mjs", "delivery-state.mjs"].map((name) => ({
+      source: path.join(packageRoot, "lib", name),
+      relative: name,
+    })),
+  ];
+}
+
+function managedRuntimeMatches(destination, sources) {
+  if (!fs.existsSync(destination)) return false;
+  const expected = new Map(sources.map((item) => [
+    item.relative.replaceAll("\\", "/"),
+    item.source,
+  ]));
+  const actualFiles = filesUnder(destination);
+  if (actualFiles.length !== expected.size) return false;
+  return actualFiles.every((file) => {
+    const relative = path.relative(destination, file).replaceAll("\\", "/");
+    const source = expected.get(relative);
+    return source && managedFilesEqual(file, source);
+  });
+}
+
+function installManagedRuntime(destination, sources) {
+  fs.mkdirSync(destination, { recursive: true });
+  for (const item of sources) {
+    const target = path.join(destination, item.relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(item.source, target);
+  }
+}
+
+function planManagedRuntime({
+  target,
+  installPath,
+  sources,
+  reinstallManagedRuntime,
+  conflicts,
+}) {
+  const destination = path.join(target, ...installPath.split("/"));
+  if (!fs.existsSync(destination)) return { type: "copy", installPath, destination, sources };
+  if (managedRuntimeMatches(destination, sources)) return null;
+  if (reinstallManagedRuntime) return { type: "replace", installPath, destination, sources };
+  conflicts.push(path.relative(target, destination));
+  return null;
+}
+
+function applyManagedRuntimePlan(target, plan, backupRoot, actions, dryRun) {
+  if (!plan) return;
+  if (plan.type === "copy") {
+    actions.push(`install ${plan.installPath}`);
+    if (!dryRun) installManagedRuntime(plan.destination, plan.sources);
+    return;
+  }
+  if (backupAndRemove(target, plan.destination, backupRoot, actions, dryRun)) {
+    installManagedRuntime(plan.destination, plan.sources);
+  }
+}
+
+export function initProject(packageRoot, target, options = {}) {
+  const { dryRun = false, force = false, packageVersion = "0.0.0" } = options;
+  validateTarget(target, { create: !dryRun });
+  const backupRoot = path.join(
+    target,
+    ".workflow",
+    "delivery",
+    "runtime",
+    "backups",
+    new Date().toISOString().replaceAll(":", "-"),
+  );
+  const legacyRoot = path.join(target, ".ai-delivery");
+  const legacyActiveTask = path.join(target, LEGACY_ACTIVE_TASK);
+  const hasLegacyRoot = fs.existsSync(legacyRoot);
+  const hasLegacyActiveTask = fs.existsSync(legacyActiveTask);
+  let previousManifest = null;
+  try {
+    previousManifest = JSON.parse(fs.readFileSync(path.join(target, INSTALL_MANIFEST), "utf8"));
+  } catch {
+    previousManifest = null;
+  }
+  const packageVersionComparison = previousManifest?.schema_version >= 5
+    && previousManifest.package === "ai-delivery-workflow"
+    ? comparePackageVersions(packageVersion, previousManifest.version)
+    : 0;
+  if (packageVersionComparison === null && previousManifest.version !== packageVersion && !force) {
+    throw new Error(`Cannot compare installed package version ${previousManifest.version} with ${packageVersion}; use --force only after verifying the intended replacement.`);
+  }
+  if (packageVersionComparison < 0 && !force) {
+    throw new Error(`Refusing package downgrade from ${previousManifest.version} to ${packageVersion}; use --force only after explicit approval.`);
+  }
+  const packageVersionUpgrade = packageVersionComparison > 0;
+  const reinstallManagedRuntime = force || hasLegacyRoot || hasLegacyActiveTask
+    || packageVersionUpgrade || (previousManifest && previousManifest.schema_version < 5);
+  if (!dryRun && hasLegacyRoot) {
+    const legacyBackup = path.join(backupRoot, "legacy-ai-delivery");
+    fs.mkdirSync(path.dirname(legacyBackup), { recursive: true });
+    fs.cpSync(legacyRoot, legacyBackup, { recursive: true });
+  }
+  if (!dryRun && hasLegacyActiveTask) {
+    const taskBackup = path.join(backupRoot, "legacy-active-task.json");
+    fs.mkdirSync(path.dirname(taskBackup), { recursive: true });
+    fs.copyFileSync(legacyActiveTask, taskBackup);
+  }
+  const currentWorkspace = readWorkspaceConfiguration(target, { optional: true });
+  const legacyWorkspaceFile = path.join(target, LEGACY_WORKSPACE_CONFIG);
+  const legacyWorkspace = !currentWorkspace && fs.existsSync(legacyWorkspaceFile)
+    ? readWorkspaceConfiguration(target, { configurationPath: LEGACY_WORKSPACE_CONFIG })
+    : null;
+  const existingWorkspace = (currentWorkspace || legacyWorkspace)?.configuration;
+  const codePath = options.codePath || existingWorkspace?.code_repository?.path || "code";
+  const codeId = options.codeId || existingWorkspace?.code_repository?.repo_id || "app";
+  const sharedRemote = options.sharedRemote || null;
+  const codeRemote = sharedRemote ? null : options.codeRemote || existingWorkspace?.code_repository?.remote || null;
+  const workflowRemote = sharedRemote ? null : options.workflowRemote || existingWorkspace?.workflow_repository?.remote || null;
+  const workspaceId = options.workspaceId || existingWorkspace?.workspace_id || null;
+  const workspace = initializeGitWorkspace(target, {
+    codePath,
+    codeId,
+    codeRemote,
+    workflowRemote,
+    sharedRemote,
+    workspaceId,
+    dryRun,
+  });
+
+  const sourceSkills = path.join(packageRoot, "skills");
+  const sourceTemplate = path.join(sourceSkills, "ai-delivery-orchestrate", "assets", "project-template");
+  const sourceWorkflow = path.join(sourceTemplate, ".workflow");
+  const sourceHook = path.join(sourceSkills, "ai-delivery-checkpoint-task", "scripts", "hook-event.mjs");
+  const sourceConfig = path.join(sourceSkills, "ai-delivery-checkpoint-task", "assets", "codex-hook-config.toml");
+  const sourceViewer = path.join(sourceTemplate, ".workflow", "tools", "viewer");
+  const bootstrapSources = bootstrapRuntimeSources(packageRoot, sourceTemplate);
+  const stateSources = stateRuntimeSources(packageRoot, sourceTemplate);
+  const evolutionSources = evolutionRuntimeSources(packageRoot, sourceTemplate);
+  const sourceStandardsIndex = path.join(sourceWorkflow, "standards", "index.yaml");
+  const workflowRoot = path.join(target, ".workflow");
+  const standardsIndexFile = path.join(workflowRoot, "standards", "index.yaml");
+  const legacyIndicators = [
+    path.join(target, "delivery", "project.yaml"),
+    path.join(target, "delivery", "workflow-state.yaml"),
+    path.join(target, "delivery", "artifact-registry.yaml"),
+    path.join(target, "delivery", "standards-baseline.yaml"),
+    path.join(target, "standards", "index.yaml"),
+  ].filter((candidate) => fs.existsSync(candidate));
+  if (fs.existsSync(workflowRoot) && legacyIndicators.length) {
+    throw new Error(
+      "Detected both .workflow and legacy delivery/standards directories. "
+      + "Resolve the split workflow state before initialization.",
+    );
+  }
+  if (legacyIndicators.length) {
+    throw new Error(
+      "Legacy workflow directories detected at delivery/ or standards/. "
+      + "Move them under .workflow/ before upgrading; refusing to create split workflow state.",
+    );
+  }
+  for (const managedPath of [
+    ".agents", ".codex", ".workflow", ".ai-delivery", "AGENTS.md", ".gitignore", ".gitattributes",
+  ]) {
+    validateManagedPath(target, path.join(target, managedPath));
+  }
+  const skillNames = packagedSkillNames(packageRoot);
+  if (!skillNames.length) throw new Error(`No packaged skills found under ${sourceSkills}`);
+
+  const actions = [];
+  const conflicts = [];
+  const skillPlans = [];
+  for (const name of skillNames) {
+    const source = path.join(sourceSkills, name);
+    const destination = path.join(target, ".agents", "skills", name);
+    if (!fs.existsSync(destination)) skillPlans.push({ type: "copy", name, source, destination });
+    else if (directoryDigest(source) !== directoryDigest(destination)) {
+      if (reinstallManagedRuntime) skillPlans.push({ type: "replace", name, source, destination });
+      else conflicts.push(path.relative(target, destination));
+    }
+  }
+
+  const hookDestination = path.join(target, ".workflow", "tools", "hooks", "hook-event.mjs");
+  const hookConflict = fs.existsSync(hookDestination)
+    && !managedFilesEqual(hookDestination, sourceHook);
+  if (hookConflict && !reinstallManagedRuntime) conflicts.push(path.relative(target, hookDestination));
+  const viewerDestination = path.join(target, ".workflow", "tools", "viewer");
+  let viewerPlan = null;
+  if (!fs.existsSync(viewerDestination)) {
+    viewerPlan = { type: "copy", source: sourceViewer, destination: viewerDestination };
+  } else if (directoryDigest(sourceViewer) !== directoryDigest(viewerDestination)) {
+    if (reinstallManagedRuntime) viewerPlan = { type: "replace", source: sourceViewer, destination: viewerDestination };
+    else conflicts.push(path.relative(target, viewerDestination));
+  }
+  const runtimePlans = [
+    [".workflow/tools/state", stateSources],
+    [".workflow/tools/evolution", evolutionSources],
+    [".workflow/tools/bootstrap", bootstrapSources],
+  ].map(([installPath, sources]) => planManagedRuntime({
+    target,
+    installPath,
+    sources,
+    reinstallManagedRuntime,
+    conflicts,
+  }));
+
+  const packagedStandards = parseYaml(fs.readFileSync(sourceStandardsIndex, "utf8")).standards || [];
+  for (const standard of packagedStandards) {
+    const sourceStandard = path.join(path.dirname(sourceStandardsIndex), standard.path);
+    const targetStandard = path.join(workflowRoot, "standards", standard.path);
+    const normalizedText = (file) => fs.readFileSync(file, "utf8").replaceAll("\r\n", "\n");
+    if (fs.existsSync(targetStandard) && normalizedText(targetStandard) !== normalizedText(sourceStandard)) {
+      throw new Error(`Standard ${standard.id} body conflicts with the packaged approved version; resolve it through standards governance.`);
+    }
+  }
+
+  if (conflicts.length) {
+    throw new Error(`Managed files already exist with different content:\n- ${conflicts.join("\n- ")}\nRerun with --force to back up and replace them.`);
+  }
+
+  const configFile = path.join(target, ".codex", "config.toml");
+  const existingConfig = fs.existsSync(configFile) ? fs.readFileSync(configFile, "utf8") : "";
+  const mergedConfig = existingConfig
+    ? mergeHookConfig(existingConfig, { force })
+    : { text: fs.readFileSync(sourceConfig, "utf8"), actions: ["create project Hook configuration"] };
+  const existingStandardsIndex = fs.existsSync(standardsIndexFile)
+    ? fs.readFileSync(standardsIndexFile, "utf8")
+    : "standards: []\n";
+  const mergedStandardsIndex = mergeStandardsIndex(
+    existingStandardsIndex,
+    fs.readFileSync(sourceStandardsIndex, "utf8"),
+  );
+
+  const agentsTemplate = fs.readFileSync(path.join(sourceTemplate, "AGENTS.md"), "utf8");
+  const agentsFile = path.join(target, "AGENTS.md");
+  const agentsText = mergeManagedMarkdown(fs.existsSync(agentsFile) ? fs.readFileSync(agentsFile, "utf8") : "", agentsTemplate);
+  const gitignoreFile = path.join(target, ".gitignore");
+  const existingGitignore = fs.existsSync(gitignoreFile) ? fs.readFileSync(gitignoreFile, "utf8") : "";
+  if (ignoresWholeWorkflow(existingGitignore)) {
+    throw new Error(
+      "The project .gitignore excludes the complete .workflow directory. "
+      + "Remove that rule and ignore only .workflow/delivery/runtime/.",
+    );
+  }
+  const gitignoreText = mergeGitignore(
+    existingGitignore,
+    [`/${workspace.configuration.code_repository.path}/`],
+  );
+  const gitattributesFile = path.join(target, ".gitattributes");
+  const existingGitattributes = fs.existsSync(gitattributesFile)
+    ? fs.readFileSync(gitattributesFile, "utf8")
+    : "";
+  const gitattributesText = mergeGitattributes(existingGitattributes);
+  if (hasLegacyRoot || hasLegacyActiveTask) {
+    actions.push("migrate legacy .ai-delivery runtime into .workflow");
+    if (!dryRun) {
+      if (hasLegacyActiveTask) {
+        const activeTask = path.join(target, ACTIVE_TASK);
+        if (!fs.existsSync(activeTask)) {
+          fs.mkdirSync(path.dirname(activeTask), { recursive: true });
+          fs.copyFileSync(legacyActiveTask, activeTask);
+        }
+      }
+    }
+  }
+
+  for (const plan of skillPlans) {
+    if (plan.type === "copy") {
+      actions.push(`install .agents/skills/${plan.name}`);
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(plan.destination), { recursive: true });
+        fs.cpSync(plan.source, plan.destination, { recursive: true });
+      }
+    } else {
+      backupAndReplace(target, plan.destination, plan.source, backupRoot, actions, dryRun);
+    }
+  }
+
+  if (!fs.existsSync(hookDestination)) {
+    actions.push("install .workflow/tools/hooks/hook-event.mjs");
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(hookDestination), { recursive: true });
+      fs.copyFileSync(sourceHook, hookDestination);
+    }
+  } else if (hookConflict) {
+    backupAndReplace(target, hookDestination, sourceHook, backupRoot, actions, dryRun);
+  }
+  if (viewerPlan?.type === "copy") {
+    actions.push("install .workflow/tools/viewer");
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(viewerDestination), { recursive: true });
+      fs.cpSync(sourceViewer, viewerDestination, { recursive: true });
+    }
+  } else if (viewerPlan?.type === "replace") {
+    backupAndReplace(target, viewerDestination, sourceViewer, backupRoot, actions, dryRun);
+  }
+  for (const runtimePlan of runtimePlans) {
+    applyManagedRuntimePlan(target, runtimePlan, backupRoot, actions, dryRun);
+  }
+
+  copyMissingTree(path.join(sourceWorkflow, "delivery"), path.join(workflowRoot, "delivery"), actions, dryRun);
+  copyMissingTree(path.join(sourceWorkflow, "standards"), path.join(workflowRoot, "standards"), actions, dryRun);
+  copyMissingTree(path.join(sourceWorkflow, "evolution"), path.join(workflowRoot, "evolution"), actions, dryRun);
+  copyMissingTree(path.join(sourceWorkflow, "extensions"), path.join(workflowRoot, "extensions"), actions, dryRun);
+  for (const directory of ["events", "pending", "staging"]) {
+    const destination = path.join(workflowRoot, "delivery", "runtime", "evolution", directory);
+    if (!fs.existsSync(destination)) {
+      actions.push(`create .workflow/delivery/runtime/evolution/${directory}/`);
+      if (!dryRun) fs.mkdirSync(destination, { recursive: true });
+    }
+  }
+  for (const directory of WORKFLOW_CONTENT_DIRECTORIES) {
+    const destination = path.join(workflowRoot, directory);
+    if (!fs.existsSync(destination)) {
+      actions.push(`create .workflow/${directory}/`);
+      if (!dryRun) fs.mkdirSync(destination, { recursive: true });
+    }
+    const marker = path.join(destination, ".gitkeep");
+    if (!fs.existsSync(marker)) {
+      actions.push(`create .workflow/${directory}/.gitkeep`);
+      if (!dryRun) atomicWrite(marker, "");
+    }
+  }
+  for (const directory of CONTROL_DIRECTORIES) {
+    const destination = path.join(workflowRoot, "control", directory);
+    if (!fs.existsSync(destination)) {
+      actions.push(`create .workflow/control/${directory}/`);
+      if (!dryRun) fs.mkdirSync(destination, { recursive: true });
+    }
+    const marker = path.join(destination, ".gitkeep");
+    if (!fs.existsSync(marker)) {
+      actions.push(`create .workflow/control/${directory}/.gitkeep`);
+      if (!dryRun) atomicWrite(marker, "");
+    }
+  }
+  if (existingStandardsIndex !== mergedStandardsIndex.text) {
+    actions.push(...mergedStandardsIndex.added.map((id) => `register ${id} in .workflow/standards/index.yaml`));
+    if (!dryRun) atomicWrite(standardsIndexFile, mergedStandardsIndex.text);
+  }
+
+  if (!fs.existsSync(agentsFile) || fs.readFileSync(agentsFile, "utf8") !== agentsText) {
+    actions.push("merge AI delivery instructions into AGENTS.md");
+    if (!dryRun) atomicWrite(agentsFile, agentsText);
+  }
+  if (!fs.existsSync(gitignoreFile) || fs.readFileSync(gitignoreFile, "utf8") !== gitignoreText) {
+    actions.push("merge local runtime entries into .gitignore");
+    if (!dryRun) atomicWrite(gitignoreFile, gitignoreText);
+  }
+  if (!fs.existsSync(gitattributesFile)
+    || fs.readFileSync(gitattributesFile, "utf8") !== gitattributesText) {
+    actions.push("merge byte-stable workflow rules into .gitattributes");
+    if (!dryRun) atomicWrite(gitattributesFile, gitattributesText);
+  }
+  if (existingConfig !== mergedConfig.text) {
+    actions.push(...mergedConfig.actions.map((item) => `${item} in .codex/config.toml`));
+    if (!dryRun) atomicWrite(configFile, mergedConfig.text);
+  }
+
+  const workspaceFile = path.join(target, WORKSPACE_CONFIG);
+  const workspaceText = workspaceConfigurationText(workspace.configuration);
+  if (!fs.existsSync(workspaceFile) || fs.readFileSync(workspaceFile, "utf8") !== workspaceText) {
+    actions.push(`write ${WORKSPACE_CONFIG.replaceAll("\\", "/")}`);
+    if (!dryRun) atomicWrite(workspaceFile, workspaceText);
+  }
+
+  const manifestFile = path.join(target, INSTALL_MANIFEST);
+  let existingManifest = null;
+  try {
+    existingManifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  } catch {
+    existingManifest = null;
+  }
+  const manifest = {
+    schema_version: 5,
+    package: "ai-delivery-workflow",
+    version: packageVersion,
+    scope: "workspace",
+    skill_root: ".agents/skills",
+    workflow_root: ".workflow",
+    viewer_root: ".workflow/tools/viewer",
+    bootstrap_cli: ".workflow/tools/bootstrap/bootstrap.mjs",
+    state_cli: ".workflow/tools/state/state.mjs",
+    evolution_cli: ".workflow/tools/evolution/evolve.mjs",
+    hook_protocol_version: 1,
+    hook_cli: ".workflow/tools/hooks/hook-event.mjs",
+    code_repository: workspace.configuration.code_repository,
+    viewer_start: {
+      windows_cmd: ".workflow/tools/viewer/start.cmd",
+      powershell: ".workflow/tools/viewer/start.ps1",
+      unix: ".workflow/tools/viewer/start.sh",
+    },
+    installed_skills: skillNames,
+    managed_assets: {
+      skills: Object.fromEntries(skillNames.map((name) => [
+        name,
+        directoryDigest(path.join(sourceSkills, name)),
+      ])),
+      hook: {
+        path: ".workflow/tools/hooks/hook-event.mjs",
+        sha256: managedFileDigest(sourceHook),
+      },
+      state_runtime: {
+        path: ".workflow/tools/state",
+        sha256: sourceSetDigest(stateSources),
+      },
+      evolution_runtime: {
+        path: ".workflow/tools/evolution",
+        sha256: sourceSetDigest(evolutionSources),
+      },
+      bootstrap_runtime: {
+        path: ".workflow/tools/bootstrap",
+        sha256: sourceSetDigest(bootstrapSources),
+      },
+    },
+    installed_at: existingManifest?.installed_at || new Date().toISOString(),
+  };
+  const manifestText = `${JSON.stringify(manifest, null, 2)}\n`;
+  if (!fs.existsSync(manifestFile) || fs.readFileSync(manifestFile, "utf8") !== manifestText) {
+    actions.push("write .workflow/config/install-manifest.json");
+    if (!dryRun) atomicWrite(manifestFile, manifestText);
+  }
+
+  if (!dryRun && (hasLegacyRoot || hasLegacyActiveTask)) {
+    for (const required of [
+      path.join(target, WORKSPACE_CONFIG),
+      path.join(target, INSTALL_MANIFEST),
+      path.join(target, ".workflow", "tools", "state", "state.mjs"),
+      path.join(target, ".workflow", "tools", "hooks", "hook-event.mjs"),
+    ]) {
+      if (!fs.existsSync(required)) {
+        throw new Error(`Legacy migration is incomplete; preserved .ai-delivery for recovery: ${required}`);
+      }
+    }
+    if (hasLegacyRoot) fs.rmSync(legacyRoot, { recursive: true, force: true });
+    if (hasLegacyActiveTask) fs.rmSync(legacyActiveTask, { force: true });
+  }
+
+  return {
+    actions: [...workspace.actions, ...actions],
+    summary: `${dryRun ? "Dry run" : "Initialized"} ${skillNames.length} workspace-scoped AI delivery skills in ${target}`
+      + (dryRun
+        ? ""
+        : "\nWorkflow viewer: .workflow\\tools\\viewer\\start.cmd (Windows) or sh ./.workflow/tools/viewer/start.sh"),
+  };
+}
+
+export function doctorProject(target, options = {}) {
+  validateTarget(target);
+  for (const managedPath of [".agents", ".codex", ".workflow", "AGENTS.md"]) {
+    validateManagedPath(target, path.join(target, managedPath));
+  }
+  const checks = [];
+  let workspace = null;
+  try {
+    workspace = readWorkspaceConfiguration(target);
+    checks.push({ ok: true, message: "workspace configuration is valid" });
+  } catch (error) {
+    checks.push({ ok: false, message: error.message });
+  }
+  const manifestFile = path.join(target, INSTALL_MANIFEST);
+  let manifest = null;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+    checks.push({
+      ok: manifest.scope === "workspace" && manifest.schema_version === 5,
+      message: "installation manifest uses workspace scope",
+    });
+  } catch (error) {
+    checks.push({ ok: false, message: `installation manifest is missing or invalid: ${error.message}` });
+  }
+
+  const workflowGit = gitTopLevel(target);
+  const codeGit = workspace ? gitTopLevel(workspace.codeRoot) : null;
+  const workflowCommonGit = workflowGit ? gitCommonDirectory(target) : null;
+  const codeCommonGit = codeGit && workspace ? gitCommonDirectory(workspace.codeRoot) : null;
+  checks.push({
+    ok: Boolean(workflowGit) && path.resolve(workflowGit).toLowerCase() === path.resolve(target).toLowerCase(),
+    message: "workflow repository has an independent Git root",
+  });
+  const missingControlDirectories = CONTROL_DIRECTORIES.filter((directory) =>
+    !fs.existsSync(path.join(target, ".workflow", "control", directory)));
+  checks.push({
+    ok: missingControlDirectories.length === 0,
+    message: missingControlDirectories.length
+      ? `shared control shard directories are missing: ${missingControlDirectories.join(", ")}`
+      : "shared task, artifact, Gate, version, and release shard directories are present",
+  });
+  checks.push({
+    ok: Boolean(codeGit)
+      && workspace
+      && path.resolve(codeGit).toLowerCase() === path.resolve(workspace.codeRoot).toLowerCase()
+      && path.resolve(codeGit).toLowerCase() !== path.resolve(workflowGit || target).toLowerCase(),
+    message: "code repository has a distinct nested Git root",
+  });
+  checks.push({
+    ok: Boolean(workflowCommonGit) && Boolean(codeCommonGit)
+      && path.resolve(workflowCommonGit).toLowerCase() !== path.resolve(codeCommonGit).toLowerCase(),
+    message: "workflow and code repositories use independent Git common directories",
+  });
+
+  const packageRoot = options.packageRoot || PACKAGE_ROOT;
+  let expectedSkills = ESSENTIAL_STARTUP_SKILLS;
+  let expectedSkillDigests = {};
+  let expectedHook = null;
+  let expectedBootstrapSources = [];
+  let expectedStateSources = [];
+  let expectedEvolutionSources = [];
+  try {
+    expectedSkills = packagedSkillNames(packageRoot);
+    expectedSkillDigests = Object.fromEntries(expectedSkills.map((name) => [
+      name,
+      directoryDigest(path.join(packageRoot, "skills", name)),
+    ]));
+    expectedHook = path.join(packageRoot, "skills", "ai-delivery-checkpoint-task", "scripts", "hook-event.mjs");
+    const sourceTemplate = path.join(packageRoot, "skills", "ai-delivery-orchestrate", "assets", "project-template");
+    expectedBootstrapSources = bootstrapRuntimeSources(packageRoot, sourceTemplate);
+    expectedStateSources = stateRuntimeSources(packageRoot, sourceTemplate);
+    expectedEvolutionSources = evolutionRuntimeSources(packageRoot, sourceTemplate);
+  } catch (error) {
+    checks.push({ ok: false, message: `packaged managed-asset baseline is unavailable: ${error.message}` });
+  }
+  const manifestSkills = Array.isArray(manifest?.installed_skills) ? [...manifest.installed_skills].sort() : [];
+  checks.push({
+    ok: JSON.stringify(manifestSkills) === JSON.stringify(expectedSkills),
+    message: JSON.stringify(manifestSkills) === JSON.stringify(expectedSkills)
+      ? `installation manifest declares the fixed ${expectedSkills.length}-skill inventory`
+      : `installation manifest skill inventory differs from the fixed ${expectedSkills.length}-skill package inventory`,
+  });
+  const missingSkills = expectedSkills.filter((name) => !fs.existsSync(path.join(target, ".agents", "skills", name, "SKILL.md")));
+  checks.push({
+    ok: expectedSkills.length > 0 && missingSkills.length === 0,
+    message: missingSkills.length ? `missing project skills: ${missingSkills.join(", ")}` : `${expectedSkills.length} project skills are present`,
+  });
+  const damagedSkills = expectedSkills.filter((name) => {
+    const installed = path.join(target, ".agents", "skills", name);
+    return !fs.existsSync(installed) || directoryDigest(installed) !== expectedSkillDigests[name];
+  });
+  const manifestSkillDigests = manifest?.managed_assets?.skills || {};
+  const inconsistentSkillDigests = expectedSkills.filter((name) =>
+    manifestSkillDigests[name] !== expectedSkillDigests[name]);
+  checks.push({
+    ok: damagedSkills.length === 0 && inconsistentSkillDigests.length === 0,
+    message: damagedSkills.length || inconsistentSkillDigests.length
+      ? `managed skill integrity failed: damaged=${damagedSkills.join(", ") || "none"}; manifest=${inconsistentSkillDigests.join(", ") || "none"}`
+      : "managed skill integrity matches the fixed package baseline",
+  });
+  try {
+    const config = inspectHookConfig(fs.readFileSync(path.join(target, ".codex", "config.toml"), "utf8"));
+    checks.push({ ok: config.hooksEnabled, message: "project Codex hooks feature is enabled" });
+    checks.push({ ok: config.registeredEvents.length === 10, message: `${config.registeredEvents.length}/10 delivery Hook events are registered` });
+  } catch (error) {
+    checks.push({ ok: false, message: `project Hook configuration is invalid: ${error.message}` });
+  }
+
+  const installedHook = path.join(target, ".workflow", "tools", "hooks", "hook-event.mjs");
+  const expectedHookDigest = expectedHook && fs.existsSync(expectedHook) ? managedFileDigest(expectedHook) : null;
+  const hookIntegrity = Boolean(expectedHookDigest)
+    && fs.existsSync(installedHook)
+    && managedFileDigest(installedHook) === expectedHookDigest
+    && manifest?.managed_assets?.hook?.sha256 === expectedHookDigest;
+  checks.push({
+    ok: hookIntegrity,
+    message: hookIntegrity ? "project Hook integrity matches the package baseline" : "project Hook integrity check failed",
+  });
+  const viewerFiles = [
+    "server.mjs",
+    "start.cmd",
+    "start.ps1",
+    "start.sh",
+    "public/index.html",
+    "public/app.js",
+    "public/styles.css",
+  ];
+  const missingViewerFiles = viewerFiles.filter((file) =>
+    !fs.existsSync(path.join(target, ".workflow", "tools", "viewer", file)));
+  checks.push({
+    ok: missingViewerFiles.length === 0,
+    required: false,
+    scope: "viewer",
+    message: missingViewerFiles.length
+      ? `workflow viewer is incomplete: ${missingViewerFiles.join(", ")}`
+      : "project workflow viewer and startup scripts are present",
+  });
+  const stateFiles = [
+    "state.mjs",
+    "delivery-state.mjs",
+    "vendor/yaml/package.json",
+    "vendor/yaml/dist/index.js",
+  ];
+  const missingStateFiles = stateFiles.filter((file) =>
+    !fs.existsSync(path.join(target, ".workflow", "tools", "state", file)));
+  checks.push({
+    ok: missingStateFiles.length === 0,
+    message: missingStateFiles.length
+      ? `formal state CLI is incomplete: ${missingStateFiles.join(", ")}`
+      : "project formal state CLI and vendored YAML runtime are present",
+  });
+  const installedStateRoot = path.join(target, ".workflow", "tools", "state");
+  const expectedStateDigest = expectedStateSources.length ? sourceSetDigest(expectedStateSources) : null;
+  const stateIntegrity = Boolean(expectedStateDigest)
+    && fs.existsSync(installedStateRoot)
+    && directoryDigest(installedStateRoot) === expectedStateDigest
+    && manifest?.managed_assets?.state_runtime?.sha256 === expectedStateDigest;
+  checks.push({
+    ok: stateIntegrity,
+    message: stateIntegrity
+      ? "formal state runtime integrity matches the package baseline"
+      : "formal state runtime integrity check failed",
+  });
+  const installedBootstrapRoot = path.join(target, ".workflow", "tools", "bootstrap");
+  const bootstrapFiles = [
+    "bootstrap.mjs",
+    "project-bootstrap.mjs",
+    "workspace.mjs",
+    "yaml-runtime.mjs",
+    "delivery-state.mjs",
+  ];
+  const missingBootstrapFiles = bootstrapFiles.filter((file) =>
+    !fs.existsSync(path.join(installedBootstrapRoot, file)));
+  checks.push({
+    ok: missingBootstrapFiles.length === 0,
+    message: missingBootstrapFiles.length
+      ? `project bootstrap CLI is incomplete: ${missingBootstrapFiles.join(", ")}`
+      : "project bootstrap inspect runtime is present",
+  });
+  const expectedBootstrapDigest = expectedBootstrapSources.length
+    ? sourceSetDigest(expectedBootstrapSources)
+    : null;
+  const bootstrapIntegrity = Boolean(expectedBootstrapDigest)
+    && fs.existsSync(installedBootstrapRoot)
+    && directoryDigest(installedBootstrapRoot) === expectedBootstrapDigest
+    && manifest?.managed_assets?.bootstrap_runtime?.sha256 === expectedBootstrapDigest;
+  checks.push({
+    ok: bootstrapIntegrity,
+    message: bootstrapIntegrity
+      ? "project bootstrap runtime integrity matches the package baseline"
+      : "project bootstrap runtime integrity check failed",
+  });
+  const bootstrapSmoke = spawnSync(
+    process.execPath,
+    [path.join(installedBootstrapRoot, "bootstrap.mjs"), "inspect"],
+    { cwd: target, encoding: "utf8", windowsHide: true },
+  );
+  let bootstrapOutput = null;
+  try { bootstrapOutput = JSON.parse(bootstrapSmoke.stdout); } catch { bootstrapOutput = null; }
+  checks.push({
+    ok: bootstrapSmoke.status === 0 && Boolean(bootstrapOutput?.state),
+    message: bootstrapSmoke.status === 0 && bootstrapOutput?.state
+      ? "project bootstrap inspect smoke check passes"
+      : `project bootstrap inspect smoke check failed: ${(bootstrapSmoke.stderr || bootstrapSmoke.error?.message || "no valid output").trim()}`,
+  });
+  const smokeResults = ["inspect", "verify"].map((command) => {
+    const result = spawnSync(
+      process.execPath,
+      [path.join(installedStateRoot, "state.mjs"), command],
+      { cwd: target, encoding: "utf8", windowsHide: true },
+    );
+    let output = null;
+    try {
+      output = JSON.parse(result.stdout);
+    } catch {
+      output = null;
+    }
+    const validOutput = command === "verify" ? output?.valid === true : output?.command === "inspect";
+    return { ...result, command, validOutput };
+  });
+  const smokeOk = smokeResults.every((result) => result.status === 0 && result.validOutput);
+  checks.push({
+    ok: smokeOk,
+    message: smokeOk
+      ? "formal state CLI inspect/verify smoke checks pass"
+      : `formal state CLI smoke check failed: ${smokeResults.find((result) => result.status !== 0 || !result.validOutput)?.stderr.trim() || "no valid output"}`,
+  });
+  const installedEvolutionRoot = path.join(target, ".workflow", "tools", "evolution");
+  const expectedEvolutionDigest = expectedEvolutionSources.length ? sourceSetDigest(expectedEvolutionSources) : null;
+  const evolutionIntegrity = Boolean(expectedEvolutionDigest)
+    && fs.existsSync(installedEvolutionRoot)
+    && directoryDigest(installedEvolutionRoot) === expectedEvolutionDigest
+    && manifest?.managed_assets?.evolution_runtime?.sha256 === expectedEvolutionDigest;
+  checks.push({
+    ok: evolutionIntegrity,
+    message: evolutionIntegrity
+      ? "workflow evolution runtime integrity matches the package baseline"
+      : "workflow evolution runtime integrity check failed",
+  });
+  const evolutionSmoke = spawnSync(
+    process.execPath,
+    [path.join(installedEvolutionRoot, "evolve.mjs"), "inspect"],
+    { cwd: target, encoding: "utf8", windowsHide: true },
+  );
+  let evolutionOutput = null;
+  try { evolutionOutput = JSON.parse(evolutionSmoke.stdout); } catch { evolutionOutput = null; }
+  checks.push({
+    ok: evolutionSmoke.status === 0 && evolutionOutput?.schema_version === 1,
+    message: evolutionSmoke.status === 0 && evolutionOutput?.schema_version === 1
+      ? "workflow evolution CLI verify smoke check passes"
+      : `workflow evolution CLI smoke check failed: ${evolutionSmoke.stderr.trim() || "no valid output"}`,
+  });
+  const evolutionVerify = spawnSync(
+    process.execPath,
+    [path.join(installedEvolutionRoot, "evolve.mjs"), "verify"],
+    { cwd: target, encoding: "utf8", windowsHide: true },
+  );
+  let evolutionVerifyOutput = null;
+  try { evolutionVerifyOutput = JSON.parse(evolutionVerify.stdout); } catch { evolutionVerifyOutput = null; }
+  checks.push({
+    ok: evolutionVerifyOutput?.ok === true,
+    required: false,
+    scope: "evolution-extensions",
+    message: evolutionVerifyOutput?.ok === false
+      ? `workflow extensions require quarantine or repair: ${(evolutionVerifyOutput.issues || []).map((item) => `${item.extension_id}@${item.version}: ${item.message}`).join("; ")}`
+      : "registered workflow extensions pass checksum and manifest validation",
+  });
+  checks.push({
+    ok: fs.existsSync(path.join(target, ".workflow", "delivery", "project.yaml")),
+    message: "project workflow state uses .workflow/delivery",
+  });
+  checks.push({
+    ok: fs.existsSync(path.join(target, ".workflow", "standards", "index.yaml")),
+    message: "project standards use .workflow/standards",
+  });
+  checks.push({
+    ok: fs.existsSync(path.join(target, ".workflow", "releases")),
+    message: "independent releases use .workflow/releases",
+  });
+  const gitignoreFile = path.join(target, ".gitignore");
+  const gitignore = fs.existsSync(gitignoreFile) ? fs.readFileSync(gitignoreFile, "utf8") : "";
+  checks.push({
+    ok: !ignoresWholeWorkflow(gitignore),
+    message: ignoresWholeWorkflow(gitignore)
+      ? "project .gitignore excludes the complete .workflow directory"
+      : "project .gitignore keeps durable .workflow documents trackable",
+  });
+  const gitattributesFile = path.join(target, ".gitattributes");
+  const gitattributes = fs.existsSync(gitattributesFile)
+    ? fs.readFileSync(gitattributesFile, "utf8")
+    : "";
+  const missingAttributes = GIT_ATTRIBUTE_ENTRIES.filter((entry) =>
+    !gitattributes.split(/\r?\n/).some((line) => line.trim() === entry));
+  const attributeTargets = [...new Set([
+    ".workflow/delivery/workflow-state.yaml",
+    ".agents/skills/ai-delivery-orchestrate/SKILL.md",
+    ".codex/config.toml",
+    "AGENTS.md",
+    ".gitignore",
+    ".gitattributes",
+    ...filesUnder(path.join(target, ".workflow"))
+      .map((file) => path.relative(target, file).replaceAll("\\", "/")),
+    ...filesUnder(path.join(target, ".agents", "skills"))
+      .map((file) => path.relative(target, file).replaceAll("\\", "/"))
+      .filter((file) => file.startsWith(".agents/skills/ai-delivery-")),
+  ])];
+  const attributeValues = new Map();
+  let effectiveAttributesFailed = false;
+  for (let index = 0; index < attributeTargets.length; index += 100) {
+    const batch = attributeTargets.slice(index, index + 100);
+    const effectiveAttributes = spawnSync(
+      "git",
+      ["-c", "core.quotePath=false", "check-attr", "text", "eol", "--", ...batch],
+      { cwd: target, encoding: "utf8", windowsHide: true },
+    );
+    if (effectiveAttributes.status !== 0) {
+      effectiveAttributesFailed = true;
+      break;
+    }
+    for (const line of effectiveAttributes.stdout.split(/\r?\n/).filter(Boolean)) {
+      const match = line.match(/^(.*): (text|eol): (.*)$/);
+      if (match) attributeValues.set(`${match[1]}:${match[2]}`, match[3]);
+    }
+  }
+  const invalidEffectiveAttributes = !effectiveAttributesFailed
+    ? attributeTargets.filter((file) => {
+      const text = attributeValues.get(`${file}:text`);
+      return !new Set(["set", "auto"]).has(text) || attributeValues.get(`${file}:eol`) !== "lf";
+    })
+    : [...attributeTargets];
+  checks.push({
+    ok: missingAttributes.length === 0 && invalidEffectiveAttributes.length === 0,
+    message: missingAttributes.length
+      ? `project .gitattributes is missing byte-stable workflow rules: ${missingAttributes.join(", ")}`
+      : invalidEffectiveAttributes.length
+        ? `project .gitattributes is overridden for checksummed files: ${invalidEffectiveAttributes.join(", ")}`
+        : "project .gitattributes keeps checksummed workflow files at LF",
+  });
+  if (workspace) {
+    const expectedIgnore = `/${workspace.configuration.code_repository.path}/`;
+    checks.push({
+      ok: gitignore.split(/\r?\n/).some((line) => line.trim() === expectedIgnore),
+      message: `workflow repository ignores ${expectedIgnore}`,
+    });
+    const codeRemote = spawnSync("git", ["remote", "get-url", "origin"], {
+      cwd: workspace.codeRoot,
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    const configuredCodeRemote = workspace.configuration.code_repository.remote || null;
+    checks.push({
+      ok: configuredCodeRemote
+        ? codeRemote.status === 0 && codeRemote.stdout.trim() === configuredCodeRemote
+        : true,
+      message: configuredCodeRemote
+        ? "code repository origin matches workspace configuration"
+        : "code repository has no required configured remote",
+    });
+    const workflowRemote = spawnSync("git", ["remote", "get-url", "origin"], {
+      cwd: target,
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    const configuredWorkflowRemote = workspace.configuration.workflow_repository.remote || null;
+    checks.push({
+      ok: configuredWorkflowRemote
+        ? workflowRemote.status === 0 && workflowRemote.stdout.trim() === configuredWorkflowRemote
+        : true,
+      message: configuredWorkflowRemote
+        ? "workflow repository origin matches workspace configuration"
+        : "workflow repository has no required configured remote",
+    });
+    const workflowBranch = spawnSync("git", ["branch", "--show-current"], {
+      cwd: target, encoding: "utf8", windowsHide: true,
+    }).stdout.trim();
+    checks.push({
+      ok: workflowBranch === workspace.configuration.workflow_repository.branch,
+      message: `workflow repository uses ${workspace.configuration.workflow_repository.branch}`,
+    });
+    checks.push({
+      ok: workspace.configuration.repository_layout === "independent-git-roots"
+        && workspace.configuration.code_repository?.default_branch === "main",
+      message: "workspace declares independent Git roots and code main",
+    });
+  }
+  checks.push({
+    ok: !fs.existsSync(path.join(target, ".ai-delivery")) && !fs.existsSync(path.join(target, LEGACY_ACTIVE_TASK)),
+    message: "legacy .ai-delivery paths are absent",
+  });
+  checks.push({ ok: fs.existsSync(path.join(target, "AGENTS.md")), message: "project AGENTS.md is present" });
+  return { checks, ok: checks.filter((check) => check.required !== false).every((check) => check.ok) };
+}