Skip to content

docs: consolidate OWASP and compliance documentation under docs/compliance/ #2435

@Ricky-G

Description

@Ricky-G

Part of the docs/ IA streamlining series. As AGT grows, our documentation has accumulated overlap, drift, and scattered ownership. This issue is the third in a coordinated cleanup that started with the link-and-frontmatter CI foundation (#2400, shipped in PR #2401). The series will end with a top-level IA pass and a strict-mode frontmatter gate.

Summary

Consolidate OWASP and compliance documentation under a single canonical home at docs/compliance/. Eliminate the three-way split for OWASP ASI coverage and give every framework AGT maps to a dedicated, discoverable page.

Problem

Compliance content is fragmented across three locations with overlapping OWASP ASI coverage tables:

  • docs/OWASP-COMPLIANCE.md
  • docs/owasp-asi-mapping.md
  • docs/compliance/ (already exists, partially populated)

Readers cannot tell which is canonical. The two root OWASP files contain near-duplicate coverage tables that have drifted apart over time. Other compliance frameworks referenced in the repo (NIST AI RMF, EU AI Act, SOC2 where cited) have no dedicated home at all.

Note: docs/proposals/OWASP-ASI-PROPOSAL.md is out of scope — proposals will be handled in a separate future initiative.

Proposed Changes

Path What changes
docs/compliance/index.md New landing page — framework matrix linking to each framework's page.
docs/compliance/owasp/asi.md New: single canonical ASI coverage page. Merge OWASP-COMPLIANCE.md + owasp-asi-mapping.md, keep the most concrete control mapping table, delete redundant prose.
docs/compliance/nist-ai-rmf.md New stub if AGT claims NIST mapping anywhere in the repo (verify during the PR).
docs/compliance/eu-ai-act.md New stub if AGT claims EU AI Act mapping anywhere in the repo.
docs/compliance/soc2.md New stub if AGT claims SOC2 alignment anywhere in the repo.
docs/OWASP-COMPLIANCE.md Removed (redirect added).
docs/owasp-asi-mapping.md Removed (redirect added).
mkdocs.yml Updated nav with a single "Compliance" section; cross-links to the new docs/security/ section from the sibling issue.
mkdocs.yml redirect plugin Entries for both removed pages.
scripts/docs/.linkcheck-baseline.txt Remove entries fixed as a side-effect.

Out of Scope

  • No new compliance claims. If a framework is not already mapped somewhere in the repo, do not add a stub for it.
  • Security docs — covered by the sibling issue in this series.
  • Proposals folder cleanup — separate future initiative.

Acceptance Criteria

  • Exactly one OWASP ASI coverage page exists in the repo.
  • docs/compliance/index.md lists every framework AGT currently claims to map to, each linking to a dedicated page.
  • The two legacy root OWASP pages are removed (with redirects).
  • python scripts/docs/check_links.py shows fewer baseline entries after this PR than before.
  • All internal cross-references updated.

Testing

  • python scripts/docs/check_links.py --root . must pass (no new broken links).
  • mkdocs serve locally: confirm the Compliance section loads and the two legacy URLs redirect.
  • Diff the two old OWASP coverage tables and document any conflicts resolved in the PR description.

Series

# Issue Status
1 #2400 — Link checker and frontmatter CI foundation Shipped (#2401)
2 Consolidate security documentation Pending
3 This issue — Consolidate OWASP and compliance documentation Pending
4 Consolidate release, publishing, and versioning documentation Planned
5 Top-level IA pass and stale-doc audit (flips frontmatter to strict, deletes baseline) Planned

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions