@cubis/foundry 0.3.77 → 0.3.79

package/src/cli/core.ts

@@ -14,6 +14,7 @@ import {
   symlink,
   writeFile,
 } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { spawn, execFile as execFileCallback } from "node:child_process";
 import os from "node:os";
@@ -60,6 +61,26 @@ const ENGINEERING_RULES_FILE_BLOCK_START_RE =
   /<!--\s*cbx:engineering:rules:start[^>]*-->/g;
 const ENGINEERING_RULES_FILE_BLOCK_END_RE =
   /<!--\s*cbx:engineering:rules:end\s*-->/g;
+const ENGINEERING_ARCHITECTURE_BLOCK_START_RE =
+  /<!--\s*cbx:architecture:rules:start[^>]*-->/g;
+const ENGINEERING_ARCHITECTURE_BLOCK_END_RE =
+  /<!--\s*cbx:architecture:rules:end\s*-->/g;
+const PRODUCT_FOUNDATION_BLOCK_START_RE =
+  /<!--\s*cbx:product:foundation:start[^>]*-->/g;
+const PRODUCT_FOUNDATION_BLOCK_END_RE =
+  /<!--\s*cbx:product:foundation:end\s*-->/g;
+const ARCHITECTURE_DOC_BLOCK_START_RE =
+  /<!--\s*cbx:architecture:doc:start[^>]*-->/g;
+const ARCHITECTURE_DOC_BLOCK_END_RE =
+  /<!--\s*cbx:architecture:doc:end\s*-->/g;
+const TECH_ARCHITECTURE_BLOCK_START_RE =
+  /<!--\s*cbx:architecture:tech:start[^>]*-->/g;
+const TECH_ARCHITECTURE_BLOCK_END_RE =
+  /<!--\s*cbx:architecture:tech:end\s*-->/g;
+const ROADMAP_FOUNDATION_BLOCK_START_RE =
+  /<!--\s*cbx:roadmap:foundation:start[^>]*-->/g;
+const ROADMAP_FOUNDATION_BLOCK_END_RE =
+  /<!--\s*cbx:roadmap:foundation:end\s*-->/g;
 const COPILOT_ALLOWED_SKILL_FRONTMATTER_KEYS = new Set([
   "compatibility",
   "description",
@@ -253,11 +274,18 @@ const PLAYWRIGHT_MCP_URL = `http://localhost:${PLAYWRIGHT_DEFAULT_PORT}/mcp`;
 const POSTMAN_WORKSPACE_MANUAL_CHOICE = "__postman_workspace_manual__";
 const CBX_CONFIG_FILENAME = "cbx_config.json";
 const CBX_CREDENTIALS_ENV_FILENAME = "credentials.env";
+const ARCHITECTURE_BUILD_METADATA_FILENAME = "architecture-build.json";
 const LEGACY_POSTMAN_CONFIG_FILENAME = ["postman", "setting.json"].join("_");
 const DEFAULT_CREDENTIAL_PROFILE_NAME = "default";
 const RESERVED_CREDENTIAL_PROFILE_NAMES = new Set(["all"]);
 const CREDENTIAL_SERVICES = new Set(["postman", "stitch"]);
 const MCP_RUNTIMES = new Set(["docker", "local"]);
+const ARCHITECTURE_BUILD_PLATFORMS = new Set([
+  "codex",
+  "claude",
+  "gemini",
+  "copilot",
+]);
 const MCP_FALLBACKS = new Set(["local", "fail", "skip"]);
 const MCP_UPDATE_POLICIES = new Set(["pinned", "latest"]);
 const DEFAULT_MCP_RUNTIME = "docker";
@@ -957,6 +985,464 @@ function buildAntigravityTerminalVerificationBlock({
   ].join("\n");
 }
 
+function hashStableObject(value) {
+  return createHash("sha256")
+    .update(JSON.stringify(value))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+function firstNonEmpty(values) {
+  for (const value of values || []) {
+    if (value) return value;
+  }
+  return null;
+}
+
+function inferArchitectureContractProfile(snapshot) {
+  const allSignals = [];
+  for (const app of snapshot.architectureByApp || []) {
+    for (const signal of app.architectureSignals || []) {
+      if (!allSignals.includes(signal)) allSignals.push(signal);
+    }
+  }
+
+  const style =
+    firstNonEmpty([
+      allSignals.find((signal) => /clean architecture/i.test(signal)),
+      allSignals.find((signal) => /hexagonal/i.test(signal)),
+      allSignals.find((signal) => /feature-first/i.test(signal)),
+      allSignals.find((signal) => /mvvm/i.test(signal)),
+      allSignals.find((signal) => /mvc/i.test(signal)),
+    ]) || "Undeclared — align to current repository conventions";
+
+  const moduleBoundaries = snapshot.annotatedDirs
+    .slice(0, 8)
+    .map(({ name, purpose }) =>
+      purpose ? `${name}/ (${purpose})` : `${name}/`,
+    );
+
+  const dependencyRules = [];
+  if (/clean architecture/i.test(style)) {
+    dependencyRules.push(
+      "Domain code must not depend on infrastructure, framework, or presentation layers.",
+    );
+    dependencyRules.push(
+      "Adapters may depend inward on domain contracts, never the reverse.",
+    );
+  } else if (/hexagonal/i.test(style)) {
+    dependencyRules.push(
+      "Ports stay stable at the boundary; adapters implement them without leaking infrastructure concerns inward.",
+    );
+  } else {
+    dependencyRules.push(
+      "Respect existing feature and package boundaries; avoid hidden cross-module imports.",
+    );
+  }
+  dependencyRules.push(
+    "Shared UI, data, and platform conventions belong in the declared common layer, not duplicated per feature.",
+  );
+
+  const designSystemSource =
+    firstNonEmpty([
+      snapshot.topDirs.includes("components")
+        ? "components/ is the primary shared UI surface."
+        : null,
+      snapshot.topDirs.includes("design-system")
+        ? "design-system/ is the primary shared UI surface."
+        : null,
+      snapshot.topDirs.includes("app")
+        ? "App-level UI patterns should be centralized and reused across screens."
+        : null,
+    ]) || "No dedicated design-system directory detected; infer shared UI rules from current components and screens.";
+
+  const testingStrategy = [];
+  if (snapshot.keyScripts.some((script) => script.name === "lint")) {
+    testingStrategy.push("Linting is part of the baseline quality gate.");
+  }
+  if (snapshot.keyScripts.some((script) => script.name.includes("type"))) {
+    testingStrategy.push(
+      "Static typing or analysis should pass before merge when the stack supports it.",
+    );
+  }
+  if (snapshot.keyScripts.some((script) => script.name.startsWith("test"))) {
+    testingStrategy.push(
+      "Focused automated tests should cover the changed behavior before merge.",
+    );
+  }
+  if (testingStrategy.length === 0) {
+    testingStrategy.push(
+      "Add focused validation evidence for non-trivial changes even when no standard test command is detected.",
+    );
+  }
+
+  const scalingConstraints = inferTechnicalConstraints(snapshot, {
+    suggestedProfile: inferContextBudget(snapshot).suggestedProfile,
+  });
+
+  const docUpdateTriggers = [
+    "feature additions that change module boundaries or shared UI rules",
+    "migrations, scale changes, or deployment-shape changes",
+    "refactors that establish new conventions future work should follow",
+  ];
+
+  return {
+    style,
+    moduleBoundaries,
+    dependencyRules,
+    designSystemSource,
+    testingStrategy,
+    scalingConstraints,
+    docUpdateTriggers,
+  };
+}
+
+function buildArchitectureMermaid(snapshot) {
+  const topDirs = snapshot.topDirs.slice(0, 4);
+  const flowNodes = topDirs.length > 0 ? topDirs : ["src", "docs"];
+  const lines = [
+    "flowchart TD",
+    '  user["User / Entry Point"] --> app["Application Surface"]',
+  ];
+  for (let index = 0; index < flowNodes.length; index += 1) {
+    const nodeName = flowNodes[index].replace(/[^A-Za-z0-9]/g, "") || `N${index}`;
+    lines.push(`  app --> ${nodeName}["${flowNodes[index]}/"]`);
+  }
+  if (snapshot.isMcpServer || snapshot.mcpSignals.length > 0) {
+    lines.push('  app --> mcp["MCP / Tooling Surface"]');
+  }
+  if (snapshot.cicdSignals.length > 0) {
+    lines.push('  app --> deploy["Delivery / Runtime"]');
+  }
+  return lines.join("\n");
+}
+
+function inferProductFoundationProfile(snapshot, specRoots = []) {
+  const appRoots = (snapshot.architectureByApp || [])
+    .map((item) => item.rootPath)
+    .filter((value) => value && value !== ".");
+  const primarySurfaces = appRoots.length > 0 ? appRoots : snapshot.topDirs.slice(0, 6);
+  const userPersonas = [];
+
+  if (snapshot.frameworks.includes("Flutter")) {
+    userPersonas.push("End users interacting through mobile or desktop app surfaces");
+  }
+  if (
+    snapshot.frameworks.includes("Next.js") ||
+    snapshot.frameworks.includes("React") ||
+    snapshot.topDirs.includes("web")
+  ) {
+    userPersonas.push("Browser users and internal operators using web-facing flows");
+  }
+  if (snapshot.frameworks.includes("NestJS") || snapshot.topDirs.includes("api")) {
+    userPersonas.push("Internal services, operators, or partner systems consuming API boundaries");
+  }
+  if (userPersonas.length === 0) {
+    userPersonas.push(
+      "Project stakeholders are not obvious from the repo alone; refine personas from product context before major feature work.",
+    );
+  }
+
+  const coreJourneys = [];
+  if (specRoots.length > 0) {
+    coreJourneys.push(
+      `Active implementation themes are reflected in current spec packs: ${specRoots.join(", ")}.`,
+    );
+  }
+  if (primarySurfaces.length > 0) {
+    coreJourneys.push(
+      `Primary product surfaces currently live in: ${primarySurfaces.join(", ")}.`,
+    );
+  }
+  if (snapshot.isMcpServer || snapshot.mcpSignals.length > 0) {
+    coreJourneys.push("Tool-assisted and MCP-driven workflows are part of the operating model and should stay stable.");
+  }
+  if (coreJourneys.length === 0) {
+    coreJourneys.push(
+      "Repository evidence is thin; capture the primary user journeys here before scaling the codebase further.",
+    );
+  }
+
+  const successSignals = [
+    "Feature work should stay aligned to explicit user or operator value, not speculative abstractions.",
+    "Architecture changes should reduce onboarding, debugging, and testing cost over time.",
+  ];
+  if (snapshot.cicdSignals.length > 0) {
+    successSignals.push(
+      `Delivery flows already rely on ${snapshot.cicdSignals.join(", ")} signals; keep release friction low for that pipeline.`,
+    );
+  }
+
+  return {
+    productScope:
+      snapshot.readmeExcerpt ||
+      "No explicit product summary was detected from repo docs. Replace this with a concise product statement when better context exists.",
+    primarySurfaces,
+    userPersonas,
+    coreJourneys,
+    successSignals,
+  };
+}
+
+function buildProductFoundationSection(snapshot, specRoots = []) {
+  const profile = inferProductFoundationProfile(snapshot, specRoots);
+  const hash = hashStableObject(profile);
+
+  return [
+    `<!-- cbx:product:foundation:start version=1 profile=${hash} -->`,
+    "## Product Foundation (auto-managed)",
+    "",
+    "### Product Scope",
+    profile.productScope,
+    "",
+    "### Primary Surfaces",
+    ...(profile.primarySurfaces.length > 0
+      ? profile.primarySurfaces.map((item) => `- ${item}`)
+      : ["- No primary surfaces were detected automatically."]),
+    "",
+    "### Users and Operators",
+    ...profile.userPersonas.map((item) => `- ${item}`),
+    "",
+    "### Core Journeys",
+    ...profile.coreJourneys.map((item) => `- ${item}`),
+    "",
+    "### Success Signals",
+    ...profile.successSignals.map((item) => `- ${item}`),
+    "",
+    "### Product Guardrails",
+    "- Keep product intent stable across future features so agents do not optimize for the wrong user outcome.",
+    "- Refresh this managed section when scope, personas, operating model, or success metrics change materially.",
+    "<!-- cbx:product:foundation:end -->",
+    "",
+  ].join("\n");
+}
+
+function inferArchitectureDocProfile(snapshot, specRoots = []) {
+  const contract = inferArchitectureContractProfile(snapshot);
+  const architectureSignals = (snapshot.architectureByApp || []).map((item) => {
+    const label = item.rootPath === "." ? "repo root" : item.rootPath;
+    const signals =
+      item.architectureSignals && item.architectureSignals.length > 0
+        ? item.architectureSignals.join(", ")
+        : "not enough signals to classify";
+    return `${label}: ${signals}`;
+  });
+  const decisionAreas = [
+    "Module boundaries and dependency direction",
+    "Design-system ownership and reusable primitives",
+    "Testing and validation expectations by runtime boundary",
+  ];
+  if (specRoots.length > 0) {
+    decisionAreas.push(
+      `Active specs that may influence upcoming architecture work: ${specRoots.join(", ")}.`,
+    );
+  }
+
+  return {
+    style: contract.style,
+    designSystemSource: contract.designSystemSource,
+    moduleBoundaries: contract.moduleBoundaries,
+    architectureSignals,
+    decisionAreas,
+    scalingConstraints: contract.scalingConstraints,
+    testingStrategy: contract.testingStrategy,
+  };
+}
+
+function buildArchitectureDocSection(snapshot, specRoots = []) {
+  const profile = inferArchitectureDocProfile(snapshot, specRoots);
+  const hash = hashStableObject(profile);
+
+  return [
+    `<!-- cbx:architecture:doc:start version=1 profile=${hash} -->`,
+    "## Accepted Architecture Backbone (auto-managed)",
+    "",
+    "### System Overview",
+    `- Accepted style: ${profile.style}.`,
+    `- Design-system source of truth: ${profile.designSystemSource}`,
+    "",
+    "### Bounded Contexts and Module Boundaries",
+    ...(profile.moduleBoundaries.length > 0
+      ? profile.moduleBoundaries.map((item) => `- ${item}`)
+      : ["- No strong top-level module boundaries were detected automatically."]),
+    "",
+    "### Architecture Signals by Surface",
+    ...(profile.architectureSignals.length > 0
+      ? profile.architectureSignals.map((item) => `- ${item}`)
+      : ["- No app-level architecture signals were inferred from the repo scan."]),
+    "",
+    "### Decision Areas to Preserve",
+    ...profile.decisionAreas.map((item) => `- ${item}`),
+    "",
+    "### Scalability and Reliability Notes",
+    ...profile.scalingConstraints.map((item) => `- ${item}`),
+    "",
+    "### Testing and Operability",
+    ...profile.testingStrategy.map((item) => `- ${item}`),
+    "",
+    "### ADR Linkage",
+    "- Keep durable architecture decisions in `docs/adr/` and summarize the active decision set here.",
+    "",
+    "### Mermaid Diagram",
+    "```mermaid",
+    buildArchitectureDocMermaid(snapshot),
+    "```",
+    "<!-- cbx:architecture:doc:end -->",
+    "",
+  ].join("\n");
+}
+
+function buildEngineeringArchitectureSection(snapshot) {
+  const profile = inferArchitectureContractProfile(snapshot);
+  const hash = hashStableObject(profile);
+
+  return [
+    `<!-- cbx:architecture:rules:start version=1 profile=${hash} -->`,
+    "## 10) Architecture Contract (auto-managed)",
+    "",
+    `- Declared style: ${profile.style}.`,
+    `- Design-system source of truth: ${profile.designSystemSource}`,
+    "- Dependency direction rules:",
+    ...profile.dependencyRules.map((rule) => `  - ${rule}`),
+    "- Module and package boundaries to preserve:",
+    ...(profile.moduleBoundaries.length > 0
+      ? profile.moduleBoundaries.map((rule) => `  - ${rule}`)
+      : ["  - No strong module boundary was detected automatically; keep new boundaries explicit in specs and ADRs."]),
+    "- Testability expectations:",
+    ...profile.testingStrategy.map((rule) => `  - ${rule}`),
+    "- Doc refresh policy:",
+    "  - Update these managed sections when architecture, scale, boundaries, design-system rules, or testing strategy changes.",
+    "  - For non-trivial work, read PRODUCT.md, ENGINEERING_RULES.md, ARCHITECTURE.md, and TECH.md in that order when they exist.",
+    "<!-- cbx:architecture:rules:end -->",
+    "",
+  ].join("\n");
+}
+
+function buildArchitectureDocMermaid(snapshot) {
+  const topDirs = snapshot.topDirs.slice(0, 5);
+  const lines = [
+    "flowchart LR",
+    '  product["Product Intent"] --> rules["Engineering Rules"]',
+    '  product --> arch["Architecture Backbone"]',
+    '  arch --> tech["Current Tech Snapshot"]',
+  ];
+  if (topDirs.length > 0) {
+    for (let index = 0; index < topDirs.length; index += 1) {
+      const dir = topDirs[index];
+      const nodeName = `D${index}`;
+      lines.push(`  arch --> ${nodeName}["${dir}/"]`);
+    }
+  }
+  lines.push('  arch --> adr["docs/adr"]');
+  lines.push('  product --> specs["docs/specs"]');
+  return lines.join("\n");
+}
+
+function buildTechArchitectureSection(snapshot) {
+  const profile = inferArchitectureContractProfile(snapshot);
+  const payload = {
+    style: profile.style,
+    topDirs: snapshot.topDirs,
+    frameworks: snapshot.frameworks,
+    architectureByApp: snapshot.architectureByApp,
+  };
+  const hash = hashStableObject(payload);
+  const architectureSignals = profile.style
+    ? [`- Primary inferred style: ${profile.style}.`]
+    : [];
+
+  return [
+    `<!-- cbx:architecture:tech:start version=1 snapshot=${hash} -->`,
+    "## Architecture Snapshot (auto-managed)",
+    ...(architectureSignals.length > 0 ? ["", ...architectureSignals] : []),
+    ...(snapshot.architectureByApp.length > 0
+      ? [
+          "- App-level structure signals:",
+          ...snapshot.architectureByApp.slice(0, 6).map((item) => {
+            const label = item.rootPath === "." ? "repo root" : item.rootPath;
+            const signals =
+              item.architectureSignals.length > 0
+                ? item.architectureSignals.join(", ")
+                : "not enough signals to classify";
+            return `  - ${label}: ${signals}`;
+          }),
+        ]
+      : ["- No app-level architecture signals detected automatically."]),
+    "",
+    "### Module / App Topology",
+    ...(profile.moduleBoundaries.length > 0
+      ? profile.moduleBoundaries.map((item) => `- ${item}`)
+      : ["- No significant top-level module boundaries detected automatically."]),
+    "",
+    "### Flow Narratives",
+    "- Describe the primary request, data, and background-job flows here when architecture generation runs.",
+    "- Keep this section current when scale changes or new integration boundaries are introduced.",
+    "",
+    "### Mermaid Diagram",
+    "```mermaid",
+    buildArchitectureMermaid(snapshot),
+    "```",
+    "",
+    "### Scaling / Deployment / Testing Snapshot",
+    ...profile.scalingConstraints.map((item) => `- ${item}`),
+    "",
+    "### External Research Evidence",
+    "- Reserved for `cbx build architecture --research auto|always` when outside evidence informs the architecture notes.",
+    "<!-- cbx:architecture:tech:end -->",
+    "",
+  ].join("\n");
+}
+
+function buildRoadmapFoundationSection(snapshot, specRoots = []) {
+  const payload = {
+    topDirs: snapshot.topDirs,
+    frameworks: snapshot.frameworks,
+    specRoots,
+  };
+  const hash = hashStableObject(payload);
+  const nowItems = specRoots.length > 0
+    ? specRoots.map((item) => `Track active change planning in \`${item}\`.`)
+    : [
+        "No active spec packs detected. Create a spec pack before starting the next non-trivial feature or migration.",
+      ];
+  const nextItems = [];
+  if (snapshot.frameworks.length > 0) {
+    nextItems.push(
+      `Keep shared conventions stable across the current stack: ${snapshot.frameworks.join(", ")}.`,
+    );
+  }
+  if (snapshot.cicdSignals.length > 0) {
+    nextItems.push(
+      `Preserve release compatibility with the detected delivery surfaces: ${snapshot.cicdSignals.join(", ")}.`,
+    );
+  }
+  if (nextItems.length === 0) {
+    nextItems.push(
+      "Document the next scaling milestones here once product direction and architecture constraints are clearer.",
+    );
+  }
+
+  return [
+    `<!-- cbx:roadmap:foundation:start version=1 profile=${hash} -->`,
+    "## Delivery Backbone (auto-managed)",
+    "",
+    "### Now",
+    ...nowItems.map((item) => `- ${item}`),
+    "",
+    "### Next",
+    ...nextItems.map((item) => `- ${item}`),
+    "",
+    "### Later",
+    "- Use this section for medium-term scaling themes, major migrations, or cross-team architecture investments.",
+    "",
+    "### Backbone Maintenance",
+    "- Keep PRODUCT.md, ARCHITECTURE.md, ENGINEERING_RULES.md, and TECH.md aligned when direction or structure changes.",
+    "- Link major roadmap themes back to specs and ADRs instead of burying them in chat-only planning.",
+    "<!-- cbx:roadmap:foundation:end -->",
+    "",
+  ].join("\n");
+}
+
 function buildEngineeringRulesTemplate() {
   return [
     "# Engineering Rules",
@@ -1039,19 +1525,125 @@ function buildEngineeringRulesTemplate() {
     "",
     "- `TECH.md` is generated from current codebase reality.",
     "- Re-run `cbx rules tech-md --overwrite` after major stack or architecture changes.",
+    "",
+    "<!-- cbx:architecture:rules:start version=1 profile=bootstrap -->",
+    "## 10) Architecture Contract (auto-managed)",
+    "",
+    "- Declared style: bootstrap placeholder. Re-run `cbx build architecture --platform <codex|claude|gemini|copilot>` to refresh this contract from the repo.",
+    "- Design-system source of truth: bootstrap placeholder.",
+    "- Dependency direction rules:",
+    "  - Replace this placeholder with the managed architecture block when architecture generation runs.",
+    "- Module and package boundaries to preserve:",
+    "  - Replace this placeholder with the managed architecture block when architecture generation runs.",
+    "- Testability expectations:",
+    "  - Replace this placeholder with the managed architecture block when architecture generation runs.",
+    "- Doc refresh policy:",
+    "  - Update this section when architecture, scale, boundaries, design-system rules, or testing strategy changes.",
+    "<!-- cbx:architecture:rules:end -->",
     "<!-- cbx:engineering:rules:end -->",
     "",
   ].join("\n");
 }
 
+function buildProductTemplate(snapshot, specRoots = []) {
+  return [
+    "# Product",
+    "",
+    "This file is the durable product backbone for the project.",
+    "",
+    buildProductFoundationSection(snapshot, specRoots).trimEnd(),
+    "",
+  ].join("\n");
+}
+
+function buildArchitectureDocTemplate(snapshot, specRoots = []) {
+  return [
+    "# Architecture",
+    "",
+    "This file captures the accepted architecture backbone for the project.",
+    "",
+    buildArchitectureDocSection(snapshot, specRoots).trimEnd(),
+    "",
+  ].join("\n");
+}
+
+function buildRoadmapTemplate(snapshot, specRoots = []) {
+  return [
+    "# Roadmap",
+    "",
+    "This file captures the living delivery backbone for medium-term product and architecture work.",
+    "",
+    buildRoadmapFoundationSection(snapshot, specRoots).trimEnd(),
+    "",
+  ].join("\n");
+}
+
+function buildAdrReadme() {
+  return [
+    "# Architecture Decision Records",
+    "",
+    "Use this directory for durable decisions that future contributors and agents need to preserve.",
+    "",
+    "## When to add an ADR",
+    "",
+    "- Architecture style or boundary changes",
+    "- Data model or persistence strategy changes",
+    "- Deployment or scaling model changes",
+    "- Design-system ownership or shared UX pattern changes",
+    "",
+    "## Suggested format",
+    "",
+    "1. Context",
+    "2. Decision",
+    "3. Consequences",
+    "4. Validation",
+    "",
+    "Start with `0000-template.md` and create numbered follow-up ADRs for accepted decisions.",
+    "",
+  ].join("\n");
+}
+
+function buildAdrTemplate() {
+  return [
+    "# ADR 0000: Title",
+    "",
+    "## Status",
+    "",
+    "Proposed",
+    "",
+    "## Context",
+    "",
+    "- What problem or pressure led to this decision?",
+    "",
+    "## Decision",
+    "",
+    "- What is the chosen direction?",
+    "",
+    "## Consequences",
+    "",
+    "- What tradeoffs, benefits, or costs follow from this choice?",
+    "",
+    "## Validation",
+    "",
+    "- How will the team know this decision is working?",
+    "",
+  ].join("\n");
+}
+
 function buildEngineeringRulesManagedBlock({
   platform,
+  productFilePath,
+  architectureFilePath,
   engineeringRulesFilePath,
   techMdFilePath,
+  roadmapFilePath,
   ruleFilePath,
 }) {
+  const productRef = toPosixPath(path.resolve(productFilePath));
+  const architectureRef = toPosixPath(path.resolve(architectureFilePath));
   const engineeringRef = toPosixPath(path.resolve(engineeringRulesFilePath));
   const techRef = toPosixPath(path.resolve(techMdFilePath));
+  const roadmapRef = toPosixPath(path.resolve(roadmapFilePath));
   const ruleRef = toPosixPath(path.resolve(ruleFilePath));
 
   return [
@@ -1059,8 +1651,11 @@ function buildEngineeringRulesManagedBlock({
     "## Engineering Guardrails (auto-managed)",
     "Apply these before planning, coding, review, and release:",
     "",
+    `- Product backbone: \`${productRef}\``,
+    `- Accepted architecture: \`${architectureRef}\``,
     `- Required baseline: \`${engineeringRef}\``,
     `- Project tech map: \`${techRef}\``,
+    `- Delivery roadmap: \`${roadmapRef}\``,
     `- Active platform rule file: \`${ruleRef}\``,
     "",
     "Hard policy:",
@@ -1068,10 +1663,11 @@ function buildEngineeringRulesManagedBlock({
     "2. Keep architecture simple (KISS) and avoid speculative work (YAGNI).",
     "3. Apply SOLID pragmatically to reduce change risk, not add ceremony.",
     "4. Use clear naming with focused responsibilities and explicit boundaries.",
-    "5. Require validation evidence (lint/types/tests) before merge.",
-    "6. Use Decision Log response style.",
-    "7. Every Decision Log must include a `Skills Used` section listing skill, workflow, or agent names.",
-    "8. If no skill loaded, `Skills Used: none` is mandatory.",
+    "5. For non-trivial work, read PRODUCT.md, ENGINEERING_RULES.md, ARCHITECTURE.md, and TECH.md in that order when they exist before planning or implementation.",
+    "6. Require validation evidence (lint/types/tests) before merge.",
+    "7. Use Decision Log response style.",
+    "8. Every Decision Log must include a `Skills Used` section listing skill, workflow, or agent names.",
+    "9. If no skill loaded, `Skills Used: none` is mandatory.",
     "",
     "<!-- cbx:engineering:auto:end -->",
   ].join("\n");
@@ -1192,14 +1788,20 @@ async function upsertEngineeringRulesFile({
 async function upsertEngineeringRulesBlock({
   ruleFilePath,
   platform,
+  productFilePath,
+  architectureFilePath,
   engineeringRulesFilePath,
   techMdFilePath,
+  roadmapFilePath,
   dryRun = false,
 }) {
   const block = buildEngineeringRulesManagedBlock({
     platform,
+    productFilePath,
+    architectureFilePath,
     engineeringRulesFilePath,
     techMdFilePath,
+    roadmapFilePath,
     ruleFilePath,
   });
   const exists = await pathExists(ruleFilePath);
@@ -1254,40 +1856,227 @@ async function upsertEngineeringRulesBlock({
   };
 }
 
-function normalizeTechPackageName(value) {
-  if (value === undefined || value === null) return null;
-  const normalized = String(value)
-    .trim()
-    .replace(/^['"]|['"]$/g, "")
-    .toLowerCase();
-  return normalized || null;
+function extractTaggedMarkerAttribute(content, startPattern, key) {
+  const match = String(content || "").match(startPattern);
+  if (!match || !match[0]) return null;
+  const attributeMatch = match[0].match(new RegExp(`${key}=([^\\s>]+)`));
+  return attributeMatch?.[1] || null;
 }
 
-function parseTomlSections(content) {
-  const sections = new Map();
-  let currentSection = "";
-  sections.set(currentSection, []);
+async function upsertTaggedSectionInFile({
+  targetPath,
+  initialContent,
+  block,
+  startPattern,
+  endPattern,
+  dryRun = false,
+}) {
+  const exists = await pathExists(targetPath);
+  const original = exists ? await readFile(targetPath, "utf8") : initialContent;
+  const analysis = analyzeTaggedBlock(original, startPattern, endPattern);
+  let nextContent = original;
 
-  for (const line of content.split(/\r?\n/)) {
-    const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
-    if (sectionMatch) {
-      currentSection = sectionMatch[1].trim();
-      if (!sections.has(currentSection)) sections.set(currentSection, []);
-      continue;
-    }
-    sections.get(currentSection).push(line);
+  if (!exists || analysis.status === "absent") {
+    const trimmed = String(original || "").trimEnd();
+    nextContent =
+      trimmed.length > 0 ? `${trimmed}\n\n${block}\n` : `${block}\n`;
+  } else if (analysis.range) {
+    nextContent = `${original.slice(0, analysis.range.start)}${block}${original.slice(analysis.range.end)}`;
+  } else {
+    const trimmed = String(original || "").trimEnd();
+    nextContent =
+      trimmed.length > 0 ? `${trimmed}\n\n${block}\n` : `${block}\n`;
   }
 
-  return sections;
-}
+  if (nextContent === original) {
+    return {
+      action: "unchanged",
+      filePath: targetPath,
+    };
+  }
 
-function escapeTomlBasicString(value) {
-  return String(value ?? "")
-    .replace(/\\/g, "\\\\")
-    .replace(/"/g, '\\"');
-}
+  if (!dryRun) {
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, nextContent, "utf8");
+  }
 
-async function patchCodexPostmanHttpHeaders({
+  return {
+    action: exists
+      ? dryRun
+        ? "would-patch"
+        : "patched"
+      : dryRun
+        ? "would-create"
+        : "created",
+    filePath: targetPath,
+  };
+}
+
+function buildArchitectureBuildMetadata({
+  platform,
+  researchMode,
+  productProfileHash,
+  architectureDocHash,
+  rulesProfileHash,
+  techSnapshotHash,
+  roadmapProfileHash,
+}) {
+  return {
+    schemaVersion: 2,
+    generatedBy: "cbx build architecture",
+    generatedAt: new Date().toISOString(),
+    platform,
+    researchMode,
+    productProfileHash,
+    architectureDocHash,
+    rulesProfileHash,
+    techSnapshotHash,
+    roadmapProfileHash,
+  };
+}
+
+async function ensureArchitectureDocScaffold({
+  workspaceRoot,
+  snapshot,
+  specRoots = [],
+  overwrite = false,
+  dryRun = false,
+}) {
+  const productPath = path.join(workspaceRoot, "PRODUCT.md");
+  const architectureDocPath = path.join(workspaceRoot, "ARCHITECTURE.md");
+  const engineeringRulesPath = path.join(workspaceRoot, "ENGINEERING_RULES.md");
+  const techMdPath = path.join(workspaceRoot, "TECH.md");
+  const roadmapPath = path.join(workspaceRoot, "ROADMAP.md");
+  const adrDir = path.join(workspaceRoot, "docs", "adr");
+  const adrReadmePath = path.join(adrDir, "README.md");
+  const adrTemplatePath = path.join(adrDir, "0000-template.md");
+
+  const productResult = await upsertTaggedSectionInFile({
+    targetPath: productPath,
+    initialContent: `${buildProductTemplate(snapshot, specRoots)}\n`,
+    block: buildProductFoundationSection(snapshot, specRoots),
+    startPattern: PRODUCT_FOUNDATION_BLOCK_START_RE,
+    endPattern: PRODUCT_FOUNDATION_BLOCK_END_RE,
+    dryRun,
+  });
+
+  const architectureDocResult = await upsertTaggedSectionInFile({
+    targetPath: architectureDocPath,
+    initialContent: `${buildArchitectureDocTemplate(snapshot, specRoots)}\n`,
+    block: buildArchitectureDocSection(snapshot, specRoots),
+    startPattern: ARCHITECTURE_DOC_BLOCK_START_RE,
+    endPattern: ARCHITECTURE_DOC_BLOCK_END_RE,
+    dryRun,
+  });
+
+  const rulesTemplate = buildEngineeringRulesTemplate();
+  const rulesFileResult = await upsertEngineeringRulesFile({
+    targetPath: engineeringRulesPath,
+    template: rulesTemplate,
+    overwrite,
+    dryRun,
+  });
+  const rulesArchitectureResult = await upsertTaggedSectionInFile({
+    targetPath: engineeringRulesPath,
+    initialContent: `${rulesTemplate}\n`,
+    block: buildEngineeringArchitectureSection(snapshot),
+    startPattern: ENGINEERING_ARCHITECTURE_BLOCK_START_RE,
+    endPattern: ENGINEERING_ARCHITECTURE_BLOCK_END_RE,
+    dryRun,
+  });
+
+  const techContent = `${buildTechMd(snapshot)}\n`;
+  const techResult = await writeTextFile({
+    targetPath: techMdPath,
+    content: techContent,
+    overwrite,
+    dryRun,
+  });
+  const techArchitectureResult = await upsertTaggedSectionInFile({
+    targetPath: techMdPath,
+    initialContent: techContent,
+    block: buildTechArchitectureSection(snapshot),
+    startPattern: TECH_ARCHITECTURE_BLOCK_START_RE,
+    endPattern: TECH_ARCHITECTURE_BLOCK_END_RE,
+    dryRun,
+  });
+
+  const roadmapResult = await upsertTaggedSectionInFile({
+    targetPath: roadmapPath,
+    initialContent: `${buildRoadmapTemplate(snapshot, specRoots)}\n`,
+    block: buildRoadmapFoundationSection(snapshot, specRoots),
+    startPattern: ROADMAP_FOUNDATION_BLOCK_START_RE,
+    endPattern: ROADMAP_FOUNDATION_BLOCK_END_RE,
+    dryRun,
+  });
+
+  const adrReadmeResult = await writeTextFile({
+    targetPath: adrReadmePath,
+    content: `${buildAdrReadme()}\n`,
+    overwrite,
+    dryRun,
+  });
+  const adrTemplateResult = await writeTextFile({
+    targetPath: adrTemplatePath,
+    content: `${buildAdrTemplate()}\n`,
+    overwrite,
+    dryRun,
+  });
+
+  return {
+    productPath,
+    architectureDocPath,
+    engineeringRulesPath,
+    techMdPath,
+    roadmapPath,
+    adrReadmePath,
+    adrTemplatePath,
+    productResult,
+    architectureDocResult,
+    rulesFileResult,
+    rulesArchitectureResult,
+    techResult,
+    techArchitectureResult,
+    roadmapResult,
+    adrReadmeResult,
+    adrTemplateResult,
+  };
+}
+
+function normalizeTechPackageName(value) {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value)
+    .trim()
+    .replace(/^['"]|['"]$/g, "")
+    .toLowerCase();
+  return normalized || null;
+}
+
+function parseTomlSections(content) {
+  const sections = new Map();
+  let currentSection = "";
+  sections.set(currentSection, []);
+
+  for (const line of content.split(/\r?\n/)) {
+    const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1].trim();
+      if (!sections.has(currentSection)) sections.set(currentSection, []);
+      continue;
+    }
+    sections.get(currentSection).push(line);
+  }
+
+  return sections;
+}
+
+function escapeTomlBasicString(value) {
+  return String(value ?? "")
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"');
+}
+
+async function patchCodexPostmanHttpHeaders({
   configPath,
   mcpUrl,
   bearerToken,
@@ -2233,7 +3022,7 @@ function inferRecommendedSkills(snapshot) {
     hasFramework("Mongoose") ||
     hasFramework("SQLAlchemy")
   ) {
-    recommended.add("database-skills");
+    recommended.add("database-design");
   }
 
   if (recommended.size === 0) {
@@ -2564,6 +3353,9 @@ function buildTechMd(snapshot, { compact = false } = {}) {
   );
   lines.push("");
 
+  lines.push(buildTechArchitectureSection(snapshot).trimEnd());
+  lines.push("");
+
   if (!compact) {
     lines.push("## Package Signals");
     appendTechPackageSection(
@@ -8383,14 +9175,6 @@ async function performWorkflowInstall(
     dryRun,
     cwd,
   });
-  const engineeringArtifactsResult = await upsertEngineeringArtifacts({
-    platform,
-    scope: ruleScope,
-    overwrite: false,
-    dryRun,
-    skipTech: false,
-    cwd,
-  });
   const postmanSetupResult = await configurePostmanInstallArtifacts({
     platform,
     scope,
@@ -8436,7 +9220,7 @@ async function performWorkflowInstall(
     bundleId,
     installResult,
     syncResult,
-    engineeringArtifactsResult,
+    engineeringArtifactsResult: null,
     postmanSetupResult,
     terminalVerificationRuleResult,
   };
@@ -8466,10 +9250,7 @@ async function runWorkflowInstall(options) {
       dryRun: result.dryRun,
     });
     printRuleSyncResult(result.syncResult);
-    printInstallEngineeringSummary({
-      engineeringResults: result.engineeringArtifactsResult.engineeringResults,
-      techResult: result.engineeringArtifactsResult.techResult,
-    });
+    printInstallDocumentationNotice();
     printPostmanSetupSummary({
       postmanSetup: result.postmanSetupResult,
     });
@@ -11924,6 +12705,16 @@ function printInstallEngineeringSummary({ engineeringResults, techResult }) {
   }
 }
 
+function printInstallDocumentationNotice() {
+  console.log("\nProject backbone docs:");
+  console.log(
+    "- Install only wires the rule references and workflow assets.",
+  );
+  console.log(
+    "- Use `cbx rules init` to scaffold ENGINEERING_RULES.md and TECH.md, or `cbx build architecture --platform <codex|claude|gemini|copilot>` to generate PRODUCT.md, ARCHITECTURE.md, ENGINEERING_RULES.md, TECH.md, ROADMAP.md, and ADR scaffolds.",
+  );
+}
+
 async function upsertEngineeringArtifacts({
   platform,
   scope,
@@ -11937,7 +12728,14 @@ async function upsertEngineeringArtifacts({
     throw new Error(`No rule file configured for platform '${platform}'.`);
 
   const workspaceRoot = findWorkspaceRoot(cwd);
-  const techMdPath = path.join(workspaceRoot, "TECH.md");
+  const snapshot = await collectTechSnapshot(workspaceRoot);
+  const scaffold = await ensureArchitectureDocScaffold({
+    workspaceRoot,
+    snapshot,
+    specRoots: [],
+    overwrite,
+    dryRun,
+  });
   const targets = [{ ruleFilePath }];
 
   if (scope === "global") {
@@ -11957,46 +12755,32 @@ async function upsertEngineeringArtifacts({
     }
   }
 
-  const template = buildEngineeringRulesTemplate();
   const engineeringResults = [];
   for (const target of targets) {
-    const rulesFilePath = path.join(
-      path.dirname(target.ruleFilePath),
-      "ENGINEERING_RULES.md",
-    );
-    const rulesFileResult = await upsertEngineeringRulesFile({
-      targetPath: rulesFilePath,
-      template,
-      overwrite,
-      dryRun,
-    });
     const blockResult = await upsertEngineeringRulesBlock({
       ruleFilePath: target.ruleFilePath,
       platform,
-      engineeringRulesFilePath: rulesFilePath,
-      techMdFilePath: techMdPath,
+      productFilePath: scaffold.productPath,
+      architectureFilePath: scaffold.architectureDocPath,
+      engineeringRulesFilePath: scaffold.engineeringRulesPath,
+      techMdFilePath: scaffold.techMdPath,
+      roadmapFilePath: scaffold.roadmapPath,
       dryRun,
     });
     engineeringResults.push({
       ruleFilePath: target.ruleFilePath,
-      rulesFilePath,
-      rulesFileResult,
+      rulesFilePath: scaffold.engineeringRulesPath,
+      rulesFileResult: scaffold.rulesArchitectureResult.action === "unchanged"
+        ? scaffold.rulesFileResult
+        : scaffold.rulesArchitectureResult,
       blockResult,
     });
   }
 
   let techResult = null;
   if (!skipTech) {
-    const snapshot = await collectTechSnapshot(workspaceRoot);
-    const content = buildTechMd(snapshot);
-    const fileResult = await writeTextFile({
-      targetPath: techMdPath,
-      content: `${content}\n`,
-      overwrite,
-      dryRun,
-    });
     techResult = {
-      ...fileResult,
+      ...scaffold.techArchitectureResult,
       snapshot,
     };
   }
@@ -12081,6 +12865,839 @@ async function runRulesTechMd(options) {
   }
 }
 
+function normalizeArchitectureBuildPlatform(value) {
+  const normalized = normalizePlatform(value);
+  if (!normalized || !ARCHITECTURE_BUILD_PLATFORMS.has(normalized)) {
+    throw new Error(
+      "Architecture build platform must be one of: codex, claude, gemini, copilot.",
+    );
+  }
+  return normalized;
+}
+
+function normalizeArchitectureResearchMode(value) {
+  const normalized = String(value || "auto")
+    .trim()
+    .toLowerCase();
+  if (!["auto", "always", "never"].includes(normalized)) {
+    throw new Error("Research mode must be one of: auto, always, never.");
+  }
+  return normalized;
+}
+
+async function listSpecPackRoots(workspaceRoot) {
+  const specsRoot = path.join(workspaceRoot, "docs", "specs");
+  if (!(await pathExists(specsRoot))) return [];
+  const entries = await readdir(specsRoot, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => `docs/specs/${entry.name}`)
+    .sort((a, b) => a.localeCompare(b))
+    .slice(0, 8);
+}
+
+function resolveArchitectureConditionalSkills(snapshot, specRoots, researchMode) {
+  const conditional = [];
+  const frameworks = new Set(snapshot.frameworks || []);
+  const topDirs = new Set(snapshot.topDirs || []);
+  const jsPackages = new Set(snapshot.packageSignals?.javascript || []);
+
+  if (
+    snapshot.isMcpServer ||
+    frameworks.has("Next.js") ||
+    frameworks.has("NestJS") ||
+    frameworks.has("FastAPI") ||
+    topDirs.has("api") ||
+    topDirs.has("routes") ||
+    topDirs.has("controllers")
+  ) {
+    conditional.push("api-design");
+  }
+
+  if (
+    topDirs.has("db") ||
+    topDirs.has("database") ||
+    topDirs.has("migrations") ||
+    jsPackages.has("prisma") ||
+    jsPackages.has("drizzle-orm") ||
+    frameworks.has("SQLAlchemy")
+  ) {
+    conditional.push("database-design");
+  }
+
+  if (specRoots.length > 0) {
+    conditional.push("sadd");
+  }
+
+  if (researchMode === "always") {
+    conditional.push("deep-research");
+  } else if (
+    researchMode === "auto" &&
+    !snapshot.readmeExcerpt &&
+    snapshot.architectureByApp.every(
+      (item) => (item.architectureSignals || []).length === 0,
+    )
+  ) {
+    conditional.push("deep-research");
+  }
+
+  return [...new Set(conditional)];
+}
+
+async function resolveArchitectureSkillPathHints(platform, cwd, skillIds) {
+  const profilePaths = await resolveProfilePaths(platform, "project", cwd);
+  const skillsDir = profilePaths.skillsDir;
+  if (!skillsDir) return [];
+  return skillIds
+    .map((skillId) => path.join(skillsDir, skillId, "SKILL.md"))
+    .map((filePath) => toPosixPath(path.relative(findWorkspaceRoot(cwd), filePath)));
+}
+
+function buildArchitecturePrompt({
+  platform,
+  workspaceRoot,
+  snapshot,
+  specRoots,
+  researchMode,
+  coreSkills,
+  conditionalSkills,
+  skillPathHints,
+}) {
+  const productPath = "PRODUCT.md";
+  const architecturePath = "ARCHITECTURE.md";
+  const rulesPath = "ENGINEERING_RULES.md";
+  const techPath = "TECH.md";
+  const roadmapPath = "ROADMAP.md";
+  const adrReadmePath = "docs/adr/README.md";
+  const architectureSignals = snapshot.architectureByApp
+    .filter((item) => (item.architectureSignals || []).length > 0)
+    .map((item) => {
+      const label = item.rootPath === "." ? "repo root" : item.rootPath;
+      return `${label}: ${item.architectureSignals.join(", ")}`;
+    });
+
+  return [
+    `You are running inside ${platform}.`,
+    "",
+    "Objective:",
+    `- Inspect the repository at ${toPosixPath(workspaceRoot)} and refresh the scalable project backbone in ${productPath}, ${architecturePath}, ${rulesPath}, ${techPath}, and ${roadmapPath}.`,
+    "- Keep PRODUCT.md focused on intent, ARCHITECTURE.md on accepted structure, ENGINEERING_RULES.md on normative rules, TECH.md on current-state evidence, and ROADMAP.md on delivery themes.",
+    "- Preserve manual content outside the managed `cbx:*` markers.",
+    "",
+    "Required skill bundle:",
+    `- Load these exact skill IDs first: ${coreSkills.map((skillId) => `\`${skillId}\``).join(", ")}`,
+    conditionalSkills.length > 0
+      ? `- Additional skills to load now: ${conditionalSkills.map((skillId) => `\`${skillId}\``).join(", ")}`
+      : "- Conditional skills to load now: none",
+    skillPathHints.length > 0
+      ? `- Local skill file hints if installed: ${skillPathHints.map((hint) => `\`${hint}\``).join(", ")}`
+      : "- Local skill file hints if installed: none detected",
+    "- Treat the route and skill bundle as already resolved. Do not begin with route discovery.",
+    "",
+    "Repository context:",
+    `- Frameworks: ${snapshot.frameworks.length > 0 ? snapshot.frameworks.join(", ") : "none detected"}`,
+    `- Top directories: ${snapshot.topDirs.length > 0 ? snapshot.topDirs.join(", ") : "none detected"}`,
+    `- Existing spec packs: ${specRoots.length > 0 ? specRoots.join(", ") : "none detected"}`,
+    architectureSignals.length > 0
+      ? `- Architecture signals: ${architectureSignals.join(" | ")}`
+      : "- Architecture signals: none confidently inferred from the repo scan",
+    "",
+    "Execution contract:",
+    `1. Read ${productPath}, ${rulesPath}, ${architecturePath}, and ${techPath} in that order when they exist.`,
+    "2. Inspect the repo before making architecture claims.",
+    "3. Update only the content between the existing managed markers in the backbone docs and preserve the marker lines themselves, including their hash metadata.",
+    "4. In PRODUCT.md, state product scope, primary surfaces, users or operators, core journeys, success signals, and product guardrails.",
+    "5. In ARCHITECTURE.md, state accepted architecture style, bounded contexts, stable decision areas, ADR linkage, and add at least one Mermaid architecture diagram if the repo is non-trivial.",
+    "6. In ENGINEERING_RULES.md, state architecture style, dependency rules, feature or module structure rules, design-system source of truth, testability expectations, and doc refresh policy.",
+    "7. In TECH.md, update architecture snapshot, module or app topology, flow narratives, Mermaid diagrams, and scaling or deployment notes.",
+    "8. In ROADMAP.md, capture current delivery themes, active spec-driven work, and major architecture follow-ups without turning it into a speculative wishlist.",
+    researchMode === "never"
+      ? "9. Stay repo-only. Do not use outside research."
+      : "9. Use repo evidence first. Use official docs when needed. Treat Reddit or community sources only as labeled secondary evidence.",
+    researchMode === "always"
+      ? "10. Include an external research evidence subsection in TECH.md with clearly labeled primary and secondary evidence."
+      : "10. Include external research notes only if they materially informed the architecture update.",
+    "11. If the project clearly follows Clean Architecture, feature-first modules, or another stable structure, make that explicit so future implementation stays consistent.",
+    `12. Ensure ${adrReadmePath} exists as the ADR entrypoint and mention ADR follow-up when the repo lacks decision history.`,
+    "",
+    "Return one JSON object on the last line with this shape:",
+    '{"files_written":["PRODUCT.md","ARCHITECTURE.md","ENGINEERING_RULES.md","TECH.md","ROADMAP.md","docs/adr/README.md"],"research_used":false,"gaps":[],"next_actions":[]}',
+    "",
+    "Do not emit placeholder TODOs in the managed sections.",
+  ].join("\n");
+}
+
+async function execFileCapture(command, args, options = {}) {
+  try {
+    const result = await execFile(command, args, {
+      ...options,
+      maxBuffer: 8 * 1024 * 1024,
+    });
+    return {
+      ok: true,
+      stdout: result.stdout || "",
+      stderr: result.stderr || "",
+    };
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(`Required CLI '${command}' is not installed or not on PATH.`);
+    }
+    return {
+      ok: false,
+      stdout: error?.stdout || "",
+      stderr: error?.stderr || "",
+      code: error?.code || 1,
+    };
+  }
+}
+
+async function spawnCapture(command, args, options = {}) {
+  const { cwd, env, streamOutput = false } = options;
+  return await new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    child.stdout.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdout += text;
+      if (streamOutput) process.stdout.write(text);
+    });
+
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderr += text;
+      if (streamOutput) process.stderr.write(text);
+    });
+
+    child.on("error", (error) => {
+      if (error?.code === "ENOENT") {
+        reject(
+          new Error(`Required CLI '${command}' is not installed or not on PATH.`),
+        );
+        return;
+      }
+      reject(error);
+    });
+
+    child.on("close", (code) => {
+      resolve({
+        ok: code === 0,
+        stdout,
+        stderr,
+        code: code ?? 1,
+      });
+    });
+  });
+}
+
+function explainArchitectureBuildFailure(platform, execution) {
+  const combined = String(
+    `${execution.stderr || ""}\n${execution.stdout || ""}`.trim(),
+  );
+  const notes = [];
+
+  if (platform === "gemini") {
+    if (
+      combined.includes("Error during discovery for MCP server") ||
+      combined.includes("[MCP error]")
+    ) {
+      notes.push(
+        "Gemini CLI is failing while loading MCP servers from your Gemini settings. Start the required MCP runtime(s) first or disable the broken server entries in `.gemini/settings.json` before retrying.",
+      );
+    }
+    if (
+      combined.includes("cloudaicompanion.companions.generateChat") ||
+      combined.includes("PERMISSION_DENIED") ||
+      combined.includes("403")
+    ) {
+      notes.push(
+        "Gemini CLI reached Google auth, but the active account or project cannot generate chat content. Re-authenticate Gemini CLI with a permitted account or configure a supported Gemini API credential and project before retrying.",
+      );
+    }
+  }
+
+  if (platform === "claude" && combined.includes("permission")) {
+    notes.push(
+      "Claude CLI appears to be blocked by its own permission model. Re-run in a Claude environment that allows non-interactive edits for this workspace.",
+    );
+  }
+
+  if (notes.length === 0) {
+    return `Architecture build failed via ${platform}. ${combined}`.trim();
+  }
+
+  return [
+    `Architecture build failed via ${platform}.`,
+    ...notes.map((note) => `- ${note}`),
+    combined ? `Raw CLI output:\n${combined}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+async function probeArchitectureAdapter(platform, cwd) {
+  if (platform === "codex") {
+    const help = await execFileCapture("codex", ["exec", "--help"], { cwd });
+    return {
+      platform,
+      binary: "codex",
+      helpText: `${help.stdout}\n${help.stderr}`.trim(),
+      buildInvocation(prompt) {
+        const args = ["exec"];
+        if (this.helpText.includes("--skip-git-repo-check")) {
+          args.push("--skip-git-repo-check");
+        }
+        args.push(prompt);
+        return args;
+      },
+    };
+  }
+
+  if (platform === "claude") {
+    const help = await execFileCapture("claude", ["--help"], { cwd });
+    const helpText = `${help.stdout}\n${help.stderr}`.trim();
+    const printFlag = helpText.includes("--print")
+      ? "--print"
+      : helpText.includes(" -p") || helpText.includes("\n-p")
+        ? "-p"
+        : null;
+    if (!printFlag) {
+      throw new Error(
+        "Claude CLI was found, but no headless print mode was detected. Install a Claude Code build that supports --print or -p.",
+      );
+    }
+    return {
+      platform,
+      binary: "claude",
+      helpText,
+      buildInvocation(prompt) {
+        return [printFlag, prompt];
+      },
+    };
+  }
+
+  if (platform === "gemini") {
+    const help = await execFileCapture("gemini", ["--help"], { cwd });
+    const helpText = `${help.stdout}\n${help.stderr}`.trim();
+    const promptFlag = helpText.includes("--prompt")
+      ? "--prompt"
+      : helpText.includes(" -p") || helpText.includes("\n-p")
+        ? "-p"
+        : null;
+    if (!promptFlag) {
+      throw new Error(
+        "Gemini CLI was found, but no prompt flag was detected. Install a Gemini CLI build with --prompt or -p support.",
+      );
+    }
+    return {
+      platform,
+      binary: "gemini",
+      helpText,
+      buildInvocation(prompt) {
+        return [promptFlag, prompt];
+      },
+    };
+  }
+
+  const help = await execFileCapture("copilot", ["--help"], { cwd });
+  const helpText = `${help.stdout}\n${help.stderr}`.trim();
+  const supportsPrompt = helpText.includes("--prompt");
+  const supportsChatPrompt =
+    helpText.includes("chat") && helpText.includes("--prompt");
+  if (!supportsPrompt && !supportsChatPrompt) {
+    throw new Error(
+      "Copilot CLI was found, but no headless prompt mode was detected. This command requires a native Copilot CLI surface with --prompt support.",
+    );
+  }
+  return {
+    platform,
+    binary: "copilot",
+    helpText,
+    buildInvocation(prompt) {
+      if (supportsPrompt) return ["--prompt", prompt];
+      return ["chat", "--prompt", prompt];
+    },
+  };
+}
+
+function normalizeArchitectureResult({
+  stdout,
+  workspaceRoot,
+  researchMode,
+  changedFiles = [],
+}) {
+  const trimmed = String(stdout || "").trim();
+  if (trimmed) {
+    const lastLine = trimmed.split(/\r?\n/).pop();
+    if (lastLine && lastLine.startsWith("{") && lastLine.endsWith("}")) {
+      try {
+        const parsed = JSON.parse(lastLine);
+        return {
+          outputRoot: workspaceRoot,
+          filesWritten:
+            changedFiles.length > 0
+              ? changedFiles
+              : Array.isArray(parsed.files_written)
+                ? parsed.files_written
+                : [],
+          researchUsed:
+            typeof parsed.research_used === "boolean"
+              ? parsed.research_used
+              : researchMode === "always",
+          gaps: Array.isArray(parsed.gaps) ? parsed.gaps : [],
+          nextActions: Array.isArray(parsed.next_actions)
+            ? parsed.next_actions
+            : [],
+          rawOutput: trimmed,
+        };
+      } catch {
+        // fall through to default normalization
+      }
+    }
+  }
+
+  return {
+    outputRoot: workspaceRoot,
+    filesWritten: changedFiles,
+    researchUsed: researchMode === "always",
+    gaps: [],
+    nextActions: [],
+    rawOutput: trimmed,
+  };
+}
+
+async function captureFileContents(filePaths) {
+  const snapshot = {};
+  for (const filePath of filePaths) {
+    if (await pathExists(filePath)) {
+      snapshot[filePath] = await readFile(filePath, "utf8");
+    } else {
+      snapshot[filePath] = null;
+    }
+  }
+  return snapshot;
+}
+
+async function readArchitectureDriftStatus(workspaceRoot, snapshot) {
+  const specRoots = await listSpecPackRoots(workspaceRoot);
+  const productPath = path.join(workspaceRoot, "PRODUCT.md");
+  const architecturePath = path.join(workspaceRoot, "ARCHITECTURE.md");
+  const rulesPath = path.join(workspaceRoot, "ENGINEERING_RULES.md");
+  const techPath = path.join(workspaceRoot, "TECH.md");
+  const roadmapPath = path.join(workspaceRoot, "ROADMAP.md");
+  const adrReadmePath = path.join(workspaceRoot, "docs", "adr", "README.md");
+  const metadataPath = path.join(
+    workspaceRoot,
+    ".cbx",
+    ARCHITECTURE_BUILD_METADATA_FILENAME,
+  );
+  const productExists = await pathExists(productPath);
+  const architectureExists = await pathExists(architecturePath);
+  const rulesExists = await pathExists(rulesPath);
+  const techExists = await pathExists(techPath);
+  const roadmapExists = await pathExists(roadmapPath);
+  const adrReadmeExists = await pathExists(adrReadmePath);
+
+  const expectedProductHash = hashStableObject(
+    inferProductFoundationProfile(snapshot, specRoots),
+  );
+  const expectedArchitectureHash = hashStableObject(
+    inferArchitectureDocProfile(snapshot, specRoots),
+  );
+  const expectedRulesHash = hashStableObject(
+    inferArchitectureContractProfile(snapshot),
+  );
+  const expectedTechHash = hashStableObject({
+    style: inferArchitectureContractProfile(snapshot).style,
+    topDirs: snapshot.topDirs,
+    frameworks: snapshot.frameworks,
+    architectureByApp: snapshot.architectureByApp,
+  });
+  const expectedRoadmapHash = hashStableObject({
+    topDirs: snapshot.topDirs,
+    frameworks: snapshot.frameworks,
+    specRoots,
+  });
+
+  const findings = [];
+  let actualProductHash = null;
+  let actualArchitectureHash = null;
+  let actualRulesHash = null;
+  let actualTechHash = null;
+  let actualRoadmapHash = null;
+
+  if (!productExists) {
+    findings.push("PRODUCT.md is missing.");
+  } else {
+    const content = await readFile(productPath, "utf8");
+    actualProductHash = extractTaggedMarkerAttribute(
+      content,
+      PRODUCT_FOUNDATION_BLOCK_START_RE,
+      "profile",
+    );
+    if (!actualProductHash) {
+      findings.push("PRODUCT.md is missing the managed product foundation block.");
+    } else if (actualProductHash !== expectedProductHash) {
+      findings.push(
+        `PRODUCT.md foundation is stale (expected ${expectedProductHash}, found ${actualProductHash}).`,
+      );
+    }
+  }
+
+  if (!architectureExists) {
+    findings.push("ARCHITECTURE.md is missing.");
+  } else {
+    const content = await readFile(architecturePath, "utf8");
+    actualArchitectureHash = extractTaggedMarkerAttribute(
+      content,
+      ARCHITECTURE_DOC_BLOCK_START_RE,
+      "profile",
+    );
+    if (!actualArchitectureHash) {
+      findings.push("ARCHITECTURE.md is missing the managed architecture backbone block.");
+    } else if (actualArchitectureHash !== expectedArchitectureHash) {
+      findings.push(
+        `ARCHITECTURE.md backbone is stale (expected ${expectedArchitectureHash}, found ${actualArchitectureHash}).`,
+      );
+    }
+  }
+
+  if (!rulesExists) {
+    findings.push("ENGINEERING_RULES.md is missing.");
+  } else {
+    const content = await readFile(rulesPath, "utf8");
+    actualRulesHash = extractTaggedMarkerAttribute(
+      content,
+      ENGINEERING_ARCHITECTURE_BLOCK_START_RE,
+      "profile",
+    );
+    if (!actualRulesHash) {
+      findings.push("ENGINEERING_RULES.md is missing the managed architecture contract block.");
+    } else if (actualRulesHash !== expectedRulesHash) {
+      findings.push(
+        `ENGINEERING_RULES.md architecture profile is stale (expected ${expectedRulesHash}, found ${actualRulesHash}).`,
+      );
+    }
+  }
+
+  if (!techExists) {
+    findings.push("TECH.md is missing.");
+  } else {
+    const content = await readFile(techPath, "utf8");
+    actualTechHash = extractTaggedMarkerAttribute(
+      content,
+      TECH_ARCHITECTURE_BLOCK_START_RE,
+      "snapshot",
+    );
+    if (!actualTechHash) {
+      findings.push("TECH.md is missing the managed architecture snapshot block.");
+    } else if (actualTechHash !== expectedTechHash) {
+      findings.push(
+        `TECH.md architecture snapshot is stale (expected ${expectedTechHash}, found ${actualTechHash}).`,
+      );
+    }
+  }
+
+  if (!roadmapExists) {
+    findings.push("ROADMAP.md is missing.");
+  } else {
+    const content = await readFile(roadmapPath, "utf8");
+    actualRoadmapHash = extractTaggedMarkerAttribute(
+      content,
+      ROADMAP_FOUNDATION_BLOCK_START_RE,
+      "profile",
+    );
+    if (!actualRoadmapHash) {
+      findings.push("ROADMAP.md is missing the managed roadmap foundation block.");
+    } else if (actualRoadmapHash !== expectedRoadmapHash) {
+      findings.push(
+        `ROADMAP.md backbone is stale (expected ${expectedRoadmapHash}, found ${actualRoadmapHash}).`,
+      );
+    }
+  }
+
+  if (!adrReadmeExists) {
+    findings.push("docs/adr/README.md is missing.");
+  }
+
+  const metadata = await readJsonFileIfExists(metadataPath);
+  if (!metadata.exists) {
+    findings.push("Architecture build metadata is missing.");
+  }
+
+  return {
+    stale: findings.length > 0,
+    findings,
+    productPath,
+    architecturePath,
+    rulesPath,
+    techPath,
+    roadmapPath,
+    adrReadmePath,
+    metadataPath,
+    expectedProductHash,
+    expectedArchitectureHash,
+    expectedRulesHash,
+    expectedTechHash,
+    expectedRoadmapHash,
+    actualProductHash,
+    actualArchitectureHash,
+    actualRulesHash,
+    actualTechHash,
+    actualRoadmapHash,
+  };
+}
+
+async function runBuildArchitecture(options) {
+  try {
+    const platform = normalizeArchitectureBuildPlatform(options.platform);
+    const researchMode = normalizeArchitectureResearchMode(options.research);
+    const overwrite = Boolean(options.overwrite);
+    const dryRun = Boolean(options.dryRun);
+    const emitJson = Boolean(options.json);
+    const checkOnly = Boolean(options.check);
+    const cwd = process.cwd();
+    const workspaceRoot = findWorkspaceRoot(cwd);
+    const snapshot = await collectTechSnapshot(workspaceRoot);
+    const specRoots = await listSpecPackRoots(workspaceRoot);
+
+    if (checkOnly) {
+      const drift = await readArchitectureDriftStatus(workspaceRoot, snapshot);
+      if (emitJson) {
+        console.log(JSON.stringify(drift, null, 2));
+      } else {
+        console.log(`Platform: ${platform}`);
+        console.log(`Workspace: ${toPosixPath(workspaceRoot)}`);
+        console.log(`Status: ${drift.stale ? "stale" : "fresh"}`);
+        console.log(
+          "Backbone docs: PRODUCT.md, ARCHITECTURE.md, ENGINEERING_RULES.md, TECH.md, ROADMAP.md, docs/adr/README.md",
+        );
+        if (drift.findings.length > 0) {
+          console.log("Findings:");
+          for (const finding of drift.findings) {
+            console.log(`- ${finding}`);
+          }
+        }
+      }
+      if (drift.stale) process.exit(1);
+      return;
+    }
+
+    const managedFilePaths = [
+      path.join(workspaceRoot, "PRODUCT.md"),
+      path.join(workspaceRoot, "ARCHITECTURE.md"),
+      path.join(workspaceRoot, "ENGINEERING_RULES.md"),
+      path.join(workspaceRoot, "TECH.md"),
+      path.join(workspaceRoot, "ROADMAP.md"),
+      path.join(workspaceRoot, "docs", "adr", "README.md"),
+      path.join(workspaceRoot, "docs", "adr", "0000-template.md"),
+    ];
+    const filesBefore = dryRun
+      ? Object.fromEntries(managedFilePaths.map((filePath) => [filePath, null]))
+      : await captureFileContents(managedFilePaths);
+
+    const scaffold = await ensureArchitectureDocScaffold({
+      workspaceRoot,
+      snapshot,
+      specRoots,
+      overwrite,
+      dryRun,
+    });
+    const coreSkills = [
+      "architecture-doc",
+      "system-design",
+      "tech-doc",
+      "frontend-design",
+    ];
+    const conditionalSkills = resolveArchitectureConditionalSkills(
+      snapshot,
+      specRoots,
+      researchMode,
+    );
+    const skillBundle = [...coreSkills, ...conditionalSkills];
+    const skillPathHints = await resolveArchitectureSkillPathHints(
+      platform,
+      cwd,
+      skillBundle,
+    );
+    const prompt = buildArchitecturePrompt({
+      platform,
+      workspaceRoot,
+      snapshot,
+      specRoots,
+      researchMode,
+      coreSkills,
+      conditionalSkills,
+      skillPathHints,
+    });
+    const adapter = await probeArchitectureAdapter(platform, workspaceRoot);
+    const args = adapter.buildInvocation(prompt);
+
+    if (dryRun) {
+      const summary = {
+        platform,
+        workspaceRoot: toPosixPath(workspaceRoot),
+        adapter: adapter.binary,
+        invocation: [adapter.binary, ...args],
+        researchMode,
+        managedTargets: [
+          toPosixPath(scaffold.productPath),
+          toPosixPath(scaffold.architectureDocPath),
+          toPosixPath(scaffold.engineeringRulesPath),
+          toPosixPath(scaffold.techMdPath),
+          toPosixPath(scaffold.roadmapPath),
+          toPosixPath(scaffold.adrReadmePath),
+          toPosixPath(scaffold.adrTemplatePath),
+        ],
+        skillBundle,
+      };
+      if (emitJson) {
+        console.log(JSON.stringify(summary, null, 2));
+      } else {
+        console.log(`Platform: ${platform}`);
+        console.log(`Workspace: ${toPosixPath(workspaceRoot)}`);
+        console.log(`Adapter: ${adapter.binary}`);
+        console.log(`Research mode: ${researchMode}`);
+        console.log(
+          `Managed targets: ${toPosixPath(scaffold.engineeringRulesPath)}, ${toPosixPath(scaffold.techMdPath)}`,
+        );
+        console.log(`Skill bundle: ${skillBundle.join(", ")}`);
+        console.log(`Invocation: ${[adapter.binary, ...args].join(" ")}`);
+      }
+      return;
+    }
+
+    if (!emitJson) {
+      console.log(`Streaming ${adapter.binary} output...`);
+    }
+
+    const execution = await spawnCapture(adapter.binary, args, {
+      cwd: workspaceRoot,
+      env: process.env,
+      streamOutput: !emitJson,
+    });
+    if (!execution.ok) {
+      throw new Error(explainArchitectureBuildFailure(platform, execution));
+    }
+
+    const filesAfter = await captureFileContents(managedFilePaths);
+    const changedFiles = managedFilePaths
+      .filter((filePath) => filesBefore[filePath] !== filesAfter[filePath])
+      .map((filePath) => toPosixPath(path.relative(workspaceRoot, filePath)));
+
+    const rulesContent =
+      filesAfter[scaffold.engineeringRulesPath] ??
+      (await readFile(scaffold.engineeringRulesPath, "utf8"));
+    const techContent =
+      filesAfter[scaffold.techMdPath] ?? (await readFile(scaffold.techMdPath, "utf8"));
+    const productContent =
+      filesAfter[scaffold.productPath] ?? (await readFile(scaffold.productPath, "utf8"));
+    const architectureContent =
+      filesAfter[scaffold.architectureDocPath] ??
+      (await readFile(scaffold.architectureDocPath, "utf8"));
+    const roadmapContent =
+      filesAfter[scaffold.roadmapPath] ?? (await readFile(scaffold.roadmapPath, "utf8"));
+
+    const metadataPath = path.join(
+      workspaceRoot,
+      ".cbx",
+      ARCHITECTURE_BUILD_METADATA_FILENAME,
+    );
+    const metadata = buildArchitectureBuildMetadata({
+      platform,
+      researchMode,
+      productProfileHash:
+        extractTaggedMarkerAttribute(
+          productContent,
+          PRODUCT_FOUNDATION_BLOCK_START_RE,
+          "profile",
+        ) || "unknown",
+      architectureDocHash:
+        extractTaggedMarkerAttribute(
+          architectureContent,
+          ARCHITECTURE_DOC_BLOCK_START_RE,
+          "profile",
+        ) || "unknown",
+      rulesProfileHash:
+        extractTaggedMarkerAttribute(
+          rulesContent,
+          ENGINEERING_ARCHITECTURE_BLOCK_START_RE,
+          "profile",
+        ) || "unknown",
+      techSnapshotHash:
+        extractTaggedMarkerAttribute(
+          techContent,
+          TECH_ARCHITECTURE_BLOCK_START_RE,
+          "snapshot",
+        ) || "unknown",
+      roadmapProfileHash:
+        extractTaggedMarkerAttribute(
+          roadmapContent,
+          ROADMAP_FOUNDATION_BLOCK_START_RE,
+          "profile",
+        ) || "unknown",
+    });
+    await mkdir(path.dirname(metadataPath), { recursive: true });
+    await writeFile(
+      metadataPath,
+      `${JSON.stringify(metadata, null, 2)}\n`,
+      "utf8",
+    );
+
+    const result = normalizeArchitectureResult({
+      stdout: execution.stdout,
+      workspaceRoot: toPosixPath(workspaceRoot),
+      researchMode,
+      changedFiles: [...new Set(changedFiles)],
+    });
+
+    if (emitJson) {
+      console.log(
+        JSON.stringify(
+          {
+            platform,
+            adapter: adapter.binary,
+            skillBundle,
+            result,
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    console.log(`Platform: ${platform}`);
+    console.log(`Adapter: ${adapter.binary}`);
+    console.log(`Workspace: ${toPosixPath(workspaceRoot)}`);
+    console.log(
+      "Managed docs: PRODUCT.md, ARCHITECTURE.md, ENGINEERING_RULES.md, TECH.md, ROADMAP.md",
+    );
+    console.log(
+      "ADR scaffold: docs/adr/README.md, docs/adr/0000-template.md",
+    );
+    console.log(`Skill bundle: ${skillBundle.join(", ")}`);
+    console.log(
+      `Files written: ${(result.filesWritten || []).join(", ") || "(none reported)"}`,
+    );
+    console.log(`Research used: ${result.researchUsed ? "yes" : "no"}`);
+    if (result.gaps.length > 0) {
+      console.log(`Gaps: ${result.gaps.join("; ")}`);
+    }
+    if (result.nextActions.length > 0) {
+      console.log(`Next actions: ${result.nextActions.join("; ")}`);
+    }
+  } catch (error) {
+    console.error(`\nError: ${error.message}`);
+    process.exit(1);
+  }
+}
+
 function parseCsvOption(value) {
   return String(value || "")
     .split(",")
@@ -12342,11 +13959,7 @@ async function runInitWizard(options) {
           dryRun: installOutcome.dryRun,
         });
         printRuleSyncResult(installOutcome.syncResult);
-        printInstallEngineeringSummary({
-          engineeringResults:
-            installOutcome.engineeringArtifactsResult.engineeringResults,
-          techResult: installOutcome.engineeringArtifactsResult.techResult,
-        });
+        printInstallDocumentationNotice();
         printPostmanSetupSummary({
           postmanSetup: installOutcome.postmanSetupResult,
         });
@@ -12467,6 +14080,7 @@ export function buildCliProgram() {
     defaultMcpDockerContainerName: DEFAULT_MCP_DOCKER_CONTAINER_NAME,
     runRulesInit,
     runRulesTechMd,
+    runBuildArchitecture,
   });
 }