Skip to content

feat(diff): semantic diff between agent versions - #98

Open
code-saksham-hash wants to merge 1 commit into
open-gitagent:mainfrom
code-saksham-hash:feat/4-semantic-diff
Open

feat(diff): semantic diff between agent versions#98
code-saksham-hash wants to merge 1 commit into
open-gitagent:mainfrom
code-saksham-hash:feat/4-semantic-diff

Conversation

@code-saksham-hash

@code-saksham-hash code-saksham-hash commented Aug 16, 2026

Copy link
Copy Markdown

Adds opengap diff [from] [to], closing #4.

Compares two agent snapshots — git refs (resolved via git archive) or plain directories — and reports what actually changed instead of a raw text diff: agent.yaml fields, SOUL.md/RULES.md/DUTIES.md size deltas, skills/tools/workflows added/removed/modified, compliance changes (flags risk tier escalation), hooks (flags a newly-added fail_open: false entry), and which files under memory/ changed. --json for scripting/CI.

A few notes on how it's built:

  • Either side of the comparison can be a git ref or a directory. If it's not an existing directory, it's treated as a ref and materialized into a temp dir via git rev-parse + git archive — no working-tree checkout, so no lock conflicts, and it still works when --dir isn't a git repo at all (both-directories case).
  • A single A..B argument works too, split on the literal ...
  • Bare opengap diff with no args compares HEAD against the working directory, same idea as plain git diff.
  • SOUL.md is diffed as presence + line-count delta only, no NLP — per your comment on the issue.
  • agent.yaml and compliance are diffed generically (flatten + compare) instead of hand-listing every field, so new schema fields get picked up without touching this code.
  • risk_tier escalation only fires on a strict increase (low < medium < high < critical), not on a downgrade.
  • SOD conflict pairs compare order-insensitively ([a, b] == [b, a]).

Tested with npm run build + npm test (75/75, 24 new tests in agent-diff.test.ts and git-ref.test.ts), plus manual runs against examples/standard vs examples/full and a throwaway two-commit repo — ref diffing, A..B syntax, bare diff, an invalid ref, and confirming temp dirs actually get cleaned up.

Sample output (`opengap diff ./examples/standard ./examples/full`)
gitagent diff: ./examples/standard → ./examples/full
────────────────────────────────────────────────────────────
  Identity (SOUL.md): +14 added, -10 removed
  Manifest.description: Automated code review agent with best-practice enforcement → Financial compliance analysis agent for FINRA and Federal Reserve regulated environments
  Manifest.name: code-review-agent → compliance-analyst
  ...
  Rules (RULES.md): +69 added, -15 removed
  Duties (DUTIES.md): added; conflict added: [analyst, reviewer]; conflict added: [analyst, auditor]; conflict added: [reviewer, auditor]
  Skills: +2 added (document-review, regulatory-analysis), -1 removed (code-review)
  Tools: +2 added (generate-report, search-regulations), -2 removed (complexity-analysis, lint-check)
  Workflows: +1 added (regulatory-review), 0 removed
! Compliance.risk_tier: unset → high  ⚠ tier escalation
  Compliance.frameworks: +finra, federal_reserve, sec, cfpb
  ...
! Hooks: +on_session_start:scripts/load-compliance-context.sh (fail_open=false), +pre_tool_use:scripts/audit-tool-call.sh (fail_open=false), ...  ⚠ enforcement added
! Memory: MEMORY.md, context.md, daily-log/2026-02-18.md, daily-log/2026-02-20.md, key-decisions.md, memory.yaml changed  ⚠ review needed
────────────────────────────────────────────────────────────

Known gaps: nothing tests the Commander wiring directly (same as the other files in src/commands/, the logic underneath is what's covered), and array-valued compliance fields like escalation_triggers/handoffs are diffed as whole values rather than per-item add/remove. Can break those out further if you want it more granular.

Adds `opengap diff [from] [to]`, comparing two agent snapshots (git
refs materialized via `git archive`, or plain directories) and
reporting structured changes instead of a raw text diff: agent.yaml
fields, SOUL.md/RULES.md/DUTIES.md size deltas, skills/tools/workflows
added-removed-modified, compliance changes (with a tier-escalation
warning), hooks (flagging newly-enforced fail_open: false entries),
and which memory/ files changed. Supports --json for CI/tooling use.

Closes open-gitagent#4.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant