sdx-cli 0.2.2 → 0.3.0

package/README.md

@@ -19,6 +19,7 @@
 <p align="center">
   <a href="#install-from-npm">Install from npm</a> •
   <a href="#one-command-setup">One-Command Setup</a> •
+  <a href="#architecture-pack-org--service-deep-dives">Architecture Pack</a> •
   <a href="#daily-workflow">Daily Workflow</a> •
   <a href="#for-codex-agents">For Codex Agents</a> •
   <a href="#release-process">Release Process</a>
@@ -131,6 +132,7 @@ From your SDX workspace root:
 
 ./scripts/sdx contracts extract --map platform-core
 ./scripts/sdx docs generate --map platform-core
+./scripts/sdx architecture generate --map platform-core
 ```
 
 For planning and rollout:
@@ -147,6 +149,32 @@ For Codex:
 ./scripts/sdx codex run implementation-plan --map platform-core --input ./plans/new-service.md
 ```
 
+### Architecture Pack (Org + Service Deep Dives)
+Generate an executive-ready architecture pack from your initialized consumer workspace:
+
+```bash
+# full pack (org-level + per-service docs/diagrams)
+./scripts/sdx architecture generate --map platform-core
+
+# org-level only
+./scripts/sdx architecture generate --map platform-core --depth org
+
+# targeted service rebuild
+./scripts/sdx architecture generate --map platform-core --service payments-api
+
+# explicit validation pass (override integrity + completeness checks)
+./scripts/sdx architecture validate --map platform-core
+```
+
+Override source of truth:
+- `maps/<map-id>/architecture-overrides.json`
+
+Use overrides to:
+- declare hidden or external dependencies,
+- assert missing relationships,
+- suppress incorrect inferred edges,
+- attach service owner/criticality/business context metadata.
+
 ## Cross-Repo Tech-Lead PRs (Spec-System Native)
 Use this flow when SDX should create real `CC-*` contract-change PRs in downstream repos that have spec-system initialized.
 
@@ -204,11 +232,16 @@ Use this minimal runbook when an agent needs architecture context quickly:
 2. `./scripts/sdx map status <map-id>`
 3. `./scripts/sdx map build <map-id>`
 4. `./scripts/sdx contracts extract --map <map-id>`
-5. `./scripts/sdx codex run <task-type> --map <map-id> --input <file>`
+5. `./scripts/sdx architecture generate --map <map-id>`
+6. `./scripts/sdx codex run <task-type> --map <map-id> --input <file>`
 
 Where outputs land:
 - `maps/<map-id>/service-map.json|md|mmd`
 - `maps/<map-id>/contracts.json|md`
+- `maps/<map-id>/architecture/model.json|validation.json`
+- `maps/<map-id>/architecture-overrides.json`
+- `docs/architecture/<map-id>/index.md`
+- `docs/architecture/<map-id>/services/*.md`
 - `codex/context-packs/*.json`
 - `codex/runs/*.md|json`
 
@@ -225,6 +258,7 @@ sdx repo add
 sdx map create|include|exclude|remove-override|status|build
 sdx prompt
 
+sdx architecture generate|validate
 sdx contracts extract
 sdx docs generate
 sdx plan review

package/dist/commands/architecture/generate.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const architecture_1 = require("../../lib/architecture");
+const project_1 = require("../../lib/project");
+const workflows_1 = require("../../lib/workflows");
+class ArchitectureGenerateCommand extends core_1.Command {
+    static description = 'Generate architecture pack artifacts and diagrams for a map';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+        depth: core_1.Flags.string({
+            required: false,
+            options: ['org', 'full'],
+            default: 'full',
+            description: 'Generation depth: org-only or full (org + per-service packs)',
+        }),
+        service: core_1.Flags.string({
+            required: false,
+            description: 'Generate only one service deep-dive (service id/repo name)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ArchitectureGenerateCommand);
+        if (flags.depth === 'org' && flags.service) {
+            throw new Error('Cannot use --service with --depth org. Use --depth full for targeted service generation.');
+        }
+        const context = (0, project_1.loadProject)(process.cwd());
+        const mapArtifacts = (0, workflows_1.buildMapArtifacts)(flags.map, context.db, context.cwd);
+        const contractArtifacts = (0, workflows_1.extractContractArtifacts)(flags.map, context.db, context.cwd);
+        const docsArtifacts = (0, workflows_1.generateDocsArtifacts)(flags.map, context.db, context.cwd);
+        const result = (0, architecture_1.generateArchitecturePack)({
+            mapId: flags.map,
+            db: context.db,
+            cwd: context.cwd,
+            depth: flags.depth,
+            serviceId: flags.service,
+        });
+        (0, project_1.recordRun)(context.db, 'architecture_generate', result.validation.valid ? 'ok' : 'error', flags.map, {
+            depth: flags.depth,
+            service: flags.service,
+            generatedServices: result.generatedServices.length,
+            validation: result.validation,
+            modelPath: result.modelPath,
+            indexDocPath: result.indexDocPath,
+            baseline: {
+                mapArtifacts,
+                contractArtifacts,
+                docsArtifacts,
+            },
+        });
+        context.db.close();
+        this.log(`Generated architecture pack for map '${flags.map}'.`);
+        this.log(`Model: ${result.modelPath}`);
+        this.log(`Overrides: ${result.overridesPath}`);
+        this.log(`Baseline service map: ${result.baselineArtifacts.serviceMapPath}`);
+        this.log(`Baseline contracts: ${result.baselineArtifacts.contractsPath}`);
+        this.log(`Baseline architecture doc: ${result.baselineArtifacts.architectureDocPath}`);
+        if (result.indexDocPath) {
+            this.log(`Architecture index: ${result.indexDocPath}`);
+        }
+        if (result.generatedServices.length > 0) {
+            this.log(`Service deep dives: ${result.generatedServices.length}`);
+        }
+        this.log(`Validation: ${result.validation.valid ? 'pass' : 'fail'} (errors=${result.validation.errors.length}, warnings=${result.validation.warnings.length})`);
+        if (!result.validation.valid) {
+            this.error('Architecture validation failed. Resolve override/model issues and rerun.', { exit: 1 });
+        }
+    }
+}
+exports.default = ArchitectureGenerateCommand;

package/dist/commands/architecture/validate.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@oclif/core");
+const architecture_1 = require("../../lib/architecture");
+const fs_1 = require("../../lib/fs");
+const project_1 = require("../../lib/project");
+class ArchitectureValidateCommand extends core_1.Command {
+    static description = 'Validate architecture model completeness and override integrity for a map';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+    };
+    async run() {
+        const { flags } = await this.parse(ArchitectureValidateCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const result = (0, architecture_1.validateArchitecture)({
+            mapId: flags.map,
+            db: context.db,
+            cwd: context.cwd,
+        });
+        const outDir = node_path_1.default.join(context.cwd, 'maps', flags.map, 'architecture');
+        const jsonPath = node_path_1.default.join(outDir, 'validation.json');
+        const mdPath = node_path_1.default.join(outDir, 'validation.md');
+        (0, fs_1.writeJsonFile)(jsonPath, result);
+        const lines = [
+            `# Architecture Validation: ${flags.map}`,
+            '',
+            `- Generated: ${result.generatedAt}`,
+            `- Valid: ${result.valid ? 'yes' : 'no'}`,
+            `- Errors: ${result.errors.length}`,
+            `- Warnings: ${result.warnings.length}`,
+            '',
+        ];
+        if (result.errors.length > 0) {
+            lines.push('## Errors');
+            lines.push('');
+            for (const err of result.errors) {
+                lines.push(`- ${err}`);
+            }
+            lines.push('');
+        }
+        if (result.warnings.length > 0) {
+            lines.push('## Warnings');
+            lines.push('');
+            for (const warning of result.warnings) {
+                lines.push(`- ${warning}`);
+            }
+            lines.push('');
+        }
+        (0, fs_1.writeTextFile)(mdPath, `${lines.join('\n')}\n`);
+        (0, project_1.recordRun)(context.db, 'architecture_validate', result.valid ? 'ok' : 'error', flags.map, {
+            validationPath: jsonPath,
+            errorCount: result.errors.length,
+            warningCount: result.warnings.length,
+            stats: result.stats,
+        });
+        context.db.close();
+        this.log(`Validated architecture for map '${flags.map}'.`);
+        this.log(`JSON: ${jsonPath}`);
+        this.log(`Markdown: ${mdPath}`);
+        this.log(`Result: ${result.valid ? 'pass' : 'fail'}`);
+        if (!result.valid) {
+            this.error('Architecture validation failed. Resolve errors and rerun.', { exit: 1 });
+        }
+    }
+}
+exports.default = ArchitectureValidateCommand;

package/dist/commands/bootstrap/quick.js

@@ -70,6 +70,7 @@ class BootstrapQuickCommand extends core_1.Command {
             this.log('- ./scripts/sdx map create all-services --org <org>');
             this.log('- ./scripts/sdx map build all-services');
         }
+        this.log('- ./scripts/sdx architecture generate --map all-services');
         if (result.warnings.length > 0) {
             this.log('');
             this.log('Warnings:');

package/dist/commands/publish/wiki.js

@@ -8,6 +8,19 @@ const node_path_1 = __importDefault(require("node:path"));
 const core_1 = require("@oclif/core");
 const fs_1 = require("../../lib/fs");
 const project_1 = require("../../lib/project");
+function copyRecursive(source, target) {
+    const stat = node_fs_1.default.statSync(source);
+    if (stat.isDirectory()) {
+        (0, fs_1.ensureDir)(target);
+        const entries = node_fs_1.default.readdirSync(source, { withFileTypes: true });
+        for (const entry of entries) {
+            copyRecursive(node_path_1.default.join(source, entry.name), node_path_1.default.join(target, entry.name));
+        }
+        return;
+    }
+    const body = node_fs_1.default.readFileSync(source, 'utf8');
+    (0, fs_1.writeTextFile)(target, body);
+}
 class PublishWikiCommand extends core_1.Command {
     static description = 'Export docs-first artifacts to a wiki-friendly directory';
     static flags = {
@@ -21,6 +34,9 @@ class PublishWikiCommand extends core_1.Command {
             node_path_1.default.join(context.cwd, 'maps', flags.map, 'contracts.md'),
             node_path_1.default.join(context.cwd, 'docs', 'architecture', `${flags.map}.md`),
         ];
+        const sourceDirs = [
+            node_path_1.default.join(context.cwd, 'docs', 'architecture', flags.map),
+        ];
         const wikiDir = node_path_1.default.join(context.cwd, 'wiki-export', flags.map);
         (0, fs_1.ensureDir)(wikiDir);
         for (const source of sourceFiles) {
@@ -28,8 +44,14 @@ class PublishWikiCommand extends core_1.Command {
                 continue;
             }
             const target = node_path_1.default.join(wikiDir, node_path_1.default.basename(source));
-            const body = node_fs_1.default.readFileSync(source, 'utf8');
-            (0, fs_1.writeTextFile)(target, body);
+            copyRecursive(source, target);
+        }
+        for (const source of sourceDirs) {
+            if (!node_fs_1.default.existsSync(source)) {
+                continue;
+            }
+            const target = node_path_1.default.join(wikiDir, node_path_1.default.basename(source));
+            copyRecursive(source, target);
         }
         (0, project_1.recordRun)(context.db, 'publish_wiki', 'ok', flags.map, { wikiDir });
         context.db.close();

package/dist/commands/status.js

@@ -29,7 +29,8 @@ class StatusCommand extends core_1.Command {
             const mapDir = node_path_1.default.join(mapsDir, mapId);
             const hasScope = (0, fs_1.fileExists)(node_path_1.default.join(mapDir, 'scope.json'));
             const hasServiceMap = (0, fs_1.fileExists)(node_path_1.default.join(mapDir, 'service-map.json'));
-            this.log(`- ${mapId}: scope=${hasScope ? 'yes' : 'no'}, service-map=${hasServiceMap ? 'yes' : 'no'}`);
+            const hasArchitectureModel = (0, fs_1.fileExists)(node_path_1.default.join(mapDir, 'architecture', 'model.json'));
+            this.log(`- ${mapId}: scope=${hasScope ? 'yes' : 'no'}, service-map=${hasServiceMap ? 'yes' : 'no'}, architecture=${hasArchitectureModel ? 'yes' : 'no'}`);
         }
         context.db.close();
     }

package/dist/lib/architecture.js

@@ -0,0 +1,793 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getArchitectureOverridesPath = getArchitectureOverridesPath;
+exports.ensureArchitectureOverridesFile = ensureArchitectureOverridesFile;
+exports.loadArchitectureOverrides = loadArchitectureOverrides;
+exports.buildArchitectureModel = buildArchitectureModel;
+exports.validateArchitecture = validateArchitecture;
+exports.generateArchitecturePack = generateArchitecturePack;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const zod_1 = require("zod");
+const constants_1 = require("./constants");
+const contracts_1 = require("./contracts");
+const fileScan_1 = require("./fileScan");
+const fs_1 = require("./fs");
+const mapBuilder_1 = require("./mapBuilder");
+const paths_1 = require("./paths");
+const repoRegistry_1 = require("./repoRegistry");
+const scope_1 = require("./scope");
+const DATASTORE_KEYWORDS = ['postgres', 'mysql', 'mongodb', 'mongo', 'dynamodb', 'redis', 'cassandra', 'sqlite'];
+const QUEUE_KEYWORDS = ['kafka', 'sqs', 'sns', 'rabbitmq', 'nats', 'pubsub', 'pulsar', 'kinesis'];
+const OVERRIDES_SCHEMA = zod_1.z.object({
+    schemaVersion: zod_1.z.string().optional(),
+    generatedAt: zod_1.z.string().optional(),
+    mapId: zod_1.z.string().optional(),
+    serviceMetadata: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.object({
+        owner: zod_1.z.string().optional(),
+        criticality: zod_1.z.enum(['low', 'medium', 'high', 'critical']).optional(),
+        businessContext: zod_1.z.string().optional(),
+    }))
+        .default({}),
+    assertedNodes: zod_1.z
+        .array(zod_1.z.object({
+        id: zod_1.z.string().min(1),
+        type: zod_1.z.enum(['service', 'repo', 'api', 'event', 'datastore', 'queue', 'team', 'external']),
+        label: zod_1.z.string().min(1),
+        metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    }))
+        .default([]),
+    assertedEdges: zod_1.z
+        .array(zod_1.z.object({
+        from: zod_1.z.string().min(1),
+        to: zod_1.z.string().min(1),
+        relation: zod_1.z.enum(['calls', 'publishes', 'consumes', 'owns', 'depends_on']),
+        metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    }))
+        .default([]),
+    suppressedEdges: zod_1.z
+        .array(zod_1.z.object({
+        from: zod_1.z.string().min(1),
+        to: zod_1.z.string().min(1),
+        relation: zod_1.z.enum(['calls', 'publishes', 'consumes', 'owns', 'depends_on']),
+    }))
+        .default([]),
+});
+function toNodeRef(input, nodes) {
+    if (nodes.has(input)) {
+        return input;
+    }
+    const prefixes = [
+        'service',
+        'repo',
+        'external',
+        'datastore',
+        'queue',
+        'team',
+        'api',
+        'event',
+    ];
+    for (const prefix of prefixes) {
+        const ref = `${prefix}:${input}`;
+        if (nodes.has(ref)) {
+            return ref;
+        }
+    }
+    return undefined;
+}
+function dedupeNodes(nodes) {
+    const byId = new Map();
+    for (const node of nodes) {
+        const existing = byId.get(node.id);
+        if (!existing) {
+            byId.set(node.id, node);
+            continue;
+        }
+        byId.set(node.id, {
+            ...existing,
+            label: node.label,
+            type: node.type,
+            metadata: {
+                ...(existing.metadata ?? {}),
+                ...(node.metadata ?? {}),
+            },
+            provenance: node.provenance.source === 'override' || existing.provenance.source !== 'override' ? node.provenance : existing.provenance,
+        });
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+function dedupeEdges(edges) {
+    const byKey = new Map();
+    for (const edge of edges) {
+        const key = `${edge.from}|${edge.to}|${edge.relation}`;
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, edge);
+            continue;
+        }
+        byKey.set(key, {
+            ...existing,
+            metadata: {
+                ...(existing.metadata ?? {}),
+                ...(edge.metadata ?? {}),
+            },
+            provenance: edge.provenance.source === 'override' || existing.provenance.source !== 'override' ? edge.provenance : existing.provenance,
+        });
+    }
+    return [...byKey.values()].sort((a, b) => {
+        const left = `${a.from}|${a.to}|${a.relation}`;
+        const right = `${b.from}|${b.to}|${b.relation}`;
+        return left.localeCompare(right);
+    });
+}
+function keywordMatches(allFiles, keywords) {
+    const out = new Map();
+    for (const filePath of allFiles) {
+        const lower = filePath.toLowerCase();
+        for (const keyword of keywords) {
+            if (!lower.includes(keyword)) {
+                continue;
+            }
+            const previous = out.get(keyword) ?? [];
+            if (previous.length < 3) {
+                previous.push(filePath);
+            }
+            out.set(keyword, previous);
+        }
+    }
+    return out;
+}
+function inferInfra(repo, nodes, edges) {
+    if (!repo.localPath || !node_fs_1.default.existsSync(repo.localPath)) {
+        return;
+    }
+    const files = (0, fileScan_1.listFilesRecursive)(repo.localPath);
+    const serviceNodeId = `service:${repo.name}`;
+    const dataStoreHits = keywordMatches(files, DATASTORE_KEYWORDS);
+    for (const [keyword, hitFiles] of dataStoreHits.entries()) {
+        const nodeId = `datastore:${keyword}`;
+        nodes.push({
+            id: nodeId,
+            type: 'datastore',
+            label: keyword,
+            metadata: {
+                inferredFrom: hitFiles.map((candidate) => node_path_1.default.relative(repo.localPath, candidate)),
+            },
+            provenance: {
+                source: 'inferred',
+                confidence: 0.6,
+                evidence: [`repo:${repo.name}:keyword:${keyword}`],
+            },
+        });
+        edges.push({
+            from: serviceNodeId,
+            to: nodeId,
+            relation: 'depends_on',
+            provenance: {
+                source: 'inferred',
+                confidence: 0.6,
+                evidence: [`repo:${repo.name}:keyword:${keyword}`],
+            },
+            metadata: {
+                inferredFrom: 'file_keyword_scan',
+            },
+        });
+    }
+    const queueHits = keywordMatches(files, QUEUE_KEYWORDS);
+    for (const [keyword, hitFiles] of queueHits.entries()) {
+        const nodeId = `queue:${keyword}`;
+        nodes.push({
+            id: nodeId,
+            type: 'queue',
+            label: keyword,
+            metadata: {
+                inferredFrom: hitFiles.map((candidate) => node_path_1.default.relative(repo.localPath, candidate)),
+            },
+            provenance: {
+                source: 'inferred',
+                confidence: 0.6,
+                evidence: [`repo:${repo.name}:keyword:${keyword}`],
+            },
+        });
+        edges.push({
+            from: serviceNodeId,
+            to: nodeId,
+            relation: 'depends_on',
+            provenance: {
+                source: 'inferred',
+                confidence: 0.6,
+                evidence: [`repo:${repo.name}:keyword:${keyword}`],
+            },
+            metadata: {
+                inferredFrom: 'file_keyword_scan',
+            },
+        });
+    }
+}
+function contractNodeId(contract) {
+    const prefix = contract.type === 'asyncapi' ? 'event' : 'api';
+    return `${prefix}:${contract.repo}:${contract.path}`;
+}
+function addConsumerSignals(contracts, baseEdges, nodes, edges) {
+    const byRepo = new Map();
+    for (const contract of contracts) {
+        const entries = byRepo.get(contract.repo) ?? [];
+        entries.push(contract);
+        byRepo.set(contract.repo, entries);
+    }
+    const hasNode = new Set(nodes.map((node) => node.id));
+    for (const relation of baseEdges) {
+        if (relation.relation !== 'depends_on' || !relation.from.startsWith('service:') || !relation.to.startsWith('service:')) {
+            continue;
+        }
+        const sourceRepo = relation.from.slice('service:'.length);
+        const targetRepo = relation.to.slice('service:'.length);
+        const targetContracts = byRepo.get(targetRepo) ?? [];
+        if (targetContracts.length === 0) {
+            continue;
+        }
+        edges.push({
+            from: relation.from,
+            to: relation.to,
+            relation: 'calls',
+            provenance: {
+                source: 'inferred',
+                confidence: 0.7,
+                evidence: [`dependency:${sourceRepo}->${targetRepo}`],
+            },
+            metadata: {
+                inferredFrom: 'dependency_plus_contract',
+            },
+        });
+        for (const contract of targetContracts) {
+            const targetNodeId = contractNodeId(contract);
+            if (!hasNode.has(targetNodeId)) {
+                continue;
+            }
+            edges.push({
+                from: relation.from,
+                to: targetNodeId,
+                relation: contract.type === 'asyncapi' ? 'consumes' : 'calls',
+                provenance: {
+                    source: 'inferred',
+                    confidence: 0.55,
+                    evidence: [`dependency:${sourceRepo}->${targetRepo}`, `contract:${contract.path}`],
+                },
+                metadata: {
+                    inferredFrom: 'dependency_plus_contract',
+                },
+            });
+        }
+    }
+}
+function defaultOverrides(mapId) {
+    return {
+        schemaVersion: constants_1.SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        mapId,
+        serviceMetadata: {},
+        assertedNodes: [],
+        assertedEdges: [],
+        suppressedEdges: [],
+    };
+}
+function getArchitectureOverridesPath(mapId, cwd = process.cwd()) {
+    return node_path_1.default.join((0, paths_1.getMapDir)(mapId, cwd), 'architecture-overrides.json');
+}
+function ensureArchitectureOverridesFile(mapId, cwd = process.cwd()) {
+    const overridesPath = getArchitectureOverridesPath(mapId, cwd);
+    if ((0, fs_1.fileExists)(overridesPath)) {
+        return overridesPath;
+    }
+    (0, fs_1.writeJsonFile)(overridesPath, defaultOverrides(mapId));
+    return overridesPath;
+}
+function loadArchitectureOverrides(mapId, cwd = process.cwd()) {
+    const overridesPath = ensureArchitectureOverridesFile(mapId, cwd);
+    const payload = (0, fs_1.readJsonFile)(overridesPath);
+    const parsed = OVERRIDES_SCHEMA.parse(payload);
+    return {
+        schemaVersion: parsed.schemaVersion ?? constants_1.SCHEMA_VERSION,
+        generatedAt: parsed.generatedAt ?? new Date().toISOString(),
+        mapId: parsed.mapId ?? mapId,
+        serviceMetadata: parsed.serviceMetadata,
+        assertedNodes: parsed.assertedNodes,
+        assertedEdges: parsed.assertedEdges,
+        suppressedEdges: parsed.suppressedEdges,
+    };
+}
+function applyOverrides(overrides, modelNodes, modelEdges) {
+    const errors = [];
+    const warnings = [];
+    const nodes = [...modelNodes];
+    const edges = [...modelEdges];
+    const nodeMap = new Map(nodes.map((node) => [node.id, node]));
+    for (const [serviceName, metadata] of Object.entries(overrides.serviceMetadata)) {
+        const id = `service:${serviceName}`;
+        const node = nodeMap.get(id);
+        if (!node) {
+            errors.push(`Override serviceMetadata references unknown service '${serviceName}'.`);
+            continue;
+        }
+        node.metadata = {
+            ...(node.metadata ?? {}),
+            ...metadata,
+        };
+        node.provenance = {
+            source: 'declared',
+            confidence: Math.max(node.provenance.confidence, 0.9),
+            evidence: [...new Set([...node.provenance.evidence, `override:serviceMetadata:${serviceName}`])],
+        };
+        nodeMap.set(id, node);
+    }
+    for (const assertedNode of overrides.assertedNodes) {
+        const existing = nodeMap.get(assertedNode.id);
+        if (existing) {
+            if (existing.type !== assertedNode.type) {
+                errors.push(`assertedNode '${assertedNode.id}' conflicts with existing type '${existing.type}' (override type '${assertedNode.type}').`);
+                continue;
+            }
+            existing.label = assertedNode.label;
+            existing.metadata = {
+                ...(existing.metadata ?? {}),
+                ...(assertedNode.metadata ?? {}),
+            };
+            existing.provenance = {
+                source: 'override',
+                confidence: 0.98,
+                evidence: [...new Set([...existing.provenance.evidence, `override:assertedNode:${assertedNode.id}`])],
+            };
+            nodeMap.set(assertedNode.id, existing);
+            continue;
+        }
+        const created = {
+            ...assertedNode,
+            provenance: {
+                source: 'override',
+                confidence: 0.98,
+                evidence: [`override:assertedNode:${assertedNode.id}`],
+            },
+        };
+        nodeMap.set(created.id, created);
+    }
+    const resolvedNodes = [...nodeMap.values()];
+    const resolvedNodeMap = new Map(resolvedNodes.map((node) => [node.id, node]));
+    const resolvedEdges = [...edges];
+    for (const assertedEdge of overrides.assertedEdges) {
+        const from = toNodeRef(assertedEdge.from, resolvedNodeMap);
+        const to = toNodeRef(assertedEdge.to, resolvedNodeMap);
+        if (!from || !to) {
+            errors.push(`assertedEdge '${assertedEdge.from} -> ${assertedEdge.to}' references unknown node(s). Add assertedNodes first or use canonical IDs.`);
+            continue;
+        }
+        resolvedEdges.push({
+            from,
+            to,
+            relation: assertedEdge.relation,
+            metadata: {
+                ...(assertedEdge.metadata ?? {}),
+                inferredFrom: 'override_asserted_edge',
+            },
+            provenance: {
+                source: 'override',
+                confidence: 0.98,
+                evidence: [`override:assertedEdge:${from}|${to}|${assertedEdge.relation}`],
+            },
+        });
+    }
+    for (const suppressed of overrides.suppressedEdges) {
+        const from = toNodeRef(suppressed.from, resolvedNodeMap);
+        const to = toNodeRef(suppressed.to, resolvedNodeMap);
+        if (!from || !to) {
+            errors.push(`suppressedEdge '${suppressed.from} -> ${suppressed.to}' references unknown node(s). Use canonical IDs or add assertedNodes first.`);
+            continue;
+        }
+        const before = resolvedEdges.length;
+        for (let i = resolvedEdges.length - 1; i >= 0; i -= 1) {
+            const edge = resolvedEdges[i];
+            if (edge.from === from && edge.to === to && edge.relation === suppressed.relation) {
+                resolvedEdges.splice(i, 1);
+            }
+        }
+        if (before === resolvedEdges.length) {
+            warnings.push(`suppressedEdge '${from} -> ${to} (${suppressed.relation})' did not match any existing edge.`);
+        }
+    }
+    return {
+        nodes: dedupeNodes([...resolvedNodes]),
+        edges: dedupeEdges(resolvedEdges),
+        errors,
+        warnings,
+    };
+}
+function buildArchitectureModel(mapId, db, cwd = process.cwd()) {
+    const scope = (0, scope_1.loadScopeManifest)(mapId, cwd);
+    const repoMap = new Map((0, repoRegistry_1.listAllRepos)(db).map((repo) => [repo.name, repo]));
+    const serviceMap = (0, mapBuilder_1.buildServiceMapArtifact)(mapId, scope, repoMap);
+    const contracts = (0, contracts_1.extractContracts)(mapId, scope, repoMap);
+    const nodes = serviceMap.nodes.map((node) => ({
+        ...node,
+        provenance: {
+            source: 'inferred',
+            confidence: node.type === 'service' || node.type === 'repo' ? 0.95 : 0.8,
+            evidence: [`service-map:${node.id}`],
+        },
+    }));
+    const edges = serviceMap.edges.map((edge) => ({
+        ...edge,
+        provenance: {
+            source: 'inferred',
+            confidence: edge.relation === 'owns' ? 0.95 : 0.75,
+            evidence: [`service-map:${edge.from}->${edge.to}:${edge.relation}`],
+        },
+    }));
+    const warnings = [];
+    for (const repoName of scope.effective) {
+        const repo = repoMap.get(repoName);
+        if (!repo?.localPath || !node_fs_1.default.existsSync(repo.localPath)) {
+            warnings.push(`Repository '${repoName}' is in scope but has no local path; deep inference may be partial.`);
+            continue;
+        }
+        inferInfra(repo, nodes, edges);
+    }
+    addConsumerSignals(contracts, serviceMap.edges, nodes, edges);
+    const overridesPath = ensureArchitectureOverridesFile(mapId, cwd);
+    const overrides = loadArchitectureOverrides(mapId, cwd);
+    const applied = applyOverrides(overrides, dedupeNodes(nodes), dedupeEdges(edges));
+    warnings.push(...applied.warnings);
+    const confidences = applied.edges.map((edge) => edge.provenance.confidence);
+    const coverageConfidence = confidences.length === 0 ? 0 : Number((confidences.reduce((sum, c) => sum + c, 0) / confidences.length).toFixed(3));
+    return {
+        schemaVersion: constants_1.SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        mapId,
+        org: scope.org,
+        overridesPath: node_path_1.default.relative(cwd, overridesPath),
+        coverageConfidence,
+        errors: applied.errors,
+        warnings,
+        nodes: applied.nodes,
+        edges: applied.edges,
+    };
+}
+function modelValidation(model, contracts) {
+    const errors = [];
+    const warnings = [];
+    const services = model.nodes.filter((node) => node.type === 'service');
+    const serviceContracts = new Set(contracts.map((record) => record.repo));
+    for (const service of services) {
+        const serviceId = service.id.replace('service:', '');
+        const relations = model.edges.filter((edge) => edge.from === service.id || edge.to === service.id);
+        const nonOwnership = relations.filter((edge) => edge.relation !== 'owns');
+        if (nonOwnership.length === 0) {
+            warnings.push(`Service '${service.label}' has no communication edges outside ownership links.`);
+        }
+        if (!serviceContracts.has(serviceId)) {
+            warnings.push(`Service '${service.label}' has no detected contract files.`);
+        }
+    }
+    for (const signal of model.errors) {
+        errors.push(signal);
+    }
+    const inferredEdges = model.edges.filter((edge) => edge.provenance.source === 'inferred').length;
+    const overrideEdges = model.edges.filter((edge) => edge.provenance.source === 'override').length;
+    return {
+        schemaVersion: constants_1.SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        mapId: model.mapId,
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        stats: {
+            serviceCount: services.length,
+            edgeCount: model.edges.length,
+            inferredEdges,
+            overrideEdges,
+        },
+    };
+}
+function mermaidId(nodeId) {
+    return nodeId.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+function renderMermaid(nodes, edges, title) {
+    const lines = ['flowchart LR'];
+    if (title) {
+        lines.push(`  %% ${title}`);
+    }
+    for (const node of nodes) {
+        lines.push(`  ${mermaidId(node.id)}["${node.label}"]`);
+    }
+    for (const edge of edges) {
+        lines.push(`  ${mermaidId(edge.from)} -->|"${edge.relation}"| ${mermaidId(edge.to)}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderArchitectureIndexMarkdown(mapId, model, validation, systemLandscapeMermaid, containerMermaid, services) {
+    const lines = [
+        `# Architecture Pack: ${mapId}`,
+        '',
+        `- Generated: ${model.generatedAt}`,
+        `- Coverage confidence: ${model.coverageConfidence}`,
+        `- Override file: ${model.overridesPath}`,
+        `- Services: ${services.length}`,
+        `- Nodes: ${model.nodes.length}`,
+        `- Edges: ${model.edges.length}`,
+        '',
+        '## Facts vs Inferred',
+        '',
+        '- Facts: repository scope, discovered contracts, registered repos/local paths.',
+        '- Inferred: communication edges from dependency/config signals.',
+        '- Overrides: explicit asserted/suppressed relationships from architecture-overrides.json.',
+        '',
+        '## Validation',
+        '',
+        `- Valid: ${validation.valid ? 'yes' : 'no'}`,
+        `- Errors: ${validation.errors.length}`,
+        `- Warnings: ${validation.warnings.length}`,
+        '',
+    ];
+    if (validation.errors.length > 0) {
+        lines.push('### Validation Errors');
+        lines.push('');
+        for (const err of validation.errors) {
+            lines.push(`- ${err}`);
+        }
+        lines.push('');
+    }
+    if (validation.warnings.length > 0) {
+        lines.push('### Validation Warnings');
+        lines.push('');
+        for (const warning of validation.warnings.slice(0, 30)) {
+            lines.push(`- ${warning}`);
+        }
+        lines.push('');
+    }
+    lines.push('## System Landscape');
+    lines.push('');
+    lines.push('```mermaid');
+    lines.push(systemLandscapeMermaid.trimEnd());
+    lines.push('```');
+    lines.push('');
+    lines.push('## Container Communication');
+    lines.push('');
+    lines.push('```mermaid');
+    lines.push(containerMermaid.trimEnd());
+    lines.push('```');
+    lines.push('');
+    lines.push('## Service Deep Dives');
+    lines.push('');
+    for (const service of services) {
+        const serviceId = service.id.replace('service:', '');
+        lines.push(`- [${service.label}](./services/${serviceId}.md)`);
+    }
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+function renderServiceDoc(service, contracts, contextDiagram, contractDiagram, model) {
+    const serviceId = service.id.replace('service:', '');
+    const serviceContracts = contracts.filter((contract) => contract.repo === serviceId);
+    const relatedEdges = model.edges.filter((edge) => edge.from === service.id || edge.to === service.id);
+    const repoNode = model.nodes.find((node) => node.id === `repo:${serviceId}`);
+    const repoPath = String(repoNode?.metadata?.['localPath'] ?? 'not-registered');
+    const repoHtmlUrl = typeof repoNode?.metadata?.['htmlUrl'] === 'string' ? String(repoNode.metadata['htmlUrl']) : undefined;
+    const defaultBranch = typeof repoNode?.metadata?.['defaultBranch'] === 'string' && String(repoNode.metadata['defaultBranch']).length > 0
+        ? String(repoNode.metadata['defaultBranch'])
+        : 'main';
+    const consumersByContract = new Map();
+    for (const edge of model.edges) {
+        if (!edge.to.startsWith('api:') && !edge.to.startsWith('event:')) {
+            continue;
+        }
+        if (!edge.from.startsWith('service:')) {
+            continue;
+        }
+        const consumer = edge.from.replace('service:', '');
+        const current = consumersByContract.get(edge.to) ?? [];
+        if (!current.includes(consumer)) {
+            current.push(consumer);
+        }
+        consumersByContract.set(edge.to, current.sort((a, b) => a.localeCompare(b)));
+    }
+    function contractSource(contract) {
+        if (!repoHtmlUrl) {
+            return `\`${contract.sourcePointer}\``;
+        }
+        const url = `${repoHtmlUrl.replace(/\/$/, '')}/blob/${defaultBranch}/${contract.path}`;
+        return `[${contract.path}](${url})`;
+    }
+    const lines = [
+        `# Service Architecture: ${service.label}`,
+        '',
+        `- Generated: ${model.generatedAt}`,
+        `- Map: ${model.mapId}`,
+        `- Coverage confidence: ${model.coverageConfidence}`,
+        `- Owner: ${String(service.metadata?.['owner'] ?? 'unknown')}`,
+        `- Criticality: ${String(service.metadata?.['criticality'] ?? 'unknown')}`,
+        `- Business context: ${String(service.metadata?.['businessContext'] ?? 'not declared')}`,
+        `- Repo path: ${repoPath}`,
+        '',
+        '## Facts vs Inferred',
+        '',
+        '- Facts: service membership, contract files, explicit overrides.',
+        '- Inferred: integration relationships from dependencies and config signals.',
+        '',
+        '## Service Context Diagram',
+        '',
+        '```mermaid',
+        contextDiagram.trimEnd(),
+        '```',
+        '',
+        '## Contract Interaction Diagram',
+        '',
+        '```mermaid',
+        contractDiagram.trimEnd(),
+        '```',
+        '',
+        '## Contract Catalog',
+        '',
+        '| Type | Contract | Version | Compatibility | Producers | Consumers |',
+        '|---|---|---|---|---|---|',
+        ...serviceContracts.map((contract) => {
+            const consumers = consumersByContract.get(contractNodeId(contract)) ?? [];
+            return `| ${contract.type} | ${contractSource(contract)} | ${contract.version ?? '-'} | ${contract.compatibilityStatus} | ${contract.producers.join(', ') || '-'} | ${consumers.join(', ') || '-'} |`;
+        }),
+        '',
+        '## Migration Guidance',
+        '',
+        '- Review the source contract docs linked above for rollout and compatibility instructions.',
+        '- Validate all consuming services against changed contract versions before cutover.',
+        '',
+        '## Integration Signals',
+        '',
+        ...relatedEdges.map((edge) => `- ${edge.from} ${edge.relation} ${edge.to} (source=${edge.provenance.source}, confidence=${edge.provenance.confidence})`),
+        '',
+    ];
+    return `${lines.join('\n')}\n`;
+}
+function serviceNodes(model) {
+    return model.nodes
+        .filter((node) => node.type === 'service')
+        .sort((a, b) => a.label.localeCompare(b.label));
+}
+function renderSystemLandscape(model) {
+    const allowedTypes = new Set(['service', 'external', 'datastore', 'queue', 'team']);
+    const nodes = model.nodes.filter((node) => allowedTypes.has(node.type));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = model.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+    return renderMermaid(nodes, edges, 'System Landscape');
+}
+function renderContainerCommunication(model) {
+    const allowedTypes = new Set(['service', 'api', 'event', 'datastore', 'queue', 'external']);
+    const nodes = model.nodes.filter((node) => allowedTypes.has(node.type));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = model.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+    return renderMermaid(nodes, edges, 'Container Communication');
+}
+function renderServiceContextDiagram(model, serviceId) {
+    const serviceNodeId = `service:${serviceId}`;
+    const included = new Set([serviceNodeId]);
+    for (const edge of model.edges) {
+        if (edge.from === serviceNodeId) {
+            included.add(edge.to);
+        }
+        if (edge.to === serviceNodeId) {
+            included.add(edge.from);
+        }
+    }
+    const disallowed = new Set(['api', 'event', 'repo']);
+    const nodes = model.nodes.filter((node) => included.has(node.id) && !disallowed.has(node.type));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = model.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+    return renderMermaid(nodes, edges, `Service Context: ${serviceId}`);
+}
+function renderServiceContractsDiagram(model, serviceId) {
+    const serviceNodeId = `service:${serviceId}`;
+    const ownedContracts = new Set();
+    for (const edge of model.edges) {
+        if (edge.from !== serviceNodeId) {
+            continue;
+        }
+        if (!edge.to.startsWith('api:') && !edge.to.startsWith('event:')) {
+            continue;
+        }
+        ownedContracts.add(edge.to);
+    }
+    const included = new Set([serviceNodeId, ...ownedContracts]);
+    for (const edge of model.edges) {
+        if (ownedContracts.has(edge.to)) {
+            included.add(edge.from);
+        }
+    }
+    const nodes = model.nodes.filter((node) => included.has(node.id));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = model.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+    return renderMermaid(nodes, edges, `Service Contracts: ${serviceId}`);
+}
+function validateArchitecture(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const mapId = options.mapId;
+    const model = buildArchitectureModel(mapId, options.db, cwd);
+    const scope = (0, scope_1.loadScopeManifest)(mapId, cwd);
+    const repoMap = new Map((0, repoRegistry_1.listAllRepos)(options.db).map((repo) => [repo.name, repo]));
+    const contracts = (0, contracts_1.extractContracts)(mapId, scope, repoMap);
+    return modelValidation(model, contracts);
+}
+function generateArchitecturePack(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const depth = options.depth ?? 'full';
+    const mapId = options.mapId;
+    const model = buildArchitectureModel(mapId, options.db, cwd);
+    const scope = (0, scope_1.loadScopeManifest)(mapId, cwd);
+    const repoMap = new Map((0, repoRegistry_1.listAllRepos)(options.db).map((repo) => [repo.name, repo]));
+    const contracts = (0, contracts_1.extractContracts)(mapId, scope, repoMap);
+    const validation = modelValidation(model, contracts);
+    const mapArchitectureDir = node_path_1.default.join((0, paths_1.getMapDir)(mapId, cwd), 'architecture');
+    const docsDir = node_path_1.default.join(cwd, 'docs', 'architecture', mapId);
+    const diagramsDir = node_path_1.default.join(docsDir, 'diagrams');
+    const servicesDocsDir = node_path_1.default.join(docsDir, 'services');
+    const modelPath = node_path_1.default.join(mapArchitectureDir, 'model.json');
+    const validationPath = node_path_1.default.join(mapArchitectureDir, 'validation.json');
+    const overridesPath = ensureArchitectureOverridesFile(mapId, cwd);
+    (0, fs_1.writeJsonFile)(modelPath, model);
+    (0, fs_1.writeJsonFile)(validationPath, validation);
+    const systemLandscape = renderSystemLandscape(model);
+    const containerCommunication = renderContainerCommunication(model);
+    const systemLandscapePath = node_path_1.default.join(diagramsDir, 'system-landscape.mmd');
+    const containerPath = node_path_1.default.join(diagramsDir, 'container-communication.mmd');
+    const output = {
+        modelPath,
+        overridesPath,
+        baselineArtifacts: {
+            serviceMapPath: node_path_1.default.join(cwd, 'maps', mapId, 'service-map.json'),
+            contractsPath: node_path_1.default.join(cwd, 'maps', mapId, 'contracts.json'),
+            architectureDocPath: node_path_1.default.join(cwd, 'docs', 'architecture', `${mapId}.md`),
+        },
+        serviceDocPaths: [],
+        generatedServices: [],
+        generatedAt: model.generatedAt,
+        validation,
+        indexDocPath: undefined,
+        overviewPath: undefined,
+    };
+    if (!options.serviceId) {
+        (0, fs_1.writeTextFile)(systemLandscapePath, systemLandscape);
+        (0, fs_1.writeTextFile)(containerPath, containerCommunication);
+        const services = serviceNodes(model);
+        const indexMarkdown = renderArchitectureIndexMarkdown(mapId, model, validation, systemLandscape, containerCommunication, services);
+        const indexDocPath = node_path_1.default.join(docsDir, 'index.md');
+        const overviewPath = node_path_1.default.join(mapArchitectureDir, 'overview.md');
+        (0, fs_1.writeTextFile)(indexDocPath, indexMarkdown);
+        (0, fs_1.writeTextFile)(overviewPath, indexMarkdown);
+        output.indexDocPath = indexDocPath;
+        output.overviewPath = overviewPath;
+    }
+    if (depth !== 'org') {
+        const services = serviceNodes(model)
+            .map((node) => node.id.replace('service:', ''))
+            .filter((serviceId) => (options.serviceId ? serviceId === options.serviceId : true));
+        if (options.serviceId && services.length === 0) {
+            throw new Error(`Unknown service '${options.serviceId}' for map '${mapId}'.`);
+        }
+        for (const serviceId of services) {
+            const serviceNode = model.nodes.find((node) => node.id === `service:${serviceId}`);
+            if (!serviceNode) {
+                continue;
+            }
+            const contextMermaid = renderServiceContextDiagram(model, serviceId);
+            const contractsMermaid = renderServiceContractsDiagram(model, serviceId);
+            const serviceDoc = renderServiceDoc(serviceNode, contracts, contextMermaid, contractsMermaid, model);
+            const serviceDocPath = node_path_1.default.join(servicesDocsDir, `${serviceId}.md`);
+            const serviceDiagramDir = node_path_1.default.join(servicesDocsDir, serviceId);
+            (0, fs_1.writeTextFile)(serviceDocPath, serviceDoc);
+            (0, fs_1.writeTextFile)(node_path_1.default.join(serviceDiagramDir, 'context.mmd'), contextMermaid);
+            (0, fs_1.writeTextFile)(node_path_1.default.join(serviceDiagramDir, 'contracts.mmd'), contractsMermaid);
+            output.serviceDocPaths.push(serviceDocPath);
+            output.generatedServices.push(serviceId);
+        }
+    }
+    return output;
+}

package/dist/lib/artifactMigration.js

@@ -8,6 +8,8 @@ exports.isManagedArtifactPayload = isManagedArtifactPayload;
 const node_path_1 = __importDefault(require("node:path"));
 const MANAGED_ARTIFACT_PATTERNS = [
     /^maps\/[^/]+\/(scope|service-map|contracts)\.json$/,
+    /^maps\/[^/]+\/architecture\/(model|validation)\.json$/,
+    /^maps\/[^/]+\/architecture-overrides\.json$/,
     /^plans\/reviews\/.*\.json$/,
     /^plans\/.*-service-proposal\.json$/,
     /^handoffs\/.*\.json$/,

package/dist/lib/bootstrap.js

@@ -21,8 +21,8 @@ function createBootstrapStructure(org, repoName, cwd = process.cwd()) {
         '  build-test:',
         '    runs-on: ubuntu-latest',
         '    steps:',
-        '      - uses: actions/checkout@v4',
-        '      - uses: actions/setup-node@v4',
+        '      - uses: actions/checkout@v5',
+        '      - uses: actions/setup-node@v5',
         '        with:',
         '          node-version: 20',
         '      - run: npm ci',

package/dist/lib/mapBuilder.js

@@ -34,7 +34,7 @@ function readPackageDependencies(repoPath) {
         const data = JSON.parse(node_fs_1.default.readFileSync(packagePath, 'utf8'));
         const names = new Set([
             ...Object.keys(data.dependencies ?? {}),
-            ...Object.keys(data.devDependencies ?? {}),
+            ...Object.keys(data.optionalDependencies ?? {}),
             ...Object.keys(data.peerDependencies ?? {}),
         ]);
         return [...names];
@@ -91,6 +91,8 @@ function buildServiceMapArtifact(mapId, scope, reposByName) {
             metadata: {
                 source: repo?.source ?? 'github',
                 localPath: repo?.localPath,
+                htmlUrl: repo?.htmlUrl,
+                defaultBranch: repo?.defaultBranch,
             },
         });
         edges.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdx-cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "System Design Intelligence CLI",
   "type": "commonjs",
   "bin": {