feat(parser): add provider facade core

Introduce the Provider interface, ProviderBase/ProviderFactory, and source-set
helpers; own provider discovery and lookup at the root; and add the
legacy-call shim scan that gates provider files.

fix(parser): cover Aider, OMP, Reasonix in migration manifest

These agents live in the registry but were absent from the provider
migration manifest, so ValidateProviderMigrationModes failed once the
registry began enforcing that every agent has a mode. They remain on the
legacy path here; later stack commits migrate them to concrete providers
and flip these entries to provider-authoritative.

fix(sync): keep shadow provider discovery observational

Shadow provider mode must not add provider-only work or satisfy source lookups that the legacy runtime would miss. Otherwise a migration comparison can change live sync behavior before the provider becomes authoritative.\n\nProvider-authoritative discovery now reports discovery failures as sync failures and suppresses the provider completion watermark for that run, preserving the next incremental pass. The shim scan also keeps pending exemptions honest by failing stale entries while ignoring provider-owned selector methods.\n\nValidation: go test -tags "fts5" ./internal/parser -run 'TestProviderFilesDoNotReferenceLegacyEntrypoints' -count=1; go test -tags "fts5" ./internal/sync -run 'Test(DiscoverProviderSourcesOnlyRunsAuthoritativeProviders|SyncAllProviderDiscoveryFailureSkipsFinishedWatermark|FindSourceFileFallsBackToAuthoritativeNonFileProvider|ClassifyProviderChangedPath|ProcessFileShadow|ProcessFileProviderAuthoritative|ProviderVirtualSourceBackedByEvent)' -count=1; go test -tags "fts5" ./internal/parser ./internal/sync -count=1; go vet ./...; git diff --check

docs(parser): clarify provider freshness contract

The facade spec still described successful parses as eligible for a clean skip-cache entry, which conflicts with the no-schema-change data-version model and can leave unchanged sessions stale after parser upgrades.\n\nDocument stored changed-path hints explicitly and keep successful unchanged-source freshness tied to DB metadata plus parser data version, reserving skipped_files for retry, failure, and explicit skip cases.\n\nValidation: go test -tags "fts5" ./internal/parser -run 'TestProviderFilesDoNotReferenceLegacyEntrypoints' -count=1; git diff --check. mdformat ran via commit hook.

docs(parser): pin provider source identity semantics

The facade contract needs to say exactly which provider source key is persisted because the migration intentionally avoids a schema change. Without that rule, providers could diverge between SourceRef, SourceFingerprint, and sessions.file_path identities.\n\nAlso define capability conformance by meaningful field presence so unsupported zero-value fields are treated consistently in provider tests.\n\nValidation: git diff --check. mdformat is unavailable on PATH, but the commit hook ran.

style(docs): mdformat provider dual-run harness plan

Author: mariusvniekerk

Makefile

@@ -332,7 +332,15 @@ nilaway-golangci-build:
 
 # Run NilAway through the custom golangci-lint module plugin.
 nilaway: pricing-snapshot ensure-embed-dir nilaway-golangci-build
-	$(CUSTOM_GCL) run --config .golangci.nilaway.yml ./...
+	@set -e; \
+	root=$$(pwd); \
+	dirs=$$(go list -f '{{.Dir}}' ./...); \
+	for dir in $$dirs; do \
+		pkg="./$${dir#$$root/}"; \
+		echo "$(CUSTOM_GCL) run --config .golangci.nilaway.yml $$pkg"; \
+		GOMAXPROCS=$${GOMAXPROCS:-1} GOGC=$${GOGC:-10} GOMEMLIMIT=$${GOMEMLIMIT:-512MiB} \
+			$(CUSTOM_GCL) run --config .golangci.nilaway.yml "$$pkg"; \
+	done
 
 # Install pinned local lint tools.
 lint-tools:

docs/superpowers/plans/2026-06-20-provider-dual-run-harness.md

@@ -0,0 +1,308 @@
+# Provider Dual-Run Harness Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use
+> superpowers:subagent-driven-development (recommended) or
+> superpowers:executing-plans to implement this plan task-by-task. Steps use
+> checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add the root-level provider migration harness so provider branches
+must opt into shadow comparison instead of only adding parallel provider
+implementations.
+
+**Architecture:** The parser package owns the per-`AgentType` migration manifest
+because provider branches already change parser factories. The sync package owns
+the source-level observation helper because it converts provider `Fingerprint`
+and `Parse` calls into engine-shaped planned effects without touching the live
+database.
+
+**Tech Stack:** Go 1.26, `testing`, `github.com/stretchr/testify`, git-spice
+stacked branches.
+
+**Migration mode semantics:**
+
+- `legacy-only`: only the legacy parser/sync path runs and writes. This is the
+  default for legacy adapter providers and is allowed for concrete providers
+  only with an explicit rollback note and open follow-up task.
+- `shadow-compare`: the legacy path remains authoritative for DB writes,
+  skip-cache persistence, data-version rows, source metadata, diagnostics,
+  SSE, and return values. The provider path runs through the shared provider
+  runner and produces normalized in-memory planned effects. Tests compare
+  those planned effects against the legacy outcome; runtime mismatches are
+  developer diagnostics only and must not create user-visible parse
+  diagnostics.
+- `provider-authoritative`: the provider path owns writes and return values and
+  the old provider-specific legacy branch is gone. This mode is reserved for
+  the stack tip after every parse-capable provider has passed shadow
+  comparison.
+- `import-only`: the provider is intentionally excluded from filesystem parse
+  comparison because it represents non-filesystem import/export metadata
+  rather than a parser replacement.
+
+Promotion requires fixture evidence for parsed sessions, exclusions, skip-cache
+keys, data-version state, source metadata, diagnostics, retry state, and
+source-key/session-ID compatibility. Rollback means moving the manifest entry
+back to `legacy-only`, recording the reason in kata/review notes, and leaving
+the legacy path authoritative until the mismatch is fixed.
+
+Provider observations must reject cross-provider output before planning effects
+and before any remote machine prefix is applied. `ParseResult.Session.Agent`
+must equal the provider `AgentType`. Persisted session IDs in the result graph
+must use the provider's ID prefix when one exists; this includes result IDs,
+parent IDs, usage-event session IDs, subagent links, exclusions, and diagnostic
+session IDs. Diagnostic `SourceError.SourceKey` values are required and must be
+the provider fingerprint key, `SourceRef.FingerprintKey`, `SourceRef.Key`, or a
+virtual key derived from one of those candidates by appending `#`, `::`, or `|`.
+
+`ProviderPlannedEffects` is an engine-shaped comparison model, not a second
+writer. Its source key is the fingerprint key when available, then
+`SourceRef.FingerprintKey`, then `SourceRef.Key`. Its skip-cache key follows the
+same engine order used for persisted skip decisions. Its data-version entries
+match the rows the legacy engine would stamp after successful writes, including
+retry state from `DataVersionNeedsRetry`. Its diagnostics mirror parse
+diagnostics without inserting them into the live store. Provider retry-reason
+text and SSE scopes are outside the root process-result comparison until a later
+caller task exposes equivalent legacy data.
+
+Performance rule: shadow comparison may double-parse a source only while that
+provider is actively migrating. Large roots and shared database providers need
+fixture or benchmark coverage before promotion, and caller-level shadow wiring
+must keep provider failures from blocking legacy writes unless a test is
+explicitly asserting the mismatch.
+
+______________________________________________________________________
+
+### Task 1: Provider Migration Manifest
+
+**Files:**
+
+- Create: `internal/parser/provider_migration.go`
+
+- Modify: `internal/parser/provider_test.go`
+
+- [ ] **Step 1: Write the failing manifest tests**
+
+Add tests that prove the manifest covers the registry and rejects a concrete
+provider left in `legacy-only` mode:
+
+```go
+func TestProviderMigrationModesCoverRegistry(t *testing.T) {
+	err := ValidateProviderMigrationModes(ProviderFactories(), ProviderMigrationModes())
+	require.NoError(t, err)
+}
+
+func TestProviderMigrationModesRejectConcreteProviderLeftLegacyOnly(t *testing.T) {
+	factory := testProviderFactory{def: AgentDef{Type: AgentCodex, DisplayName: "Codex"}}
+	modes := map[AgentType]ProviderMigrationMode{
+		AgentCodex: ProviderMigrationLegacyOnly,
+	}
+
+	err := ValidateProviderMigrationModes([]ProviderFactory{factory}, modes)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "codex")
+	assert.Contains(t, err.Error(), "shadow-compare")
+}
+```
+
+- [ ] **Step 2: Run the parser tests and verify RED**
+
+Run:
+
+```bash
+go test -tags "fts5" ./internal/parser -run TestProviderMigrationModes -count=1
+```
+
+Expected: FAIL because `ProviderMigrationMode`, `ProviderMigrationModes`, and
+`ValidateProviderMigrationModes` do not exist yet.
+
+- [ ] **Step 3: Implement the manifest types and validation**
+
+Create `internal/parser/provider_migration.go` with:
+
+```go
+type ProviderMigrationMode string
+
+const (
+	ProviderMigrationLegacyOnly          ProviderMigrationMode = "legacy-only"
+	ProviderMigrationShadowCompare       ProviderMigrationMode = "shadow-compare"
+	ProviderMigrationProviderAuthoritative ProviderMigrationMode = "provider-authoritative"
+	ProviderMigrationImportOnly          ProviderMigrationMode = "import-only"
+)
+```
+
+Add a registry-covering manifest initialized to `legacy-only`, return copies to
+callers, and validate:
+
+- every provider factory has one mode;
+
+- no extra manifest entry points at an unknown agent;
+
+- concrete non-legacy factories cannot remain `legacy-only`;
+
+- `shadow-compare`, `provider-authoritative`, and `import-only` require a
+  concrete factory;
+
+- `import-only` is allowed only for Claude.ai and ChatGPT.
+
+- [ ] **Step 4: Run the parser tests and verify GREEN**
+
+Run:
+
+```bash
+go test -tags "fts5" ./internal/parser -run TestProviderMigrationModes -count=1
+```
+
+Expected: PASS.
+
+### Task 2: Source-Level Provider Observation
+
+**Files:**
+
+- Create: `internal/sync/provider_shadow.go`
+
+- Create: `internal/sync/provider_shadow_test.go`
+
+- [ ] **Step 1: Write failing observation tests**
+
+Add tests that use a fake provider to prove the helper:
+
+- calls `Fingerprint` before `Parse`;
+- converts `ParseOutcome` into an observation;
+- records planned data-version/source/diagnostic effects in memory;
+- never accepts a mismatched `SourceRef.Provider`;
+- rejects provider results, exclusions, and diagnostics whose agent or persisted
+  session-ID namespace belongs to another provider.
+
+The main test should assert:
+
+```go
+assert.Equal(t, []string{"fingerprint", "parse"}, provider.calls)
+assert.Equal(t, []string{"codex:one"}, observation.Planned.DataVersionSessionIDs())
+assert.Equal(t, []string{"codex:two"}, observation.Planned.RetrySessionIDs())
+assert.Equal(t, []string{"source-key"}, observation.Planned.SourceKeys)
+assert.Len(t, observation.Planned.Diagnostics, 1)
+```
+
+- [ ] **Step 2: Run the sync tests and verify RED**
+
+Run:
+
+```bash
+go test -tags "fts5" ./internal/sync -run TestObserveProviderSource -count=1
+```
+
+Expected: FAIL because `ObserveProviderSource` and observation types do not
+exist.
+
+- [ ] **Step 3: Implement the minimal observation helper**
+
+Create `internal/sync/provider_shadow.go` with:
+
+```go
+type ProviderObserveRequest struct {
+	Source     parser.SourceRef
+	Machine    string
+	ForceParse bool
+}
+
+type ProviderObservation struct {
+	Results            []parser.ParseResult
+	ExcludedSessionIDs []string
+	SourceErrors       []parser.SourceError
+	SkipReason         parser.SkipReason
+	ForceReplace       bool
+	Planned            ProviderPlannedEffects
+}
+```
+
+`ObserveProviderSource` checks the source/provider type match, calls
+`Fingerprint`, calls `Parse`, validates provider output invariants, and builds
+in-memory planned effects. It must not accept a `db.DB`, `Engine`, writer
+callback, or mutable skip-cache reference.
+
+- [ ] **Step 4: Run the sync tests and verify GREEN**
+
+Run:
+
+```bash
+go test -tags "fts5" ./internal/sync -run TestObserveProviderSource -count=1
+```
+
+Expected: PASS.
+
+### Follow-Up: Caller-Level Wiring
+
+**Files:**
+
+The root harness branch wires the shared `processFile` shadow comparison. The
+remaining caller families below stay as later sync migration work so provider
+branches can add caller-specific source selection, hint lookup, and acceptance
+coverage one behavior group at a time.
+
+**Step 1: Wire remaining source-processing callers into shadow comparison**
+
+Move changed-path sync and `SyncSingleSession` semantics into the caller-level
+dual-run wrapper without adding a duplicate `processFile` hook. These callers
+reuse the shared `processFile` observation for parse comparison, then add
+caller-specific source selection, stored-source hints, and acceptance assertions
+around that observation. They must leave live DB/diagnostic/SSE state driven
+only by the legacy result.
+
+**Step 2: Add lookup/watch/diagnostic caller coverage**
+
+Move session watch flows, export/source lookup, source mtime, token-usage raw
+source probing, parse-diff, and parse diagnostics through the same provider
+runner. Tests must cover source lookup freshness, virtual paths, source mtime,
+raw probing behavior, report shape, and source-error behavior.
+
+**Step 3: Define runtime mismatch reporting**
+
+Mismatches are test failures in shared parity tests. Runtime mismatch reporting
+is developer-only logging or debug diagnostics and must include provider, source
+key, fingerprint key, mode, field path, legacy value summary, provider value
+summary, and whether fingerprinting or parsing failed. It must not persist
+user-visible parse diagnostics while `shadow-compare` is active.
+
+### Task 3: Validation And Commit
+
+**Files:**
+
+- Modify as needed from Tasks 1-2.
+
+- [ ] **Step 1: Format and verify**
+
+Run:
+
+```bash
+go fmt ./...
+go test -tags "fts5" ./internal/parser -run TestProviderMigrationModes -count=1
+go test -tags "fts5" ./internal/sync -run TestObserveProviderSource -count=1
+go test -tags "fts5" ./internal/parser -count=1
+go test -tags "fts5" ./internal/sync -count=1
+go vet ./...
+git diff --check
+```
+
+Expected: all commands pass. If `go fmt ./...` rewrites unrelated comments,
+restore only unrelated user-owned changes before committing.
+
+- [ ] **Step 2: Commit on `provider-facade-core`**
+
+Commit the root harness slice with a conventional message:
+
+```bash
+git add docs/superpowers/plans/2026-06-20-provider-dual-run-harness.md internal/parser/provider_migration.go internal/parser/provider_test.go internal/sync/provider_shadow.go internal/sync/provider_shadow_test.go
+git commit -m "feat(parser): add provider migration harness"
+```
+
+- [ ] **Step 3: Restack locally when explicitly authorized**
+
+If the user has explicitly authorized branch changes and restacking for this
+session, run:
+
+```bash
+git-spice upstack restack
+```
+
+Expected: dependent provider branches are replayed on the harness branch and
+conflicts are resolved provider by provider. Do not push, submit, or update PRs
+unless the user has separately authorized that network operation.