archgraph-argo 0.10.30 → 0.10.31

package/argo/rules/archgraph.instructions.md

@@ -20,6 +20,8 @@ The following are non-negotiable red lines (MUST) for this Agent and must never
 4. Any change must first identify and pass the regression tests of all affected acceptance test cases; if the acceptance test cases are missing, add them first. Tier 1 (behavior-independent) changes are exempt from acceptance regression and full validation per `<ChangeTierGate>`; all other tiers keep the full requirement. See `<AcceptanceTestFirst>` and `<ChangeTierGate>`.
 5. Before finishing work, you MUST summarize the key progress of this session and write it back to long-term memory, to prevent forgetting across long or separate sessions. See `<SessionMemorySummarization>` and `<MemoryTriggerTiming>`.
 6. Continuously comply with the red lines above throughout the process; never skip, simplify, or silently violate any of them.
+7. KG-first retrieval and semantic-first KG retrieval: any retrieval MUST first query the intent graph, and KG retrieval MUST prioritize semantic retrieval (getSystemArchitecture with query.purpose + query.intent, getIntentElementContext) over full-graph reads and structural Cypher queries. See `<QueryPriorityGuideline>`.
+8. Content storage is KG-first: except for content that must stay in the repository or cannot be stored in the KG (e.g., videos), ALL document content MUST be written into the intent graph, and repository-only content MUST be summarized and registered in the KG. See `<ContentStoragePolicy>`.
 </CoreRules>
 
 <Ontology>
@@ -29,11 +31,27 @@ Your cognitive architecture is composed of ArchiMate 3.2 elements and their exte
 </Ontology>
 
 <ExplorationGuideline>
+0. KG-first retrieval: for ANY retrieval — architecture context, past decisions, files, code, knowledge — FIRST query the intent graph through ARGO MCP before searching the file system, code, or web. See `<QueryPriorityGuideline>`.
 1. When exploring context, explore in small steps: keep each query shallow, and after each query decide the next exploration direction based on the result.
 2. When you receive multiple similar or conflicting pieces of information, prefer the context closest to your current task and avoid wasting time on irrelevant context.
 3. For structural/type-based graph lookups (list elements of a type, traverse relationships, count, aggregate), use `queryNeo4jGraph` per `<GraphQueryGuideline>` instead of reading the JSON file directly.
 </ExplorationGuideline>
 
+<QueryPriorityGuideline>
+1. KG-first retrieval: for ANY retrieval task (architecture context, past decisions, files, code, knowledge), the intent graph (design/KG/SystemArchitecture.json via ARGO MCP) is the FIRST hop. Do NOT default to searching the file system, code, or web before querying the graph.
+2. Semantic-first KG retrieval: KG retrieval MUST go through semantic retrieval first — `getSystemArchitecture` with query.purpose + query.intent (semantic), and `getIntentElementContext` / `getArchitectureViewContext` for focused context. An omitted-query full read, or reading the graph JSON file directly, is a last resort, never the default.
+3. `queryNeo4jGraph` (read-only Cypher) is the SECONDARY path for structural/type-based lookups that semantic retrieval does not cover (list elements of a type, traverse relationships, count, aggregate), per `<GraphQueryGuideline>`.
+4. Exception: when the task explicitly requires exhaustive enumeration, use view membership via `getArchitectureViewContext`. Never fabricate or guess retrieval results — if the graph cannot answer, state that and escalate to the human partner.
+5. Bound the scope when the whole graph is too broad: if a semantic query would return too much content or only a local region is relevant, restrict retrieval to a subgraph with `scope` (view_id, or element_id + depth) on getSystemArchitecture, then drill into the returned ids with getIntentElementContext. Prefer a scoped read over an unbounded whole-graph read.
+</QueryPriorityGuideline>
+
+<ContentStoragePolicy>
+1. KG-first document storage: except for content that MUST physically live in the repository, or that cannot be stored in the intent graph (e.g., videos, binaries, executables), ALL document content MUST be written into the KG (design/KG/SystemArchitecture.json via ARGO MCP) as architecture elements carrying descriptions/attributes.
+2. Repository-only content still requires a KG summary (SUMMARY): any file that must stay in the repository (e.g., video, binary, executable) MUST be summarized and registered in the KG — create a corresponding element (e.g., Artifact / Representation / Business Object) whose description summarizes the content and whose attributes record the repository file path + commit id.
+3. The KG is the source of truth for document content: do not keep document bodies as standalone repository files when the KG can hold them; if a document must also live in the repository (e.g., a rendered/exported artifact), the KG element remains authoritative.
+4. When writing document content into the KG, follow `<IntentArchitectureFirst>` (locate or create the element and View) and register commit id + file paths per `<AcceptanceTestFirst>`.
+</ContentStoragePolicy>
+
 <IntentArchitectureFirst>
 1. Before modifying anything in the repository, you MUST first find the corresponding architecture element in the architecture graph.
 2. If the element is not found, you MUST first pick a View and create a new reasonable architecture element within it.
@@ -56,17 +74,17 @@ When you are about to build an element, first look up the skills and resources n
 
 <ChangeTierGate>
 Every repository change MUST be classified into exactly one tier BEFORE implementation; the tier is declared explicitly. Tier classification is objective and enumerable; if the Agent cannot conclusively classify the change, it MUST default to Tier 2 (fail-safe).
-1. Tier 1 — 行为无关（behavior-independent）: qualifies ONLY if ALL of the following hold:
+1. Tier 1 — behavior-independent: qualifies ONLY if ALL of the following hold:
    - The diff touches only non-executable content: comments, documentation (including this rules file), whitespace/formatting-only hunks, or descriptive metadata text in the intent graph.
    - No executable logic, public interface/API surface, or test logic is changed (test files untouched).
    - No graph structure change: no element/relationship/view added, removed, renamed, or retyped.
-   - Skipped ceremony（跳过验收回归与全量校验）: acceptance test identification and regression, and full validateSystemArchitecture, are skipped (unless the graph was touched). Kept ceremony: locate the element, git commit + register commit id, and defer memory milestone writes to session end.
-2. Tier 2 — 行为变化（behavior-changing, scoped）: any change touching executable logic, interfaces, or test behavior within existing elements. Full ceremony: locate element, identify affected acceptance test cases, run regression, validateSystemArchitecture, commit + register, immediate memory writes.
-3. Tier 3 — 结构性/新增（structural/new）: new elements/relationships/views, new features, or cross-cutting changes. Full Tier 2 ceremony plus preview/apply mutation for any graph change.
+   - Skipped ceremony (acceptance regression and full validation): acceptance test identification and regression, and full validateSystemArchitecture, are skipped (unless the graph was touched). Kept ceremony: locate the element, git commit + register commit id, and defer memory milestone writes to session end.
+2. Tier 2 — behavior-changing, scoped: any change touching executable logic, interfaces, or test behavior within existing elements. Full ceremony: locate element, identify affected acceptance test cases, run regression, validateSystemArchitecture, commit + register, immediate memory writes.
+3. Tier 3 — structural/new: new elements/relationships/views, new features, or cross-cutting changes. Full Tier 2 ceremony plus preview/apply mutation for any graph change.
 4. Safety net (MUST, non-negotiable):
-   - Declared tier is verified at commit time: the actual git diff file list is checked against the Tier 1 allowlist; if any disallowed file/hunk appears, the change automatically 升为 Tier 2 and MUST complete the acceptance regression and validation before finishing. Tier 1 is revocable, not merely declared.
-   - KG 触线规则: any diff touching design/KG/SystemArchitecture.json keeps full validation; the Tier 1 exemption never applies to graph structure changes.
-   - 零歧义默认升档（fail-safe）: any uncertain classification MUST be treated as Tier 2, never Tier 1.
+   - Declared tier is verified at commit time: the actual git diff file list is checked against the Tier 1 allowlist; if any disallowed file/hunk appears, the change is automatically escalated to Tier 2 and MUST complete the acceptance regression and validation before finishing. Tier 1 is revocable, not merely declared.
+   - KG touch rule: any diff touching design/KG/SystemArchitecture.json keeps full validation; the Tier 1 exemption never applies to graph structure changes.
+   - Fail-safe (zero-ambiguity default escalation): any uncertain classification MUST be treated as Tier 2, never Tier 1.
 </ChangeTierGate>
 
 <CoperationGuideline>
@@ -78,8 +96,8 @@ Every repository change MUST be classified into exactly one tier BEFORE implemen
 </CoperationGuideline>
 
 <CapabilityDelegationGuideline>
-1. When an Agent receives a task that requires viewing or reading images (图片), videos (视频), or other multimodal (多模态) content, it MUST first assess whether its own model has the recognition capability to consume that content.
-2. If the Agent's model lacks that capability (不具备识别能力), or the harness fails to deliver the content, the Agent MUST NOT (不得) guess, fabricate, or silently skip the content; it MUST proactively identify another `Business Actor` in the intent graph whose agent/model has the required capability (via the Actor's `agent`/`model` attributes or description) and formally delegate (委托) that subtask to that Actor per `<CoperationGuideline>` (look up the stable identity; launch the corresponding Agent, or fall back to a general-purpose Agent passing that Actor's description).
+1. When an Agent receives a task that requires viewing or reading images, videos, or other multimodal content, it MUST first assess whether its own model has the recognition capability to consume that content.
+2. If the Agent's model lacks that capability, or the harness fails to deliver the content, the Agent MUST NOT guess, fabricate, or silently skip the content; it MUST proactively identify another `Business Actor` in the intent graph whose agent/model has the required capability (via the Actor's `agent`/`model` attributes or description) and formally delegate that subtask to that Actor per `<CoperationGuideline>` (look up the stable identity; launch the corresponding Agent, or fall back to a general-purpose Agent passing that Actor's description).
 3. If no capable Actor can be found, the Agent MUST report the exact blocking reason and alternatives to the human partner instead of pretending to have consumed the content.
 4. After delegation, the delegating Agent remains responsible for verifying the delegated result against the original task's acceptance criteria (external view), keeping the executable GIVEN-WHEN-THEN validation principle intact.
 </CapabilityDelegationGuideline>
@@ -103,7 +121,7 @@ The above immediate records also follow the conciseness and de-duplication requi
 
 <ToolsGuideline>
 You MUST read/write the intent architecture through the tools provided by the ARGO MCP server; direct modification of the intent architecture source file is forbidden:
-1. getSystemArchitecture: semantically read the architecture (recommended: with query.purpose + query.intent, rather than a full read).
+1. getSystemArchitecture: semantically read the architecture — MUST supply query.purpose + query.intent (semantic retrieval per <QueryPriorityGuideline>); an omitted-query full read is a last resort, not the default.
 2. getIntentElementContext: get the context of an intent architecture element, including its attributes and relationships.
 3. previewSystemArchitectureMutation: preview intent architecture changes to ensure they don't break the existing architecture structure.
 4. applySystemArchitectureMutation: apply intent architecture changes and formally write the previewed changes into the intent architecture.
@@ -126,7 +144,7 @@ For structural/type-based graph lookups, use the read-only Neo4j Cypher interfac
 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
 3. Never submit write clauses (CREATE, MERGE, DELETE, SET, REMOVE, DROP, LOAD CSV, FOREACH, IN TRANSACTIONS); the interface rejects them to protect the canonical JSON single source of truth.
-4. Use it for structural queries: list elements of a type, traverse ARCHIMATE_RELATES edges, count and aggregate. For semantic/context reading (subgraph context, dependency traversal, view membership), keep using getSystemArchitecture (semantic query), getIntentElementContext, and getArchitectureViewContext.
+4. Use it as the SECONDARY path for structural/type-based lookups that semantic retrieval does not cover: list elements of a type, traverse ARCHIMATE_RELATES edges, count and aggregate. Semantic-first KG retrieval — semantic/context reading (getSystemArchitecture with query.purpose + query.intent, getIntentElementContext, getArchitectureViewContext) is the PRIORITY path per <QueryPriorityGuideline>.
 5. The query is read-only; never attempt to mutate the graph through Cypher.
 </GraphQueryGuideline>
 

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

@@ -157,6 +157,16 @@ const TOOLS = [
             },
             intent: { type: 'string', description: 'Natural-language intent for semantic retrieval, for example "summarize business features for high-risk audit".' },
             subject: { type: 'string', description: 'Required for audit; optional anchor/focus id for other semantic purposes.' },
+            scope: {
+              type: 'object',
+              description: 'Optional subgraph scope to bound semantic retrieval and limit the returned content to a local region. Provide view_id to search within one view membership, or element_id (+ depth) to search within an element subtree.',
+              properties: {
+                view_id: { type: 'string', description: 'Restrict retrieval to the members of this view.' },
+                element_id: { type: 'string', description: 'Restrict retrieval to this element and its mounted sub-view subtree.' },
+                depth: { type: 'number', description: 'Default: 2. Subtree depth for element scope.' },
+              },
+              additionalProperties: false,
+            },
           },
           additionalProperties: true,
         },

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

@@ -68,6 +68,13 @@ const VECTOR_QUERY_CYPHER = [
   'RETURN properties(node) AS record, score',
   'ORDER BY score DESC',
 ].join('\n');
+const VECTOR_QUERY_CYPHER_SCOPED = [
+  'CALL db.index.vector.queryNodes($indexName, $topK, $vector)',
+  'YIELD node, score',
+  'WHERE node.channel = $channel AND node.canonicalIdentity IN $canonicalIdentities',
+  'RETURN properties(node) AS record, score',
+  'ORDER BY score DESC',
+].join('\n');
 const READINESS_QUERY_CYPHER = [
   'MATCH (readiness:ArgoProductionSemanticReadiness {identity: $identity})',
   'RETURN properties(readiness) AS readiness',
@@ -159,6 +166,7 @@ async function executeWpP2Retrieval({
   readiness,
   configurationEvidence,
 }) {
+  const { canonicalIdentities, ...completeRequest } = request;
   const provider = createLiveEmbeddingProviderClient({
     configuration: configurationEvidence.configuration,
     transport: composition.transport,
@@ -171,10 +179,13 @@ async function executeWpP2Retrieval({
       channel,
       neo4jDriver: composition.neo4jDriver,
       vector,
+      ...(Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0
+        ? { canonicalIdentities }
+        : {}),
     });
   }
   return completeSemanticResult({
-    request,
+    request: completeRequest,
     canonicalGraph,
     readiness,
     seedsByType,
@@ -609,7 +620,8 @@ function publicReadinessOutcome(alignment) {
   };
 }
 
-async function exhaustChannel({ channel, neo4jDriver, vector }) {
+async function exhaustChannel({ channel, neo4jDriver, vector, canonicalIdentities }) {
+  const scoped = Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0;
   const accepted = [];
   const seen = new Set();
   let offset = 0;
@@ -621,12 +633,13 @@ async function exhaustChannel({ channel, neo4jDriver, vector }) {
       windowSize: INITIAL_WINDOW_SIZE,
       topK: offset + INITIAL_WINDOW_SIZE,
       vector,
+      ...(scoped ? { canonicalIdentities } : {}),
     });
     const result = await neo4jDriver.execute(Object.freeze({
       kind: 'semantic-vector-window-query',
       channel: channel.channel,
       indexName: channel.indexName,
-      cypher: VECTOR_QUERY_CYPHER,
+      cypher: scoped ? VECTOR_QUERY_CYPHER_SCOPED : VECTOR_QUERY_CYPHER,
       parameters,
     }));
     const records = Array.isArray(result && result.records) ? result.records : [];

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

@@ -204,6 +204,16 @@ const TOOLS = [
             },
             intent: { type: 'string', description: 'Natural-language intent for semantic retrieval, for example "summarize business features for high-risk audit".' },
             subject: { type: 'string', description: 'Required for audit; optional anchor/focus id for other semantic purposes.' },
+            scope: {
+              type: 'object',
+              description: 'Optional subgraph scope to bound semantic retrieval and limit the returned content to a local region. Provide view_id to search within one view membership, or element_id (+ depth) to search within an element subtree.',
+              properties: {
+                view_id: { type: 'string', description: 'Restrict retrieval to the members of this view.' },
+                element_id: { type: 'string', description: 'Restrict retrieval to this element and its mounted sub-view subtree.' },
+                depth: { type: 'number', description: 'Default: 2. Subtree depth for element scope.' },
+              },
+              additionalProperties: false,
+            },
           },
           additionalProperties: true,
         },
@@ -2291,6 +2301,16 @@ async function executeSemanticSystemArchitectureQuery(args, dependencies) {
       : {}),
   });
   const query = args.query;
+  const scopeResolution = resolveSemanticScope(context.document, query && query.scope);
+  if (scopeResolution.status === 'failed') {
+    return getSystemArchitectureResult(queryError(
+      scopeResolution.error.category,
+      scopeResolution.error.message,
+    ));
+  }
+  const queryForRetrieval = Array.isArray(scopeResolution.identities) && scopeResolution.identities.length > 0
+    ? { ...(query || {}), canonicalIdentities: scopeResolution.identities }
+    : query;
   const contractOptions = semanticContractOptions(args, dependencies);
   const canonicalSubsetContract = isCanonicalSubsetSemanticContract(query, contractOptions);
   if (canonicalSubsetContract) {
@@ -2310,7 +2330,7 @@ async function executeSemanticSystemArchitectureQuery(args, dependencies) {
   }
   let document;
   try {
-    const retrieved = await semanticRetrievalBoundary.retrieve(query);
+    const retrieved = await semanticRetrievalBoundary.retrieve(queryForRetrieval);
     if (canonicalSubsetContract) {
       const subset = buildCanonicalSemanticDocumentSubset(retrieved, context.document);
       if (subset.status === 'failed') {
@@ -2352,6 +2372,14 @@ async function executeSemanticSystemArchitectureQuery(args, dependencies) {
       semanticErrorEvidence,
     ));
   }
+  if (
+    Array.isArray(scopeResolution.identities)
+    && scopeResolution.identities.length > 0
+    && document
+    && typeof document === 'object'
+  ) {
+    document = applySemanticScopeFilter(document, scopeResolution.identities);
+  }
   const semanticPayload = {
     status: 'passed',
     graphPath: context.graphPath.relativePath,
@@ -2381,6 +2409,109 @@ function shouldReturnDebugSemanticResult(query) {
   ).toLowerCase());
 }
 
+function resolveSemanticScope(document, scope) {
+  if (!scope || typeof scope !== 'object') {
+    return { identities: undefined };
+  }
+  const elements = new Set();
+  const relationships = new Set();
+  const views = new Set();
+
+  if (typeof scope.view_id === 'string' && scope.view_id) {
+    const view = (document.views || []).find(item => item && item.view_id === scope.view_id);
+    if (!view) {
+      return {
+        status: 'failed',
+        error: {
+          category: 'SCOPE_VIEW_NOT_FOUND',
+          message: `Scope view '${scope.view_id}' does not exist in the canonical graph`,
+        },
+      };
+    }
+    (view.included_elements || []).forEach(id => elements.add(String(id)));
+    (view.included_relationships || []).forEach(id => relationships.add(String(id)));
+    views.add(String(scope.view_id));
+    return { identities: scopeIdentitiesOf(elements, relationships, views) };
+  }
+
+  if (typeof scope.element_id === 'string' && scope.element_id) {
+    const root = (document.elements || []).find(item => item && item.id === scope.element_id);
+    if (!root) {
+      return {
+        status: 'failed',
+        error: {
+          category: 'SCOPE_ELEMENT_NOT_FOUND',
+          message: `Scope element '${scope.element_id}' does not exist in the canonical graph`,
+        },
+      };
+    }
+    const depth = Number.isInteger(scope.depth) && scope.depth > 0 ? scope.depth : 2;
+    elements.add(String(scope.element_id));
+    const queue = [{ elementId: scope.element_id, level: 0 }];
+    const visited = new Set();
+    while (queue.length > 0) {
+      const { elementId, level } = queue.shift();
+      if (visited.has(elementId)) continue;
+      visited.add(elementId);
+      const element = (document.elements || []).find(item => item && item.id === elementId);
+      const subViews = Array.isArray(element && element.subdiagram_views)
+        ? element.subdiagram_views
+        : [];
+      for (const subView of subViews) {
+        const view = (document.views || []).find(item => item && item.view_id === subView.view_id);
+        if (!view) continue;
+        views.add(String(view.view_id));
+        (view.included_relationships || []).forEach(id => relationships.add(String(id)));
+        for (const childId of (view.included_elements || [])) {
+          elements.add(String(childId));
+          if (level < depth - 1) {
+            queue.push({ elementId: childId, level: level + 1 });
+          }
+        }
+      }
+    }
+    return { identities: scopeIdentitiesOf(elements, relationships, views) };
+  }
+
+  return { identities: undefined };
+}
+
+function scopeIdentitiesOf(elements, relationships, views) {
+  return [...elements, ...relationships, ...views];
+}
+
+function applySemanticScopeFilter(document, identities) {
+  if (!document || typeof document !== 'object' || !Array.isArray(identities)) {
+    return document;
+  }
+  const allowed = new Set(identities.map(id => String(id)));
+  if (
+    Array.isArray(document.elements)
+    || Array.isArray(document.relationships)
+    || Array.isArray(document.views)
+  ) {
+    return Object.freeze({
+      ...document,
+      elements: Object.freeze((document.elements || []).filter(item => item && allowed.has(String(item.id)))),
+      relationships: Object.freeze((document.relationships || []).filter(item => item && allowed.has(String(item.id)))),
+      views: Object.freeze((document.views || []).filter(item => item && allowed.has(String(item.view_id)))),
+    });
+  }
+  if (document.businessObjects) {
+    return Object.freeze({
+      ...document,
+      businessObjects: Object.freeze({
+        elements: Object.freeze((document.businessObjects.elements || []).filter(item => item && allowed.has(String(item.id)))),
+        relationships: Object.freeze((document.businessObjects.relationships || []).filter(item => item && allowed.has(String(item.id)))),
+        views: Object.freeze((document.businessObjects.views || []).filter(item => item && allowed.has(String(item.view_id)))),
+      }),
+      semanticSeeds: Object.freeze((document.semanticSeeds || []).filter(seed => seed && allowed.has(String(seed.objectId)))),
+      hitReasons: Object.freeze((document.hitReasons || []).filter(reason => reason && allowed.has(String(reason.objectId)))),
+    });
+  }
+  return document;
+}
+
 function buildBusinessSemanticSummary(retrieved, query = {}) {
   if (retrieved && retrieved.responseProfile === 'business-summary') return retrieved;
   if (retrieved && retrieved.result && retrieved.result.responseProfile === 'business-summary') return retrieved.result;
@@ -3348,8 +3479,10 @@ module.exports = {
   compactMutationResponse,
   createDefaultCanonicalSemanticInitComposition,
   createDefaultProductionSemanticOperatorJourney,
+  applySemanticScopeFilter,
   handleRequest,
   loadContext,
   main,
+  resolveSemanticScope,
   validateDocument,
 };

package/package.json

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