feat(espn): reprint with default-on self-healing learn loop (store v6→v9)

[mvanhorn]

Reprint: ESPN with default-on self-healing learn loop (store v6 → v9)

Reprint of media-and-entertainment/espn under the current Printing Press (feat/self-improving-learn-loop, 4.27.1 + a ctx-propagation template backport). Provenance: regen-merge, not from-scratch — the ~30 live learnings, 5 .printing-press-patches, and hand-evolved domain code are preserved.

Feature parity verified against origin/main: all 58 flags and every command carry over (the vestigial auth command is intentionally dropped — ESPN is a no-auth API). sync/export/import restored and migrated. Net-new on top: the self-healing derive loop and agent-context/which/schedule.

What's new

• Default-on self-healing derive loop. A flag that fails on one invocation and is corrected on a later one is auto-captured as a flag_alias candidate even when Cobra records no did-you-mean suggestion (inference from the new success-entry flag by edit distance; ambiguous ties skipped).
• Store schema v6 → v9. New internal/store/migration_v6_v9_reprint_test.go opens a populated v6 fixture (learnings + playbooks, user_version=6) and asserts every row survives the upgrade to v9 and that learn_candidates/learn_events are created.

Reconciliation (hand-evolved tree)

• Framework taken fresh: v9 store (FTS/migration machinery), new MCP SDK surface, helpers, client.
• ESPN domain preserved: the search-rerank appliers and all NOVEL commands (boxscore/compare/h2h/odds/scores/streak/rivals/today/sos/dashboard/watch), with the events/news/teams domain store methods isolated into a new internal/store/espn_domain.go (regen-durable).
• pr#850 fixes preserved: ctx propagation upstreamed into the generator templates (see Companion PR); ErrApplierSkip re-injected.
• sync/export/import restored and migrated to the new client/store API. sync is load-bearing — it populates the events store that rivals/streak/search read offline. (The current generator's read-through drop-classification is a separate generator issue worth a retro.)

Live proof (site.api.espn.com)

The World Cup incident heals end-to-end:

1. recall "why did argentina win yesterday world cup" → cold miss (found:false)
2. scoreboard soccer fifa.world --date 20221218 → exit 2 (unknown flag: --date)
3. scoreboard soccer fifa.world --dates 20221218 → exit 0 (live 2022 WC Final)
4. learnings candidates:

{ "class": "flag_alias", "command_path": "scoreboard",
  "failed_flag": "--date", "corrected_flag": "--dates",
  "example": "scoreboard --compact --dates" }

go build ./..., go vet ./..., go test ./..., and govulncheck ./... all pass.

Reviewer notes

• Companion PR (recommended to land alongside): the pr#850 ctx-propagation backport into cli-printing-press learn templates (learnings.go.tmpl / teach.go.tmpl). This PR's generated code already contains the fix and is correct standalone; landing the template change keeps the press and library in sync so a future regen doesn't reintroduce the drift.
• Canonical SKILL/README install sections carry pre-existing drift (shared by all library entries); left untouched for the post-merge sweep-canonical retrofit per its convention.

🤖 Generated with Claude Code

[mvanhorn]

Tracking: #1425. Draft pending (1) the generator-side ctx-backport PR in cli-printing-press, and (2) post-merge sweep-canonical for the SKILL/README install sections.

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for 8b881d4bc91402d4fba071eff54c12e77c3a20d1 after 186s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}

[mvanhorn]

@greptile-apps please review — this exceeds the default 100-file limit because it's a full CLI reprint (framework taken fresh from the current generator). The review-worthy surface is the hand-reconciled/novel code: internal/store/espn_domain.go, internal/store/migration_v6_v9_reprint_test.go, internal/store/learnings.go, internal/mcp/tools.go, internal/cli/sync.go, internal/cli/export.go, internal/cli/import.go, and the restored-command wiring in internal/cli/root.go. The rest is generator-emitted framework.

[greptile-apps]

Greptile Summary

This re-review covers the single fix commit (2c67ba1cb) that landed since the previous pass: correcting the hardcoded tool_count values in handleAbout (7 → 15) and handleContext (11 → 15) to match the 15 typed s.AddTool registrations in RegisterTools. All previously identified issues — missing AddCommand registrations, version reset, PM-domain content in handleContext, PRAGMA identifier guard, and the edit-distance cap in inferCorrectedFlagFromNewSuccessFlag — were resolved in the intermediate commits and remain fixed.

• tool_count corrected in both handlers: handleAbout and handleContext now agree on 15, matching the count of explicit s.AddTool calls (injuries, leaders, news, plays, rankings, scoreboard, summary, teams_get, teams_list, teams_schedule, transactions, sync, sql, search, context/about). The tool_surface note already clarifies that cobratree.RegisterAll adds additional command-mirror tools separately, so agents are not misled.
• All prior findings resolved: novel commands are registered in AddCommand, version string is preserved, handleContext playbook is ESPN-specific sports content (not PM template copy), pragmaColumns validates identifiers, and inferCorrectedFlagFromNewSuccessFlag caps edit distance at min(len(a), len(b)) / 2.

Confidence Score: 5/5

The change is a two-line cosmetic correction to hardcoded metadata values; no logic paths are affected and the counts now accurately reflect the registered tool surface.

The only diff since the previous passing review is updating two integer literals from stale values (7 and 11) to 15 in the handleAbout and handleContext return payloads. The new value matches the count of explicit s.AddTool calls in RegisterTools (15 tools verified by inspection). All prior findings — missing command registrations, version reset, PM-domain context content, SQL identifier guard, and unbounded edit-distance inference — were resolved in earlier commits and are confirmed correct in the current HEAD.

No files require special attention.

Important Files Changed

Filename	Overview
library/media-and-entertainment/espn/internal/mcp/tools.go	Both handleAbout and handleContext now report tool_count: 15, matching the 15 explicit s.AddTool registrations in RegisterTools; all MCP tool definitions, param bindings, and handlers look correct.
library/media-and-entertainment/espn/internal/learn/derive.go	Edit-distance cap (min(len(a), len(b)) / 2, floor 1) is present in inferCorrectedFlagFromNewSuccessFlag; the previously flagged unbounded inference issue is resolved.
library/media-and-entertainment/espn/internal/store/espn_domain.go	pragmaColumns now uses the validIdentifierRE guard before interpolating table names into SQL, matching the pattern used by ListField/ListIDsScoped.
library/media-and-entertainment/espn/internal/cli/root.go	All novel ESPN domain commands (scores, today, boxscore, watch, dashboard, rivals, streak, odds, compare, h2h, sos, trending, recap, search, sql, standings) are now registered via AddCommand.
library/media-and-entertainment/espn/internal/store/migration_v6_v9_reprint_test.go	Migration test opens a populated v6 fixture and asserts all rows survive upgrade to v9 with learn_candidates/learn_events tables created correctly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[MCP Server start] --> B[RegisterTools called]
    B --> C[15 typed s.AddTool registrations\ninjuries, leaders, news, plays, rankings,\nscoreboard, summary, teams_get,\nteams_list, teams_schedule, transactions,\nsync, sql, search, context/about]
    B --> D[cobratree.RegisterAll\nruntime Cobra command-mirror tools]
    C --> E[handleAbout\ntool_count: 15 ✓]
    C --> F[handleContext\ntool_count: 15 ✓\narchetype: content\nplaybook: ESPN sports tips]
    D --> G[Shell-out to espn-pp-cli\nfor novel commands]
    E --> H[Agent gets accurate surface metadata]
    F --> H

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[MCP Server start] --> B[RegisterTools called]
    B --> C[15 typed s.AddTool registrations\ninjuries, leaders, news, plays, rankings,\nscoreboard, summary, teams_get,\nteams_list, teams_schedule, transactions,\nsync, sql, search, context/about]
    B --> D[cobratree.RegisterAll\nruntime Cobra command-mirror tools]
    C --> E[handleAbout\ntool_count: 15 ✓]
    C --> F[handleContext\ntool_count: 15 ✓\narchetype: content\nplaybook: ESPN sports tips]
    D --> G[Shell-out to espn-pp-cli\nfor novel commands]
    E --> H[Agent gets accurate surface metadata]
    F --> H

Loading

_{Reviews (6): Last reviewed commit: "fix(espn): correct stale MCP tool_count ..." | Re-trigger Greptile}

[mvanhorn]

Both Greptile findings addressed in 3d44a5b1:

1. handleContext domain content — archetype project-management → content, and the PM-template playbook tips replaced with ESPN-specific guidance (scoreboard/--dates, summary for the richest payload, sync for offline). Root cause is the generator profiler misclassifying espn's domain as project-management — filing that as a separate generator retro so future prints get the right DomainContext instead of a per-CLI patch.
2. pragmaColumns identifier guard — added the validIdentifierRE.MatchString guard before interpolating the table name, consistent with the rest of the store package.

go build/vet/test ./... and govulncheck still clean.

[mvanhorn]

@greptile-apps please re-review at 3d44a5b — both prior findings are fixed (handleContext domain content, pragmaColumns guard). The 131-file count is a full CLI reprint; the hand-written surface to review is internal/store/espn_domain.go, internal/store/migration_v6_v9_reprint_test.go, internal/mcp/tools.go, internal/cli/{sync,export,import}.go, and internal/cli/root.go wiring.

[greptile-apps]

Greptile Summary

This PR introduces a self-healing derive loop for the ESPN CLI reprint, migrating the SQLite store from schema v6 to v9 by adding learn_candidates and learn_events tables, a journal-based derivation pipeline that auto-captures flag-correction candidates from post-run journal pairing, and new learnings candidates CLI commands for reviewing/confirming/rejecting auto-derived suggestions.

• Store migration (v6→v9): Additive-only CREATE TABLE IF NOT EXISTS migrations preserve all existing rows; a pinned TestMigrateV6PopulatedStoreUpgradesToV9 fixture verifies 3 learnings and 2 playbooks survive the upgrade with the two new v9 tables created.
• Derive loop (learn/derive.go): DeriveFlagCorrections tail-scans the JSONL journal, pairs flag-failure/success entries within a 15-minute same-session window, and calls DeriveCandidate to upsert quarantined candidates into learn_candidates.
• Root entrypoint rewrite (cli/root.go): Switches from Execute() to ExecuteC() with deferred journaling/derivation on every invocation; removes SilenceErrors and the manual fmt.Fprintln error print in main.go to avoid double-printing.

Confidence Score: 3/5

Not safe to merge: the missing AddCommand registrations make every novel ESPN domain command unreachable at runtime.

Score 3 reflects one blocking P1 defect (all domain commands absent from root) that would make the binary silently broken for all ESPN-specific subcommands, alongside two P2 concerns (uncapped edit distance, version downgrade). The store migration, journal, derive logic, and candidate store are all well-implemented.

library/media-and-entertainment/espn/internal/cli/root.go requires immediate attention — the AddCommand block (lines 266–303) must include all domain command constructors before this PR can ship.

Important Files Changed

Filename	Overview
library/media-and-entertainment/espn/internal/cli/root.go	Rewrites Execute() to use ExecuteC() with deferred journal/derive; critical P1 bug — all novel ESPN domain commands are defined but never registered with AddCommand
library/media-and-entertainment/espn/internal/learn/derive.go	New derive pipeline: journal tail-scan, 15-min same-session pairing, DeriveCandidate upsert; edit-distance inference has no distance cap (P2)
library/media-and-entertainment/espn/internal/store/candidates.go	New candidates lifecycle: DeriveCandidate upsert with tombstone, ConfirmCandidate/RejectCandidate transactions, ExpireCandidates TTL sweep, PurgeCandidates cleanup — all correct
library/media-and-entertainment/espn/internal/store/store.go	Schema bumped to v9; additive migrations add learn_candidates and learn_events; double-check prevents downgrade race; backfillColumns handles existing columns correctly
library/media-and-entertainment/espn/internal/store/migration_v6_v9_reprint_test.go	Pins v6→v9 migration contract with verbatim v6 DDL fixture; verifies 3 learnings and 2 playbooks survive and new v9 tables are created
library/media-and-entertainment/espn/internal/learn/journal.go	Append-only JSONL journal with O_APPEND single-write, retention caps, tolerant reader for torn lines, atomic offset persistence
library/media-and-entertainment/espn/internal/cli/learnings_candidates.go	New candidates subcommands (list/confirm/reject/purge); materializeCandidate dispatches per class; promoteCandidateOnTeach convergence is best-effort
library/media-and-entertainment/espn/internal/cli/version.go	Extracted version constant; silently resets from 2026.6.2 to 1.0.0 (P2 version downgrade)

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Main as main.go
    participant Exec as root.Execute
    participant Cobra as rootCmd.ExecuteC
    participant Journal as journalInvocation
    participant Derive as deriveFlagCorrections
    participant Store as SQLite Store

    Main->>Exec: Execute(args)
    Exec->>Exec: defer journalInvocation + deriveFlagCorrections
    Exec->>Cobra: rootCmd.ExecuteC()
    Cobra-->>Exec: cmd, err
    Note over Exec: isCobraUsageError? → usageErr (exit 2)
    Exec->>Journal: AppendJournalEntry(argv, outcome)
    Journal-->>Exec: offset advanced
    Exec->>Derive: DeriveFlagCorrections(openStore, flagExists)
    Derive->>Journal: ReadJournalFrom(lastOffset)
    Journal-->>Derive: entries[]
    Derive->>Derive: pairFlagCorrections(entries)
    alt pairs found
        Derive->>Store: OpenWithContext(dbPath)
        Derive->>Store: DeriveCandidate(class, payload, sig)
        Store-->>Derive: CandidateRow, inserted
        Derive->>Journal: StoreJournalOffset(newOffset)
    end
    Derive-->>Exec: done
    Exec-->>Main: retErr

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Main as main.go
    participant Exec as root.Execute
    participant Cobra as rootCmd.ExecuteC
    participant Journal as journalInvocation
    participant Derive as deriveFlagCorrections
    participant Store as SQLite Store

    Main->>Exec: Execute(args)
    Exec->>Exec: defer journalInvocation + deriveFlagCorrections
    Exec->>Cobra: rootCmd.ExecuteC()
    Cobra-->>Exec: cmd, err
    Note over Exec: isCobraUsageError? → usageErr (exit 2)
    Exec->>Journal: AppendJournalEntry(argv, outcome)
    Journal-->>Exec: offset advanced
    Exec->>Derive: DeriveFlagCorrections(openStore, flagExists)
    Derive->>Journal: ReadJournalFrom(lastOffset)
    Journal-->>Derive: entries[]
    Derive->>Derive: pairFlagCorrections(entries)
    alt pairs found
        Derive->>Store: OpenWithContext(dbPath)
        Derive->>Store: DeriveCandidate(class, payload, sig)
        Store-->>Derive: CandidateRow, inserted
        Derive->>Journal: StoreJournalOffset(newOffset)
    end
    Derive-->>Exec: done
    Exec-->>Main: retErr

Loading

Comments Outside Diff (1)

1. library/media-and-entertainment/espn/internal/learn/derive.go, line 1-391 (link)

   No maximum edit-distance cap in inferCorrectedFlagFromNewSuccessFlag

   inferCorrectedFlagFromNewSuccessFlag picks the success-argv flag with the minimum Levenshtein distance to the failed flag, but applies no upper-bound cap. A failed flag --date with no close match in a success argv containing only --standings-type or --sport will still "infer" a correction, producing a spurious flag_alias candidate that maps an unrelated flag. The standard heuristic caps at min(len(a), len(b))/2 or a fixed small constant (e.g. 3); without it, low-sighting noise candidates accumulate for every flag-error/success pair even when the flag names share no meaningful prefix.

   

_{Reviews (2): Last reviewed commit: "fix(espn): correct MCP context domain + ..." | Re-trigger Greptile}

[mvanhorn]

All three findings fixed in 48266df0:

1. P1 — novel commands unregistered (blocking). Correct and serious catch. Taking root.go fresh dropped the AddCommand block for all 16 hand-authored domain commands; they compiled but were unreachable. Restored the full registration block and verified every published top-level command and subcommand now resolves against a freshly-built published binary (only the vestigial no-auth auth command remains intentionally dropped).
2. P2 — version downgrade. version.go now preserves the public-library release version 2026.6.2 (from .printing-press-release.json) instead of the fresh 1.0.0 skeleton.
3. P2 — uncapped edit distance. inferCorrectedFlagFromNewSuccessFlag now caps the inferred correction at min(len(failed), len(best))/2 (floor 1), so an unrelated new success flag (e.g. --sport when --date failed) is no longer promoted as a spurious flag_alias. Added a negative test. The same cap will land in the generator template via the companion cli-printing-press PR.

go build/vet/test ./... green.

@greptile-apps please re-review at 48266df0 (131-file reprint exceeds the default limit).

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for 2c67ba1cb761f757f999c049ec9e9b93f25d7d59 after 186s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}

[mvanhorn]

@greptile-apps re-review at 2c67ba1 — the only new change since the 5/5 pass is the cosmetic tool_count fix you noted (stale 7/11 -> 15, matching the registered typed tools).