archgraph-argo 0.26.2 → 0.28.0

package/argo/scripts/workspace-write-guard.js

@@ -0,0 +1,144 @@
+'use strict';
+
+// Cross-project workspace WRITE guard.
+//
+// The per-call `workspaceRoot` override is a wanted capability: it lets a caller
+// READ another local project's intent graph. It must NOT let the caller WRITE an
+// arbitrary other project's graph. This guard bounds writes to the server's HOME
+// workspace PLUS a host-designated session workspace that only a trusted broker
+// may name.
+//
+// Two channels, deliberately distinct:
+//   - `workspaceRoot`      : the generic per-call override. A model may set it.
+//                            Reads honor it; a WRITE to a foreign path is denied.
+//   - `sessionWorkspaceRoot`: the host broker's (e.g. the DSH workspace bridge)
+//                            designation of the current session's workspace. It
+//                            is trusted for writes ONLY when the process was
+//                            launched with ARGO_WORKSPACE_ROOT_TRUSTED=1 (set by
+//                            the broker at spawn, which the model cannot forge).
+//                            A model-supplied sessionWorkspaceRoot on a plain
+//                            (unflagged) server is ignored.
+//
+// So: cross-project reading keeps working everywhere; cross-project WRITING is
+// blocked unless the trusted host broker explicitly designates that workspace.
+// The whole guard is OFF (all-or-nothing) with ARGO_WORKSPACE_WRITE_GUARD=0.
+
+const path = require('node:path');
+
+// Host-designated trusted session workspace (broker channel, not advertised to
+// the model).
+const TRUSTED_SESSION_FIELD = 'sessionWorkspaceRoot';
+// Spawn-time flag the broker sets to assert it controls TRUSTED_SESSION_FIELD.
+const TRUSTED_ENV = 'ARGO_WORKSPACE_ROOT_TRUSTED';
+
+// Tools whose invocation mutates the target workspace. `preview*` and the read
+// tools are intentionally absent.
+const WRITE_TOOLS = Object.freeze(new Set([
+  'initializeWorkspace',
+  'runArchitectureTests',
+  'applySystemArchitectureMutation',
+  'addArchitectureElement',
+  'updateArchitectureElement',
+  'removeArchitectureElement',
+  'addArchitectureRelationship',
+  'updateArchitectureRelationship',
+  'removeArchitectureRelationship',
+  'addArchitectureView',
+  'updateArchitectureView',
+  'removeArchitectureView',
+]));
+
+function guardDisabled(env = process.env) {
+  const value = env && env.ARGO_WORKSPACE_WRITE_GUARD;
+  return value !== undefined && String(value).trim() === '0';
+}
+
+// A focused mutation with dryRun:true validates only and never writes, so it is
+// not a write for this guard. initializeWorkspace has no dry-run.
+function isWriteTool(name, args = {}) {
+  if (!WRITE_TOOLS.has(name)) {
+    return false;
+  }
+  if (name !== 'initializeWorkspace' && args && args.dryRun === true) {
+    return false;
+  }
+  return true;
+}
+
+function sameWorkspace(a, b) {
+  const na = path.resolve(String(a));
+  const nb = path.resolve(String(b));
+  return process.platform === 'win32' ? na.toLowerCase() === nb.toLowerCase() : na === nb;
+}
+
+// The host-broker-designated session workspace, honored only behind the
+// spawn-time trust flag. Returns an absolute path or null.
+function trustedSessionWorkspace(args, env = process.env) {
+  if (!env || String(env[TRUSTED_ENV]).trim() !== '1') {
+    return null;
+  }
+  const raw = args && typeof args[TRUSTED_SESSION_FIELD] === 'string'
+    ? args[TRUSTED_SESSION_FIELD].trim()
+    : '';
+  return raw !== '' ? path.resolve(raw) : null;
+}
+
+/**
+ * Authorize one write against the home workspace and the trusted session workspace.
+ *
+ * @param {object} options
+ * @param {string} options.tool
+ * @param {object} [options.args]
+ * @param {string} options.homeRoot - the server's own workspace root.
+ * @param {object} [options.env] - injectable environment (tests).
+ * @returns {{allowed:boolean, category?:string, message?:string, tool:string, homeWorkspaceRoot:string, requestedWorkspaceRoot:string, trustedSessionWorkspaceRoot:(string|null)}}
+ */
+function authorizeWorkspaceWrite({ tool, args = {}, homeRoot, env = process.env }) {
+  const requestedRaw = args && typeof args.workspaceRoot === 'string' ? args.workspaceRoot.trim() : '';
+  const requested = requestedRaw !== '' ? path.resolve(requestedRaw) : path.resolve(homeRoot);
+  const trusted = trustedSessionWorkspace(args, env);
+  const base = {
+    tool,
+    homeWorkspaceRoot: path.resolve(homeRoot),
+    requestedWorkspaceRoot: requested,
+    trustedSessionWorkspaceRoot: trusted,
+  };
+  if (guardDisabled(env) || sameWorkspace(requested, homeRoot)) {
+    return { ...base, allowed: true };
+  }
+  if (trusted && sameWorkspace(requested, trusted)) {
+    return { ...base, allowed: true };
+  }
+  return {
+    ...base,
+    allowed: false,
+    category: 'WORKSPACE_WRITE_DENIED',
+    message:
+      `Write tool '${tool}' targets workspace '${requested}' but this server is only allowed to write its home workspace ` +
+      `'${base.homeWorkspaceRoot}' (plus a trusted host-designated session workspace). Cross-project access is read-only: ` +
+      'pass workspaceRoot only to read tools (getSystemArchitecture, getIntentElementContext, getArchitectureViewContext, ' +
+      'queryNeo4jGraph, memory_search).',
+  };
+}
+
+// Remove the broker-only field so it never reaches tool schema validation.
+function stripTrustedSessionField(args) {
+  if (!args || !Object.prototype.hasOwnProperty.call(args, TRUSTED_SESSION_FIELD)) {
+    return args;
+  }
+  const next = { ...args };
+  delete next[TRUSTED_SESSION_FIELD];
+  return next;
+}
+
+module.exports = {
+  WRITE_TOOLS,
+  TRUSTED_SESSION_FIELD,
+  TRUSTED_ENV,
+  guardDisabled,
+  isWriteTool,
+  sameWorkspace,
+  trustedSessionWorkspace,
+  authorizeWorkspaceWrite,
+  stripTrustedSessionField,
+};

package/argo/skills/argo-init/SKILL.md

@@ -17,10 +17,12 @@ disable-model-invocation: true
 ## Rules
 
 - **MUST** 调用 ARGO MCP 工具 `initializeWorkspace`（传当前工作区根）执行确定性初始化，并以其返回报告为最终判断依据。
+- **MUST** 报告当前 schema：`initializeWorkspace` 返回的 `schema`（或 harness 的 `schemaBundle`）中的 `kind`（default=内置 ArchiMate 3.2 / workspace=仓内自定义 / override）、`language`（名称）、`actorElementType`、`dir`、`guide`；输出形如 `schema: default / ArchiMate 3.2`。
 - **MUST** 报告 `mcp` / `systemArchitecture` / `neo4j` / `qeaFullProjection` / `semanticLifecycle` / `subdiagramViews` 与整体 `status`。
 - **MUST** 核验并报告：① `.qea` 投影是否成功（`qeaFullProjection.status`），且投影目标 `qeaFullProjection.qea` 是否为**本仓库自己的 .qea 文件**（解析自 `ARGO_EA_QEA` 或仓库根唯一 `*.qea`）；目标不是本仓库文件或投影失败 → 报告为告警/失败，不得视为 init 成功。
 - **MUST** 核验并报告：Neo4j 投影目标数据库名（`neo4j.database`）是否**与本仓库名一致**（仓库 basename == 数据库名）；不一致 → 报告为告警/失败。
-- **MUST NOT** 读取、打印或复述 `.env` 中的 secret 值；排查时只允许报告 key 是否存在、ACL 主体。
+- **MUST NOT** 因 schema 是自定义的而跳过 `.qea` 投影：投影对任何 schema 都执行；只有确实没有 `.qea` 目标时才允许 `noop`。
+- **MUST NOT** 读取、打印或复述 `.env` 中的 secret 值；排查时只允许报告 key 是否存在。
 - **MUST NOT** 通过 shell 手工执行 WORKSPACE 外的初始化脚本或一组无关命令来替代 `initializeWorkspace`（除非报告显示底层脚本自身失败需要排查）。
 
 ## Workflow
@@ -47,18 +49,13 @@ disable-model-invocation: true
 
 ### 3. Handle Secret File Blockers（仅当报告含 secret 相关失败）
 
-`semanticLifecycle` 或 `systemArchitecture` 失败可能源于 `.env` 安全预检。诊断（不打印 secret 值）：
+`semanticLifecycle` 或 `systemArchitecture` 失败可能源于 `.env` 预检。诊断（不打印 secret 值）：
 
-```powershell
-icacls "$env:USERPROFILE\.argo\.env"
-```
+处理规则（env 文件不做 OS ACL / 权限加固；只保证不被提交）：
 
-处理规则：
-
-- `SECRET_FILE_ACL_UNSAFE`：收紧 Windows ACL，只保留当前用户、Administrators、SYSTEM。
 - `SECRET_FILE_REPARSE_PROHIBITED`：将 `.env` 替换为普通文件（去掉符号链接/重解析点）。
 - `SECRET_FILE_PATH_PROHIBITED`：修正 `ARGO_ENV_FILE` 与安装根 `.env` 不一致的路径。
-- git 跟踪/忽略类错误（`SECRET_FILE_TRACKED` / `SECRET_FILE_NOT_IGNORED`）只在 `.env` 位于 git 仓库内时出现；全局 `.env` 位于仓库外时天然不适用。
+- git 跟踪/忽略类错误（`SECRET_FILE_TRACKED` / `SECRET_FILE_NOT_IGNORED`）：把 `.env` 加入 `.gitignore` 并 `git rm --cached`；全局 `.env` 位于仓库外时天然不适用。
 
 修复后重跑 `initializeWorkspace`。
 
@@ -72,6 +69,7 @@ icacls "$env:USERPROFILE\.argo\.env"
 
 ### 1. Environment Status
 - overall status: ok / failed
+- **解析到的 schema：kind（default/workspace/override）+ language（名称）+ actorElementType + dir/guide**（默认 ArchiMate 3.2 还是仓内自定义 schema）
 - whether mcp health passed
 - whether neo4j health passed
 - whether .qea full projection passed

package/argo/skills/ea-human-reconcile/SKILL.md

@@ -1,39 +1,40 @@
----
-name: ea-human-reconcile
-description: "把人类从 EA 提取的 draft 提议（results/human-draft.md，内嵌 JSON 提议集）交给 Agent 后，Agent 结合当前全局（canonical 意图图 design/KG/SystemArchitecture.json + Neo4j 语义检索）逐条/整体分析并给出建议，最终由人类裁决是否写入。它是『人类 EA 草稿 → 语义 diff 提取 → 人类裁决写回』的最后一步：Agent 只做分析+建议，绝不自作主张 apply。Use when the user hands over an EA human-draft proposal set (human-draft.md) and wants the agent to analyze it against the whole architecture and propose, leaving the final decision to the human. Keywords: EA human draft, reconcile, EA 人类草稿裁决, draft review, 语义diff建议, ARGO preview/apply, 人类裁决."
-argument-hint: human-draft
-disable-model-invocation: true
----
-
-# EA HUMAN DRAFT RECONCILE（EA 人类草稿 → Agent 分析建议 → 人类裁决）
-
-Agent 的职责：结合全局分析 draft 中的每条提议、给出建议与理由、识别风险，把结论呈现给人类，由人类裁决。Agent 不自动执行写入。
-
-## 前置
-
-- [ ] 存在 `results/human-draft.md`（人类从 EA 提取的草稿提议集）。
-- [ ] 工作区有 `design/KG/SystemArchitecture.json`（canonical 意图图）——分析全局的依据。
-- [ ] ARGO MCP 可用。关键查询手段：
-  - 语义/上下文：`getSystemArchitecture`（带 query.purpose + query.intent）、`getIntentElementContext`（看单个元素/关系/视图的依赖与受影响对象）。
-  - 结构/类型：`queryNeo4jGraph`（只读 Cypher，如 `MATCH (e:Element {graphKey: $graphKey, type:'Business Actor'}) ...`；先 `{schema:true}` 查投影 schema）。
-  - 校验：`validateSystemArchitecture`；写图：`previewSystemArchitectureMutation` / `applySystemArchitectureMutation`。
-
-## 原则
-
-- **人类裁决**：Agent 只分析、给建议、识别风险；**MUST NOT 未经人类裁决就 `applySystemArchitectureMutation`（或任何写图）**。人类拍板（采纳/拒绝/修改）后才写。
-- **全局优先**：不只对着 draft 字段，要用查询手段读 canonical 中相关对象及其依赖（被谁引用、级联影响谁、子视图是否悬空、命名/类型是否与全局一致、是否与既有元素重复冲突），再下判断。
-- **删除/破坏性提议单独把关**：对 `removeElement` / `removeRelationship` / `removeView`，必须指出 canonical 里谁引用它、删除会级联影响谁，并给出「保留 / 改挂 / 确认删除」的建议，交由人类确认。
-- **新增/更新提议**：核对 type / name / description / attributes 是否与全局命名与类型一致、是否与既有元素/关系重复冲突、应挂在哪个 parent / 视图下。
-- **视图提议**：核对成员是否落在正确层级（parent_element_id 是否合理）、删视图会否使相关 subdiagram_views 悬空。
-- **只读取、不泄露**：MUST NOT 读取/复述 `.env` 里的 secret 或推断敏感配置值。
-
-## 目标
-
-读 draft → 结合全局逐条分析 → 给出「逐条建议 + 整体结论 + 待人类裁决项」。具体产出：
-
-1. **操作统计**：add/update/remove × element/relationship/view。
-2. **逐条建议**：每条含 `提议`（op + id/名称）、`分析`（全局依赖/冲突/层级）、`建议`（采纳/拒绝/修改后采纳，附理由）、`风险`（若有）。
-3. **整体结论**：这批草稿的整体风险等级、必人工确认的高风险项。
-4. **待裁决**：明确列出需人类拍板的条目，并询问哪些采纳、哪些修改、哪些拒绝。
-
-**等待人类答复之后**才进入写回；若人类同意，才经 `previewSystemArchitectureMutation` →（确认后）`applySystemArchitectureMutation`；拒绝/搁置的不写。
+---
+name: ea-human-reconcile
+description: "把人类从 EA 提取的 draft 提议（results/human-draft.md，内嵌 JSON 提议集）交给 Agent 后，Agent 结合当前全局（canonical 意图图 design/KG/SystemArchitecture.json + Neo4j 语义检索）逐条/整体分析并给出建议，最终由人类裁决是否写入。它是『人类 EA 草稿 → 语义 diff 提取 → 人类裁决写回』的最后一步：Agent 只做分析+建议，绝不自作主张 apply。Use when the user hands over an EA human-draft proposal set (human-draft.md) and wants the agent to analyze it against the whole architecture and propose, leaving the final decision to the human. Keywords: EA human draft, reconcile, EA 人类草稿裁决, draft review, 语义diff建议, ARGO preview/apply, 人类裁决."
+argument-hint: human-draft
+disable-model-invocation: true
+---
+
+# EA HUMAN DRAFT RECONCILE（EA 人类草稿 → Agent 分析建议 → 人类裁决）
+
+Agent 的职责：结合全局分析 draft 中的每条提议、给出建议与理由、识别风险，把结论呈现给人类，由人类裁决。Agent 不自动执行写入。
+
+## 前置
+
+- [ ] 存在 `results/human-draft.md`（人类从 EA 提取的草稿提议集）。
+- [ ] 工作区有 `design/KG/SystemArchitecture.json`（canonical 意图图）——分析全局的依据。
+- [ ] ARGO MCP 可用。关键查询手段：
+  - 语义/上下文：`getSystemArchitecture`（带 query.purpose + query.intent）、`getIntentElementContext`（看单个元素/关系/视图的依赖与受影响对象）。
+  - 结构/类型：`queryNeo4jGraph`（只读 Cypher，如 `MATCH (e:Element {graphKey: $graphKey, type:'<element type>'}) ...`）。先 `{schema:true}` 取当前工作区的语言与类型枚举，类型名一律取自该结果，勿硬编码。
+  - 校验：`validateSystemArchitecture`；写图：`previewSystemArchitectureMutation` / `applySystemArchitectureMutation`。
+
+## 原则
+
+- **人类裁决**：Agent 只分析、给建议、识别风险；**MUST NOT 未经人类裁决就 `applySystemArchitectureMutation`（或任何写图）**。人类拍板（采纳/拒绝/修改）后才写。
+- **全局优先**：不只对着 draft 字段，要用查询手段读 canonical 中相关对象及其依赖（被谁引用、级联影响谁、子视图是否悬空、命名/类型是否与全局一致、是否与既有元素重复冲突），再下判断。
+- **删除/破坏性提议单独把关**：对 `removeElement` / `removeRelationship` / `removeView`，必须指出 canonical 里谁引用它、删除会级联影响谁，并给出「保留 / 改挂 / 确认删除」的建议，交由人类确认。
+- **新增/更新提议**：核对 type / name / description / attributes 是否与全局命名与类型一致、是否与既有元素/关系重复冲突、应挂在哪个 parent / 视图下。
+- **视图提议**：核对成员是否落在正确层级（parent_element_id 是否合理）、删视图会否使相关 subdiagram_views 悬空。
+- **类型以工作区 schema 为准**：分析前先 `queryNeo4jGraph {schema:true}` 取 `schemaLanguage` 与元素/关系类型枚举；按该枚举判定类型，**勿硬编码 ArchiMate 类型**。
+- **只读取、不泄露**：MUST NOT 读取/复述 `.env` 里的 secret 或推断敏感配置值。
+
+## 目标
+
+读 draft → 结合全局逐条分析 → 给出「逐条建议 + 整体结论 + 待人类裁决项」。具体产出：
+
+1. **操作统计**：add/update/remove × element/relationship/view。
+2. **逐条建议**：每条含 `提议`（op + id/名称）、`分析`（全局依赖/冲突/层级）、`建议`（采纳/拒绝/修改后采纳，附理由）、`风险`（若有）。
+3. **整体结论**：这批草稿的整体风险等级、必人工确认的高风险项。
+4. **待裁决**：明确列出需人类拍板的条目，并询问哪些采纳、哪些修改、哪些拒绝。
+
+**等待人类答复之后**才进入写回；若人类同意，才经 `previewSystemArchitectureMutation` →（确认后）`applySystemArchitectureMutation`；拒绝/搁置的不写。

package/cordis.patch.yml

@@ -1,6 +1,15 @@
-# ArchGraph ARGO bundle patch：随 bundle 安装，按包名引用包内插件（非 file://）。
-- insert:
-    - id: argo-workspace
-      name: archgraph-argo/dsh-argo-workspace
-    - id: argo-wakeup
-      name: archgraph-argo/dsh-argo-wakeup
+# ArchGraph ARGO bundle patch：随 bundle 安装，按包名引用包内插件（非 file://）。
+- insert:
+    - id: argo-workspace
+      name: archgraph-argo/dsh-argo-workspace
+      config:
+        servers:
+          - id: argo
+            injectWorkspaceRoot: true
+          - id: graph-mcp
+            serverPath: '../argo/mcp-bridges/graph-mcp-stdio.js'
+            env:
+              GRAPH_MCP_URL: https://argo.derekworkspacev5.com/mcp
+            injectWorkspaceRoot: false
+    - id: argo-wakeup
+      name: archgraph-argo/dsh-argo-wakeup

package/dsh-argo-wakeup/index.js

@@ -1,17 +1,17 @@
-// dsh-argo-wakeup - generated by install-argo.ps1 from
-// argo/rules/archgraph.instructions.md (single source of truth: the rule file;
-// this file is a deployment artifact, do not edit by hand).
-// DeepSeek Harness equivalent of the OpenCode hook argo/plugins/argo-wakeup.js:
-// registers the unconditional wakeup gate as the first system-prompt section
-// after the harness identity, so every session identifies its Business Actor
-// through the argo MCP server before responding.
-export const name = 'dsh-argo-wakeup'
-export const inject = ['systemPrompt']
-const WAKEUP_GATE = "STEP 0 — UNCONDITIONAL STARTUP GATE. This applies to the very first message of every session, including greetings, casual chat, and questions; it may never be skipped, deferred, or treated as optional.\r\n1. Your very FIRST tool call in the session MUST be an ARGO MCP query that lists all `Business Actor`s (getSystemArchitecture with purpose \"audit\" and subject \"Business Actor\"). Identify which `Business Actor` you are. If you are not sure, consult your human partner to confirm your role before doing anything else.\r\n2. Restore your long-term memory: the SUBVIEW hierarchy mounted under that `Business Actor` element — the Views whose `parent_element_id` points to this Actor, plus the elements, relationships, and further nested sub-views inside them (NOT the View that merely includes the Actor in its `included_elements`) — and load it into session memory.\r\n3. If the `agent` attribute of the confirmed Actor differs from your current Agent type, switch to that Agent type, or delegate to an Agent of that type per `\u003cCoperationGuideline\u003e` item 2.\r\n4. If the ARGO MCP is unavailable or errors, state that explicitly to the user before doing anything else. Only after completing this gate may you respond to the user or take any other action."
-export function apply(ctx) {
-  ctx.effect(() => ctx.systemPrompt.section({
-    name: 'argo:wakeup',
-    order: -90,
-    text: WAKEUP_GATE,
-  }), 'argo:wakeup.section()')
-}
+// dsh-argo-wakeup - generated by scripts/gen-dsh-plugins.js from
+// argo/rules/archgraph.instructions.md (single source of truth: the rule file;
+// this file is a deployment artifact, do not edit by hand).
+// DeepSeek Harness equivalent of the OpenCode hook argo/plugins/argo-wakeup.js:
+// registers the unconditional wakeup gate as the first system-prompt section
+// after the harness identity, so every session identifies its Business Actor
+// through the argo MCP server before responding.
+export const name = 'dsh-argo-wakeup'
+export const inject = ['systemPrompt']
+const WAKEUP_GATE = "STEP 0 — UNCONDITIONAL STARTUP GATE. Applies to the very first message of every session, greetings and chat included; never skip, defer, or treat it as optional.\n1. Your first tool call MUST resolve the workspace schema and list its Actors: `queryNeo4jGraph` with `{schema:true}` → read `actorElementType` (`null` = no Actor concept, skip Actor identification), then query that element type. Confirm which Actor you are; if unsure, ask your human partner before anything else.\n2. Restore memory: load ONLY the T1 working-memory digest — your T1 summary, the most recent/active memory cards, and any session hooks (unfinished items from the last session). Do NOT bulk-load the T2 long-term memory or T3 archive; recall them on demand via `memory_search`, then read full content with `getIntentElementContext`. T2 is a recall target, not as a bulk context load.\n3. If the Actor's `agent` attribute differs from your type, switch to it or delegate per `<CoperationGuideline>` item 2.\n4. If the ARGO MCP is unavailable or errors, say so before doing anything else."
+export function apply(ctx) {
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'argo:wakeup',
+    order: -90,
+    text: WAKEUP_GATE,
+  }), 'argo:wakeup.section()')
+}