archgraph-argo 0.19.1 → 0.20.1

package/README.md

@@ -7,6 +7,10 @@ An architecture-graph driven framework for Agentic Engineering.
 ArchGraph builds a **unified language** that puts harness design and target product design into
 **one model** — so you get a single view to work and observe, and real control over your agents.
 
+It doubles as a **long-term memory for coding agents**: an ArchiMate 3.2 intent graph exposed through
+a single read/write MCP interface. Writes are deduplicated, so the graph stays clean and semantic
+recall stays precise. See the [home page](https://archgraph.org/) for the full capability set.
+
 ![alt text](docs/diagrams/image.png)
 
 ## Architecture
@@ -71,7 +75,9 @@ After installing, open your project and start a coding agent. It will:
 
 1. locate the architecture element behind the task before changing anything,
 2. arm itself with that element's Skills and Rules,
-3. work test-first (GIVEN-WHEN-THEN), and trace every commit back to the graph.
+3. work test-first (GIVEN-WHEN-THEN), and trace every commit back to the graph,
+4. reuse an existing element, relationship, or view instead of creating a duplicate — the write path
+   deduplicates by identity and flags a semantically near element of the same type.
 
 The intent architecture graph — modelled in **ArchiMate 3.2** — is the single source of truth.
 

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

@@ -14,6 +14,21 @@ const {
   getWorkspaceRoot,
   resolveArgoPath,
 } = require('../argo-paths.js');
+const {
+  isHybridEnabled,
+  hybridTopK,
+  hybridWeights,
+  rrfK,
+  fuseChannelSeeds,
+  sanitizeFulltextQuery,
+} = require('./hybridRetrieval.js');
+const {
+  isRerankEnabled,
+  rerankConfig,
+  resolveRerankProvider,
+  rerankCandidates,
+  applyRerankOrder,
+} = require('./rerankRetrieval.js');
 
 const APPROVED_SOURCE_KEYS = Object.freeze([
   'ARGO_EMBEDDING_BASE_URL',
@@ -75,6 +90,20 @@ const VECTOR_QUERY_CYPHER_SCOPED = [
   'RETURN properties(node) AS record, score',
   'ORDER BY score DESC',
 ].join('\n');
+const LEXICAL_QUERY_CYPHER = [
+  'CALL db.index.fulltext.queryNodes($indexName, $queryText, { limit: $topK })',
+  'YIELD node, score',
+  'WHERE node.channel = $channel',
+  'RETURN properties(node) AS record, score',
+  'ORDER BY score DESC',
+].join('\n');
+const LEXICAL_QUERY_CYPHER_SCOPED = [
+  'CALL db.index.fulltext.queryNodes($indexName, $queryText, { limit: $topK })',
+  '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',
@@ -206,18 +235,49 @@ async function executeWpP2Retrieval({
   const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
   const strict = AUDIT_PURPOSES.has(purpose);
   const topK = Number.isInteger(request.topK) && request.topK > 0 ? request.topK : resolveTopK();
+  const scoped = Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0;
+  const hybrid = isHybridEnabled();
+  const lexicalTopK = hybridTopK();
+  const fusionK = rrfK();
+  const fusionWeights = hybridWeights();
+  const rerank = isRerankEnabled();
+  const rerankOptions = rerankConfig();
+  const rerankProvider = rerank ? resolveRerankProvider(configurationEvidence.configuration) : null;
+  // Rerank needs a larger candidate pool than the final top-K.
+  const pool = rerank ? Math.max(topK, rerankOptions.poolSize) : topK;
   const seedsByType = {};
   for (const channel of CHANNELS) {
-    seedsByType[channel.key] = await exhaustChannel({
+    const vectorSeeds = await exhaustChannel({
       channel,
       neo4jDriver: composition.neo4jDriver,
       vector,
       threshold: strict ? auditThresholdFor(channel) : memoryThresholdFor(channel),
-      maxSeeds: topK,
-      ...(Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0
-        ? { canonicalIdentities }
-        : {}),
+      maxSeeds: pool,
+      ...(scoped ? { canonicalIdentities } : {}),
     });
+    let seeds = vectorSeeds;
+    if (hybrid) {
+      const lexicalSeeds = await exhaustLexicalChannel({
+        channel,
+        neo4jDriver: composition.neo4jDriver,
+        queryText: request.intent,
+        maxSeeds: lexicalTopK,
+        ...(scoped ? { canonicalIdentities } : {}),
+      });
+      seeds = fuseChannelSeeds({ vectorSeeds, lexicalSeeds, k: fusionK, limit: Math.max(pool, lexicalTopK), weights: fusionWeights });
+    }
+    if (rerank && seeds.length > 1) {
+      const ordered = await rerankCandidates({
+        query: request.intent,
+        candidates: seeds,
+        provider: rerankProvider,
+        transport: composition.transport,
+        maxReturn: rerankOptions.maxReturn,
+      });
+      // fail-open: a null/empty order keeps the original ordering
+      seeds = applyRerankOrder(seeds, ordered, topK);
+    }
+    seedsByType[channel.key] = seeds;
   }
   return completeSemanticResult({
     request: completeRequest,
@@ -303,6 +363,9 @@ async function executeProductionNeo4jOperation(configuration, operation) {
       ...record.get('record'),
       score: numberValue(record.get('score')),
     }));
+    if (operation.kind === 'semantic-lexical-query') {
+      return { records };
+    }
     const offset = operation.parameters.offset;
     const windowSize = operation.parameters.windowSize;
     const returnedCount = Math.max(0, records.length - offset);
@@ -709,6 +772,53 @@ async function exhaustChannel({
   return Object.freeze(accepted);
 }
 
+// Lexical (full-text/BM25) sibling of exhaustChannel. Additive and fail-open:
+// it returns [] when the query text is blank, when the full-text index is
+// missing, or on any error, so hybrid retrieval can never break the baseline.
+async function exhaustLexicalChannel({
+  channel,
+  neo4jDriver,
+  queryText,
+  maxSeeds,
+  canonicalIdentities,
+}) {
+  if (typeof queryText !== 'string' || queryText.trim() === '') {
+    return Object.freeze([]);
+  }
+  const safeQuery = sanitizeFulltextQuery(queryText);
+  if (safeQuery === '') {
+    return Object.freeze([]);
+  }
+  const scoped = Array.isArray(canonicalIdentities) && canonicalIdentities.length > 0;
+  const scopedCanonicalIdentities = scoped
+    ? scopeCanonicalIdentitiesForChannel(canonicalIdentities, channel)
+    : canonicalIdentities;
+  const effectiveMax = Number.isInteger(maxSeeds) && maxSeeds > 0 ? maxSeeds : INITIAL_WINDOW_SIZE;
+  const indexName = `${channel.indexName}_fulltext`;
+  try {
+    const result = await neo4jDriver.execute(Object.freeze({
+      kind: 'semantic-lexical-query',
+      channel: channel.channel,
+      indexName,
+      cypher: scoped ? LEXICAL_QUERY_CYPHER_SCOPED : LEXICAL_QUERY_CYPHER,
+      parameters: Object.freeze({
+        indexName,
+        channel: channel.channel,
+        queryText: safeQuery,
+        topK: effectiveMax,
+        ...(scoped ? { canonicalIdentities: scopedCanonicalIdentities } : {}),
+      }),
+    }));
+    const records = Array.isArray(result && result.records) ? result.records : [];
+    return Object.freeze(records
+      .map(raw => normalizeVectorRecord(raw, channel))
+      .filter(Boolean)
+      .slice(0, effectiveMax));
+  } catch {
+    return Object.freeze([]);
+  }
+}
+
 // Scope identities come from the canonical graph as BARE ids (e.g.
 // "memory-eval-bench-wp-001"), but the semantic vector records store their
 // canonicalIdentity with a channel prefix (e.g. "Element:memory-eval-bench-wp-001").

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

@@ -0,0 +1,114 @@
+'use strict';
+
+// Hybrid retrieval fusion (P2). Pure, dependency-free helpers so the fusion
+// logic is fully unit-testable and the production retrieval path can stay
+// additive: when hybrid is OFF nothing here is invoked.
+//
+// Design:
+// - vector (dense) and lexical (full-text/BM25) ranked lists are fused with
+//   Reciprocal Rank Fusion: score(id) = sum over lists of 1/(k + rank).
+// - RRF needs no score normalization between the two very different score
+//   scales, and guarantees the union is retained (recall can only increase).
+
+const DEFAULT_RRF_K = 60;
+const DEFAULT_HYBRID_TOP_K = 16;
+// Vector-first weighting: the dense channel is the stronger signal on this
+// graph, so lexical only nudges the ranking and rescues misses.
+const DEFAULT_VECTOR_WEIGHT = 3;
+const DEFAULT_LEXICAL_WEIGHT = 1;
+
+function isHybridEnabled(env = process.env) {
+  return String((env && env.ARGO_SEMANTIC_HYBRID) || '') === '1';
+}
+
+function hybridWeights(env = process.env) {
+  const vector = Number(env && env.ARGO_SEMANTIC_HYBRID_VECTOR_WEIGHT);
+  const lexical = Number(env && env.ARGO_SEMANTIC_HYBRID_LEXICAL_WEIGHT);
+  return [
+    Number.isFinite(vector) && vector >= 0 ? vector : DEFAULT_VECTOR_WEIGHT,
+    Number.isFinite(lexical) && lexical >= 0 ? lexical : DEFAULT_LEXICAL_WEIGHT,
+  ];
+}
+
+function hybridTopK(env = process.env) {
+  const value = Number(env && env.ARGO_SEMANTIC_HYBRID_TOP_K);
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_HYBRID_TOP_K;
+}
+
+function rrfK(env = process.env) {
+  const value = Number(env && env.ARGO_SEMANTIC_HYBRID_RRF_K);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_RRF_K;
+}
+
+// Lucene full-text queries reject raw punctuation (e.g. "A --(Flow)--> B") and
+// blow the maxClauseCount on very long text (long Chinese descriptions become
+// hundreds of single-character clauses). Truncate first, then escape the
+// reserved query-syntax characters so any intent/name/statement is literal.
+// Returns '' for blank input (caller skips).
+const MAX_FULLTEXT_QUERY_LENGTH = 256;
+
+function sanitizeFulltextQuery(text) {
+  const value = String(text === undefined || text === null ? '' : text)
+    .trim()
+    .slice(0, MAX_FULLTEXT_QUERY_LENGTH);
+  if (!value) return '';
+  return value
+    .replace(/&&/g, '\\&\\&')
+    .replace(/\|\|/g, '\\|\\|')
+    .replace(/([+\-!(){}[\]^"~*?:\\/])/g, '\\$1');
+}
+
+// Fuse ranked record lists by id (canonicalIdentity). Each list is expected to be
+// already sorted best-first. Returns records carrying the fused `score`, with
+// the first-seen record object preserved (so downstream keeps its fields).
+function rrfFuse(lists, options = {}) {
+  const k = Number.isFinite(options.k) && options.k > 0 ? options.k : DEFAULT_RRF_K;
+  const weights = Array.isArray(options.weights) ? options.weights : [];
+  const byId = new Map();
+  (Array.isArray(lists) ? lists : []).forEach((list, listIndex) => {
+    const weight = Number.isFinite(weights[listIndex]) && weights[listIndex] >= 0 ? weights[listIndex] : 1;
+    (Array.isArray(list) ? list : []).forEach((record, rank) => {
+      if (!record || !record.id) return;
+      const entry = byId.get(record.id) || { id: record.id, record, score: 0, matchedLists: 0 };
+      entry.score += weight / (k + rank + 1);
+      entry.matchedLists += 1;
+      if (!entry.record) entry.record = record;
+      byId.set(record.id, entry);
+    });
+  });
+  return [...byId.values()]
+    .sort((left, right) => (right.score - left.score) || String(left.id).localeCompare(String(right.id)))
+    .map(entry => Object.freeze({
+      ...entry.record,
+      id: entry.id,
+      canonicalIdentity: entry.id,
+      score: entry.score,
+      rrfScore: entry.score,
+      matchedLists: entry.matchedLists,
+    }));
+}
+
+// Fuse the two per-channel seed lists. With an empty lexical list this preserves
+// the vector ordering (RRF on a single list is order-preserving) — which is what
+// makes "hybrid ON but no lexical hit" behave like the vector-only baseline.
+function fuseChannelSeeds({ vectorSeeds = [], lexicalSeeds = [], k = DEFAULT_RRF_K, limit, weights } = {}) {
+  const fused = rrfFuse([
+    Array.isArray(vectorSeeds) ? vectorSeeds.filter(Boolean) : [],
+    Array.isArray(lexicalSeeds) ? lexicalSeeds.filter(Boolean) : [],
+  ], { k, ...(Array.isArray(weights) ? { weights } : {}) });
+  return Number.isInteger(limit) && limit > 0 ? fused.slice(0, limit) : fused;
+}
+
+module.exports = {
+  DEFAULT_RRF_K,
+  DEFAULT_HYBRID_TOP_K,
+  DEFAULT_VECTOR_WEIGHT,
+  DEFAULT_LEXICAL_WEIGHT,
+  isHybridEnabled,
+  hybridTopK,
+  hybridWeights,
+  rrfK,
+  rrfFuse,
+  fuseChannelSeeds,
+  sanitizeFulltextQuery,
+};

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

@@ -34,6 +34,24 @@ 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',
+  'ARGO_SEMANTIC_RERANK_MODEL',
+  'ARGO_SEMANTIC_RERANK_POOL',
+  'ARGO_SEMANTIC_RERANK_RETURN',
+  'ARGO_SEMANTIC_RERANK_TIMEOUT_MS',
+  'ARGO_RERANK_BASE_URL',
+  'ARGO_RERANK_API_KEY',
+  'ARGO_RERANK_PROVIDER',
+  'ARGO_RERANK_MODEL',
 ]);
 const OPT_IN_KEYS = Object.freeze({
   ARGO_LIVE_PROVIDER_E2E: 'LIVE_PROVIDER_E2E_OPT_IN_REQUIRED',
@@ -47,7 +65,7 @@ const READABLE_KEYS = Object.freeze([
 ]);
 const LEGACY_KEYS = Object.freeze(['ARGO_NEO4J_URI', 'ARGO_NEO4J_USERNAME', 'ARGO_NEO4J_PASSWORD']);
 const PROHIBITED_RUNTIME_FIELD_KEYS = Object.freeze(['neo4jUri', 'embeddingCredential']);
-const SECRET_KEYS = new Set(['ARGO_NEO4J_DATABASE_PASSWORD', 'QWEN_KEY']);
+const SECRET_KEYS = new Set(['ARGO_NEO4J_DATABASE_PASSWORD', 'QWEN_KEY', 'ARGO_RERANK_API_KEY']);
 const APPROVED = Object.freeze({
   ARGO_EMBEDDING_BASE_URL: 'https://llm-clids9mqc5o1mbvb.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
   ARGO_EMBEDDING_MODEL: 'qwen3.7-text-embedding',
@@ -514,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/graph-rag/mutationEmbeddingVectorLifecycle.js

@@ -531,6 +531,7 @@ function buildPersistentWork(canonicalWrite, configuration, versions) {
           contentVersion: `content:${fingerprint(content)}`,
           indexVersion: `index:${fingerprint({ objectId, content, canonicalVersion: versions.canonicalVersion })}`,
           content,
+          searchText: content,
         }));
       } else {
         tombstones.push(Object.freeze(base));

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

@@ -0,0 +1,150 @@
+'use strict';
+
+// Two-stage rerank (P3): after the (vector, or hybrid) candidate pool is
+// retrieved, an LLM listwise reranker reorders it by relevance to the query.
+// Additive and fail-open: when disabled nothing runs; any error returns null so
+// the caller keeps the original ordering. Pure helpers are exported for tests.
+
+const DEFAULT_RERANK_MODEL = 'qwen-turbo';
+const DEFAULT_RERANK_POOL = 20;
+const DEFAULT_RERANK_RETURN = 8;
+const DEFAULT_RERANK_TIMEOUT_MS = 8000;
+
+function rerankTimeoutMs(env = process.env) {
+  const value = Number(env && env.ARGO_SEMANTIC_RERANK_TIMEOUT_MS);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_RERANK_TIMEOUT_MS;
+}
+
+function isRerankEnabled(env = process.env) {
+  return String((env && env.ARGO_SEMANTIC_RERANK) || '') === '1';
+}
+
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim() !== '') return value.trim();
+  }
+  return '';
+}
+
+// Rerank provider resolution, DECOUPLED from the embedding provider:
+// - dedicated keys (ARGO_RERANK_BASE_URL / ARGO_RERANK_API_KEY / ARGO_RERANK_PROVIDER
+//   / ARGO_RERANK_MODEL) win when set, so a different provider/model can be used;
+// - otherwise it falls back to the embedding configuration (qwen by default).
+function resolveRerankProvider(configuration = {}, env = process.env) {
+  const baseUrl = firstNonEmpty(env.ARGO_RERANK_BASE_URL, configuration.embeddingBaseUrl);
+  const apiKey = firstNonEmpty(env.ARGO_RERANK_API_KEY, configuration.qwenKey);
+  const model = firstNonEmpty(env.ARGO_RERANK_MODEL, env.ARGO_SEMANTIC_RERANK_MODEL, DEFAULT_RERANK_MODEL);
+  const provider = firstNonEmpty(env.ARGO_RERANK_PROVIDER, configuration.embeddingProvider, 'qwen');
+  return { baseUrl, apiKey, model, provider };
+}
+
+function rerankConfig(env = process.env) {
+  const model = (env && typeof env.ARGO_SEMANTIC_RERANK_MODEL === 'string' && env.ARGO_SEMANTIC_RERANK_MODEL.trim())
+    ? env.ARGO_SEMANTIC_RERANK_MODEL.trim()
+    : DEFAULT_RERANK_MODEL;
+  const pool = Number(env && env.ARGO_SEMANTIC_RERANK_POOL);
+  const maxReturn = Number(env && env.ARGO_SEMANTIC_RERANK_RETURN);
+  return {
+    model,
+    poolSize: Number.isInteger(pool) && pool > 0 ? pool : DEFAULT_RERANK_POOL,
+    maxReturn: Number.isInteger(maxReturn) && maxReturn > 0 ? maxReturn : DEFAULT_RERANK_RETURN,
+  };
+}
+
+function candidateText(record) {
+  const raw = record && (record.searchText || record.description || record.name || '');
+  return String(raw).replace(/\s+/g, ' ').slice(0, 160);
+}
+
+// Accept the canonical id or its bare/suffix form (models often drop the
+// channel prefix), dedupe, ignore anything not in the candidate set.
+function parseRerankOrder(content, candidateIds) {
+  let parsed;
+  try { parsed = JSON.parse(content); } catch { return []; }
+  const raw = Array.isArray(parsed && parsed.order) ? parsed.order : [];
+  const byKey = new Map();
+  for (const id of candidateIds) {
+    const text = String(id);
+    byKey.set(text, id);
+    byKey.set(text.split(':').slice(1).join(':'), id);
+    byKey.set(text.split(':').pop(), id);
+  }
+  const seen = new Set();
+  const order = [];
+  for (const value of raw) {
+    const canonical = byKey.get(String(value));
+    if (canonical && !seen.has(canonical)) {
+      seen.add(canonical);
+      order.push(canonical);
+    }
+  }
+  return order;
+}
+
+// Reorder seeds by the model's order, then append any seeds the model omitted
+// (nothing is lost), bounded by `limit`.
+function applyRerankOrder(seeds, orderedIds, limit) {
+  const list = Array.isArray(seeds) ? seeds.filter(Boolean) : [];
+  const byId = new Map(list.map(seed => [seed.id, seed]));
+  const out = [];
+  const seen = new Set();
+  for (const id of (Array.isArray(orderedIds) ? orderedIds : [])) {
+    const seed = byId.get(id);
+    if (seed && !seen.has(id)) { seen.add(id); out.push(seed); }
+  }
+  for (const seed of list) {
+    if (!seen.has(seed.id)) { seen.add(seed.id); out.push(seed); }
+  }
+  return Number.isInteger(limit) && limit > 0 ? out.slice(0, limit) : out;
+}
+
+async function rerankCandidates({ query, candidates, provider, transport, maxReturn, timeoutMs } = {}) {
+  const list = Array.isArray(candidates) ? candidates.filter(candidate => candidate && candidate.id) : [];
+  if (list.length < 2 || typeof query !== 'string' || query.trim() === '') return null;
+  if (!provider || !transport || typeof transport.request !== 'function') return null;
+  const baseUrl = typeof provider.baseUrl === 'string' ? provider.baseUrl : '';
+  const apiKey = typeof provider.apiKey === 'string' ? provider.apiKey : '';
+  if (baseUrl === '' || apiKey === '') return null;
+  const model = provider.model || DEFAULT_RERANK_MODEL;
+  const body = {
+    model,
+    temperature: 0,
+    response_format: { type: 'json_object' },
+    messages: [
+      { role: 'system', content: 'You rank architecture elements by relevance to a query. Return ONLY JSON {"order":[ids best-first]} using only the candidate ids.' },
+      { role: 'user', content: `Query: ${query}\n\nCandidates (id\\ttext):\n${list.map(candidate => `${candidate.id}\t${candidateText(candidate)}`).join('\n')}\n\nReturn up to ${Math.min(maxReturn || DEFAULT_RERANK_RETURN, list.length)} ids best-first.` },
+    ],
+  };
+  const controller = typeof AbortController === 'function' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs || rerankTimeoutMs()) : null;
+  try {
+    const response = await transport.request(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      ...(controller ? { signal: controller.signal } : {}),
+    });
+    if (!response || response.ok !== true || typeof response.json !== 'function') return null;
+    const payload = await response.json();
+    const content = payload && payload.choices && payload.choices[0] && payload.choices[0].message && payload.choices[0].message.content;
+    return parseRerankOrder(content, list.map(candidate => candidate.id));
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+module.exports = {
+  DEFAULT_RERANK_MODEL,
+  DEFAULT_RERANK_POOL,
+  DEFAULT_RERANK_RETURN,
+  DEFAULT_RERANK_TIMEOUT_MS,
+  isRerankEnabled,
+  rerankConfig,
+  rerankTimeoutMs,
+  resolveRerankProvider,
+  parseRerankOrder,
+  applyRerankOrder,
+  rerankCandidates,
+};

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

@@ -154,8 +154,9 @@ async function processChannel(options) {
 }
 
 function buildSemanticRecord(record, vector, options) {
+  const searchText = buildSemanticRecordText(record.channel, record.canonicalObject);
   const contentHash = crypto.createHash('sha256')
-    .update(buildSemanticRecordText(record.channel, record.canonicalObject))
+    .update(searchText)
     .digest('hex');
   return Object.freeze({
     canonicalIdentity: record.canonicalIdentity,
@@ -167,6 +168,7 @@ function buildSemanticRecord(record, vector, options) {
     model: options.qualification.model,
     modelVersion: options.qualification.version,
     dimensions: options.qualification.dimensions,
+    searchText,
     vector: Object.freeze([...vector]),
   });
 }

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

@@ -30,6 +30,7 @@ function createProductionSemanticNeo4jAdapter(dependencies = {}) {
       }
       return withSession(driver, dependencies.configuration, async session => {
         await ensureVectorIndexes(session);
+        await ensureFulltextIndexes(session);
         const results = [];
         for (const [channel, definition] of Object.entries(CHANNEL_INDEXES)) {
           const channelRecords = records.filter(record => record.channel === channel).map(cloneRecord);
@@ -121,6 +122,19 @@ async function ensureVectorIndexes(session) {
   }
 }
 
+async function ensureFulltextIndexes(session) {
+  for (const definition of Object.values(CHANNEL_INDEXES)) {
+    await executeWrite(
+      session,
+      [
+        `CREATE FULLTEXT INDEX ${definition.indexName}_fulltext IF NOT EXISTS`,
+        `FOR (semantic:${definition.label}) ON EACH [semantic.searchText]`,
+      ].join('\n'),
+      {},
+    );
+  }
+}
+
 async function withSession(driver, configuration, action) {
   const database = configuration && configuration.neo4jDatabase;
   const session = driver.session(database === undefined ? undefined : { database });

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.19.1",
+  "version": "0.20.1",
   "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",