Proposal: Generate Architecture Delta directly from Git changes

[ARE404]

Problem

Archify can already compare two authored architecture JSON snapshots and render an Architecture Delta with Before, Delta, and After views. It can identify added, removed, changed, moved, and rerouted components, connections, and boundaries when the snapshots preserve stable IDs.

The missing step is producing the second snapshot from a real code change. Today, after implementing a feature, a user must manually author or regenerate head.json before running the comparison. Archify cannot yet inspect a Git diff, determine which architecture elements were affected, and update the architecture snapshot automatically.

Proposed capability

Add a repository-aware command such as:

archify diff --base main --head HEAD --repo-root .

The command would:

1. Load or generate the architecture snapshot for the base revision.
2. Inspect the Git changes between the base and head revisions.
3. Map changed files and symbols to existing architecture components through stable IDs and sources evidence.
4. Add, update, or remove affected components, connections, and boundaries in the head snapshot.
5. Reuse the existing Architecture Delta comparator to produce the final Before / Delta / After artifact.

In short:

Git change -> affected architecture elements -> updated head JSON -> Architecture Delta

Suggested MVP

The first version could stay deliberately conservative:

• Support architecture diagrams only.
• Require an existing base architecture JSON with stable component and connection IDs.
• Use components[].sources as the primary code-to-architecture mapping.
• Detect direct file-level additions, removals, and modifications first.
• Preserve unchanged authored layout and metadata.
• Emit explicit unknown or needs-review results when a change cannot be mapped confidently.
• Never infer runtime impact, causality, risk, or mergeability without evidence.
• Output the generated head.json, the compare receipt, and the Architecture Delta HTML so the result remains inspectable and reproducible.

Possible follow-up scope

Later versions could add symbol-level dependency analysis, language-specific adapters, CI and pull-request integration, and delta support for sequence, workflow, data-flow, and lifecycle diagrams.

Acceptance criteria

• Given a repository, a base revision, a head revision, and a valid base architecture snapshot, Archify can generate a deterministic head snapshot.
• Stable IDs are retained for unchanged architecture entities.
• Directly mapped additions, removals, and modifications appear correctly in the existing Delta view.
• Ambiguous changes are surfaced for review instead of being silently guessed.
• The generated snapshot passes the existing Archify schema and quality validation.
• Re-running the command on the same revisions produces the same semantic result.

Would this repository-aware snapshot generation fit Archify's intended scope? If so, should the first iteration require explicit sources mappings, or also attempt best-effort repository inference?

[arvindand]

I've been working on a PR action around Archify's snapshot comparison, and this is the gap it leaves today: when code changes without a corresponding map update, it can only prompt an architecture review.
I agree with starting from explicit sources mappings. I'd keep identifying affected components separate from deciding how their architecture has changed. A mapped file changing gives us a reason to review the component, but doesn't establish that its responsibilities or dependencies changed. Even deleting a file could mean moving an implementation rather than removing a component.
For the MVP, could we report affected components with the supporting Git changes, and only update head.json where there's enough evidence for a specific structural change? That would already be useful in PR review.