docs: product-first README restructure + keyword-rosetta consistency proof - #2554
Merged
Conversation
…proof README.md 687 -> 387 lines. The long proof narrative (structural-extraction thesis, full tri-comparison section, validity ladder, risk-over-git-history experiment, research direction) moves intact to the new docs/validation.md; the README keeps a condensed "Accuracy, measured" summary holding the old #structural-validation-gitgalaxy-vs-tree-sitter-vs-ctags anchor stable. New product section "What a scan gives you" leads: the six outputs, the LLM architecture brief showcased with two dated, reproducible scan excerpts from the current engine (curl: cross-language pillar/function ranking, 16.4% scanned caveat; cics-genapp: COBOL/DB2 risk hitlist, flat-graph pillar degeneration caveat). New proof: keyword-rosetta 46-language control corpus embedded via its raw main-branch chart URL (self-updating), shipped limitations-first (3/33 strict passes, avg 75% in-band), with a new "Measurement consistency" rung in the validity ladder. Kubernetes bullet gains its long-missing rule-4 limitation clause (fitted two-regime speed model). Pandoc-style tables converted to GFM pipe tables so they actually render on GitHub. how_to_maintain_the_readme.md section-order target updated to the new structure; readme_evidence_roadmap.md gains the shipped keyword-rosetta row. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M11wL1mSgk1fghxz1PAWGY
Contributor
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 this does
docs/validation.md(thesis, full tri-comparison section, validity ladder — now 7 rungs, risk-over-git-history experiment, research direction).bias_variance_chart.svgfrom that repo's raw main URL (self-updating, same pattern as the speed chart). Shipped limitations-first: 3/33 metrics pass the strict cross-language gate today; avg 75% of languages within ±25% of median.how_to_maintain_the_readme.mdflagged as missing (fitted two-regime speed model, throughput ≠ insight quality).how_to_maintain_the_readme.mdsection-order target state updated;readme_evidence_roadmap.mdgains the shipped keyword-rosetta row.Anchor stability
#structural-validation-gitgalaxy-vs-tree-sitter-vs-ctagsstill resolves in README.md (kept as a subsection heading inside "Accuracy, measured"). Tone-bar sections ("Risk exposure: what GitGalaxy claims", "Evidence, not just claims") kept verbatim, with one new Keyword Rosetta bullet added to the latter.Note for reviewer
The README's 75%-consistency framing matches keyword-rosetta's
feat/green-share-badgesbranch (consistency-score badges on the chart). Merging squid-protocol/keyword-rosetta#(badges PR) makes the embedded chart and linked bias report show the same framing; until then main shows the same data with 3 PASS / 30 FAIL badges — both numbers are stated in this README, so neither ordering breaks a claim.🤖 Generated with Claude Code
https://claude.ai/code/session_01M11wL1mSgk1fghxz1PAWGY