nexarch 0.9.28 → 0.9.30

package/dist/commands/init-project.js

@@ -1480,21 +1480,10 @@ export async function initProject(args) {
     if (detectedRepo?.canonicalRepoRef) {
         addRel("depends_on", projectExternalKey, detectedRepo.canonicalRepoRef, 0.95);
     }
-    let graphDiff = null;
+    // In refresh mode the raw graph state (fetched above) is emitted alongside scan results
+    // for the agent to compare — no automated stale/removed determination is made.
     if (refreshMode) {
-        const newRelKeySet = new Set(relationships.map((r) => `${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
-        const currentRelKeySet = new Set(currentOutgoingRels
-            .filter((r) => r.fromEntityExternalKey && r.toEntityExternalKey)
-            .map((r) => `${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
-        const newRelationshipsInDiff = relationships.filter((r) => !currentRelKeySet.has(`${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
-        const staleRelationships = currentOutgoingRels.filter((r) => r.fromEntityExternalKey &&
-            r.toEntityExternalKey &&
-            !newRelKeySet.has(`${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
-        const currentSubPackageKeys = new Set(currentPartOfRels.map((r) => r.fromEntityExternalKey).filter((k) => Boolean(k)));
-        const newSubPackageKeys = new Set(subPackages.map((sp) => sp.externalKey));
-        const removedSubPackageKeys = [...currentSubPackageKeys].filter((k) => !newSubPackageKeys.has(k));
-        graphDiff = { newRelationships: newRelationshipsInDiff, staleRelationships, removedSubPackageKeys };
-        logProgress("refresh.diff", `newRels=${newRelationshipsInDiff.length}, staleRels=${staleRelationships.length}, removedSubPkgs=${removedSubPackageKeys.length}`);
+        logProgress("refresh.graph-state", `outgoing=${currentOutgoingRels.length}, partOf=${currentPartOfRels.length}`);
     }
     if (!asJson)
         console.log(`\nWriting to graph…`);
@@ -1633,13 +1622,52 @@ export async function initProject(args) {
         });
         return {
             status: "enrichment_required",
-            note: "IMPORTANT: Execute ALL pendingSteps before reporting the project as registered. Do not pause or ask for confirmation between steps.",
+            note: refreshMode
+                ? "Execute ALL pendingSteps. In refresh mode, compare graphState vs scanState to identify gaps — do not blindly remove relationships the scanner missed; the scanner cannot detect platforms, integrations, data assets, or application_functions."
+                : "Execute ALL pendingSteps before reporting the project as registered. Do not pause or ask for confirmation between steps.",
             projectEntity: {
                 externalKey: projectExternalKey,
                 entityType: entityTypeOverride,
             },
             pendingSteps,
             readFiles: readmeHints,
+            ...(refreshMode
+                ? {
+                    graphState: {
+                        note: "Current relationships recorded in Nexarch for this project.",
+                        outgoingRelationships: currentOutgoingRels.map((r) => ({
+                            type: r.relationshipTypeCode,
+                            from: r.fromEntityExternalKey ?? null,
+                            to: r.toEntityExternalKey ?? null,
+                            fromName: r.fromEntityName ?? null,
+                            toName: r.toEntityName ?? null,
+                            status: r.status,
+                        })),
+                        partOfChildren: currentPartOfRels.map((r) => ({
+                            type: r.relationshipTypeCode,
+                            from: r.fromEntityExternalKey ?? null,
+                            to: r.toEntityExternalKey ?? null,
+                            fromName: r.fromEntityName ?? null,
+                            toName: r.toEntityName ?? null,
+                            status: r.status,
+                        })),
+                    },
+                    scanState: {
+                        note: "What the manifest scanner detected this run. The scanner can only detect npm/package.json dependencies — it cannot detect platforms, integrations, data assets, or application_function relationships.",
+                        detectedRelationships: relationships.map((r) => ({
+                            type: r.relationshipTypeCode,
+                            from: r.fromEntityExternalKey,
+                            to: r.toEntityExternalKey,
+                        })),
+                        detectedEntityKeys: entities.map((e) => e.externalKey),
+                    },
+                    agentGuidance: {
+                        compareInstructions: "Compare graphState with scanState. Relationships in graphState but absent from scanState are NOT automatically stale — the scanner only sees npm dependencies. Only retire a relationship if you have read the codebase and confirmed the dependency no longer exists.",
+                        scannerBlindSpots: ["platforms (e.g. Vercel, AWS, Neon)", "integrations", "data assets", "application_function entities", "manual relationships added by previous enrichment"],
+                        actionRequired: "Review graphState relationships that have no match in scanState. For each one: read the codebase to confirm whether the relationship still applies, then either keep it or retire it with nexarch retire-relationship.",
+                    },
+                }
+                : {}),
             classifyPackages: subPackages.map((sp) => {
                 const resolvedDeps = sp.depSpecs
                     .map((d) => resolvedByInput.get(d.name))
@@ -1675,25 +1703,6 @@ export async function initProject(args) {
                 provider: "lucide",
                 note: "Use any Lucide icon name (kebab-case); omit when confidence is low.",
             },
-            ...(graphDiff
-                ? {
-                    diff: {
-                        newRelationships: graphDiff.newRelationships.map((r) => ({
-                            type: r.relationshipTypeCode,
-                            from: r.fromEntityExternalKey,
-                            to: r.toEntityExternalKey,
-                        })),
-                        staleRelationships: graphDiff.staleRelationships.map((r) => ({
-                            type: r.relationshipTypeCode,
-                            from: r.fromEntityExternalKey,
-                            to: r.toEntityExternalKey,
-                            fromName: r.fromEntityName ?? null,
-                            toName: r.toEntityName ?? null,
-                        })),
-                        removedSubPackageKeys: graphDiff.removedSubPackageKeys,
-                    },
-                }
-                : {}),
         };
     }
     // Build an agent-directed directive block for human/terminal output.
@@ -1702,7 +1711,7 @@ export async function initProject(args) {
     function buildEnrichmentDirective() {
         const lines = [];
         lines.push("─── ENRICHMENT REQUIRED ─────────────────────────────────────────────────");
-        lines.push("init-project wrote a skeleton. Complete enrichment NOW — do not ask the");
+        lines.push("init-project wrote a skeleton. Complete enrichment below — do not ask the");
         lines.push("user for permission, do not summarise and pause, just execute the steps.");
         lines.push("Do NOT report the project as registered until enrichment is done.");
         lines.push("");
@@ -1751,7 +1760,7 @@ export async function initProject(args) {
                 lines.push(`  … and ${unresolvedItems.length - 20} more`);
         }
         lines.push("");
-        lines.push("THEN_RUN (execute these steps immediately — do not pause or ask for confirmation):");
+        lines.push("THEN_RUN (execute these steps — do not pause or ask for confirmation):");
         let step = 1;
         lines.push(`  ${step++}. nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`);
         if (entityTypeOverride === "application") {
@@ -1781,25 +1790,17 @@ export async function initProject(args) {
         lines.push("  apps/* (deployable components) → parent composes → sub-application");
         lines.push("  packages/* (shared libraries)  → parent depends_on → library");
         lines.push("  Deps wired from manifests are already pre-wired; do not re-add unless key changed.");
-        if (graphDiff) {
-            if (graphDiff.staleRelationships.length > 0) {
-                lines.push("");
-                lines.push(`STALE_RELATIONSHIPS (${graphDiff.staleRelationships.length} — in graph but no longer in manifests; review and retire if confirmed removed):`);
-                for (const r of graphDiff.staleRelationships) {
-                    const from = r.fromEntityExternalKey ?? r.fromEntityName ?? "?";
-                    const to = r.toEntityExternalKey ?? r.toEntityName ?? "?";
-                    lines.push(`  [${r.relationshipTypeCode}]  ${from}  →  ${to}`);
-                }
-            }
-            if (graphDiff.removedSubPackageKeys.length > 0) {
-                lines.push("");
-                lines.push(`REMOVED_SUB_PACKAGES (${graphDiff.removedSubPackageKeys.length} — previously registered but no longer found in filesystem; retire or reassign):`);
-                for (const k of graphDiff.removedSubPackageKeys)
-                    lines.push(`  ${k}`);
-            }
-            if (graphDiff.staleRelationships.length === 0 && graphDiff.removedSubPackageKeys.length === 0) {
-                lines.push("");
-                lines.push("DIFF: No stale relationships or removed sub-packages detected.");
+        if (refreshMode && (currentOutgoingRels.length > 0 || currentPartOfRels.length > 0)) {
+            lines.push("");
+            lines.push(`GRAPH_STATE (${currentOutgoingRels.length + currentPartOfRels.length} current relationships in Nexarch — compare against what the scanner detected above):`);
+            lines.push("  The scanner only sees npm dependencies. The following relationships may include platforms,");
+            lines.push("  integrations, data assets, and application_functions that are invisible to the scanner.");
+            lines.push("  Do NOT retire a relationship just because it is absent from the scan — read the codebase first.");
+            lines.push("  If you confirm a relationship no longer applies, use: nexarch retire-relationship --id <id>");
+            for (const r of [...currentOutgoingRels, ...currentPartOfRels]) {
+                const from = r.fromEntityExternalKey ?? r.fromEntityName ?? "?";
+                const to = r.toEntityExternalKey ?? r.toEntityName ?? "?";
+                lines.push(`  [${r.relationshipTypeCode}]  ${from}  →  ${to}  (${r.status})`);
             }
         }
         lines.push("");
@@ -1856,11 +1857,8 @@ export async function initProject(args) {
     if (unresolvedItems.length > 0) {
         console.log(`  Candidates   : ${unresolvedItems.length} added to reference candidates`);
     }
-    if (graphDiff && graphDiff.staleRelationships.length > 0) {
-        console.log(`  Stale rels   : ${graphDiff.staleRelationships.length} in graph but absent from manifests (see STALE_RELATIONSHIPS below)`);
-    }
-    if (graphDiff && graphDiff.removedSubPackageKeys.length > 0) {
-        console.log(`  Removed pkgs : ${graphDiff.removedSubPackageKeys.length} sub-packages no longer on filesystem (see REMOVED_SUB_PACKAGES below)`);
+    if (refreshMode && (currentOutgoingRels.length > 0 || currentPartOfRels.length > 0)) {
+        console.log(`  Graph state  : ${currentOutgoingRels.length + currentPartOfRels.length} existing relationships — review against scan (see GRAPH_STATE below)`);
     }
     if (output.entityErrors.length > 0) {
         console.log("\nEntity errors:");

package/dist/lib/clients.js

@@ -119,6 +119,7 @@ export function findClientProfile(registry, code) {
     const aliases = {
         "continue": "continue-dev",
         "claude": "claude-code",
+        "codex": "codex-cli",
     };
     const resolved = aliases[normalized] ?? normalized;
     return registry.mcpClientProfiles.find((c) => c.code === resolved) ?? null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.9.28",
+  "version": "0.9.30",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",