ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/project-installer.mjs

@@ -5,8 +5,12 @@ 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 { isSeq, parse as parseYaml, parseDocument, stringify as stringifyYaml } from "yaml";
+import { assertPathInside, atomicWrite, filesUnder } from "./fs-utils.mjs";
+import { inspectCodeGraph } from "./codegraph.mjs";
+import { executeDeliveryStateCommand } from "./delivery-state.mjs";
+import { planPrototypeMigration } from "./prototype-migration.mjs";
+import { inspectHookConfig, managedHookConfigProjection, mergeHookConfig } from "./toml-hooks.mjs";
 import {
   LEGACY_WORKSPACE_CONFIG,
   WORKSPACE_CONFIG,
@@ -22,6 +26,10 @@ 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 RAW_GIT_ATTRIBUTE_TARGETS = Object.freeze([
+  "ref/ui/README.md",
+  "ref/ui/LICENSE",
+]);
 const GIT_ATTRIBUTE_ENTRIES = [
   "/.workflow/** text=auto eol=lf",
   "/.agents/skills/ai-delivery-*/** text=auto eol=lf",
@@ -29,13 +37,43 @@ const GIT_ATTRIBUTE_ENTRIES = [
   "/AGENTS.md text eol=lf",
   "/.gitignore text eol=lf",
   "/.gitattributes text eol=lf",
+  ...RAW_GIT_ATTRIBUTE_TARGETS.map((file) => `/${file} -text`),
 ];
 const OBSOLETE_IGNORE_ENTRIES = new Set([".ai-delivery-task", ".ai-delivery/backups/"]);
 const INSTALL_MANIFEST = path.join(".workflow", "config", "install-manifest.json");
+const UPGRADE_RUNTIME = path.join(".workflow", "delivery", "runtime", "upgrades");
+const PRESERVED_DETAIL_LIMIT = 200;
+const PRESERVED_TRANSIENT_ROOTS = Object.freeze([".workflow/delivery/runtime"]);
+const DOCTOR_ATTRIBUTE_BATCH_SIZE = 5_000;
+const DOCTOR_DETAIL_LIMIT = 200;
+const FORMAL_STATE_INSPECT_MAX_BUFFER = 16 * 1024 * 1024;
+const INSTALL_MANIFEST_SCHEMA = 6;
+const UI_CONTRACT_VERSION = "prototype-first-ui-v1";
+const FORMAL_STATE_YAML = {
+  parse: parseYaml,
+  stringify: (value) => stringifyYaml(value, { lineWidth: 0 }),
+};
+const MERGED_MANAGED_SURFACES = Object.freeze([
+  { key: "agents", path: "AGENTS.md" },
+  { key: "hook_config", path: ".codex/config.toml" },
+  { key: "gitignore", path: ".gitignore" },
+  { key: "gitattributes", path: ".gitattributes" },
+]);
 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 CONTROL_DIRECTORIES = [
+  "tasks", "checkpoints", "artifacts", "gates", "versions", "releases", "events", "archives",
+  "migrations", "repairs",
+];
+const ENSURED_CONTROL_DIRECTORIES = ["migrations", "repairs"];
+const RETIRED_MANAGED_ASSETS = Object.freeze([
+  {
+    path: ".workflow/tools/viewer",
+    kind: "retired-directory",
+    manifest_key: "viewer",
+  },
+]);
 const ESSENTIAL_STARTUP_SKILLS = [
   "ai-delivery-assemble-release",
   "ai-delivery-bootstrap",
@@ -45,6 +83,79 @@ const ESSENTIAL_STARTUP_SKILLS = [
   "ai-delivery-orchestrate",
   "ai-delivery-orchestrate-release",
 ];
+const WORKFLOW_MANAGER_LAUNCHER_FILES = Object.freeze([
+  "manager.mjs",
+  "start.cmd",
+  "start.ps1",
+  "start.sh",
+]);
+const WORKFLOW_MANAGER_RUNTIME_MODULES = Object.freeze([
+  "workflow-manager-facts.mjs",
+  "workflow-manager-contracts.mjs",
+  "workflow-manager-transaction.mjs",
+  "workflow-manager-systems.mjs",
+  "workflow-manager-mock.mjs",
+  "workflow-manager-prototypes.mjs",
+  "workflow-manager-governance.mjs",
+]);
+const PROTOTYPE_EVIDENCE_RUNTIME_MODULES = Object.freeze([
+  "prototype-review-target.mjs",
+  "prototype-page-review.mjs",
+  "prototype-revision.mjs",
+  "visual-standard.mjs",
+  "artifact-files.mjs",
+  "yaml-runtime.mjs",
+]);
+const V2_PROTOTYPE_CATALOG_TEMPLATE_FILES = Object.freeze([
+  "prototype-terminals.csv",
+  "prototype-pages.csv",
+  "prototype-review-scenes.csv",
+  "prototype-trigger-conditions.csv",
+  "prototype-routes.csv",
+  "ui-mapping.csv",
+  "prototype-review-units.csv",
+  "prototype-review-unit-pages.csv",
+  "prototype-components.csv",
+  "prototype-data-contracts.csv",
+  "prototype-component-candidates.csv",
+  "prototype-component-bindings.csv",
+  "prototype-implementation-bindings.csv",
+  "prototype-source-inspection-snapshots.csv",
+]);
+const EXPERIENCE_TEMPLATE_ROOT = "skills/ai-delivery-design-experience/assets/experience-template";
+const V2_PROTOTYPE_DELIVERY_SURFACE_FILES = Object.freeze([
+  "docs/agents/workflow-manager-agent-interface.md",
+  "lib/workflow-manager.mjs",
+  "lib/workflow-manager-public/index.html",
+  "skills/ai-delivery-design-experience/SKILL.md",
+  ...[...WORKFLOW_MANAGER_RUNTIME_MODULES, ...PROTOTYPE_EVIDENCE_RUNTIME_MODULES]
+    .map((name) => `lib/${name}`),
+  ...WORKFLOW_MANAGER_LAUNCHER_FILES
+    .map((name) => `skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/manager/${name}`),
+  ...["prototype.yaml", "prototype-revision.yaml", "frontend-change-scope.yaml", ...V2_PROTOTYPE_CATALOG_TEMPLATE_FILES]
+    .map((name) => `${EXPERIENCE_TEMPLATE_ROOT}/${name}`),
+]);
+const REQUIRED_PACKAGE_SURFACE_FILES = Object.freeze([
+  "LICENSE",
+  "bin/ai-delivery.mjs",
+  "docs/PROTOTYPE-MIGRATION.zh-CN.md",
+  "lib/mock-scenario-pack.mjs",
+  "lib/mock-system.mjs",
+  "lib/project-migration.mjs",
+  "lib/prototype-migration.mjs",
+  "lib/prototype-page-review.mjs",
+  "lib/prototype-review-target.mjs",
+  "skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs",
+  "skills/ai-delivery-orchestrate/SKILL.md",
+  "skills/ai-delivery-orchestrate/assets/project-template/AGENTS.md",
+  "skills/ai-delivery-orchestrate/assets/project-template/gitignore.template",
+  "skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/mock/mock.mjs",
+  "skills/ai-delivery-orchestrate/assets/project-template/ref/ui/README.md",
+  "skills/ai-delivery-orchestrate/assets/project-template/ref/ui/LICENSE",
+  "skills/ai-delivery-orchestrate/assets/project-template/ref/ui/UPSTREAM.yaml",
+  "skills/ai-delivery-orchestrate/assets/project-template/ref/ui/design-md/linear.app/DESIGN.md",
+  ...V2_PROTOTYPE_DELIVERY_SURFACE_FILES,
+]);
 const DELIVERY_SKILLS = Object.freeze([
   "ai-delivery-assemble-release",
   "ai-delivery-bootstrap",
@@ -132,40 +243,13 @@ function validateTarget(target, options = {}) {
 }
 
 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}`);
+  try {
+    assertPathInside(target, destination);
+  } catch (error) {
+    throw new Error(`Managed path resolves outside the project: ${error.message}`);
   }
 }
 
-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"));
@@ -178,7 +262,8 @@ function managedFilesEqual(left, right) {
 function directoryDigest(root) {
   const hash = crypto.createHash("sha256");
   for (const file of filesUnder(root)) {
-    hash.update(path.relative(root, file).replaceAll("\\", "/"));
+    const relative = path.relative(root, file).replaceAll("\\", "/");
+    hash.update(relative);
     hash.update("\0");
     hash.update(normalizedManagedContent(file));
     hash.update("\0");
@@ -190,6 +275,39 @@ function managedFileDigest(file) {
   return crypto.createHash("sha256").update(normalizedManagedContent(file)).digest("hex");
 }
 
+function contentDigest(content) {
+  const value = Buffer.isBuffer(content) ? content : Buffer.from(String(content).replaceAll("\r\n", "\n"));
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function pathDigest(target) {
+  if (!fs.existsSync(target)) return null;
+  if (fs.statSync(target).isDirectory()) return directoryDigest(target);
+  if (fs.statSync(target).isFile()) return managedFileDigest(target);
+  throw new Error(`Managed asset is not a regular file or directory: ${target}`);
+}
+
+function exactTreeDigest(root) {
+  if (!fs.existsSync(root)) return null;
+  const hash = crypto.createHash("sha256");
+  for (const file of filesUnder(root)) {
+    hash.update(path.relative(root, file).replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function exactPathDigest(target) {
+  if (!fs.existsSync(target)) return null;
+  if (fs.statSync(target).isDirectory()) return exactTreeDigest(target);
+  if (fs.statSync(target).isFile()) {
+    return crypto.createHash("sha256").update(fs.readFileSync(target)).digest("hex");
+  }
+  throw new Error(`Managed asset is not a regular file or directory: ${target}`);
+}
+
 function sourceSetDigest(sources) {
   const hash = crypto.createHash("sha256");
   for (const item of [...sources].sort((left, right) => left.relative.localeCompare(right.relative))) {
@@ -324,6 +442,14 @@ function stateRuntimeSources(packageRoot, sourceTemplate) {
       source: path.join(packageRoot, "lib", "delivery-state.mjs"),
       relative: "delivery-state.mjs",
     },
+    {
+      source: path.join(packageRoot, "lib", "history-anchor.mjs"),
+      relative: "history-anchor.mjs",
+    },
+    {
+      source: path.join(packageRoot, "lib", "fs-utils.mjs"),
+      relative: "fs-utils.mjs",
+    },
     ...filesUnder(yamlRoot).map((source) => ({
       source,
       relative: path.join("vendor", "yaml", path.relative(yamlRoot, source)),
@@ -344,19 +470,341 @@ function evolutionRuntimeSources(packageRoot, sourceTemplate) {
   ];
 }
 
+function mockRuntimeSources(packageRoot, sourceTemplate) {
+  return [
+    {
+      source: path.join(sourceTemplate, ".workflow", "tools", "mock", "mock.mjs"),
+      relative: "mock.mjs",
+    },
+    ...[
+      "mock-system.mjs",
+      "mock-scenario-pack.mjs",
+      "prototype-revision.mjs",
+      "artifact-files.mjs",
+      "workspace.mjs",
+      "yaml-runtime.mjs",
+      "fs-utils.mjs",
+      "stable-value.mjs",
+    ].map((name) => ({
+      source: path.join(packageRoot, "lib", name),
+      relative: name,
+    })),
+  ];
+}
+
+function packagedRuntimeModules(packageRoot, modules) {
+  return modules.map((name) => ({
+    source: path.join(packageRoot, "lib", name),
+    relative: name,
+  }));
+}
+
+function frontendGuardRuntimeSources(packageRoot, sourceTemplate) {
+  return [
+    {
+      source: path.join(sourceTemplate, ".workflow", "tools", "frontend-guard", "frontend-guard.mjs"),
+      relative: "frontend-guard.mjs",
+    },
+    {
+      source: path.join(packageRoot, "lib", "frontend-guard.mjs"),
+      relative: "frontend-guard-runtime.mjs",
+    },
+    ...packagedRuntimeModules(packageRoot, PROTOTYPE_EVIDENCE_RUNTIME_MODULES),
+  ];
+}
+
+function uiAcceptanceRuntimeSources(packageRoot, sourceTemplate) {
+  return [
+    {
+      source: path.join(sourceTemplate, ".workflow", "tools", "ui-acceptance", "ui-acceptance.mjs"),
+      relative: "ui-acceptance.mjs",
+    },
+    {
+      source: path.join(packageRoot, "lib", "ui-acceptance.mjs"),
+      relative: "ui-acceptance-runtime.mjs",
+    },
+    ...packagedRuntimeModules(packageRoot, [
+      ...PROTOTYPE_EVIDENCE_RUNTIME_MODULES,
+      "mock-scenario-pack.mjs",
+      "mock-system.mjs",
+      "png-evidence.mjs",
+      "fs-utils.mjs",
+      "workspace.mjs",
+      "stable-value.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) => ({
+    ...[
+      "project-bootstrap.mjs", "workspace.mjs", "yaml-runtime.mjs", "delivery-state.mjs",
+      "history-anchor.mjs", "fs-utils.mjs",
+    ].map((name) => ({
+      source: path.join(packageRoot, "lib", name),
+      relative: name,
+    })),
+  ];
+}
+
+function managerRuntimeSources(packageRoot, sourceTemplate) {
+  const publicRoot = path.join(packageRoot, "lib", "workflow-manager-public");
+  return [
+    {
+      source: path.join(sourceTemplate, ".workflow", "tools", "manager", "manager.mjs"),
+      relative: "manager.mjs",
+    },
+    {
+      source: path.join(packageRoot, "docs", "agents", "workflow-manager-agent-interface.md"),
+      relative: "AGENT-INTERFACE.md",
+    },
+    ...WORKFLOW_MANAGER_LAUNCHER_FILES.filter((name) => name !== "manager.mjs").map((name) => ({
+      source: path.join(sourceTemplate, ".workflow", "tools", "manager", name),
+      relative: name,
+    })),
+    {
+      source: path.join(packageRoot, "lib", "workflow-manager.mjs"),
+      relative: "workflow-manager-runtime.mjs",
+    },
+    ...WORKFLOW_MANAGER_RUNTIME_MODULES.map((name) => ({
       source: path.join(packageRoot, "lib", name),
       relative: name,
     })),
+    ...packagedRuntimeModules(packageRoot, PROTOTYPE_EVIDENCE_RUNTIME_MODULES),
+    ...filesUnder(publicRoot).map((source) => ({
+      source,
+      relative: path.join("public", path.relative(publicRoot, source)),
+    })),
   ];
 }
 
+function installationSources(packageRoot) {
+  const sourceSkills = path.join(packageRoot, "skills");
+  const sourceTemplate = path.join(sourceSkills, "ai-delivery-orchestrate", "assets", "project-template");
+  const sourceWorkflow = path.join(sourceTemplate, ".workflow");
+  const sourceDesignReferenceLibrary = path.join(sourceTemplate, "ref", "ui");
+  const gitignoreTemplate = path.join(sourceTemplate, "gitignore.template");
+  if (!fs.existsSync(gitignoreTemplate) || !fs.statSync(gitignoreTemplate).isFile()) {
+    throw new Error("Project template is missing gitignore.template.");
+  }
+  const expectedGitignoreTemplate = `${IGNORE_ENTRIES.join("\n")}\n`;
+  if (fs.readFileSync(gitignoreTemplate, "utf8").replaceAll("\r\n", "\n")
+    !== expectedGitignoreTemplate) {
+    throw new Error("Project gitignore.template does not match the managed runtime ignore contract.");
+  }
+  validateDesignReferenceLibrary(sourceDesignReferenceLibrary);
+  const skillNames = packagedSkillNames(packageRoot);
+  return {
+    sourceSkills,
+    sourceTemplate,
+    sourceWorkflow,
+    skillNames,
+    sourceHook: path.join(sourceSkills, "ai-delivery-checkpoint-task", "scripts", "hook-event.mjs"),
+    sourceHookConfig: path.join(sourceSkills, "ai-delivery-checkpoint-task", "assets", "codex-hook-config.toml"),
+    sourceDesignReferenceLibrary,
+    bootstrapSources: bootstrapRuntimeSources(packageRoot, sourceTemplate),
+    stateSources: stateRuntimeSources(packageRoot, sourceTemplate),
+    evolutionSources: evolutionRuntimeSources(packageRoot, sourceTemplate),
+    mockSources: mockRuntimeSources(packageRoot, sourceTemplate),
+    frontendGuardSources: frontendGuardRuntimeSources(packageRoot, sourceTemplate),
+    uiAcceptanceSources: uiAcceptanceRuntimeSources(packageRoot, sourceTemplate),
+    managerSources: managerRuntimeSources(packageRoot, sourceTemplate),
+  };
+}
+
+function validateDesignReferenceLibrary(source) {
+  for (const relative of ["README.md", "LICENSE", "UPSTREAM.yaml"]) {
+    if (!fs.existsSync(path.join(source, relative))) {
+      throw new Error(`Design Reference Library is missing required ${relative}.`);
+    }
+  }
+  const upstream = parseYaml(fs.readFileSync(path.join(source, "UPSTREAM.yaml"), "utf8"));
+  if (!/^[a-f0-9]{40}$/.test(String(upstream?.source_commit || ""))) {
+    throw new Error("Design Reference Library UPSTREAM.yaml must pin a full source commit.");
+  }
+  if (upstream?.license !== "MIT" || upstream?.license_ref !== "LICENSE") {
+    throw new Error("Design Reference Library must declare its MIT license and LICENSE path.");
+  }
+  if (!/^MIT License\b/.test(fs.readFileSync(path.join(source, "LICENSE"), "utf8"))) {
+    throw new Error("Design Reference Library LICENSE content is missing or invalid.");
+  }
+  for (const [relative, checksumField] of [
+    ["README.md", "source_readme_sha256"],
+    ["LICENSE", "license_sha256"],
+  ]) {
+    const expected = String(upstream?.[checksumField] || "");
+    const actual = crypto.createHash("sha256").update(fs.readFileSync(path.join(source, relative))).digest("hex");
+    if (!/^[a-f0-9]{64}$/.test(expected) || actual !== expected) {
+      throw new Error(`Design Reference Library ${relative} checksum does not match UPSTREAM.yaml.`);
+    }
+  }
+  const references = filesUnder(path.join(source, "design-md"))
+    .filter((file) => path.basename(file) === "DESIGN.md");
+  if (references.length < 2) {
+    throw new Error("Design Reference Library must contain selectable DESIGN.md references.");
+  }
+}
+
+function designReferenceDoctorCheck(target, packageSource, manifest) {
+  const installed = path.join(target, "ref", "ui");
+  try {
+    validateDesignReferenceLibrary(packageSource);
+    validateDesignReferenceLibrary(installed);
+    const expectedDigest = directoryDigest(packageSource);
+    const installedDigest = directoryDigest(installed);
+    const manifestDigest = manifest?.managed_assets?.design_reference_library?.sha256;
+    const ok = installedDigest === expectedDigest && manifestDigest === expectedDigest;
+    return {
+      ok,
+      scope: "design-reference-library",
+      message: ok
+        ? "Design Reference Library integrity and raw attribution checksums match the package baseline"
+        : "Design Reference Library integrity does not match the package baseline",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      scope: "design-reference-library",
+      message: `Design Reference Library integrity check failed: ${error.message}`,
+    };
+  }
+}
+
+function packageSurfaceDoctorCheck(packageRoot) {
+  const missing = [];
+  const empty = [];
+  for (const relative of REQUIRED_PACKAGE_SURFACE_FILES) {
+    const file = path.join(packageRoot, ...relative.split("/"));
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) missing.push(relative);
+    else if (fs.statSync(file).size === 0) empty.push(relative);
+  }
+  const ok = missing.length === 0 && empty.length === 0;
+  return {
+    ok,
+    scope: "package-surface",
+    message: ok
+      ? `release package surface contains all ${REQUIRED_PACKAGE_SURFACE_FILES.length} required files`
+      : `release package surface is incomplete: missing=${missing.join(", ") || "none"}; empty=${empty.join(", ") || "none"}`,
+  };
+}
+
+function managedMarkdownContribution(text) {
+  const start = text.indexOf(MANAGED_START);
+  const end = text.indexOf(MANAGED_END);
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error("AGENTS.md does not contain a complete ai-delivery managed block.");
+  }
+  return text.slice(start, end + MANAGED_END.length);
+}
+
+function mergedSurfaceManagedDigest(key, text, codePath) {
+  if (key === "agents") return contentDigest(managedMarkdownContribution(text));
+  if (key === "hook_config") return contentDigest(JSON.stringify(managedHookConfigProjection(text)));
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (key === "gitignore") {
+    const managedEntries = new Set([...IGNORE_ENTRIES, `/${codePath}/`, ...OBSOLETE_IGNORE_ENTRIES]);
+    return contentDigest(JSON.stringify(lines.filter((line) => managedEntries.has(line)).sort()));
+  }
+  return contentDigest(JSON.stringify(lines.filter((line) => GIT_ATTRIBUTE_ENTRIES.includes(line)).sort()));
+}
+
+function expectedMergedSurfaceText(surface, sources, codePath) {
+  if (surface.key === "agents") {
+    const template = fs.readFileSync(path.join(sources.sourceTemplate, "AGENTS.md"), "utf8");
+    return mergeManagedMarkdown("", template);
+  }
+  if (surface.key === "hook_config") return fs.readFileSync(sources.sourceHookConfig, "utf8");
+  if (surface.key === "gitignore") return mergeGitignore("", [`/${codePath}/`]);
+  return mergeGitattributes("");
+}
+
+function buildInstallManifest(sources, packageVersion, codeRepository, previousManifest = null) {
+  const inventory = managedAssetInventory(sources, previousManifest);
+  const named = Object.fromEntries(
+    inventory.filter((asset) => asset.manifest_key).map((asset) => [asset.manifest_key, asset]),
+  );
+  return {
+    schema_version: INSTALL_MANIFEST_SCHEMA,
+    package: "ai-delivery-workflow",
+    version: packageVersion,
+    scope: "workspace",
+    skill_root: ".agents/skills",
+    workflow_root: ".workflow",
+    bootstrap_cli: ".workflow/tools/bootstrap/bootstrap.mjs",
+    state_cli: ".workflow/tools/state/state.mjs",
+    evolution_cli: ".workflow/tools/evolution/evolve.mjs",
+    mock_cli: ".workflow/tools/mock/mock.mjs",
+    frontend_guard_cli: ".workflow/tools/frontend-guard/frontend-guard.mjs",
+    ui_acceptance_cli: ".workflow/tools/ui-acceptance/ui-acceptance.mjs",
+    manager_root: ".workflow/tools/manager",
+    manager_cli: ".workflow/tools/manager/manager.mjs",
+    hook_protocol_version: 1,
+    hook_cli: ".workflow/tools/hooks/hook-event.mjs",
+    code_repository: codeRepository,
+    manager_start: {
+      windows_cmd: ".workflow/tools/manager/start.cmd",
+      powershell: ".workflow/tools/manager/start.ps1",
+      unix: ".workflow/tools/manager/start.sh",
+    },
+    installed_skills: sources.skillNames,
+    managed_assets: {
+      skills: Object.fromEntries(inventory
+        .filter((asset) => asset.skill_name)
+        .map((asset) => [asset.skill_name, asset.expected_digest])),
+      hook: {
+        path: named.hook.path,
+        sha256: named.hook.expected_digest,
+      },
+      state_runtime: {
+        path: named.state_runtime.path,
+        sha256: named.state_runtime.expected_digest,
+      },
+      evolution_runtime: {
+        path: named.evolution_runtime.path,
+        sha256: named.evolution_runtime.expected_digest,
+      },
+      mock_runtime: {
+        path: named.mock_runtime.path,
+        sha256: named.mock_runtime.expected_digest,
+      },
+      frontend_guard_runtime: {
+        path: named.frontend_guard_runtime.path,
+        sha256: named.frontend_guard_runtime.expected_digest,
+      },
+      ui_acceptance_runtime: {
+        path: named.ui_acceptance_runtime.path,
+        sha256: named.ui_acceptance_runtime.expected_digest,
+      },
+      manager_runtime: {
+        path: named.manager_runtime.path,
+        sha256: named.manager_runtime.expected_digest,
+      },
+      bootstrap_runtime: {
+        path: named.bootstrap_runtime.path,
+        sha256: named.bootstrap_runtime.expected_digest,
+      },
+      design_reference_library: {
+        path: named.design_reference_library.path,
+        sha256: named.design_reference_library.expected_digest,
+      },
+      merged_surfaces: Object.fromEntries(
+        MERGED_MANAGED_SURFACES.map((surface) => {
+          const expected = expectedMergedSurfaceText(surface, sources, codeRepository.path);
+          return [surface.key, {
+            path: surface.path,
+            sha256: mergedSurfaceManagedDigest(surface.key, expected, codeRepository.path),
+          }];
+        }),
+      ),
+    },
+    installed_at: previousManifest?.installed_at || new Date().toISOString(),
+  };
+}
+
 function managedRuntimeMatches(destination, sources) {
   if (!fs.existsSync(destination)) return false;
   const expected = new Map(sources.map((item) => [
@@ -410,6 +858,7 @@ function applyManagedRuntimePlan(target, plan, backupRoot, actions, dryRun) {
 
 export function initProject(packageRoot, target, options = {}) {
   const { dryRun = false, force = false, packageVersion = "0.0.0" } = options;
+  const sources = installationSources(packageRoot);
   validateTarget(target, { create: !dryRun });
   const backupRoot = path.join(
     target,
@@ -474,15 +923,22 @@ export function initProject(packageRoot, target, options = {}) {
     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 {
+    sourceSkills,
+    sourceTemplate,
+    sourceWorkflow,
+    sourceHook,
+    sourceHookConfig: sourceConfig,
+    sourceDesignReferenceLibrary,
+    bootstrapSources,
+    stateSources,
+    evolutionSources,
+    mockSources,
+    frontendGuardSources,
+    uiAcceptanceSources,
+    managerSources,
+    skillNames,
+  } = sources;
   const sourceStandardsIndex = path.join(sourceWorkflow, "standards", "index.yaml");
   const workflowRoot = path.join(target, ".workflow");
   const standardsIndexFile = path.join(workflowRoot, "standards", "index.yaml");
@@ -510,7 +966,7 @@ export function initProject(packageRoot, target, options = {}) {
   ]) {
     validateManagedPath(target, path.join(target, managedPath));
   }
-  const skillNames = packagedSkillNames(packageRoot);
+  validateManagedPath(target, path.join(target, "ref", "ui"));
   if (!skillNames.length) throw new Error(`No packaged skills found under ${sourceSkills}`);
 
   const actions = [];
@@ -530,18 +986,29 @@ export function initProject(packageRoot, target, options = {}) {
   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 retiredViewerDestination = path.join(target, ".workflow", "tools", "viewer");
+  const retireLegacyViewer = hasLegacyRoot && fs.existsSync(retiredViewerDestination);
+  const designReferenceDestination = path.join(target, "ref", "ui");
+  let designReferencePlan = null;
+  if (!fs.existsSync(designReferenceDestination)) {
+    designReferencePlan = {
+      type: "copy", source: sourceDesignReferenceLibrary, destination: designReferenceDestination,
+    };
+  } else if (directoryDigest(sourceDesignReferenceLibrary) !== directoryDigest(designReferenceDestination)) {
+    if (reinstallManagedRuntime) {
+      designReferencePlan = {
+        type: "replace", source: sourceDesignReferenceLibrary, destination: designReferenceDestination,
+      };
+    } else conflicts.push(path.relative(target, designReferenceDestination));
   }
   const runtimePlans = [
     [".workflow/tools/state", stateSources],
     [".workflow/tools/evolution", evolutionSources],
     [".workflow/tools/bootstrap", bootstrapSources],
+    [".workflow/tools/mock", mockSources],
+    [".workflow/tools/frontend-guard", frontendGuardSources],
+    [".workflow/tools/ui-acceptance", uiAcceptanceSources],
+    [".workflow/tools/manager", managerSources],
   ].map(([installPath, sources]) => planManagedRuntime({
     target,
     installPath,
@@ -631,14 +1098,19 @@ export function initProject(packageRoot, target, options = {}) {
   } else if (hookConflict) {
     backupAndReplace(target, hookDestination, sourceHook, backupRoot, actions, dryRun);
   }
-  if (viewerPlan?.type === "copy") {
-    actions.push("install .workflow/tools/viewer");
+  if (retireLegacyViewer) {
+    backupAndRemove(target, retiredViewerDestination, backupRoot, actions, dryRun);
+  }
+  if (designReferencePlan?.type === "copy") {
+    actions.push("install ref/ui Design Reference Library");
     if (!dryRun) {
-      fs.mkdirSync(path.dirname(viewerDestination), { recursive: true });
-      fs.cpSync(sourceViewer, viewerDestination, { recursive: true });
+      fs.mkdirSync(path.dirname(designReferenceDestination), { recursive: true });
+      fs.cpSync(sourceDesignReferenceLibrary, designReferenceDestination, { recursive: true });
     }
-  } else if (viewerPlan?.type === "replace") {
-    backupAndReplace(target, viewerDestination, sourceViewer, backupRoot, actions, dryRun);
+  } else if (designReferencePlan?.type === "replace") {
+    backupAndReplace(
+      target, designReferenceDestination, sourceDesignReferenceLibrary, backupRoot, actions, dryRun,
+    );
   }
   for (const runtimePlan of runtimePlans) {
     applyManagedRuntimePlan(target, runtimePlan, backupRoot, actions, dryRun);
@@ -716,50 +1188,12 @@ export function initProject(packageRoot, target, options = {}) {
   } 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 manifest = buildInstallManifest(
+    sources,
+    packageVersion,
+    workspace.configuration.code_repository,
+    existingManifest,
+  );
   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");
@@ -783,11 +1217,827 @@ export function initProject(packageRoot, target, options = {}) {
 
   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"),
+    summary: `${dryRun ? "Dry run" : "Initialized"} ${skillNames.length} workspace-scoped AI delivery skills in ${target}`,
+  };
+}
+
+function readInstallManifest(target) {
+  const manifestFile = path.join(target, INSTALL_MANIFEST);
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read installed workflow manifest: ${error.message}`);
+  }
+  if (manifest.package !== "ai-delivery-workflow" || manifest.scope !== "workspace") {
+    throw new Error("The installation manifest is not a compatible project-scoped ai-delivery-workflow installation.");
+  }
+  return { manifest, manifestFile };
+}
+
+function installPath(target, relative) {
+  return path.join(target, ...relative.split("/"));
+}
+
+function managedAssetInventory(sources, previousManifest = {}) {
+  const previous = previousManifest || {};
+  const assets = sources.skillNames.map((name) => ({
+    path: `.agents/skills/${name}`,
+    kind: "directory",
+    skill_name: name,
+    source: path.join(sources.sourceSkills, name),
+    expected_digest: directoryDigest(path.join(sources.sourceSkills, name)),
+    previous_digest: previous.managed_assets?.skills?.[name] || null,
+  }));
+  assets.push(
+    ...ENSURED_CONTROL_DIRECTORIES.map((directory) => ({
+      path: `.workflow/control/${directory}`,
+      kind: "ensure-directory",
+      source: path.join(sources.sourceTemplate, ".workflow", "control", directory),
+      expected_digest: directoryDigest(
+        path.join(sources.sourceTemplate, ".workflow", "control", directory),
+      ),
+      previous_digest: null,
+    })),
+    ...ENSURED_CONTROL_DIRECTORIES.map((directory) => ({
+      path: `.workflow/control/${directory}/.gitkeep`,
+      kind: "ensure-directory-marker",
+      source: path.join(sources.sourceTemplate, ".workflow", "control", directory, ".gitkeep"),
+      expected_digest: managedFileDigest(
+        path.join(sources.sourceTemplate, ".workflow", "control", directory, ".gitkeep"),
+      ),
+      previous_digest: null,
+    })),
+    {
+      path: ".workflow/tools/hooks/hook-event.mjs",
+      kind: "file",
+      manifest_key: "hook",
+      source: sources.sourceHook,
+      expected_digest: managedFileDigest(sources.sourceHook),
+      previous_digest: previous.managed_assets?.hook?.sha256 || null,
+    },
+    {
+      path: ".workflow/tools/state",
+      kind: "runtime",
+      manifest_key: "state_runtime",
+      sources: sources.stateSources,
+      expected_digest: sourceSetDigest(sources.stateSources),
+      previous_digest: previous.managed_assets?.state_runtime?.sha256 || null,
+    },
+    {
+      path: ".workflow/tools/evolution",
+      kind: "runtime",
+      manifest_key: "evolution_runtime",
+      sources: sources.evolutionSources,
+      expected_digest: sourceSetDigest(sources.evolutionSources),
+      previous_digest: previous.managed_assets?.evolution_runtime?.sha256 || null,
+    },
+    {
+      path: ".workflow/tools/bootstrap",
+      kind: "runtime",
+      manifest_key: "bootstrap_runtime",
+      sources: sources.bootstrapSources,
+      expected_digest: sourceSetDigest(sources.bootstrapSources),
+      previous_digest: previous.managed_assets?.bootstrap_runtime?.sha256 || null,
+    },
+    {
+      path: ".workflow/tools/mock",
+      kind: "runtime",
+      manifest_key: "mock_runtime",
+      sources: sources.mockSources,
+      expected_digest: sourceSetDigest(sources.mockSources),
+      previous_digest: previous.managed_assets?.mock_runtime?.sha256 || null,
+    },
+    {
+      path: ".workflow/tools/frontend-guard",
+      kind: "runtime",
+      manifest_key: "frontend_guard_runtime",
+      sources: sources.frontendGuardSources,
+      expected_digest: sourceSetDigest(sources.frontendGuardSources),
+      previous_digest: previous.managed_assets?.frontend_guard_runtime?.sha256 || null,
+    },
+    {
+      path: ".workflow/tools/ui-acceptance",
+      kind: "runtime",
+      manifest_key: "ui_acceptance_runtime",
+      sources: sources.uiAcceptanceSources,
+      expected_digest: sourceSetDigest(sources.uiAcceptanceSources),
+      previous_digest: previous.managed_assets?.ui_acceptance_runtime?.sha256 || null,
+    },
+    {
+      path: ".workflow/tools/manager",
+      kind: "runtime",
+      manifest_key: "manager_runtime",
+      sources: sources.managerSources,
+      expected_digest: sourceSetDigest(sources.managerSources),
+      previous_digest: previous.managed_assets?.manager_runtime?.sha256 || null,
+    },
+    {
+      path: "ref/ui",
+      kind: "directory",
+      manifest_key: "design_reference_library",
+      source: sources.sourceDesignReferenceLibrary,
+      expected_digest: directoryDigest(sources.sourceDesignReferenceLibrary),
+      previous_digest: previous.managed_assets?.design_reference_library?.sha256 || null,
+    },
+  );
+  return assets;
+}
+
+function upgradeMergedAssets(target, sources, manifest) {
+  const codePath = manifest.code_repository?.path;
+  if (!codePath || path.isAbsolute(codePath) || codePath.split(/[\\/]/).includes("..")) {
+    throw new Error("The installation manifest contains an unsafe code repository path.");
+  }
+  const definitions = MERGED_MANAGED_SURFACES.map((surface) => {
+    if (surface.key === "agents") {
+      return { ...surface, desired(existing) {
+        const template = fs.readFileSync(path.join(sources.sourceTemplate, "AGENTS.md"), "utf8");
+        return mergeManagedMarkdown(existing, template);
+      } };
+    }
+    if (surface.key === "hook_config") {
+      return { ...surface, desired(existing, refreshManaged) {
+        return existing
+          ? mergeHookConfig(existing, { force: refreshManaged }).text
+          : fs.readFileSync(sources.sourceHookConfig, "utf8");
+      } };
+    }
+    if (surface.key === "gitignore") {
+      return { ...surface, desired: (existing) => mergeGitignore(existing, [`/${codePath}/`]) };
+    }
+    return { ...surface, desired: (existing) => mergeGitattributes(existing) };
+  });
+  return definitions.map((definition) => {
+    const destination = installPath(target, definition.path);
+    const existing = fs.existsSync(destination) ? fs.readFileSync(destination, "utf8") : "";
+    const previousDigest = manifest.managed_assets?.merged_surfaces?.[definition.key]?.sha256 || null;
+    const currentManagedDigest = fs.existsSync(destination)
+      ? mergedSurfaceManagedDigest(definition.key, existing, codePath)
+      : null;
+    const packagedManagedDigest = mergedSurfaceManagedDigest(
+      definition.key,
+      expectedMergedSurfaceText(definition, sources, codePath),
+      codePath,
+    );
+    const desired = definition.desired(
+      existing,
+      !previousDigest
+        || currentManagedDigest !== previousDigest
+        || packagedManagedDigest !== previousDigest,
+    );
+    return {
+      ...definition,
+      destination,
+      exists: fs.existsSync(destination),
+      current_digest: fs.existsSync(destination) ? managedFileDigest(destination) : null,
+      current_managed_digest: currentManagedDigest,
+      previous_digest: previousDigest,
+      desired,
+      expected_digest: crypto.createHash("sha256")
+        .update(Buffer.from(desired.replaceAll("\r\n", "\n")))
+        .digest("hex"),
+    };
+  });
+}
+
+function preservedWorkflowFiles(target, managedPaths) {
+  const entries = [];
+  let totalFiles = 0;
+  const roots = [path.join(target, ".workflow"), path.join(target, ".agents")];
+  const normalizedManaged = managedPaths.map((item) => item.replaceAll("\\", "/").replace(/\/$/, ""));
+  const isWithin = (relative, prefixes) => prefixes.some(
+    (prefix) => relative === prefix || relative.startsWith(`${prefix}/`),
+  );
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    const pending = [{ absolute: root, directory: true }];
+    while (pending.length) {
+      const current = pending.pop();
+      const relative = path.relative(target, current.absolute).replaceAll("\\", "/");
+      if (isWithin(relative, PRESERVED_TRANSIENT_ROOTS) || isWithin(relative, normalizedManaged)) {
+        continue;
+      }
+      if (current.directory) {
+        const children = fs.readdirSync(current.absolute, { withFileTypes: true })
+          .filter((entry) => entry.isDirectory() || entry.isFile())
+          .sort((left, right) => left.name.localeCompare(right.name));
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+          const child = children[index];
+          pending.push({
+            absolute: path.join(current.absolute, child.name),
+            directory: child.isDirectory(),
+          });
+        }
+        continue;
+      }
+      if (relative === INSTALL_MANIFEST.replaceAll("\\", "/")) continue;
+      totalFiles += 1;
+      if (entries.length < PRESERVED_DETAIL_LIMIT) {
+        entries.push({ path: relative, reason: "outside managed installation assets" });
+      }
+    }
+  }
+  return {
+    entries,
+    summary: {
+      total_files: totalFiles,
+      reported_files: entries.length,
+      omitted_files: totalFiles - entries.length,
+      excluded_transient_roots: [...PRESERVED_TRANSIENT_ROOTS],
+    },
+  };
+}
+
+function planUpgrade(packageRoot, target, options) {
+  const { force = false, packageVersion = "0.0.0" } = options;
+  validateTarget(target);
+  for (const managedPath of [".agents", ".codex", ".workflow", "AGENTS.md", ".gitignore", ".gitattributes"]) {
+    validateManagedPath(target, path.join(target, managedPath));
+  }
+  const { manifest, manifestFile } = readInstallManifest(target);
+  if (!Number.isInteger(manifest.schema_version)
+    || manifest.schema_version < 5
+    || manifest.schema_version > INSTALL_MANIFEST_SCHEMA) {
+    throw new Error(
+      `Installation manifest schema ${manifest.schema_version} is incompatible with upgrade; run the compatible migration or repair command first.`,
+    );
+  }
+  const comparison = comparePackageVersions(packageVersion, manifest.version);
+  if (comparison === null) {
+    throw new Error(`Cannot compare installed package version ${manifest.version} with ${packageVersion}.`);
+  }
+  if (comparison < 0 && !force) {
+    throw new Error(`Refusing package downgrade from ${manifest.version} to ${packageVersion}; use --force only after explicit approval.`);
+  }
+  const workspace = readWorkspaceConfiguration(target);
+  const contractRetirement = executeDeliveryStateCommand([
+    "contract", "retire", "--project", target, "--gate-id", "UX-LF", "--dry-run",
+  ], { yaml: FORMAL_STATE_YAML });
+  const prototypeMigration = planPrototypeMigration(target);
+  const codeRepository = workspace.configuration.code_repository;
+  if (["path", "repo_id", "remote", "default_branch"].some((key) =>
+    (manifest.code_repository?.[key] ?? null) !== (codeRepository[key] ?? null))) {
+    throw new Error(
+      "The installation manifest code repository identity differs from authoritative .workflow/config/workspace.yaml; repair the installation state before upgrade.",
+    );
+  }
+  const sources = installationSources(packageRoot);
+  const exactAssets = managedAssetInventory(sources, manifest);
+  const retiredAssets = RETIRED_MANAGED_ASSETS
+    .filter((asset) => manifest.managed_assets?.[asset.manifest_key])
+    .map((asset) => ({
+      ...asset,
+      previous_digest: manifest.managed_assets[asset.manifest_key].sha256 || null,
+    }));
+  const mergedAssets = upgradeMergedAssets(
+    target,
+    sources,
+    { ...manifest, code_repository: codeRepository },
+  );
+  for (const asset of [...exactAssets, ...retiredAssets, ...mergedAssets]) {
+    validateManagedPath(target, installPath(target, asset.path));
+  }
+  const additions = [];
+  const replacements = [];
+  const removals = [];
+  const preserved = [];
+  const conflicts = [];
+  for (const asset of exactAssets) {
+    const destination = installPath(target, asset.path);
+    asset.destination = destination;
+    if (asset.kind === "ensure-directory") {
+      if (!fs.existsSync(destination)) {
+        asset.current_digest = null;
+        additions.push({ path: asset.path, kind: asset.kind });
+      } else if (fs.statSync(destination).isDirectory()) {
+        asset.current_digest = directoryDigest(destination);
+        preserved.push({ path: asset.path, reason: "required control shard directory is present" });
+      } else {
+        asset.current_digest = pathDigest(destination);
+        conflicts.push({
+          path: asset.path,
+          reason: "required control shard path is not a directory",
+          forceable: false,
+        });
+      }
+      continue;
+    }
+    const currentDigest = pathDigest(destination);
+    asset.current_digest = currentDigest;
+    if (currentDigest === null) additions.push({ path: asset.path, kind: asset.kind });
+    else if (currentDigest === asset.expected_digest) {
+      preserved.push({ path: asset.path, reason: "already current" });
+    } else if (asset.previous_digest && currentDigest !== asset.previous_digest) {
+      conflicts.push({ path: asset.path, reason: "managed asset differs from the installed manifest digest" });
+      if (force) replacements.push({ path: asset.path, kind: asset.kind, forced: true });
+    } else if (!asset.previous_digest) {
+      conflicts.push({ path: asset.path, reason: "installed manifest does not prove ownership of the current bytes" });
+      if (force) replacements.push({ path: asset.path, kind: asset.kind, forced: true });
+    } else {
+      replacements.push({ path: asset.path, kind: asset.kind, forced: false });
+    }
+  }
+  for (const asset of mergedAssets) {
+    if (!asset.exists) additions.push({ path: asset.path, kind: "merged-file" });
+    else if (asset.current_digest === asset.expected_digest) {
+      preserved.push({ path: asset.path, reason: "user-owned portions and managed contribution already current" });
+    } else if (asset.previous_digest && asset.current_managed_digest !== asset.previous_digest) {
+      conflicts.push({ path: asset.path, reason: "managed contribution differs from the installed manifest digest" });
+      if (force) replacements.push({ path: asset.path, kind: "merged-file", forced: true });
+    } else if (!asset.previous_digest) {
+      conflicts.push({ path: asset.path, reason: "installed manifest does not prove ownership of the managed contribution" });
+      if (force) replacements.push({ path: asset.path, kind: "merged-file", forced: true });
+    } else {
+      replacements.push({ path: asset.path, kind: "merged-file", forced: false });
+    }
+  }
+  for (const asset of retiredAssets) {
+    const destination = installPath(target, asset.path);
+    asset.destination = destination;
+    const currentDigest = pathDigest(destination);
+    asset.current_digest = currentDigest;
+    if (currentDigest === null) {
+      preserved.push({ path: asset.path, reason: "retired managed asset is already absent" });
+    } else if (asset.previous_digest && currentDigest === asset.previous_digest) {
+      removals.push({ path: asset.path, kind: asset.kind, forced: false });
+    } else {
+      conflicts.push({
+        path: asset.path,
+        reason: asset.previous_digest
+          ? "retired managed asset differs from the installed manifest digest"
+          : "installed manifest does not prove ownership of the retired managed asset",
+      });
+      if (force) removals.push({ path: asset.path, kind: asset.kind, forced: true });
+    }
+  }
+  const preservedWorkflow = preservedWorkflowFiles(
+    target,
+    [
+      ...exactAssets
+        .filter((asset) => asset.kind !== "ensure-directory")
+        .map((asset) => asset.path),
+      ...retiredAssets.map((asset) => asset.path),
+      ...mergedAssets.map((asset) => asset.path),
+    ],
+  );
+  for (const entry of preservedWorkflow.entries) preserved.push(entry);
+  const changedPaths = [...additions, ...replacements, ...removals].map((item) => item.path);
+  const manifestReplacement = {
+    path: INSTALL_MANIFEST.replaceAll("\\", "/"),
+    kind: "manifest",
+    forced: false,
+  };
+  replacements.push(manifestReplacement);
+  const backups = [
+    ...changedPaths.filter((relative) => fs.existsSync(installPath(target, relative))),
+    INSTALL_MANIFEST.replaceAll("\\", "/"),
+  ].map((relative) => ({ path: relative }));
+  return {
+    manifest,
+    manifestFile,
+    codeRepository,
+    sources,
+    exactAssets,
+    retiredAssets,
+    mergedAssets,
+    additions,
+    replacements,
+    removals,
+    preserved,
+    preservedSummary: preservedWorkflow.summary,
+    conflicts,
+    backups,
+    comparison,
+    contractRetirement,
+    prototypeMigration,
+  };
+}
+
+function copyUpgradeAsset(asset, destination) {
+  fs.rmSync(destination, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  if (asset.kind === "runtime") installManagedRuntime(destination, asset.sources);
+  else if (new Set(["directory", "ensure-directory"]).has(asset.kind)) {
+    fs.cpSync(asset.source, destination, { recursive: true });
+  }
+  else fs.copyFileSync(asset.source, destination);
+}
+
+function backupUpgradePath(target, upgradeRoot, relative) {
+  const source = installPath(target, relative);
+  if (!fs.existsSync(source)) return null;
+  const backupRelative = path.posix.join("backup", relative.replaceAll("\\", "/"));
+  const backup = installPath(upgradeRoot, backupRelative);
+  fs.mkdirSync(path.dirname(backup), { recursive: true });
+  fs.cpSync(source, backup, { recursive: true });
+  return backupRelative;
+}
+
+function restoreUpgradeAssets(target, upgradeRoot, assets) {
+  for (const asset of [...assets].reverse()) {
+    const destination = installPath(target, asset.path);
+    fs.rmSync(destination, { recursive: true, force: true });
+    if (asset.operation === "replace" || asset.operation === "remove") {
+      const backup = installPath(upgradeRoot, asset.backup_path);
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.cpSync(backup, destination, { recursive: true });
+    }
+  }
+}
+
+function applyReceiptBackedAsset({
+  target,
+  upgradeRoot,
+  asset,
+  operation,
+  receiptAssets,
+  apply,
+}) {
+  const backupPath = backupUpgradePath(target, upgradeRoot, asset.path);
+  const receiptAsset = {
+    path: asset.path,
+    operation,
+    backup_path: backupPath,
+    before_digest: exactPathDigest(asset.destination),
+    after_digest: null,
   };
+  receiptAssets.push(receiptAsset);
+  apply();
+  receiptAsset.after_digest = exactPathDigest(asset.destination);
+}
+
+function applyUpgradePlan(target, plan, packageVersion) {
+  const upgradeId = `UPGRADE-${new Date().toISOString().replace(/[-:.]/g, "")}-${crypto.randomBytes(4).toString("hex")}`;
+  const upgradeRoot = path.join(target, UPGRADE_RUNTIME, upgradeId);
+  const formalEvents = path.join(target, ".workflow", "control", "events");
+  const formalEventFingerprint = exactTreeDigest(formalEvents);
+  const receiptAssets = [];
+  fs.mkdirSync(upgradeRoot, { recursive: true });
+  try {
+    const additions = new Set(plan.additions.map((item) => item.path));
+    const changes = new Set([
+      ...plan.additions.map((item) => item.path),
+      ...plan.replacements.map((item) => item.path),
+      ...plan.removals.map((item) => item.path),
+    ]);
+    changes.delete(INSTALL_MANIFEST.replaceAll("\\", "/"));
+    for (const asset of plan.exactAssets) {
+      if (!changes.has(asset.path)) continue;
+      applyReceiptBackedAsset({
+        target,
+        upgradeRoot,
+        asset,
+        operation: additions.has(asset.path) ? "add" : "replace",
+        receiptAssets,
+        apply: () => copyUpgradeAsset(asset, asset.destination),
+      });
+    }
+    for (const asset of plan.mergedAssets) {
+      if (!changes.has(asset.path)) continue;
+      applyReceiptBackedAsset({
+        target,
+        upgradeRoot,
+        asset,
+        operation: additions.has(asset.path) ? "add" : "replace",
+        receiptAssets,
+        apply: () => atomicWrite(asset.destination, asset.desired),
+      });
+    }
+    for (const asset of plan.retiredAssets) {
+      if (!changes.has(asset.path)) continue;
+      applyReceiptBackedAsset({
+        target,
+        upgradeRoot,
+        asset,
+        operation: "remove",
+        receiptAssets,
+        apply: () => fs.rmSync(asset.destination, { recursive: true, force: true }),
+      });
+    }
+    const manifestRelative = INSTALL_MANIFEST.replaceAll("\\", "/");
+    const manifestBackup = backupUpgradePath(target, upgradeRoot, manifestRelative);
+    const nextManifest = buildInstallManifest(
+      plan.sources,
+      packageVersion,
+      plan.codeRepository,
+      plan.manifest,
+    );
+    nextManifest.last_upgrade = { upgrade_id: upgradeId, upgraded_at: new Date().toISOString() };
+    const manifestReceipt = {
+      path: manifestRelative,
+      operation: "replace",
+      backup_path: manifestBackup,
+      before_digest: exactPathDigest(installPath(upgradeRoot, manifestBackup)),
+      after_digest: null,
+    };
+    receiptAssets.push(manifestReceipt);
+    atomicWrite(plan.manifestFile, `${JSON.stringify(nextManifest, null, 2)}\n`);
+    manifestReceipt.after_digest = exactPathDigest(plan.manifestFile);
+    const receipt = {
+      schema_version: 1,
+      upgrade_id: upgradeId,
+      status: "applied",
+      from_version: plan.manifest.version,
+      to_version: packageVersion,
+      applied_at: new Date().toISOString(),
+      formal_event_tree_fingerprint: formalEventFingerprint,
+      contract_retirement: {
+        gate_id: plan.contractRetirement.gate_id,
+        contract_version: UI_CONTRACT_VERSION,
+        affected_iterations: plan.contractRetirement.affected_iterations,
+        expected_scope_revisions: plan.contractRetirement.expected_scope_revisions,
+      },
+      assets: receiptAssets,
+    };
+    atomicWrite(path.join(upgradeRoot, "receipt.json"), `${JSON.stringify(receipt, null, 2)}\n`);
+    const retirementArgs = [
+      "contract", "retire", "--project", target,
+      "--gate-id", "UX-LF",
+      "--actor", "system:package-upgrade",
+      "--reason", "prototype-first UI contract",
+      "--contract-version", UI_CONTRACT_VERSION,
+    ];
+    const expectedRevisions = Object.values(plan.contractRetirement.expected_scope_revisions);
+    if (expectedRevisions.length === 1) {
+      retirementArgs.push("--expected-scope-revision", String(expectedRevisions[0]));
+    }
+    const contractRetirement = executeDeliveryStateCommand(retirementArgs, {
+      yaml: FORMAL_STATE_YAML,
+    });
+    return { upgradeId, contractRetirement };
+  } catch (error) {
+    restoreUpgradeAssets(target, upgradeRoot, receiptAssets);
+    fs.rmSync(upgradeRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function rollbackUpgrade(packageRoot, target, upgradeId) {
+  validateTarget(target);
+  if (!/^UPGRADE-[0-9A-Za-z_-]+$/.test(upgradeId || "")) {
+    throw new Error("Invalid upgrade rollback identifier.");
+  }
+  const upgradeRoot = path.join(target, UPGRADE_RUNTIME, upgradeId);
+  validateManagedPath(target, upgradeRoot);
+  const receiptFile = path.join(upgradeRoot, "receipt.json");
+  let receipt;
+  try {
+    receipt = JSON.parse(fs.readFileSync(receiptFile, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read upgrade rollback receipt ${upgradeId}: ${error.message}`);
+  }
+  if (receipt.schema_version !== 1
+    || receipt.upgrade_id !== upgradeId
+    || receipt.status !== "applied"
+    || !Array.isArray(receipt.assets)) {
+    throw new Error(`Upgrade ${upgradeId} is not in an applied rollback state.`);
+  }
+  const sources = installationSources(packageRoot);
+  const allowedPaths = new Set([
+    ...managedAssetInventory(sources).map((asset) => asset.path),
+    ...RETIRED_MANAGED_ASSETS.map((asset) => asset.path),
+    ...MERGED_MANAGED_SURFACES.map((surface) => surface.path),
+    INSTALL_MANIFEST.replaceAll("\\", "/"),
+  ]);
+  for (const asset of receipt.assets) {
+    if (!allowedPaths.has(asset.path)
+      || !new Set(["add", "replace", "remove"]).has(asset.operation)
+      || (new Set(["replace", "remove"]).has(asset.operation) && !asset.backup_path)) {
+      throw new Error(`Upgrade receipt contains an unsafe managed asset entry: ${asset.path || "<missing>"}.`);
+    }
+    const destination = installPath(target, asset.path);
+    validateManagedPath(target, destination);
+    if (asset.backup_path) {
+      const backup = installPath(upgradeRoot, asset.backup_path);
+      if (!isInside(backup, upgradeRoot)
+        || !asset.backup_path.replaceAll("\\", "/").startsWith("backup/")) {
+        throw new Error(`Upgrade receipt contains an unsafe backup path for ${asset.path}.`);
+      }
+      validateManagedPath(upgradeRoot, backup);
+    }
+  }
+  const currentFingerprint = exactTreeDigest(path.join(target, ".workflow", "control", "events"));
+  if (currentFingerprint !== receipt.formal_event_tree_fingerprint) {
+    throw new Error(
+      "A new-format formal transaction was written after this upgrade; rollback is blocked. Use forward repair.",
+    );
+  }
+  for (const asset of receipt.assets) {
+    if (exactPathDigest(installPath(target, asset.path)) !== asset.after_digest) {
+      throw new Error(`Managed asset changed after upgrade (${asset.path}); rollback is blocked. Use forward repair.`);
+    }
+    if (asset.operation === "replace" || asset.operation === "remove") {
+      const backup = installPath(upgradeRoot, asset.backup_path);
+      if (exactPathDigest(backup) !== asset.before_digest) {
+        throw new Error(`Upgrade backup changed after apply (${asset.path}); rollback is blocked. Use forward repair.`);
+      }
+    }
+  }
+  restoreUpgradeAssets(target, upgradeRoot, receipt.assets);
+  receipt.status = "rolled_back";
+  receipt.rolled_back_at = new Date().toISOString();
+  atomicWrite(receiptFile, `${JSON.stringify(receipt, null, 2)}\n`);
+  return {
+    command: "upgrade rollback",
+    upgrade_id: upgradeId,
+    rolled_back: true,
+    restored_version: receipt.from_version,
+  };
+}
+
+export function upgradeProject(packageRoot, target, options = {}) {
+  if (options.rollback) return rollbackUpgrade(packageRoot, target, options.rollback);
+  const { dryRun = false, force = false, packageVersion = "0.0.0" } = options;
+  const plan = planUpgrade(packageRoot, target, { force, packageVersion });
+  const report = {
+    command: "upgrade",
+    dry_run: dryRun,
+    applied: false,
+    upgrade_id: null,
+    from_version: plan.manifest.version,
+    to_version: packageVersion,
+    changes: {
+      additions: plan.additions,
+      replacements: plan.replacements,
+      removals: plan.removals,
+      preserved: plan.preserved,
+      preserved_summary: plan.preservedSummary,
+      conflicts: plan.conflicts,
+      backups: plan.backups,
+    },
+    compatibility: {
+      installation_manifest: "compatible",
+      package_version: plan.comparison > 0 ? "upgrade" : plan.comparison === 0 ? "same-version repair" : "forced downgrade",
+    },
+    code_repository: {
+      path: plan.codeRepository.path,
+      write_planned: false,
+    },
+    contract_retirement: {
+      ...plan.contractRetirement,
+      contract_version: UI_CONTRACT_VERSION,
+      write_planned: plan.contractRetirement.affected_iterations.length > 0,
+    },
+    prototype_migration: {
+      ...plan.prototypeMigration,
+      required_follow_up: {
+        command: "ai-delivery migrate",
+        write_planned: false,
+      },
+    },
+  };
+  if (dryRun) return report;
+  const blockingConflicts = plan.conflicts.filter((item) => !force || item.forceable === false);
+  if (blockingConflicts.length) {
+    throw new Error(
+      `Managed files differ from the installed manifest:\n- ${blockingConflicts.map((item) =>
+        `${item.path}: ${item.reason}`).join("\n- ")}\nRerun with --force only after explicit approval of forceable conflicts.`,
+    );
+  }
+  const applied = applyUpgradePlan(target, plan, packageVersion);
+  report.upgrade_id = applied.upgradeId;
+  report.contract_retirement = {
+    ...report.contract_retirement,
+    ...applied.contractRetirement,
+    contract_version: UI_CONTRACT_VERSION,
+    write_planned: false,
+  };
+  report.applied = true;
+  return report;
+}
+
+function managedRuntimeDoctorCheck(target, options) {
+  const installedRoot = path.join(target, ".workflow", "tools", options.directory);
+  const expectedDigest = options.expectedSources.length
+    ? sourceSetDigest(options.expectedSources)
+    : null;
+  const integrity = Boolean(expectedDigest)
+    && fs.existsSync(installedRoot)
+    && directoryDigest(installedRoot) === expectedDigest
+    && options.manifestDigest === expectedDigest;
+  const smoke = spawnSync(
+    process.execPath,
+    [path.join(installedRoot, options.cli), "--help"],
+    { cwd: target, encoding: "utf8", windowsHide: true },
+  );
+  const smokeOk = smoke.status === 0 && options.helpPattern.test(smoke.stdout);
+  return {
+    ok: integrity && smokeOk,
+    scope: options.scope,
+    message: !integrity
+      ? `project ${options.label} runtime integrity check failed`
+      : smokeOk
+        ? `project ${options.label} runtime integrity and CLI smoke check pass`
+        : `project ${options.label} CLI smoke check failed: ${smoke.stderr.trim() || smoke.error?.message || "no valid output"}`,
+  };
+}
+
+function rawGitAttributePolicy(gitattributes) {
+  const rawTargets = new Set(RAW_GIT_ATTRIBUTE_TARGETS.map((target) => `/${target}`));
+  const invalid = [];
+  const legacyPatterns = [];
+  for (const line of gitattributes.split(/\r?\n/).map((entry) => entry.trim())) {
+    if (!line || line.startsWith("#") || !/(?:^|\s)-text(?:\s|$)/.test(line)) continue;
+    const [pattern] = line.split(/\s+/);
+    if (rawTargets.has(pattern)) continue;
+    const normalized = pattern.replace(/^\//, "");
+    const segments = normalized.split("/");
+    const fixedDirectory = segments.length >= 4
+      && segments[0] === ".workflow"
+      && segments[1] === "iterations"
+      && !/[?*\[]/.test(segments[2])
+      && segments.slice(0, -1).every((segment) => !/[?*\[]/.test(segment));
+    const narrowFilename = !pattern.includes("**") && !/[?\[]/.test(segments.at(-1));
+    if (fixedDirectory && narrowFilename) legacyPatterns.push(normalized);
+    else invalid.push(line);
+  }
+  return { invalid, legacyPatterns };
+}
+
+function matchesRegisteredLegacyPattern(relative, pattern) {
+  const relativeSegments = relative.split("/");
+  const patternSegments = pattern.split("/");
+  if (relativeSegments.length !== patternSegments.length) return false;
+  return patternSegments.every((segment, index) => {
+    if (!segment.includes("*")) return segment === relativeSegments[index];
+    const expression = segment.split("*")
+      .map((part) => part.replace(/[.+^${}()|[\]\\]/g, "\\$&"))
+      .join("[^/]*");
+    return new RegExp(`^${expression}$`).test(relativeSegments[index]);
+  });
+}
+
+function isRawLegacyIterationEvidence(target, relative, text, eol, registeredPatterns) {
+  return text === "unset"
+    && eol === "lf"
+    && relative.startsWith(".workflow/iterations/")
+    && fs.existsSync(installPath(target, relative))
+    && registeredPatterns.some((pattern) => matchesRegisteredLegacyPattern(relative, pattern));
+}
+
+function filesUnderExcluding(root, excludedRoots) {
+  if (!fs.existsSync(root)) return [];
+  const files = [];
+  const pending = [root];
+  while (pending.length) {
+    const current = pending.pop();
+    if (excludedRoots.some((excluded) => isInside(current, excluded))) continue;
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) pending.push(absolute);
+      else if (entry.isFile()) files.push(absolute);
+    }
+  }
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function effectiveGitAttributeAudit(target, files, registeredLegacyPatterns) {
+  const invalid = [];
+  let invalidCount = 0;
+  for (let index = 0; index < files.length; index += DOCTOR_ATTRIBUTE_BATCH_SIZE) {
+    const batch = files.slice(index, index + DOCTOR_ATTRIBUTE_BATCH_SIZE);
+    const result = spawnSync(
+      "git",
+      ["-c", "core.quotePath=false", "check-attr", "-z", "--stdin", "text", "eol"],
+      {
+        cwd: target,
+        encoding: "utf8",
+        input: `${batch.join("\0")}\0`,
+        maxBuffer: 16 * 1024 * 1024,
+        windowsHide: true,
+      },
+    );
+    if (result.status !== 0) {
+      return {
+        failed: true,
+        error: (result.stderr || result.error?.message || "git check-attr failed").trim(),
+        invalid,
+        invalidCount,
+      };
+    }
+    const values = new Map();
+    const tokens = result.stdout.split("\0");
+    for (let offset = 0; offset + 2 < tokens.length; offset += 3) {
+      const [file, attribute, value] = tokens.slice(offset, offset + 3);
+      if (!file || !attribute) continue;
+      if (!values.has(file)) values.set(file, {});
+      values.get(file)[attribute] = value;
+    }
+    for (const file of batch) {
+      const text = values.get(file)?.text;
+      const eol = values.get(file)?.eol;
+      const rawAttribution = RAW_GIT_ATTRIBUTE_TARGETS.includes(file);
+      const valid = rawAttribution
+        ? text === "unset" && eol === "unspecified"
+        : isRawLegacyIterationEvidence(target, file, text, eol, registeredLegacyPatterns)
+          || (text === "set" || text === "auto") && eol === "lf";
+      if (valid) continue;
+      invalidCount += 1;
+      if (invalid.length < DOCTOR_DETAIL_LIMIT) invalid.push(file);
+    }
+  }
+  return { failed: false, error: null, invalid, invalidCount };
 }
 
 export function doctorProject(target, options = {}) {
@@ -803,12 +2053,19 @@ export function doctorProject(target, options = {}) {
   } catch (error) {
     checks.push({ ok: false, message: error.message });
   }
+  if (workspace) {
+    checks.push(inspectCodeGraph(target, {
+      runner: options.codeGraphRunner,
+      command: options.codeGraphCommand,
+      env: options.codeGraphEnv,
+    }));
+  }
   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,
+      ok: manifest.scope === "workspace" && manifest.schema_version === INSTALL_MANIFEST_SCHEMA,
       message: "installation manifest uses workspace scope",
     });
   } catch (error) {
@@ -824,11 +2081,21 @@ export function doctorProject(target, options = {}) {
     message: "workflow repository has an independent Git root",
   });
   const missingControlDirectories = CONTROL_DIRECTORIES.filter((directory) =>
-    !fs.existsSync(path.join(target, ".workflow", "control", directory)));
+    !fs.existsSync(path.join(target, ".workflow", "control", directory))
+      || !fs.statSync(path.join(target, ".workflow", "control", directory)).isDirectory());
+  const missingControlMarkers = ENSURED_CONTROL_DIRECTORIES.filter((directory) => {
+    const directoryPath = path.join(target, ".workflow", "control", directory);
+    const marker = path.join(directoryPath, ".gitkeep");
+    return fs.existsSync(directoryPath)
+      && fs.statSync(directoryPath).isDirectory()
+      && (!fs.existsSync(marker) || !fs.statSync(marker).isFile());
+  }).map((directory) => `${directory}/.gitkeep`);
   checks.push({
-    ok: missingControlDirectories.length === 0,
+    ok: missingControlDirectories.length === 0 && missingControlMarkers.length === 0,
     message: missingControlDirectories.length
       ? `shared control shard directories are missing: ${missingControlDirectories.join(", ")}`
+      : missingControlMarkers.length
+        ? `shared control shard directories have missing markers: ${missingControlMarkers.join(", ")}`
       : "shared task, artifact, Gate, version, and release shard directories are present",
   });
   checks.push({
@@ -845,12 +2112,17 @@ export function doctorProject(target, options = {}) {
   });
 
   const packageRoot = options.packageRoot || PACKAGE_ROOT;
+  const packageSurface = packageSurfaceDoctorCheck(packageRoot);
+  checks.push(packageSurface);
   let expectedSkills = ESSENTIAL_STARTUP_SKILLS;
   let expectedSkillDigests = {};
   let expectedHook = null;
   let expectedBootstrapSources = [];
   let expectedStateSources = [];
   let expectedEvolutionSources = [];
+  let expectedMockSources = [];
+  let expectedFrontendGuardSources = [];
+  let expectedUiAcceptanceSources = [];
   try {
     expectedSkills = packagedSkillNames(packageRoot);
     expectedSkillDigests = Object.fromEntries(expectedSkills.map((name) => [
@@ -858,10 +2130,15 @@ export function doctorProject(target, options = {}) {
       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);
+    if (packageSurface.ok) {
+      const sourceTemplate = path.join(packageRoot, "skills", "ai-delivery-orchestrate", "assets", "project-template");
+      expectedBootstrapSources = bootstrapRuntimeSources(packageRoot, sourceTemplate);
+      expectedStateSources = stateRuntimeSources(packageRoot, sourceTemplate);
+      expectedEvolutionSources = evolutionRuntimeSources(packageRoot, sourceTemplate);
+      expectedMockSources = mockRuntimeSources(packageRoot, sourceTemplate);
+      expectedFrontendGuardSources = frontendGuardRuntimeSources(packageRoot, sourceTemplate);
+      expectedUiAcceptanceSources = uiAcceptanceRuntimeSources(packageRoot, sourceTemplate);
+    }
   } catch (error) {
     checks.push({ ok: false, message: `packaged managed-asset baseline is unavailable: ${error.message}` });
   }
@@ -890,6 +2167,20 @@ export function doctorProject(target, options = {}) {
       ? `managed skill integrity failed: damaged=${damagedSkills.join(", ") || "none"}; manifest=${inconsistentSkillDigests.join(", ") || "none"}`
       : "managed skill integrity matches the fixed package baseline",
   });
+  if (!packageSurface.ok) return { checks, ok: false };
+  checks.push(designReferenceDoctorCheck(
+    target,
+    path.join(
+      packageRoot,
+      "skills",
+      "ai-delivery-orchestrate",
+      "assets",
+      "project-template",
+      "ref",
+      "ui",
+    ),
+    manifest,
+  ));
   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" });
@@ -908,28 +2199,11 @@ export function doctorProject(target, options = {}) {
     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",
+    "history-anchor.mjs",
+    "fs-utils.mjs",
     "vendor/yaml/package.json",
     "vendor/yaml/dist/index.js",
   ];
@@ -960,6 +2234,8 @@ export function doctorProject(target, options = {}) {
     "workspace.mjs",
     "yaml-runtime.mjs",
     "delivery-state.mjs",
+    "history-anchor.mjs",
+    "fs-utils.mjs",
   ];
   const missingBootstrapFiles = bootstrapFiles.filter((file) =>
     !fs.existsSync(path.join(installedBootstrapRoot, file)));
@@ -999,7 +2275,13 @@ export function doctorProject(target, options = {}) {
     const result = spawnSync(
       process.execPath,
       [path.join(installedStateRoot, "state.mjs"), command],
-      { cwd: target, encoding: "utf8", windowsHide: true },
+      {
+        cwd: target,
+        encoding: "utf8",
+        maxBuffer: command === "inspect" ? FORMAL_STATE_INSPECT_MAX_BUFFER : undefined,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+      },
     );
     let output = null;
     try {
@@ -1007,7 +2289,9 @@ export function doctorProject(target, options = {}) {
     } catch {
       output = null;
     }
-    const validOutput = command === "verify" ? output?.valid === true : output?.command === "inspect";
+    const validOutput = command === "verify"
+      ? output?.valid === true
+      : output?.command === "inspect";
     return { ...result, command, validOutput };
   });
   const smokeOk = smokeResults.every((result) => result.status === 0 && result.validOutput);
@@ -1042,6 +2326,47 @@ export function doctorProject(target, options = {}) {
       ? "workflow evolution CLI verify smoke check passes"
       : `workflow evolution CLI smoke check failed: ${evolutionSmoke.stderr.trim() || "no valid output"}`,
   });
+  const installedMockRoot = path.join(target, ".workflow", "tools", "mock");
+  const expectedMockDigest = expectedMockSources.length ? sourceSetDigest(expectedMockSources) : null;
+  const mockIntegrity = Boolean(expectedMockDigest)
+    && fs.existsSync(installedMockRoot)
+    && directoryDigest(installedMockRoot) === expectedMockDigest
+    && manifest?.managed_assets?.mock_runtime?.sha256 === expectedMockDigest;
+  const mockSmoke = spawnSync(
+    process.execPath,
+    [path.join(installedMockRoot, "mock.mjs"), "--help"],
+    { cwd: target, encoding: "utf8", windowsHide: true },
+  );
+  const mockSmokeOk = mockSmoke.status === 0
+    && /mock <setup\|start\|stop\|status\|sync>/.test(mockSmoke.stdout)
+    && /mock freeze.*--scenario-pack/.test(mockSmoke.stdout);
+  checks.push({
+    ok: mockIntegrity && mockSmokeOk,
+    scope: "mock-system",
+    message: !mockIntegrity
+      ? "project Mock System runtime integrity check failed"
+      : mockSmokeOk
+        ? "project Mock System runtime integrity and CLI smoke check pass"
+        : `project Mock System CLI smoke check failed: ${mockSmoke.stderr.trim() || "no valid output"}`,
+  });
+  checks.push(managedRuntimeDoctorCheck(target, {
+    directory: "frontend-guard",
+    expectedSources: expectedFrontendGuardSources,
+    manifestDigest: manifest?.managed_assets?.frontend_guard_runtime?.sha256,
+    cli: "frontend-guard.mjs",
+    helpPattern: /frontend-guard <check-file\|verify-diff>/,
+    scope: "frontend-guard",
+    label: "frontend guard",
+  }));
+  checks.push(managedRuntimeDoctorCheck(target, {
+    directory: "ui-acceptance",
+    expectedSources: expectedUiAcceptanceSources,
+    manifestDigest: manifest?.managed_assets?.ui_acceptance_runtime?.sha256,
+    cli: "ui-acceptance.mjs",
+    helpPattern: /ui-acceptance <plan\|verify>/,
+    scope: "ui-acceptance",
+    label: "UI Acceptance",
+  }));
   const evolutionVerify = spawnSync(
     process.execPath,
     [path.join(installedEvolutionRoot, "evolve.mjs"), "verify"],
@@ -1083,6 +2408,7 @@ export function doctorProject(target, options = {}) {
     : "";
   const missingAttributes = GIT_ATTRIBUTE_ENTRIES.filter((entry) =>
     !gitattributes.split(/\r?\n/).some((line) => line.trim() === entry));
+  const rawAttributePolicy = rawGitAttributePolicy(gitattributes);
   const attributeTargets = [...new Set([
     ".workflow/delivery/workflow-state.yaml",
     ".agents/skills/ai-delivery-orchestrate/SKILL.md",
@@ -1090,43 +2416,37 @@ export function doctorProject(target, options = {}) {
     "AGENTS.md",
     ".gitignore",
     ".gitattributes",
-    ...filesUnder(path.join(target, ".workflow"))
+    ...RAW_GIT_ATTRIBUTE_TARGETS,
+    ...filesUnderExcluding(
+      path.join(target, ".workflow"),
+      PRESERVED_TRANSIENT_ROOTS.map((root) => installPath(target, root)),
+    )
       .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];
+  const attributeAudit = effectiveGitAttributeAudit(
+    target,
+    attributeTargets,
+    rawAttributePolicy.legacyPatterns,
+  );
+  const omittedInvalidAttributes = attributeAudit.invalidCount - attributeAudit.invalid.length;
   checks.push({
-    ok: missingAttributes.length === 0 && invalidEffectiveAttributes.length === 0,
+    ok: missingAttributes.length === 0
+      && rawAttributePolicy.invalid.length === 0
+      && !attributeAudit.failed
+      && attributeAudit.invalidCount === 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",
+      : rawAttributePolicy.invalid.length
+        ? `project .gitattributes is overridden by broad raw-byte rules or unsupported raw-byte rules: ${rawAttributePolicy.invalid.join(", ")}`
+      : attributeAudit.failed
+        ? `project .gitattributes effective check failed: ${attributeAudit.error}`
+        : attributeAudit.invalidCount
+          ? `project .gitattributes is overridden for checksummed files: ${attributeAudit.invalid.join(", ")}`
+            + (omittedInvalidAttributes ? ` (+${omittedInvalidAttributes} omitted)` : "")
+          : "project .gitattributes keeps managed checksummed files byte-stable",
   });
   if (workspace) {
     const expectedIgnore = `/${workspace.configuration.code_repository.path}/`;