archgraph-argo 0.20.10 → 0.22.0

package/argo/rules/archgraph.instructions.md

@@ -23,6 +23,8 @@ Non-negotiable red lines (MUST). Never skip, simplify, or silently violate them;
 7. Retrieve KG-first and semantic-first. See `<QueryPriorityGuideline>`.
 8. Store content KG-first. See `<ContentStoragePolicy>`.
 9. Never duplicate: reuse is the default; a create blocked as an exact or semantic duplicate must be reused, or explicitly overridden with `onConflict: "allowDuplicate"` + justification. See `<GraphDeduplication>`.
+10. Reason critically: challenge the human partner with evidence — your native knowledge, the repository, and the intent graph — instead of agreeing by default; never silently comply with an unsound request. See `<CriticalReasoningGuideline>`.
+11. Never lose content silently: writes that reduce existing content must be lossless (merge/delta) or explicitly acknowledged (`acknowledgeLoss`), and destructive removals are tombstoned. See `<LosslessWrite>`.
 </CoreRules>
 
 <Ontology>
@@ -31,6 +33,15 @@ Your architecture is ArchiMate 3.2 plus ARGO extensions. Reference files live un
 2. Element/relationship type definitions: ~/.argo/schema/archimate3.2.md
 </Ontology>
 
+<CriticalReasoningGuideline>
+Be a critical peer, not a compliant assistant: your duty is to the evidence, not to the human partner's preferences. Do not be sycophantic.
+1. Evaluate before agreeing: never accept a question's premise, a request, or a proposal just because the human asserts it. First check it against evidence from three sources — your native model knowledge, the repository (code, docs, tests, history), and the intent graph. Endorsement without evidence is a failure.
+2. Challenge with evidence: when the evidence contradicts the human, say so plainly and cite it (a file path + line/commit, a graph element id, or a named fact), then offer the corrected alternative. Say what evidence would change your mind, so the challenge is falsifiable.
+3. Separate facts from preferences: facts (correctness, behavior, constraints, feasibility) are decided by evidence and MUST be contested when wrong; preferences (taste, priority, scope, risk appetite) belong to the human — accept them and state the trade-off instead of dressing a preference up as a fact.
+4. Do not cave to pressure: revise a conclusion only for new evidence or a better argument — never for repetition, tone, urgency, or authority. Agreeing to please is a defect, not politeness.
+5. Refuse the wrong part, offer the right path: when a request conflicts with evidence or a CoreRule, neither silently comply nor merely refuse — name the conflict with evidence and propose the compliant alternative.
+</CriticalReasoningGuideline>
+
 <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.
@@ -62,6 +73,14 @@ Never add what the graph already has. Reuse is the default; there is no reject m
 5. Updates are never gated. Never work around a duplicate by editing around it — reuse or update the existing object.
 </GraphDeduplication>
 
+<LosslessWrite>
+Never lose stored content silently. A write must never reduce existing content unless it is lossless (merge/delta) or you explicitly acknowledge the reduction; omission never means deletion.
+1. Structured fields merge: element testcases merge by `name`; view membership accepts a delta `{ add, remove }`; relationship attributes merge by `name`. Omitting an existing entry preserves it. Delete only with an explicit `op: "remove"` or an explicit delta remove.
+2. Scalar text is guarded: `description`, `statement`, `document`, `name`, `view_name` are full-value fields. A *reworded* line is not a loss; dropping prior lines, or losing structured tokens (ids, numbers, commit hashes, paths), is blocked unless you pass `acknowledgeLoss: true` (and `lossJustification` when the loss is major). Read the current value first and edit as a minimal diff.
+3. Destructive removals (`removeElement` / `removeRelationship` / `removeView`) require `acknowledgeLoss: true` — per mutation, or once for the whole set via the top-level `acknowledgeLoss` on `applySystemArchitectureMutation`; the full removed object is appended to the NDJSON tombstone ledger `design/KG/SystemArchitecture.tombstones.ndjson` (rotated by size) for recovery.
+4. Always read the `lossless` loss report in the response (preview and apply). It lists removed text lines / testcases / members / objects. If it is blocked, fix the mutation—do not retry blindly and do not disable the gate.
+</LosslessWrite>
+
 <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.

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

@@ -291,6 +291,29 @@ for (const tool of TOOLS) {
   }
 }
 
+// Lossless write gate acknowledgement params for the update/remove helpers
+// (see lossless-write-gate.js). add* is purely additive and left alone.
+const LOSS_ACK_INPUT_PROPS = Object.freeze({
+  acknowledgeLoss: {
+    type: 'boolean',
+    description: 'Set true to confirm an intentional content reduction: a text rewrite that drops prior segments, or a destructive removal. Without it the lossless write gate blocks the write and returns the exact removed content.',
+  },
+  lossJustification: {
+    type: 'string',
+    description: 'Required for MAJOR text loss (large removedChars or most of the value): the reason the prior content is being intentionally replaced.',
+  },
+});
+for (const tool of TOOLS) {
+  if (tool && tool.name && /^(update|remove)Architecture/.test(tool.name)
+    && tool.inputSchema && tool.inputSchema.properties) {
+    for (const [key, value] of Object.entries(LOSS_ACK_INPUT_PROPS)) {
+      if (!Object.prototype.hasOwnProperty.call(tool.inputSchema.properties, key)) {
+        tool.inputSchema.properties[key] = value;
+      }
+    }
+  }
+}
+
 function intentElementContextInputSchema() {
   return {
     type: 'object',
@@ -318,6 +341,8 @@ function mutationInputSchema() {
     required: ['mutations'],
     properties: {
       architecturePath: { type: 'string', description: 'Default: design/KG/SystemArchitecture.json' },
+      acknowledgeLoss: { type: 'boolean', description: 'Batch-level loss acknowledgement: set true to confirm every intentional content reduction in this mutation set (a text rewrite that drops prior segments, or destructive removals). Counts for all mutations — one confirmation for a whole batch.' },
+      lossJustification: { type: 'string', description: 'Batch-level justification for MAJOR text loss in this mutation set.' },
       mutations: {
         type: 'array',
         minItems: 1,
@@ -348,6 +373,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' } },
+            acknowledgeLoss: { type: 'boolean', description: 'Set true to confirm an intentional content reduction: a text rewrite that drops prior segments, or a destructive removal. Without it the lossless write gate blocks the write and returns the exact removed content.' },
+            lossJustification: { type: 'string', description: 'Required for MAJOR text loss (large removedChars or most of the value): the reason the prior content is being intentionally replaced.' },
           },
           additionalProperties: false,
         },

package/argo/scripts/lossless-write-gate.js

@@ -0,0 +1,474 @@
+'use strict';
+
+/**
+ * Lossless Write Gate (无损写入门禁), framework-level.
+ *
+ * Invariant: NO SILENT LOSS. A write must never reduce stored content unless the
+ * caller explicitly acknowledges it (and, for major loss, justifies it). Two
+ * mechanisms make this possible:
+ *
+ *   G1 structured fields MERGE (omission never means deletion): updateElement
+ *      .testcases (by name), updateRelationship .attributes (by name),
+ *      updateView membership (delta {add,remove}); explicit op:'remove' deletes.
+ *   G2 scalar text GUARDED: description / statement / document / name / view_name
+ *      are full-value fields; a value that drops prior segments is blocked unless
+ *      the mutation carries acknowledgeLoss:true (and lossJustification for major
+ *      loss). Pure additions/expansions are always allowed.
+ *   G3 destructive removals ACKNOWLEDGED + RECOVERABLE: removeElement /
+ *      removeRelationship / removeView require acknowledgeLoss:true and snapshot
+ *      the full removed object into a tombstone ledger (nothing is truly lost).
+ *   G5 every response carries a loss report (text/testcases/members/objects +
+ *      the removed samples), on preview as well as apply.
+ *
+ * The gate is enforced at the single funnel buildMutationResult (apply +
+ * preview + all single-object helpers), so every MCP write interface is covered.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOSS_ACK_FIELD = 'acknowledgeLoss';
+const LOSS_JUSTIFICATION_FIELD = 'lossJustification';
+
+// A text loss is "major" (justification, not just acknowledgement, required)
+// when it removes this many characters or this share of the original text.
+const MAJOR_REMOVED_CHARS = 200;
+const MAJOR_REMOVED_RATIO = 0.5;
+
+// A changed segment is a "modification" (not a loss) when its token overlap with
+// some new segment is at least this high — "reworded, not dropped".
+const MODIFICATION_SIMILARITY = 0.5;
+
+// Tokens that carry structured identity (ids, numbers, hashes, paths): if one is
+// gone it is always a loss, even when the surrounding sentence was only reworded.
+const TOKEN_RE = /[A-Za-z0-9_@#./\\:-]+|[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/g;
+
+// Full-value text fields per mutation type. Editing any of these can silently
+// drop prior content, so they are loss-guarded.
+const TEXT_FIELDS_BY_MUTATION = Object.freeze({
+  updateElement: Object.freeze(['description', 'name']),
+  updateRelationship: Object.freeze(['statement', 'name', 'description', 'document']),
+  updateView: Object.freeze(['view_name', 'description']),
+});
+
+function normalizeForCompare(value) {
+  return String(value === undefined || value === null ? '' : value)
+    .normalize('NFKC')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function normalizeSegments(text) {
+  return String(text === undefined || text === null ? '' : text)
+    .split(/\r?\n/)
+    .map(normalizeForCompare)
+    .filter(segment => segment.length > 0);
+}
+
+function tokenize(segment) {
+  const matches = String(segment === undefined || segment === null ? '' : segment).match(TOKEN_RE);
+  return matches ? matches.map(token => token.toLowerCase()) : [];
+}
+
+function isStructuredToken(token) {
+  return /[0-9]/.test(token) || /[/\\]/.test(token) || /^[0-9a-f]{7,40}$/i.test(token);
+}
+
+// Sørensen–Dice coefficient over token sets (deterministic, no network).
+function diceCoefficient(aTokens, bTokens) {
+  if (aTokens.length === 0 && bTokens.length === 0) return 1;
+  if (aTokens.length === 0 || bTokens.length === 0) return 0;
+  const a = new Set(aTokens);
+  const b = new Set(bTokens);
+  let intersection = 0;
+  for (const token of a) if (b.has(token)) intersection += 1;
+  return (2 * intersection) / (a.size + b.size);
+}
+
+// Deterministic loss detector. A changed segment is classified as a MODIFICATION
+// (kept, just reworded) when it is similar enough to some new segment; otherwise
+// it is a LOSS (dropped or substantially rewritten). Structured tokens (ids,
+// numbers, hashes, paths) that disappear are always a loss. Pure additions and
+// reorderings report nothing.
+function detectTextLoss(oldText, newText) {
+  const oldSegments = normalizeSegments(oldText);
+  if (oldSegments.length === 0) {
+    return { removedSegments: [], modifiedSegments: [], removedChars: 0, oldChars: 0, ratio: 0, structuredTokensRemoved: [] };
+  }
+  const newSegments = normalizeSegments(newText);
+  const newNormalized = normalizeForCompare(newText);
+  const newTokenSet = new Set(newSegments.flatMap(tokenize));
+  const newSegmentTokens = newSegments.map(tokenize);
+  const removedSegments = [];
+  const modifiedSegments = [];
+  const structuredTokensRemoved = [];
+  for (const segment of oldSegments) {
+    const segmentTokens = tokenize(segment);
+    for (const token of segmentTokens) {
+      if (isStructuredToken(token) && !newTokenSet.has(token)) structuredTokensRemoved.push(token);
+    }
+    if (newNormalized.includes(segment)) continue; // kept verbatim
+    const best = newSegmentTokens.reduce((max, tokens) => Math.max(max, diceCoefficient(segmentTokens, tokens)), 0);
+    if (best >= MODIFICATION_SIMILARITY) modifiedSegments.push(segment);
+    else removedSegments.push(segment);
+  }
+  const removedChars = removedSegments.reduce((sum, segment) => sum + segment.length, 0);
+  const oldChars = oldSegments.reduce((sum, segment) => sum + segment.length, 0);
+  return {
+    removedSegments,
+    modifiedSegments,
+    removedChars,
+    oldChars,
+    ratio: oldChars > 0 ? removedChars / oldChars : 0,
+    structuredTokensRemoved: [...new Set(structuredTokensRemoved)],
+  };
+}
+
+// G1: merge testcases by their stable key (name). Untouched testcases survive;
+// only an explicit {name, op:'remove'} deletes one.
+function mergeTestcasesPatch(existing, patchEntries) {
+  if (!Array.isArray(patchEntries)) {
+    throw new Error('patch.testcases must be an array of { name, ... } entries');
+  }
+  const result = Array.isArray(existing) ? existing.map(entry => ({ ...entry })) : [];
+  for (const entry of patchEntries) {
+    if (!entry || typeof entry !== 'object' || typeof entry.name !== 'string' || entry.name.trim() === '') {
+      throw new Error('patch.testcases entries must have a non-empty string name (the stable merge key)');
+    }
+    const index = result.findIndex(existingEntry => existingEntry.name === entry.name);
+    if (entry.op === 'remove') {
+      if (index >= 0) result.splice(index, 1);
+      continue;
+    }
+    const next = { ...entry };
+    delete next.op;
+    if (index >= 0) result[index] = next;
+    else result.push(next);
+  }
+  return result;
+}
+
+// G1: merge relationship attributes by name ({ name, description }). Unmentioned
+// attributes survive; op:'remove' deletes by name.
+function mergeRelationshipAttributesPatch(existing, patchEntries) {
+  if (!Array.isArray(patchEntries)) {
+    throw new Error('patch.attributes must be an array of { name, ... } entries');
+  }
+  const result = Array.isArray(existing) ? existing.map(entry => ({ ...entry })) : [];
+  for (const entry of patchEntries) {
+    if (!entry || typeof entry !== 'object' || typeof entry.name !== 'string' || entry.name.trim() === '') {
+      throw new Error('patch.attributes entries must have a non-empty string name');
+    }
+    const index = result.findIndex(attr => attr.name === entry.name);
+    if (entry.op === 'remove') {
+      if (index >= 0) result.splice(index, 1);
+      continue;
+    }
+    const next = { name: entry.name };
+    for (const field of ['value', 'description', 'content']) {
+      if (Object.prototype.hasOwnProperty.call(entry, field)) next[field] = entry[field];
+    }
+    if (index >= 0) result[index] = next;
+    else result.push(next);
+  }
+  return result;
+}
+
+// G1: apply a view membership patch as either a full list (legacy replace) or a
+// lossless delta { add, remove }. Returns the resulting list.
+function applyViewMembershipPatch(current, patchValue) {
+  const base = Array.isArray(current) ? current : [];
+  if (Array.isArray(patchValue)) {
+    return { list: dedupe(patchValue), explicitRemove: null };
+  }
+  if (patchValue && typeof patchValue === 'object') {
+    const remove = Array.isArray(patchValue.remove) ? patchValue.remove : [];
+    const add = Array.isArray(patchValue.add) ? patchValue.add : [];
+    const kept = base.filter(id => !remove.includes(id));
+    return { list: dedupe([...kept, ...add]), explicitRemove: remove };
+  }
+  throw new Error('view membership patch must be an array or { add, remove }');
+}
+
+function dedupe(entries) {
+  const seen = new Set();
+  const result = [];
+  for (const entry of entries) {
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    result.push(entry);
+  }
+  return result;
+}
+
+function findById(entries, id) {
+  return Array.isArray(entries) ? entries.find(entry => entry && entry.id === id) : undefined;
+}
+
+function findView(views, viewId) {
+  return Array.isArray(views) ? views.find(view => view && view.view_id === viewId) : undefined;
+}
+
+function isAcknowledged(mutation, lossAck) {
+  return (Boolean(mutation) && mutation[LOSS_ACK_FIELD] === true)
+    || (Boolean(lossAck) && lossAck[LOSS_ACK_FIELD] === true);
+}
+
+function hasJustification(mutation, lossAck) {
+  const text = (mutation && mutation[LOSS_JUSTIFICATION_FIELD])
+    || (lossAck && lossAck[LOSS_JUSTIFICATION_FIELD]);
+  return typeof text === 'string' && text.trim() !== '';
+}
+
+// G5+enforcement: compute every content reduction a mutation set would cause,
+// with per-item acknowledgement state, and whether the set must be blocked.
+// `lossAck` is an optional batch-level acknowledgement (applySystemArchitectureMutation
+// top level) that counts for every mutation in the set.
+function buildLossReport({ baseDocument, mutations, nextDocument, lossAck }) {
+  const base = baseDocument || {};
+  const next = nextDocument || {};
+  const report = {
+    blocked: false,
+    acknowledged: true,
+    reasons: [],
+    text: [],
+    modifications: [],
+    membersRemoved: [],
+    testcasesRemoved: [],
+    attributesRemoved: [],
+    objectsRemoved: [],
+  };
+
+  const pushReason = (reason) => {
+    report.blocked = true;
+    report.acknowledged = false;
+    if (!report.reasons.includes(reason)) report.reasons.push(reason);
+  };
+
+  const guardText = (mutation, kind, id, field, oldValue, newValue) => {
+    const loss = detectTextLoss(oldValue, newValue);
+    if (loss.modifiedSegments.length > 0) {
+      // Reworded, not dropped: reported for transparency, never blocked.
+      report.modifications.push({ kind, id, field, modifiedLines: loss.modifiedSegments.length, sample: loss.modifiedSegments.slice(0, 3) });
+    }
+    const hasLoss = loss.removedSegments.length > 0 || loss.structuredTokensRemoved.length > 0;
+    if (!hasLoss) return;
+    // "Major" only when the removed volume is substantial; a large share of a
+    // tiny value is not major (avoids forcing justification for short edits).
+    const major = loss.removedChars > MAJOR_REMOVED_CHARS
+      || (loss.oldChars > MAJOR_REMOVED_CHARS && loss.ratio > MAJOR_REMOVED_RATIO);
+    const acknowledged = isAcknowledged(mutation, lossAck) && (!major || hasJustification(mutation, lossAck));
+    const item = {
+      kind,
+      id,
+      field,
+      removedChars: loss.removedChars,
+      removedLines: loss.removedSegments.length,
+      structuredTokensRemoved: loss.structuredTokensRemoved,
+      ratio: Number(loss.ratio.toFixed(3)),
+      major,
+      acknowledged,
+      removedSample: loss.removedSegments.slice(0, 3),
+    };
+    report.text.push(item);
+    if (!acknowledged) {
+      const why = major && !hasJustification(mutation, lossAck)
+        ? ' (major loss requires a non-empty lossJustification)'
+        : '';
+      const structured = loss.structuredTokensRemoved.length > 0
+        ? ` [structured tokens removed: ${loss.structuredTokensRemoved.slice(0, 5).join(', ')}]`
+        : '';
+      pushReason(
+        `Unacknowledged text loss: ${kind} '${id}' field '${field}' would remove ${loss.removedChars} char(s) / ${loss.removedSegments.length} line(s)${structured}${why}. `
+        + 'Read the current value first, then pass acknowledgeLoss:true (and lossJustification) to confirm an intentional rewrite, or use an additive edit that keeps the prior content.',
+      );
+    }
+  };
+
+  for (const mutation of mutations || []) {
+    if (mutation.type === 'updateElement' || mutation.type === 'updateRelationship') {
+      const collection = mutation.type === 'updateElement' ? 'elements' : 'relationships';
+      const kind = mutation.type === 'updateElement' ? 'element' : 'relationship';
+      const baseEntry = findById(base[collection], mutation.id);
+      const nextEntry = findById(next[collection], mutation.id);
+      if (!baseEntry || !nextEntry) continue;
+      for (const field of TEXT_FIELDS_BY_MUTATION[mutation.type]) {
+        guardText(mutation, kind, mutation.id, field, baseEntry[field], nextEntry[field]);
+      }
+      if (mutation.type === 'updateElement' && Array.isArray(baseEntry.testcases)) {
+        const nextNames = new Set((nextEntry.testcases || []).map(tc => tc && tc.name));
+        for (const tc of baseEntry.testcases) {
+          if (tc && tc.name && !nextNames.has(tc.name)) {
+            report.testcasesRemoved.push({ id: mutation.id, name: tc.name });
+          }
+        }
+      }
+    } else if (mutation.type === 'updateView') {
+      const viewId = mutation.view_id || mutation.id;
+      const baseView = findView(base.views, viewId);
+      const nextView = findView(next.views, viewId);
+      if (!baseView || !nextView) continue;
+      for (const field of TEXT_FIELDS_BY_MUTATION.updateView) {
+        guardText(mutation, 'view', viewId, field, baseView[field], nextView[field]);
+      }
+      const baseElements = new Set(baseView.included_elements || []);
+      const removedElements = [...baseElements].filter(id => !(nextView.included_elements || []).includes(id));
+      const baseRelationships = new Set(baseView.included_relationships || []);
+      const removedRelationships = [...baseRelationships].filter(id => !(nextView.included_relationships || []).includes(id));
+      if (removedElements.length > 0 || removedRelationships.length > 0) {
+        // A channel with no removals is trivially covered; a channel with removals
+        // is explicit only when patched via the delta { remove } form.
+        const elementsExplicit = removedElements.length === 0
+          || isExplicitRemovePatch(mutation.patch, 'included_elements');
+        const relationshipsExplicit = removedRelationships.length === 0
+          || isExplicitRemovePatch(mutation.patch, 'included_relationships');
+        const explicit = elementsExplicit && relationshipsExplicit;
+        const acknowledged = explicit || isAcknowledged(mutation, lossAck);
+        report.membersRemoved.push({
+          view_id: viewId,
+          elements: removedElements,
+          relationships: removedRelationships,
+          explicit,
+          acknowledged,
+        });
+        if (!acknowledged) {
+          pushReason(
+            `Unacknowledged membership removal in view '${viewId}': ${removedElements.length} element(s) and ${removedRelationships.length} relationship(s) would be dropped. `
+            + 'Use the delta form included_elements:{remove:[...]} for explicit removal, or pass acknowledgeLoss:true.',
+          );
+        }
+      }
+    } else if (mutation.type === 'removeElement' || mutation.type === 'removeRelationship' || mutation.type === 'removeView') {
+      const spec = {
+        removeElement: { collection: 'elements', id: mutation.id },
+        removeRelationship: { collection: 'relationships', id: mutation.id },
+        removeView: { collection: 'views', id: mutation.view_id },
+      }[mutation.type];
+      const id = spec.id;
+      const baseEntry = mutation.type === 'removeView'
+        ? findView(base.views, id)
+        : findById(base[spec.collection], id);
+      const stillPresent = mutation.type === 'removeView'
+        ? Boolean(findView(next.views, id))
+        : Boolean(findById(next[spec.collection], id));
+      if (!baseEntry || stillPresent) continue;
+      const acknowledged = isAcknowledged(mutation, lossAck);
+      report.objectsRemoved.push({
+        kind: mutation.type.replace(/^remove/, '').toLowerCase(),
+        id,
+        name: baseEntry.name || baseEntry.view_name,
+        acknowledged,
+      });
+      if (!acknowledged) {
+        pushReason(
+          `Unacknowledged destructive removal: ${mutation.type} '${id}' ('${baseEntry.name || baseEntry.view_name}') deletes the object permanently. `
+          + 'Pass acknowledgeLoss:true (a full tombstone snapshot is recorded for recovery).',
+        );
+      }
+    }
+  }
+
+  return report;
+}
+
+function isExplicitRemovePatch(patch, field) {
+  if (!patch || !Object.prototype.hasOwnProperty.call(patch, field)) return false;
+  const value = patch[field];
+  return Boolean(value) && !Array.isArray(value) && typeof value === 'object' && Array.isArray(value.remove);
+}
+
+// G3: append full removed objects to an NDJSON tombstone ledger. Each append is a
+// single O(1) line write (no read/rewrite of prior content). When the active file
+// exceeds the size cap (~5k entries) it is rotated aside (rename, O(1)) so the
+// active file and its git diff stay bounded.
+const TOMBSTONE_ACTIVE_BASENAME = 'SystemArchitecture.tombstones.ndjson';
+const TOMBSTONE_ROTATE_BYTES = 2 * 1024 * 1024;
+
+function tombstoneFilePath(graphAbsolutePath) {
+  return path.join(path.dirname(graphAbsolutePath), TOMBSTONE_ACTIVE_BASENAME);
+}
+
+function appendTombstones(graphAbsolutePath, entries, options = {}) {
+  const file = tombstoneFilePath(graphAbsolutePath);
+  const rotateBytes = Number.isFinite(options.rotateBytes) ? options.rotateBytes : TOMBSTONE_ROTATE_BYTES;
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length === 0) return { path: file, count: 0, rotatedTo: null };
+  let rotatedTo = null;
+  try {
+    if (rotateBytes > 0 && fs.statSync(file).size >= rotateBytes) {
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+      rotatedTo = path.join(path.dirname(file), `SystemArchitecture.tombstones.${stamp}.ndjson`);
+      fs.renameSync(file, rotatedTo);
+    }
+  } catch {
+    // No active file yet (first append) — nothing to rotate.
+  }
+  const at = new Date().toISOString();
+  const lines = list.map(entry => JSON.stringify({
+    at,
+    op: entry.op || ('remove' + entry.kind),
+    kind: entry.kind,
+    id: entry.id,
+    object: entry.object,
+  }));
+  fs.appendFileSync(file, `${lines.join('\n')}\n`, 'utf8');
+  return { path: file, count: list.length, rotatedTo };
+}
+
+// Read back the NDJSON tombstone ledger (recovery / audit). Malformed lines are
+// skipped rather than throwing, so a partially written tail never blocks reads.
+function readTombstones(file) {
+  try {
+    return fs.readFileSync(file, 'utf8')
+      .split(/\r?\n/)
+      .filter(line => line.trim() !== '')
+      .map(line => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// Collect the full base objects for every global removal in a mutation set.
+function collectRemovedObjects(baseDocument, mutations, nextDocument) {
+  const removed = [];
+  for (const mutation of mutations || []) {
+    if (mutation.type === 'removeElement') {
+      const obj = findById((baseDocument || {}).elements, mutation.id);
+      if (obj && !findById((nextDocument || {}).elements, mutation.id)) removed.push({ op: mutation.type, kind: 'element', id: mutation.id, object: obj });
+    } else if (mutation.type === 'removeRelationship') {
+      const obj = findById((baseDocument || {}).relationships, mutation.id);
+      if (obj && !findById((nextDocument || {}).relationships, mutation.id)) removed.push({ op: mutation.type, kind: 'relationship', id: mutation.id, object: obj });
+    } else if (mutation.type === 'removeView') {
+      const obj = findView((baseDocument || {}).views, mutation.view_id);
+      if (obj && !findView((nextDocument || {}).views, mutation.view_id)) removed.push({ op: mutation.type, kind: 'view', id: mutation.view_id, object: obj });
+    }
+  }
+  return removed;
+}
+
+module.exports = {
+  LOSS_ACK_FIELD,
+  LOSS_JUSTIFICATION_FIELD,
+  MAJOR_REMOVED_CHARS,
+  MAJOR_REMOVED_RATIO,
+  TEXT_FIELDS_BY_MUTATION,
+  normalizeSegments,
+  detectTextLoss,
+  mergeTestcasesPatch,
+  mergeRelationshipAttributesPatch,
+  applyViewMembershipPatch,
+  buildLossReport,
+  appendTombstones,
+  readTombstones,
+  tombstoneFilePath,
+  TOMBSTONE_ACTIVE_BASENAME,
+  TOMBSTONE_ROTATE_BYTES,
+  collectRemovedObjects,
+};

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

@@ -167,6 +167,8 @@ const {
   verifyArchitectureSync,
 } = require('./neo4j-system-architecture-store.js');
 
+const losslessWriteGate = require('./lossless-write-gate.js');
+
 const HANDLED_MUTATION_TYPES = new Set([
   'addElement',
   'updateElement',
@@ -413,11 +415,32 @@ const WORKSPACE_ROOT_PARAM = Object.freeze({
   description:
     'Optional absolute workspace root for this call. When provided it is used as-is; otherwise the server launch directory is used.',
 });
+// Lossless write gate: every update/remove helper accepts an explicit loss
+// acknowledgement (see lossless-write-gate.js). add* is purely additive and is
+// left alone. Without the acknowledgement a shrinking text edit or a destructive
+// removal is blocked at the buildMutationResult funnel.
+const LOSS_ACK_INPUT_PROPS = Object.freeze({
+  acknowledgeLoss: {
+    type: 'boolean',
+    description: 'Set true to confirm an intentional content reduction: a text rewrite that drops prior segments, or a destructive removal. Without it the lossless write gate blocks the write and returns the exact removed content.',
+  },
+  lossJustification: {
+    type: 'string',
+    description: 'Required for MAJOR text loss (large removedChars or most of the value): the reason the prior content is being intentionally replaced.',
+  },
+});
+
 for (const tool of TOOLS) {
   const inputSchema = tool && tool.inputSchema;
-  if (inputSchema && inputSchema.type === 'object' && inputSchema.properties) {
-    if (!Object.prototype.hasOwnProperty.call(inputSchema.properties, 'workspaceRoot')) {
-      inputSchema.properties.workspaceRoot = WORKSPACE_ROOT_PARAM;
+  if (!inputSchema || inputSchema.type !== 'object' || !inputSchema.properties) continue;
+  if (!Object.prototype.hasOwnProperty.call(inputSchema.properties, 'workspaceRoot')) {
+    inputSchema.properties.workspaceRoot = WORKSPACE_ROOT_PARAM;
+  }
+  if (tool.name && /^(update|remove)Architecture/.test(tool.name)) {
+    for (const [key, value] of Object.entries(LOSS_ACK_INPUT_PROPS)) {
+      if (!Object.prototype.hasOwnProperty.call(inputSchema.properties, key)) {
+        inputSchema.properties[key] = value;
+      }
     }
   }
 }
@@ -464,6 +487,8 @@ function mutationInputSchema() {
     required: ['mutations'],
     properties: {
       architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
+      acknowledgeLoss: { type: 'boolean', description: 'Batch-level loss acknowledgement: set true to confirm every intentional content reduction in this mutation set (a text rewrite that drops prior segments, or destructive removals). Counts for all mutations — one confirmation for a whole batch.' },
+      lossJustification: { type: 'string', description: 'Batch-level justification for MAJOR text loss in this mutation set.' },
       mutations: {
         type: 'array',
         minItems: 1,
@@ -483,6 +508,8 @@ function mutationInputSchema() {
             relationship_ids: { type: 'array', items: { type: 'string' } },
             onConflict: { type: 'string', enum: ['reuse', 'allowDuplicate'], description: 'Dedup policy for add* mutations. reuse (default): find-or-create — attach an existing exact-natural-key match instead of creating a duplicate; a same-type semantic near-duplicate also blocks creation unless allowDuplicate is set. allowDuplicate: create a new object even if a duplicate exists, 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.' },
+            acknowledgeLoss: { type: 'boolean', description: 'Set true to confirm an intentional content reduction: a text rewrite that drops prior segments, or a destructive removal. Without it the lossless write gate blocks the write and returns the exact removed content.' },
+            lossJustification: { type: 'string', description: 'Required for MAJOR text loss (large removedChars or most of the value): the reason the prior content is being intentionally replaced.' },
           },
           additionalProperties: false,
         },
@@ -1248,7 +1275,7 @@ function resolveDuplicateConflict(options, candidates) {
   return { action: 'create', justification: options.justification };
 }
 
-function applyMutations(document, mutations) {
+function applyMutations(document, mutations, options = {}) {
   const nextDocument = clone(document);
   const touchedElementIds = new Set();
   const touchedRelationshipIds = new Set();
@@ -1323,6 +1350,14 @@ function applyMutations(document, mutations) {
           patch.attributes,
         );
       }
+      if (Array.isArray(patch.testcases)) {
+        // G1: merge testcases by name so an omitted testcase is preserved; only
+        // an explicit { name, op:'remove' } deletes one.
+        patch.testcases = losslessWriteGate.mergeTestcasesPatch(
+          Array.isArray(element.testcases) ? element.testcases : [],
+          patch.testcases,
+        );
+      }
       Object.assign(element, patch);
       if (patchesSubdiagramViews || patchesName) {
         reconcileSubdiagramViewsForElement(nextDocument, element);
@@ -1440,7 +1475,15 @@ function applyMutations(document, mutations) {
       requirePatchDoesNotChangeRelationshipIdentityOrType(mutation.id, mutation.patch);
       const oldSourceId = relationship.source_id;
       const oldTargetId = relationship.target_id;
-      Object.assign(relationship, clone(mutation.patch));
+      const relationshipPatch = clone(mutation.patch);
+      if (Array.isArray(relationshipPatch.attributes)) {
+        // G1: merge relationship attributes by name (unmentioned preserved).
+        relationshipPatch.attributes = losslessWriteGate.mergeRelationshipAttributesPatch(
+          Array.isArray(relationship.attributes) ? relationship.attributes : [],
+          relationshipPatch.attributes,
+        );
+      }
+      Object.assign(relationship, relationshipPatch);
       for (const view of nextDocument.views) {
         if (!(view.included_relationships || []).includes(relationship.id)) {
           continue;
@@ -1547,11 +1590,12 @@ function applyMutations(document, mutations) {
       const oldParentId = view.parent_element_id;
       const oldViewId = view.view_id;
       const patch = clone(mutation.patch);
-      if (Array.isArray(patch.included_elements)) {
-        patch.included_elements = addUnique([], patch.included_elements);
+      if (Object.prototype.hasOwnProperty.call(patch, 'included_elements')) {
+        // G1: full list (legacy replace) or lossless delta { add, remove }.
+        patch.included_elements = losslessWriteGate.applyViewMembershipPatch(view.included_elements || [], patch.included_elements).list;
       }
-      if (Array.isArray(patch.included_relationships)) {
-        patch.included_relationships = addUnique([], patch.included_relationships);
+      if (Object.prototype.hasOwnProperty.call(patch, 'included_relationships')) {
+        patch.included_relationships = losslessWriteGate.applyViewMembershipPatch(view.included_relationships || [], patch.included_relationships).list;
       }
       Object.assign(view, patch);
       if (oldParentId !== view.parent_element_id) {
@@ -1588,6 +1632,12 @@ function applyMutations(document, mutations) {
     touchedViewIds: Array.from(touchedViewIds),
     viewLimitCheckIds: Array.from(viewLimitCheckIds),
     mutationSummaries,
+    lossReport: losslessWriteGate.buildLossReport({
+      baseDocument: document,
+      mutations,
+      nextDocument,
+      lossAck: options.lossAck,
+    }),
   };
 }
 
@@ -1768,12 +1818,12 @@ function removeEntries(existing, removals) {
   return (Array.isArray(existing) ? existing : []).filter(entry => !removalSet.has(entry));
 }
 
-async function buildMutationResult(context, mutations, write, dependencies) {
+async function buildMutationResult(context, mutations, write, dependencies, lossAck) {
   markPhase('mutation:' + (write ? 'apply' : 'preview'));
   const beforeSummary = summarizeDocument(context.document);
   let mutationResult;
   try {
-    mutationResult = applyMutations(context.document, mutations);
+    mutationResult = applyMutations(context.document, mutations, { lossAck });
   } catch (error) {
     const errors = [String(error && error.message ? error.message : error)];
     const failed = {
@@ -1846,13 +1896,52 @@ async function buildMutationResult(context, mutations, write, dependencies) {
     }
   }
 
-  if (errors.length > 0 || semanticBlocked || !write) {
+  // Lossless write gate: block any unacknowledged content reduction (text shrink,
+  // membership drop, destructive removal). Preview reports it too (status failed)
+  // so the loss is visible before writing.
+  const lossReport = mutationResult.lossReport;
+  const hasLoss = lossReport && (
+    lossReport.text.length > 0
+    || lossReport.membersRemoved.length > 0
+    || lossReport.objectsRemoved.length > 0
+    || lossReport.testcasesRemoved.length > 0
+  );
+  let losslessBlocked = false;
+  if (hasLoss) {
+    result.lossless = lossReport;
+    if (errors.length === 0 && lossReport.blocked) {
+      losslessBlocked = true;
+      result.status = 'failed';
+      result.after = beforeSummary;
+      result.errors = lossReport.reasons;
+      result.guidance = addUnique(result.guidance || [], [
+        ...lossReport.reasons,
+        'Lossless write gate: read the current value first. For an intentional text rewrite pass acknowledgeLoss:true (and lossJustification for major loss); for a destructive removal pass acknowledgeLoss:true (a tombstone snapshot is recorded). Prefer lossless forms: testcases merge by name, view membership delta { add, remove }.',
+      ]);
+    }
+  }
+
+  if (errors.length > 0 || semanticBlocked || losslessBlocked || !write) {
     return result;
   }
 
   writeGraph(context.graphPath.absolutePath, mutationResult.document);
   result.written = true;
 
+  {
+    const removedObjects = losslessWriteGate.collectRemovedObjects(context.document, mutations, mutationResult.document);
+    if (removedObjects.length > 0) {
+      try {
+        const tomb = losslessWriteGate.appendTombstones(context.graphPath.absolutePath, removedObjects);
+        result.tombstones = { status: 'passed', path: tomb.path, count: tomb.count };
+      } catch (error) {
+        const message = String(error && error.message ? error.message : error);
+        result.tombstones = { status: 'failed', error: message };
+        result.warnings = addUnique(result.warnings || [], ['tombstone snapshot failed (non-fatal): ' + message]);
+      }
+    }
+  }
+
   // WP2791: .qea projection parallel to the Neo4j trigger — non-fatal, best-effort,
   // but ALWAYS reported on the result (passed / failed / noop+reason) so a missing EA
   // update is never silent.
@@ -2543,12 +2632,12 @@ async function callTool(name, args = {}, dependencies = undefined) {
 
   if (name === 'previewSystemArchitectureMutation') {
     const context = await loadContext(args);
-    return toolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, false, dependencies), context));
+    return toolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, false, dependencies, { acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }), context));
   }
 
   if (name === 'applySystemArchitectureMutation') {
     const context = await loadContext(args);
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, true, dependencies), context), true);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, args.mutations, true, dependencies, { acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }), context), true);
   }
 
   if (name === 'addArchitectureElement') {
@@ -2560,13 +2649,13 @@ async function callTool(name, args = {}, dependencies = undefined) {
   if (name === 'updateArchitectureElement') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'updateElement', id: args.id, patch: args.patch }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'updateElement', id: args.id, patch: args.patch, acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }], write), context), write);
   }
 
   if (name === 'removeArchitectureElement') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeElement', id: args.id, view_ids: args.view_ids }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeElement', id: args.id, view_ids: args.view_ids, acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }], write), context), write);
   }
 
   if (name === 'addArchitectureRelationship') {
@@ -2578,13 +2667,13 @@ async function callTool(name, args = {}, dependencies = undefined) {
   if (name === 'updateArchitectureRelationship') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'updateRelationship', id: args.id, patch: args.patch }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'updateRelationship', id: args.id, patch: args.patch, acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }], write), context), write);
   }
 
   if (name === 'removeArchitectureRelationship') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeRelationship', id: args.id, view_ids: args.view_ids }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeRelationship', id: args.id, view_ids: args.view_ids, acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }], write), context), write);
   }
 
   if (name === 'addArchitectureView') {
@@ -2596,13 +2685,13 @@ async function callTool(name, args = {}, dependencies = undefined) {
   if (name === 'updateArchitectureView') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'updateView', view_id: args.view_id, patch: args.patch }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'updateView', view_id: args.view_id, patch: args.patch, acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }], write), context), write);
   }
 
   if (name === 'removeArchitectureView') {
     const context = await loadContext(args);
     const write = !args.dryRun;
-    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeView', view_id: args.view_id }], write), context), write);
+    return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeView', view_id: args.view_id, acknowledgeLoss: args.acknowledgeLoss, lossJustification: args.lossJustification }], write), context), write);
   }
 
   if (name === 'queryNeo4jGraph') {

package/package.json

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