feat(mine): ADR-candidate mining from local git history (kb mine, slice 1)#30
Merged
Conversation
…ce 1)
Resolves the DESIGN tension between D5 (>= 1 code-span grounding,
LOCKED) and "ADRs are not extractable from code": a decision artifact
is grounded on the spans its source commit CHANGED (present at the
commit, absent at its first parent; role "changed"; root commits mine
against the empty tree), so prose-born knowledge still points at exact
code spans. The commit message is stored verbatim in the payload as a
fact - immutable, pinned by the sha in the deterministic logical key
(decision:{sha}) - context, never grounding.
kb mine is a separate key-gated LLM pass (mirror of kb describe):
first-parent walk from the latest indexed commit, merge commits
skipped (PR mining is a future network slice), unindexed commits
skipped, docs-only commits never pay an LLM call, oversized grounding
sets capped with a retro-flag, one transaction per commit (crash-safe),
re-runs skip already-mined commits. Claims pass the same deterministic
validate_claims floor; no survivors -> nothing stored;
confidence = kept/(kept+dropped); trust stays LOW.
New HARD gate adr_mining_test (stub LLM, offline): grounded claim kept,
fabricated claim dropped, provenance limited to touched files, root
grounded on the whole initial tree, no-claim commit stores nothing,
merge skipped, re-mining idempotent. Headline HARD gates: fourteen ->
fifteen. make_git_repo fixtures accept per-commit messages.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
New key-gated LLM pass
kb mine(kb.extract.semantic.mine, mirror ofkb describe): walks the local first-parent history from the latest indexed commit (--sha/--max-commits/--force) and extracts the decision each commit records from its message plus its changed code — the last substantive roadmap item before more-languages, slice 1 (local git only).The D5 bridge (the design core)
DESIGN said both "ADRs are NOT extractable from code" (§4) and "no artifact without ≥ 1 code span" (D5, LOCKED) — unresolved until now. The bridge: a
decisionartifact is grounded on the spans its source commit changed (changed_span_ids(C, parent); rolechanged; root commits mine against the empty tree). The commit message is stored verbatim in the payload as a fact — immutable, pinned by the sha in the deterministicdecision:{sha}key — context, never grounding. Claims pass the same deterministicvalidate_claimsfloor as describe: fabricated claims dropped, no survivors → nothing stored,confidence = kept/(kept+dropped), trust stays LOW.Behavior
grounding_capped+total_changed_spans) — bounded, never silent.--forcere-mines but content-addressing keeps the ids.Gates
New HARD gate
adr_mining_test(stub LLM, offline): grounded claim kept / adversarial fabricated claim dropped; provenance limited to the commit's touched files; root grounded on the whole initial tree; a commit whose changed code backs no claim stores nothing; docs-only provably skips the LLM (call counter); merges skipped; re-mining idempotent (same artifact ids). Headline HARD gates: fourteen → fifteen.make_git_repofixtures accept per-commitmessages(backwards-compatible).Local:
ruffclean,mypy --strictclean,pytest -q→ 109 passed, 1 skipped.Next
PR-description mining (network slice); release cut later per cadence.