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

[buzzdan]

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").

The OKF layer (R9 + skill + command)

• Frontmatter on every doc-root file: content docs carry type/title/description/timestamp (+ optional tags, lifecycle status/stale_after — the frontmatter-native ⚠️ stale flag); indexes carry type: index as a documented R9 extension (OKF keeps reserved index.md bare), never a timestamp; the root index carries okf_version.
• Derivation rule: every index line is derived from the frontmatter one level down — a doc's line IS its description — so the map is regenerable and can't drift. Map of maps is directory-shaped; 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, lateral links inline with the reason in the sentence; optional ## Related capped at 3 reason-claused entries. 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 — dependency-free bash gate running Q1–Q3 + Q7; BOOTSTRAP installs it into target repos and suggests the one-line CI wiring. Every failure message points at conventions.md.

Migration

BOOTSTRAP verify-or-adds frontmatter, so a network wired by an older plugin version converges in one idempotent re-run; un-inferable types go to the advisory report, never guessed.

Testing

• bash -n clean; script verified against a 15-case fixture matrix: true positives for every check (orphan, broken code edge, unresolved symbol and method, file:line ban, missing frontmatter, index timestamp, missing type: index, related: key, log.md, unwired root), both symbol-resolution exemptions (⚠️ / (planned)), URL exemption, fenced-block skipping, no-doc-root no-op (exit 0), bad-root usage error (exit 2), and clean conformant runs before/after each case.
• Consistency greps: no lingering "AGENTS.md fallback" phrasing; Q-set counts updated in the skill and command; okf_version only on root-index guidance; related:/log.md bans present in R9, the conventions template, and the script; version aligned across plugin.json, CHANGELOG, and the root README (stale 2.6.0 cell fixed in passing).
• R9's "Comment policy" section is byte-identical (verified via diff-hunk scan) — the comment-critic's verbatim payload extraction is unaffected.

Scope notes

• Go plugin only; ts-react-linter-driven-development untouched.
• No dogfooding in this PR — running /wire-repo-brain on this repo itself is the natural follow-up live test.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CH1Y4ssZbAKJYwqBX1qxCF

---

Generated by Claude Code

[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.

[buzzdan]

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