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:

let assertion = claim_to_assertion(claim, &self.signing_key, timestamp, git_commit.as_deref());

To:

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

# 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.