jml e95c978481 feat(aphoria): add inline claim markers and claim enrichment infrastructure

This commit implements Phase 17 of the Aphoria roadmap, adding:

**Inline Claim Markers (@aphoria:claim):**
- New extractor for detecting inline markers in comments
- Pending markers tracked in .aphoria/pending_markers.toml
- CLI commands: list-markers, formalize-marker, reject-marker
- Support for all major comment styles (Rust, Python, SQL, etc.)
- Auto-sync during scan (configurable)

**Claim Enrichment:**
- ClaimEnrichment type with source attribution (inline, extractor, manual)
- EnrichedClaimInfo with full enrichment metadata
- Extended AuthoredClaim with optional enrichment field
- API endpoints for enriched claim queries
- Dashboard UI components (enrichment badge, verdict badge)

**Enhanced Extractor Trait:**
- verifiable_predicates() method for declaring (tail_path, predicate) pairs
- 10 security extractors now implement verifiable_predicates
- Enables claim suggester skill to find unclaimed patterns

**Documentation:**
- Phase 17 summary with complete implementation details
- Gap fixes summary documenting 8 closed vision gaps
- Updated CLI reference with new commands
- New aphoria-docs skill for documentation maintenance
- Updated roadmap with Phase 17 completion

**Integration:**
- ClaimsFile support for claim enrichment persistence
- Pattern aggregate store support for enrichment queries
- Dashboard filters and display for enrichment metadata
- API handlers for list-markers and enrichment queries

**Tests:**
- New gap_fixes_integration test suite
- Corpus enricher module with best practices ingestion

Closes: VG-005, VG-017, VG-018, VG-019, VG-020, VG-021, VG-022, VG-023

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-08 20:18:20 +00:00

4.4 KiB

Raw Blame History

The Open Vision: The Epistemic Assertion Protocol (EAP)

Protocol Vision: This document describes the Epistemic Assertion Protocol (EAP) - an open standard for publishing authoritative technical knowledge. For Aphoria's product vision, see Vision.

From "Reading the Manual" to "Querying the Truth."

The Stagnation of Truth

For 40 years, the authoritative "Truth" of software engineering has been locked in dead formats:

RFCs are ASCII text files.
OWASP Standards are Markdown wikis.
Vendor Recommendations are HTML documentation portals.

These formats are designed for Human Consumption. But humans are no longer the only ones writing code.

AI Agents cannot "read" an RFC and "understand" the nuance of a SHOULD vs. a MUST reliably enough for safety-critical systems. They need structured data. They need a protocol.

The Proposal: A Universal Standard for Truth

We propose the Epistemic Assertion Protocol (EAP): an open standard for publishing authoritative technical knowledge as graph-ready assertions.

Aphoria is not just a linter; it is the Reference Implementation (Browser) for this new web of data.

1. The Protocol Layers

Layer 1: Truth Publishing (The Supply Side)

Instead of just publishing a PDF, standards bodies and vendors publish an EAP Manifest.

The IETF publishes rfc7519.eap.json: Machine-readable definitions of JWT claims, mandatory validations, and algorithmic constraints.
AWS publishes rds-postgres.eap.json: Recommended connection pool sizes, timeout settings, and SSL modes, versioned by engine release.
Corporate Security publishes corp-policy.eap.json: Internal overrides for encryption standards.

The Win: Vendors stop writing "Best Practices" guides that nobody reads. They publish "Best Practices" data that tools automatically enforce.

Layer 2: Semantic Mapping (The Bridge)

The protocol defines a universal namespace for software concepts (ConceptPaths).

concept://net/tls/verification
concept://auth/jwt/audience
concept://db/connection/timeout

This allows a Rust extractor, a Go extractor, and a Python extractor to all map their specific implementation details to the same universal concept.

Layer 3: The Consumption Engine (The Demand Side)

Any tool can consume EAP data.

IDEs can highlight a config value and say: "AWS recommends 30s here (Tier 2 Authority)."
CI Pipelines can block merges based on Policy.
AI Agents can query the protocol before writing code: "What is the mandatory TLS version for this service type?"

Why This Wins (The Strategy)

1. The "Wikipedia" Effect

If we try to ingest the world's knowledge ourselves, we lose. If we provide the standard format for knowledge, the world does the work for us.

Phase 1 (Aphoria): We scrape and ingest (current state).
Phase 2 (Community): Open Source maintainers contribute EAP definitions for their libraries to stop users from misconfiguring them.
Phase 3 (Standard): "EAP Compatible" becomes a requirement for enterprise adoption of new libraries.

2. The Agentic Moat

AI Agents fundamentally change the market.

Old World: Developers read docs.
New World: Agents query APIs. There is currently NO API for "Is this architectural decision correct?" Aphoria + EAP becomes that API. We become the DNS for Truth.

3. Commoditizing the Linter, Monopolizing the Graph

Traditional linters (ESLint, Pylint) are commodities. By making the assertions an open standard, we encourage widespread adoption. However, StemeDB (the engine that efficiently stores, versions, and resolves conflicts in this massive graph) remains the high-performance proprietary/core engine required to run this at scale.

The Future Workflow

Vendor Release: Redis releases v8.0. They publish redis-v8.eap detailing new timeout behaviors.
Global Ingest: The global Aphoria network ingests this update.
Local Alert: 10,000 developers (and 50,000 AI agents) wake up to a "Config Drift" warning. Their code hasn't changed, but the Truth regarding that code has.
Auto-Remediation: The Agent sees the conflict, reads the EAP recommendation, and opens a PR to update the config.

Aphoria is not just finding bugs. It is synchronizing the state of the world's code with the state of the world's knowledge.

4.4 KiB Raw Blame History