archgraph-argo 0.18.0 → 0.19.0

package/argo/rules/archgraph.instructions.md

@@ -22,7 +22,7 @@ Non-negotiable red lines (MUST). Never skip, simplify, or silently violate them;
 6. Continuously comply with these red lines throughout the session.
 7. Retrieve KG-first and semantic-first. See `<QueryPriorityGuideline>`.
 8. Store content KG-first. See `<ContentStoragePolicy>`.
-9. Never duplicate: reuse first, and handle duplicate rejections by reusing or updating. See `<GraphDeduplication>`.
+9. Never duplicate: reuse is the default; a create blocked as an exact or semantic duplicate must be reused, or explicitly overridden with `onConflict: "allowDuplicate"` + justification. See `<GraphDeduplication>`.
 </CoreRules>
 
 <Ontology>
@@ -54,11 +54,11 @@ Your architecture is ArchiMate 3.2 plus ARGO extensions. Reference files live un
 </ContentStoragePolicy>
 
 <GraphDeduplication>
-Never add what the graph already has. Reuse first.
-1. Before adding an element, relationship, or view, look for an existing match (an element: same type + name; a relationship: same source + type + target + name; a view: same parent + name) and reuse it — pass `onConflict: "reuse"` whenever the identity is known or likely to exist.
-2. If an add is rejected as a duplicate, act on the existing id(s) it returns — reuse or update them. Never retry to force a second copy.
-3. Add a same-name duplicate only for a genuinely distinct object, and only with `onConflict: "allowDuplicate"` plus a real `justification`.
-4. Preview/apply may return semantic near-duplicate hints: review them and reuse when appropriate, otherwise proceed. They are advisory and never block a write.
+Never add what the graph already has. Reuse is the default; there is no reject mode.
+1. `addElement` / `addRelationship` / `addView` default to `onConflict: "reuse"` (find-or-create). An exact match (element: same type + name; relationship: same source + type + target + name; view: same parent + name) is reused — the existing object is attached to the requested view(s) and nothing new is created.
+2. A new ELEMENT is also blocked when it is semantically near an existing element of the same type anywhere in the graph: the call writes nothing and returns `semanticConflicts` with the candidates.
+3. To create despite an exact or semantic duplicate you MUST pass `onConflict: "allowDuplicate"` with a real `justification`. Nothing else creates a duplicate.
+4. On a block, reuse the returned existing element: re-call `addElement` with that element's id (it is then attached to your view), or update it with `updateArchitectureElement`.
 5. Updates are never gated. Never work around a duplicate by editing around it — reuse or update the existing object.
 </GraphDeduplication>
 

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

@@ -149,7 +149,7 @@ const TOOLS = [
       properties: {
         element: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
-        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (type, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing element instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: find-or-create — attach an existing exact (type, name) match; a same-type semantic near-duplicate also blocks creation. allowDuplicate: create anyway (even if a duplicate exists), requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
       },
@@ -193,7 +193,7 @@ const TOOLS = [
       properties: {
         relationship: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
-        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (source, type, target, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing relationship instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: find-or-create — attach an existing exact (source, type, target, name) match. allowDuplicate: create anyway, requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
       },
@@ -236,7 +236,7 @@ const TOOLS = [
       required: ['view'],
       properties: {
         view: { type: 'object' },
-        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject a duplicate (parent_element_id, normalized view_name) and return its candidates. reuse: attach the existing view. allowDuplicate: create anyway, requires justification.' },
+        onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: attach an existing exact (parent, view name) match. allowDuplicate: create anyway, requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
       },

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

@@ -205,7 +205,7 @@ async function executeWpP2Retrieval({
   requireQualifiedVector(vector);
   const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
   const strict = AUDIT_PURPOSES.has(purpose);
-  const topK = resolveTopK();
+  const topK = Number.isInteger(request.topK) && request.topK > 0 ? request.topK : resolveTopK();
   const seedsByType = {};
   for (const channel of CHANNELS) {
     seedsByType[channel.key] = await exhaustChannel({

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

@@ -245,7 +245,7 @@ const TOOLS = [
       properties: {
         element: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
-        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (type, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing element instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: find-or-create — attach an existing exact (type, name) match; a same-type semantic near-duplicate also blocks creation. allowDuplicate: create anyway (even if a duplicate exists), requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         dryRun: { type: 'boolean', description: 'When true, validates and returns the result without writing to the graph. Default: false.' },
         architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
@@ -292,7 +292,7 @@ const TOOLS = [
       properties: {
         relationship: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
-        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (source, type, target, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing relationship instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: find-or-create — attach an existing exact (source, type, target, name) match. allowDuplicate: create anyway, requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         dryRun: { type: 'boolean', description: 'When true, validates and returns the result without writing to the graph. Default: false.' },
         architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
@@ -338,7 +338,7 @@ const TOOLS = [
       required: ['view'],
       properties: {
         view: { type: 'object' },
-        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject a duplicate (parent_element_id, normalized view_name) and return its candidates. reuse: attach the existing view. allowDuplicate: create anyway, requires justification.' },
+        onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy (default reuse). reuse: attach an existing exact (parent, view name) match. allowDuplicate: create anyway, requires a justification.' },
         justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         dryRun: { type: 'boolean', description: 'When true, validates and returns the result without writing to the graph. Default: false.' },
         architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
@@ -480,7 +480,7 @@ function mutationInputSchema() {
             view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
             element_ids: { type: 'array', items: { type: 'string' } },
             relationship_ids: { type: 'array', items: { type: 'string' } },
-            onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy for add* mutations. fail (default): reject an exact natural-key duplicate and return its candidates. reuse: find-or-create — attach the existing object instead of creating a duplicate. allowDuplicate: create a new object, requires a non-empty justification.' },
+            onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy for add* mutations. reuse (default): find-or-create — attach an existing exact-natural-key match instead of creating a duplicate; a same-type semantic near-duplicate also blocks creation unless allowDuplicate is set. allowDuplicate: create a new object even if a duplicate exists, requires a non-empty justification.' },
             justification: { type: 'string', description: 'Required when onConflict is allowDuplicate; recorded as the reason a semantically-equal duplicate is intentionally created.' },
           },
           additionalProperties: false,
@@ -1169,7 +1169,7 @@ function mergeAttributesPatch(existing, patchEntries) {
   return result;
 }
 
-const DUPLICATE_CONFLICT_POLICIES = new Set(['fail', 'reuse', 'allowDuplicate']);
+const DUPLICATE_CONFLICT_POLICIES = new Set(['reuse', 'allowDuplicate']);
 
 // L0 dedup gate: normalize a name to a stable natural-key component. NFKC folds
 // full-width forms, whitespace is collapsed, and case is folded, so " Widget ",
@@ -1221,27 +1221,19 @@ function findDuplicateViews(views, view) {
 }
 
 // Resolve an add against its exact natural-key candidates under the caller's
-// onConflict policy: fail (default) rejects and returns candidates; reuse is
-// find-or-create (attach the existing object); allowDuplicate creates only with
-// a non-empty justification. Semantic similarity (L1) is never handled here.
+// onConflict policy: reuse (default) is find-or-create (attach the existing
+// object); allowDuplicate creates only with a non-empty justification. Semantic
+// similarity is handled separately (the semantic dedup gate), never here.
 function resolveDuplicateConflict(options, candidates) {
   const onConflict = options.onConflict === undefined || options.onConflict === null
-    ? 'fail'
+    ? 'reuse'
     : options.onConflict;
   if (!DUPLICATE_CONFLICT_POLICIES.has(onConflict)) {
-    throw new Error(`onConflict must be one of fail, reuse, allowDuplicate (got '${onConflict}')`);
+    throw new Error(`onConflict must be one of reuse, allowDuplicate (got '${onConflict}')`);
   }
   if (candidates.length === 0) {
     return { action: 'create' };
   }
-  if (onConflict === 'fail') {
-    const error = new Error(
-      `Duplicate ${options.label} already exists (${candidates.map(candidate => candidate.id).join(', ')}). ` +
-      'Reuse it with onConflict:"reuse", or pass onConflict:"allowDuplicate" with a non-empty justification to create a new one.',
-    );
-    error.duplicateConflicts = candidates;
-    throw error;
-  }
   if (onConflict === 'reuse') {
     return { action: 'reuse', existing: candidates[0] };
   }
@@ -1812,16 +1804,33 @@ async function buildMutationResult(context, mutations, write, dependencies) {
     result.guidance = buildFailureGuidance(errors);
   }
 
-  // L1 advisory: semantic near-duplicate suggestions for element adds. Never
-  // blocks or fails the write; preview and apply both surface it.
+  // Semantic dedup gate: a would-be element create is blocked when a same-type
+  // semantic near-duplicate exists, unless the caller explicitly passed
+  // onConflict:'allowDuplicate' (with justification). Never blocks on an
+  // unavailable semantic backend. Both preview and apply surface the outcome.
+  let semanticBlocked = false;
   if (errors.length === 0) {
-    const semanticDedup = await buildSemanticDedupAdvisory(context, mutations, dependencies);
+    const createdAdds = selectCreatedElementAdds(mutations, mutationResult.mutationSummaries);
+    const semanticDedup = await buildSemanticDedupAdvisory(context, createdAdds, dependencies);
     if (semanticDedup) {
       result.semanticDedup = semanticDedup;
+      const gate = evaluateSemanticDedupGate(semanticDedup, createdAdds);
+      if (gate.blocked) {
+        semanticBlocked = true;
+        result.status = 'failed';
+        result.after = beforeSummary;
+        result.semanticConflicts = gate.conflicts;
+        result.errors = gate.conflicts.map(entry => (
+          `Semantic duplicate for element (type '${entry.requested.type}', name '${entry.requested.name}'): `
+          + `${entry.matches.map(match => `${match.id} (score ${match.score})`).join(', ')}. `
+          + 'Reuse the existing element (re-call with that element id), or pass onConflict:"allowDuplicate" with a justification to create a new one.'
+        ));
+        result.guidance = addUnique(result.guidance || [], result.errors);
+      }
     }
   }
 
-  if (errors.length > 0 || !write) {
+  if (errors.length > 0 || semanticBlocked || !write) {
     return result;
   }
 
@@ -2449,6 +2458,9 @@ function compactMutationResponse(payload) {
     if (Array.isArray(payload.guidance)) {
       compact.guidance = payload.guidance;
     }
+    if (Array.isArray(payload.semanticConflicts)) {
+      compact.semanticConflicts = payload.semanticConflicts;
+    }
   }
   return compact;
 }
@@ -2661,15 +2673,16 @@ function memoryHitCard(element, maxDescLen) {
   return card;
 }
 
-// L1 semantic dedup advisory (GraphDeduplication item 3): for each element about
-// to be created, return semantically near elements within a CONTROLLED scope
-// (same ArchiMate type, and - when the add targets views - the union of those
-// views' current members) scoring above a strict threshold. Advisory ONLY: it
-// never rejects or blocks a write; a missing/unavailable semantic backend
-// degrades to an explicit status, never an error.
+// Semantic dedup gate (GraphDeduplication): for each element that would be
+// CREATED, search the WHOLE graph for same-type semantically near elements (a
+// large candidate window, strict threshold). A hit blocks the default create —
+// the caller must reuse an existing candidate or explicitly pass
+// onConflict:'allowDuplicate' with a justification. A missing/unavailable
+// semantic backend degrades to an explicit status, never an error.
 const DEFAULT_SEMANTIC_DEDUP_THRESHOLD = 0.85;
 const SEMANTIC_DEDUP_MAX_QUERIES = 3;
-const SEMANTIC_DEDUP_MAX_MATCHES = 5;
+const SEMANTIC_DEDUP_MAX_MATCHES = 10;
+const SEMANTIC_DEDUP_TOP_K = 25;
 
 function semanticDedupThreshold() {
   const raw = process.env.ARGO_SEMANTIC_DEDUP_THRESHOLD
@@ -2695,6 +2708,47 @@ function collectViewMemberElementIds(document, viewIds) {
   return ids;
 }
 
+// Only element adds that the applied mutation actually CREATED are subject to
+// the L1 advisory. A reuse that found an exact natural-key match creates nothing
+// (created:false) and is skipped; a reuse that fell through to creation
+// (created:true, id === requested id) is advised like any other new element.
+function selectCreatedElementAdds(mutations, mutationSummaries) {
+  const createdIds = new Set(
+    (Array.isArray(mutationSummaries) ? mutationSummaries : [])
+      .filter(summary => summary && summary.type === 'addElement' && summary.created === true)
+      .map(summary => summary.id),
+  );
+  return (Array.isArray(mutations) ? mutations : []).filter(mutation => (
+    mutation
+    && mutation.type === 'addElement'
+    && mutation.element
+    && createdIds.has(mutation.element.id)
+  ));
+}
+
+// Decide whether the semantic candidates block the create. A create is blocked
+// unless the caller explicitly opted into allowDuplicate (with justification).
+function evaluateSemanticDedupGate(advisory, mutations) {
+  if (!advisory || advisory.status !== 'passed' || !Array.isArray(advisory.candidates)) {
+    return { blocked: false, conflicts: [] };
+  }
+  const byId = new Map((Array.isArray(mutations) ? mutations : [])
+    .filter(mutation => mutation && mutation.type === 'addElement' && mutation.element)
+    .map(mutation => [mutation.element.id, mutation]));
+  const conflicts = [];
+  for (const entry of advisory.candidates) {
+    if (!entry || !Array.isArray(entry.matches) || entry.matches.length === 0) {
+      continue;
+    }
+    const mutation = byId.get(entry.requested && entry.requested.id);
+    const overridden = mutation && mutation.onConflict === 'allowDuplicate';
+    if (!overridden) {
+      conflicts.push(entry);
+    }
+  }
+  return { blocked: conflicts.length > 0, conflicts };
+}
+
 async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
   if (process.env.ARGO_MCP_SEMANTIC_DEDUP === '0') {
     return undefined;
@@ -2705,7 +2759,6 @@ async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
     && mutation.element
     && typeof mutation.element.name === 'string'
     && mutation.element.name.trim() !== ''
-    && mutation.onConflict !== 'reuse'
   ));
   if (addedElements.length === 0) {
     return undefined;
@@ -2734,7 +2787,7 @@ async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
       const intent = [element.type, element.name, element.description]
         .filter(part => typeof part === 'string' && part.trim() !== '')
         .join(' ');
-      const retrieved = await journey.query({ purpose: 'general', intent });
+      const retrieved = await journey.query({ purpose: 'general', intent, topK: SEMANTIC_DEDUP_TOP_K });
       const source = retrieved && (retrieved.result || retrieved.document) || retrieved;
       const subset = buildCanonicalSemanticDocumentSubset(source, context.document);
       const elements = subset && subset.status === 'passed' && subset.document
@@ -2744,7 +2797,6 @@ async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
         .filter(candidate => candidate && candidate.id !== element.id && typeof candidate.semanticScore === 'number')
         .filter(candidate => !element.type || candidate.type === element.type)
         .filter(candidate => candidate.semanticScore >= threshold)
-        .filter(candidate => targetMemberIds.size === 0 || targetMemberIds.has(candidate.id))
         .sort((left, right) => right.semanticScore - left.semanticScore)
         .slice(0, SEMANTIC_DEDUP_MAX_MATCHES)
         .map(candidate => ({
@@ -2768,7 +2820,7 @@ async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
     status: 'passed',
     advisoryOnly: true,
     threshold,
-    scope: 'same type; when view_ids are given, restricted to those views\' current members',
+    scope: 'whole graph, same type',
     candidates,
     has_suggestions: candidates.some(entry => entry.matches.length > 0),
   };
@@ -4106,6 +4158,8 @@ module.exports = {
   TOOLS,
   applyMutations,
   buildSemanticDedupAdvisory,
+  selectCreatedElementAdds,
+  evaluateSemanticDedupGate,
   callTool,
   compactMutationResponse,
   createDefaultCanonicalSemanticInitComposition,

package/package.json

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