Documentation Rules

Review implemented validation rules for ADR coverage, architecture documentation, access-control documentation, and suppression hygiene.

Why it matters

Documentation findings keep architecture decisions, security expectations, and accepted-risk records visible for reviewers.

Overview

Review implemented validation rules for ADR coverage, architecture documentation, access-control documentation, and suppression hygiene.

Documentation findings keep architecture decisions, security expectations, and accepted-risk records visible for reviewers.

Why it matters

Cloud uses this guidance to help teams interpret local validation findings in organization context without turning the docs into implementation notes.

When this domain drifts, findings become harder to triage, ownership becomes less clear, and architecture review depends too much on individual memory.

Good architectural practices

ADR and architecture documentation present for important decisions.
Access-control expectations documented for security-sensitive workflows.
Suppressions that include reasons, expiry hygiene, and current finding context.

Common anti-patterns

ADR directory missing
ADR file missing title
ADR status missing or invalid
Required ADR missing for architecture context
Tenant model ADR exists for different-schema model
RBAC or role-based access control mentioned in overview
Suppression reason missing
Suppression expired
Suppression does not match any active finding
Duplicate suppression entry
Suppression expiry format invalid

Relationship to other architecture areas

This domain usually overlaps with neighboring validation categories. Use the related pages below to understand the adjacent architecture concerns before changing policy, suppressing a finding, or accepting risk.

Implemented rules

These are the currently implemented rules in this category. Use this table for category-level orientation, then open the Rule Catalog when you need rule-specific examples and remediation guidance.

Rule ID	Rule title	Category	Severity	Short explanation	Example violation	Remediation guidance	Rule detail
AP-ADR-001	ADR directory missing	Documentation	warning	Checks that the configured ADR directory exists.	Architecture decisions are scattered across pull requests and tickets.	Create the ADR directory. Move ADRs into the configured path or update the configuration. Add a template ADR so future decisions have a consistent shape.	View rule page
AP-ADR-002	ADR file missing title	Documentation	warning	Checks that ADR files include a top-level title.	A markdown ADR starts with plain text and no # heading.	Add a top-level ADR title. Keep the title specific to the decision. Run validation again to confirm the ADR can be indexed.	View rule page
AP-ADR-003	ADR status missing or invalid	Documentation	warning	Checks that ADR files include a recognized decision status.	Status: maybe final	Add a clear status field or status heading. Use a supported value such as accepted where appropriate. Update old ADRs to the current template.	View rule page
AP-ADR-004	Required ADR missing for architecture context	Documentation	warning	Checks that key architecture topics have ADR coverage.	The repository config says REST, but no API style ADR exists.	Add or update an ADR for the missing context. Use clear keywords for the architecture topic. Link the ADR from overview docs when it explains a central system decision.	View rule page
AP-DOC-001	Tenant model ADR exists for different-schema model	Documentation	warning	Checks that different-schema tenant modeling decisions are captured in an ADR.	Tenant isolation changes are only described in a pull request.	Add or update an ADR for the tenant model. Include status, context, decision, and consequences. Link related migrations or operational runbooks.	View rule page
AP-DOC-002	RBAC or role-based access control mentioned in overview	Documentation	warning	Checks that architecture overview documentation mentions RBAC or role-based access control where expected.	The overview describes users and organizations but omits authorization boundaries.	Update the architecture overview with RBAC context. Link to authorization docs or ADRs. Mention the modules or services responsible for access-control decisions.	View rule page
AP-SUP-001	Suppression reason missing	Documentation	warning	Checks that suppression entries include a reason.	{ "ruleId": "AP-DEP-004", "reason": "" }	Add a clear reason. Include owner or review context where your workflow expects it. Prefer exceptions for governed temporary risk acceptance.	View rule page
AP-SUP-002	Suppression expired	Documentation	warning	Flags suppression entries whose expiry date has passed.	A suppression expired last month but still hides an active finding.	Remove the suppression if the finding is fixed. Fix the underlying issue if it is still active. Create a fresh governed exception only if the risk is still intentionally accepted.	View rule page
AP-SUP-003	Suppression does not match any active finding	Documentation	info	Reports suppression entries that no longer match an active finding.	A suppression stays in the file after the matching AP-DEP-004 finding is gone.	Remove unused suppression entries. Refresh suppressions only for findings that are still active. Run validation again to confirm no stale entries remain.	View rule page
AP-SUP-004	Duplicate suppression entry	Documentation	warning	Flags duplicate suppression entries.	Two identical AP-DEP-004 suppression records exist for the same file.	Keep one suppression entry. Prefer the narrowest useful scope. Remove stale duplicates after merge conflict resolution.	View rule page
AP-SUP-005	Suppression expiry format invalid	Documentation	warning	Checks that suppression expiry dates use a valid format.	"expiresAt": "next Friday"	Use a clear ISO-style date. Remove prose from the expiry field. Run validation to confirm the expiry is recognized.	View rule page

Policy & ADR Workflows Quick Fixes, Exceptions & Suppressions Rule Catalog

Next steps

Security Rules Safety Controls