docs: docs/solutions/ design-decision library (KLA-445)

[jklaassenjc]

Summary

A grep-able library of non-obvious decisions made in jc-cli, modeled after jamf-cli's docs/solutions/. Pins decisions next to the systems they constrain via stable filenames + YAML-frontmatter tags, so future contributors (human or agent) don't redo settled debates.

Layout

docs/solutions/
├── README.md                  conventions + frontmatter spec
├── design-patterns/           architectural / structural decisions
├── conventions/               coding conventions and style rules
├── postmortems/               what-went-wrong and how-we-recovered
└── lint_test.go               frontmatter enforcement (CI gate)

Seed entries (7)

Pulled from the KLA-408..452 arc:

design-patterns/

• step-up-auth-chokepoint — reflection on Execute bool for one-gate-across-30-tools
• pre-flight-before-step-up — input validation runs before the gate (Bugbot PR feat(mcp): Apple MDM payloads as MCP tools (KLA-452) #60 catch)
• mcp-app-registration-shapes — appSpec (no-args) vs typed (parameterized) MCP Apps

conventions/

• parallel-mcp-and-cli-taxonomies — MCP tools and Cobra commands are siblings, not 1:1
• aggregate-validation-errors — every problem in one pass (multi-payload compose)
• empirical-gate-before-coding — hit the live tenant before writing the emitter (KLA-450 iOS)
• worst-case-capability-classification — jc:class worst-case rule (Bugbot PR feat(cmd): jc:class annotation registry + CI lint (KLA-444) #62)

postmortems/

• stacked-pr-self-approval-blocked — PR feat(apple-mdm): payloads template — offline .mobileconfig emitter (KLA-449 PR2/3) #50-54 → consolidated bundle PR feat(apple-mdm): emitter + create-policy + TUI authoring + edit (KLA-449/453/454/455) #55

Frontmatter contract

Every file declares title / date / category / module / tags / applies_when (and optional superseded_by). TestEverySolutionFileHasFrontmatter (docs/solutions/lint_test.go) enforces required fields and refuses files whose declared category disagrees with their parent directory.

AGENTS.md pointer

A new top-of-file section tells agents to grep docs/solutions/ before starting any non-trivial structural work:

grep -rl \"tags:.*mcp\" docs/solutions/
grep -rl \"module: internal/apple_mdm\" docs/solutions/

Test plan

• TestEverySolutionFileHasFrontmatter enforces required fields + category/dir consistency
• go test ./... green
• Every seed entry's frontmatter parses
• Cross-references between entries resolve (relative-path links)
• CI passes
• Bugbot review

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and test-only enforcement only; no production or auth behavior changes.

Overview
Introduces a grep-able docs/solutions/ library for non-obvious design decisions (patterns, conventions, postmortems), with YAML frontmatter (title, date, category, module, tags, applies_when) and a README that defines layout, filenames, and authoring rules.

Seven seed entries document settled choices from the MCP/Apple MDM arc (e.g. step-up chokepoint on Execute, pre-flight before step-up, MCP vs CLI taxonomies, aggregate validation, empirical API probing, worst-case jc:class, stacked-PR review deadlock).

Adds docs/solutions/lint_test.go (TestEverySolutionFileHasFrontmatter) so CI fails on missing frontmatter, invalid categories, or category/directory mismatches.

AGENTS.md gets a top section telling agents to search docs/solutions/ before non-trivial structural work, with example grep commands.

^{Reviewed by Cursor Bugbot for commit fee4ac3. Bugbot is set up for automated code reviews on this repo. Configure here.}