feat(mine): enrich decisions with GitHub PR text (kb mine --prs, ADR slice 2) (#36)

New kb.git.forge module - the ONLY networked step in the toolchain,
strictly opt-in: PRProvider protocol + GitHubPRProvider (stdlib urllib,
GITHUB_TOKEN/GH_TOKEN optional), origin_slug and
pr_number_from_subject (squash '(#NN)' anchor).

PR text feeds the prompt (own system prompt) and the payload (capped) -
context and fact, never grounding. PR text is MUTABLE after merge, so
a digest of the capped text is folded into framework_versions
(identity-bearing, the sink-registry precedent): an edited PR yields a
NEW artifact id, never a silent payload swap. The enriched prompt pins
prompt_version '2+pr1'; plain prompts and plain ids stay byte-
identical. A failed fetch degrades to the byte-identical plain
artifact, counted per run. Merge commits stay skipped.

ADR-mining gate grows six tests; headline HARD gates stay fifteen.
Verified live against real GitHub + LLM before merge.

Author: v0ropaev

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **PR-description mining — ADR slice 2** (`kb mine --prs`, `kb.git.forge`): decisions mined
+  from squash-merged commits (subject ending in `(#NN)`) are enriched with the pull request's
+  title and body, fetched from api.github.com via a new `PRProvider` protocol +
+  `GitHubPRProvider` (stdlib urllib; `GITHUB_TOKEN`/`GH_TOKEN` optional — anonymous works for
+  public repos; `--repo-slug` overrides the origin-derived `owner/name`). **Strictly opt-in and
+  the only networked step in the toolchain**: without `--prs`, behavior is byte-identical to
+  slice 1. PR text is prompt context and a payload fact (`pr_number`/`pr_title`/`pr_body`,
+  capped) — never grounding; and because PR text is MUTABLE after merge, a digest of the capped
+  text is folded into `framework_versions` (identity-bearing, the sink-registry precedent), so
+  an edited PR yields a NEW artifact id instead of a silent payload swap. The enriched prompt
+  runs under its own system prompt and carries its own `prompt_version` (`"2+pr1"`); the plain
+  prompt stays byte-identical. A failed fetch (404 / network / rate limit) degrades softly to
+  the byte-identical plain artifact and is counted per run (`pr_enriched` / `pr_fetch_failed`
+  in the CLI summary) — exactly two identities exist per (sha, model): plain and
+  enriched(digest). The ADR-mining HARD gate grows six tests (enrichment identity, floor under
+  enrichment, post-merge-edit → new id, fetch-failure degradation, no-PR byte-compat, slug and
+  provider parsing incl. fail-soft HTTP paths); headline HARD gates stay **fifteen**.
+
 ## [0.8.0] - 2026-07-09
 
 ### Fixed

DESIGN.md

@@ -89,7 +89,13 @@ Two reframings carried from review:
 - **ADRs are not extractable from code.** Code shows "we use Kafka now", not "we switched
   because RabbitMQ couldn't handle load". ADR candidates are mined from git history + commit
   messages + PR descriptions. Separate pipeline — **local commit history shipped (slice 1,
-  `kb mine`); PR-description mining deferred** (needs a network adapter; `kb.git` stays local).
+  `kb mine`); PR-description mining shipped (slice 2, `kb mine --prs` — strictly opt-in: the
+  only networked step in the toolchain, off the index/serve paths and OFF by default;
+  `kb.git.forge` fetches a squash-merged commit's PR title/body from api.github.com). PR text is
+  context for the LLM and a payload fact — never grounding; and because PR text is MUTABLE after
+  merge, a digest of the capped text is folded into `framework_versions` (identity-bearing, the
+  sink-registry precedent) so an edited PR yields a NEW artifact id instead of a silent payload
+  swap. A failed fetch degrades to the byte-identical plain artifact, counted per run.**
   The D5 grounding bridge: a `decision` artifact is grounded on the spans its source commit
   **changed** (present at the commit, absent at its first parent — the commit's diff is the
   decision's footprint in code), so even prose-born knowledge points at exact code spans. The
@@ -290,7 +296,7 @@ test.)
 EMBED stage; tsvector/`pg_search`/BM25/RRF; snapshot Merkle-root; the runtime `app.openapi()`
 sandbox oracle (eval-only, later milestone — it executes user code); the grounded
 business-process/LLM layer (call-graph slicing, sink registry, labeler, validator); ADR mining
-(slice 1 since shipped — `kb mine`; PR mining still deferred);
+(both slices since shipped — `kb mine` / `kb mine --prs`);
 multi-branch dedup, mutable branch pointers exercise; eval Tiers 2/3 (build when the artifacts
 they score exist; stub the Tier-3 question schema now); GC; SCIP/scip-python upgrade.
 
@@ -418,12 +424,12 @@ freshness(current|stale@sha)`, with a deterministic tie-break for reproducible e
 | `kb.introspect` | Eval-only runtime oracle: runs a FastAPI app in a network-blocked sandbox and emits `app.openapi()` for the Tier-1 API gate. Never on the index path. | subprocess sandbox, fastapi |
 | `kb.embed` | Replaceable embedding adapters + snapshot population for `search_knowledge`. Torch isolated behind the `embed` extra and a lazy import. | sentence-transformers (default), OpenAI (optional), pgvector |
 | `kb.rag` | Frozen pgvector RAG-over-source baseline — the "other arm" of the knowledge-vs-RAG A/B (no provenance/grounding). | deterministic line-window chunker, pgvector |
-| `kb.git` | Ingest commits/branches; diff SHAs → changed byte ranges → changed span_ids. (PR mining deferred.) | pygit2 |
+| `kb.git` | Ingest commits/branches; diff SHAs → changed byte ranges → changed span_ids. `kb.git.forge`: GitHub PR-text adapter (stdlib urllib; feeds opt-in `kb mine --prs` — the only networked module; fail-soft). | pygit2 |
 | `kb.store` | Single source of truth: content-addressed spans/artifacts, provenance edges, snapshot manifests. Enforces the ≥1-derived_from invariant at write. | PostgreSQL 17, psycopg 3, SQLAlchemy Core, alembic |
 | `kb.eval` | Tiered eval; deterministic tiers gate CI. | pytest over SHA-pinned golden repos |
 | `kb.mcp` | Read-only MCP server; provenance-carrying records; budget-aware assembly. | FastMCP (pinned), Pydantic models |
 | `kb.daemon` | Orchestration + CLI: index a repo @ SHA (full or incremental), run extractors in order, write snapshot, host MCP; `kb watch` polls a local branch ref and indexes new first-parent commits incrementally (`branch_ref` cursor, per-commit crash-safe advance). | typer |
-| `kb.extract.semantic` | **Shipped:** `kb describe` — LLM-grounded NL descriptions of routes/entities/modules, **per-package architecture overviews** (a package grounded on its own + direct-child modules' spans; the overview synthesizes the import graph + public surface + member-module summaries as context, claims code-grounded), **process-path labels** (one per materialized `process_path`, grounded on every span along the path, confidence < 1.0), **event-handler descriptions**, **and the whole-repo overview** (one `desc:repo` per snapshot, grounded on the bounded top-level surface via `queries.repo_target`, synthesizing package summaries + cross-package imports + artifact counts as context), each claim validated against the target's spans by a deterministic sub-property gate (`grounding.validate_claims`); separate key-gated pass, never on `index`. **`kb mine`** — ADR-candidate mining over local first-parent history: one `decision` per mined commit, grounded on the commit's changed spans (role `changed`), message verbatim in the payload, same claim floor. *Deferred:* PR-description mining. | thin LLM adapter (`kb.llm`); `PathEngine` + YAML sink registry live in `kb.extract.deterministic.paths` |
+| `kb.extract.semantic` | **Shipped:** `kb describe` — LLM-grounded NL descriptions of routes/entities/modules, **per-package architecture overviews** (a package grounded on its own + direct-child modules' spans; the overview synthesizes the import graph + public surface + member-module summaries as context, claims code-grounded), **process-path labels** (one per materialized `process_path`, grounded on every span along the path, confidence < 1.0), **event-handler descriptions**, **and the whole-repo overview** (one `desc:repo` per snapshot, grounded on the bounded top-level surface via `queries.repo_target`, synthesizing package summaries + cross-package imports + artifact counts as context), each claim validated against the target's spans by a deterministic sub-property gate (`grounding.validate_claims`); separate key-gated pass, never on `index`. **`kb mine`** — ADR-candidate mining over local first-parent history: one `decision` per mined commit, grounded on the commit's changed spans (role `changed`), message verbatim in the payload, same claim floor; `--prs` enriches squash-merged commits with PR title/body (digest identity-bearing in `framework_versions`; enriched prompt pinned by its own `prompt_version`). | thin LLM adapter (`kb.llm`); `PathEngine` + YAML sink registry live in `kb.extract.deterministic.paths` |
 
 ---
 
@@ -511,9 +517,10 @@ Review fact-checked these against current (2026) sources. Caveats are first-clas
    gated in `semantic_grounding_test`).
 3. Recursive invalidation (`artifact_depends_on`), multi-branch dedup, freshness precompute.
 4. Embeddings + `search_knowledge` *(shipped v0.2)*; then `pg_search`/BM25 + RRF if vector ranking is insufficient.
-5. ADR mining from git/PR history — **slice 1 shipped** (`kb mine`: local commit history, decisions
-   grounded on the source commit's changed spans, `adr_mining_test` gate); PR-description mining
-   deferred (network adapter).
+5. ADR mining from git/PR history — **both slices shipped**: `kb mine` (local commit history,
+   decisions grounded on the source commit's changed spans, `adr_mining_test` gate) and
+   `kb mine --prs` (opt-in GitHub PR-text enrichment via `kb.git.forge`; PR-text digest is
+   identity-bearing).
 6. SCIP/scip-python precise-reference backend behind `PathEngine`.
 7. Scale: GC/retention, read replicas, monorepo boundaries, runtime-oracle sandbox hardening.
 

README.md

@@ -94,12 +94,12 @@ flowchart LR
 - **A frozen RAG-over-source baseline** and the **Tier-3 knowledge-vs-RAG recall gate** — the honest A/B that backs the "knowledge > RAG" thesis.
 - **LLM-grounded descriptions** — an optional, key-gated `kb describe` pass has an LLM write NL summaries for routes, entities, **event handlers**, modules (per file), **packages** (a per-package architecture overview that synthesizes the import graph + public surface + member-module summaries, grounded on the package's own and its direct submodules' spans), **business-process paths** (each materialized `process_path` chain gets an LLM-written label grounded on every span along the path, with a confidence that honestly stays < 1.0), and **the repo as a whole** (one whole-repo overview per snapshot, grounded on the bounded top-level surface and synthesizing the package overviews beneath it); every claim is validated against the target's own spans by a deterministic sub-property gate, so ungrounded claims are *dropped* (the anti-hallucination invariant, with a model in the loop). Stored as `extraction_method = "llm_grounded"`, grounded on code spans.
 - **Incremental re-index** — `kb index --parent <sha>` reuses unchanged files' spans from the parent snapshot and parses only the diff; extraction stays full, so the result is identical to a full re-index (a HARD gate proves it). Auto-detects the parent; falls back to full when none is indexed.
-- **ADR-candidate mining** — an optional, key-gated `kb mine` pass walks local first-parent git history and has an LLM extract the *decision* a commit records (the "why" that code alone cannot show). The provenance bridge: each `decision` artifact is grounded on the spans its source commit **changed** — prose-born knowledge still points at exact code spans; the commit message is stored verbatim as a fact (immutable, pinned by the sha), and every claim passes the same deterministic span-validation floor (fabricated claims dropped; a commit with no surviving claim stores nothing). Local commits only; PR-description mining is a future slice.
+- **ADR-candidate mining** — an optional, key-gated `kb mine` pass walks local first-parent git history and has an LLM extract the *decision* a commit records (the "why" that code alone cannot show). The provenance bridge: each `decision` artifact is grounded on the spans its source commit **changed** — prose-born knowledge still points at exact code spans; the commit message is stored verbatim as a fact (immutable, pinned by the sha), and every claim passes the same deterministic span-validation floor (fabricated claims dropped; a commit with no surviving claim stores nothing). With **`--prs`** (strictly opt-in — the only networked step in the toolchain), a squash-merged commit's GitHub PR title/body enrich the prompt and the payload; PR text stays context, never grounding, and a digest of it is folded into the artifact's identity, so a PR edited after merge yields a *new* artifact instead of a silent payload swap.
 - **Fifteen HARD CI eval gates** (see [Development](#development)).
 
 - **A nightly LLM-judged A/B** (optional, key-gated, **non-gating**) — an answerer LLM answers each question from knowbase's grounded context vs a RAG-over-source context, and a judge LLM scores **answer accuracy** (against hand-written gold) + **hallucination**. Tracked metrics on top of recall; it never blocks CI.
 
-**Not done yet** (and deliberately not faked): PR-description mining (the network slice of ADR mining) and languages beyond Python. See the [Roadmap](#roadmap).
+**Not done yet** (and deliberately not faked): languages beyond Python. See the [Roadmap](#roadmap).
 
 ## Quickstart
 
@@ -176,7 +176,9 @@ uv run kb describe --db-url <postgres-url>   # separate, key-gated pass (ANTHROP
 uv run kb mine <path-to-repo> --db-url <postgres-url>   # separate, key-gated pass (ANTHROPIC_API_KEY / OPENAI_API_KEY)
 ```
 
-`kb mine` walks the local first-parent history from the latest indexed commit (`--sha` to start elsewhere, `--max-commits` to bound the LLM spend) and has an LLM extract the decision each commit records from its message plus its changed code. Each stored `decision` artifact is **grounded on the spans the commit changed** — the same ≥ 1-span invariant as everything else — with the commit message kept verbatim in the payload as a fact. Claims are span-validated (fabricated claims dropped; nothing survives → nothing stored); merge commits are skipped (PR mining is a future slice), docs-only commits never pay an LLM call, and re-running skips already-mined commits (`--force` to re-mine). Requires the commits to be indexed first (`kb index` / `kb watch`).
+`kb mine` walks the local first-parent history from the latest indexed commit (`--sha` to start elsewhere, `--max-commits` to bound the LLM spend) and has an LLM extract the decision each commit records from its message plus its changed code. Each stored `decision` artifact is **grounded on the spans the commit changed** — the same ≥ 1-span invariant as everything else — with the commit message kept verbatim in the payload as a fact. Claims are span-validated (fabricated claims dropped; nothing survives → nothing stored); merge commits are skipped (squash-merge flow is fully covered; grounding a classic merge on its first-parent diff is an open question), docs-only commits never pay an LLM call, and re-running skips already-mined commits (`--force` to re-mine). Requires the commits to be indexed first (`kb index` / `kb watch`).
+
+Add `--prs` to enrich decisions with GitHub PR titles/bodies (`GITHUB_TOKEN=... kb mine <repo> --prs`) — strictly opt-in, the only networked step in the toolchain (anonymous works for public repos at 60 req/h; `--repo-slug owner/name` overrides the origin-derived slug). A digest of the fetched PR text is identity-bearing, and a failed fetch degrades to plain mining with a per-run counter.
 
 ### Serve to an AI agent (MCP)
 
@@ -280,7 +282,7 @@ CI (GitHub Actions, workflow **"CI"**, `.github/workflows/ci.yml`) runs ruff, `m
 12. **Semantic grounding floor** — the LLM-grounded describer's claims are validated against the artifact's own spans by a deterministic sub-property gate; an adversarial fabricated claim is *dropped*, never stored, on every describe path (artifacts incl. event handlers, modules, packages, process paths, and the whole-repo overview — whose grounding is provably bounded: a grandchild module never grounds it). Run on a stub LLM, so it gates without an API key.
 13. **Incremental re-index equivalence** — an incremental re-index (reuse unchanged files' spans from the parent, parse only the diff) yields the *identical* `{logical_key: artifact_id}` snapshot as a full re-index of the same tree, and the parse is provably skipped for unchanged files (counter assertions); a missing/unindexed parent falls back to full.
 14. **Tier-1 process-paths oracle** — materialized business-process paths match a hand-labeled oracle (2-hop cross-file chain, 0-hop direct-sink handler, event-handler entrypoint); the flagship artifact is grounded across **three files**; a reachable call cycle cannot hang the BFS; the fixture's own `.kb/sinks.yaml` proves the override chain; a no-sink route yields no artifact; depth caps are honored.
-15. **ADR-mining floor** — mined `decision` artifacts are grounded on the spans their source commit changed (role `changed`, provenance limited to the touched files); an adversarial fabricated claim is *dropped*; a commit whose changed code backs no claim stores nothing; a docs-only commit never calls the LLM; merges are skipped; re-mining is idempotent and never re-bills stored decisions (run on a stub LLM, so it gates without an API key).
+15. **ADR-mining floor** — mined `decision` artifacts are grounded on the spans their source commit changed (role `changed`, provenance limited to the touched files); an adversarial fabricated claim is *dropped*; a commit whose changed code backs no claim stores nothing; a docs-only commit never calls the LLM; merges are skipped; re-mining is idempotent and never re-bills stored decisions. PR enrichment is covered too: the PR-text digest is identity-bearing (an edited PR yields a new id, never a silent swap), a failed fetch degrades to the byte-identical plain artifact, and commits without a PR reference stay byte-compatible (run on stub LLM/PR providers, so it gates without keys or network).
 
 The identity rules in `kb.ids` (and `kb.structural`) are **LOCKED**: changing one is a breaking change, gated behind a `NORMALIZATION_VERSION` / `extractor_version` bump so existing digests are invalidated rather than silently colliding.
 
@@ -310,7 +312,7 @@ Next milestones:
 - [x] **LLM-grounded semantic layer** — model-backed artifacts that still carry ≥ 1 span (`extraction_method = "llm_grounded"`): `kb describe` writes span-validated descriptions for routes, entities, event handlers, modules, per-package architecture overviews, and a whole-repo overview. *(shipped)*
 - [x] **Incremental re-index on git push** — `kb index --incremental`/`--parent` reuses unchanged files' spans from the parent snapshot (extraction stays full; equivalence is gated), and `kb watch` polls a local branch ref, indexing each new first-parent commit incrementally with a `branch_ref` cursor (`--max-catchup` guard, `--once` for cron/CI). *(shipped)*
 - [x] **ADR mining — slice 1 (local commit history)** — `kb mine` walks first-parent history and stores span-grounded `decision` candidates: each grounded on the spans its commit changed, message verbatim as a fact, claims under the deterministic span-validation floor. *(shipped)*
-- [ ] **PR-description mining** — the network slice of ADR mining (PR titles/bodies mapped onto merge commits).
+- [x] **PR-description mining** — `kb mine --prs` (strictly opt-in, the only networked step) enriches decisions with GitHub PR titles/bodies for squash-merged commits; the PR-text digest is identity-bearing, so post-merge PR edits can never silently swap a payload. *(shipped)*
 - [x] **Grounded business-process extraction** — `process_path` artifacts (entrypoint → call chain → sink-registry match, multi-file grounding) plus LLM labeling via `kb describe` (a span-validated NL label per path, grounded on the path's own spans, confidence honestly < 1.0). *(shipped)*
 - [ ] **More languages** beyond Python.