feat: give agents a briefing, split the docs, and generate the diagrams from source

[PIsberg]

The problem

CLAUDE.md was 100% generated. Every line sat between the VibeTags markers. An agent opening this repo learned the security guardrails and nothing else — not what Skill3 is, not the two invariants the whole design serves, not where anything lives, not how to build it.

Three changes with one theme: what gets loaded on every session should orient you.

1. A hand-written briefing

CLAUDE.md now opens with what Skill3 is, the two invariants (a skill is a post-cutoff delta, not a primer; discovery is topic-agnostic), a where-to-read-what table, the build commands, and the five things that will bite someone changing this code — the marker rule, the enforced layering, the untrusted-data path, and that absence of findings is never asserted.

It lives outside the markers, so every compile leaves it alone. Verified by recompiling and confirming it survived.

2. Guardrails split by tier

Adding .claude/rules/ switches VibeTags to its indexed layout:

before   90 lines, everything inline, no orientation
after   140 lines — 57 hand-written briefing + safety tier inline
                  + 20 scoped rule files loaded on demand

The always-on tier (privacy, core, security) stays inline; per-element detail moves to scoped files a host tool loads when you open a matching source file.

This requires 1.0.0-RC8. Before it, the indexed root kept nothing inline — an @AIPrivacy rule on the Brave key only loaded once an agent opened the file holding the key, by which point it has become a comment. RC1 → RC8 also fixes XML escaping in the generated region (" was emitted raw).

3. README split by task

446 lines covering pitch, install, usage, development and sample output → a 171-line landing page plus:

New	Lines
docs/INSTALL.md	69
docs/USAGE.md	143
docs/DEVELOPMENT.md	81
docs/EXAMPLE-OUTPUT.md	45

Someone installing no longer scrolls past the release process. Moved sections had their repo-root links re-rooted, and three README anchors pointing at now-moved sections were repointed. All 57 relative links verified to resolve by a checker run after every edit.

4. Diagrams parsed, not drawn

./gradlew diagrams renders four SVGs straight from src/main/java with code-karta, pinned from Maven Central so no local checkout is needed, on a tool-only configuration that never touches a compile or runtime classpath.

• model — what flows between stages
• llm — why --llm-provider works: both providers implement one ChatModel
• pipeline — discovery/ingestion collaborators and the two seams FileCorpus implements both of
• pipeline (stitched call graph) — linked, not inlined; it's 3460×2974

The hand-drawn mermaid graph in ARCHITECTURE.md stays. It shows the pipeline as intended; these show it as written. Verified byte-identical across re-runs, so they stay out of review diffs unless the structure really moved.

No module diagram — Skill3 has no module-info.java, so it would have nothing to show. Ruled out rather than shipped empty.

5. Eight new annotations

Coverage was 13 of 95 files, skewed to security. Each addition records an invariant the code cannot state itself:

• @AIContract on ChatModel, SearchClient, PageFetcher — the seams that make the pipeline testable with no network and no model
• @AILoadBearing on FileCorpus (implements both discovery seams on purpose — it looks like a layering slip and is the design) and InputVetter (quarantine is mitigation, not amnesty; redaction is unconditional)
• @AISchemaSafe on RunManifest — its component names are the run.json field names
• @AIIdempotent on SkillMdPostProcessor.render(), which SelfCorrectionLoop re-runs on its own output
• @AIDomainModel + @AIArchitecture on Source, mirroring the layering ArchitectureTest already enforces

Verification

./gradlew build — BUILD SUCCESSFUL: Error Prone, PMD, SpotBugs, ArchUnit and the JaCoCo gate (75% instruction / 65% branch) all pass. Regeneration is stable: recompiling with a cleared .vibetags-cache produces no diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_0153QiTQsRQEikh9pHa5zrpC