Repo+Story is a PR/repo-history narrative for review & maintenance. It ingests a repository's git event-stream — commits × file mutations × authors, the data Gource consumes, not its animation — and produces a clustered, blast-radius-aware story in which every claim is cited back to its source commit. Reviewers and maintainers read what changed, why it matters, and what it touches — instead of re-deriving it from raw history.
Repo history is write-only memory: commits, PRs and file mutations accumulate, but the story — what changed together, what it put at risk, who touched it — must be re-derived by every reviewer and maintainer, every time.
A chronological evolution, not a static diff — narrated by a “technical code chronicler”, with strict markdown citations: [Description](commit_hash).
STEP 1 · INGEST
Commits × file mutations × authors — the Gource data plane, not its animation.
STEP 2 · CLUSTER
Events grouped by change coupling, file neighborhoods, authorship, and time windows — past a noise filter (lockfiles, linters), with rename lineage kept.
STEP 3 · BLAST RADIUS
Each unit carries its touched-surface footprint: co-changing file clusters are implicit dependencies, made explicit.
STEP 4 · NARRATE
The story is generated with every claim cited ↦ its source commit. An uncited claim does not ship.
STEP 5 · PUBLISH
A GitHub Action posts and updates a sticky story on the PR.
Concrete artifacts in the spec: extract_pr_story_context and mine_pr_evolution (file-coupling matrix; payload {metadata, chronological_stream, architectural_coupling}) · workflow .github/workflows/pr_storyteller.yml. The narrative model reads the Iteration Path (change → rewrite → revert = an architectural dead-end story) and the Why-behind-What (commit messages × line diffs = an auditable trail).
Alerts on the surfaces a change actually puts at risk — drawn from the coupling and blast-radius analysis, not the diff alone.
Automated changelogs where every line carries its receipt: a citation back to the source commit.
Blame with the story attached — not just who touched a line, but the change narrative it belongs to.
A file changed without its coupled test file — e.g. routes/user.py changed without tests/test_user.py — raises a warning before human review.
pr_storyteller.yml on pull_request: [opened, synchronize] — posts the story as the sticky first PR comment.
A lightweight local run that produces a draft PR description before the push lands.
The pinned markdown Story on the PR thread — the durable, readable record of the change.
Persistence is decided in Spec v2: the hybrid is the adopted target — merge → Action → central datastore → coupling alerts → pinned Story — and v0 sequencing starts with M1, the .story/ orphan-ref store. The I1 candidate set is the record the decision was drawn from: .story/ PR-{id}.json (git-native, orphan refs/notes) · a ChromaDB local vector index (.story_vector_db) · a SQL chrono-graph (Commits / FileMutations / Coupling tables, with a shared_commit_count smell flag). One primary store — the set is options, not a commitment to all three.
Repo+Story is a concept of record with a buildable spec — nothing here is a shipped product yet, and this page claims nothing built, live, or entered.
The source conversation titles this concept “PR+Story”; the fleet name of record is Repo+Story — one concept, two titles.