docs: add a CHANGELOG, index the unlisted docs, flag the stale estate figures

[bawoodruff]

The repo had no history record of any kind — no CHANGELOG, no release-notes section in any of the five READMEs. The only account of what changed since v0.1.0 was the git log.

CHANGELOG.md (new)

Keep a Changelog format. One [Unreleased] section covering the 43 commits since the tag, grouped by Added / Fixed / Changed / Removed rather than enumerated commit-by-commit. Notes that builds are version-stamped from git describe, which is why an installed binary reports v0.1.0-43-g0ae49e6.

README docs index

Three of ten docs were absent from the table:

• docs/kg-graph-linking-design.md — so the design behind cross-layer linking was unreachable from the README
• docs/kg-shared-service-design.md
• docs/kg-log-plugins.md

Plus a row for the CHANGELOG.

Pending re-measurement

Every estate figure in kg-graph-linking-design.md, and in the --federated section of kg-cli-reference.md, was measured before JVM package indexing shipped (5211bc2). At that point the only package entities kg index minted were Go's bare identifiers, which the rule's specificity floor filters out — so those numbers cannot have come from an estate indexed by the binary current at the time.

Rather than leave them reading as current, both files now point at a single Pending re-measurement section that lists every affected figure (2,525 derived edges, the 845 gate prediction, 3,359 discarded, the 5,138/50,993 corpus counts, estate size, load cost) and says which direction each should move. The section is written to be deleted once the numbers are reproduced.

Re-deriving them needs the estate itself on a machine at 5211bc2 or later, so it stays open.

Hub design doc status

docs/kg-shared-service-design.md was still headed "Status: proposal (not yet implemented)" despite phases 1–4 being in and per-user auth being built. Its own Rollout phases section already said so, so the header contradicted the body. Corrected, along with two other claims shipping had falsified:

• Sequencing said "Nothing here is built." — Identity is threaded through the request path and token/oidc/github verifiers all exist in src/kg/internal/hub; proxy is the one that remains.
• Identity "should carry groups from the start" — it does, as Groups.

Docs only; no code paths touched.

🤖 Generated with Claude Code

[github-actions]

Review Summary

Docs-only PR (CHANGELOG.md added, README index updated, two design docs annotated with "pending re-measurement" / status corrections). No code paths touched, matching the PR description's claim.

I fact-checked the testable claims in the diff against the actual working tree rather than taking them at face value:

• docs/kg-shared-service-design.md claims Identity is threaded through the request path and that token/oidc/github verifiers exist while proxy remains outstanding. Confirmed: src/kg/internal/hub/auth.go defines the Verifier interface and TokenVerifier; oidc.go/github.go implement OIDCVerifier/GitHubVerifier; Identity.Groups []string exists exactly as described; no proxy.go/ProxyVerifier exists in the package. The updated status header and body are accurate.
• CHANGELOG.md feature/fix list spot-checked against the tree: src/kg/health.go, src/kg/personal.go, KG_HOME env var (src/kg/personal.go, scope.go), --public-only filter (src/kg/search.go), recover() panic guard in src/kg/internal/mcp/server.go, src/kg/Makefile's install: keeps the binary it replaces comment, and absence of any slack-mcp/upk directories — all consistent with the changelog's claims.
• docs/kg-graph-linking-design.md / docs/kg-cli-reference.md "Pending re-measurement" additions: cross-checked the new table's figures (5,138/50,993, 845, 3,204, 2,525, 3,359, 67,263) against the pre-existing numbers in the same file's body — they match exactly, so the new summary table isn't introducing drift. New anchor links (#pending-re-measurement, #problem, #measurement-gate--result, #acceptance, #open-questions, #rollout-phases) all resolve to real headings in the target files.
• README table additions point at three real files (docs/kg-graph-linking-design.md, docs/kg-shared-service-design.md, docs/kg-log-plugins.md), all present in the tree.

No fabricated or stale claims survived the check. No code, tests, or build config touched, so no build/test verification is applicable.

Critical Issues (must fix before merge)

None.

Major Issues (should fix)

None.

Minor Issues (optional)

• README.md:155 — docs/kg-log-plugins.md is inserted between skills/README.md and the Claude-integration docs rather than near the other kg-* design docs a few rows up; the table isn't strictly grouped/alphabetized elsewhere either, so this is a nit, not a defect. Consider moving it next to kg-graph-linking-design.md/kg-shared-service-design.md for topical locality if the table's implicit grouping matters to maintainers.
• Both "pending re-measurement" callouts point at 5211bc2 as the commit where JVM package indexing shipped; I could not verify this SHA exists (shallow clone in this environment, no tags fetched), so it's unverified rather than confirmed — worth a maintainer's own sanity check before merge, though it's not something I could falsify.

Security Findings

None — no code changed.

Positive Observations

• Every quantitative and code-existence claim I checked (verifier types, Identity.Groups, CLI subcommands, removed servers, env var name, panic recovery, public-only filter) matched the actual source tree exactly — unusually well-verified for a docs PR.
• The "Pending re-measurement" sections in both kg-cli-reference.md and kg-graph-linking-design.md are cross-linked to a single source of truth rather than duplicating stale numbers in two places with independent drift risk.
• The kg-shared-service-design.md status correction removes a genuine contradiction (header said "not yet implemented" while the body's own Rollout phases section said otherwise) rather than just cosmetically updating a date.