archgraph-argo 0.10.21 → 0.10.23

package/argo/rules/archgraph.instructions.md

@@ -99,7 +99,7 @@ You MUST read/write the intent architecture through the tools provided by the AR
 16. queryNeo4jGraph: run a read-only Cypher query against the Neo4j structural projection of the intent graph, or request the projection schema with {schema: true}. Use for structural/type-based graph queries (see <GraphQueryGuideline>).
 
 <GraphQueryGuideline>
-For structural/type-based graph lookups, use the read-only Neo4j Cypher interface `queryNeo4jGraph` instead of reading the canonical JSON file directly. It never mutates the graph; all writes still go through the mutation tools.
+For structural/type-based graph lookups, use the read-only Neo4j Cypher interface `queryNeo4jGraph` instead of reading the canonical JSON file directly. It never mutates the canonical graph; all writes still go through the mutation tools.
 1. Ask for the projection schema first: call `queryNeo4jGraph` with {schema: true} to learn node labels (ArchitectureGraph, Element, ArchitectureRelationship, View), relationship types (OWNS_ELEMENT, OWNS_RELATIONSHIP, OWNS_VIEW, RELATIONSHIP_SOURCE, RELATIONSHIP_TARGET, ARCHIMATE_RELATES, VIEW_OF, INCLUDES_ELEMENT, INCLUDES_RELATIONSHIP, HAS_SUBDIAGRAM), property keys, and the legal ArchiMate element/relationship type enums (e.g. 'Business Actor', 'Assignment').
 2. Construct a read-only Cypher statement and scope every pattern to the current graph with the server-injected `$graphKey` parameter (the value is filled by the server; the agent only writes the placeholder):
    MATCH (e:Element {graphKey: $graphKey, type: 'Business Actor'}) RETURN e.id, e.name ORDER BY e.name

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -164,6 +164,7 @@ const {
 } = require('./graph-rag/mutationEmbeddingVectorLifecycle.js');
 const {
   DEFAULT_GRAPH_PATH: NEO4J_DEFAULT_GRAPH_PATH,
+  assertReadOnlyCypher,
   buildGraphKey,
   buildNeo4jGraphSchema,
   recoverNeo4jSyncIfNeeded,
@@ -2188,20 +2189,43 @@ async function queryNeo4jGraphTool(args = {}) {
     return queryNeo4jGraphSchemaResult(architecturePath, workspaceRoot);
   }
 
+  let recovery = null;
   try {
+    // Reject invalid/write queries before any side effect.
+    assertReadOnlyCypher(args.cypher);
+
+    // Same projection-recovery mechanism as the loadContext-based tools
+    // (e.g. getSystemArchitecture): when the sync state is dirty or the
+    // recorded canonicalDigest no longer matches the canonical JSON, rebuild
+    // the Neo4j projection before servicing the read-only query.
+    recovery = await recoverNeo4jSyncIfNeeded({
+      architecturePath,
+      workspaceRoot,
+    });
+
     const result = await runNeo4jCypherQuery({
       architecturePath,
       cypher: args.cypher,
       workspaceRoot,
     });
-    return toolResult({
+    const payload = {
       status: 'passed',
       architecturePath: result.architecturePath,
       graphKey: result.graphKey,
       database: result.database,
       records: result.records,
       summary: result.summary,
-    });
+    };
+    if (recovery.attempted) {
+      payload.neo4jRecovery = recovery;
+      if (recovery.status === 'failed') {
+        payload.warnings = [
+          `Neo4j automatic resync failed before servicing ${architecturePath}: ${recovery.error}`,
+          'The read-only query still ran against the current projection. Neo4j will be retried on the next canonical read or write, or you can run node .argo/scripts/syncSystemArchitectureToNeo4j.js manually.',
+        ];
+      }
+    }
+    return toolResult(payload);
   } catch (error) {
     return toolResult(queryError(
       error && error.category ? error.category : 'NEO4J_QUERY_FAILED',
@@ -2212,6 +2236,7 @@ async function queryNeo4jGraphTool(args = {}) {
         ...(error && error.clause ? { clause: error.clause } : {}),
         ...(error && error.queriedDatabase ? { queriedDatabase: error.queriedDatabase } : {}),
         ...(error && error.expectedDatabase ? { expectedDatabase: error.expectedDatabase } : {}),
+        ...(recovery && recovery.attempted ? { neo4jRecovery: recovery } : {}),
       },
     ));
   }

package/install-argo.ps1

@@ -726,7 +726,7 @@ if ($SkipDsh) {
         Write-DshManagedBlock -Path $patchPath -Block $block -MarkerStart '# BEGIN ArchGraph ARGO deployment' -MarkerEnd '# END ArchGraph ARGO deployment'
     }
 
-    Write-Host "[19/19] argo\agents10 -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
+    Write-Host "[19/19] argo\agents11 -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
     New-DshAgentPresets -DshHome $DshHome -AgentsSrc (Join-Path $argoDir 'agents')
 
     Write-Host '  Restart `dsh web` to activate the MCP bridge and the wakeup plugin;'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.21",
+  "version": "0.10.23",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {