Skip to content

feat: two-revision graph-diff spike for evidence-backed change-impact wedge #219

Description

@parthrohit22

Problem

PARTHA's strongest claimed moat is "evidence-backed change impact for inherited services," but today it only answers "what does this one revision contain?" There is no two-revision product workflow, so teams cannot answer the roadmap's highest-value question: "what changed, why, what is affected, and what decision should we make?" The 2026-07-27 audit (§4, §15 Risk 3) confirms the differentiating layer is entirely absent and the current product competes as a commodity static analyzer.

This spike builds the first recurring-decision workflow over the already-deterministic, immutable ri.v1 snapshots: given two exact revisions of the same repository, produce an added/removed/changed fact diff with producer-diff separation and exact, inspectable evidence.

Proposed Behavior

A user selects two sealed snapshots (revision A and revision B) for the same repository. PARTHA returns:

  • Added / removed / changed nodes and edges (with producer-diff separation so extraction changes don't masquerade as code changes).
  • For changed entities, the exact evidence spans that changed.
  • A bounded, evidence-linked view — no opaque score, no fabricated confidence.

This is deliberately a spike: prove the wedge works on real partner repositories (from P0-C) before productizing UI/PR integration.

Scope

  • New evolution model/query in apps/backend/app/intelligence/ (reuse SnapshotQueryService, do NOT build a second parser — AGENTS.md architectural rule).
  • New API route(s) for revision-pair diff (owner-scoped, 404 for cross-owner).
  • Minimal UI: a diff/compare view reusing existing honest-limit (not_assessed/PreviewBanner) patterns.
  • Likely files: snapshot_store.py, query_service.py, a new evolution.py, route + schema, frontend compare page.

Acceptance Criteria

  • Given two sealed snapshots of the same repository, the API returns added/removed/changed facts with producer-diff separation and exact evidence handles.
  • Every changed-entity conclusion is pinned to a revision and an inspectable evidence span (no unsourced claim).
  • Owner-scoping enforced: cross-owner or non-existent snapshot → 404.
  • Runs on ≥2 real partner repository revision pairs supplied by P0-C; human rates usefulness/correctness.
  • Backend tests (added/removed/changed, rename/move handling at basic level) pass; test_openapi_contract.py updated if a new route is added.
  • No second repository parser introduced (reuse intelligence/).

Priority

P0 - Critical

Risks and Dependencies

  • Depends on: P0-B (canonical core honest), P0-C (real revision pairs + partner access). Do not start before those unblock it.
  • Depends on the existing deterministic ri.v1 sealing + canonical hash (already implemented, audit §5 "Implemented").
  • Risk: rename/move/split/merge entity matching is hard; scope this spike to basic changed-set + evidence, defer high-confidence move detection to the medium-term hardening (audit §16 medium-term "Harden cross-revision identity").
  • Risk: accuracy on real frameworks — mitigated by using only supported extractor facts, consistent with the support matrix.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P0Priority: criticalenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions