---
kind: decision
status: accepted
confidence: low
---

# ADR — `/brain:diff` drift detection

## Context

`/brain:build` can generate code from structured intent blocks. Once generated code is applied to a target repo, it will drift. We need a lightweight, read-only way to detect that drift before we add reconciliation (`/brain:sync-code`).

## Decision

pi-brain will add `/brain:diff <scope> <target>` that regenerates expected code from intent blocks, compares it to actual code, and reports structural differences.

### Approach

1. Use the same block extraction and renderer as `/brain:build`.
2. Load the actual generated file(s) from:
   - `wiki/<scope>/ai-suggestions/build/<target>/` for repo-agnostic clones.
   - Configured target repo path for onboarded/converted repos.
3. Parse TypeScript interfaces using a simple regex/AST-free approach for v1.
4. Compare declared names, fields, and primitive types.
5. Write the drift report to `wiki/<scope>/ai-suggestions/drift/<target>.md`.

### Scope

- First target: TypeScript interfaces generated by `/brain:build types`.
- Only structural comparison: names, fields, optional flags, primitive types.
- Reports are suggestions, not commits.

## Alternatives considered

1. **Full AST diff using TypeScript compiler API.**
   - *Rejected:* too heavy for v1; simple regex comparison is enough for structural drift.

2. **Text diff only.**
   - *Rejected:* too noisy; refactors that don't change semantics would be flagged.

3. **No drift detection; rely on humans to remember.**
   - *Rejected:* defeats the purpose of regenerative intent.

4. **Simple structural diff.** (Chosen.)
   - *Pros:* fast, easy to understand, good enough for v1.
   - *Cons:* may miss subtle type aliases or generics; acceptable for first bet.

## Consequences

- Users can detect drift between intent and code without manual inspection.
- Sets up the foundation for `/brain:sync-code` reconciliation.
- Encourages keeping intent blocks accurate because drift is visible.

## Related

- [wiki/brain/prds/brain-diff-drift-detection.md](../prds/brain-diff-drift-detection.md)
- [wiki/brain/bets/brain-diff-drift-detection.md](../bets/brain-diff-drift-detection.md)
- [wiki/brain/epics/regenerative-intent.md](../epics/regenerative-intent.md)
- [wiki/brain/adrs/structured-intent-and-build.md](../adrs/structured-intent-and-build.md)
- [wiki/brain/constraints/adr-before-structural-changes.md](../constraints/adr-before-structural-changes.md)