arkgate 3.7.0 → 3.8.1

package/bin/ark-shared.mjs

@@ -6,26 +6,18 @@ import {
   withArkConfigMetadata,
 } from './lib/config-contract.mjs';
 import { collectForbiddenCapabilityUses } from './lib/analysis-engine.mjs';
-import { looksLikeArkIntent } from './lib/source-policy.mjs';
+import {
+  DEFAULT_INTENT_PREFIXES as DOMAIN_DEFAULT_INTENT_PREFIXES,
+  looksLikeArkIntent,
+  resolveIntentLayer as resolveConfiguredIntentLayer,
+} from './lib/source-policy.mjs';
 
 /**
  * Default intent-prefix map shared by both CLIs and the ark-mcp write-path gate. The rule
  * matrix comes from the generated Domain config contract above. Prefixes mirror the runtime
  * profile but stay in this standalone CLI module because the CLIs run without a build step.
  */
-export const DEFAULT_INTENT_PREFIXES = [
-  { layer: 'DomainModel', prefixes: ['Domain.'] },
-  { layer: 'ApplicationOrchestration', prefixes: ['Application.'] },
-  { layer: 'PersistenceAdapters', prefixes: ['Adapter.Persistence.', 'Adapter.Repository.'] },
-  { layer: 'IntegrationAdapters', prefixes: ['Adapter.Integration.', 'Adapter.External.'] },
-  { layer: 'WorkflowSagaEngine', prefixes: ['Workflow.'] },
-  { layer: 'BackgroundJobsScheduling', prefixes: ['Job.'] },
-  { layer: 'PresentationAdapters', prefixes: ['Presentation.', 'Adapter.Presentation.', 'Adapter.Api.'] },
-  { layer: 'ReportingReadModels', prefixes: ['Reporting.'] },
-  { layer: 'ExtensibilityMetadata', prefixes: ['Metadata.'] },
-  { layer: 'SecurityAuditObservability', prefixes: ['Security.', 'Audit.', 'Observability.'] },
-  { layer: 'Kernel', prefixes: ['Kernel.'] },
-];
+export const DEFAULT_INTENT_PREFIXES = DOMAIN_DEFAULT_INTENT_PREFIXES;
 
 export const DEFAULT_LAYER_DIRECTORIES = {
   DomainModel: ['domain'],
@@ -447,10 +439,6 @@ export {
   isScanExcludedRelative,
 } from './ark-layer-match.mjs';
 
-function normalizePrefix(prefix) {
-  return prefix.endsWith('.') ? prefix : `${prefix}.`;
-}
-
 /**
  * Resolve an intent name to its layer using the SAME semantics as
  * ArchitectureProfile.resolveLayer in src/kernel/layers/ArchitectureProfile.ts (which the
@@ -460,16 +448,7 @@ function normalizePrefix(prefix) {
  * the write-path gate classify identically. `layers` is an array of { name, prefixes }.
  */
 export function resolveIntentLayer(intent, layers) {
-  const normalized = layers.map((layer) => ({
-    name: layer.name,
-    prefixes: (layer.prefixes ?? []).map(normalizePrefix),
-  }));
-  const sorted = [...normalized].sort((a, b) => {
-    const maxA = Math.max(0, ...a.prefixes.map((p) => p.length));
-    const maxB = Math.max(0, ...b.prefixes.map((p) => p.length));
-    return maxB - maxA;
-  });
-  return sorted.find((layer) => layer.prefixes.some((prefix) => intent.startsWith(prefix)))?.name;
+  return resolveConfiguredIntentLayer(intent, layers);
 }
 
 export function looksLikeIntent(value) {
@@ -489,7 +468,8 @@ export {
 
 /**
  * Normalize a required/imported TypeScript module for ark-check's host.
- * TS 5/6 expose `sys` on the root export. Early TS 7 / some ESM interop shapes
+ * TS 5/6 expose `sys` and the AST helpers used by the scanner on the root export. Early TS 7 /
+ * some ESM interop shapes
  * may nest under `.default` or omit `sys` — those are unusable for resolve/scan
  * and must fall through to a JS-API-compatible TypeScript (Ark's own or 5/6).
  *
@@ -508,7 +488,8 @@ export function usableTypescript(mod) {
       ts.sys &&
       typeof ts.sys.fileExists === 'function' &&
       typeof ts.createSourceFile === 'function' &&
-      typeof ts.resolveModuleName === 'function'
+      typeof ts.resolveModuleName === 'function' &&
+      typeof ts.isInTypeQuery === 'function'
     ) {
       return ts;
     }
@@ -537,6 +518,9 @@ export function typescriptUsabilityHint(mod) {
   if (typeof ts.sys.fileExists !== 'function') return 'ts.sys.fileExists is not a function';
   if (typeof ts.createSourceFile !== 'function') return 'missing createSourceFile (AST API)';
   if (typeof ts.resolveModuleName !== 'function') return 'missing resolveModuleName';
+  if (typeof ts.isInTypeQuery !== 'function') {
+    return 'missing isInTypeQuery (requires a TypeScript 5/6 analysis host)';
+  }
   return 'unknown shape incompatibility';
 }
 
@@ -1732,14 +1716,26 @@ export function formatArchitectureRecommendationHuman(recommendation) {
 
 export const ADOPTION_PLAN_FILENAME = 'ark-adoption-plan.json';
 
-const GALLERY_STARTER_BY_ARCHETYPE = {
-  'crud-product': 'examples/crud-product-starter/',
-  'api-backend': 'examples/api-backend-starter/',
-  'worker-pipeline': 'examples/worker-pipeline-starter/',
-  'multi-app-workspace': 'examples/multi-app-workspace-starter/',
-  'vertical-slice-product': 'examples/vertical-slice-starter/',
-  'ddd-bounded-contexts': 'examples/ddd-context-starter/',
-};
+function galleryStarter(archetype, directory = archetype, generatedPreset) {
+  return Object.freeze({
+    archetype,
+    directory: `examples/${directory}-starter`,
+    ...(generatedPreset ? { generatedPreset } : {}),
+  });
+}
+
+export const GALLERY_STARTERS = Object.freeze([
+  galleryStarter('crud-product'),
+  galleryStarter('api-backend'),
+  galleryStarter('worker-pipeline'),
+  galleryStarter('multi-app-workspace'),
+  galleryStarter('vertical-slice-product', 'vertical-slice', 'vertical-slice'),
+  galleryStarter('ddd-bounded-contexts', 'ddd-context', 'ddd-bounded-contexts'),
+]);
+
+const GALLERY_STARTER_BY_ARCHETYPE = Object.fromEntries(
+  GALLERY_STARTERS.map(({ archetype, directory }) => [archetype, `${directory}/`])
+);
 
 /** Enthusiast pack id for a named preset, or null when none ships. */
 export function policyPackIdForPreset(preset) {

package/bin/ark.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import readline from 'node:readline/promises';
@@ -21,8 +20,10 @@ import {
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import { applyStartPreview, planStart, renderStartPreview } from './lib/start-preview.mjs';
+import { runUpgradeCommand } from './lib/upgrade-command.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
+import { loadTypeScript } from './lib/typescript-host.mjs';
 import {
   prepareChangeFromRoot,
   readChangeMapFile,
@@ -70,6 +71,8 @@ function parseArgs(argv) {
     install: true,
     installExplicit: false,
     apply: false,
+    acceptConflicts: false,
+    planDigest: undefined,
     json: false,
     internalApply: false,
     skipPackageManager: false,
@@ -104,6 +107,8 @@ function parseArgs(argv) {
       args.installExplicit = true;
     }
     else if (arg === '--apply') args.apply = true;
+    else if (arg === '--accept-conflicts') args.acceptConflicts = true;
+    else if (arg === '--plan-digest') args.planDigest = requireValue(arg, i++);
     else if (arg === '--json') args.json = true;
     else if (arg === '--internal-apply') args.internalApply = true;
     else if (arg === '--skip-package-manager') args.skipPackageManager = true;
@@ -112,6 +117,8 @@ function parseArgs(argv) {
     else if (arg === '--config') args.config = requireValue(arg, i++);
     else if (arg === '--changes') args.changes = requireValue(arg, i++);
     else if (arg === '--change-map') args.changeMap = requireValue(arg, i++);
+    else if (arg === '--manifest') args.manifest = requireValue(arg, i++);
+    else if (arg === '--tsconfig') args.tsconfig = requireValue(arg, i++);
     else if (arg === '--archetype') args.archetype = requireValue(arg, i++);
     else if (arg === '--tools') args.tools = requireValue(arg, i++);
     else if (arg === '--require-write-hook') {
@@ -131,17 +138,17 @@ function usage() {
   ark start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
   ark init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture]
               [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
-  ark upgrade [--root <project>] [--no-install] [--no-strict]
-  ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--json]
+  ark upgrade [--root <project>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--json] [--no-install] [--no-strict]
+  ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--manifest <manifest.json>] [--tsconfig <tsconfig.json>] [--json]
 
 Commands:
   start     New here? Analyze and preview the complete setup. Read-only unless --apply.
   init      Configure Ark project enforcement with explicit prompts.
-  upgrade   One command to update Ark: bump the package to @latest, refresh gate
-            templates + /ark-* skills (and Codex home prompts), migrate command
-            runners to this project's package manager, then run the strict check.
-  preflight Validate one atomic create/update/delete set without writing project files.
+  upgrade   Preview identity-proven Ark-managed asset updates. With package install,
+            --apply bumps to @latest and recomputes the preview; a second explicit
+            --apply --no-install applies those exact bytes and verifies them.
             (alias: ark update)
+  preflight Validate one atomic create/update/delete set without writing project files.
 
 Options:
   --yes        Non-interactive defaults: create config if needed, install gate templates, run strict check.
@@ -150,8 +157,11 @@ Options:
   --no-strict  Skip the final strict ark-check run.
   --install    Add arkgate to package.json explicitly before applying a start plan.
   --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
-  --apply       Apply the mutations shown by the start preview.
-  --json        Emit the start preview as deterministic machine-readable JSON.
+  --apply       Apply a start plan; for upgrade, update/repreview or apply with --no-install.
+  --accept-conflicts
+                Allow upgrade to recreate deleted managed assets or replace recorded conflicts.
+  --plan-digest Digest emitted by an upgrade preview; required to apply managed bytes.
+  --json        Emit the start/upgrade preview as deterministic machine-readable JSON.
   --preset     Start from a named architecture preset instead of detection.
   --archetype  Application shape from templates/architecture-playbook.json (maps to the matching preset).
                Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
@@ -199,60 +209,6 @@ function runCommand(command, commandArgs, cwd) {
   return result.status ?? 1;
 }
 
-// `ark upgrade`: the one command that replaces the "install @latest && install-agent-gates
-// --skills-only --force && ... --codex-home --force && ... --migrate-commands && check" chain.
-// Each step reruns ark-check as a fresh process, so the refresh runs from the freshly-installed
-// version, not this (now-older) process.
-async function upgrade(args) {
-  const root = args.root;
-  console.log('Ark upgrade — updating the package, gates, skills, and command runners.');
-
-  if (args.install) {
-    const [command, commandArgs] = packageInstallArgv(root);
-    console.log(`\n1/4  Updating the package: ${command} ${commandArgs.join(' ')}`);
-    const status = runCommand(command, commandArgs, root);
-    if (status !== 0) {
-      console.error(
-        `\nPackage update failed (exit ${status}). Fix the install and re-run, or use ` +
-          '`ark upgrade --no-install` to refresh gates/skills against the installed version.'
-      );
-      return status;
-    }
-  } else {
-    console.log('\n1/4  Skipping package install (--no-install).');
-  }
-
-  console.log('\n2/4  Refreshing agent gates + /ark-* skills…');
-  let status = runArkCheck(['--root', root, '--install-agent-gates'], { cwd: root });
-  if (status !== 0) return status;
-
-  // Codex home skill catalog is $CODEX_HOME/skills/<name>/SKILL.md (repo uses .agents/skills/).
-  // Refresh home skills when a Codex home exists. Project MCP is installed above in
-  // .codex/config.toml. Non-fatal: a permission error (e.g. sandbox) shouldn't fail upgrade.
-  const codexHomeBase = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  if (fs.existsSync(codexHomeBase)) {
-    console.log(`\n     Refreshing Codex home (${codexHomeBase})…`);
-    runArkCheck(
-      ['--root', root, '--install-agent-gates', '--skills-only', '--codex-home', '--force'],
-      { cwd: root }
-    );
-  }
-
-  console.log('\n3/4  Migrating command runners to this project’s package manager…');
-  status = runArkCheck(['--root', root, '--install-agent-gates', '--migrate-commands'], { cwd: root });
-  if (status !== 0) return status;
-
-  if (!args.strict) {
-    console.log('\n4/4  Skipping the strict check (--no-strict). Upgrade complete.');
-    return 0;
-  }
-  console.log('\n4/4  Verifying architecture…');
-  return runArkCheck(
-    ['--root', root, '--config', 'ark.config.json', '--strict-merge'],
-    { cwd: root }
-  );
-}
-
 function runArkCheck(args, options = {}) {
   const result = spawnSync(process.execPath, [arkCheck, ...args], {
     cwd: options.cwd,
@@ -790,9 +746,12 @@ async function main() {
   }
   if (
     args.command !== 'preflight' &&
-    (args.changes || args.changeMap || args.config !== 'ark.config.json')
+    (args.changes || args.changeMap || args.manifest || args.tsconfig ||
+      args.config !== 'ark.config.json')
   ) {
-    console.error('--changes, --change-map, and --config are supported by ark preflight.');
+    console.error(
+      '--changes, --change-map, --config, --manifest, and --tsconfig are supported by ark preflight.'
+    );
     return 2;
   }
   const enforcement = validateHardWriteRequest({
@@ -830,7 +789,7 @@ async function main() {
 
   if (args.command === 'upgrade' || args.command === 'update') {
     try {
-      return await upgrade(args);
+      return runUpgradeCommand(args, { arkCheck, packageInstallArgv, runArkCheck });
     } catch (error) {
       console.error(error instanceof Error ? error.message : String(error));
       return 2;
@@ -848,11 +807,19 @@ async function main() {
         configPath
       ).config;
       const changeMap = args.changeMap ? readChangeMapFile(args.root, args.changeMap) : undefined;
+      const manifestPath = args.manifest
+        ? path.resolve(args.root, args.manifest)
+        : undefined;
+      const manifest = manifestPath ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : undefined;
+      const loadedTypeScript = await loadTypeScript(args.root);
       const result = prepareChangeFromRoot({
         root: args.root,
         config,
         configSource: configPath,
         changes: readChangeSetFile(args.root, args.changes),
+        ts: loadedTypeScript.ts ?? undefined,
+        tsconfig: args.tsconfig,
+        manifest,
         ...(changeMap ? { changeMap: changeMap.input, changeMapSource: changeMap.source } : {}),
       });
       if (args.json) console.log(JSON.stringify(result, null, 2));

package/bin/lib/adapter-contract.mjs

@@ -8,7 +8,7 @@
  * Pure CLI helper (bin/lib/adapter-contract.mjs). Zero Node I/O.
  */
 
-export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.1';
+export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.3';
 function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
@@ -50,6 +50,23 @@ export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
         ...(text(violation.fromLayer) ? { fromLayer: text(violation.fromLayer) } : {}),
         ...(text(violation.toLayer) ? { toLayer: text(violation.toLayer) } : {}),
         ...(typeof violation.typeOnly === 'boolean' ? { typeOnly: violation.typeOnly } : {}),
+        ...(typeof violation.targetTypeOnlyExports === 'boolean'
+            ? { targetTypeOnlyExports: violation.targetTypeOnlyExports }
+            : {}),
+        ...(typeof violation.sourcePureTypeModule === 'boolean'
+            ? { sourcePureTypeModule: violation.sourcePureTypeModule }
+            : {}),
+        ...(typeof violation.namedBindingsTypeOnly === 'boolean'
+            ? { namedBindingsTypeOnly: violation.namedBindingsTypeOnly }
+            : {}),
+        ...(typeof violation.portProofEligible === 'boolean'
+            ? { portProofEligible: violation.portProofEligible }
+            : {}),
+        ...(typeof violation.peerIsolation === 'boolean'
+            ? { peerIsolation: violation.peerIsolation }
+            : {}),
+        ...(text(violation.capability) ? { capability: text(violation.capability) } : {}),
+        ...(text(violation.edgeKind) ? { edgeKind: text(violation.edgeKind) } : {}),
     };
     return {
         ruleId,
@@ -65,25 +82,153 @@ export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
     };
 }
 export function createAdapterResult(input) {
-    return {
+    const completeness = input.completeness ?? 'complete';
+    const mode = input.mode ?? 'lexical-compatibility';
+    if (completeness === 'complete' && (input.completenessReasons?.length ?? 0) > 0) {
+        throw new Error('completenessReasons must be empty when completeness is complete.');
+    }
+    const completenessReasons = completeness === 'complete'
+        ? []
+        : input.completenessReasons && input.completenessReasons.length > 0
+            ? input.completenessReasons.map((reason) => ({
+                code: text(reason.code) ?? 'ANALYSIS_EVIDENCE_INCOMPLETE',
+                message: text(reason.message) ??
+                    `Analysis ${completeness}: required evidence is incomplete.`,
+                ...(text(reason.file) ? { file: text(reason.file) } : {}),
+            }))
+            : [
+                {
+                    code: completeness === 'unavailable'
+                        ? 'ANALYSIS_UNAVAILABLE'
+                        : 'ANALYSIS_EVIDENCE_INCOMPLETE',
+                    message: `Analysis ${completeness}: required evidence is incomplete.`,
+                },
+            ];
+    const evidence = {
+        ...(text(input.policyHash) ? { policyHash: text(input.policyHash) } : {}),
+        ...(text(input.resolverIdentity) ? { resolverIdentity: text(input.resolverIdentity) } : {}),
+        ...(text(input.factsHash) ? { factsHash: text(input.factsHash) } : {}),
+        ...(text(input.candidateTreeHash) ? { candidateTreeHash: text(input.candidateTreeHash) } : {}),
+    };
+    if (mode === 'resolved-candidate-facts' && completeness !== 'unavailable') {
+        for (const field of ['policyHash', 'resolverIdentity', 'factsHash', 'candidateTreeHash']) {
+            if (!evidence[field]) {
+                throw new Error(`${field} is required for resolved ${completeness} adapter evidence.`);
+            }
+        }
+    }
+    const diagnostics = [
+        ...(input.violations ?? []).map((item) => toAdapterDiagnostic(item, 'error')),
+        ...(input.warnings ?? []).map((item) => toAdapterDiagnostic(item, 'warning')),
+    ];
+    const base = {
         schemaVersion: ARK_ANALYSIS_RESULT_SCHEMA_VERSION,
-        valid: input.valid,
-        diagnostics: [
-            ...(input.violations ?? []).map((item) => toAdapterDiagnostic(item, 'error')),
-            ...(input.warnings ?? []).map((item) => toAdapterDiagnostic(item, 'warning')),
-        ],
+        completenessReasons,
+        diagnostics,
     };
+    if (mode === 'resolved-candidate-facts') {
+        if (completeness === 'unavailable') {
+            return {
+                ...base,
+                mode,
+                valid: false,
+                completeness,
+                ...evidence,
+            };
+        }
+        const resolvedEvidence = {
+            policyHash: evidence.policyHash,
+            resolverIdentity: evidence.resolverIdentity,
+            factsHash: evidence.factsHash,
+            candidateTreeHash: evidence.candidateTreeHash,
+        };
+        if (completeness === 'complete') {
+            return {
+                ...base,
+                mode,
+                valid: input.valid,
+                completeness,
+                ...resolvedEvidence,
+            };
+        }
+        return {
+            ...base,
+            mode,
+            valid: false,
+            completeness,
+            ...resolvedEvidence,
+        };
+    }
+    if (completeness === 'complete') {
+        return { ...base, mode, valid: input.valid, completeness, ...evidence };
+    }
+    return { ...base, mode, valid: false, completeness, ...evidence };
 }
 export const ARK_ANALYSIS_RESULT_SCHEMA = {
     $schema: 'https://json-schema.org/draft/2020-12/schema',
-    $id: 'https://unpkg.com/arkgate@2/schemas/ark.analysis-result.schema.json',
+    $id: 'https://unpkg.com/arkgate@3/schemas/ark.analysis-result.schema.json',
     title: 'ArkGate analysis result',
     type: 'object',
     additionalProperties: false,
-    required: ['schemaVersion', 'valid', 'diagnostics'],
+    required: [
+        'schemaVersion',
+        'mode',
+        'valid',
+        'completeness',
+        'completenessReasons',
+        'diagnostics',
+    ],
+    allOf: [
+        {
+            if: {
+                properties: { completeness: { enum: ['partial', 'unavailable'] } },
+                required: ['completeness'],
+            },
+            then: { properties: { valid: { const: false } } },
+        },
+        {
+            if: {
+                properties: {
+                    mode: { const: 'resolved-candidate-facts' },
+                    completeness: { enum: ['complete', 'partial'] },
+                },
+                required: ['mode', 'completeness'],
+            },
+            then: {
+                required: ['policyHash', 'resolverIdentity', 'factsHash', 'candidateTreeHash'],
+            },
+        },
+        {
+            if: {
+                properties: { completeness: { const: 'complete' } },
+                required: ['completeness'],
+            },
+            then: { properties: { completenessReasons: { maxItems: 0 } } },
+            else: { properties: { completenessReasons: { minItems: 1 } } },
+        },
+    ],
     properties: {
         schemaVersion: { const: ARK_ANALYSIS_RESULT_SCHEMA_VERSION },
+        mode: { enum: ['lexical-compatibility', 'resolved-candidate-facts'] },
         valid: { type: 'boolean' },
+        completeness: { enum: ['complete', 'partial', 'unavailable'] },
+        completenessReasons: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['code', 'message'],
+                properties: {
+                    code: { type: 'string', minLength: 1 },
+                    message: { type: 'string', minLength: 1 },
+                    file: { type: 'string', minLength: 1 },
+                },
+            },
+        },
+        policyHash: { type: 'string', minLength: 1 },
+        resolverIdentity: { type: 'string', minLength: 1 },
+        factsHash: { type: 'string', minLength: 1 },
+        candidateTreeHash: { type: 'string', minLength: 1 },
         diagnostics: {
             type: 'array',
             items: {
@@ -112,6 +257,13 @@ export const ARK_ANALYSIS_RESULT_SCHEMA = {
                             fromLayer: { type: 'string' },
                             toLayer: { type: 'string' },
                             typeOnly: { type: 'boolean' },
+                            targetTypeOnlyExports: { type: 'boolean' },
+                            sourcePureTypeModule: { type: 'boolean' },
+                            namedBindingsTypeOnly: { type: 'boolean' },
+                            portProofEligible: { type: 'boolean' },
+                            peerIsolation: { type: 'boolean' },
+                            capability: { type: 'string', minLength: 1 },
+                            edgeKind: { type: 'string', minLength: 1 },
                         },
                     },
                     nextAction: { type: 'string', minLength: 1 },

package/bin/lib/agent-gates.mjs

@@ -120,6 +120,7 @@ export {
 } from './weakest-link.mjs';
 
 export {
+  buildManagedAssetCatalog,
   staleRunnerGateFiles,
   warnLockfileConflict,
   runMigrateCommands,

package/bin/lib/analysis-completeness.mjs

@@ -0,0 +1,28 @@
+/** Shared fail-closed completeness semantics for CLI/MCP Tooling surfaces. */
+
+export const ANALYSIS_COMPLETENESS = Object.freeze({
+  complete: 'complete',
+  partial: 'partial',
+  unavailable: 'unavailable',
+});
+
+export function normalizeAnalysisCompleteness(value) {
+  return value === ANALYSIS_COMPLETENESS.complete ||
+    value === ANALYSIS_COMPLETENESS.partial ||
+    value === ANALYSIS_COMPLETENESS.unavailable
+    ? value
+    : ANALYSIS_COMPLETENESS.unavailable;
+}
+
+export function completenessFromParseHealth(parseHealth) {
+  if (parseHealth?.available !== true) return ANALYSIS_COMPLETENESS.unavailable;
+  return parseHealth.affectedFiles > 0
+    ? ANALYSIS_COMPLETENESS.partial
+    : ANALYSIS_COMPLETENESS.complete;
+}
+
+export function analysisIncompleteStatement(completeness) {
+  return completeness === ANALYSIS_COMPLETENESS.partial
+    ? 'Analysis incomplete: governed parse diagnostics prevent a complete architecture verdict.'
+    : 'Analysis unavailable: no API-compatible TypeScript host could produce architecture evidence.';
+}