feat(diff): semantic diff between agent versions

README.md

@@ -310,6 +310,7 @@ Both `opengap` and `gitagent` refer to the same binary — use whichever you pre
 |---------|-------------|
 | `opengap init [--template]` | Scaffold new agent (`minimal`, `standard`, `full`, `llm-wiki`) |
 | `opengap validate [--compliance]` | Validate against spec and regulatory requirements |
+| `opengap diff [from] [to]` | Semantic diff between two agent versions (git refs or directories) |
 | `opengap info` | Display agent summary |
 | `opengap export --format <fmt>` | Export to other formats (see adapters below) |
 | `opengap import --from <fmt> <path>` | Import (`claude`, `cursor`, `crewai`, `opencode`) |

docs.md

@@ -555,6 +555,52 @@ opengap audit -d ./examples/full
 
 ---
 
+### diff
+
+Show a semantic diff between two agent versions — what changed in `agent.yaml`, `SOUL.md`, `RULES.md`, `DUTIES.md`, skills, tools, workflows, compliance, hooks, and memory, instead of a raw text diff.
+
+```bash
+opengap diff [from] [to] [options]
+```
+
+| Argument/Option | Default | Description |
+|------------------|---------|-------------|
+| `from` | `HEAD` | Git ref or directory to compare from |
+| `to` | working directory | Git ref or directory to compare to |
+| `-d, --dir <dir>` | `.` | Repository/agent directory used to resolve git refs |
+| `--json` | `false` | Output the structured diff as JSON instead of formatted text |
+
+Each side of the comparison can be a git ref (commit, branch, or tag — resolved against `--dir` via `git archive`) or a path to a standalone agent directory. Passing a single `from..to` argument is also accepted as shorthand for two separate refs.
+
+**What gets reported:**
+
+- **Identity (SOUL.md)** — presence + added/removed line counts (no NLP, just a size signal)
+- **Manifest (agent.yaml)** — every changed field (name, version, model, runtime, dependencies, mcp_servers, tags, metadata, ...), reported as `field.path: old → new`
+- **Rules / Duties (RULES.md / DUTIES.md)** — added/removed line counts, plus segregation-of-duties conflict pairs added or removed
+- **Skills / Tools / Workflows** — added, removed, and content-modified entries
+- **Compliance** — `risk_tier` changes (flagged with `⚠ tier escalation` when the tier increases), framework additions/removals, and every other changed compliance field
+- **Hooks** — added/removed hook entries, flagged with `⚠ enforcement added` when a new hook has `fail_open: false`
+- **Memory** — which files under `memory/` changed, flagged `⚠ review needed`
+
+```bash
+# What changed since the last commit
+opengap diff
+
+# Compare two tagged releases
+opengap diff v1.0.0 v1.1.0
+
+# Compare two branches
+opengap diff main..feature/new-skill
+
+# Compare two standalone agent directories
+opengap diff ./agent-v1 ./agent-v2
+
+# Machine-readable output for CI/PR bots
+opengap diff v1.0.0 v1.1.0 --json
+```
+
+---
+
 ### skills
 
 Manage agent skills — search registries, install, list, and inspect.

src/commands/diff.ts

@@ -0,0 +1,201 @@
+import { Command } from 'commander';
+import { existsSync, lstatSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { computeAgentDiff, type AgentDiffResult, type TextDiff, type ListDiff } from '../utils/agent-diff.js';
+import { materializeGitRef } from '../utils/git-ref.js';
+import { success, error, warn, label, heading, divider } from '../utils/format.js';
+
+interface DiffOptions {
+  dir: string;
+  json: boolean;
+}
+
+interface DiffSource {
+  dir: string;
+  label: string;
+  cleanup?: () => void;
+}
+
+function isExistingDirectory(path: string): boolean {
+  return existsSync(path) && lstatSync(path).isDirectory();
+}
+
+function resolveDiffSource(spec: string | undefined, repoDir: string): DiffSource {
+  if (spec === undefined) {
+    return { dir: repoDir, label: 'working directory' };
+  }
+  const asPath = resolve(spec);
+  if (isExistingDirectory(asPath)) {
+    return { dir: asPath, label: spec };
+  }
+  const { dir, cleanup } = materializeGitRef(repoDir, spec);
+  return { dir, label: spec, cleanup };
+}
+
+export const diffCommand = new Command('diff')
+  .description('Show a semantic diff between two agent versions (git refs or directories)')
+  .argument('[from]', 'Git ref or directory to compare from (default: HEAD)')
+  .argument('[to]', 'Git ref or directory to compare to (default: working directory)')
+  .option('-d, --dir <dir>', 'Repository/agent directory used to resolve git refs', '.')
+  .option('--json', 'Output as JSON', false)
+  .action((fromArg: string | undefined, toArg: string | undefined, options: DiffOptions) => {
+    const repoDir = resolve(options.dir);
+
+    let from = fromArg;
+    let to = toArg;
+    if (!to && from?.includes('..')) {
+      const idx = from.indexOf('..');
+      const a = from.slice(0, idx);
+      const b = from.slice(idx + 2);
+      if (a && b) {
+        from = a;
+        to = b;
+      }
+    }
+    from = from ?? 'HEAD';
+
+    let fromSource: DiffSource;
+    let toSource: DiffSource;
+    try {
+      fromSource = resolveDiffSource(from, repoDir);
+      toSource = resolveDiffSource(to, repoDir);
+    } catch (e) {
+      error((e as Error).message);
+      process.exit(1);
+    }
+
+    let result: AgentDiffResult;
+    try {
+      result = computeAgentDiff(fromSource.dir, toSource.dir, fromSource.label, toSource.label);
+    } finally {
+      fromSource.cleanup?.();
+      toSource.cleanup?.();
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      renderDiff(result);
+    }
+  });
+
+function textSummary(t: TextDiff): string {
+  if (!t.fromPresent && !t.toPresent) return 'not present';
+  if (!t.fromPresent) return 'added';
+  if (!t.toPresent) return 'removed';
+  if (!t.changed) return 'unchanged';
+  return `+${t.added} added, -${t.removed} removed`;
+}
+
+function listSummary(l: ListDiff): string {
+  if (l.added.length === 0 && l.removed.length === 0 && l.modified.length === 0) return 'unchanged';
+  const parts: string[] = [];
+  parts.push(l.added.length ? `+${l.added.length} added (${l.added.join(', ')})` : '0 added');
+  parts.push(l.removed.length ? `-${l.removed.length} removed (${l.removed.join(', ')})` : '0 removed');
+  if (l.modified.length) parts.push(`${l.modified.length} modified (${l.modified.join(', ')})`);
+  return parts.join(', ');
+}
+
+function fmt(v: unknown): string {
+  if (v === undefined) return 'unset';
+  if (typeof v === 'string') return v;
+  return JSON.stringify(v);
+}
+
+function isEmpty(r: AgentDiffResult): boolean {
+  return (
+    !r.identity.changed &&
+    r.manifest.length === 0 &&
+    !r.rules.changed &&
+    !r.duties.changed &&
+    r.duties.conflictsAdded.length === 0 &&
+    r.duties.conflictsRemoved.length === 0 &&
+    r.skills.added.length === 0 &&
+    r.skills.removed.length === 0 &&
+    r.skills.modified.length === 0 &&
+    r.tools.added.length === 0 &&
+    r.tools.removed.length === 0 &&
+    r.tools.modified.length === 0 &&
+    r.workflows.added.length === 0 &&
+    r.workflows.removed.length === 0 &&
+    r.workflows.modified.length === 0 &&
+    r.compliance.riskTier.from === r.compliance.riskTier.to &&
+    r.compliance.frameworksAdded.length === 0 &&
+    r.compliance.frameworksRemoved.length === 0 &&
+    r.compliance.changed.length === 0 &&
+    r.hooks.added.length === 0 &&
+    r.hooks.removed.length === 0 &&
+    !r.memory.changed
+  );
+}
+
+function renderDiff(r: AgentDiffResult): void {
+  heading(`gitagent diff: ${r.from} → ${r.to}`);
+  divider();
+
+  if (!r.manifestPresent.from || !r.manifestPresent.to) {
+    warn(`agent.yaml missing on one side (from: ${r.manifestPresent.from}, to: ${r.manifestPresent.to}) — comparison may be incomplete`);
+  }
+
+  label('Identity (SOUL.md)', textSummary(r.identity));
+
+  if (r.manifest.length === 0) {
+    label('Manifest (agent.yaml)', 'unchanged');
+  } else {
+    for (const f of r.manifest) {
+      label(`Manifest.${f.path}`, `${fmt(f.from)} → ${fmt(f.to)}`);
+    }
+  }
+
+  label('Rules (RULES.md)', textSummary(r.rules));
+
+  const dutiesParts = [textSummary(r.duties)];
+  for (const pair of r.duties.conflictsAdded) dutiesParts.push(`conflict added: [${pair.join(', ')}]`);
+  for (const pair of r.duties.conflictsRemoved) dutiesParts.push(`conflict removed: [${pair.join(', ')}]`);
+  label('Duties (DUTIES.md)', dutiesParts.join('; '));
+
+  label('Skills', listSummary(r.skills));
+  label('Tools', listSummary(r.tools));
+  if (r.workflows.added.length || r.workflows.removed.length || r.workflows.modified.length) {
+    label('Workflows', listSummary(r.workflows));
+  }
+
+  if (r.compliance.riskTier.from !== r.compliance.riskTier.to) {
+    const line = `${r.compliance.riskTier.from ?? 'unset'} → ${r.compliance.riskTier.to ?? 'unset'}`;
+    if (r.compliance.riskEscalated) {
+      warn(`Compliance.risk_tier: ${line}  ⚠ tier escalation`);
+    } else {
+      label('Compliance.risk_tier', line);
+    }
+  }
+  if (r.compliance.frameworksAdded.length || r.compliance.frameworksRemoved.length) {
+    const parts: string[] = [];
+    if (r.compliance.frameworksAdded.length) parts.push(`+${r.compliance.frameworksAdded.join(', ')}`);
+    if (r.compliance.frameworksRemoved.length) parts.push(`-${r.compliance.frameworksRemoved.join(', ')}`);
+    label('Compliance.frameworks', parts.join(', '));
+  }
+  for (const f of r.compliance.changed) {
+    label(`Compliance.${f.path}`, `${fmt(f.from)} → ${fmt(f.to)}`);
+  }
+
+  if (r.hooks.added.length || r.hooks.removed.length) {
+    const parts = [
+      ...r.hooks.added.map(h => `+${h.event}:${h.script}${h.failOpen === false ? ' (fail_open=false)' : ''}`),
+      ...r.hooks.removed.map(h => `-${h.event}:${h.script}`),
+    ];
+    if (r.hooks.enforcementAdded) {
+      warn(`Hooks: ${parts.join(', ')}  ⚠ enforcement added`);
+    } else {
+      label('Hooks', parts.join(', '));
+    }
+  }
+
+  if (r.memory.changed) {
+    warn(`Memory: ${r.memory.files.join(', ')} changed  ⚠ review needed`);
+  }
+
+  divider();
+  if (isEmpty(r)) {
+    success('No semantic changes detected');
+  }
+}

src/index.ts

@@ -8,6 +8,7 @@ import { exportCommand } from './commands/export.js';
 import { importCommand } from './commands/import.js';
 import { installCommand } from './commands/install.js';
 import { auditCommand } from './commands/audit.js';
+import { diffCommand } from './commands/diff.js';
 import { skillsCommand } from './commands/skills.js';
 import { runCommand } from './commands/run.js';
 import { lyzrCommand } from './commands/lyzr.js';
@@ -27,6 +28,7 @@ program.addCommand(exportCommand);
 program.addCommand(importCommand);
 program.addCommand(installCommand);
 program.addCommand(auditCommand);
+program.addCommand(diffCommand);
 program.addCommand(skillsCommand);
 program.addCommand(runCommand);
 program.addCommand(lyzrCommand);