agentxchain 2.91.0 → 2.93.0

package/src/lib/repo-decisions.js

@@ -0,0 +1,100 @@
+/**
+ * Repo Decisions — cross-run decision carryover.
+ *
+ * Decisions with durability: "repo" persist in `.agentxchain/repo-decisions.jsonl`
+ * across governed runs. They act as binding constraints: agents in future runs
+ * must comply with active repo decisions or explicitly override them.
+ *
+ * DEC-SPEC: .planning/CROSS_RUN_DECISION_CARRYOVER_SPEC.md
+ */
+
+import { readFileSync, appendFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+const REPO_DECISIONS_PATH = '.agentxchain/repo-decisions.jsonl';
+
+// ── Read ────────────────────────────────────────────────────────────────────
+
+export function readRepoDecisions(root) {
+  const filePath = join(root, REPO_DECISIONS_PATH);
+  if (!existsSync(filePath)) return [];
+  try {
+    const content = readFileSync(filePath, 'utf8').trim();
+    if (!content) return [];
+    return content.split('\n').filter(Boolean).map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function getActiveRepoDecisions(root) {
+  return readRepoDecisions(root).filter(d => d.status === 'active');
+}
+
+export function getRepoDecisionById(root, decisionId) {
+  return readRepoDecisions(root).find(d => d.id === decisionId) || null;
+}
+
+// ── Write ───────────────────────────────────────────────────────────────────
+
+export function appendRepoDecision(root, entry) {
+  const filePath = join(root, REPO_DECISIONS_PATH);
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(filePath, JSON.stringify(entry) + '\n');
+}
+
+export function overrideRepoDecision(root, targetId, overridingId) {
+  const all = readRepoDecisions(root);
+  const updated = all.map(d => {
+    if (d.id === targetId) {
+      return { ...d, status: 'overridden', overridden_by: overridingId };
+    }
+    return d;
+  });
+  const filePath = join(root, REPO_DECISIONS_PATH);
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, updated.map(d => JSON.stringify(d)).join('\n') + '\n');
+}
+
+// ── Validate Override ───────────────────────────────────────────────────────
+
+export function validateOverride(root, decision) {
+  if (!decision.overrides) return { ok: true };
+  const targetId = decision.overrides;
+  const target = getRepoDecisionById(root, targetId);
+  if (!target) {
+    return { ok: false, error: `decisions: overrides references ${targetId} which does not exist in repo decisions.` };
+  }
+  if (target.status === 'overridden') {
+    return { ok: false, error: `decisions: ${targetId} is already overridden by ${target.overridden_by}.` };
+  }
+  if (target.status !== 'active') {
+    return { ok: false, error: `decisions: ${targetId} has status "${target.status}", only active repo decisions can be overridden.` };
+  }
+  return { ok: true };
+}
+
+// ── Render ──────────────────────────────────────────────────────────────────
+
+export function renderRepoDecisionsMarkdown(activeDecisions) {
+  if (!activeDecisions || activeDecisions.length === 0) return '';
+  const lines = [
+    '## Active Repo Decisions',
+    '',
+    'These decisions persist from prior governed runs. Comply or explicitly override with rationale.',
+    '',
+  ];
+  for (const d of activeDecisions) {
+    lines.push(`- **${d.id}** (${d.category}): ${d.statement}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+export { REPO_DECISIONS_PATH };

package/src/lib/repo-observer.js

@@ -175,7 +175,7 @@ export function observeChanges(root, baseline) {
   };
 }
 
-export function attributeObservedChangesToTurn(observation, currentTurn, historyEntries = []) {
+export function attributeObservedChangesToTurn(observation, currentTurn, historyEntries = [], options = {}) {
   const observedFiles = Array.isArray(observation?.files_changed) ? observation.files_changed : [];
   if (observedFiles.length === 0) {
     return observation;
@@ -184,6 +184,11 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
   const concurrentIds = new Set(
     Array.isArray(currentTurn?.concurrent_with) ? currentTurn.concurrent_with : [],
   );
+  for (const siblingId of Array.isArray(options.concurrentSiblingIds) ? options.concurrentSiblingIds : []) {
+    if (typeof siblingId === 'string' && siblingId.length > 0) {
+      concurrentIds.add(siblingId);
+    }
+  }
   if (concurrentIds.size === 0) {
     return observation;
   }
@@ -195,11 +200,17 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
     .filter((entry) => (
       Number.isInteger(entry?.accepted_sequence)
       && entry.accepted_sequence > assignedSequence
-      && concurrentIds.has(entry.turn_id)
+      && (
+        concurrentIds.has(entry.turn_id)
+        || (Array.isArray(entry?.concurrent_with) && entry.concurrent_with.includes(currentTurn?.turn_id))
+      )
     ))
     .sort((left, right) => left.accepted_sequence - right.accepted_sequence);
 
-  if (acceptedConcurrentSiblings.length === 0) {
+  const pendingConcurrentSiblingDeclarations = Array.isArray(options.pendingConcurrentSiblingDeclarations)
+    ? options.pendingConcurrentSiblingDeclarations
+    : [];
+  if (acceptedConcurrentSiblings.length === 0 && pendingConcurrentSiblingDeclarations.length === 0) {
     return observation;
   }
 
@@ -221,7 +232,20 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
     }
   }
 
-  if (siblingMarkersByFile.size === 0) {
+  const currentDeclaredFiles = new Set(
+    Array.isArray(options.currentDeclaredFiles) ? options.currentDeclaredFiles : [],
+  );
+  const pendingConcurrentSiblingFiles = new Set();
+  for (const declaration of pendingConcurrentSiblingDeclarations) {
+    const siblingFiles = Array.isArray(declaration?.files_changed) ? declaration.files_changed : [];
+    for (const filePath of siblingFiles) {
+      if (typeof filePath === 'string' && filePath.length > 0 && !currentDeclaredFiles.has(filePath)) {
+        pendingConcurrentSiblingFiles.add(filePath);
+      }
+    }
+  }
+
+  if (siblingMarkersByFile.size === 0 && pendingConcurrentSiblingFiles.size === 0) {
     return observation;
   }
 
@@ -239,6 +263,10 @@ export function attributeObservedChangesToTurn(observation, currentTurn, history
       attributedToConcurrentSiblings.push(filePath);
       continue;
     }
+    if (pendingConcurrentSiblingFiles.has(filePath)) {
+      attributedToConcurrentSiblings.push(filePath);
+      continue;
+    }
     nextFiles.push(filePath);
     if (typeof currentMarker === 'string') {
       nextMarkers[filePath] = currentMarker;
@@ -503,7 +531,13 @@ export function compareDeclaredVsObserved(declared, observed, writeAuthority, op
 
   if (writeAuthority === 'authoritative') {
     if (undeclared.length > 0) {
-      errors.push(`Undeclared file changes detected (observed but not in files_changed): ${undeclared.join(', ')}`);
+      if (options.has_unaccepted_concurrent_siblings) {
+        // Concurrent siblings may have written these files; downgrade to warning.
+        // The attribution system will handle later-accepted siblings correctly.
+        warnings.push(`Undeclared file changes detected (likely from concurrent sibling turns): ${undeclared.join(', ')}`);
+      } else {
+        errors.push(`Undeclared file changes detected (observed but not in files_changed): ${undeclared.join(', ')}`);
+      }
     }
     if (phantom.length > 0) {
       warnings.push(`Declared files not observed in actual diff: ${phantom.join(', ')}`);