archgraph-argo 0.26.2 → 0.27.0

package/README.md

@@ -8,10 +8,14 @@ ArchGraph builds a **unified language** that puts harness design and target prod
 **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.
+a single read/write MCP interface. Memory is tiered — a compact working memory restored at session
+start, a long-term memory recalled on demand — and writes are deduplicated, so the graph stays clean
+and semantic recall stays precise. Reusable subgraphs can also be shared across projects through a
+federated registry, and any read tool can take an optional <code>projectId</code> to query
+**another project's graph** through the federation center — authorized, read-only, and by
+reference (denied by default). See the [home page](https://archgraph.org/) for the full capability set.
 
-![alt text](docs/diagrams/image.png)
+![ArchGraph core model — harness design and product design in one graph](docs/diagrams/core-model.svg)
 
 ## Architecture
 
@@ -21,7 +25,7 @@ engineering:
 
 ![Global architecture — Layered Viewpoint](docs/diagrams/global-architecture.svg)
 
-Editable source: [`docs/diagrams/global-architecture.excalidraw`](docs/diagrams/global-architecture.excalidraw)
+Editable source: [`scripts/gen-diagrams.js`](scripts/gen-diagrams.js)
 
 ## Supported Harnesses
 
@@ -93,6 +97,11 @@ subgraphs** across projects, and follow the governance & contribution guides:
 - **graph-wiki repository** — https://github.com/derekhu0002/graph-wiki (graph-asset home: contribute
   a subgraph from your project, or pull one back to reuse)
 
+Sharing is **federated**: each project keeps its own graph sovereign and publishes subgraphs to a
+registry, where other members register, discover, and read opened content **by reference** —
+register, discover, authorize, read. Access is **denied by default**, and nothing is copied or merged.
+Browse the [federation members](https://argo.derekworkspacev5.com/archgraph/federation).
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/argo/.env.example

@@ -1,163 +1,170 @@
-# =============================================================================
-# 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 -------
-# Provider profile: "approved" (default) = the human-approved cloud profile
-# below; "openai-compatible" = a self-hosted OpenAI-compatible endpoint
-# (intranet/offline) whose URL/model/label/dimension are read verbatim.
-ARGO_EMBEDDING_PROFILE=
-# 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 and the vector index
-# (current profiles: 1536).
-ARGO_EMBEDDING_DIMENSIONS=
-# Query-side instruction prefix for instruction-tuned embedding models (e.g.
-# gte-Qwen2: "Instruct: <task>\nQuery: "). Empty = no prefix. Documents are
-# never prefixed; only the query side is.
-ARGO_EMBEDDING_QUERY_INSTRUCTION=
-# Optional embedding API key. SECRET: overrides QWEN_KEY as the Bearer token for
-# the embeddings call when set (useful for a self-hosted endpoint). Leave empty
-# to use QWEN_KEY.
-ARGO_EMBEDDING_API_KEY=
-
-# --- 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 3500.
-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=
-# Disable the rerank model's hidden "thinking"/reasoning (reasoning models spend
-# 6-12s per call for a listwise ranking with no accuracy gain). Default 1 =
-# disabled; set 0 to send nothing. Applies to every provider so a model swap
-# keeps the fast path. If a provider rejects the fragment it is retried without.
-ARGO_RERANK_DISABLE_THINKING=
-# Exact JSON body fragment merged into the rerank request to disable thinking
-# (default {"thinking":{"type":"disabled"}}). Override for another model/provider
-# that uses a different field, e.g. {"reasoning_effort":"none"} or
-# {"enable_thinking":false}.
-ARGO_RERANK_THINKING_PARAM=
-
-# --- 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=
+# =============================================================================
+# 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 (never commit it);
+# 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 -------
+# Provider profile: "approved" (default) = the human-approved cloud profile
+# below; "openai-compatible" = a self-hosted OpenAI-compatible endpoint
+# (intranet/offline) whose URL/model/label/dimension are read verbatim.
+ARGO_EMBEDDING_PROFILE=
+# 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 and the vector index
+# (current profiles: 1536).
+ARGO_EMBEDDING_DIMENSIONS=
+# Query-side instruction prefix for instruction-tuned embedding models (e.g.
+# gte-Qwen2: "Instruct: <task>\nQuery: "). Empty = no prefix. Documents are
+# never prefixed; only the query side is.
+ARGO_EMBEDDING_QUERY_INSTRUCTION=
+# Optional embedding API key. SECRET: overrides QWEN_KEY as the Bearer token for
+# the embeddings call when set (useful for a self-hosted endpoint). Leave empty
+# to use QWEN_KEY.
+ARGO_EMBEDDING_API_KEY=
+
+# --- 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
+# .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 3500.
+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=
+# Disable the rerank model's hidden "thinking"/reasoning (reasoning models spend
+# 6-12s per call for a listwise ranking with no accuracy gain). Default 1 =
+# disabled; set 0 to send nothing. Applies to every provider so a model swap
+# keeps the fast path. If a provider rejects the fragment it is retried without.
+ARGO_RERANK_DISABLE_THINKING=
+# Exact JSON body fragment merged into the rerank request to disable thinking
+# (default {"thinking":{"type":"disabled"}}). Override for another model/provider
+# that uses a different field, e.g. {"reasoning_effort":"none"} or
+# {"enable_thinking":false}.
+ARGO_RERANK_THINKING_PARAM=
+
+# --- 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=
+# Explicit schema-bundle directory (highest precedence): overrides both the
+# repository's own <workspace>/.argo/schema bundle and the default ArgoBument
+# bundle. Must contain SystemArchitecture.schema.json.
+# ARGO_SCHEMA_DIR=
+# Actor element type the wakeup gate looks up when a workspace schema renames
+# it. Default: Business Actor.
+# ARGO_ACTOR_ELEMENT_TYPE=
+# 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/plugins/argo-wakeup.js

@@ -1,27 +1,29 @@
-// Argo wakeup gate plugin for opencode.
-//
-// Injects an unconditional "wakeup gate" as the FIRST system instruction of
-// every session, so the agent identifies its Business Actor and restores its
-// long-term memory before responding to anything (including greetings and
-// casual questions). The rule also lives in argo/rules/archgraph.instructions.md,
-// but that file is long and can be skimmed; this hook guarantees a short,
-// high-salience gate sits at the top of the system prompt on session start.
-
-const WAKEUP_GATE = [
-  "WAKEUP GATE (unconditional; applies to the very first message of every session, including greetings, casual chat, and questions; never skip or defer).",
-  "1. Your very FIRST tool call must be an ARGO MCP query listing all Business Actors (getSystemArchitecture, purpose \"audit\", subject \"Business Actor\") to identify which Business Actor you are.",
-  "2. Restore that Actor's long-term memory (the SUBVIEW hierarchy mounted under it) before responding.",
-  "3. If the ARGO MCP is unavailable or errors, say so explicitly first. Only after this gate may you respond or act.",
-].join("\n");
-
-export default async function argoWakeupPlugin() {
-  return {
-    "experimental.chat.system.transform": async (_input, output) => {
-      const system = Array.isArray(output.system) ? output.system : [];
-      if (system.some((entry) => entry.includes("WAKEUP GATE"))) {
-        return;
-      }
-      output.system = [WAKEUP_GATE, ...system];
-    },
-  };
-}
+// Argo wakeup gate plugin for opencode.
+//
+// Injects an unconditional "wakeup gate" as the FIRST system instruction of
+// every session, so the agent identifies its Business Actor and restores its
+// long-term memory before responding to anything (including greetings and
+// casual questions). The rule also lives in argo/rules/archgraph.instructions.md,
+// but that file is long and can be skimmed; this hook guarantees a short,
+// high-salience gate sits at the top of the system prompt on session start.
+
+const ACTOR_ELEMENT_TYPE = process.env.ARGO_ACTOR_ELEMENT_TYPE || 'Business Actor';
+
+const WAKEUP_GATE = [
+  "WAKEUP GATE (unconditional; applies to the very first message of every session, including greetings, casual chat, and questions; never skip or defer).",
+  `1. Your very FIRST tool call must be an ARGO MCP query listing all Actor elements (getSystemArchitecture, purpose "audit", subject "${ACTOR_ELEMENT_TYPE}"). Resolve the workspace's own schema first: queryNeo4jGraph with {schema:true} reports actorElementType (a .argo/schema bundle may rename it; null means no Actor concept, then skip), bundleValidation, and the type enums.`,
+  "2. Restore that Actor's long-term memory (the SUBVIEW hierarchy mounted under it) before responding.",
+  "3. If the ARGO MCP is unavailable or errors, say so explicitly first. Only after this gate may you respond or act.",
+].join("\n");
+
+export default async function argoWakeupPlugin() {
+  return {
+    "experimental.chat.system.transform": async (_input, output) => {
+      const system = Array.isArray(output.system) ? output.system : [];
+      if (system.some((entry) => entry.includes("WAKEUP GATE"))) {
+        return;
+      }
+      output.system = [WAKEUP_GATE, ...system];
+    },
+  };
+}