go-ldd v2.10.0: OKF-conformant repo brain — frontmatter, derived index, conventions self-hosting, CI gate by buzzdan · Pull Request #24 · buzzdan/ai-coding-rules

buzzdan · 2026-08-20T13:22:47Z

What

Layers Open Knowledge Format (OKF) v0.2 — Google Cloud's open markdown-bundle spec — onto the repo brain (R9 + @documentation + /wire-repo-brain), and makes the network maintainable by monorepo contributors who never installed the plugin. Full design rationale lives in the session's design artifact ("The Repo Brain Ladder"). Two review rounds (token-economy lens + OKF spec audit against the canonical GoogleCloudPlatform/open-knowledge-format SPEC.md) shaped the layer; the result below is the post-review design. Round-2 verdicts: OKF lens — "conformant, no violations or mislabels remain"; token-economy lens — "more efficient than main; keep".

The OKF layer (R9 + skill + command)

Frontmatter on content docs only: required type (the spec's one required key) and description; optional title, generated (OKF's provenance key), tags, and lifecycle status/stale_after — the frontmatter-native ⚠️ stale flag. Indexes stay bare (OKF §8 reserves index.md); the root index carries only okf_version. R9 is a stricter profile of the spec built from spec-valid keys — bundles pass a strict OKF validator.
Drift-check rule: a doc's index line IS its description, copied verbatim — the description is the single source, the gate fails when the copy drifts, and check-repo-brain.sh --fix rewrites drifted lines from the descriptions (the one mechanical repair the gate performs). Map of maps is directory-shaped; sub-index lines in the root map are authored (a bare sub-index has no description to copy); the split lands in the same commit as the See docs/... path rewrite.
One-way link policy: write an edge only when no structure implies it — no child→parent backlinks, no related: frontmatter key, no ## Related section; lateral links go inline with the reason in the sentence. log.md never emitted.
New falsifying question Q7 (bundle contract) alongside Q1–Q6, same evidence-based grep style. Comment policy untouched (the comment-critic payload extraction still cuts cleanly).

Teach / route / enforce (for devs without the plugin)

Teach: BOOTSTRAP creates <docroot>/conventions.md (template in reference.md) — the network's maintenance manual, listed first in the index; the one content file bootstrap is sanctioned to generate.
Route: AGENTS.md upgraded from "fallback" to a first-class routing block — root + nested per sub-project, closest file wins — covering Cursor/Codex/Copilot/Gemini-driven contributors.
Enforce: new scripts/check-repo-brain.sh [--fix] — dependency-free bash gate running Q1–Q3 + Q7 (the R9 profile, stricter than OKF); BOOTSTRAP installs it into target repos and suggests the one-line CI wiring. Every failure message points at conventions.md. Docs→code resolution covers type/func/var/const declarations (including inside var (/const ( blocks) and package-qualified tokens; ⚠️/(planned) exemptions are per-line, and R9's wording matches the gate.

Migration

BOOTSTRAP verify-or-adds frontmatter on content docs and strips it from indexes, so a network wired by an older plugin version (including earlier shapes of this PR) converges in one idempotent re-run; un-inferable types go to the advisory report, never guessed.

Testing

bash -n clean; script verified against a fixture matrix: clean conformant bundle, map of maps (bare sub-index, authored root line), ⚠️-stale and (planned) exemptions, sub-index frontmatter, root-index extra key, missing root okf_version, missing required key, related: key, drifted index line (check mode fails; --fix rewrites it and the re-check is clean), log.md (single report), file:line ban with URL exemption, unresolved symbol, block-declared var resolution, package-qualified token resolution, missing optional generated accepted, no-doc-root no-op (exit 0), bad-root usage error (exit 2); plus the six real-repo false-positive classes from the genius-api dogfood (grouped declarations, bare methods, stdlib pkg.Sym, non-Go tokens, fenced/glob paths, .golangci-style names).
Consistency greps: no lingering timestamp/type: index/## Related-as-feature/"regenerable map" phrasing; okf_version root-only; related:/log.md/index-frontmatter bans present in R9, the conventions template, and the script; version aligned across plugin.json, CHANGELOG, and the root README.
R9's "Comment policy" section is byte-identical to main — the comment-critic's verbatim payload extraction is unaffected.

Scope notes

Go plugin only; ts-react-linter-driven-development untouched.
Dogfooded on genius-api (31 docs, 1,271 Go files, isolated worktree off origin/main): BOOTSTRAP wired the whole brownfield network in one pass with Q1/Q3/Q7 = 0; the first Q2 gate design produced 1,071 false positives in ~25 min, which drove the set-based resolver rewrite — now ~55 s with only genuine findings (301 prose file-path citations the edge policy bans + 23 real symbol drift).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

The doc root becomes an Open Knowledge Format (OKF v0.2) bundle: required frontmatter on content docs, type: index on indexes (a documented R9 extension; okf_version on the root), index lines derived from the frontmatter one level down, directory-shaped map of maps with the same-commit split rule, one-way link policy with the capped Related section, conventions.md as the self-hosting doc, AGENTS.md upgraded to a first-class routing block, and new falsifying question Q7 for the bundle contract. Comment policy untouched. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

…ap migration reference.md gains frontmatter templates (content doc / sub-index / root index), the conventions.md template, the AGENTS.md routing block, the class-to-type mapping, and the brownfield frontmatter-migration guidance; the Feature Doc Template's Related section is reconciled with the one-way link policy (optional, max 3, reason clauses). SKILL.md's FEATURE and BOOTSTRAP steps produce and verify the bundle: derived index lines, the new teach-and-enforce step (conventions.md + check script install), and Q7 in the self-checks. /wire-repo-brain's outcomes follow suit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

Dependency-free bash gate running R9's mechanical questions — Q1 orphans, Q2 edges in both directions plus the file:line ban, Q3 root wiring, Q7 bundle contract — with exit 0 clean/not-adopted, 1 violations, 2 usage error. Installed into target repos by the documentation skill's BOOTSTRAP pass; every failure message points at the doc root's conventions.md. Verified against a 15-case fixture matrix (true positives for each check, the two symbol-resolution exemptions, URL exemption, fence skipping). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

Version bump with the 2.10.0 changelog entry, plugin README tree and table rows for the OKF layer and the new scripts/ directory, the stale root-README version cell fixed in passing, and the pre-commit-review R9 hunter's hunt-focus extended with bundle-contract breaks. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

Copilot

Pull request overview

Adds OKF-based repo-brain conventions, contributor routing, and a CI conformance gate to the Go plugin.

Changes:

Defines OKF frontmatter, index derivation, and linking policies.
Extends documentation bootstrap with conventions and AGENTS.md routing.
Adds the repo-brain validation script and releases v2.10.0.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`README.md`	Updates the plugin version.
`go-linter-driven-development/skills/pre-commit-review/SKILL.md`	Expands R9 review scope.
`go-linter-driven-development/skills/documentation/SKILL.md`	Adds OKF bootstrap workflow.
`go-linter-driven-development/skills/documentation/reference.md`	Adds templates and conventions.
`go-linter-driven-development/scripts/check-repo-brain.sh`	Implements the conformance gate.
`go-linter-driven-development/rules/R9-repo-brain.md`	Defines the OKF policy.
`go-linter-driven-development/README.md`	Documents the new capabilities.
`go-linter-driven-development/commands/wire-repo-brain.md`	Updates command behavior.
`go-linter-driven-development/CHANGELOG.md`	Records the v2.10.0 release.
`go-linter-driven-development/.claude-plugin/plugin.json`	Updates plugin metadata.

Suppressed comments (1)

go-linter-driven-development/rules/R9-repo-brain.md:511

Q7 defines only a subset of the bundle contract stated above: it omits the required content keys, required index title/description/tags, root okf_version, a closing frontmatter delimiter, and the derivation/lifecycle checks. Because the skill and shipped script treat Q7 as the authoritative confirmation, these omissions formally permit nonconformant bundles. Extend Q7 and the checker together to cover the full mechanical contract.

7. **Does any file break the bundle contract?**
   Detection: for every `.md` under `<docroot>`, check the first line is `---`
   (e.g. `head -1` per file); for every `index.md`, check its frontmatter block
   contains `type: index` and no `timestamp:` key; `grep -rn '^related:'` over
   doc-root frontmatter; `find <docroot> -name 'log.md'`.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

…e-links rule Addresses Copilot review on the normative side: Q3 requires the exact <docroot>/index.md path per doc root (bare index.md mentions no longer count; a monorepo sub-root may ride the repo-root index; a missing AGENTS.md routing reference is an advisory). Q7 states the full bundle contract — terminated frontmatter, per-class required keys, okf_version on the root index alone, and the index-line-equals-description derivation check with the warning-flag exemption. The canonical example's index gains tags, and the conventions template pins links to inline form (reference-style links are not checked). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

…chability, full contract The gate now discovers a doc root at the repo root AND every go.mod sub-project, resolving code edges against the citing file's own project. Q1 walks the bundle from its root index, so an unlinked sub-index no longer launders its children. Q3 matches the exact <docroot>/index.md path, accepts sub-roots linked from the repo-root index, and downgrades a missing AGENTS.md reference to an advisory. Q7 enforces the full frontmatter contract (termination, per-class required keys, root-only okf_version) and the derivation rule (index line text equals the target's description, warning-flagged lines exempt). Link extraction strips optional titles; fences match ``` and ~~~ indented up to three spaces; the file:line ban strips URL spans instead of whole lines. Verified against the extended fixture matrix (regressions + 12 new cases, including a two-bundle monorepo). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

buzzdan · 2026-08-20T15:17:48Z

All 9 Copilot findings (plus the suppressed Q7-scope one) are addressed in 1a94a99 + 6845e3b:

Multi-root discovery: the gate now checks the repo root and every go.mod sub-project's doc root; code edges resolve against the citing file's own project.
Transitive reachability: Q1 walks the bundle from its root index — an unlinked sub-index and its children are now orphans.
Q3 exact-path wiring: bare index.md mentions no longer count; sub-roots may ride the repo-root index; a missing AGENTS.md reference is an advisory rather than a violation (matching R9's updated Q3).
Derivation validated: each index line's text is compared against the target's description (⚠️-flagged lines exempt).
Full Q7 contract: terminated frontmatter, per-class required keys, okf_version on the root index only — R9's Q7 text and the script were extended together, and the rule's worked example gained tags.
Link titles stripped; inline-links-only documented (reference-style links stay out of scope, now stated in the conventions template and script header).
Fences: ``` and ~~~ recognized with up to 3 spaces of indentation (simple toggle, documented — no fence-length matching).
URL exemption narrowed: URL spans are stripped from the line before the file:line test, so handler.go:42 next to a URL is caught.

Verified against an extended fixture matrix (all prior regressions + 12 new cases, including a two-bundle monorepo).

Generated by Claude Code

…uting block The routing block is authored once, in AGENTS.md (root and nested per sub-project); CLAUDE.md carries two imports — @AGENTS.md and @<docroot>/index.md — so Claude sessions get the same routing prose other tools read, without a second copy that could drift. R9's root wiring and fix pattern, the reference snippets, the bootstrap step, and the command outcome all state the single-source form; the conformance gate accepts both files as wiring evidence, unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

…atter, script bugs Applies both review verdicts (Karpathy lens + OKF spec audit): - Indexes carry NO frontmatter (OKF §8): type:index/title/description/tags removed; root index keeps only okf_version. Bundles now pass a strict OKF validator — the "R9 extension" label was a spec violation, not an extension. - timestamp renamed to generated (the spec's provenance key); title now optional (the H1 is the title). Required content-doc keys: type, description, generated. - "Regenerable map" claim corrected to drift-check: the description is the single source, the index line is a verified copy — nothing regenerates. - `## Related` section removed: unenforced ceremony; lateral links go inline with the reason in the sentence. - check-repo-brain.sh: docs→code resolution now covers var/const declarations (including inside var/const blocks) and package-qualified tokens (`retry.Policy`); Q7 index branch enforces bare indexes + root-only okf_version; log.md no longer triple-reported; header states the gate enforces the R9 profile (stricter than OKF v0.2). - R9 "description + tags" vs script exact-match contradiction resolved: sub-index lines are authored (bare sub-index has no description to copy). - Verified against a fixture matrix: clean bundle, map of maps, ⚠️/(planned) exemptions, sub-index frontmatter, root extra key, missing okf_version, missing generated, related: key, drifted line, log.md, file:line ban, unresolved symbol, no-doc-root no-op, usage error. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… exemption wording Remaining items from the second two-lens review pass: - `generated` demoted to optional: required but nothing validated or consumed it — a self-reported date that silently rots. Required content-doc keys are now `type` (OKF's one required key — dropping it would un-conform the bundle) and `description` (feeds the drift check). - New `check-repo-brain.sh --fix`: rewrites drifted index lines from each target doc's `description` — the gate already computed the correct line; the flag turns the drift check into the fixer and removes the last hand-copy step. Fixes apply after the read loop, never during it. - R9 Q2 exemption wording aligned to the script: the ⚠️ / *(planned)* exemptions are per-LINE, matching what the gate actually skips. - Spec-lawyer parentheticals trimmed from R9's bundle policy. Verified: bash -n clean; --fix rewrites the drifted line and the re-check is clean; check mode still fails on drift; full fixture matrix regressions green; missing `generated` no longer a violation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…n -> 55 s The first real-repo run (31 docs, 1,271 Go files) produced 1,071 violations — near-all false positives — in 20-25 minutes. Root causes and fixes: - Per-token repo-wide greps replaced by set operations: one awk pass builds the declaration set (single-line AND grouped `type (`/`var (`/`const (` declarations, functions, methods); one awk pass extracts all doc tokens and file-path candidates (fence-aware); one batched repo-wide word-grep resolves the whole unresolved set at once. - Bare method names and grouped declarations now resolve (the two biggest false-positive classes). - External `pkg.Sym` (stdlib, dependencies) exempt — the package-name set from the same awk pass decides what is "in this repo". - Non-Go tokens (alert names, config keys) resolve via the whole-word fallback over non-markdown files instead of failing as "missing Go symbols". - file:line ban now skips fenced code blocks and glob patterns (`**/*.go`), and no longer substring-matches names like `.golangci.yml`. Re-run on the same repo: 55 s, 324 violations — all genuine (301 prose file-path citations the edge policy bans, 23 real symbol drift). Fixture matrix extended with the six discovered classes; all regressions green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…structure The genius-api dogfood showed the degradation on non-Go code is silent. Five one-liners state it where each audience looks: - /wire-repo-brain: what a non-Go or mixed repo gets and loses - documentation SKILL step 6: upward edges wire Go files only — non-Go docs are reported as unwired, never wired unverifiably - R9 monorepo section: go.mod-keyed discovery; other-language sub-projects stay reachable but outside the gate - script header: structure checks language-agnostic, Q2 Go-only - conventions.md template: contributors see the scope in-repo Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

claude added 4 commits August 20, 2026 13:22

buzzdan requested a balanced review from Copilot August 20, 2026 13:31

Copilot started reviewing on behalf of buzzdan August 20, 2026 13:32 View session

Copilot AI reviewed Aug 20, 2026

View reviewed changes

claude added 2 commits August 20, 2026 15:16

claude and others added 5 commits August 20, 2026 21:09

Navigation Menu

go-ldd v2.10.0: OKF-conformant repo brain — frontmatter, derived index, conventions self-hosting, CI gate - #24

go-ldd v2.10.0: OKF-conformant repo brain — frontmatter, derived index, conventions self-hosting, CI gate#24
buzzdan wants to merge 11 commits into
mainfrom
claude/docling-graph-wire-repo-jx3msi

buzzdan commented Aug 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

buzzdan commented Aug 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

buzzdan commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

The OKF layer (R9 + skill + command)

Teach / route / enforce (for devs without the plugin)

Migration

Testing

Scope notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

buzzdan commented Aug 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

buzzdan commented Aug 20, 2026 •

edited

Loading