stemedb/applications/aphoria/docs/gap-fixes-summary.md

# Gap Fixes Summary

## Overview

This document summarizes the fixes implemented for Gap 1 (Observations Treatment) and Gap 5 (Lineage Enforcement) from the Aphoria gap analysis.

## Gap 1: Fix Observation Treatment (Confidence-Based Tiers)

### Problem
The persistent scan mode was using `claim_to_assertion()` which assigned Tier 3 (Expert) authority to all observations, regardless of confidence. This gave extractor observations the same weight as human-authored claims.

### Solution
Changed `episteme/local/store.rs` line 36 in `ingest_claims()` from:
```rust
let assertion = claim_to_assertion(claim, &self.signing_key, timestamp, git_commit.as_deref());
```

To:
```rust
let assertion = observation_to_assertion(claim, &self.signing_key, timestamp, git_commit.as_deref());
```

### Behavior
Observations now get appropriate tier assignment based on confidence:
- **Tier 4 (Community, 0.3 weight)**: confidence ≥ 0.9
- **Tier 5 (Anecdotal, 0.1 weight)**: confidence < 0.9

This correctly distinguishes observations (extractor pattern matches) from claims (human-authored rules with provenance).

### Files Changed
- `applications/aphoria/src/episteme/local/store.rs` (1 line)

### Tests
- Existing `bridge::tests::test_observation_to_tier_*` tests validate tier mapping
- Existing `episteme::tests::test_ingest_observations_creates_tier4_assertions` validates storage integration
- All 1171 aphoria tests pass

---

## Gap 5: Enforce Lineage on Supersede (Already Implemented + Enhanced)

### Status
The core auto-deprecation feature was **already implemented** in `ClaimsFile::supersede()` at line 152-168.

### Enhancement Added
Added duplicate validation warning when creating a new claim that conflicts with an existing active claim.

### Implementation
Modified `ClaimsFile::add()` in `claims_file.rs` to check for duplicate active claims with the same `concept_path` and `predicate`. When detected, prints a warning:

```
⚠️  Warning: Active claim(s) already exist for path/to/concept::predicate
  - claim-001 (Invariant description)
Consider using 'aphoria claims supersede claim-001' instead
```

### Behavior
- **Supersede**: Automatically marks old claim as `ClaimStatus::Superseded` when creating superseding claim
- **Create**: Warns if creating duplicate active claim (suggests using supersede instead)
- **No breaking changes**: Warning is informational only, claim is still added

### Files Changed
- `applications/aphoria/src/claims_file.rs` (add() method enhanced, 2 new tests added)

### Tests
- `test_supersede()` validates auto-deprecation (already existed)
- `test_duplicate_active_warning()` validates warning is shown
- `test_no_warning_for_deprecated_duplicates()` validates warning only for active claims
- All 1171 aphoria tests pass

---

## Verification

### Build & Test
```bash
# Build
cargo build -p aphoria

# Run all tests
cargo test -p aphoria --lib

# Run clippy
cargo clippy -p aphoria --lib -- -D warnings
```

All checks pass with no warnings.

### Manual Testing
1. **Gap 1**: Run `aphoria scan --mode persistent --sync` and verify observations are created with Tier 4/5 (not Tier 3)
2. **Gap 5**: Run `aphoria claims supersede old-id --new-id new-id ...` and verify old claim status becomes `superseded`
3. **Gap 5**: Run `aphoria claims create` with same concept_path/predicate as existing active claim and verify warning is displayed

---

## Impact

### Gap 1
- **Semantic correctness**: Observations are now properly distinguished from claims in authority weight
- **Query resolution**: Lens calculations will correctly weight observations lower than authored claims
- **Backward compatible**: Existing scans continue to work, just with corrected tier assignment

### Gap 5
- **Lineage enforcement**: Supersession now properly deprecates old claims (already worked)
- **User guidance**: Duplicate warnings help users discover supersede feature
- **No breaking changes**: All existing workflows continue to work

---

## Related Documentation

- `applications/aphoria/docs/vision-gaps.md` - Original gap analysis
- `applications/aphoria/docs/claims-explained.md` - Claim vs observation semantics
- `.aphoria/claims.toml` - Example claims with supersession chains
- `applications/aphoria/src/bridge.rs` - Tier assignment logic

---

## Commit Message

```
fix(aphoria): use confidence-based tiers for observations (Gap 1) + enhance lineage warnings (Gap 5)

Gap 1: Fix Observation Treatment
- Change ingest_claims() to use observation_to_assertion() instead of claim_to_assertion()
- Observations now get Tier 4 (≥0.9 confidence) or Tier 5 (<0.9 confidence) instead of Tier 3
- Semantically correct: observations (grep results) ≠ claims (human-authored rules)

Gap 5: Enhance Lineage Enforcement
- Add duplicate validation warning when creating claims with same concept_path/predicate
- Suggests using 'aphoria claims supersede' instead of creating duplicate actives
- Core auto-deprecation already worked (supersede() marks old claim as Superseded)

All 1171 tests pass. No breaking changes.
```