docs(diagrams): add mmd template, architecture metadata, linter support and ADR-040

[SatoryKono]

Motivation

• Standardize the canonical .mmd diagram format and metadata so decomposed views and CI checks can be automated.
• Prevent unreadable large Mermaid diagrams by enforcing node-size guidance and a superseded workflow for historical sources.
• Enforce visual/style governance (single source of truth for theme/colors) and add CI-driven linting to prevent regressions.

Description

• Add a canonical template docs/02-architecture/mmd-diagrams/_template.mmd with standardized %% @* metadata and theming guidance.
• Annotated all architecture/*.mmd files with %% @status active and %% @nodes <count> (18 files updated) and created docs/02-architecture/decisions/ADR-040-diagram-governance.md documenting the new governance.
• Updated docs/02-architecture/mmd-diagrams/render.sh to skip files marked %% @status superseded during rendering.
• Reworked scripts/lint_diagrams.py to support canonical .mmd plus legacy .mermaid, to skip superseded/legend files, and to add checks for VIEW-*, SIZE-*, COLOUR-* and HACK-* rules and node-count heuristics.
• Added a local pre-commit hook entry lint-diagrams in .pre-commit-config.yaml and updated docs/02-architecture/mmd-diagrams/README.md and docs/02-architecture/06-diagram-policy.md to reference ADR-040 and the new rules.

Testing

• Ran Python byte-compile for the linter with python -m py_compile scripts/lint_diagrams.py which succeeded.
• Executed the linter against the architecture diagrams with python scripts/lint_diagrams.py docs/02-architecture/mmd-diagrams/architecture --stale-days 365, which reported expected policy issues including SIZE-001 (CRITICAL oversized diagrams) for files such as 01-high-level-hexagonal.mmd, 03-medallion-data-flow.mmd, and 13-port-protocol-contracts.mmd, and CONTENT-001 (placeholder) for 05-provider-adapter-hierarchy.mmd.
• Attempted pre-commit run surfaced unrelated repository baseline issues (missing pip-audit in the environment, legacy config-path references, and root-level VCR cassettes) which are out-of-scope for this PR and do not block the functional changes to templates, linter, render script, and ADR.

---

Codex Task

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[SatoryKono]

Superseded by #2422.