[enilsen16]

Problem

Six kind docs and rule docs cite a design decision by number only, for example "Decision #27: slug == namespace." Agents get these docs from list_entity_kinds and list_validation_rules. No list of decisions exists that an agent can read, so a bare number tells the agent nothing. The Schema kind doc cites "Decision #33." and gives no rule at all.

Change

• Each of the six docs now states its rule in one plain sentence. The rule text comes from the proto comments and the validator code:
  • Read model: give each consumer its own read model. Declare a SharedConsumersAnnotation when one read model serves several on purpose.
  • Bounded context: its slug must equal its namespace, so each namespace has exactly one bounded context.
  • Schema: two entities that hold the same schema are the same type, because shape is declared, not inferred.
  • SLICE_STALE_REF, CONTEXT_SLUG_MISMATCH: the rule was already in the text. The change removes the number.
  • SEAM_WITHOUT_RELATIONSHIP: declare the relationship on the downstream context, so the relationship intent and the seam data agree.
• No other agent-visible string (MCP server instructions, tool descriptions, validation messages, CLI output) cites a decision number.
• Code comments and proto comments keep their numbers.

A full decisions document stays with the maintainer. Only the maintainer knows what each number originally said, and the proto has no list to generate it from.

Test

• New tests/catalog_docs.rs checks that no entity kind doc and no validation rule doc contains "Decision #". It failed on the six docs before the change and passes after it.
• cargo test -p trogon-atlas-server passes. cargo clippy -p trogon-atlas-server --all-targets -- -D warnings is clean.

Closes #82

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: c0f9ad14-1ff7-4d8a-93d8-a79dd671f740

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

PR Summary

Low Risk
Documentation-only changes to agent-visible catalog strings plus a regression test; no validation logic or runtime behavior changes.

Overview
Agent-facing entity kind and validation rule catalog text in validation.rs no longer cites opaque “Decision #…” labels. Six entries now spell out the rule in plain language (read models per consumer + SharedConsumersAnnotation, bounded-context slug/namespace, schema-as-type identity, stale slice refs, context slug mismatch, and declaring relationships when a seam exists).

A new catalog_docs.rs test fails if any kind or rule doc still contains Decision #, so MCP consumers of list_entity_kinds / list_validation_rules always get self-contained guidance.

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