@cubis/foundry 0.3.77 → 0.3.79

package/dist/cli/core.js

@@ -3,6 +3,7 @@ import { confirm, input, select } from "@inquirer/prompts";
 import { parse as parseJsonc } from "jsonc-parser";
 import { existsSync } from "node:fs";
 import { chmod, cp, mkdir, readdir, readFile, rm, stat, 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";
@@ -24,6 +25,16 @@ const ENGINEERING_RULES_BLOCK_START_RE = /<!--\s*cbx:engineering:auto:start[^>]*
 const ENGINEERING_RULES_BLOCK_END_RE = /<!--\s*cbx:engineering:auto:end\s*-->/g;
 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",
@@ -215,11 +226,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";
@@ -838,6 +856,395 @@ function buildAntigravityTerminalVerificationBlock({ provider, powerShellScriptP
         "<!-- cbx:terminal:verification:end -->",
     ].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",
@@ -920,21 +1327,122 @@ 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 buildEngineeringRulesManagedBlock({ platform, engineeringRulesFilePath, techMdFilePath, ruleFilePath, }) {
+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 [
         `<!-- cbx:engineering:auto:start platform=${platform} version=1 -->`,
         "## 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:",
@@ -942,10 +1450,11 @@ function buildEngineeringRulesManagedBlock({ platform, engineeringRulesFilePath,
         "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");
@@ -1032,11 +1541,14 @@ async function upsertEngineeringRulesFile({ targetPath, template, overwrite = fa
         filePath: targetPath,
     };
 }
-async function upsertEngineeringRulesBlock({ ruleFilePath, platform, engineeringRulesFilePath, techMdFilePath, dryRun = false, }) {
+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);
@@ -1080,6 +1592,160 @@ async function upsertEngineeringRulesBlock({ ruleFilePath, platform, engineering
         warnings,
     };
 }
+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;
+}
+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;
+    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`;
+    }
+    if (nextContent === original) {
+        return {
+            action: "unchanged",
+            filePath: targetPath,
+        };
+    }
+    if (!dryRun) {
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, nextContent, "utf8");
+    }
+    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;
@@ -1963,7 +2629,7 @@ function inferRecommendedSkills(snapshot) {
         hasFramework("TypeORM") ||
         hasFramework("Mongoose") ||
         hasFramework("SQLAlchemy")) {
-        recommended.add("database-skills");
+        recommended.add("database-design");
     }
     if (recommended.size === 0) {
         recommended.add("clean-code");
@@ -2217,6 +2883,8 @@ function buildTechMd(snapshot, { compact = false } = {}) {
     lines.push(`- Suggested install profile: \`${contextBudget.suggestedProfile}\``);
     lines.push("- Use `--all-skills` only when task scope clearly requires full catalog breadth.");
     lines.push("");
+    lines.push(buildTechArchitectureSection(snapshot).trimEnd());
+    lines.push("");
     if (!compact) {
         lines.push("## Package Signals");
         appendTechPackageSection(lines, "JavaScript / TypeScript (package.json)", snapshot.packageSignals.javascript);
@@ -6649,14 +7317,6 @@ async function performWorkflowInstall(options, { postmanSelectionOverride = null
         dryRun,
         cwd,
     });
-    const engineeringArtifactsResult = await upsertEngineeringArtifacts({
-        platform,
-        scope: ruleScope,
-        overwrite: false,
-        dryRun,
-        skipTech: false,
-        cwd,
-    });
     const postmanSetupResult = await configurePostmanInstallArtifacts({
         platform,
         scope,
@@ -6698,7 +7358,7 @@ async function performWorkflowInstall(options, { postmanSelectionOverride = null
         bundleId,
         installResult,
         syncResult,
-        engineeringArtifactsResult,
+        engineeringArtifactsResult: null,
         postmanSetupResult,
         terminalVerificationRuleResult,
     };
@@ -6726,10 +7386,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,
         });
@@ -9588,12 +10245,24 @@ function printInstallEngineeringSummary({ engineeringResults, techResult }) {
         console.log(`- TECH scan files: ${techResult.snapshot.scannedFiles}`);
     }
 }
+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, overwrite = false, skipTech = false, dryRun = false, cwd = process.cwd(), }) {
     const ruleFilePath = await resolveRuleFilePath(platform, scope, cwd);
     if (!ruleFilePath)
         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") {
         const workspaceRuleFile = await resolveWorkspaceRuleFileForGlobalScope(platform, cwd);
@@ -9603,42 +10272,31 @@ async function upsertEngineeringArtifacts({ platform, scope, overwrite = false,
             targets.push({ ruleFilePath: workspaceRuleFile });
         }
     }
-    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,
         };
     }
@@ -9714,6 +10372,659 @@ async function runRulesTechMd(options) {
         process.exit(1);
     }
 }
+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(",")
@@ -9919,10 +11230,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,
                 });
@@ -10025,6 +11333,7 @@ export function buildCliProgram() {
         defaultMcpDockerContainerName: DEFAULT_MCP_DOCKER_CONTAINER_NAME,
         runRulesInit,
         runRulesTechMd,
+        runBuildArchitecture,
     });
 }
 export async function runCli(argv = process.argv) {