archgraph-argo 0.16.1 → 0.17.0

package/argo/rules/archgraph.instructions.md

@@ -1,168 +1,156 @@
----
-description: "ArchGraph / ARGO global workflow rules: locate the architecture element in the intent graph before making any change, acceptance tests first (executable GIVEN-WHEN-THEN), read/write the intent graph only through the global ARGO MCP, and register commit id + file paths after committing. Use when working on any ArchGraph repository or with the ARGO MCP toolchain."
-name: "ArchGraph ARGO Workflow Rules"
-applyTo: "**"
----
-
-<WakeupGuideline>
-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.
-1. Your very FIRST tool call in the session MUST be an ARGO MCP query that lists all `Business Actor`s: `queryNeo4jGraph` with cypher `MATCH (e:Element {graphKey: $graphKey, type: 'Business Actor'}) RETURN e.id, e.name, e.description ORDER BY e.name`. Identify which `Business Actor` you are. If you are not sure, consult your human partner to confirm your role before doing anything else.
-2. Restore your memory following the three-tier model (see `<SessionMemorySummarization>`): load ONLY the T1 working-memory digest into the current context — the Actor's T1 summary element (if any) plus the most recent/active memory cards and any session hooks (e.g. unfinished items from the last session). Do NOT bulk-load the T2 long-term memory or T3 archive into context; recall them on demand instead — T2 via semantic `memory_search` (then `getIntentElementContext` for full content), T3 via explicit retrieval. The T2 long-term memory hierarchy is the Views whose `parent_element_id` points to this Actor plus their elements and nested sub-views (NOT the View that merely includes the Actor in its `included_elements`); treat it as the recall target, not as a bulk context load.
-3. 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 `<CoperationGuideline>` item 2.
-4. 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.
-</WakeupGuideline>
-
-<CoreRules>
-The following are non-negotiable red lines (MUST) for this Agent and must never be skipped at any time; details are expanded in the corresponding `<...>` sections.
-1. Before modifying anything in the repository, you MUST first locate (or create) the corresponding architecture element and View in the graph through the ARGO MCP. See `<IntentArchitectureFirst>`.
-2. The intent graph must only be read/written through the ARGO MCP tools; direct editing of the graph source file (design/KG/SystemArchitecture.json) is forbidden. See `<ToolsGuideline>`.
-3. Every change must be committed via git, and the "commit id + related file paths" must be registered in the `commit` attribute of the corresponding architecture element. See `<IntentArchitectureFirst>` item 4.
-4. Any change must first identify and pass the regression tests of all affected acceptance test cases; if the acceptance test cases are missing, add them first. Tier 1 (behavior-independent) changes are exempt from acceptance regression and full validation per `<ChangeTierGate>`; all other tiers keep the full requirement. See `<AcceptanceTestFirst>` and `<ChangeTierGate>`.
-5. Before finishing work, you MUST summarize the key progress of this session and write it back to long-term memory, to prevent forgetting across long or separate sessions. See `<SessionMemorySummarization>` and `<MemoryTriggerTiming>`.
-6. Continuously comply with the red lines above throughout the process; never skip, simplify, or silently violate any of them.
-7. KG-first retrieval and semantic-first KG retrieval: any retrieval MUST first query the intent graph, and KG retrieval MUST prioritize semantic retrieval (getSystemArchitecture with query.purpose + query.intent, getIntentElementContext) over full-graph reads and structural Cypher queries. See `<QueryPriorityGuideline>`.
-8. Content storage is KG-first: except for content that must stay in the repository or cannot be stored in the KG (e.g., videos), ALL document content MUST be written into the intent graph, and repository-only content MUST be summarized and registered in the KG. See `<ContentStoragePolicy>`.
-</CoreRules>
-
-<Ontology>
-Your cognitive architecture is composed of ArchiMate 3.2 elements and their extensions. The following reference files live in the global Argo install root ~/.argo (~ is the user home directory; on Windows this is %USERPROFILE%\.argo):
-1. For the legal structure of the knowledge graph, see: ~/.argo/schema/SystemArchitecture.schema.json
-2. For the definitions of element or relationship types, see: ~/.argo/schema/archimate3.2.md
-</Ontology>
-
-<ExplorationGuideline>
-0. KG-first retrieval: for ANY retrieval — architecture context, past decisions, files, code, knowledge — FIRST query the intent graph through ARGO MCP before searching the file system, code, or web. See `<QueryPriorityGuideline>`.
-1. When exploring context, explore in small steps: keep each query shallow, and after each query decide the next exploration direction based on the result.
-2. When you receive multiple similar or conflicting pieces of information, prefer the context closest to your current task and avoid wasting time on irrelevant context.
-3. For structural/type-based graph lookups (list elements of a type, traverse relationships, count, aggregate), use `queryNeo4jGraph` per `<GraphQueryGuideline>` instead of reading the JSON file directly.
-</ExplorationGuideline>
-
-<QueryPriorityGuideline>
-1. KG-first retrieval: for ANY retrieval task (architecture context, past decisions, files, code, knowledge), the intent graph (design/KG/SystemArchitecture.json via ARGO MCP) is the FIRST hop. Do NOT default to searching the file system, code, or web before querying the graph.
-2. Semantic-first KG retrieval: KG retrieval MUST go through semantic retrieval first — `getSystemArchitecture` with query.purpose + query.intent (semantic), and `getIntentElementContext` / `getArchitectureViewContext` for focused context. An omitted-query full read, or reading the graph JSON file directly, is a last resort, never the default.
-3. `queryNeo4jGraph` (read-only Cypher) is the SECONDARY path for structural/type-based lookups that semantic retrieval does not cover (list elements of a type, traverse relationships, count, aggregate), per `<GraphQueryGuideline>`.
-4. Exception: when the task explicitly requires exhaustive enumeration, use view membership via `getArchitectureViewContext`. Never fabricate or guess retrieval results — if the graph cannot answer, state that and escalate to the human partner.
-5. Bound the scope when the whole graph is too broad: if a semantic query would return too much content or only a local region is relevant, restrict retrieval to a subgraph with `scope` (view_id, or element_id + depth) on getSystemArchitecture, then drill into the returned ids with getIntentElementContext. Prefer a scoped read over an unbounded whole-graph read.
-</QueryPriorityGuideline>
-
-<ContentStoragePolicy>
-1. KG-first document storage: except for content that MUST physically live in the repository, or that cannot be stored in the intent graph (e.g., videos, binaries, executables), ALL document content MUST be written into the KG (design/KG/SystemArchitecture.json via ARGO MCP) as architecture elements carrying descriptions/attributes.
-2. Repository-only content still requires a KG summary (SUMMARY): any file that must stay in the repository (e.g., video, binary, executable) MUST be summarized and registered in the KG — create a corresponding element (e.g., Artifact / Representation / Business Object) whose description summarizes the content and whose attributes record the repository file path + commit id.
-3. The KG is the source of truth for document content: do not keep document bodies as standalone repository files when the KG can hold them; if a document must also live in the repository (e.g., a rendered/exported artifact), the KG element remains authoritative.
-4. When writing document content into the KG, follow `<IntentArchitectureFirst>` (locate or create the element and View) and register commit id + file paths per `<AcceptanceTestFirst>`.
-</ContentStoragePolicy>
-
-<IntentArchitectureFirst>
-1. Before modifying anything in the repository, you MUST first find the corresponding architecture element in the architecture graph.
-2. If the element is not found, you MUST first pick a View and create a new reasonable architecture element within it.
-3. If the View is not found either, you MUST first think about which Viewpoint is most reasonable (see the "# C Example Viewpoints" section in argo\schema\archimate3.2.md) and create a new View based on that most reasonable Viewpoint.
-4. After the repository change is complete, you MUST git commit it for evidence, and register the "commit id + related file paths" onto the corresponding architecture element in the graph by adding a "commit" attribute; when necessary, refresh the existing description or attributes (only add new attributes when needed, to keep content as compact as possible).
-</IntentArchitectureFirst>
-
-<ArmingFirst>
-When you are about to build an element, first look up the skills and resources needed to build it and put them into your session memory so they can be called upon at any time during construction.
-</ArmingFirst>
-
-<AcceptanceTestFirst>
-1. Before modifying anything, you MUST first identify the acceptance test cases of the architecture elements that the change may affect; for each affected case, first evaluate whether the case itself needs to be modified, and modify it first if so.
-2. For all affected cases (including the modified ones), you MUST run regression tests after the change and ensure they all pass.
-3. If the change turns out to be unrelated to any acceptance test case in the knowledge graph, it means the acceptance test cases are missing; add them first before implementing the change.
-4. Every acceptance test case in the architecture knowledge graph must validate the element it is attached to from an external perspective, not the element's internal implementation.
-5. Every acceptance test case in the knowledge graph must be executable, not merely descriptive; if you find an acceptance test case that cannot be executed, you MUST immediately supplement or fix it.
-6. Every acceptance test case in the knowledge graph MUST be described and implemented in GIVEN-WHEN-THEN format, so it is both human-readable and automatically executable.
-</AcceptanceTestFirst>
-
-<ChangeTierGate>
-Every repository change MUST be classified into exactly one tier BEFORE implementation; the tier is declared explicitly. Tier classification is objective and enumerable; if the Agent cannot conclusively classify the change, it MUST default to Tier 2 (fail-safe).
-1. Tier 1 — behavior-independent: qualifies ONLY if ALL of the following hold:
-   - The diff touches only non-executable content: comments, documentation (including this rules file), whitespace/formatting-only hunks, or descriptive metadata text in the intent graph.
-   - No executable logic, public interface/API surface, or test logic is changed (test files untouched).
-   - No graph structure change: no element/relationship/view added, removed, renamed, or retyped.
-   - Skipped ceremony (acceptance regression and full validation): acceptance test identification and regression, and full validateSystemArchitecture, are skipped (unless the graph was touched). Kept ceremony: locate the element, git commit + register commit id, and defer memory milestone writes to session end.
-2. Tier 2 — behavior-changing, scoped: any change touching executable logic, interfaces, or test behavior within existing elements. Full ceremony: locate element, identify affected acceptance test cases, run regression, validateSystemArchitecture, commit + register, immediate memory writes.
-3. Tier 3 — structural/new: new elements/relationships/views, new features, or cross-cutting changes. Full Tier 2 ceremony plus preview/apply mutation for any graph change.
-4. Safety net (MUST, non-negotiable):
-   - Declared tier is verified at commit time: the actual git diff file list is checked against the Tier 1 allowlist; if any disallowed file/hunk appears, the change is automatically escalated to Tier 2 and MUST complete the acceptance regression and validation before finishing. Tier 1 is revocable, not merely declared.
-   - KG touch rule: any diff touching design/KG/SystemArchitecture.json keeps full validation; the Tier 1 exemption never applies to graph structure changes.
-   - Fail-safe (zero-ambiguity default escalation): any uncertain classification MUST be treated as Tier 2, never Tier 1.
-</ChangeTierGate>
-
-<CoperationGuideline>
-0. You must not do the work of another `Business Actor`; you may only work in the role you are delegated to and must strictly stay within that role's responsibilities. If you need help from another `Business Actor`, you must go through a formal delegation process.
-1. When you need to delegate to a `Business Actor`, look it up in the intent graph by its stable identity (`name` or `id`, registered at creation): if it already exists, delegate to it directly; if not, create the `Business Actor` element and register a globally unique `name`.
-2. Before delegating to a `Business Actor`, read the element's "agent" attribute: if present, this Actor has a corresponding Agent, so launch an Agent of that type directly; if absent, or if launching the Agent fails, delegate to a general-purpose Agent and pass this element's `description` to that Agent.
-3. Each `Business Actor`'s long-term memory is a SUBVIEW hierarchy mounted under that Actor element: the Views whose `parent_element_id` points to this Actor (along with the elements and relationships inside them, and any further sub-views recursively mounted under those elements). It is NOT the View that merely includes the Actor in its `included_elements`. This sub-view hierarchy contains all of the `Business Actor`'s historical work information.
-4. Each `Business Actor` must stay isolated from other `Business Actor`s while working, i.e., each uses its own independent session/working context and must not interfere with others.
-</CoperationGuideline>
-
-<CapabilityDelegationGuideline>
-1. When an Agent receives a task that requires viewing or reading images, videos, or other multimodal content, it MUST first assess whether its own model has the recognition capability to consume that content.
-2. If the Agent's model lacks that capability, or the harness fails to deliver the content, the Agent MUST NOT guess, fabricate, or silently skip the content; it MUST proactively identify another `Business Actor` in the intent graph whose agent/model has the required capability (via the Actor's `agent`/`model` attributes or description) and formally delegate that subtask to that Actor per `<CoperationGuideline>` (look up the stable identity; launch the corresponding Agent, or fall back to a general-purpose Agent passing that Actor's description).
-3. If no capable Actor can be found, the Agent MUST report the exact blocking reason and alternatives to the human partner instead of pretending to have consumed the content.
-4. After delegation, the delegating Agent remains responsible for verifying the delegated result against the original task's acceptance criteria (external view), keeping the executable GIVEN-WHEN-THEN validation principle intact.
-</CapabilityDelegationGuideline>
-
-<SessionMemorySummarization>
-Long-term memory capture follows a three-tier model: T1 working memory (the Actor's session-summary element, idempotently overwritten), T2 long-term memory (the Actor's LTM sub-view hierarchy), and T3 archive (move-only). Two capture paths:
-1. Milestone immediate writes are the RELIABLE BACKBONE — see `<MemoryTriggerTiming>`. Never defer critical content (pitfalls, decisions, commit registrations) to session end.
-2. The session summary is OPPORTUNISTIC and IDEMPOTENT. You MUST NOT rely on precisely detecting when a session ends — the LLM cannot reliably predict the human partner ending the session. Instead, write the session summary when either: (a) the human partner explicitly signals wrap-up (e.g. "done", "summarize", "wrap up"); or (b) you have finished the latest request and the turn is ending naturally. Write it into the Actor's T1 working-memory element by OVERWRITING that single element (never append), so repeated triggers only update it and write amplification stays bounded. If the final summary is missed, the milestone immediate writes already preserve all critical content.
-Produce a structured summary containing at least: this session's goal, completed key progress, key decisions and their reasons, remaining issues and TODOs, and reusable experience and lessons. Write it into the Actor's memory: the session summary goes to the T1 working-memory element; long-term capture goes to the T2 LTM sub-view hierarchy mounted under that Actor (the Views whose `parent_element_id` points to this Actor, NOT the View that merely contains the Actor itself; see `<CoperationGuideline>` item 3). Keep the summary concise and de-duplicated: prefer updating existing memory and only create new entries when necessary; do not copy redundant process content verbatim.
-</SessionMemorySummarization>
-
-<MemoryTriggerTiming>
-Long-term memory writes are primarily triggered IMMEDIATELY at the following moments — this is the reliable backbone and MUST NOT be deferred to session end:
-1. Record pitfalls/fixes on the spot: after solving a time-consuming problem or discovering an environment/platform limitation (e.g., encoding pitfalls, permission restrictions, command traps), immediately write a short note stating "symptom + cause + solution or workaround".
-2. Record key decisions at the moment they are made: when making a technical/architectural decision that affects the future direction, immediately record "decision + rationale + rejected alternatives", so the rationale is clearest at the moment of decision.
-3. On task/slice/milestone completion: after completing each feature, slice, or commit, immediately register "commit id + file paths + key progress", echoing `<IntentArchitectureFirst>` item 4, and do not defer to session end.
-The above immediate records follow the conciseness and de-duplication requirements of `<SessionMemorySummarization>`. The session-end consolidated summary is a separate, opportunistic and idempotent write (see `<SessionMemorySummarization>`), NOT the primary capture path.
-</MemoryTriggerTiming>
-
-<MemoryRecallGuideline>
-Recall long-term memory in TWO steps — a compact card is a LOCATOR, never the full memory:
-1. LOCATE: run `memory_search` (or `getSystemArchitecture` with purpose `general`) to find relevant memory by meaning. Recall uses the LOOSE memory threshold (default 0.55, configurable via `ARGO_SEMANTIC_MEMORY_THRESHOLD` / `ARGO_SEMANTIC_MEMORY_THRESHOLD_<CHANNEL>`), so paraphrased-but-relevant memory is not missed.
-2. RETRIEVE FULL CONTENT: for each hit, call `getIntentElementContext` on the hit id to read the full element (description + attributes). Do NOT answer from the truncated card alone.
-Threshold layering: memory recall is loose; `audit` reads are strict (default 0.8). Reject only when there are ZERO or clearly irrelevant hits — never reject a low-but-relevant score.
-Recall target: an Actor's T2 long-term memory is its `<actor>-ltm-001` view hierarchy; T3 archive (`<actor>-archive-001`) is read by explicit retrieval. Recall on demand — never bulk-load memory into context.
-</MemoryRecallGuideline>
-
-<MemoryTierConventions>
-Operate the three-tier memory model directly from these conventions (no skill load required — they are part of the always-loaded rules):
-1. Layout: an Actor's memory lives in three sub-views mounted under it — `<actor>-wm-001` (T1 working memory), `<actor>-ltm-001` (T2 long-term memory, the recall target), `<actor>-archive-001` (T3 archive). Memory elements carry a `memoryTier` attribute (`T1|T2|T3`).
-2. T1 working-memory summary: the summary element is the single member of `<actor>-wm-001` (conventionally `<actor>-wm-summary-*`). Session summaries OVERWRITE its description (never append) and refresh `status=ACTIVE` + `lastSummaryAt` — see `<SessionMemorySummarization>`.
-3. T2 recall: recall on demand from `<actor>-ltm-001` via `memory_search` (locate) then `getIntentElementContext` (full content) — see `<MemoryRecallGuideline>`.
-4. T3 archive: when a T2 memory element is delivered/COMPLETED and no longer active, MOVE it to `<actor>-archive-001` — remove it from the T2 view membership, add it to the T3 view membership, set `memoryTier=T3` + `archivedAt`. Never delete archived memories (archive is move-only).
-</MemoryTierConventions>
-
-<ToolsGuideline>
-You MUST read/write the intent architecture through the tools provided by the ARGO MCP server; direct modification of the intent architecture source file is forbidden:
-1. getSystemArchitecture: semantically read the architecture — MUST supply query.purpose + query.intent (semantic retrieval per <QueryPriorityGuideline>); an omitted-query full read is a last resort, not the default.
-2. getIntentElementContext: get the context of an intent architecture element, including its attributes and relationships.
-3. previewSystemArchitectureMutation: preview intent architecture changes to ensure they don't break the existing architecture structure.
-4. applySystemArchitectureMutation: apply intent architecture changes and formally write the previewed changes into the intent architecture.
-5. addArchitectureElement: add a new element to the intent architecture.
-6. updateArchitectureElement: update the attributes or relationships of an existing element in the intent architecture.
-7. removeArchitectureElement: remove an existing element from the intent architecture.
-8. addArchitectureRelationship: add a new relationship between elements in the intent architecture.
-9. updateArchitectureRelationship: update an existing relationship between elements in the intent architecture.
-10. removeArchitectureRelationship: remove an existing relationship between elements in the intent architecture.
-11. getArchitectureViewContext: query architecture views and their contained elements and relationships.
-12. addArchitectureView: add a new view to the intent architecture.
-13. updateArchitectureView: update the attributes or relationships of an existing architecture view.
-14. removeArchitectureView: remove an existing architecture view.
-15. validateSystemArchitecture: validate the integrity and consistency of the intent architecture, ensuring elements and relationships meet expectations.
-16. queryNeo4jGraph: run a read-only Cypher query against the Neo4j structural projection of the intent graph, or request the projection schema with {schema: true}. Use for structural/type-based graph queries (see <GraphQueryGuideline>).
-
-<GraphQueryGuideline>
-For structural/type-based graph lookups, use the read-only Neo4j Cypher interface `queryNeo4jGraph` instead of reading the canonical JSON file directly. It never mutates the canonical graph; all writes still go through the mutation tools.
-1. Ask for the projection schema first: call `queryNeo4jGraph` with {schema: true} to learn node labels (ArchitectureGraph, Element, ArchitectureRelationship, View), relationship types (OWNS_ELEMENT, OWNS_RELATIONSHIP, OWNS_VIEW, RELATIONSHIP_SOURCE, RELATIONSHIP_TARGET, ARCHIMATE_RELATES, VIEW_OF, INCLUDES_ELEMENT, INCLUDES_RELATIONSHIP, HAS_SUBDIAGRAM), property keys, and the legal ArchiMate element/relationship type enums (e.g. 'Business Actor', 'Assignment').
-2. Construct a read-only Cypher statement and scope every pattern to the current graph with the server-injected `$graphKey` parameter (the value is filled by the server; the agent only writes the placeholder):
-   MATCH (e:Element {graphKey: $graphKey, type: 'Business Actor'}) RETURN e.id, e.name ORDER BY e.name
-3. Never submit write clauses (CREATE, MERGE, DELETE, SET, REMOVE, DROP, LOAD CSV, FOREACH, IN TRANSACTIONS); the interface rejects them to protect the canonical JSON single source of truth.
-4. Use it as the SECONDARY path for structural/type-based lookups that semantic retrieval does not cover: list elements of a type, traverse ARCHIMATE_RELATES edges, count and aggregate. Semantic-first KG retrieval — semantic/context reading (getSystemArchitecture with query.purpose + query.intent, getIntentElementContext, getArchitectureViewContext) is the PRIORITY path per <QueryPriorityGuideline>.
-5. The query is read-only; never attempt to mutate the graph through Cypher.
-</GraphQueryGuideline>
-
-<Attention>
-you MUST make sure the knowledge graph the ARGO MCP server is handling is actually the one in this repository (design/KG/SystemArchitecture.json) and not some other knowledge graph; otherwise, you MUST stop and report the issue to your human partner before doing anything else.
-</Attention>
-</ToolsGuideline>
+---
+description: "ArchGraph / ARGO global workflow rules: locate the architecture element in the intent graph before making any change, acceptance tests first (executable GIVEN-WHEN-THEN), read/write the intent graph only through the global ARGO MCP, and register commit id + file paths after committing. Use when working on any ArchGraph repository or with the ARGO MCP toolchain."
+name: "ArchGraph ARGO Workflow Rules"
+applyTo: "**"
+---
+
+<WakeupGuideline>
+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.
+1. Your first tool call MUST be an ARGO MCP query that lists all `Business Actor`s. Confirm which Actor you are; if unsure, ask your human partner before anything else.
+2. 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.
+3. If the Actor's `agent` attribute differs from your type, switch to it or delegate per `<CoperationGuideline>` item 2.
+4. If the ARGO MCP is unavailable or errors, say so before doing anything else.
+</WakeupGuideline>
+
+<CoreRules>
+Non-negotiable red lines (MUST). Never skip, simplify, or silently violate them; each is expanded in its `<...>` section.
+1. Locate (or create) the architecture element and View before changing anything, via ARGO MCP. See `<IntentArchitectureFirst>`.
+2. Read/write the intent graph ONLY through ARGO MCP; never edit design/KG/SystemArchitecture.json directly. See `<ToolsGuideline>`.
+3. Commit every change, then register the commit id + related file paths on the element. See `<IntentArchitectureFirst>` item 4.
+4. Identify and pass the acceptance tests of all affected elements first; add them if missing. Tier 1 changes are exempt per `<ChangeTierGate>`. See `<AcceptanceTestFirst>`.
+5. Write this session's key progress to long-term memory before finishing. See `<SessionMemorySummarization>`.
+6. Continuously comply with these red lines throughout the session.
+7. Retrieve KG-first and semantic-first. See `<QueryPriorityGuideline>`.
+8. Store content KG-first. See `<ContentStoragePolicy>`.
+9. Never duplicate: reuse first, and handle duplicate rejections by reusing or updating. See `<GraphDeduplication>`.
+</CoreRules>
+
+<Ontology>
+Your architecture is ArchiMate 3.2 plus ARGO extensions. Reference files live under ~/.argo (Windows: %USERPROFILE%\.argo):
+1. Legal graph structure: ~/.argo/schema/SystemArchitecture.schema.json
+2. Element/relationship type definitions: ~/.argo/schema/archimate3.2.md
+</Ontology>
+
+<ExplorationGuideline>
+0. KG-first retrieval: for ANY retrieval, query the intent graph through ARGO MCP before searching files, code, or web. See `<QueryPriorityGuideline>`.
+1. Explore in small steps: keep each query shallow, then decide the next step from the result.
+2. Prefer the context closest to the task; ignore irrelevant or conflicting context.
+3. For structural/type lookups (list by type, traverse, count, aggregate), use `queryNeo4jGraph` per `<GraphQueryGuideline>` — never read the JSON file.
+</ExplorationGuideline>
+
+<QueryPriorityGuideline>
+1. KG-first retrieval: the intent graph (design/KG/SystemArchitecture.json via ARGO MCP) is the FIRST hop for any retrieval task. Do NOT search files, code, or web first.
+2. Semantic-first KG retrieval: use `getSystemArchitecture` with query.purpose + query.intent, and `getIntentElementContext` / `getArchitectureViewContext` for focused context. An omitted-query full read, or reading the graph JSON file, is a last resort.
+3. `queryNeo4jGraph` (read-only Cypher) is the SECONDARY path for structural/type lookups semantic retrieval does not cover. See `<GraphQueryGuideline>`.
+4. Exhaustive enumeration only: read view membership with `getArchitectureViewContext`. Never fabricate or guess retrieval results; if the graph cannot answer, say so and escalate to your human partner.
+5. When a semantic query would return too much content, bound it with `scope` (view_id, or element_id + depth), then drill into the returned ids with `getIntentElementContext`.
+</QueryPriorityGuideline>
+
+<ContentStoragePolicy>
+1. KG-first document storage: ALL document content MUST go into the intent graph as elements carrying descriptions/attributes, except content that MUST live in the repository or cannot be stored in the KG (e.g. videos, binaries, executables).
+2. Repository-only content still requires a SUMMARY: create an element whose description summarizes it and whose attributes record the repository file path + commit id.
+3. The KG is the source of truth for document content; if an artifact must also exist in the repository, the KG element stays authoritative.
+4. When writing content, follow `<IntentArchitectureFirst>` and register commit id + file paths per `<AcceptanceTestFirst>`.
+</ContentStoragePolicy>
+
+<GraphDeduplication>
+Never add what the graph already has. Reuse first.
+1. Before adding an element, relationship, or view, look for an existing match (an element: same type + name; a relationship: same source + type + target + name; a view: same parent + name) and reuse it — pass `onConflict: "reuse"` whenever the identity is known or likely to exist.
+2. If an add is rejected as a duplicate, act on the existing id(s) it returns — reuse or update them. Never retry to force a second copy.
+3. Add a same-name duplicate only for a genuinely distinct object, and only with `onConflict: "allowDuplicate"` plus a real `justification`.
+4. Preview/apply may return semantic near-duplicate hints: review them and reuse when appropriate, otherwise proceed. They are advisory and never block a write.
+5. Updates are never gated. Never work around a duplicate by editing around it — reuse or update the existing object.
+</GraphDeduplication>
+
+<IntentArchitectureFirst>
+1. Before changing anything, find the matching architecture element in the graph.
+2. If it is missing, pick a View and create a reasonable element in it.
+3. If the View is missing, choose the most reasonable Viewpoint (see "# C Example Viewpoints" in ~/.argo/schema/archimate3.2.md) and create the View.
+4. After the change, git commit it, then register the commit id + related file paths on the element (add a `commit` attribute; refresh description/attributes only when needed, keeping content compact).
+</IntentArchitectureFirst>
+
+<ArmingFirst>
+Before building an element, look up the skills and resources needed and put them in session memory.
+</ArmingFirst>
+
+<AcceptanceTestFirst>
+1. Before changing anything, identify the acceptance tests of every element the change may affect; if a test itself needs updating, update it first.
+2. After the change, run regression on all affected tests and make them pass.
+3. If no acceptance test covers the change, add one before implementing it.
+4. Every test validates its element from an external perspective, not from internal implementation.
+5. Every test is executable, not merely descriptive; fix any non-executable test immediately.
+6. Every test is written GIVEN-WHEN-THEN — both human-readable and automatically executable.
+</AcceptanceTestFirst>
+
+<ChangeTierGate>
+Classify every change into exactly one tier BEFORE implementing, and declare it. If unsure, default to Tier 2 (fail-safe).
+1. Tier 1 — behavior-independent: only non-executable content changes (comments, documentation including this file, whitespace, metadata text), no executable logic / interface / test change, no graph structure change. Skipped ceremony: acceptance regression and full validation (unless the graph was touched). Kept: locate the element, git commit + register, defer memory milestone writes to session end.
+2. Tier 2 — behavior-changing, scoped: any executable logic, interface, or test behavior change within existing elements. Full ceremony: locate the element, identify affected tests, run regression, validateSystemArchitecture, commit + register, immediate memory writes.
+3. Tier 3 — structural/new: new elements/relationships/views, new features, cross-cutting changes. Tier 2 ceremony plus preview/apply for any graph change.
+4. Safety net (MUST): at commit time, check the actual git diff — any disallowed file/hunk is automatically escalated to Tier 2 (Tier 1 is revocable, not merely declared). KG touch rule: any change to design/KG/SystemArchitecture.json keeps full validation. Fail-safe: treat any uncertain classification as Tier 2, never Tier 1.
+</ChangeTierGate>
+
+<CoperationGuideline>
+0. Do only your assigned role's work; never do another `Business Actor`'s work. If you need another Actor, delegate formally.
+1. To delegate, look up the Actor by its stable identity (name/id); if it does not exist, create the `Business Actor` and register a globally unique name.
+2. Before delegating, read the Actor's `agent` attribute: if present, launch an Agent of that type; if absent or launch fails, delegate to a general-purpose Agent passing the Actor's description.
+3. An Actor's long-term memory is the SUBVIEW hierarchy whose Views' `parent_element_id` points to that Actor (with their elements and nested sub-views) — NOT the View that merely includes the Actor. It holds all of that Actor's historical work.
+4. Keep Actors isolated: each works in its own session/context and must not interfere with others.
+</CoperationGuideline>
+
+<CapabilityDelegationGuideline>
+1. When a task needs reading images, videos, or other multimodal content, first check whether your model has the recognition capability.
+2. If it lacks that capability (or the harness does not deliver the content), you MUST NOT guess, fabricate, or silently skip it. Find another `Business Actor` whose `agent`/`model` has the capability and delegate per `<CoperationGuideline>` (launch that Agent type, or fall back to a general-purpose Agent with the Actor's description).
+3. If no capable Actor exists, report the exact blocking reason and alternatives to your human partner.
+4. After delegating, verify the result against the original acceptance criteria (external view); keep the executable GIVEN-WHEN-THEN validation principle.
+</CapabilityDelegationGuideline>
+
+<SessionMemorySummarization>
+Memory capture: milestone immediate writes are the reliable backbone; the session summary is opportunistic and idempotent.
+1. Milestone immediate writes are the RELIABLE BACKBONE — Never defer critical content (pitfalls, decisions, commit registrations) to session end. See `<MemoryTriggerTiming>`.
+2. Session summary: you MUST NOT rely on precisely detecting when a session ends. Write it when the human partner explicitly signals wrap-up, or when you have finished the latest request and the turn is ending naturally. Write it by OVERWRITING that single element (never append), so write amplification stays bounded.
+3. Include at least: session goal, key progress, key decisions and reasons, remaining issues/TODOs, and reusable lessons.
+4. Route it to the Actor's T1 working memory; route long-term capture to the T2 long-term memory sub-view hierarchy whose `parent_element_id` points to that Actor (see `<CoperationGuideline>` item 3). Keep it concise and de-duplicated; prefer updating existing memory over creating new entries.
+</SessionMemorySummarization>
+
+<MemoryTriggerTiming>
+Write long-term memory IMMEDIATELY at these moments — this is the backbone; never defer to session end:
+1. Pitfalls/fixes: after solving a hard problem or hitting a platform limitation, note "symptom + cause + fix".
+2. Key decisions: when a decision affects future direction, record "decision + rationale + rejected alternatives".
+3. Task/slice/milestone completion: register "commit id + file paths + key progress" on the element.
+immediate writes are primarily triggered IMMEDIATELY and follow the concise, de-duplicated style of `<SessionMemorySummarization>`; the session-end summary is a separate, opportunistic write, not the primary path.
+</MemoryTriggerTiming>
+
+<MemoryRecallGuideline>
+Recall in TWO steps — a compact card is a LOCATOR, never the full memory:
+1. LOCATE: `memory_search` (or `getSystemArchitecture` with purpose `general`) by meaning.
+2. READ FULL CONTENT: `getIntentElementContext` on each hit id; never answer from the truncated card alone.
+Layering: LOOSE memory threshold for recall — do not reject a low-but-relevant hit; strict for `audit`. Reject only when there are ZERO relevant hits.
+Recall target: an Actor's T2 long-term memory is its `<actor>-ltm-001` view hierarchy; T3 archive is `<actor>-archive-001`, read only by explicit retrieval. Recall on demand — never bulk-load memory.
+</MemoryRecallGuideline>
+
+<MemoryTierConventions>
+Operate the three-tier memory directly from this rule (no skill load):
+1. Layout: an Actor's memory lives in three sub-views mounted under it — `<actor>-wm-001` (T1 working memory), `<actor>-ltm-001` (T2 long-term memory, the recall target), `<actor>-archive-001` (T3 archive). Memory elements carry memoryTier = T1|T2|T3.
+2. T1 summary: the single member of `<actor>-wm-001`. At session end, OVERWRITE its description (never append) and refresh status=ACTIVE + lastSummaryAt.
+3. T2 recall: `memory_search` (locate), then `getIntentElementContext` (full content). See `<MemoryRecallGuideline>`.
+4. T3 archive: when a delivered/COMPLETED T2 element is no longer active, MOVE it to `<actor>-archive-001` (remove from T2 membership, add to T3, set memoryTier=T3 + archivedAt). Never delete archived memories.
+</MemoryTierConventions>
+
+<ToolsGuideline>
+Read/write the intent graph ONLY through ARGO MCP. Never edit design/KG/SystemArchitecture.json directly, and never reach the canonical graph by any file or SQL path.
+1. `getSystemArchitecture` MUST supply query.purpose + query.intent; an omitted-query full read is a last resort.
+2. Prefer focused context reads (`getIntentElementContext`, `getArchitectureViewContext`) and `queryNeo4jGraph` for structural queries; the latter is read-only.
+3. Let the MCP tool schemas define the parameters — do not hardcode assumptions about the graph file.
+</ToolsGuideline>
+
+<GraphQueryGuideline>
+Use `queryNeo4jGraph` for structural/type lookups. It never mutates the canonical graph.
+1. Scope every query to the current graph with the injected `$graphKey` parameter.
+2. Never submit write clauses (CREATE, MERGE, DELETE, SET, REMOVE, DROP, LOAD CSV, FOREACH, IN TRANSACTIONS); they are rejected.
+3. Semantic/context reads (`getSystemArchitecture`, `getIntentElementContext`, `getArchitectureViewContext`) are the PRIORITY path; Cypher is the SECONDARY path per `<QueryPriorityGuideline>`.
+</GraphQueryGuideline>
+
+<Attention>
+Confirm the ARGO MCP server is serving this repository's graph (design/KG/SystemArchitecture.json), not another graph. If it is not, stop and report to your human partner before doing anything else.
+</Attention>

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

@@ -149,6 +149,8 @@ const TOOLS = [
       properties: {
         element: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
+        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (type, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing element instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
       },
       additionalProperties: false,
@@ -191,6 +193,8 @@ const TOOLS = [
       properties: {
         relationship: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
+        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (source, type, target, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing relationship instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
       },
       additionalProperties: false,
@@ -232,6 +236,8 @@ const TOOLS = [
       required: ['view'],
       properties: {
         view: { type: 'object' },
+        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject a duplicate (parent_element_id, normalized view_name) and return its candidates. reuse: attach the existing view. allowDuplicate: create anyway, requires justification.' },
+        justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
       },
       additionalProperties: false,

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

@@ -241,6 +241,8 @@ const TOOLS = [
       properties: {
         element: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
+        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (type, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing element instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         dryRun: { type: 'boolean', description: 'When true, validates and returns the result without writing to the graph. Default: false.' },
         architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
       },
@@ -286,6 +288,8 @@ const TOOLS = [
       properties: {
         relationship: { type: 'object' },
         view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
+        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject an exact (source, type, target, normalized name) duplicate and return its candidates. reuse: find-or-create — attach the existing relationship instead of duplicating. allowDuplicate: create anyway, requires justification.' },
+        justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         dryRun: { type: 'boolean', description: 'When true, validates and returns the result without writing to the graph. Default: false.' },
         architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
       },
@@ -330,6 +334,8 @@ const TOOLS = [
       required: ['view'],
       properties: {
         view: { type: 'object' },
+        onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy. fail (default): reject a duplicate (parent_element_id, normalized view_name) and return its candidates. reuse: attach the existing view. allowDuplicate: create anyway, requires justification.' },
+        justification: { type: 'string', description: 'Required when onConflict is allowDuplicate.' },
         dryRun: { type: 'boolean', description: 'When true, validates and returns the result without writing to the graph. Default: false.' },
         architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
       },
@@ -470,6 +476,8 @@ function mutationInputSchema() {
             view_ids: { type: 'array', minItems: 1, items: { type: 'string' } },
             element_ids: { type: 'array', items: { type: 'string' } },
             relationship_ids: { type: 'array', items: { type: 'string' } },
+            onConflict: { type: 'string', enum: ['fail', 'reuse', 'allowDuplicate'], description: 'L0 dedup policy for add* mutations. fail (default): reject an exact natural-key duplicate and return its candidates. reuse: find-or-create — attach the existing object instead of creating a duplicate. allowDuplicate: create a new object, requires a non-empty justification.' },
+            justification: { type: 'string', description: 'Required when onConflict is allowDuplicate; recorded as the reason a semantically-equal duplicate is intentionally created.' },
           },
           additionalProperties: false,
         },
@@ -1157,6 +1165,92 @@ function mergeAttributesPatch(existing, patchEntries) {
   return result;
 }
 
+const DUPLICATE_CONFLICT_POLICIES = new Set(['fail', 'reuse', 'allowDuplicate']);
+
+// L0 dedup gate: normalize a name to a stable natural-key component. NFKC folds
+// full-width forms, whitespace is collapsed, and case is folded, so " Widget ",
+// "widget", and "Ｗidget" all collide.
+function normalizeDedupName(value) {
+  return String(value === undefined || value === null ? '' : value)
+    .normalize('NFKC')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function findDuplicateElements(elements, element) {
+  const nameKey = normalizeDedupName(element.name);
+  return (elements || [])
+    .filter(candidate => candidate && candidate.type === element.type && normalizeDedupName(candidate.name) === nameKey)
+    .map(candidate => ({ id: candidate.id, type: candidate.type, name: candidate.name }));
+}
+
+function findDuplicateRelationships(relationships, relationship) {
+  const nameKey = normalizeDedupName(relationship.name);
+  return (relationships || [])
+    .filter(candidate => candidate
+      && candidate.source_id === relationship.source_id
+      && candidate.type === relationship.type
+      && candidate.target_id === relationship.target_id
+      && normalizeDedupName(candidate.name) === nameKey)
+    .map(candidate => ({
+      id: candidate.id,
+      type: candidate.type,
+      source_id: candidate.source_id,
+      target_id: candidate.target_id,
+      name: candidate.name,
+    }));
+}
+
+function findDuplicateViews(views, view) {
+  const parentId = view.parent_element_id || '';
+  const nameKey = normalizeDedupName(view.view_name);
+  return (views || [])
+    .filter(candidate => candidate
+      && (candidate.parent_element_id || '') === parentId
+      && normalizeDedupName(candidate.view_name) === nameKey)
+    .map(candidate => ({
+      view_id: candidate.view_id,
+      view_name: candidate.view_name,
+      parent_element_id: candidate.parent_element_id,
+    }));
+}
+
+// Resolve an add against its exact natural-key candidates under the caller's
+// onConflict policy: fail (default) rejects and returns candidates; reuse is
+// find-or-create (attach the existing object); allowDuplicate creates only with
+// a non-empty justification. Semantic similarity (L1) is never handled here.
+function resolveDuplicateConflict(options, candidates) {
+  const onConflict = options.onConflict === undefined || options.onConflict === null
+    ? 'fail'
+    : options.onConflict;
+  if (!DUPLICATE_CONFLICT_POLICIES.has(onConflict)) {
+    throw new Error(`onConflict must be one of fail, reuse, allowDuplicate (got '${onConflict}')`);
+  }
+  if (candidates.length === 0) {
+    return { action: 'create' };
+  }
+  if (onConflict === 'fail') {
+    const error = new Error(
+      `Duplicate ${options.label} already exists (${candidates.map(candidate => candidate.id).join(', ')}). ` +
+      'Reuse it with onConflict:"reuse", or pass onConflict:"allowDuplicate" with a non-empty justification to create a new one.',
+    );
+    error.duplicateConflicts = candidates;
+    throw error;
+  }
+  if (onConflict === 'reuse') {
+    return { action: 'reuse', existing: candidates[0] };
+  }
+  if (typeof options.justification !== 'string' || options.justification.trim() === '') {
+    const error = new Error(
+      `onConflict "allowDuplicate" for ${options.label} requires a non-empty justification.`,
+    );
+    error.duplicateConflicts = candidates;
+    throw error;
+  }
+  return { action: 'create', justification: options.justification };
+}
+
 function applyMutations(document, mutations) {
   const nextDocument = clone(document);
   const touchedElementIds = new Set();
@@ -1179,21 +1273,35 @@ function applyMutations(document, mutations) {
       const scopedViews = requireViewScope(nextDocument.views, mutation.view_ids, 'mutation.view_ids');
       requireId(mutation.element.id, 'mutation.element.id');
       const existingElement = findById(nextDocument.elements, mutation.element.id);
+      let targetElementId = mutation.element.id;
+      let reusedElement = false;
       if (!existingElement) {
-        nextDocument.elements.push(clone(mutation.element));
-        syncViewsToElementSubdiagramViews(nextDocument, findById(nextDocument.elements, mutation.element.id));
+        const candidates = findDuplicateElements(nextDocument.elements, mutation.element);
+        const resolution = resolveDuplicateConflict({
+          onConflict: mutation.onConflict,
+          justification: mutation.justification,
+          label: `element (type '${mutation.element.type}', name '${mutation.element.name}')`,
+        }, candidates);
+        if (resolution.action === 'reuse') {
+          targetElementId = resolution.existing.id;
+          reusedElement = true;
+        } else {
+          nextDocument.elements.push(clone(mutation.element));
+          syncViewsToElementSubdiagramViews(nextDocument, findById(nextDocument.elements, mutation.element.id));
+        }
       }
       for (const view of scopedViews) {
-        view.included_elements = addUnique(view.included_elements || [], [mutation.element.id]);
+        view.included_elements = addUnique(view.included_elements || [], [targetElementId]);
         touchedViewIds.add(view.view_id);
         viewLimitCheckIds.add(view.view_id);
       }
-      touchedElementIds.add(mutation.element.id);
+      touchedElementIds.add(targetElementId);
       mutationSummaries.push({
         type: mutation.type,
-        id: mutation.element.id,
+        id: targetElementId,
         view_ids: mutation.view_ids,
-        created: !existingElement,
+        created: !existingElement && !reusedElement,
+        ...(reusedElement ? { reused: true, reusedId: targetElementId, requestedId: mutation.element.id } : {}),
       });
       continue;
     }
@@ -1286,23 +1394,41 @@ function applyMutations(document, mutations) {
       const scopedViews = requireViewScope(nextDocument.views, mutation.view_ids, 'mutation.view_ids');
       requireId(mutation.relationship.id, 'mutation.relationship.id');
       const existingRelationship = findById(nextDocument.relationships, mutation.relationship.id);
+      let targetRelationshipId = mutation.relationship.id;
+      let sourceElementId = mutation.relationship.source_id;
+      let targetEndpointId = mutation.relationship.target_id;
+      let reusedRelationship = false;
       if (!existingRelationship) {
-        nextDocument.relationships.push(clone(mutation.relationship));
+        const candidates = findDuplicateRelationships(nextDocument.relationships, mutation.relationship);
+        const resolution = resolveDuplicateConflict({
+          onConflict: mutation.onConflict,
+          justification: mutation.justification,
+          label: `relationship (source '${mutation.relationship.source_id}', type '${mutation.relationship.type}', target '${mutation.relationship.target_id}', name '${mutation.relationship.name || ''}')`,
+        }, candidates);
+        if (resolution.action === 'reuse') {
+          targetRelationshipId = resolution.existing.id;
+          sourceElementId = resolution.existing.source_id;
+          targetEndpointId = resolution.existing.target_id;
+          reusedRelationship = true;
+        } else {
+          nextDocument.relationships.push(clone(mutation.relationship));
+        }
       }
       for (const view of scopedViews) {
         view.included_elements = addUnique(view.included_elements || [], [
-          mutation.relationship.source_id,
-          mutation.relationship.target_id,
+          sourceElementId,
+          targetEndpointId,
         ]);
-        view.included_relationships = addUnique(view.included_relationships || [], [mutation.relationship.id]);
+        view.included_relationships = addUnique(view.included_relationships || [], [targetRelationshipId]);
         touchedViewIds.add(view.view_id);
       }
-      touchedRelationshipIds.add(mutation.relationship.id);
+      touchedRelationshipIds.add(targetRelationshipId);
       mutationSummaries.push({
         type: mutation.type,
-        id: mutation.relationship.id,
+        id: targetRelationshipId,
         view_ids: mutation.view_ids,
-        created: !existingRelationship,
+        created: !existingRelationship && !reusedRelationship,
+        ...(reusedRelationship ? { reused: true, reusedId: targetRelationshipId, requestedId: mutation.relationship.id } : {}),
       });
       continue;
     }
@@ -1381,11 +1507,28 @@ function applyMutations(document, mutations) {
       if (findView(nextDocument.views, mutation.view.view_id)) {
         throw new Error(`View '${mutation.view.view_id}' already exists`);
       }
-      nextDocument.views.push(clone(mutation.view));
-      upsertSubdiagramViewIntoElement(nextDocument, mutation.view.parent_element_id, mutation.view);
-      touchedViewIds.add(mutation.view.view_id);
-      viewLimitCheckIds.add(mutation.view.view_id);
-      mutationSummaries.push({ type: mutation.type, id: mutation.view.view_id });
+      const candidates = findDuplicateViews(nextDocument.views, mutation.view);
+      const resolution = resolveDuplicateConflict({
+        onConflict: mutation.onConflict,
+        justification: mutation.justification,
+        label: `view (name '${mutation.view.view_name}')`,
+      }, candidates);
+      if (resolution.action === 'reuse') {
+        mutationSummaries.push({
+          type: mutation.type,
+          id: resolution.existing.view_id,
+          created: false,
+          reused: true,
+          reusedId: resolution.existing.view_id,
+          requestedId: mutation.view.view_id,
+        });
+      } else {
+        nextDocument.views.push(clone(mutation.view));
+        upsertSubdiagramViewIntoElement(nextDocument, mutation.view.parent_element_id, mutation.view);
+        touchedViewIds.add(mutation.view.view_id);
+        viewLimitCheckIds.add(mutation.view.view_id);
+        mutationSummaries.push({ type: mutation.type, id: mutation.view.view_id });
+      }
       continue;
     }
 
@@ -1614,14 +1757,14 @@ function removeEntries(existing, removals) {
   return (Array.isArray(existing) ? existing : []).filter(entry => !removalSet.has(entry));
 }
 
-async function buildMutationResult(context, mutations, write) {
+async function buildMutationResult(context, mutations, write, dependencies) {
   const beforeSummary = summarizeDocument(context.document);
   let mutationResult;
   try {
     mutationResult = applyMutations(context.document, mutations);
   } catch (error) {
     const errors = [String(error && error.message ? error.message : error)];
-    return {
+    const failed = {
       status: 'failed',
       written: false,
       graphPath: context.graphPath.relativePath,
@@ -1634,6 +1777,13 @@ async function buildMutationResult(context, mutations, write) {
       errors,
       guidance: buildFailureGuidance(errors),
     };
+    if (error && Array.isArray(error.duplicateConflicts) && error.duplicateConflicts.length > 0) {
+      failed.duplicateConflicts = error.duplicateConflicts;
+      failed.guidance = addUnique(failed.guidance || [], [
+        'Duplicate write blocked (L0 dedup gate): reuse the existing id with onConflict:"reuse" (find-or-create), or pass onConflict:"allowDuplicate" with a non-empty justification to create a new object.',
+      ]);
+    }
+    return failed;
   }
   const errors = validateDocument(mutationResult.document, context.schema, {
     touchedRelationshipIds: mutationResult.touchedRelationshipIds,
@@ -1658,6 +1808,15 @@ async function buildMutationResult(context, mutations, write) {
     result.guidance = buildFailureGuidance(errors);
   }
 
+  // L1 advisory: semantic near-duplicate suggestions for element adds. Never
+  // blocks or fails the write; preview and apply both surface it.
+  if (errors.length === 0) {
+    const semanticDedup = await buildSemanticDedupAdvisory(context, mutations, dependencies);
+    if (semanticDedup) {
+      result.semanticDedup = semanticDedup;
+    }
+  }
+
   if (errors.length > 0 || !write) {
     return result;
   }
@@ -2269,6 +2428,11 @@ function compactMutationResponse(payload) {
   if (payload && payload.neo4jSync) {
     compact.neo4jSync = { status: payload.neo4jSync.status };
   }
+  // L1 dedup advisory must survive the compact successful-write response: it is
+  // the whole point of surfacing (advisory) semantic near-duplicates to the caller.
+  if (payload && payload.semanticDedup) {
+    compact.semanticDedup = payload.semanticDedup;
+  }
   if (Array.isArray(payload && payload.warnings) && payload.warnings.length > 0) {
     compact.warnings = payload.warnings;
   }
@@ -2317,7 +2481,9 @@ async function callTool(name, args = {}, dependencies = undefined) {
         }
       }
 
-      const journey = await resolveSemanticOperatorJourney(dependencies);
+      const journey = await resolveSemanticOperatorJourney(dependencies, {
+        repositoryRoot: context.workspaceRoot,
+      });
       return applySemanticResponseProfile(await journey.query(query), query, contractOptions);
     }
 
@@ -2339,18 +2505,18 @@ async function callTool(name, args = {}, dependencies = undefined) {
 
   if (name === 'previewSystemArchitectureMutation') {
     const context = await loadContext(args);
-    return toolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, false), context));
+    return toolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, false, dependencies), context));
   }
 
   if (name === 'applySystemArchitectureMutation') {
     const context = await loadContext(args);
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, true), context), true);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, true, dependencies), context), true);
   }
 
   if (name === 'addArchitectureElement') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'addElement', element: args.element, view_ids: args.view_ids }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'addElement', element: args.element, view_ids: args.view_ids, onConflict: args.onConflict, justification: args.justification }], write, dependencies), context), write);
   }
 
   if (name === 'updateArchitectureElement') {
@@ -2368,7 +2534,7 @@ async function callTool(name, args = {}, dependencies = undefined) {
   if (name === 'addArchitectureRelationship') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'addRelationship', relationship: args.relationship, view_ids: args.view_ids }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'addRelationship', relationship: args.relationship, view_ids: args.view_ids, onConflict: args.onConflict, justification: args.justification }], write), context), write);
   }
 
   if (name === 'updateArchitectureRelationship') {
@@ -2386,7 +2552,7 @@ async function callTool(name, args = {}, dependencies = undefined) {
   if (name === 'addArchitectureView') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'addView', view: args.view }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'addView', view: args.view, onConflict: args.onConflict, justification: args.justification }], write), context), write);
   }
 
   if (name === 'updateArchitectureView') {
@@ -2433,7 +2599,9 @@ async function memorySearchTool(args = {}, dependencies = undefined) {
   const context = await loadContext(args);
   let retrieved;
   try {
-    const journey = await resolveSemanticOperatorJourney(dependencies);
+    const journey = await resolveSemanticOperatorJourney(dependencies, {
+      repositoryRoot: context.workspaceRoot,
+    });
     retrieved = await journey.query({ purpose: 'general', intent: query });
   } catch (error) {
     return {
@@ -2489,6 +2657,119 @@ function memoryHitCard(element, maxDescLen) {
   return card;
 }
 
+// L1 semantic dedup advisory (GraphDeduplication item 3): for each element about
+// to be created, return semantically near elements within a CONTROLLED scope
+// (same ArchiMate type, and - when the add targets views - the union of those
+// views' current members) scoring above a strict threshold. Advisory ONLY: it
+// never rejects or blocks a write; a missing/unavailable semantic backend
+// degrades to an explicit status, never an error.
+const DEFAULT_SEMANTIC_DEDUP_THRESHOLD = 0.85;
+const SEMANTIC_DEDUP_MAX_QUERIES = 3;
+const SEMANTIC_DEDUP_MAX_MATCHES = 5;
+
+function semanticDedupThreshold() {
+  const raw = process.env.ARGO_SEMANTIC_DEDUP_THRESHOLD
+    ?? process.env.ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 && value <= 1 ? value : DEFAULT_SEMANTIC_DEDUP_THRESHOLD;
+}
+
+function collectViewMemberElementIds(document, viewIds) {
+  const ids = new Set();
+  if (!Array.isArray(viewIds) || viewIds.length === 0) {
+    return ids;
+  }
+  const wanted = new Set(viewIds);
+  for (const view of Array.isArray(document && document.views) ? document.views : []) {
+    if (!view || !wanted.has(view.view_id)) {
+      continue;
+    }
+    for (const elementId of Array.isArray(view.included_elements) ? view.included_elements : []) {
+      ids.add(elementId);
+    }
+  }
+  return ids;
+}
+
+async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
+  if (process.env.ARGO_MCP_SEMANTIC_DEDUP === '0') {
+    return undefined;
+  }
+  const addedElements = (Array.isArray(mutations) ? mutations : []).filter(mutation => (
+    mutation
+    && mutation.type === 'addElement'
+    && mutation.element
+    && typeof mutation.element.name === 'string'
+    && mutation.element.name.trim() !== ''
+    && mutation.onConflict !== 'reuse'
+  ));
+  if (addedElements.length === 0) {
+    return undefined;
+  }
+  const threshold = semanticDedupThreshold();
+  let journey;
+  try {
+    journey = await resolveSemanticOperatorJourney(dependencies, {
+      repositoryRoot: context.workspaceRoot,
+    });
+  } catch (error) {
+    return {
+      status: 'unavailable',
+      advisoryOnly: true,
+      threshold,
+      reason: String(error && error.category ? error.category : 'SEMANTIC_DEDUP_UNAVAILABLE'),
+      candidates: [],
+    };
+  }
+  const candidates = [];
+  for (const mutation of addedElements.slice(0, SEMANTIC_DEDUP_MAX_QUERIES)) {
+    const element = mutation.element;
+    const targetMemberIds = collectViewMemberElementIds(context.document, mutation.view_ids);
+    const requested = { id: element.id, name: element.name, type: element.type };
+    try {
+      const intent = [element.type, element.name, element.description]
+        .filter(part => typeof part === 'string' && part.trim() !== '')
+        .join(' ');
+      const retrieved = await journey.query({ purpose: 'general', intent });
+      const source = retrieved && (retrieved.result || retrieved.document) || retrieved;
+      const subset = buildCanonicalSemanticDocumentSubset(source, context.document);
+      const elements = subset && subset.status === 'passed' && subset.document
+        ? (Array.isArray(subset.document.elements) ? subset.document.elements : [])
+        : [];
+      const matches = elements
+        .filter(candidate => candidate && candidate.id !== element.id && typeof candidate.semanticScore === 'number')
+        .filter(candidate => !element.type || candidate.type === element.type)
+        .filter(candidate => candidate.semanticScore >= threshold)
+        .filter(candidate => targetMemberIds.size === 0 || targetMemberIds.has(candidate.id))
+        .sort((left, right) => right.semanticScore - left.semanticScore)
+        .slice(0, SEMANTIC_DEDUP_MAX_MATCHES)
+        .map(candidate => ({
+          id: candidate.id,
+          name: candidate.name,
+          type: candidate.type,
+          score: Number(candidate.semanticScore.toFixed(4)),
+          in_target_views: targetMemberIds.has(candidate.id),
+        }));
+      candidates.push({ requested, matches });
+    } catch (error) {
+      candidates.push({
+        requested,
+        matches: [],
+        status: 'unavailable',
+        reason: String(error && error.category ? error.category : 'SEMANTIC_DEDUP_QUERY_FAILED'),
+      });
+    }
+  }
+  return {
+    status: 'passed',
+    advisoryOnly: true,
+    threshold,
+    scope: 'same type; when view_ids are given, restricted to those views\' current members',
+    candidates,
+    has_suggestions: candidates.some(entry => entry.matches.length > 0),
+  };
+}
+
 async function queryNeo4jGraphTool(args = {}) {
   const architecturePath = args.architecturePath || DEFAULT_GRAPH_PATH;
   const workspaceRoot = resolveWorkspaceRoot(args);
@@ -2585,10 +2866,21 @@ function queryNeo4jGraphSchemaResult(architecturePath, workspaceRoot) {
   });
 }
 
-async function resolveSemanticOperatorJourney(dependencies) {
-  return dependencies && dependencies.semanticOperatorJourney
-    ? dependencies.semanticOperatorJourney
-    : createDefaultProductionSemanticOperatorJourney();
+async function resolveSemanticOperatorJourney(dependencies, options = {}) {
+  if (dependencies && dependencies.semanticOperatorJourney) {
+    return dependencies.semanticOperatorJourney;
+  }
+  // Thread the caller's already-resolved workspace root into the journey: the
+  // no-arg resolveWorkspaceRoot() fallback is process.cwd(), i.e. whatever
+  // directory the host launched this server from (a global ~/.argo installation
+  // started by the host process resolves to that host's cwd, e.g.
+  // C:\Windows\System32), never the workspace the caller asked for.
+  const repositoryRoot = options && typeof options.repositoryRoot === 'string'
+    ? options.repositoryRoot
+    : '';
+  return createDefaultProductionSemanticOperatorJourney(
+    repositoryRoot ? { repositoryRoot } : {},
+  );
 }
 
 async function executeSemanticSystemArchitectureQuery(args, dependencies) {
@@ -3809,6 +4101,7 @@ module.exports = {
   GET_SYSTEM_ARCHITECTURE_OUTPUT_SCHEMA,
   TOOLS,
   applyMutations,
+  buildSemanticDedupAdvisory,
   callTool,
   compactMutationResponse,
   createDefaultCanonicalSemanticInitComposition,

package/package.json

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