@jaimevalasek/aioson 1.9.2 → 1.16.0

package/src/lib/agent-semantic-diff.js

@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * agent-semantic-diff — pure helpers for detecting semantic drift between
+ * workspace `.aioson/agents/{agent}.md` and template `template/.aioson/agents/{agent}.md`.
+ *
+ * F4 / T5 (workflow-handoff-integrity v1.9.8). Designed to catch the 981a8fd-style
+ * migration where the workspace agent prompt was updated but the template was not.
+ * The existing `sync-agents-preflight#checkParity` only inspects the `## Feature dossier`
+ * section length — this helper extends that lens to headers, section content, and
+ * frontmatter.
+ *
+ * Three diff strategies (per DD-03):
+ *   - diffHeaders        — section list (presence + order) at `##` and `###` levels
+ *   - diffSectionContent — hash-based diff of section bodies (catches content drift)
+ *   - diffFrontmatter    — field-level YAML-ish frontmatter comparison
+ *
+ * Plain text body diff is deliberately skipped — too noisy for typos/cosmetic edits.
+ */
+
+const crypto = require('node:crypto');
+
+// ─── Frontmatter ─────────────────────────────────────────────────────────────
+
+function extractFrontmatter(content) {
+  const match = String(content || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const out = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    if (!key) continue;
+    out[key] = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+function diffFrontmatter(workspaceContent, templateContent) {
+  const ws = extractFrontmatter(workspaceContent);
+  const tpl = extractFrontmatter(templateContent);
+  if (ws === null && tpl === null) return null; // both have no frontmatter
+  const missingInTemplate = [];
+  const missingInWorkspace = [];
+  const valueChanged = [];
+  const wsObj = ws || {};
+  const tplObj = tpl || {};
+  for (const key of Object.keys(wsObj)) {
+    if (!(key in tplObj)) {
+      missingInTemplate.push(key);
+    } else if (wsObj[key] !== tplObj[key]) {
+      valueChanged.push({ key, workspace: wsObj[key], template: tplObj[key] });
+    }
+  }
+  for (const key of Object.keys(tplObj)) {
+    if (!(key in wsObj)) missingInWorkspace.push(key);
+  }
+  if (missingInTemplate.length + missingInWorkspace.length + valueChanged.length === 0) return null;
+  return { missingInTemplate, missingInWorkspace, valueChanged };
+}
+
+// ─── Headers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extract ## and ### headers in document order.
+ * Skips anything inside fenced code blocks.
+ */
+function extractHeaders(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  const headers = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = line.match(/^(##{1,2})\s+(.+?)\s*$/);
+    if (m) headers.push(m[2].trim());
+  }
+  return headers;
+}
+
+function diffHeaders(workspaceContent, templateContent) {
+  const ws = extractHeaders(workspaceContent);
+  const tpl = extractHeaders(templateContent);
+  const wsSet = new Set(ws);
+  const tplSet = new Set(tpl);
+  const missingInTemplate = ws.filter((h) => !tplSet.has(h));
+  const missingInWorkspace = tpl.filter((h) => !wsSet.has(h));
+  // Order check: of the headers present in both, do they appear in the same sequence?
+  const common = ws.filter((h) => tplSet.has(h));
+  const commonInTpl = tpl.filter((h) => wsSet.has(h));
+  const reordered = common.length === commonInTpl.length
+    && common.some((h, i) => h !== commonInTpl[i]);
+  if (missingInTemplate.length + missingInWorkspace.length === 0 && !reordered) return null;
+  return { missingInTemplate, missingInWorkspace, reordered };
+}
+
+// ─── Section content (hash-based) ────────────────────────────────────────────
+
+/**
+ * Split content into Map<header, body>. Body is normalized (trimmed lines,
+ * collapsed whitespace) before hashing to avoid cosmetic-only false positives.
+ */
+function extractSections(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  const sections = new Map();
+  let current = '__preamble__';
+  let body = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) {
+      inFence = !inFence;
+      body.push(line);
+      continue;
+    }
+    const headerMatch = !inFence && line.match(/^(##{1,2})\s+(.+?)\s*$/);
+    if (headerMatch) {
+      sections.set(current, body.join('\n'));
+      current = headerMatch[2].trim();
+      body = [];
+      continue;
+    }
+    body.push(line);
+  }
+  sections.set(current, body.join('\n'));
+  return sections;
+}
+
+function normalizeBody(body) {
+  return String(body || '')
+    .split(/\r?\n/)
+    .map((l) => l.replace(/\s+/g, ' ').trim())
+    .filter(Boolean)
+    .join('\n');
+}
+
+function hashBody(body) {
+  return crypto.createHash('sha256').update(normalizeBody(body)).digest('hex').slice(0, 16);
+}
+
+function diffSectionContent(workspaceContent, templateContent) {
+  const ws = extractSections(workspaceContent);
+  const tpl = extractSections(templateContent);
+  const diverged = [];
+  for (const [header, wsBody] of ws.entries()) {
+    if (!tpl.has(header)) continue; // missing-header case handled by diffHeaders
+    const wsHash = hashBody(wsBody);
+    const tplHash = hashBody(tpl.get(header));
+    if (wsHash !== tplHash) {
+      diverged.push({ header, workspaceHash: wsHash, templateHash: tplHash });
+    }
+  }
+  return diverged.length > 0 ? diverged : null;
+}
+
+// ─── Aggregate runner ────────────────────────────────────────────────────────
+
+/**
+ * Run all three diff strategies on a single agent file pair.
+ * Returns null when no drift is detected, otherwise an issue object.
+ */
+function diffAgentFile(workspaceContent, templateContent) {
+  // AC-T5-08: missing-on-one-side detection.
+  if (!workspaceContent && !templateContent) return null;
+  if (!workspaceContent || !templateContent) {
+    return {
+      missingFile: !workspaceContent ? 'workspace' : 'template',
+      missingInTemplate: [], missingInWorkspace: [], reordered: false,
+      divergedSections: [],
+      frontmatter: null
+    };
+  }
+  const headers = diffHeaders(workspaceContent, templateContent);
+  const sections = diffSectionContent(workspaceContent, templateContent);
+  const frontmatter = diffFrontmatter(workspaceContent, templateContent);
+  if (!headers && !sections && !frontmatter) return null;
+  return {
+    missingFile: null,
+    missingInTemplate: headers?.missingInTemplate || [],
+    missingInWorkspace: headers?.missingInWorkspace || [],
+    reordered: headers?.reordered || false,
+    divergedSections: sections || [],
+    frontmatter: frontmatter || null
+  };
+}
+
+module.exports = {
+  extractFrontmatter,
+  extractHeaders,
+  extractSections,
+  diffFrontmatter,
+  diffHeaders,
+  diffSectionContent,
+  diffAgentFile,
+  hashBody,
+  normalizeBody
+};

package/src/operator-memory/conflict.js

@@ -0,0 +1,202 @@
+'use strict';
+
+/**
+ * operator-memory — conflict policy + warning surface (Phase 4, v1.15.0).
+ *
+ * V1 binary policy (PMD-09): project rules in `.aioson/rules/` always win.
+ * Operator decisions are unchanged on conflict — only a stderr warning is
+ * emitted, debounced per (decision_slug, rule_path) pair via _conflict_state.json
+ * with a 60s window (AC-P4-03).
+ *
+ * Detection (V1 keyword-based — V2 will move to LLM-tagged):
+ *   1. Rule frontmatter must opt in: `conflicts_with_signal_types: [authorization, ...]`
+ *      Rules without this field generate zero false positives (additive policy).
+ *   2. Operator decision's signal_type must intersect rule's `conflicts_with_signal_types`.
+ *   3. Keyword overlap ≥ 2 between rule body and decision body (case-insensitive,
+ *      stopwords filtered). Configurable via env `AIOSON_OPERATOR_CONFLICT_KEYWORD_THRESHOLD`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getStorageRoot } = require('./storage');
+
+const DEFAULT_KEYWORD_THRESHOLD = 2;
+const DEFAULT_DEBOUNCE_MS = 60_000;
+const CONFLICT_STATE_FILE = '_conflict_state.json';
+
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'of', 'to', 'for', 'in', 'on', 'with', 'is', 'be',
+  'que', 'de', 'em', 'para', 'sem', 'com', 'um', 'uma', 'os', 'as', 'no', 'na'
+]);
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w && !STOPWORDS.has(w) && w.length >= 3);
+}
+
+function keywordOverlap(textA, textB) {
+  const a = new Set(tokenize(textA));
+  const b = new Set(tokenize(textB));
+  if (a.size === 0 || b.size === 0) return 0;
+  let overlap = 0;
+  for (const t of a) if (b.has(t)) overlap += 1;
+  return overlap;
+}
+
+function parseRuleFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const out = {};
+  let inList = null;
+  for (const rawLine of m[1].split('\n')) {
+    if (inList) {
+      const listItem = rawLine.match(/^\s+-\s+(.*)$/);
+      if (listItem) {
+        out[inList].push(listItem[1].trim().replace(/^['"]|['"]$/g, ''));
+        continue;
+      } else if (rawLine.trim() === '' || /^[a-z_]+:/.test(rawLine)) {
+        inList = null;
+        // fall through to parse this line as regular field
+      }
+    }
+    const arrayLineMatch = rawLine.match(/^([a-z_]+):\s*\[(.*)\]$/);
+    if (arrayLineMatch) {
+      out[arrayLineMatch[1]] = arrayLineMatch[2].split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+      continue;
+    }
+    const listStartMatch = rawLine.match(/^([a-z_]+):\s*$/);
+    if (listStartMatch) {
+      out[listStartMatch[1]] = [];
+      inList = listStartMatch[1];
+      continue;
+    }
+    const fieldMatch = rawLine.match(/^([a-z_]+):\s*(.+)$/);
+    if (fieldMatch) {
+      let v = fieldMatch[2].trim();
+      if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+      out[fieldMatch[1]] = v;
+    }
+  }
+  return out;
+}
+
+function readRule(rulePath) {
+  const content = fs.readFileSync(rulePath, 'utf8');
+  const fm = parseRuleFrontmatter(content);
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  return { frontmatter: fm || {}, body, path: rulePath };
+}
+
+function scanProjectRules(projectRoot) {
+  const rulesDir = path.join(projectRoot, '.aioson', 'rules');
+  if (!fs.existsSync(rulesDir)) return [];
+  const files = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md') && f !== 'README.md');
+  return files.map((f) => readRule(path.join(rulesDir, f)));
+}
+
+/**
+ * Detect conflicts between loaded operator decisions and project rules.
+ *
+ * @param {Array<object>} decisions — decisions to check (e.g. matched by preflightLoad)
+ * @param {Array<object>} rules — output of scanProjectRules(projectRoot)
+ * @param {object} options — { threshold }
+ * @returns {Array<{decision_slug, rule_path, rule_basename, reason, severity, overlap}>}
+ */
+function detectConflicts(decisions, rules, options = {}) {
+  const threshold = options.threshold || DEFAULT_KEYWORD_THRESHOLD;
+  const conflicts = [];
+
+  for (const decision of decisions) {
+    for (const rule of rules) {
+      const conflictSignals = rule.frontmatter.conflicts_with_signal_types;
+      if (!Array.isArray(conflictSignals) || conflictSignals.length === 0) continue;
+      if (!conflictSignals.includes(decision.signal_type)) continue;
+      const overlap = keywordOverlap(rule.body, decision.body || decision.proposal || '');
+      if (overlap >= threshold) {
+        conflicts.push({
+          decision_slug: decision.slug,
+          rule_path: rule.path,
+          rule_basename: path.basename(rule.path),
+          severity: 'warning',
+          overlap,
+          reason: `keyword overlap=${overlap} ≥ threshold=${threshold}, signal_type=${decision.signal_type} in rule.conflicts_with_signal_types`
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+function formatConflictWarning(conflict) {
+  return `⚠ Operator memory '${conflict.decision_slug}' conflicts with project rule '${conflict.rule_basename}'. Project rule applies.`;
+}
+
+function conflictStatePath(identity) {
+  return path.join(getStorageRoot(identity), CONFLICT_STATE_FILE);
+}
+
+function loadConflictState(identity) {
+  const p = conflictStatePath(identity);
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveConflictState(identity, state) {
+  const p = conflictStatePath(identity);
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * Filter conflicts to those whose debounce window has elapsed.
+ * Updates state file with new last_warned_at timestamps for emitted ones.
+ *
+ * @returns {Array} subset of conflicts that should be emitted right now
+ */
+function debounceConflicts(identity, conflicts, options = {}) {
+  if (conflicts.length === 0) return [];
+  const debounceMs = options.debounceMs || DEFAULT_DEBOUNCE_MS;
+  const state = loadConflictState(identity);
+  const now = Date.now();
+  const toEmit = [];
+  let stateChanged = false;
+  for (const c of conflicts) {
+    const key = `${c.decision_slug}::${c.rule_basename}`;
+    const last = state[key];
+    if (!last || (now - new Date(last).getTime()) >= debounceMs) {
+      toEmit.push(c);
+      state[key] = new Date(now).toISOString();
+      stateChanged = true;
+    }
+  }
+  if (stateChanged) {
+    try { saveConflictState(identity, state); } catch { /* non-fatal */ }
+  }
+  return toEmit;
+}
+
+module.exports = {
+  detectConflicts,
+  debounceConflicts,
+  formatConflictWarning,
+  scanProjectRules,
+  readRule,
+  parseRuleFrontmatter,
+  keywordOverlap,
+  tokenize,
+  loadConflictState,
+  saveConflictState,
+  DEFAULT_KEYWORD_THRESHOLD,
+  DEFAULT_DEBOUNCE_MS,
+  CONFLICT_STATE_FILE
+};

package/src/operator-memory/decay.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * operator-memory — per-category TTL decay engine (Phase 5, v1.16.0).
+ *
+ * PMD-03: category half-life (identity=365d, autonomy=180d, tooling=90d, default=90d).
+ * Decay prompt fires when (now - last_reinforced) >= half_life, debounced 30d per slug
+ * via _decay_state.json.
+ *
+ * Per-category override via env: AIOSON_OPERATOR_DECAY_<CATEGORY>_DAYS (e.g.
+ * AIOSON_OPERATOR_DECAY_IDENTITY_DAYS=730 for 2-year identity persistence).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getStorageRoot } = require('./storage');
+const { readDecision } = require('./decision');
+const { listDecisionSlugs } = require('./index-md');
+
+const DECAY_STATE_FILE = '_decay_state.json';
+
+const HALF_LIFE_DAYS_DEFAULT = {
+  identity: 365,
+  autonomy: 180,
+  tooling: 90,
+  default: 90
+};
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_PROMPT_DEBOUNCE_DAYS = 30;
+
+function halfLifeForCategory(category) {
+  const envKey = `AIOSON_OPERATOR_DECAY_${String(category).toUpperCase()}_DAYS`;
+  const override = process.env[envKey];
+  if (override && !Number.isNaN(Number(override))) {
+    return Number(override);
+  }
+  return HALF_LIFE_DAYS_DEFAULT[category] ?? HALF_LIFE_DAYS_DEFAULT.default;
+}
+
+function decayStatePath(identity) {
+  return path.join(getStorageRoot(identity), DECAY_STATE_FILE);
+}
+
+function loadDecayState(identity) {
+  const p = decayStatePath(identity);
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveDecayState(identity, state) {
+  const p = decayStatePath(identity);
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * Compute days since last_reinforced for a decision.
+ */
+function daysSinceReinforced(decision, now = Date.now()) {
+  const reinforced = new Date(decision.last_reinforced || decision.promoted_at || 0).getTime();
+  if (!reinforced) return Infinity;
+  return Math.floor((now - reinforced) / DAY_MS);
+}
+
+/**
+ * Identify stale decisions whose decay-prompt debounce window has elapsed.
+ *
+ * @returns {Array<{slug, category, days_stale, half_life}>} candidates to surface
+ */
+function findStaleDecisions(identity, options = {}) {
+  const now = options.now || Date.now();
+  const debounceDays = options.debounceDays ?? DEFAULT_PROMPT_DEBOUNCE_DAYS;
+  const state = loadDecayState(identity);
+  const slugs = listDecisionSlugs(identity);
+  const stale = [];
+
+  for (const slug of slugs) {
+    const decision = readDecision(identity, slug);
+    if (!decision) continue;
+    const category = decision.category || 'default';
+    const halfLife = halfLifeForCategory(category);
+    const daysStale = daysSinceReinforced(decision, now);
+    if (daysStale < halfLife) continue;
+
+    const last = state[slug];
+    if (last) {
+      const daysSincePrompt = Math.floor((now - new Date(last).getTime()) / DAY_MS);
+      if (daysSincePrompt < debounceDays) continue;
+    }
+    stale.push({ slug, category, days_stale: daysStale, half_life: halfLife, title: decision.body?.slice(0, 80) || slug });
+  }
+
+  return stale;
+}
+
+/**
+ * Mark a stale decision's prompt as shown (updates debounce timestamp).
+ */
+function markDecayPromptShown(identity, slug) {
+  const state = loadDecayState(identity);
+  state[slug] = new Date().toISOString();
+  saveDecayState(identity, state);
+}
+
+function formatDecayPrompt(stale) {
+  return `⏱ Memory '${stale.slug}' is ${stale.days_stale}d stale (${stale.category}, half-life=${stale.half_life}d). Still valid? aioson op:reinforce ${stale.slug} | op:forget ${stale.slug}`;
+}
+
+/**
+ * Clean up history/ entries older than maxAgeDays (default 365). Phase 5
+ * cleanup runs alongside decay sweep — hard-delete old soft-deleted items.
+ *
+ * @returns {Array<string>} paths of files removed
+ */
+function cleanupHistory(identity, options = {}) {
+  const maxAgeDays = options.maxAgeDays || 365;
+  const now = options.now || Date.now();
+  const historyDir = path.join(getStorageRoot(identity), 'history');
+  if (!fs.existsSync(historyDir)) return [];
+
+  const removed = [];
+  for (const f of fs.readdirSync(historyDir)) {
+    if (!f.endsWith('.md')) continue;
+    const full = path.join(historyDir, f);
+    try {
+      const stat = fs.statSync(full);
+      const ageDays = Math.floor((now - stat.mtimeMs) / DAY_MS);
+      if (ageDays >= maxAgeDays) {
+        fs.unlinkSync(full);
+        removed.push(full);
+      }
+    } catch { /* ignore */ }
+  }
+
+  return removed;
+}
+
+module.exports = {
+  findStaleDecisions,
+  markDecayPromptShown,
+  formatDecayPrompt,
+  cleanupHistory,
+  loadDecayState,
+  saveDecayState,
+  halfLifeForCategory,
+  daysSinceReinforced,
+  HALF_LIFE_DAYS_DEFAULT,
+  DEFAULT_PROMPT_DEBOUNCE_DAYS,
+  DECAY_STATE_FILE,
+  DAY_MS
+};