archgraph-argo 0.10.20 → 0.10.22

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/neo4j-system-architecture-store.js

@@ -35,20 +35,22 @@ function requireNeo4jDriver() {
   return neo4jDriverModule;
 }
 
-function getRepoRoot() {
-  return getWorkspaceRoot();
+function getRepoRoot(workspaceRoot) {
+  return workspaceRoot && typeof workspaceRoot === 'string' && workspaceRoot.trim() !== ''
+    ? path.resolve(workspaceRoot)
+    : getWorkspaceRoot();
 }
 
-function resolveArchitecturePath(architecturePath = DEFAULT_GRAPH_PATH) {
-  return path.join(getRepoRoot(), architecturePath);
+function resolveArchitecturePath(architecturePath = DEFAULT_GRAPH_PATH, workspaceRoot) {
+  return path.join(getRepoRoot(workspaceRoot), architecturePath);
 }
 
-function resolveSyncStatePath() {
-  return path.join(getRepoRoot(), SYNC_STATE_RELATIVE_PATH);
+function resolveSyncStatePath(workspaceRoot) {
+  return path.join(getRepoRoot(workspaceRoot), SYNC_STATE_RELATIVE_PATH);
 }
 
-function getDefaultNeo4jDatabaseName() {
-  const repoName = path.basename(getRepoRoot());
+function getDefaultNeo4jDatabaseName(workspaceRoot) {
+  const repoName = path.basename(getRepoRoot(workspaceRoot));
   const normalized = String(repoName)
     .toLowerCase()
     .replace(/[^a-z0-9.-]+/g, '-')
@@ -86,7 +88,7 @@ function getNeo4jConfig(overrides = {}) {
     uri: external.neo4jUri,
     username: external.neo4jUsername,
     password: external.neo4jPassword,
-    database: overrides.database || process.env.ARGO_NEO4J_DATABASE || getDefaultNeo4jDatabaseName(),
+    database: overrides.database || process.env.ARGO_NEO4J_DATABASE || getDefaultNeo4jDatabaseName(overrides.workspaceRoot),
   };
 }
 
@@ -133,8 +135,8 @@ function createDriver(config = {}) {
   );
 }
 
-function readArchitectureDocument(architecturePath = DEFAULT_GRAPH_PATH) {
-  const absolutePath = resolveArchitecturePath(architecturePath);
+function readArchitectureDocument(architecturePath = DEFAULT_GRAPH_PATH, workspaceRoot) {
+  const absolutePath = resolveArchitecturePath(architecturePath, workspaceRoot);
   if (!fs.existsSync(absolutePath)) {
     throw new Error(`System architecture file is missing at ${architecturePath}`);
   }
@@ -146,8 +148,8 @@ function readArchitectureDocument(architecturePath = DEFAULT_GRAPH_PATH) {
   }
 }
 
-function digestCanonicalArchitecture(architecturePath = DEFAULT_GRAPH_PATH) {
-  const absolutePath = resolveArchitecturePath(architecturePath);
+function digestCanonicalArchitecture(architecturePath = DEFAULT_GRAPH_PATH, workspaceRoot) {
+  const absolutePath = resolveArchitecturePath(architecturePath, workspaceRoot);
   try {
     return crypto.createHash('sha256').update(fs.readFileSync(absolutePath)).digest('hex');
   } catch {
@@ -188,8 +190,8 @@ function createEmptySyncState() {
   };
 }
 
-function readNeo4jSyncState() {
-  const statePath = resolveSyncStatePath();
+function readNeo4jSyncState(workspaceRoot) {
+  const statePath = resolveSyncStatePath(workspaceRoot);
   if (!fs.existsSync(statePath)) {
     return createEmptySyncState();
   }
@@ -205,15 +207,15 @@ function readNeo4jSyncState() {
   }
 }
 
-function writeNeo4jSyncState(state) {
-  const statePath = resolveSyncStatePath();
+function writeNeo4jSyncState(state, workspaceRoot) {
+  const statePath = resolveSyncStatePath(workspaceRoot);
   fs.mkdirSync(path.dirname(statePath), { recursive: true });
   fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
 }
 
-function getNeo4jGraphSyncState(architecturePath = DEFAULT_GRAPH_PATH) {
+function getNeo4jGraphSyncState(architecturePath = DEFAULT_GRAPH_PATH, workspaceRoot) {
   const graphKey = buildGraphKey(architecturePath);
-  const state = readNeo4jSyncState();
+  const state = readNeo4jSyncState(workspaceRoot);
   return {
     graphKey,
     dirty: false,
@@ -221,30 +223,30 @@ function getNeo4jGraphSyncState(architecturePath = DEFAULT_GRAPH_PATH) {
   };
 }
 
-function updateNeo4jGraphSyncState(architecturePath, patch) {
+function updateNeo4jGraphSyncState(architecturePath, patch, workspaceRoot) {
   const graphKey = buildGraphKey(architecturePath);
-  const state = readNeo4jSyncState();
+  const state = readNeo4jSyncState(workspaceRoot);
   state.graphs[graphKey] = {
     graphKey,
     dirty: false,
     ...(state.graphs[graphKey] || {}),
     ...patch,
   };
-  writeNeo4jSyncState(state);
+  writeNeo4jSyncState(state, workspaceRoot);
   return state.graphs[graphKey];
 }
 
-function markNeo4jSyncDirty(architecturePath, error) {
+function markNeo4jSyncDirty(architecturePath, error, workspaceRoot) {
   return updateNeo4jGraphSyncState(architecturePath, {
     dirty: true,
     lastError: String(error && error.message ? error.message : error),
     lastFailureAt: new Date().toISOString(),
-  });
+  }, workspaceRoot);
 }
 
-function markNeo4jSyncClean(architecturePath, verification) {
-  const current = getNeo4jGraphSyncState(architecturePath);
-  const canonicalDigest = digestCanonicalArchitecture(architecturePath);
+function markNeo4jSyncClean(architecturePath, verification, workspaceRoot) {
+  const current = getNeo4jGraphSyncState(architecturePath, workspaceRoot);
+  const canonicalDigest = digestCanonicalArchitecture(architecturePath, workspaceRoot);
   return updateNeo4jGraphSyncState(architecturePath, {
     dirty: false,
     lastError: undefined,
@@ -252,7 +254,7 @@ function markNeo4jSyncClean(architecturePath, verification) {
     lastSuccessAt: new Date().toISOString(),
     lastVerifiedCounts: verification ? verification.actual : current.lastVerifiedCounts,
     canonicalDigest,
-  });
+  }, workspaceRoot);
 }
 
 function isCanonicalArchitecturePath(architecturePath = DEFAULT_GRAPH_PATH) {
@@ -544,8 +546,9 @@ async function writeSubdiagramLinks(tx, graphKey, elements) {
 
 async function syncArchitectureToNeo4j(options = {}) {
   const architecturePath = options.architecturePath || DEFAULT_GRAPH_PATH;
+  const workspaceRoot = options.workspaceRoot;
   const graphKey = buildGraphKey(architecturePath);
-  const document = options.document || readArchitectureDocument(architecturePath);
+  const document = options.document || readArchitectureDocument(architecturePath, workspaceRoot);
   const config = getNeo4jConfig(options);
   const driver = options.driver || createDriver(config);
   const ownDriver = !options.driver;
@@ -583,7 +586,7 @@ async function syncArchitectureToNeo4j(options = {}) {
     }
 
     if (isCanonicalArchitecturePath(architecturePath)) {
-      markNeo4jSyncClean(architecturePath, verification);
+      markNeo4jSyncClean(architecturePath, verification, workspaceRoot);
     }
 
     return {
@@ -598,7 +601,7 @@ async function syncArchitectureToNeo4j(options = {}) {
     };
   } catch (error) {
     if (isCanonicalArchitecturePath(architecturePath)) {
-      markNeo4jSyncDirty(architecturePath, error);
+      markNeo4jSyncDirty(architecturePath, error, workspaceRoot);
     }
     throw error;
   } finally {
@@ -610,6 +613,7 @@ async function syncArchitectureToNeo4j(options = {}) {
 
 async function recoverNeo4jSyncIfNeeded(options = {}) {
   const architecturePath = options.architecturePath || DEFAULT_GRAPH_PATH;
+  const workspaceRoot = options.workspaceRoot;
   if (!isCanonicalArchitecturePath(architecturePath)) {
     return {
       attempted: false,
@@ -618,8 +622,8 @@ async function recoverNeo4jSyncIfNeeded(options = {}) {
     };
   }
 
-  const syncState = getNeo4jGraphSyncState(architecturePath);
-  const stale = isNeo4jGraphSyncStale(syncState, digestCanonicalArchitecture(architecturePath));
+  const syncState = getNeo4jGraphSyncState(architecturePath, workspaceRoot);
+  const stale = isNeo4jGraphSyncStale(syncState, digestCanonicalArchitecture(architecturePath, workspaceRoot));
   if (!syncState.dirty && !stale) {
     return {
       attempted: false,
@@ -658,8 +662,9 @@ async function recoverNeo4jSyncIfNeeded(options = {}) {
 
 async function verifyArchitectureSync(options = {}) {
   const architecturePath = options.architecturePath || DEFAULT_GRAPH_PATH;
+  const workspaceRoot = options.workspaceRoot;
   const graphKey = buildGraphKey(architecturePath);
-  const document = options.document || readArchitectureDocument(architecturePath);
+  const document = options.document || readArchitectureDocument(architecturePath, workspaceRoot);
   const config = getNeo4jConfig(options);
   const driver = options.driver || createDriver(config);
   const ownDriver = !options.driver;

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,
@@ -498,6 +499,7 @@ async function syncCanonicalStructuralProjection(request) {
   return syncArchitectureToNeo4j({
     architecturePath: context.graphPath.relativePath,
     document: context.document,
+    workspaceRoot: context.workspaceRoot,
   });
 }
 
@@ -556,6 +558,7 @@ async function loadContext(args = {}) {
   context.neo4jSyncRecovery = await recoverNeo4jSyncIfNeeded({
     architecturePath: graphPath.relativePath,
     document: context.document,
+    workspaceRoot: context.workspaceRoot,
   });
   return context;
 }
@@ -1536,6 +1539,7 @@ async function buildMutationResult(context, mutations, write) {
       const syncResult = await syncArchitectureToNeo4j({
         architecturePath: context.graphPath.relativePath,
         document: mutationResult.document,
+        workspaceRoot: context.workspaceRoot,
       });
       result.neo4jSync = {
         status: 'passed',
@@ -2179,24 +2183,49 @@ async function callTool(name, args = {}, dependencies = undefined) {
 
 async function queryNeo4jGraphTool(args = {}) {
   const architecturePath = args.architecturePath || DEFAULT_GRAPH_PATH;
+  const workspaceRoot = resolveWorkspaceRoot(args);
 
   if (args.schema === true) {
-    return queryNeo4jGraphSchemaResult(architecturePath);
+    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',
@@ -2207,17 +2236,18 @@ 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 } : {}),
       },
     ));
   }
 }
 
-function queryNeo4jGraphSchemaResult(architecturePath) {
+function queryNeo4jGraphSchemaResult(architecturePath, workspaceRoot) {
   const schema = buildNeo4jGraphSchema(architecturePath);
   let typeEnums = {};
   try {
-    const workspaceRoot = resolveWorkspaceRoot({ architecturePath });
-    const schemaPath = resolveSchemaPath(workspaceRoot);
+    const resolvedRoot = workspaceRoot || resolveWorkspaceRoot({ architecturePath });
+    const schemaPath = resolveSchemaPath(resolvedRoot);
     const jsonSchema = readJson(schemaPath.absolutePath, schemaPath.relativePath);
     typeEnums = {
       archimateElementTypes: (jsonSchema.$defs.archimateElementType || {}).enum || [],

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\agents9 -> $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.20",
+  "version": "0.10.22",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {