archgraph-argo 0.17.0 → 0.18.0

package/argo/scripts/graph-rag/mutationEmbeddingVectorLifecycle.js

@@ -15,6 +15,9 @@ const {
 const {
   createLiveEmbeddingProviderClient,
 } = require('./liveEmbeddingProviderClient.js');
+const {
+  buildSemanticRecordText,
+} = require('./semanticRecordText.js');
 const {
   createProductionSemanticNeo4jAdapter,
 } = require('./semantic-persistence/productionSemanticNeo4jAdapter.js');
@@ -218,7 +221,7 @@ function createProductionPersistentLifecycleDependencies(options = {}) {
     provider: Object.freeze({
       async embed(content) {
         const active = await requireResources();
-        return active.provider.embed(JSON.stringify(content));
+        return active.provider.embed(typeof content === 'string' ? content : JSON.stringify(content));
       },
     }),
     projectionStore: Object.freeze({
@@ -513,7 +516,8 @@ function buildPersistentWork(canonicalWrite, configuration, versions) {
   const tombstones = [];
   for (const definition of definitions) {
     for (const objectId of definition.ids) {
-      const content = definition.entries.find(entry => entry && entry[definition.idField] === objectId);
+      const object = definition.entries.find(entry => entry && entry[definition.idField] === objectId);
+      const content = object ? buildSemanticRecordText(definition.channel, object) : undefined;
       const base = {
         objectId,
         canonicalIdentity: `${definition.channel}:${objectId}`,

package/argo/scripts/graph-rag/semantic-persistence/productionSemanticBackfill.js

@@ -2,6 +2,9 @@ const crypto = require('node:crypto');
 const {
   evaluateEmbeddingQualification,
 } = require('../embeddingQualificationGate.js');
+const {
+  buildSemanticRecordText,
+} = require('../semanticRecordText.js');
 
 const CHANNELS = Object.freeze(['Element', 'ArchitectureRelationship', 'View']);
 const CHANNEL_SOURCES = Object.freeze({
@@ -152,7 +155,7 @@ async function processChannel(options) {
 
 function buildSemanticRecord(record, vector, options) {
   const contentHash = crypto.createHash('sha256')
-    .update(JSON.stringify(record.canonicalObject))
+    .update(buildSemanticRecordText(record.channel, record.canonicalObject))
     .digest('hex');
   return Object.freeze({
     canonicalIdentity: record.canonicalIdentity,

package/argo/scripts/graph-rag/semanticRecordText.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// Curated embedding text for a canonical semantic record.
+//
+// The canonical JSON (design/KG/SystemArchitecture.json) remains the structural
+// source of truth. The vector index, however, only encodes the human-meaningful
+// fields of each record — never ids, endpoint ids, view member-id arrays, or
+// JSON syntax — because embedding the raw object measurably dilutes retrieval
+// (most severely for Views, whose member-id arrays dominate the text, and for
+// Relationships, which are mostly structural). Both the full backfill and the
+// incremental mutation lifecycle MUST embed through this single composer so the
+// indexed text is identical across both paths.
+
+function meaningful(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function formatAttributes(attributes) {
+  if (!Array.isArray(attributes)) {
+    return [];
+  }
+  const lines = [];
+  for (const attribute of attributes) {
+    if (!attribute || !meaningful(attribute.name)) {
+      continue;
+    }
+    const detail = meaningful(attribute.value)
+      ? attribute.value
+      : (meaningful(attribute.description) ? attribute.description : '');
+    lines.push(detail ? `${attribute.name.trim()}: ${detail.trim()}` : attribute.name.trim());
+  }
+  return lines;
+}
+
+function buildSemanticRecordText(channel, object) {
+  const record = object && typeof object === 'object' ? object : {};
+  const lines = [];
+  const add = value => {
+    if (meaningful(value)) {
+      lines.push(value.trim());
+    }
+  };
+
+  if (channel === 'ArchitectureRelationship' || channel === 'Relationship') {
+    add(record.statement);
+    add(record.name);
+    add(record.description);
+    add(record.document);
+    lines.push(...formatAttributes(record.attributes));
+    return lines.join('\n');
+  }
+
+  if (channel === 'View') {
+    add(record.view_name);
+    add(record.description);
+    return lines.join('\n');
+  }
+
+  // Element (default channel)
+  add(record.type);
+  add(record.name);
+  add(record.alias);
+  add(record.description);
+  lines.push(...formatAttributes(record.attributes));
+  if (Array.isArray(record.testcases)) {
+    for (const testcase of record.testcases) {
+      if (testcase && meaningful(testcase.description)) {
+        lines.push(testcase.description.trim());
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = { buildSemanticRecordText };

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

@@ -9,6 +9,10 @@ const {
   resolveCallWorkspaceRoot,
 } = require('./argo-paths.js');
 
+const {
+  buildSemanticRecordText,
+} = require('./graph-rag/semanticRecordText.js');
+
 const DEFAULT_GRAPH_PATH = 'design/KG/SystemArchitecture.json';
 const LEGAL_QUERY_PURPOSES = new Set([
   'general',
@@ -3839,7 +3843,7 @@ async function createDefaultProductionSemanticRuntime(options = {}) {
             try {
               vectors.push(Object.freeze({
                 canonicalIdentity: record.canonicalIdentity,
-                vector: Object.freeze(await providerClient.embed(JSON.stringify(record.canonicalObject))),
+                vector: Object.freeze(await providerClient.embed(buildSemanticRecordText(record.channel, record.canonicalObject))),
               }));
             } catch (error) {
               failures.push(Object.freeze({

package/install-argo.ps1

@@ -215,6 +215,30 @@ function Register-OpenCodePlugin {
     [System.IO.File]::WriteAllText($ConfigPath, $json, (New-Object System.Text.UTF8Encoding $false))
 }
 
+function Get-ArchGraphRuleBlockEndIndex {
+    # Locate the end of a previously merged ArchGraph rule block. The rule's
+    # final section tag changed over versions: earlier rules ended with
+    # </ToolsGuideline>, the current layout ends with </Attention> and places
+    # <ToolsGuideline> earlier. Pick whichever final tag occurs LAST at/after
+    # the block marker, so the merge stays correct across rule reorderings and
+    # also repairs a previously duplicated tail.
+    param([string]$Text, [int]$From)
+    $idx = -1
+    foreach ($tag in @('</ToolsGuideline>', '</Attention>')) {
+        $i = $Text.LastIndexOf($tag)
+        if ($i -ge $From -and $i -gt $idx) { $idx = $i }
+    }
+    return $idx
+}
+
+function Get-ArchGraphRuleBlockEndTagLength {
+    param([string]$Text, [int]$Index)
+    if ($Index -lt 0) { return 0 }
+    if ($Text.Substring($Index).StartsWith('</ToolsGuideline>')) { return '</ToolsGuideline>'.Length }
+    if ($Text.Substring($Index).StartsWith('</Attention>')) { return '</Attention>'.Length }
+    return 0
+}
+
 function Add-AgentsRule {
     param(
         [string]$AgentsPath,
@@ -231,18 +255,18 @@ function Add-AgentsRule {
             # An existing ArchGraph rules block is present. Replace it with the
             # current rule content while preserving any unrelated content that
             # surrounds it (e.g. user-authored OpenCode instructions).
-            $endTag = '</ToolsGuideline>'
             $markerIdx = $existing.IndexOf($marker)
             if ($markerIdx -lt 0) { $markerIdx = 0 }
             $startIdx = $existing.LastIndexOf('---', $markerIdx)
             if ($startIdx -lt 0) { $startIdx = 0 }
-            $endIdx = $existing.IndexOf($endTag, $markerIdx)
+            $endIdx = Get-ArchGraphRuleBlockEndIndex -Text $existing -From $markerIdx
 
             $before = $existing.Substring(0, $startIdx).TrimEnd()
             if ($endIdx -lt 0) {
                 $combined = $ruleContent
             } else {
-                $after = $existing.Substring($endIdx + $endTag.Length)
+                $endLen = Get-ArchGraphRuleBlockEndTagLength -Text $existing -Index $endIdx
+                $after = $existing.Substring($endIdx + $endLen)
                 $combined = $before
                 if ($combined.Length -gt 0) { $combined += "`n`n" }
                 $combined += $ruleContent
@@ -301,13 +325,15 @@ function Write-ArchGraphRuleBlock {
     if (Test-Path $DestPath) {
         $existing = Get-Content $DestPath -Raw -Encoding UTF8
         if ($existing -like "*$marker*") {
-            $endTag = '</ToolsGuideline>'
             $startIdx = $existing.IndexOf($marker)
             if ($startIdx -lt 0) { $startIdx = 0 }
-            $endIdx = $existing.IndexOf($endTag, $startIdx)
+            $endIdx = Get-ArchGraphRuleBlockEndIndex -Text $existing -From $startIdx
             $before = $existing.Substring(0, $startIdx).TrimEnd()
             $after = ''
-            if ($endIdx -ge 0) { $after = $existing.Substring($endIdx + $endTag.Length).TrimStart() }
+            if ($endIdx -ge 0) {
+                $endLen = Get-ArchGraphRuleBlockEndTagLength -Text $existing -Index $endIdx
+                $after = $existing.Substring($endIdx + $endLen).TrimStart()
+            }
             $combined = $before
             if ($combined.Length -gt 0) { $combined += "`n`n" }
             $combined += $ruleContent

package/package.json

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