[yordis]

• Architectural declarations need explicit identity and lifecycle rules before labels can be mistaken for behavioral or runtime evidence.
• Deployable and external boundaries must retain their existing meaning while abstract grouping and actor aggregation remain separate decisions.
• Native acceptance must protect exact subjects, visibility and Source isolation before support is considered complete.

[cursor]

PR Summary

Low Risk
Documentation-only specification with no schema, backend, or test changes; risk is limited to doc accuracy and future implementation alignment.

Overview
Adds proposed (not implemented) reference docs for labeled directed relationships between Component and ExternalSystem, and wires them into the docs index, architecture roadmap, and coverage table.

system-relationship-contracts.md defines a bounded declaration layer: repeated ArchitecturalRelationship on owners, typed endpoints with exact versions, connection identity, reference/subject/impact behavior, admission and visibility rules, and explicit deferrals (abstract grouping, containment via labels, system-level interactions, message flow). Labels stay descriptive and separate from behavioral or runtime evidence; source integration must reject adoption/ownership of these fields.

system-relationship-acceptance.md specifies executable acceptance (fixtures, public API outcomes, lifecycle/admission matrix, auth/bounds, negative assertions that relationships do not imply membership or processors) with status that no tests are claimed today.

Roadmap and architecture-resource-coverage now point at this proposal as a specification milestone rather than implying current native support.

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

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3cbaff06-0a37-4727-bc43-ee3049fa0807

Commits

Reviewing files that changed from the base of the PR and between 5199605 and 63d53e4.

Files selected for processing: 5

• docs/README.md
• docs/explanation/architecture-resource-roadmap.md
• docs/reference/architecture-resource-coverage.md
• docs/reference/system-relationship-acceptance.md
• docs/reference/system-relationship-contracts.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

This pull request adds a proposed system relationship contract and acceptance specification. It links both documents from the reference materials and roadmap. The documents define proposed relationship shapes, lifecycle and admission requirements, scope boundaries, and evidence for future acceptance. They do not report implementation or passing tests.

Changes

System Relationship Specification

Layer / File(s)	Summary
Scope and relationship shape docs/README.md, docs/explanation/architecture-resource-roadmap.md, docs/reference/architecture-resource-coverage.md, docs/reference/system-relationship-contracts.md, docs/reference/system-relationship-acceptance.md	The documentation links to the proposal and defines its proposed scope, typed relationship shape, and fixture setup. It states that the proposal does not establish implementation.
Identity and native surfaces docs/reference/system-relationship-contracts.md, docs/reference/system-relationship-acceptance.md	The proposal specifies identity and lifecycle rules, subject and catalog support, native authoring boundaries, and public-surface acceptance outcomes.
Admission and resource constraints docs/reference/system-relationship-contracts.md, docs/reference/system-relationship-acceptance.md	The proposal specifies guarded atomic publication, visibility protections, resource limits, and failure requirements.
Boundaries and completion evidence docs/reference/system-relationship-contracts.md, docs/reference/system-relationship-acceptance.md	The documents state deferred interaction and negative scope boundaries, and define evidence required for future acceptance.

Priority: Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Other

Possibly related PRs

• TrogonStack/atlas#233: Establishes subject, ConnectionId, selector, and catalog-query boundaries referenced by this proposal.
• TrogonStack/atlas#242: Documents the deferred relationship boundary that this proposal specifies.
• TrogonStack/atlas#237: Defines source-integration boundaries that this proposal applies to architectural relationships.

Merge Risk: Minimal · up to 63d53

The documentation-only proposal is mergeable with no identified current-head risk.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly summarizes the documentation changes. It distinguishes architectural declarations from behavioral and runtime evidence.
Description check		The description directly matches the documented objectives. It addresses identity and lifecycle rules, boundary preservation, and acceptance protections.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (5 skipped: 5 unsupported.)

Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• 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

_{A rabbit reads the contract by the moon,
And marks each typed connection in a tune.
“No runtime proof,” the careful pages say,
“Acceptance needs its evidence one day.”
The rabbit hops, then files the links away.}

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