dxcomplete 0.1.0

package/dist/runtime/workspace.d.ts

@@ -0,0 +1,19 @@
+export type WorkspaceBootstrapMember = {
+    email: string;
+    roles: WorkspaceBootstrapRole[];
+    role?: "owner" | "member";
+};
+export type WorkspaceConfig = {
+    workspaceId: string;
+    name: string;
+    mode?: WorkspaceMode;
+    bootstrapMembers: WorkspaceBootstrapMember[];
+};
+export type WorkspaceMode = "transformation" | "greenfield" | "limited-disclosure";
+export type WorkspaceBootstrapRole = "owner" | "engineer" | "tester" | "operator" | "support_agent" | "end_user";
+export type WorkspaceConfigOptions = {
+    cwd?: string;
+    configPath?: string;
+};
+export declare function loadWorkspaceConfig(options?: WorkspaceConfigOptions): Promise<WorkspaceConfig>;
+export declare function parseWorkspaceConfig(value: unknown, source?: string): WorkspaceConfig;

package/dist/runtime/workspace.js

@@ -0,0 +1,102 @@
+import { constants as fsConstants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { normalizeEmail } from "./actor.js";
+const DEFAULT_WORKSPACE_CONFIG = path.join("dxcomplete", "workspace.json");
+export async function loadWorkspaceConfig(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const configPath = path.resolve(cwd, options.configPath ?? DEFAULT_WORKSPACE_CONFIG);
+    if (!(await fileExists(configPath))) {
+        throw new Error(`DX Complete workspace config not found: ${configPath}`);
+    }
+    const parsed = JSON.parse(await readFile(configPath, "utf8"));
+    return parseWorkspaceConfig(parsed, configPath);
+}
+export function parseWorkspaceConfig(value, source = "workspace config") {
+    if (!value || typeof value !== "object") {
+        throw new Error(`${source} must be a JSON object.`);
+    }
+    const input = value;
+    const workspaceId = readRequiredString(input.workspaceId, "workspaceId", source);
+    const name = readRequiredString(input.name, "name", source);
+    const mode = parseWorkspaceMode(input.mode, source);
+    const bootstrapMembers = parseBootstrapMembers(input.bootstrapMembers, source);
+    return {
+        workspaceId,
+        name,
+        ...(mode ? { mode } : {}),
+        bootstrapMembers
+    };
+}
+function parseWorkspaceMode(value, source) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "transformation" || value === "greenfield" || value === "limited-disclosure") {
+        return value;
+    }
+    throw new Error(`${source} mode must be transformation, greenfield, or limited-disclosure when provided.`);
+}
+function parseBootstrapMembers(value, source) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${source} bootstrapMembers must be an array when provided.`);
+    }
+    return value.map((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`${source} bootstrapMembers[${index}] must be an object.`);
+        }
+        const record = entry;
+        const email = normalizeEmail(readRequiredString(record.email, `bootstrapMembers[${index}].email`, source));
+        const roles = parseBootstrapMemberRoles(record, `bootstrapMembers[${index}]`, source);
+        return { email, roles };
+    });
+}
+function parseBootstrapMemberRoles(record, keyPrefix, source) {
+    if (Array.isArray(record.roles)) {
+        const roles = record.roles.map((role, roleIndex) => parseBootstrapRole(role, `${keyPrefix}.roles[${roleIndex}]`, source));
+        return uniqueRoles(roles);
+    }
+    if (record.role === "owner") {
+        return ["owner"];
+    }
+    if (record.role === "member") {
+        return ["end_user"];
+    }
+    throw new Error(`${source} ${keyPrefix}.roles must contain at least one valid workspace role.`);
+}
+function parseBootstrapRole(value, key, source) {
+    if (value === "owner" ||
+        value === "engineer" ||
+        value === "tester" ||
+        value === "operator" ||
+        value === "support_agent" ||
+        value === "end_user") {
+        return value;
+    }
+    throw new Error(`${source} ${key} must be owner, engineer, tester, operator, support_agent, or end_user.`);
+}
+function uniqueRoles(roles) {
+    const unique = [...new Set(roles)];
+    if (unique.length === 0) {
+        throw new Error("workspace config bootstrap member roles must contain at least one role.");
+    }
+    return unique.sort();
+}
+function readRequiredString(value, key, source) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${source} ${key} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,20 @@
+import { type UpgradeManagedFile } from "./install-manifest.js";
+export type UpgradeOptions = {
+    targetDir: string;
+    apply?: boolean;
+    force?: boolean;
+};
+export type UpgradeResult = {
+    targetDir: string;
+    applied: boolean;
+    packageVersion: string;
+    workspaceCompatibility: number;
+    written: string[];
+    planned: string[];
+    unchanged: string[];
+    manualReview: string[];
+    userOwnedDrift: string[];
+    manifestWritten: boolean;
+};
+export declare function upgradeProject(options: UpgradeOptions): Promise<UpgradeResult>;
+export declare function getUpgradeManagedFiles(packageRoot: string, targetDir: string): UpgradeManagedFile[];

package/dist/upgrade.js

@@ -0,0 +1,246 @@
+import { copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { INSTALL_MANIFEST_SCHEMA_VERSION, INSTALL_MANIFEST_PATH, hashContent, hashFile, readInstallManifest, writeInstallManifest } from "./install-manifest.js";
+import { fileExists, resolvePackageRoot } from "./package-root.js";
+import { DXCOMPLETE_PACKAGE_VERSION, WORKSPACE_COMPATIBILITY_VERSION } from "./version.js";
+const WELL_KNOWN_REWRITES = [
+    {
+        source: "/.well-known/oauth-authorization-server",
+        destination: "/api/dxcomplete/.well-known/oauth-authorization-server"
+    },
+    {
+        source: "/.well-known/oauth-protected-resource/api/mcp",
+        destination: "/api/dxcomplete/.well-known/oauth-protected-resource/api/mcp"
+    }
+];
+const WORKSPACE_CONFIG_PATH = path.join("dxcomplete", "workspace.json");
+export async function upgradeProject(options) {
+    const targetDir = path.resolve(options.targetDir);
+    const apply = options.apply ?? false;
+    const force = options.force ?? false;
+    await assertExistingDxcompleteInstall(targetDir);
+    const packageRoot = await resolvePackageRoot();
+    const managedFiles = getUpgradeManagedFiles(packageRoot, targetDir);
+    const manifest = await readInstallManifest(targetDir);
+    const result = {
+        targetDir,
+        applied: apply,
+        packageVersion: DXCOMPLETE_PACKAGE_VERSION,
+        workspaceCompatibility: WORKSPACE_COMPATIBILITY_VERSION,
+        written: [],
+        planned: [],
+        unchanged: [],
+        manualReview: [],
+        userOwnedDrift: [],
+        manifestWritten: false
+    };
+    if (apply) {
+        const preview = await upgradeProject({ targetDir, apply: false, force });
+        if (preview.manualReview.length > 0) {
+            return {
+                ...preview,
+                applied: true,
+                written: [],
+                planned: [],
+                manifestWritten: false
+            };
+        }
+    }
+    for (const file of managedFiles) {
+        if (file.strategy === "merge-vercel") {
+            await upgradeVercelConfig(file, { apply, force, manifest }, result);
+            continue;
+        }
+        await upgradeCopiedFile(file, { apply, force, manifest }, result);
+    }
+    result.userOwnedDrift.push(...(await collectUserOwnedDrift(packageRoot, targetDir)));
+    const manifestNeedsWrite = result.planned.length > 0 || result.written.length > 0 || shouldWriteManifest(manifest, managedFiles);
+    if (apply && result.manualReview.length === 0 && manifestNeedsWrite) {
+        await writeInstallManifest(targetDir, managedFiles);
+        result.written.push(INSTALL_MANIFEST_PATH);
+        result.manifestWritten = true;
+    }
+    else if (!apply && manifestNeedsWrite) {
+        result.planned.push(INSTALL_MANIFEST_PATH);
+    }
+    return result;
+}
+async function assertExistingDxcompleteInstall(targetDir) {
+    if (await fileExists(path.join(targetDir, WORKSPACE_CONFIG_PATH))) {
+        return;
+    }
+    throw new Error(`DX Complete install not found in ${targetDir}. Run dxcomplete init before dxcomplete upgrade.`);
+}
+function shouldWriteManifest(manifest, files) {
+    if (!manifest) {
+        return true;
+    }
+    if (manifest.schemaVersion !== INSTALL_MANIFEST_SCHEMA_VERSION ||
+        manifest.packageVersion !== DXCOMPLETE_PACKAGE_VERSION ||
+        manifest.workspaceCompatibility !== WORKSPACE_COMPATIBILITY_VERSION) {
+        return true;
+    }
+    return files.some((file) => !manifest.managedFiles[file.destinationRelative]);
+}
+export function getUpgradeManagedFiles(packageRoot, targetDir) {
+    const files = [
+        {
+            sourceRelative: path.join("templates", "next", "pages", "api", "mcp.js"),
+            destinationRelative: path.join("pages", "api", "mcp.js"),
+            strategy: "copy"
+        },
+        {
+            sourceRelative: path.join("templates", "next", "pages", "api", "dxcomplete.js"),
+            destinationRelative: path.join("pages", "api", "dxcomplete.js"),
+            strategy: "copy"
+        },
+        {
+            sourceRelative: path.join("templates", "next", "pages", "api", "dxcomplete", "[...path].js"),
+            destinationRelative: path.join("pages", "api", "dxcomplete", "[...path].js"),
+            strategy: "copy"
+        },
+        {
+            sourceRelative: path.join("templates", "next", "pages", "api", "auth", "callback", "google.js"),
+            destinationRelative: path.join("pages", "api", "auth", "callback", "google.js"),
+            strategy: "copy"
+        },
+        {
+            sourceRelative: path.join("templates", "next", "vercel.json"),
+            destinationRelative: "vercel.json",
+            strategy: "merge-vercel"
+        }
+    ];
+    return files.map((file) => ({
+        ...file,
+        sourcePath: path.join(packageRoot, file.sourceRelative),
+        destinationPath: path.join(targetDir, file.destinationRelative)
+    }));
+}
+async function upgradeCopiedFile(file, options, result) {
+    const desiredHash = await hashFile(file.sourcePath);
+    const exists = await fileExists(file.destinationPath);
+    const currentHash = exists ? await hashFile(file.destinationPath) : undefined;
+    if (currentHash === desiredHash) {
+        result.unchanged.push(file.destinationRelative);
+        return;
+    }
+    const previousHash = options.manifest?.managedFiles[file.destinationRelative]?.sha256;
+    if (exists && !options.force && currentHash !== previousHash) {
+        result.manualReview.push(previousHash
+            ? `${file.destinationRelative} (modified since last DX Complete install)`
+            : `${file.destinationRelative} (differs from the current scaffold and no install manifest is available)`);
+        return;
+    }
+    if (!options.apply) {
+        result.planned.push(file.destinationRelative);
+        return;
+    }
+    await mkdir(path.dirname(file.destinationPath), { recursive: true });
+    await copyFile(file.sourcePath, file.destinationPath);
+    result.written.push(file.destinationRelative);
+}
+async function upgradeVercelConfig(file, options, result) {
+    const exists = await fileExists(file.destinationPath);
+    const templateContent = await readFile(file.sourcePath, "utf8");
+    let desiredContent = templateContent;
+    if (exists) {
+        const currentContent = await readFile(file.destinationPath, "utf8");
+        try {
+            desiredContent = `${JSON.stringify(mergeVercelConfig(JSON.parse(currentContent)), null, 2)}\n`;
+        }
+        catch {
+            if (!options.force) {
+                result.manualReview.push(`${file.destinationRelative} (invalid JSON; cannot merge safely)`);
+                return;
+            }
+        }
+        if (hashContent(currentContent) === hashContent(desiredContent)) {
+            result.unchanged.push(file.destinationRelative);
+            return;
+        }
+    }
+    if (!options.apply) {
+        result.planned.push(file.destinationRelative);
+        return;
+    }
+    await writeFile(file.destinationPath, desiredContent, "utf8");
+    result.written.push(file.destinationRelative);
+}
+function mergeVercelConfig(value) {
+    const config = isPlainObject(value) ? { ...value } : {};
+    const functions = isPlainObject(config.functions) ? { ...config.functions } : {};
+    const pagesFunctionKey = "pages/api/**/*.js";
+    const pagesFunction = isPlainObject(functions[pagesFunctionKey])
+        ? { ...functions[pagesFunctionKey] }
+        : {};
+    pagesFunction.includeFiles = mergeIncludeFiles(pagesFunction.includeFiles, "dxcomplete/workspace.json");
+    functions[pagesFunctionKey] = pagesFunction;
+    config.functions = functions;
+    config.rewrites = mergeRewrites(config.rewrites);
+    return config;
+}
+function mergeIncludeFiles(value, requiredFile) {
+    if (typeof value === "string") {
+        return value === requiredFile ? value : uniqueStrings([value, requiredFile]);
+    }
+    if (Array.isArray(value)) {
+        return uniqueStrings([...value.filter((entry) => typeof entry === "string"), requiredFile]);
+    }
+    return requiredFile;
+}
+function mergeRewrites(value) {
+    const rewrites = Array.isArray(value)
+        ? value.filter((entry) => isPlainObject(entry)).map((entry) => ({ ...entry }))
+        : [];
+    for (const requiredRewrite of WELL_KNOWN_REWRITES) {
+        const existing = rewrites.find((rewrite) => rewrite.source === requiredRewrite.source);
+        if (existing) {
+            existing.destination = requiredRewrite.destination;
+        }
+        else {
+            rewrites.push({ ...requiredRewrite });
+        }
+    }
+    return rewrites;
+}
+async function collectUserOwnedDrift(packageRoot, targetDir) {
+    const files = [
+        ...(await collectTemplateFiles(path.join(packageRoot, "docs"), path.join(targetDir, "dxcomplete", "docs"), path.join("dxcomplete", "docs"))),
+        ...(await collectTemplateFiles(path.join(packageRoot, "templates", "process"), path.join(targetDir, "dxcomplete", "process"), path.join("dxcomplete", "process")))
+    ];
+    const drift = [];
+    for (const file of files) {
+        if (!(await fileExists(file.destinationPath))) {
+            drift.push(`${file.destinationRelative} (missing user-owned scaffold file)`);
+            continue;
+        }
+        if ((await hashFile(file.sourcePath)) !== (await hashFile(file.destinationPath))) {
+            drift.push(`${file.destinationRelative} (differs from current package template)`);
+        }
+    }
+    return drift;
+}
+async function collectTemplateFiles(sourceDir, destinationDir, destinationRootRelative) {
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationPath = path.join(destinationDir, entry.name);
+        const destinationRelative = path.join(destinationRootRelative, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectTemplateFiles(sourcePath, destinationPath, destinationRelative)));
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        files.push({ sourcePath, destinationPath, destinationRelative });
+    }
+    return files;
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}

package/dist/validate.d.ts

@@ -0,0 +1,10 @@
+export type ValidateOptions = {
+    targetDir: string;
+    packageLayout?: boolean;
+};
+export type ValidateResult = {
+    targetDir: string;
+    ok: boolean;
+    missing: string[];
+};
+export declare function validateScaffold(options: ValidateOptions): Promise<ValidateResult>;

package/dist/validate.js

@@ -0,0 +1,119 @@
+import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+const docs = [
+    "index.md",
+    "decision-basis.md",
+    "cost-model.md",
+    "glossary.md",
+    "model.md",
+    "roles.md",
+    "taxonomy.md",
+    "workflows.md",
+    "diagrams.md",
+    "codex-integration.md",
+    "open-questions.md"
+];
+const processFiles = [
+    "README.md",
+    "decision-basis.yml",
+    "cost-model.yml",
+    "roles.yml",
+    "taxonomy.yml",
+    "workflows.yml",
+    "controls.yml"
+];
+const diagrams = [
+    "00-decision-basis.mmd",
+    "00-overview.mmd",
+    "01-intake-triage.mmd",
+    "02-product-definition.mmd",
+    "03-engineering-execution.mmd",
+    "04-qa-verification.mmd",
+    "05-product-validation.mmd",
+    "06-change-release-control.mmd",
+    "07-deployment-operations.mmd",
+    "08-support-incident-management.mmd",
+    "09-problem-improvement.mmd",
+    "10-risk-control-management.mmd",
+    "11-audit-evidence-capture.mmd"
+];
+export async function validateScaffold(options) {
+    const targetDir = path.resolve(options.targetDir);
+    const requiredFiles = options.packageLayout
+        ? packageRequiredFiles()
+        : installedRequiredFiles();
+    const missing = [];
+    for (const requiredFile of requiredFiles) {
+        if (!(await fileExists(path.join(targetDir, requiredFile)))) {
+            missing.push(requiredFile);
+        }
+    }
+    return {
+        targetDir,
+        ok: missing.length === 0,
+        missing
+    };
+}
+function packageRequiredFiles() {
+    return [
+        ...docs.map((file) => path.join("docs", file)),
+        ...processFiles.map((file) => path.join("templates", "process", file)),
+        ...diagrams.map((file) => path.join("templates", "process", "diagrams", file)),
+        ".env.example",
+        path.join("api", "mcp.js"),
+        path.join("api", "dxcomplete.js"),
+        path.join("api", "dxcomplete-service.js"),
+        path.join("api", "auth", "callback", "google.js"),
+        path.join("dxcomplete", "workspace.json"),
+        path.join("scripts", "check-env-surface.mjs"),
+        path.join("scripts", "smoke-mcp-http.mjs"),
+        path.join("scripts", "dogfood-work-order.mjs"),
+        path.join("scripts", "check-public-copy.mjs"),
+        path.join("scripts", "check-service-boundary.mjs"),
+        path.join("templates", "next", "pages", "api", "mcp.js"),
+        path.join("templates", "next", "pages", "api", "dxcomplete.js"),
+        path.join("templates", "next", "pages", "api", "dxcomplete", "[...path].js"),
+        path.join("templates", "next", "pages", "api", "auth", "callback", "google.js"),
+        path.join("templates", "next", "vercel.json"),
+        path.join("templates", "github", "workflows", "dxcomplete.yml"),
+        path.join("src", "cli.ts"),
+        path.join("src", "install-manifest.ts"),
+        path.join("src", "init.ts"),
+        path.join("src", "package-root.ts"),
+        path.join("src", "http", "server.ts"),
+        path.join("src", "http", "service.ts"),
+        path.join("src", "mcp", "server.ts"),
+        path.join("src", "runtime", "auth.ts"),
+        path.join("src", "runtime", "check.ts"),
+        path.join("src", "runtime", "config.ts"),
+        path.join("src", "runtime", "mongo.ts"),
+        path.join("src", "runtime", "records.ts"),
+        path.join("src", "runtime", "workspace.ts"),
+        path.join("src", "upgrade.ts"),
+        path.join("src", "version.ts"),
+        path.join("src", "validate.ts")
+    ];
+}
+function installedRequiredFiles() {
+    return [
+        path.join("pages", "api", "mcp.js"),
+        path.join("pages", "api", "dxcomplete.js"),
+        path.join("pages", "api", "dxcomplete", "[...path].js"),
+        path.join("pages", "api", "auth", "callback", "google.js"),
+        "vercel.json",
+        path.join("dxcomplete", "workspace.json"),
+        ...docs.map((file) => path.join("dxcomplete", "docs", file)),
+        ...processFiles.map((file) => path.join("dxcomplete", "process", file)),
+        ...diagrams.map((file) => path.join("dxcomplete", "process", "diagrams", file))
+    ];
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const DXCOMPLETE_PACKAGE_VERSION: string;
+export declare const WORKSPACE_COMPATIBILITY_VERSION = 1;
+export declare const MCP_SURFACE_ID = "dxc-mcp-surface";

package/dist/version.js

@@ -0,0 +1,12 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+export const DXCOMPLETE_PACKAGE_VERSION = readPackageVersion(packageJson.version);
+export const WORKSPACE_COMPATIBILITY_VERSION = 1;
+export const MCP_SURFACE_ID = "dxc-mcp-surface";
+function readPackageVersion(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error("DX Complete package.json version must be a non-empty string.");
+    }
+    return value;
+}

package/docs/codex-integration.md

@@ -0,0 +1,29 @@
+# Codex Integration Draft
+
+Codex is an instance of a coding-capable model. It is not a role in the DX Complete operating model.
+
+The related role is `Engineer`: the person who performs implementation work directly or drives coding-capable tools. Codex may assist the Engineer.
+
+## Current Hypothesis
+
+Codex assistance works primarily on `Task` objects. The Engineer defines or accepts the implementation approach, assigns task scope, reviews outputs, and decides whether work is ready for testing.
+
+This does not mean Codex can only work on tasks. Codex may also help draft requirements, generate diagrams, update documentation, collect evidence, or propose workflow revisions. Those uses should remain subject to the owning role.
+
+## Draft Operating Pattern
+
+1. Owner defines the requirement and acceptance criteria.
+2. Engineer may add non-blocking review notes to the expectation or requirement where delivery input should stay visible.
+3. Engineer refines the committed requirement into requirement detail and tasks.
+4. Engineer performs implementation on a task, with Codex assistance where appropriate.
+5. Engineer reviews the implementation output.
+6. Tester verifies against requirements and acceptance criteria.
+7. Owner validates the result.
+
+## Guardrails To Resolve
+
+- What level of task detail is required before Codex assistance can begin?
+- Who approves Codex-generated changes?
+- What evidence should Codex produce automatically?
+- How should Codex hand off incomplete or uncertain work?
+- Which tasks are not appropriate for Codex assistance?

package/docs/cost-model.md

@@ -0,0 +1,61 @@
+# Draft Cost Model
+
+Cost modeling is first-class in DX Complete. Do not reduce the top-level model to OPEX. OPEX/CAPEX-like categories may exist inside the cost model, but the top-level concept should remain Cost Model / Decision Basis.
+
+## Cost Visibility Rule
+
+Cost visibility is mandatory. Complete cost data is not mandatory.
+
+The system should make the following clear:
+
+- What current-state cost data was attempted.
+- What cost data is known.
+- What cost data is estimated.
+- What cost data is unavailable.
+- What cost data is intentionally undisclosed.
+- What assumptions were used.
+
+## Cost Model Distinction
+
+Baseline is what the current state costs now, if known.
+
+Estimate is what the proposed future state is expected to cost.
+
+Actuals are what the delivered future state actually costs after launch, if measured.
+
+The structured `Estimate` record is cost-only. It keeps one-time and recurring cost totals separate by period and currency.
+
+Expected value belongs in `Benefits`. Benefits may include quantified items with amounts, or qualitative items that are complete without an amount.
+
+## Draft Cost Objects
+
+Current-state cost context should be attempted where relevant. It may be complete, partial, unavailable, or limited by disclosure, but it is no longer a separate runtime record in the current model.
+
+`Estimate` records itemized cost information for the scope being weighed.
+
+`Benefits` records expected value for the scope being weighed. It may contain quantified or qualitative benefit items.
+
+Post-launch cost and benefit observations should be captured where useful, but they are not separate runtime records in the current model.
+
+## Possible Cost Categories
+
+These categories are examples, not mandatory fields:
+
+- Build labor
+- Codex-assisted implementation cost
+- Testing and validation effort
+- Infrastructure
+- Licenses and tools
+- Migration
+- Training and adoption
+- User support load
+- Operational run cost
+- Maintenance
+- Risk mitigation
+- Decommissioning or replacement
+
+## Measurement Rule
+
+Actuals should be captured when available. Missing actuals should not block project or service lifecycle closure, but the absence should be visible.
+
+Estimate refinement should use actuals where available and record uncertainty where actuals are unavailable.