archgraph-argo 0.20.0 → 0.20.2

package/argo/.env.example

@@ -0,0 +1,140 @@
+# =============================================================================
+# ArchGraph (archgraph-argo) environment configuration — EXAMPLE.
+#
+# Copy this file to the live env file and fill in real values:
+#   Windows      %USERPROFILE%\.argo\.env
+#   Linux/macOS  ~/.argo/.env
+# The live file is git-ignored and MUST stay untracked with a restricted ACL;
+# this example is committed and contains no secrets.
+#
+# PART 1 keys are the ONLY keys accepted inside the .env file (any unknown key
+# makes the secret-file preflight reject the whole file). PART 2 keys are
+# host/process-level only — set them in the host/MCP launch config or shell, NOT
+# here. Empty values below are placeholders.
+# =============================================================================
+
+
+# -----------------------------------------------------------------------------
+# PART 1 — .env file keys
+# -----------------------------------------------------------------------------
+
+# --- Embedding provider (required) — powers vector semantic retrieval -------
+# OpenAI-compatible embedding endpoint base URL (no trailing slash).
+ARGO_EMBEDDING_BASE_URL=
+# Embedding model id (e.g. qwen3.7-text-embedding).
+ARGO_EMBEDDING_MODEL=
+# Provider label recorded in evidence; also the rerank fallback provider.
+ARGO_EMBEDDING_PROVIDER=
+# Model version / qualification label (recorded evidence only).
+ARGO_EMBEDDING_MODEL_VERSION=
+# Embedding vector dimension; must match the model (current profiles: 1536).
+ARGO_EMBEDDING_DIMENSIONS=
+
+# --- Neo4j (required) — structural projection + vector/full-text store ------
+# Neo4j connection URI (e.g. neo4j://127.0.0.1:7687).
+ARGO_NEO4J_DATABASE_URL=
+# Neo4j username.
+ARGO_NEO4J_DATABASE_USERNAME=
+# Neo4j password. SECRET: value must come from the untracked, ACL-restricted
+# .env (or direct process injection) only — never commit it.
+ARGO_NEO4J_DATABASE_PASSWORD=
+# Optional: override the Neo4j database name. Default = sanitized repository
+# folder name (e.g. repo "archgraph" -> database "archgraph").
+ARGO_NEO4J_DATABASE=
+
+# --- Secrets (required) ------------------------------------------------------
+# API key for the embedding endpoint above. SECRET; also the fallback key for
+# the reranker when ARGO_RERANK_API_KEY is not set. Never commit it.
+QWEN_KEY=
+
+# --- Semantic retrieval tuning (optional; safe defaults shown) --------------
+# Similarity threshold, memory purposes (recall-oriented). Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD=
+# Memory threshold override for the Element channel. Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD_ELEMENT=
+# Memory threshold override for the ArchitectureRelationship channel. Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD_RELATIONSHIP=
+# Memory threshold override for the View channel. Default 0.55.
+ARGO_SEMANTIC_MEMORY_THRESHOLD_VIEW=
+# Similarity threshold, audit purpose (precision-oriented). Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD=
+# Audit threshold override for the Element channel. Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD_ELEMENT=
+# Audit threshold override for the ArchitectureRelationship channel. Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD_RELATIONSHIP=
+# Audit threshold override for the View channel. Default 0.8.
+ARGO_SEMANTIC_AUDIT_THRESHOLD_VIEW=
+# Bound on returned candidates per retrieval. Default 8.
+ARGO_SEMANTIC_TOP_K=
+
+# --- Hybrid retrieval (vector + lexical BM25 via RRF; optional) -------------
+# Master switch. "1" enables hybrid fusion; unset/"0" = vector-only (default off).
+ARGO_SEMANTIC_HYBRID=
+# Weight of the vector channel in the RRF fusion. Default 3.
+ARGO_SEMANTIC_HYBRID_VECTOR_WEIGHT=
+# Weight of the lexical (full-text) channel in the RRF fusion. Default 1.
+ARGO_SEMANTIC_HYBRID_LEXICAL_WEIGHT=
+# RRF smoothing constant k. Default 60.
+ARGO_SEMANTIC_HYBRID_RRF_K=
+# Candidate pool size pulled per channel before fusion. Default 16.
+ARGO_SEMANTIC_HYBRID_TOP_K=
+
+# --- LLM rerank (second-stage reordering; optional) -------------------------
+# Master switch. "1" enables rerank; unset/"0" = off (default off). Fail-open:
+# any error/timeout keeps the original order.
+ARGO_SEMANTIC_RERANK=
+# Rerank model when using the embedding provider fallback. Default qwen-turbo.
+ARGO_SEMANTIC_RERANK_MODEL=
+# Candidate pool size offered to the reranker. Default 20.
+ARGO_SEMANTIC_RERANK_POOL=
+# Max ids the reranker may return. Default 8.
+ARGO_SEMANTIC_RERANK_RETURN=
+# Per-request rerank timeout in ms (AbortController). Default 8000.
+ARGO_SEMANTIC_RERANK_TIMEOUT_MS=
+# Dedicated rerank provider (optional). When unset, rerank falls back to the
+# embedding provider above. Use these to point rerank at another provider/model
+# (e.g. DeepSeek: base https://api.deepseek.com, model deepseek-flash).
+ARGO_RERANK_BASE_URL=
+# Dedicated rerank API key. SECRET. Falls back to QWEN_KEY when unset.
+ARGO_RERANK_API_KEY=
+# Dedicated rerank provider label (informational; defaults to the embedding provider label).
+ARGO_RERANK_PROVIDER=
+# Dedicated rerank model id (overrides ARGO_SEMANTIC_RERANK_MODEL).
+ARGO_RERANK_MODEL=
+
+# --- Live end-to-end opt-ins (optional; normally unset) ---------------------
+# "1" allows the live embedding-provider E2E to hit the real network.
+ARGO_LIVE_PROVIDER_E2E=
+# "1" allows the live W3.1 mutation-vector E2E to hit the real network.
+ARGO_W31_LIVE_MUTATION_VECTOR_E2E=
+
+
+# -----------------------------------------------------------------------------
+# PART 2 — host / process-level only (do NOT put these in .env)
+# Set in the host or MCP launch configuration (mcp.json / opencode.json env,
+# dsh plugin, or the shell), never in the .env file.
+# -----------------------------------------------------------------------------
+# Point at a non-default env file path.
+# ARGO_ENV_FILE=
+# Pin the workspace/repository root the MCP server serves.
+# ARGO_REPO_ROOT=
+# Path to the Enterprise Architect model file (.qea) to project to/from.
+# ARGO_EA_QEA=
+# Semicolon-separated roots for multi-workspace hosts (DSH plugin).
+# ARGO_WORKSPACE_ROOTS=
+# Explicit path to the argo MCP server entry script (DSH plugin).
+# ARGO_SERVER_PATH=
+# URL of the graph-mcp HTTP bridge.
+# GRAPH_MCP_URL=
+# "1" enables verbose EA <-> .qea sync debug logging.
+# EA_QEA_DEBUG=
+# Architecture test runner timeout in ms.
+# ARGO_TEST_TIMEOUT_MS=
+# "1" prints the full mutation response for debugging.
+# ARGO_MCP_MUTATION_RESPONSE_DEBUG=
+# "0" disables the pre-write semantic dedup advisory (default: enabled).
+# ARGO_MCP_SEMANTIC_DEDUP=
+# Similarity threshold for the semantic dedup advisory. Default 0.85.
+# ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD=
+# Alias of ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD (takes precedence when set).
+# ARGO_SEMANTIC_DEDUP_THRESHOLD=

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

@@ -835,15 +835,26 @@ function scopeCanonicalIdentitiesForChannel(identities, channel) {
   });
 }
 
+// Semantic vector records store their canonicalIdentity channel-prefixed
+// (e.g. "Element:widget-1") so the scoped Cypher `node.canonicalIdentity IN
+// $canonicalIdentities` matches. Every consumer of a seed's `id` — purpose
+// closure anchors, provenance keys, and the canonical-subset score lookup —
+// however keys on the BARE canonical graph id. Expose the bare id as `id` and
+// keep the prefixed value as `canonicalIdentity` so a seed resolves against the
+// canonical graph instead of a phantom prefixed id.
+function bareCanonicalId(id) {
+  return String(id).replace(/^[^:]*:/, '');
+}
+
 function normalizeVectorRecord(raw, channel) {
   if (!raw || typeof raw !== 'object') return undefined;
-  const id = raw.canonicalIdentity || raw.id || raw.objectId;
+  const canonicalIdentity = raw.canonicalIdentity || raw.id || raw.objectId;
   const score = numberValue(raw.score);
-  if (!id || !Number.isFinite(score)) return undefined;
+  if (!canonicalIdentity || !Number.isFinite(score)) return undefined;
   return {
     ...raw,
-    id,
-    canonicalIdentity: id,
+    id: bareCanonicalId(canonicalIdentity),
+    canonicalIdentity,
     objectType: channel.objectType,
     channel: channel.channel,
     score,
@@ -1157,5 +1168,7 @@ module.exports = {
   auditThresholdFor,
   resolveTopK,
   scopeCanonicalIdentitiesForChannel,
+  bareCanonicalId,
+  normalizeVectorRecord,
   AUDIT_PURPOSES,
 };

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

@@ -34,6 +34,13 @@ const RETRIEVAL_TUNING_KEYS = Object.freeze([
   'ARGO_SEMANTIC_AUDIT_THRESHOLD_RELATIONSHIP',
   'ARGO_SEMANTIC_AUDIT_THRESHOLD_VIEW',
   'ARGO_SEMANTIC_TOP_K',
+  // Hybrid (vector + lexical RRF) retrieval (P2). Off unless
+  // ARGO_SEMANTIC_HYBRID=1; weights/k/top-K tune the fusion.
+  'ARGO_SEMANTIC_HYBRID',
+  'ARGO_SEMANTIC_HYBRID_VECTOR_WEIGHT',
+  'ARGO_SEMANTIC_HYBRID_LEXICAL_WEIGHT',
+  'ARGO_SEMANTIC_HYBRID_RRF_K',
+  'ARGO_SEMANTIC_HYBRID_TOP_K',
   // Rerank (P3) tuning + optional dedicated rerank provider. When the provider
   // keys are unset the reranker falls back to the embedding provider (qwen).
   'ARGO_SEMANTIC_RERANK',
@@ -525,4 +532,10 @@ module.exports = {
   resolveApprovedLiveConfiguration,
   withApprovedLiveConfigurationTestComposition,
   posixModeIsSecretSafe,
+  // The authoritative set of keys an approved `.env` file may carry. The
+  // committed `.env.example` must document exactly this set (see
+  // tests/env-example.test.js); SECRET_KEYS marks the subset that must be
+  // preflighted as secrets.
+  ENV_FILE_KEYS: READABLE_KEYS,
+  ENV_FILE_SECRET_KEYS: Object.freeze(Array.from(SECRET_KEYS)),
 };

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

@@ -3462,7 +3462,11 @@ function buildCanonicalSemanticDocumentSubset(source, canonicalDocument = undefi
     if (!item) continue;
     const numericScore = Number(item.semanticScore);
     if (!Number.isFinite(numericScore)) continue;
-    const key = String(item.id !== undefined ? item.id : item.view_id);
+    // Evidence ids may still carry the channel prefix (real Neo4j shape); the
+    // seed-score map and canonical lookups are keyed on the bare canonical id,
+    // so normalize before comparing (otherwise the rank-derived score lands on
+    // a phantom prefixed key and the tiny fused RRF score wins for the element).
+    const key = String(item.id !== undefined ? item.id : item.view_id).replace(/^[^:]*:/, '');
     if (key && (!semanticScoreById.has(key) || numericScore > semanticScoreById.get(key))) {
       semanticScoreById.set(key, numericScore);
     }

package/install-argo.ps1

@@ -1008,6 +1008,16 @@ if ($SkipEnv) {
         $lines += "$key=$value"
     }
 
+    # Preserve any extra keys already present in .env but not part of the
+    # interactive prompt list (e.g. semantic retrieval tuning: hybrid/rerank/
+    # thresholds). Without this a re-deploy would silently drop them. They are
+    # documented in argo/.env.example.
+    foreach ($key in ($existing.Keys | Sort-Object)) {
+        if ($envKeys -notcontains $key) {
+            $lines += "$key=$($existing[$key])"
+        }
+    }
+
     [System.IO.File]::WriteAllLines(
         $envPath,
         $lines,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {
@@ -17,6 +17,7 @@
     "argo/skills/ea-human-reconcile",
     "argo/rules",
     "argo/package.json",
+    "argo/.env.example",
     "vendor",
     "install-argo.ps1",
     "bin",