Add discovery reconciliation engine

docs/repo-reality-scanner.md

@@ -91,6 +91,46 @@ candidates. Unresolved edge endpoints or attribute targets also become review
 artifacts. Accepted graph data still requires deterministic evidence,
 repo-owned declarations, or a later human review/acceptance path.
 
+## Reconciliation And Dry-Run Diffs
+
+Scans can be reconciled against a previous discovery snapshot:
+
+```bash
+railiance-fabric scan . \
+  --repo-slug railiance-fabric \
+  --previous-snapshot previous-discovery.json \
+  --dry-run \
+  --output current-discovery.json
+```
+
+The reconciler writes `reconciliation.diff` with explicit stable-key sets:
+
+- `added`
+- `changed`
+- `retired`
+- `conflicted`
+
+It deduplicates candidates by stable key, merges source anchors and provenance,
+and applies source-aware precedence when duplicate candidates disagree. The
+current precedence is:
+
+1. `repo_declaration`
+2. `deterministic`
+3. `catalog`
+4. `registry`
+5. `llm`
+6. `manual`
+
+Possible duplicates found through matching aliases, normalized labels,
+relationship endpoints, or attribute targets are not silently merged. They are
+marked `status: conflicted`, moved to `review_state: needs_review`, and listed
+under `reconciliation.conflicts`.
+
+Missing previous candidates become tombstones only when their replacement scope
+is present in the current scan and has `mode: replacement`. Missing candidates
+from additive scopes, such as broad LLM evidence bundles, are left alone.
+Existing tombstones are preserved so repeated scans can explain graph drift.
+
 ## Identity
 
 Identity is the main safety boundary. The scanner must not append guesses on