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

README.md

@@ -6,7 +6,7 @@ A [Claude Code](https://claude.ai/code) plugin marketplace for **linter-driven d
 
 | | Plugin | Version | For |
 |---|--------|---------|-----|
-| 🐹 | [`go-linter-driven-development`](go-linter-driven-development/README.md) | 2.6.0 | Go |
+| 🐹 | [`go-linter-driven-development`](go-linter-driven-development/README.md) | 2.10.0 | Go |
 | ⚛️ | [`ts-react-linter-driven-development`](ts-react-linter-driven-development/README.md) | 1.2.0 | TypeScript + React |
 
 Plus the standalone rule documents the plugins grew out of:

go-linter-driven-development/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "go-linter-driven-development",
-  "version": "2.9.1",
-  "description": "Rules-as-data linter-driven development workflow for Go: 12 single-source rule files, thin directional skills (design, TDD implementation, refactoring, testing, review, documentation), and a hunter/skeptic/critic review architecture with parallel single-rule reviewers, an over-abstraction skeptic, and a comment critic enforcing the Comment Value Toolbox",
+  "version": "2.10.0",
+  "description": "Rules-as-data linter-driven development workflow for Go: 12 single-source rule files, thin directional skills (design, TDD implementation, refactoring, testing, review, documentation), a hunter/skeptic/critic review architecture with parallel single-rule reviewers, an over-abstraction skeptic, and a comment critic enforcing the Comment Value Toolbox, plus an OKF-conformant repo brain with a shippable CI conformance gate",
   "author": {
     "name": "Dan Mordechay"
   },

go-linter-driven-development/CHANGELOG.md

@@ -3,6 +3,73 @@
 All notable changes to the `go-linter-driven-development` plugin are documented here.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [Semantic Versioning](https://semver.org/).
 
+## [2.10.0] - 2026-08-20
+
+The repo brain had one audience: a session with this plugin installed. In a
+monorepo most contributors — and their agents — don't have it, so the network's
+rules lived nowhere they could find and nothing enforced them. This release
+makes the doc root a standard, self-describing artifact: an Open Knowledge
+Format (OKF v0.2) bundle any tool can consume, with its own maintenance manual
+inside and a CI gate outside.
+
+### Added
+
+- **OKF v0.2 bundle conformance (R9)**: content docs carry YAML frontmatter —
+  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 form of the ⚠️ stale flag.
+  Indexes stay bare, as the spec reserves them; the root index carries only
+  `okf_version`. R9 is a stricter profile of the spec built from spec-valid
+  keys, so the bundle stays consumable by any OKF tool. New falsifying
+  question **Q7** checks the bundle contract mechanically.
+- **Drift-check rule (R9)**: a doc's index line IS its `description`, copied
+  verbatim — the description is the single source, and the conformance gate
+  fails when the copy drifts; `check-repo-brain.sh --fix` rewrites drifted
+  lines from the descriptions (the one mechanical repair the gate performs).
+  The map of maps is directory-shaped (per-topic subdirectories with their
+  own bare index.md), and the split lands in the same commit as the
+  `See docs/...` path rewrite.
+- **One-way link policy (R9)**: 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` is
+  never emitted.
+- **Self-hosting conventions doc**: BOOTSTRAP creates `<docroot>/conventions.md`
+  (template in reference.md) — the network's maintenance rules written for
+  contributors without this plugin, listed first in the index.
+- **AGENTS.md routing block**: upgraded from "fallback when CLAUDE.md is
+  absent" to first-class multi-tool coverage — root and nested per sub-project
+  (closest file wins), pointing every AGENTS.md-reading agent at the index and
+  conventions.md. Authored once: CLAUDE.md embeds it via `@AGENTS.md` (plus the
+  `@<docroot>/index.md` map import) instead of duplicating the routing prose.
+- **New `scripts/check-repo-brain.sh`**: dependency-free conformance gate
+  running Q1–Q3 and Q7 over every doc root (repo root plus each go.mod
+  sub-project): transitive reachability from the root index, both edge
+  directions, the file:line ban (URL spans, fenced code blocks, and glob
+  patterns exempt), exact-path root wiring (missing AGENTS.md routing is an
+  advisory), the full frontmatter contract (termination, required content-doc
+  keys, bare indexes, root-only `okf_version`), and every index line checked
+  against its target's `description`. Docs→code resolution is set-based and
+  Go-shaped: one pass builds the repo's declaration set (single-line and
+  grouped `type (`/`var (`/`const (` declarations, functions, methods); a
+  token missing there still resolves as a whole word in any non-markdown repo
+  file (config keys, alert names); external `pkg.Sym` (stdlib, dependencies)
+  is exempt. Dogfooded on a 1,271-file production repo: ~55 s per run, zero
+  false-positive classes left. BOOTSTRAP installs it into
+  target repos and suggests the
+  one-line CI wiring. Exit 0 clean/not-adopted, 1 violations, 2 usage error;
+  every failure message points at conventions.md.
+
+### Changed
+
+- **BOOTSTRAP is now a migration pass too**: frontmatter is verified-or-added
+  on content docs (never duplicated) and stripped from indexes, so a network
+  wired by an older plugin version converges to the current rules in one
+  idempotent re-run; an un-inferable `type` goes to the advisory report, never
+  guessed.
+- **Feature Doc Template's `Related` section removed**: lateral doc links go
+  inline, in the sentence that states the relationship — a relationship that
+  cannot find a sentence in the body is not worth an edge.
+
 ## [2.9.1] - 2026-07-23
 
 A real 143-line file surfaced the gap v2.9.0 left open: every one of its nine

go-linter-driven-development/README.md

@@ -24,6 +24,7 @@ go-linter-driven-development/
 │                 pre-commit-review · testing · documentation   (thin directional views)
 ├── agents/       rule-hunter · overabstraction-skeptic · lint-fixer   (isolated workers)
 ├── commands/     go-ldd-analyze · autopilot · quickfix · prepare · review · status · wire-repo-brain
+├── scripts/      check-repo-brain.sh — repo-brain conformance gate, installed into target repos by /wire-repo-brain
 └── hooks/        package-size gate
 ```
 
@@ -82,7 +83,7 @@ Isolated contexts matter: the `lint-fixer` loop's token noise stays out of your
 | R6 | [`rules/R6-test-only-interfaces.md`](rules/R6-test-only-interfaces.md) | No interface whose only second implementer is a test double |
 | R7 | [`rules/R7-test-placement.md`](rules/R7-test-placement.md) | `pkg_test` only, no wantErr conditionals, right-rung tests, no sleeps |
 | R8 | [`rules/R8-no-globals.md`](rules/R8-no-globals.md) | No package-level state; no `context.Background()` in library code |
-| R9 | [`rules/R9-repo-brain.md`](rules/R9-repo-brain.md) | Documentation network: fact at its lowest rung, reachable from the root, edges both directions; index wired into CLAUDE.md |
+| R9 | [`rules/R9-repo-brain.md`](rules/R9-repo-brain.md) | Documentation network: fact at its lowest rung, reachable from the root, edges both directions; index wired into CLAUDE.md; doc root is an OKF bundle (frontmatter, drift-checked index lines) |
 | R10 | [`rules/R10-concurrency-safety.md`](rules/R10-concurrency-safety.md) | Goroutines with owners and exit paths; shared state guarded where it lives; no production sleeps |
 | R11 | [`rules/R11-conditional-dispatch.md`](rules/R11-conditional-dispatch.md) | One dispatch owner per kind/variant family (Anti-IF): duplicated kind-switches become interface/map dispatch chosen once at the boundary; a single switch stays and goes exhaustive |
 | R12 | [`rules/R12-mutation-discipline.md`](rules/R12-mutation-discipline.md) | Mutation only through invariant-owning methods: constructors copy collections in, queries copy (or iterate) out, no query/modifier hybrids, no setters around validating constructors |
@@ -106,7 +107,7 @@ Isolated contexts matter: the `lint-fixer` loop's token noise stays out of your
 | [`@refactoring`](skills/refactoring/SKILL.md) | BACKWARD view — routes each linter/review failure to its owning rule's Fix pattern; preparatory mode reshapes ahead of a planned change (Phase 1.5) |
 | [`@pre-commit-review`](skills/pre-commit-review/SKILL.md) | Orchestrates the hunter/skeptic review (Phase 4); reports, never edits |
 | [`@testing`](skills/testing/SKILL.md) | The composition ladder — test each behavior at the lowest rung that contains it |
-| [`@documentation`](skills/documentation/SKILL.md) | Repo-brain author (R9) — behavior docs + network wiring; FEATURE mode (Phase 5) / BOOTSTRAP mode |
+| [`@documentation`](skills/documentation/SKILL.md) | Repo-brain author (R9) — behavior docs + network wiring, OKF conformance + conventions self-hosting; FEATURE mode (Phase 5) / BOOTSTRAP mode |
 
 **Agents → spawned by** (payload-fed, isolated):
 
@@ -126,7 +127,7 @@ Isolated contexts matter: the `lint-fixer` loop's token noise stays out of your
 | [`/go-ldd-analyze [files]`](commands/go-ldd-analyze.md) | 🔍 Tests + lint + review, combined report | ❌ No | ✅ Optional |
 | [`/go-ldd-review [files]`](commands/go-ldd-review.md) | 🔍 Commit-readiness check | ❌ No | ✅ Optional |
 | [`/go-ldd-status`](commands/go-ldd-status.md) | Show current phase + progress | N/A | — |
-| [`/wire-repo-brain [path]`](commands/wire-repo-brain.md) | Wire the documentation network in one pass: upward edges → docs → index.md → CLAUDE.md (@documentation BOOTSTRAP) | ✅ Wiring only | ✅ Optional |
+| [`/wire-repo-brain [path]`](commands/wire-repo-brain.md) | Wire the documentation network in one pass: frontmatter → upward edges → docs → index.md → CLAUDE.md/AGENTS.md + conventions.md + conformance script (@documentation BOOTSTRAP) | ✅ Wiring only | ✅ Optional |
 
 ## How Auto-Detection Works
 

go-linter-driven-development/commands/wire-repo-brain.md

@@ -19,20 +19,43 @@ mode** against `$ARGUMENTS` (default: the current repo root). The skill's protoc
 authoritative; this command adds nothing to it. One pass delivers the whole chain:
 
 1. Doc root discovered (`.ai/` → `.ainav/` → `docs/`; per sub-project in a monorepo)
-2. Existing docs inventoried and classified (stale docs indexed with a ⚠️ flag)
-3. `index.md` built — short, grouped, one line per doc (map of maps past ~300 lines)
-4. CLAUDE.md wired with the `@<docroot>/index.md` import (AGENTS.md: plain reference)
-5. **Upward edges wired**: every confidently-anchorable doc gets its one-line
+2. Existing docs inventoried and classified (stale docs indexed with a ⚠️ flag);
+   OKF frontmatter verified-or-added on content docs, stripped from indexes
+   (un-inferable types reported)
+3. `index.md` built — short, grouped, one line per doc copied from each doc's
+   `description`; the root index carries only `okf_version`
+   (directory-shaped map of maps past ~300 lines)
+4. AGENTS.md routing block authored once (root, and nested per sub-project in a
+   monorepo); CLAUDE.md embeds it (`@AGENTS.md`) + the `@<docroot>/index.md` import
+5. `<docroot>/conventions.md` created/verified (listed first in the index) and the
+   plugin's `scripts/check-repo-brain.sh` installed — the report suggests the CI
+   one-liner
+6. **Upward edges wired**: every confidently-anchorable doc gets its one-line
    `// See <docroot>/<file>.md ...` edge on its front-door symbol
-6. R9 confirmation pass + the advisory findings report (broken edges, edge-policy
-   violations, rung-2 gaps, stale/unwired docs)
+7. R9 confirmation pass — Q1–Q3 and Q7 via the installed script — + the advisory
+   findings report (broken edges, edge-policy violations, rung-2 gaps,
+   stale/unwired docs, types needing a human call)
 
 **What this command does NOT do** (by design — the skill's constraints):
 - Generate or rewrite content docs — gaps are reported for FEATURE mode to fill
+  (conventions.md and the copied check script are the two sanctioned artifacts)
 - Decide the fate of stale docs — refresh / remove / keep-as-roadmap is your call
-- Touch anything beyond doc files, `index.md`, CLAUDE.md/AGENTS.md, and one-line
-  godoc edge additions (verified with `go vet` after each)
+- Add CI workflows — the report only suggests `bash scripts/check-repo-brain.sh`
+- Touch anything beyond doc files, `index.md`, `conventions.md`,
+  CLAUDE.md/AGENTS.md, the copied check script, and one-line godoc edge additions
+  (verified with `go vet` after each)
+
+**Language scope**: this is the Go plugin, so code↔docs verification is
+Go-first. On a repo with no Go, the pass still delivers the whole structure
+layer (frontmatter, index, drift check, conventions, routing, CI gate on
+structure) — but code→docs edges, symbol drift detection, and the file-path
+ban only cover `.go` files, and doc roots are only discovered at the repo root
+and `go.mod` sub-projects (a TS/Python sub-project's own docs/ is not wired —
+it is reported, not silently skipped). Non-Go CamelCase symbols cited in
+covered docs still resolve via the gate's whole-word fallback.
 
 When it finishes, review the report, then `git diff` — the changes should read as
 pure documentation-network wiring. Re-run any time: the pass is idempotent (existing
-index lines are refreshed, existing edges and wiring are verified, not duplicated).
+index lines are refreshed from frontmatter; existing edges, wiring, conventions, and
+the script are verified, not duplicated — a repo wired by an older plugin version
+converges to the current rules in one pass).