archgraph-argo 0.10.34 → 0.10.36

package/argo/scripts/ARCHITECTURE.md

@@ -15,13 +15,13 @@ This local contract refines `OVERALL_ARCHITECTURE.md`.
 
 `getSystemArchitecture` accepts:
 
-- no `query`: return exactly the legacy public envelope `{ status, graphPath, document }` with the complete canonical `document` and no query-mode metadata;
-- `query.purpose`: one of `intent-decision`, `implementation-design`, `coding-repair`, `audit`, or `graph-tidy`;
+- `query`: REQUIRED. An omitted-query call is rejected with `QUERY_REQUIRED`; the legacy full-graph snapshot envelope is no longer exposed to agents.
+- `query.purpose`: one of `general` or `audit` (`intent-decision`, `implementation-design`, `coding-repair`, and `graph-tidy` were removed from the agent-facing purpose enum; the runtime engine retains all of them as internal closure categories reachable only via the private journey/CLI, never the public tool — `general` binds to the internal `implementation-design` closure category);
 - `query.intent`: required non-empty natural-language intent for an explicit query;
 - `query.subject`: required non-empty audit subject when `purpose` is `audit`;
 - optional deterministic anchors may be added without changing no-argument behavior.
 
-All five purpose values remain legal contract inputs. `intent-decision`, `implementation-design`, `coding-repair`, and valid `audit` requests invoke the semantic retrieval boundary; `graph-tidy` never invokes it and reports `mode: "full-snapshot"` plus `semanticRetrieval: "bypassed"`.
+Both purpose values remain legal agent-facing contract inputs. `general` (generic semantic/memory retrieval, loose threshold) and valid `audit` requests (strict proof-closure, subject required) invoke the semantic retrieval boundary. No agent-facing path reports `mode: "full-snapshot"` or `semanticRetrieval: "bypassed"`; the output contract mode is `semantic-query` or `error` only.
 
 For W6, semantic query results must remain traceable to the canonical graph version used by the same no-argument legacy read. Endpoint, View, and provenance completion are delegated inward to the Graph RAG boundary, but the query service must surface their evidence without silently dropping or rewriting `canonicalVersion`, policy, index, or alignment fields.
 
@@ -29,6 +29,7 @@ For BP-MCP-SEM-PAYLOAD and BP-MCP-SEM-ELEMENT, semantic result mapping is object
 
 Validation occurs before retrieval and returns these stable categories:
 
+- missing `query`: `QUERY_REQUIRED`;
 - missing purpose: `QUERY_PURPOSE_REQUIRED`;
 - purpose outside the legal enum: `QUERY_PURPOSE_INVALID`;
 - missing or blank intent: `QUERY_INTENT_REQUIRED`;

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

@@ -8,9 +8,6 @@ const systemArchitectureMcp = require('./systemarchitecture-mcp-server.js');
 const {
   semanticOperatorErrorResult,
 } = require('./graph-rag/semanticOperatorError.js');
-const {
-  runCanonicalSemanticInit,
-} = require('./graph-rag/semanticOperatorJourney.js');
 const {
   loadRepositoryArgoEnvironment,
 } = require('./repositoryArgoEnvironment.js');
@@ -45,8 +42,6 @@ const WINDOWS_RESERVED_NAMES = new Set([
 
 const VALIDATOR_TOOL_NAMES = new Set([
   'validateSystemArchitecture',
-  'validateStageHandoff',
-  'validateTraceProposal',
   'runArchitectureTests',
 ]);
 const SYSTEM_ARCHITECTURE_TOOL_NAMES = new Set([
@@ -64,7 +59,6 @@ const SYSTEM_ARCHITECTURE_TOOL_NAMES = new Set([
   'addArchitectureView',
   'updateArchitectureView',
   'removeArchitectureView',
-  'generateArchitectureDiffPlantuml',
   'queryNeo4jGraph',
   'memory_search',
 ]);
@@ -79,35 +73,6 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
-  {
-    name: 'validateStageHandoff',
-    description: 'Validate Argo stage handoff JSON. Use stage intent-to-implementation or implementation-to-coding, or omit to validate all supported stages.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        stage: {
-          type: 'string',
-          enum: ['intent-to-implementation', 'implementation-to-coding'],
-          description: 'Optional handoff stage to validate.',
-        },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'validateTraceProposal',
-    description: 'Validate ImplementationToIntentTraceProposal JSON against .argo/schema/ImplementationToIntentTraceProposal.schema.json and repository path references.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        proposalPath: {
-          type: 'string',
-          description: 'Optional proposal path relative to workspace root. Default: design/KG/ImplementationToIntentTraceProposal.json',
-        },
-      },
-      additionalProperties: false,
-    },
-  },
   {
     name: 'runArchitectureTests',
     description: 'Execute explicit architecture testcases from the intent graph and refresh design/KG/test-failure-records.json. This MCP call can exceed client timeouts; if it times out, run the same test runner directly with: node .argo/scripts/runArchitectureTests.js',
@@ -122,39 +87,22 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
-  {
-    name: 'generateArchitectureDiffPlantuml',
-    description: 'Generate a timestamped PlantUML Markdown tree for current git diff changes in SystemArchitecture.json. The tool compares HEAD and working tree, extracts changed elements/relationships, and writes to .argo/temp/architecture_analysis/.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        architecturePath: {
-          type: 'string',
-          description: 'Optional architecture graph path relative to workspace root. Default: design/KG/SystemArchitecture.json',
-        },
-        outputDir: {
-          type: 'string',
-          description: 'Optional output directory relative to workspace root. Default: .argo/temp/architecture_analysis',
-        },
-      },
-      additionalProperties: false,
-    },
-  },
   {
     name: 'getSystemArchitecture',
     description: 'Start here, but prefer an explicit semantic query instead of an omitted-query full graph read. Provide query.purpose and query.intent to get a compact business/architecture result, then use returned element ids with getIntentElementContext for focused dependency context. Omit query only when an exact full canonical snapshot is explicitly required.',
     inputSchema: {
       type: 'object',
+      required: ['query'],
       properties: {
         architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
         query: {
           type: 'object',
-          description: 'Preferred for ordinary agent reading. Use semantic query instead of full graph reads; combine the returned element ids with getIntentElementContext when deeper local context is needed.',
+          description: 'Required semantic query. Provide query.purpose + query.intent; combine the returned element ids with getIntentElementContext when deeper local context is needed.',
           properties: {
             purpose: {
               type: 'string',
-              enum: ['intent-decision', 'implementation-design', 'coding-repair', 'audit', 'graph-tidy'],
-              description: 'Declared reading purpose. Use intent-decision, implementation-design, coding-repair, or audit for semantic retrieval; graph-tidy intentionally bypasses semantic retrieval and may return a full snapshot.',
+              enum: ['general', 'audit'],
+              description: 'Declared reading purpose: general for generic semantic/memory retrieval, or audit for strict proof-closure reads (subject required).',
             },
             intent: { type: 'string', description: 'Natural-language intent for semantic retrieval, for example "summarize business features for high-risk audit".' },
             subject: { type: 'string', description: 'Required for audit; optional anchor/focus id for other semantic purposes.' },
@@ -416,19 +364,42 @@ async function callTool(name, args = {}, progressToken = null, dependencies = un
   loadRepositoryArgoEnvironment(resolveWorkspaceRoot(args));
   if (name === 'initializeWorkspace') {
     const workspace = await initializeWorkspace(resolveWorkspaceRoot(args));
-    const composition = canonicalSemanticInitStorage.getStore()
-      || systemArchitectureMcp.createDefaultCanonicalSemanticInitComposition({
-        repositoryRoot: resolveWorkspaceRoot(args),
-      });
-    const semanticLifecycle = await runCanonicalSemanticInit(composition, {
-      repositoryRoot: resolveWorkspaceRoot(args),
-      workspace,
+    // Deterministic argo-init harness report (Neo4j structural sync, semantic
+    // lifecycle, canonical validation, subdiagram_views consistency), built
+    // in-process so the argo-init skill needs no workspace-external script.
+    // Lazy require avoids a circular dependency (ensureArgoHarnessEnvironment
+    // requires this module at its top).
+    const { buildHarnessReport } = require('./ensureArgoHarnessEnvironment.js');
+    const report = await buildHarnessReport({
+      checkOnly: false,
+      workspaceRoot: workspace.workspaceRoot,
+      includeBootstrap: false,
     });
     return toolResult({
-      ...workspace,
-      semanticState: semanticLifecycle.state,
-      semanticLifecycle,
-      alignment: semanticLifecycle.alignment,
+      status: report.status,
+      workspaceRoot: workspace.workspaceRoot,
+      targetFeapName: workspace.targetFeapName,
+      createdFiles: workspace.createdFiles,
+      updatedFiles: workspace.updatedFiles,
+      removedFiles: workspace.removedFiles,
+      skippedSteps: workspace.skippedSteps,
+      workspaceBootstrap: {
+        status: 'ok',
+        workspaceRoot: workspace.workspaceRoot,
+        targetFeapName: workspace.targetFeapName,
+        createdFiles: workspace.createdFiles,
+        updatedFiles: workspace.updatedFiles,
+        removedFiles: workspace.removedFiles,
+        skippedSteps: workspace.skippedSteps,
+      },
+      mcp: report.mcp,
+      systemArchitecture: report.systemArchitecture,
+      subdiagramViews: report.subdiagramViews,
+      neo4j: report.neo4j,
+      semanticLifecycle: report.semanticLifecycle,
+      semanticState: report.semanticLifecycle && report.semanticLifecycle.state,
+      alignment: report.semanticLifecycle && report.semanticLifecycle.alignment,
+      reportPath: report.reportPath,
     });
   }
   if (VALIDATOR_TOOL_NAMES.has(name)) {
@@ -685,7 +656,6 @@ async function handleRequest(request, dependencies = undefined) {
         && params.arguments
         && Object.prototype.hasOwnProperty.call(params.arguments, 'query')
         && params.arguments.query
-        && params.arguments.query.purpose !== 'graph-tidy'
       ) {
         activeDependencies = {
           semanticOperatorJourney:

package/argo/scripts/ensureArgoHarnessEnvironment.js

@@ -33,40 +33,38 @@ const REQUIRED_TOOL_NAMES = [
   'validateSystemArchitecture',
 ];
 
-async function main() {
-  const options = parseArgs(process.argv.slice(2));
-  const workspaceRoot = resolveWorkspaceRoot();
+// Build the deterministic argo-init harness report (Neo4j structural sync,
+// semantic lifecycle, canonical validation, subdiagram_views consistency).
+// `includeBootstrap` is true for the standalone CLI (it calls initializeWorkspace
+// to bootstrap the workspace); the initializeWorkspace MCP tool passes false
+// because it already bootstrapped — avoids re-entrancy through ensureWorkspaceBootstrap.
+async function buildHarnessReport({ checkOnly = false, workspaceRoot, includeBootstrap = true }) {
   const reportPath = path.join(workspaceRoot, '.argo', 'temp', 'argo-harness-init-report.json');
-  const harnessEnvironment = loadRepositoryArgoEnvironment(workspaceRoot);
   const report = {
     status: 'ok',
     workspaceRoot,
     generatedAt: new Date().toISOString(),
-    mode: options.checkOnly ? 'check-only' : 'prepare-and-check',
+    mode: checkOnly ? 'check-only' : 'prepare-and-check',
     reportPath: normalizeRelativePath(path.relative(workspaceRoot, reportPath)),
-    harnessEnvironment,
   };
 
   try {
-    report.workspaceBootstrap = await ensureWorkspaceBootstrap({
-      checkOnly: options.checkOnly,
-      workspaceRoot,
-    });
+    report.harnessEnvironment = loadRepositoryArgoEnvironment(workspaceRoot);
+    if (includeBootstrap) {
+      report.workspaceBootstrap = await ensureWorkspaceBootstrap({ checkOnly, workspaceRoot });
+    }
     report.mcp = verifyArgoMcpServer({ workspaceRoot });
-    report.systemArchitecture = await verifyCanonicalSystemArchitecture();
+    report.systemArchitecture = await verifyCanonicalSystemArchitecture({ workspaceRoot });
     report.subdiagramViews = report.systemArchitecture.status === 'ok'
-      ? await ensureSubdiagramViewsConsistency({
-          checkOnly: options.checkOnly,
-          workspaceRoot,
-        })
+      ? await ensureSubdiagramViewsConsistency({ checkOnly, workspaceRoot })
       : {
           status: 'skipped',
-          mode: options.checkOnly ? 'check' : 'fix-direct',
+          mode: checkOnly ? 'check' : 'fix-direct',
           reason: 'system architecture invalid; subdiagram_views repair skipped',
         };
-    report.neo4j = await ensureNeo4jProjection({ checkOnly: options.checkOnly });
+    report.neo4j = await ensureNeo4jProjection({ checkOnly });
     report.semanticLifecycle = await ensureCanonicalSemanticLifecycle({
-      checkOnly: options.checkOnly,
+      checkOnly,
       workspaceRoot,
       neo4j: report.neo4j,
     });
@@ -75,25 +73,24 @@ async function main() {
     report.error = formatErrorForReport(error);
   }
 
-  if (report.workspaceBootstrap && report.workspaceBootstrap.status === 'failed') {
-    report.status = 'failed';
-  }
-  if (report.mcp && report.mcp.status === 'failed') {
-    report.status = 'failed';
-  }
-  if (report.systemArchitecture && report.systemArchitecture.status === 'failed') {
-    report.status = 'failed';
-  }
-  if (report.neo4j && report.neo4j.status === 'failed') {
-    report.status = 'failed';
-  }
-  if (report.semanticLifecycle && report.semanticLifecycle.status === 'failed') {
-    report.status = 'failed';
-  }
-  if (report.subdiagramViews && report.subdiagramViews.status === 'failed') {
-    report.status = 'failed';
+  for (const section of ['workspaceBootstrap', 'mcp', 'systemArchitecture', 'neo4j', 'semanticLifecycle', 'subdiagramViews']) {
+    if (report[section] && report[section].status === 'failed') {
+      report.status = 'failed';
+    }
   }
 
+  return report;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const workspaceRoot = resolveWorkspaceRoot();
+  const report = await buildHarnessReport({
+    checkOnly: options.checkOnly,
+    workspaceRoot,
+    includeBootstrap: true,
+  });
+  const reportPath = path.join(workspaceRoot, '.argo', 'temp', 'argo-harness-init-report.json');
   writeJson(reportPath, report);
   console.log(JSON.stringify(report, null, 2));
 
@@ -102,6 +99,8 @@ async function main() {
   }
 }
 
+module.exports = { buildHarnessReport, main };
+
 function parseArgs(argv) {
   const options = {
     checkOnly: false,
@@ -246,16 +245,16 @@ function verifyArgoMcpServer({ workspaceRoot }) {
   };
 }
 
-async function verifyCanonicalSystemArchitecture() {
-  const getResponse = await argoMcp.callTool('getSystemArchitecture', {
-    architecturePath: DEFAULT_GRAPH_PATH,
-  });
-  const getPayload = parseToolPayload(getResponse);
-  if (getPayload.status !== 'passed') {
+async function verifyCanonicalSystemArchitecture({ workspaceRoot } = {}) {
+  const graphPath = DEFAULT_GRAPH_PATH;
+  let document = null;
+  try {
+    const raw = fs.readFileSync(path.resolve(workspaceRoot, graphPath), 'utf8');
+    document = JSON.parse(raw);
+  } catch (error) {
     return {
       status: 'failed',
-      error: `getSystemArchitecture failed for ${DEFAULT_GRAPH_PATH}`,
-      payload: getPayload,
+      error: `failed to read canonical graph ${graphPath}: ${error.message}`,
     };
   }
 
@@ -264,7 +263,7 @@ async function verifyCanonicalSystemArchitecture() {
   if (validatePayload.status !== 'passed') {
     return {
       status: 'failed',
-      graphPath: getPayload.graphPath,
+      graphPath,
       error: 'validateSystemArchitecture reported errors.',
       errors: validatePayload.errors || [],
     };
@@ -272,11 +271,11 @@ async function verifyCanonicalSystemArchitecture() {
 
   return {
     status: 'ok',
-    graphPath: getPayload.graphPath,
-    elementCount: Array.isArray(getPayload.document && getPayload.document.elements) ? getPayload.document.elements.length : 0,
-    relationshipCount: Array.isArray(getPayload.document && getPayload.document.relationships) ? getPayload.document.relationships.length : 0,
-    viewCount: Array.isArray(getPayload.document && getPayload.document.views) ? getPayload.document.views.length : 0,
-    neo4jRecovery: getPayload.neo4jRecovery || null,
+    graphPath,
+    elementCount: Array.isArray(document.elements) ? document.elements.length : 0,
+    relationshipCount: Array.isArray(document.relationships) ? document.relationships.length : 0,
+    viewCount: Array.isArray(document.views) ? document.views.length : 0,
+    neo4jRecovery: null,
   };
 }
 
@@ -412,7 +411,9 @@ function formatErrorForReport(error) {
   return message;
 }
 
-main().catch(error => {
-  console.error(formatErrorForReport(error));
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch(error => {
+    console.error(formatErrorForReport(error));
+    process.exit(1);
+  });
+}

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

@@ -50,6 +50,14 @@ const PURPOSE_CATEGORIES = Object.freeze([
   'graph-tidy',
 ]);
 
+// Agent-facing purpose alias: the generic memory/context read is exposed to
+// agents as `general`; internally it binds to the implementation-design closure
+// category (same loose-threshold retrieval, generic closure shape). The other
+// categories stay internal-only (exercised by the W5 purpose-closure runners).
+const AGENT_PURPOSE_TO_CATEGORY = Object.freeze({
+  general: 'implementation-design',
+});
+
 const PURPOSE_POLICY_ANCHORS = Object.freeze({
   'intent-decision': 'grag-intent-decision-policy',
   'implementation-design': 'grag-implementation-policy',
@@ -617,7 +625,7 @@ function average(values) {
 
 async function closePurposePolicyScope(options) {
   const request = options.request || {};
-  const category = request.purpose;
+  const category = AGENT_PURPOSE_TO_CATEGORY[request.purpose] || request.purpose;
   const template = PURPOSE_POLICY_TEMPLATES[category];
   const policyAnchorId = PURPOSE_POLICY_ANCHORS[category];
   if (!template || !policyAnchorId) {
@@ -1582,7 +1590,8 @@ function isLifecycleRequest(request = {}) {
 }
 
 function isPurposePolicyClosureRequest(request = {}) {
-  return PURPOSE_CATEGORIES.includes(request.purpose);
+  const category = AGENT_PURPOSE_TO_CATEGORY[request.purpose] || request.purpose;
+  return PURPOSE_CATEGORIES.includes(category);
 }
 
 function semanticIndexNotAligned(alignment) {

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

@@ -10,11 +10,8 @@ const {
 
 const DEFAULT_GRAPH_PATH = 'design/KG/SystemArchitecture.json';
 const LEGAL_QUERY_PURPOSES = new Set([
-  'intent-decision',
-  'implementation-design',
-  'coding-repair',
+  'general',
   'audit',
-  'graph-tidy',
 ]);
 const FORBIDDEN_RESPONSE_SHAPE_CONTROL_FIELDS = Object.freeze([
   'responseProfile',
@@ -42,12 +39,12 @@ const GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA = {
     },
     mode: {
       type: 'string',
-      enum: ['full-snapshot', 'semantic-query', 'error'],
+      enum: ['semantic-query', 'error'],
       description: 'Discriminator for the response variant.',
     },
     document: {
       type: ['object', 'null'],
-      description: 'Canonical graph snapshot for full-snapshot responses; semantic business-summary responses may use result in the text payload and set this to null; null for errors.',
+      description: 'Canonical graph snapshot for semantic responses; semantic business-summary responses may use result in the text payload and set this to null; null for errors.',
     },
     query: {
       type: ['object', 'null'],
@@ -55,11 +52,11 @@ const GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA = {
         purpose: { type: 'string', enum: Array.from(LEGAL_QUERY_PURPOSES) },
         intent: { type: 'string' },
         subject: { type: 'string' },
-        mode: { type: 'string', enum: ['full-snapshot', 'semantic-query'] },
-        semanticRetrieval: { type: 'string', enum: ['bypassed', 'invoked'] },
+        mode: { type: 'string', enum: ['semantic-query'] },
+        semanticRetrieval: { type: 'string', enum: ['invoked'] },
       },
       additionalProperties: true,
-      description: 'Normalized explicit query metadata; null for no-argument snapshots and errors.',
+      description: 'Normalized explicit query metadata; null for errors.',
     },
     error: {
       oneOf: [
@@ -87,14 +84,6 @@ const GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA = {
     },
   },
   oneOf: [
-    {
-      properties: {
-        mode: { const: 'full-snapshot' },
-        document: { type: 'object' },
-        query: { type: ['object', 'null'] },
-        error: { type: 'null' },
-      },
-    },
     {
       properties: {
         mode: { const: 'semantic-query' },
@@ -137,7 +126,6 @@ const {
   validateArchiMateEndpointMatrix,
   validateViewElementLimits,
 } = require('./graph-semantics.js');
-const architectureDiffPlantuml = require('./generateArchitectureDiffPlantuml.js');
 const {
   createProductionGraphRagRuntime,
 } = require('./graph-rag/productionGraphRagRuntime.js');
@@ -188,19 +176,20 @@ const HANDLED_MUTATION_TYPES = new Set([
 const TOOLS = [
   {
     name: 'getSystemArchitecture',
-    description: 'Start here for read-only intent architecture access, but prefer an explicit semantic query instead of an omitted-query full graph read. Provide query.purpose and query.intent to get a compact business/architecture result, then use returned element ids with getIntentElementContext for focused dependency context. Omit query only when an exact full canonical snapshot is explicitly required.',
+    description: 'Read-only intent architecture access via explicit semantic query. Always provide query.purpose and query.intent to get a compact business/architecture result, then use returned element ids with getIntentElementContext for focused dependency context. Full-graph snapshot access is not exposed; query is required.',
     inputSchema: {
       type: 'object',
+      required: ['query'],
       properties: {
         architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
         query: {
           type: 'object',
-          description: 'Preferred for ordinary agent reading. Use semantic query instead of full graph reads; combine the returned element ids with getIntentElementContext when deeper local context is needed.',
+          description: 'Required semantic query. Provide query.purpose + query.intent; combine the returned element ids with getIntentElementContext when deeper local context is needed.',
           properties: {
             purpose: {
               type: 'string',
               enum: Array.from(LEGAL_QUERY_PURPOSES),
-              description: 'Declared reading purpose. Use intent-decision, implementation-design, coding-repair, or audit for semantic retrieval; graph-tidy intentionally bypasses semantic retrieval and may return a full snapshot.',
+              description: 'Declared reading purpose: general for generic semantic/memory retrieval, or audit for strict proof-closure reads (subject required).',
             },
             intent: { type: 'string', description: 'Natural-language intent for semantic retrieval, for example "summarize business features for high-risk audit".' },
             subject: { type: 'string', description: 'Required for audit; optional anchor/focus id for other semantic purposes.' },
@@ -232,24 +221,6 @@ const TOOLS = [
     description: 'read-only query that resolves one view by view_id into its complete membership: the view object, every member element (from included_elements), every member relationship (from included_relationships), the parent element, and optionally child sub-views declared by member elements. Resolves ids into full canonical objects instead of returning raw id lists.',
     inputSchema: viewContextInputSchema(),
   },
-  {
-    name: 'generateArchitectureDiffPlantuml',
-    description: 'Generate a timestamped PlantUML Markdown tree for current git diff changes in SystemArchitecture.json. The tool compares HEAD and working tree, extracts changed elements/relationships, and writes to .argo/temp/architecture_analysis/.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        architecturePath: {
-          type: 'string',
-          description: `Optional architecture graph path relative to workspace root. Default: ${DEFAULT_GRAPH_PATH}`,
-        },
-        outputDir: {
-          type: 'string',
-          description: 'Optional output directory relative to workspace root. Default: .argo/temp/architecture_analysis',
-        },
-      },
-      additionalProperties: false,
-    },
-  },
   {
     name: 'previewSystemArchitectureMutation',
     description: 'Use before apply for complex or risky changes. Performs a dry-run of one or more mutations, runs schema, graph, view, and ArchiMate 3.2 validation, and does not write the graph.',
@@ -1965,15 +1936,10 @@ function validateSemanticQueryResponseShapeControls(query) {
   return { status: 'passed' };
 }
 
-function isPurposeClosureProbe(query) {
-  return Array.isArray(query && query.anchors) && query.anchors.length > 0;
-}
-
 function isOrdinarySemanticQuery(query) {
   return !!query
     && typeof query === 'object'
-    && !Array.isArray(query)
-    && query.purpose !== 'graph-tidy';
+    && !Array.isArray(query);
 }
 
 function isCanonicalSubsetSemanticContract(query, options = {}) {
@@ -2059,7 +2025,7 @@ function getSystemArchitectureResult(payload) {
   const failed = payload.status === 'failed';
   return toolResult(payload, {
     version: '1.0',
-    mode: failed ? 'error' : ((payload.query && payload.query.mode) || 'full-snapshot'),
+    mode: failed ? 'error' : 'semantic-query',
     document: failed ? null : (payload.document === undefined ? null : payload.document),
     query: failed ? null : (payload.query || null),
     error: failed ? payload.error : null,
@@ -2075,23 +2041,6 @@ async function callTool(name, args = {}, dependencies = undefined) {
       }
 
       const query = validation.query;
-      if (query.purpose === 'graph-tidy') {
-        const context = await loadContext(args);
-        const payload = {
-          status: 'passed',
-          graphPath: context.graphPath.relativePath,
-          document: context.document,
-        };
-        if (isPurposeClosureProbe(query) && !dependencies) {
-          return attachContextWarnings(payload, context);
-        }
-        payload.query = {
-          ...query,
-          mode: 'full-snapshot',
-          semanticRetrieval: 'bypassed',
-        };
-        return getSystemArchitectureResult(attachContextWarnings(payload, context));
-      }
       const context = await loadContext(args);
       const contractOptions = semanticContractOptions({
         ...args,
@@ -2108,12 +2057,10 @@ async function callTool(name, args = {}, dependencies = undefined) {
       return applySemanticResponseProfile(await journey.query(query), query, contractOptions);
     }
 
-    const context = await loadContext(args);
-    return getSystemArchitectureResult(attachContextWarnings({
-      status: 'passed',
-      graphPath: context.graphPath.relativePath,
-      document: context.document,
-    }, context));
+    return getSystemArchitectureResult(queryError(
+      'QUERY_REQUIRED',
+      'getSystemArchitecture requires an explicit query (query.purpose + query.intent); full-graph snapshot access has been removed.',
+    ));
   }
 
   if (name === 'getIntentElementContext') {
@@ -2126,14 +2073,6 @@ async function callTool(name, args = {}, dependencies = undefined) {
     return toolResult(attachContextWarnings(buildViewContext(context, args), context));
   }
 
-  if (name === 'generateArchitectureDiffPlantuml') {
-    return toolResult(architectureDiffPlantuml.generateArchitectureDiffPlantuml({
-      workspaceRoot: resolveWorkspaceRoot(args),
-      architecturePath: args.architecturePath,
-      outputDir: args.outputDir,
-    }));
-  }
-
   if (name === 'previewSystemArchitectureMutation') {
     const context = await loadContext(args);
     return toolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, false), context));
@@ -2209,12 +2148,11 @@ async function callTool(name, args = {}, dependencies = undefined) {
   throw new Error(`Unknown tool: ${name}`);
 }
 
-// memory_search: natural-language semantic memory retrieval. Reuses the
-// memory-retrieval purpose (implementation-design) of the semantic journey
-// (same path as getSystemArchitecture, so readiness/closure behave identically)
-// and reshapes the retrieved elements into a memory-oriented hit list with
-// content + similarity score, so an agent can look up the user's memory in one
-// call.
+// memory_search: natural-language semantic memory retrieval. Uses the
+// agent-facing 'general' purpose of the semantic journey (same path as
+// getSystemArchitecture, so readiness/closure behave identically) and reshapes
+// the retrieved elements into a memory-oriented hit list with content +
+// similarity score, so an agent can look up the user's memory in one call.
 async function memorySearchTool(args = {}, dependencies = undefined) {
   const query = typeof args.query === 'string' ? args.query.trim() : '';
   if (!query) {
@@ -2232,7 +2170,7 @@ async function memorySearchTool(args = {}, dependencies = undefined) {
   let retrieved;
   try {
     const journey = await resolveSemanticOperatorJourney(dependencies);
-    retrieved = await journey.query({ purpose: 'implementation-design', intent: query });
+    retrieved = await journey.query({ purpose: 'general', intent: query });
   } catch (error) {
     return {
       status: 'failed',
@@ -3536,7 +3474,6 @@ async function handleRequest(request, dependencies = undefined) {
         && params.arguments
         && Object.prototype.hasOwnProperty.call(params.arguments, 'query')
         && params.arguments.query
-        && params.arguments.query.purpose !== 'graph-tidy'
       ) {
         activeDependencies = {
           semanticOperatorJourney: await createDefaultProductionSemanticOperatorJourney({

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

@@ -12,20 +12,12 @@ const {
   resolveCallWorkspaceRoot,
 } = require('./argo-paths.js');
 
-const HANDOFF_STAGES = ['intent-to-implementation', 'implementation-to-coding'];
-const DEFAULT_TRACE_PROPOSAL_PATH = 'design/KG/ImplementationToIntentTraceProposal.json';
 const DEFAULT_ARCHITECTURE_GRAPH_PATH = 'design/KG/SystemArchitecture.json';
 
 const SCRIPT_CANDIDATES = {
   validateSystemArchitecture: [
     'scripts/validateSystemArchitecture.js',
   ],
-  validateStageHandoff: [
-    'scripts/validateStageHandoff.js',
-  ],
-  validateTraceProposal: [
-    'scripts/validateTraceProposal.js',
-  ],
   runArchitectureTests: [
     'scripts/runArchitectureTests.js',
   ],
@@ -41,35 +33,6 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
-  {
-    name: 'validateStageHandoff',
-    description: 'Validate Argo stage handoff JSON. Use stage intent-to-implementation or implementation-to-coding, or omit to validate all supported stages.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        stage: {
-          type: 'string',
-          enum: HANDOFF_STAGES,
-          description: 'Optional handoff stage to validate.',
-        },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'validateTraceProposal',
-    description: 'Validate ImplementationToIntentTraceProposal JSON against .argo/schema/ImplementationToIntentTraceProposal.schema.json and repository path references.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        proposalPath: {
-          type: 'string',
-          description: `Optional proposal path relative to workspace root. Default: ${DEFAULT_TRACE_PROPOSAL_PATH}`,
-        },
-      },
-      additionalProperties: false,
-    },
-  },
   {
     name: 'runArchitectureTests',
     description: 'Execute explicit architecture testcases from the intent graph and refresh design/KG/test-failure-records.json. This MCP call can exceed client timeouts; if it times out, run the same test runner directly with: node .argo/scripts/runArchitectureTests.js',
@@ -257,19 +220,6 @@ async function callTool(name, args, progressToken = null) {
     return toolResult(await runValidatorScript(workspaceRoot, 'validateSystemArchitecture'));
   }
 
-  if (name === 'validateStageHandoff') {
-    const stage = args && args.stage;
-    if (stage && !HANDOFF_STAGES.includes(stage)) {
-      throw new Error(`Unsupported handoff stage '${stage}'. Expected one of: ${HANDOFF_STAGES.join(', ')}`);
-    }
-    return toolResult(await runValidatorScript(workspaceRoot, 'validateStageHandoff', stage ? [stage] : []));
-  }
-
-  if (name === 'validateTraceProposal') {
-    const proposalPath = (args && args.proposalPath) || DEFAULT_TRACE_PROPOSAL_PATH;
-    return toolResult(await runValidatorScript(workspaceRoot, 'validateTraceProposal', [proposalPath]));
-  }
-
   if (name === 'runArchitectureTests') {
     const architecturePath = (args && args.architecturePath) || DEFAULT_ARCHITECTURE_GRAPH_PATH;
     if (progressToken) {

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

@@ -1,65 +1,46 @@
 ---
 name: argo-init
-description: "检查全局 ARGO MCP 是否正常，并完成 NEO4J 初始同步与语义生命周期初始化。Use when the user asks to verify Argo MCP readiness and perform or verify the canonical JSON-to-Neo4j initial sync plus semantic lifecycle init. Keywords: ARGO INIT, harness init, MCP health check, Neo4j initial sync, semantic lifecycle."
+description: "通过 ARGO MCP 的 initializeWorkspace 接口完成工作区确定性的初始化（NEO4J 初始同步 + 语义生命周期 + canonical 校验 + subdiagram_views 一致性），无需执行 WORKSPACE 外脚本。Use when the user asks to verify Argo MCP readiness and perform or verify the canonical JSON-to-Neo4j initial sync plus semantic lifecycle init. Keywords: ARGO INIT, harness init, initializeWorkspace, Neo4j initial sync, semantic lifecycle."
 argument-hint: scope-or-mode
 disable-model-invocation: true
 ---
 
 # ARGO INIT
 
-`argo-init` 负责检查全局安装的 `argo` MCP 是否正常、完成或验证 canonical intent graph 的 Neo4j 初始同步，并在非 `--check-only` 模式下执行 canonical semantic lifecycle init。它不再负责调用旧的工作区 bootstrap / `initializeWorkspace` 工具。
+`argo-init` 通过 ARGO MCP 的 `initializeWorkspace` 接口完成确定性初始化：工作区 bootstrap（缺 `SystemArchitecture.json` / `.feap` 自动生成）+ Neo4j 结构投影同步 + 语义生命周期初始化 + canonical 校验 + subdiagram_views 一致性，并返回完整报告。**不需要也不应执行任何 WORKSPACE 外脚本**——所有确定性步骤都在 MCP 进程内完成，避免扩大访问面。
 
-- `argo` MCP 服务器（全局 `.argo` 安装）能正常初始化、列出关键工具并响应 `ping`。
-- `design/KG/SystemArchitecture.json` 可通过 `argo` MCP 正常读取和校验。
-- 工作区缺少 `design/KG/SystemArchitecture.json` 时，非 `--check-only` 模式会自动从部署的 `defaults` 拷贝默认模板；工作区没有 `.feap` 时，自动以当前项目名拷贝默认 `EA-model-template.feap`。
-- 本机 Neo4j 连接可用。
-- canonical intent graph 至少完成一次 JSON -> Neo4j 初始同步，并通过一致性校验。
-- 非 `--check-only` 模式会在结构同步后执行语义生命周期：双 gate 未开启时记录 pending/disabled；双 gate 开启时执行全量 embedding backfill 与 readiness 对齐。
+- 工作区缺少 `design/KG/SystemArchitecture.json` 时自动从部署的 `defaults` 拷贝默认模板；缺 `.feap` 时以当前项目名拷贝默认模板。
+- 本机 Neo4j 连接可用，canonical 意图图完成至少一次 JSON -> Neo4j 初始同步并通过一致性校验。
+- 语义生命周期：双 gate 未开启时记录 skipped/disabled；开启时执行全量 embedding backfill 与 readiness 对齐。
 
 ## Rules
 
-- **MUST** 优先运行全局 harness 原生命令（当前工作目录须为目标仓库根）：`node "$env:USERPROFILE\.argo\scripts\ensureArgoHarnessEnvironment.js"`。
-- **MUST** 将该命令返回的 JSON 结果作为最终判断依据，而不是凭主观描述报告环境状态。
-- **MUST** 报告 `argo` MCP 是否通过、Neo4j 是否通过、初始同步是否完成、以及 `semanticLifecycle` 当前状态。
-- **MUST** 在脚本失败时直接转述失败阶段、错误摘要和报告路径，不要改用含糊描述。
-- **MUST NOT** 读取、打印或复述 `.env` 中的 secret 值；排查时只允许报告 key 是否存在、文件是否位于 git 仓库内、以及 ACL 主体。
-- **MUST NOT** 绕开脚本分别手工执行一堆无关命令来替代初始化工作流，除非你是在排查脚本自身失败。
+- **MUST** 调用 ARGO MCP 工具 `initializeWorkspace`（传当前工作区根）执行确定性初始化，并以其返回报告为最终判断依据。
+- **MUST** 报告 `mcp` / `systemArchitecture` / `neo4j` / `semanticLifecycle` / `subdiagramViews` 与整体 `status`。
+- **MUST NOT** 读取、打印或复述 `.env` 中的 secret 值；排查时只允许报告 key 是否存在、ACL 主体。
+- **MUST NOT** 通过 shell 手工执行 WORKSPACE 外的初始化脚本或一组无关命令来替代 `initializeWorkspace`（除非报告显示底层脚本自身失败需要排查）。
 
 ## Workflow
 
-### 1. Run ARGO HARNESS Init
+### 1. Run Deterministic Init via initializeWorkspace
 
-在目标仓库根目录执行（harness 通过 `ARGO_REPO_ROOT` / `WORKSPACE_FOLDER` / `cwd` 解析工作区）：
+调用 ARGO MCP 工具 `initializeWorkspace`（传入当前工作区根 `workspaceRoot`）。该接口在 MCP 进程内完成全部确定性步骤并返回报告：
 
-```powershell
-$env:ARGO_REPO_ROOT = (Get-Location).Path
-node "$env:USERPROFILE\.argo\scripts\ensureArgoHarnessEnvironment.js"
-```
-
-只读检查（不修改工作区、不执行初始同步）：
-
-```powershell
-$env:ARGO_REPO_ROOT = (Get-Location).Path
-node "$env:USERPROFILE\.argo\scripts\ensureArgoHarnessEnvironment.js" --check-only
-```
-
-若通过 `ARGO_ENV_FILE` 指定了秘密文件，请先设置该变量再运行。
+- `workspaceBootstrap`：缺 `SystemArchitecture.json` / `.feap` 时自动生成（createdFiles / skippedSteps）
+- `mcp`：ARGO MCP 健康（协议 / tools-list / ping）
+- `systemArchitecture`：canonical 校验（元素/关系/视图计数）
+- `subdiagramViews`：subdiagram_views 一致性检查/修复
+- `neo4j`：Neo4j 连通 + 结构投影初始同步 + 一致性校验（initialSync / verification）
+- `semanticLifecycle`：语义生命周期初始化（state / alignment / readiness；未开 gate 时 skipped/disabled）
 
 ### 2. Interpret The Report
 
-读取脚本输出的 JSON，并关注 `mcp`、`systemArchitecture`、`neo4j`、`semanticLifecycle`、`reportPath`。
+- 整体 `status=ok`：环境就绪。
+- 任一 section `status=failed` → 整体 `status=failed`，指出失败阶段：`mcp` / `systemArchitecture` / `neo4j` / `semanticLifecycle` / `subdiagramViews`。
 
-- `status=ok`：环境已就绪或已确认健康。
-- `status=failed`：指出失败阶段：
-  - Argo MCP protocol health
-  - canonical SystemArchitecture validation
-  - Neo4j connectivity
-  - Neo4j initial sync / verification
-  - semantic lifecycle init / readiness alignment
+### 3. Handle Secret File Blockers（仅当报告含 secret 相关失败）
 
-### 3. Handle Secret File Blockers
-
-全局 `.env` 默认位于 `$env:USERPROFILE\.argo\.env`（可用 `ARGO_ENV_FILE` 覆盖）。安全诊断（不打印 secret 值）：
+`semanticLifecycle` 或 `systemArchitecture` 失败可能源于 `.env` 安全预检。诊断（不打印 secret 值）：
 
 ```powershell
 icacls "$env:USERPROFILE\.argo\.env"
@@ -67,30 +48,16 @@ icacls "$env:USERPROFILE\.argo\.env"
 
 处理规则：
 
-- `SECRET_FILE_ACL_UNSAFE`: 收紧 Windows ACL，只保留当前用户、Administrators、SYSTEM。
-- `SECRET_FILE_REPARSE_PROHIBITED`: 将 `.env` 替换为普通文件（去掉符号链接/重解析点）。
-- `SECRET_FILE_PATH_PROHIBITED`: 修正 `ARGO_ENV_FILE` 与安装根 `.env` 不一致的路径。
+- `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` 位于仓库外时天然不适用。
 
-Windows ACL 修复：
-
-```powershell
-$identity = whoami
-icacls "$env:USERPROFILE\.argo\.env" /inheritance:r /grant:r "${identity}:F" "BUILTIN\Administrators:F" "NT AUTHORITY\SYSTEM:F" /remove:g "BUILTIN\Users" "Everyone" "Authenticated Users" "NT AUTHORITY\Authenticated Users"
-```
-
-修复后必须重跑 init。
+修复后重跑 `initializeWorkspace`。
 
 ### 4. Report Concisely
 
-输出应直接说明：
-
-- `argo` MCP 是否正常
-- `SystemArchitecture.json` 是否正常
-- Neo4j 是否连通
-- 是否完成了一次初始同步
-- 语义生命周期状态、alignment、是否因 `--check-only` 跳过
-- 报告文件位置
+输出应直接说明：`mcp` 是否正常、`SystemArchitecture.json` 是否正常、Neo4j 是否连通、是否完成一次初始同步、语义生命周期状态与 alignment、报告路径（`.argo/temp/argo-harness-init-report.json`）。
 
 ## Output
 
@@ -98,8 +65,8 @@ icacls "$env:USERPROFILE\.argo\.env" /inheritance:r /grant:r "${identity}:F" "BU
 
 ### 1. Environment Status
 - overall status: ok / failed
-- whether Argo MCP health passed
-- whether Neo4j health passed
+- whether mcp health passed
+- whether neo4j health passed
 
 ### 2. Sync Status
 - whether initial sync was executed

package/package.json

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