feat(rules): bootstrap 3 Go doc families (enum-type, composition, build-args)

[bborbe]

Summary

Fifth Go bootstrap batch. 3 docs (120-189 lines), 5 rules.

`rules/index.json`: 90 → 95 entries (3 new families).

Rules added

family / id	level	owner
`go-enum-type/typed-constants-with-collection`	MUST	go-architecture-assistant
`go-enum-type/validate-against-available-collection`	MUST	go-architecture-assistant
`go-composition/no-package-function-calls-in-business-logic`	MUST	go-architecture-assistant
`go-composition/small-interfaces-1-2-methods`	SHOULD	go-architecture-assistant
`go-build-args/three-args-required`	MUST	go-quality-assistant

5 rules across 3 docs — build-args's single MUST is the strong one for that doc; padding wouldn't add signal. Enum + composition have 2 rules each.

Pre-emptive checks

• `grep -nEi` for personal paths + trading terms → clean across all 3 docs
• All 5 rule IDs unique against 90 existing entries
• Both owner agents exist
• CLAUDE.md doc-agent table updated with 3 new rows
• `make build-index` regenerated; `check-index` passes (PR feat(precommit): add check-index target to catch walker-output drift #13 drift guard)

Test plan

• `make precommit` clean
• 5 entries in index with consistent schema
• All rule IDs pass walker validation
• Bot review

[ben-s-pull-request-reviewer]

PR Review Summary

Review of: feat(rules): bootstrap 3 Go doc families (enum-type, composition, build-args)
Branch: feat/bootstrap-go5 → master
Files Changed: CLAUDE.md, docs/go-build-args-guide.md, docs/go-composition.md, docs/go-enum-type-pattern.md, rules/index.json

---

Automated Checks

Check	Result
make precommit	Has precommit target (check-links check-json check-index)
Project type	Plugin repo (Markdown + JSON), not Go library
License file	✅ Present (BSD-2-Clause)
README License section	✅ Present

---

Findings

Must Fix

File	Line	Issue
docs/go-composition.md	24	Unused variable in Bad example — queued := prompt.ListQueued(...) is declared but never used. Go rejects this at compile time. The Bad example is meant to show hidden dependencies, not unused variables — fix by using _ = prompt.ListQueued(...) or passing queued to Execute.

Should Fix

File	Line	Issue
docs/go-enum-type-pattern.md	61	Missing context.Context — the Process(status OrderStatus) error function signature in the Good example should be Process(ctx context.Context, status OrderStatus) error per project conventions. This is a Good example teaching the wrong signature.
docs/go-composition.md	135	Missing context.Context — the Logger interface in the Good example has Log(msg string) but should accept ctx context.Context for trace propagation consistency with glog(ctx, ...).
docs/go-enum-type-pattern.md	42–118	Exported identifiers lack doc comments — both the #### Good block and the ### Minimal Complete Implementation define OrderStatus, OrderStatuses, AvailableOrderStatuses, String(), Validate(), Contains() without GoDoc comments. This directly contradicts the go-doc/exported-item-must-have-comment (MUST) rule the doc itself teaches. Readers who copy these examples get non-compliant code.
docs/go-composition.md	34–53	New "Good" example interfaces lack doc comments — PromptScanner, Releaser, and NewRunner in the diff-added Good block have no GoDoc comments, same issue as above.

Nice to Have

File	Line	Issue
docs/go-enum-type-pattern.md	105	== false vs ! inconsistency — Minimal Complete Implementation uses if AvailableOrderStatuses.Contains(o) == false while the newer Good example (line 147) uses idiomatic if !AvailableOrderStatuses.Contains(o). The latter is canonical — update line 105 to match.
docs/go-enum-type-pattern.md	174	Undefined Priority type referenced — the Order struct has a Priority field of type Priority that is never declared in the example, potentially confusing readers who try to compile it.
docs/go-composition.md	49	Runner return type undeclared — NewRunner returns Runner but the interface is not declared in the code block. Self-contained examples should declare it.
docs/go-build-args-guide.md	19	RULE block placed before its context — go-build-args/three-args-required RULE appears before the ## Layout section that formally introduces the three-file structure. A reader lands on the rule before seeing the implementation.
docs/go-composition.md	110	Composed Service interface not addressed in examples — the small-interfaces-1-2-methods Good example shows a composed Service { Logger; ItemStore; Notifier } with 3+ methods, which could be naively flagged as a violation. The text resolves this but the example doesn't demonstrate the discriminator.

---

Verdict

{
  "verdict": "request-changes",
  "summary": "The PR adds 5 new rule definitions across 3 Go doc families (enum-type, composition, build-args) with correct rules/index.json entries and CLAUDE.md mappings. However, the Go code examples embedded in the docs have two categories of issues: (1) a compile error in the Bad example at go-composition.md:24 (unused variable), and (2) consistent omission of GoDoc comments on exported identifiers in Good examples — directly contradicting the go-doc/exported-item-must-have-comment rule these docs teach. Additionally, two Good examples teach function signatures missing context.Context.",
  "comments": [
    {
      "file": "docs/go-composition.md",
      "line": 24,
      "severity": "critical",
      "message": "Must Fix [go-composition/no-package-function-calls-in-business-logic Bad example]: `queued` is declared and assigned but never used — Go rejects this at compile time. Fix: use `_ = prompt.ListQueued(ctx, r.dir)` or pass `queued` to `Execute`. The Bad example should demonstrate hidden dependencies, not unused variables."
    },
    {
      "file": "docs/go-enum-type-pattern.md",
      "line": 61,
      "severity": "major",
      "message": "Should Fix [go-enum-type/typed-constants-with-collection Good example]: `Process(status OrderStatus) error` is missing `context.Context` as first parameter. Per project conventions (and go-errors/no-context-background-in-business-logic), exported functions doing validation/business logic must accept ctx. Correct signature: `Process(ctx context.Context, status OrderStatus) error`."
    },
    {
      "file": "docs/go-composition.md",
      "line": 135,
      "severity": "major",
      "message": "Should Fix [go-composition/small-interfaces-1-2-methods Good example]: `Logger` interface defines `Log(msg string)` without context. For trace propagation consistency with glog(ctx, ...) conventions, correct shape is `Log(ctx context.Context, msg string)`."
    },
    {
      "file": "docs/go-enum-type-pattern.md",
      "line": 42,
      "severity": "major",
      "message": "Should Fix [go-enum-type/typed-constants-with-collection Good example + Minimal Complete Implementation]: All exported identifiers (OrderStatus, OrderStatuses, AvailableOrderStatuses, String(), Validate(), Contains()) lack GoDoc comments. This directly contradicts the go-doc/exported-item-must-have-comment (MUST) rule these docs teach — readers copying the example get non-compliant code. Add doc comments to all exported items per the rule."
    },
    {
      "file": "docs/go-composition.md",
      "line": 34,
      "severity": "major",
      "message": "Should Fix [go-composition/no-package-function-calls-in-business-logic Good example]: Exported identifiers PromptScanner, Releaser, and NewRunner lack GoDoc comments, contradicting go-doc/exported-item-must-have-comment (MUST)."
    },
    {
      "file": "docs/go-enum-type-pattern.md",
      "line": 105,
      "severity": "nit",
      "message": "Nice to Have [go-enum-type-pattern.md Minimal Complete Implementation]: Uses `if AvailableOrderStatuses.Contains(o) == false` while the newer Good example at line 147 uses idiomatic `if !AvailableOrderStatuses.Contains(o)`. Update line 105 to use `!` for internal consistency."
    },
    {
      "file": "docs/go-enum-type-pattern.md",
      "line": 174,
      "severity": "nit",
      "message": "Nice to Have [go-enum-type-pattern.md Usage Example]: `Order` struct references `Priority Priority` field but `Priority` type is never declared in the example. Either declare it or remove the field to avoid confusing readers who try to compile the snippet."
    },
    {
      "file": "docs/go-composition.md",
      "line": 49,
      "severity": "nit",
      "message": "Nice to Have [go-composition.md NewRunner Good example]: `NewRunner` returns `Runner` interface but `Runner` is not declared in the code block. For self-contained examples, add `type Runner interface { Run(ctx context.Context) error }` above the constructor."
    },
    {
      "file": "docs/go-build-args-guide.md",
      "line": 19,
      "severity": "nit",
      "message": "Nice to Have [go-build-args/three-args-required]: RULE block is placed before the ## Layout section that formally describes the three-file structure (Makefile.docker, Dockerfile, Argument struct). Readers hitting the rule first may lack context for understanding the examples. Consider moving the RULE after the Layout section, or adding a cross-reference."
    },
    {
      "file": "docs/go-composition.md",
      "line": 110,
      "severity": "nit",
      "message": "Nice to Have [go-composition/small-interfaces-1-2-methods]: The composed `Service` interface in the Good example has 3+ methods (Logger+ItemStore+Notifier), which could be naively flagged as a rule violation. The applies_when text correctly explains this is acceptable via composition, but the example itself doesn't call this out. Consider adding a comment in the example explaining the composed interface satisfies ISP."
    }
  ],
  "concerns_addressed": [
    "correctness: rules/index.json rule definitions are syntactically valid and consistent with existing rule schema — confirmed, all 5 entries are well-formed",
    "correctness: go-enum-type-pattern.md enum-type examples are idiomatic with one compile error (unused variable in Bad example at composition:24) and missing context.Context in Good examples",
    "correctness: go-composition.md composition patterns follow Go idioms but have unused variable bug in Bad example",
    "correctness: go-build-args-guide.md build args guidance is accurate for Go toolchain"
  ]
}

superseded by new automated review

[ben-s-pull-request-reviewer]

---

PR Review Report: feat/ruled: bootstrap 3 Go doc families (enum-type, composition, build-args)

Summary

The PR adds 3 new Go documentation guides with 5 new rules, updates the CLAUDE.md agent table, and registers all rules in rules/index.json. All schema fields are consistent and complete.

---

Must Fix (Critical)

None.

---

Should Fix (Important)

None.

---

Nice to Have (Optional)

None — all cross-references verified, agents exist, JSON valid, README/llms.txt already had entries.

---

Concerns Addressed

• correctness:rules/index.json: 5 new rule entries verified — all have anchor, applies_when, doc_path, enforcement, id, level, owner. No duplicate IDs.
• correctness:CLAUDE.md: Agent table updated with 3 new rows. go-enum-type-pattern.md → go-architecture-assistant ✓, go-composition.md → go-architecture-assistant ✓, go-build-args-guide.md → go-quality-assistant ✓. All three agents exist in agents/.
• correctness:README/llms.txt: Both already contained entries for the 3 new docs — no drift.
• docs:cross-refs: go-build-args-guide.md:221 references go-makefile-commands.md — file exists. go-enum-type-pattern.md:214 references go-validation-framework-guide.md — file exists.

---

{
  "verdict": "approve",
  "summary": "PR adds 5 high-quality rules across 3 new Go doc families with consistent schema, correct agent assignments, and valid cross-references. No mechanical issues found in rules/index.json, CLAUDE.md, or doc cross-links.",
  "comments": [],
  "concerns_addressed": [
    "correctness: rules/index.json — 5 new entries verified complete with all required fields, no duplicate IDs",
    "correctness: CLAUDE.md — 3 new agent table rows correctly map docs to existing agents (go-architecture-assistant, go-quality-assistant)",
    "docs: cross-references — go-makefile-commands.md and go-validation-framework-guide.md both exist",
    "correctness: README.md and llms.txt already contained entries for all 3 new docs"
  ]
}