ADR-0047: Documentation Architecture Migration Bridge
Status
Accepted -- 2026-05-02
Author: Ben Peries (orchestrator session 05-01-26-A)
Context
ADR-0000 established the two-tier documentation model and the 3-class / 11-prefix ADR
taxonomy. This ADR is the last entry in the legacy flat-numbering scheme (0001--0046,
OT-0001--OT-0010) and documents the migration event that transitions all 56 existing
ADRs to their new paths under the taxonomy.
This document serves as the permanent cross-reference: any reader holding a legacy ADR
number can look it up here to find its new canonical location.
Decision
The migration is executed in phases per the A.3 session plan (orchestrator: 05-01-26-A).
Each phase produces one or more PRs linked to umbrella WI-389. The phases are:
- Phase A (this ADR + ADR-0000): author taxonomy spine and migration bridge
- Phase B: expand DLP rules; create class folder skeleton
- Phase C: migrate
security/ class
- Phase D: migrate
it/ class
- Phase E: migrate
ot/ class; retire wiki-bound ADRs
- Phase F: update cross-references; restructure mkdocs.yml nav
- Phase G: author Tier 2 wiki pages
- Phase H: verification and close
Legacy ADR files at old paths will have a deprecation banner added during their
respective migration phases. Old files are NOT deleted -- they retain the banner and
a pointer to the new path, preserving the audit trail.
Migration Map
Security Class
GOV -- Governance
| Old path |
Old title |
New path |
Migration action |
adr/0001-hybrid-branching-strategy.md |
ADR-0001: Hybrid Branching Strategy |
adr/security/GOV/GOV-0001-wi-first-branching.md |
Rename; content preserved |
adr/0022-ado-project-consolidation-and-board-structure.md |
ADR-0022: ADO Project Consolidation |
adr/security/GOV/GOV-0002-ado-project-consolidation.md |
Rename; content preserved |
adr/0028-ado-board-single-source-of-truth.md |
ADR-0028: ADO Board SSOT |
adr/security/GOV/GOV-0003-ado-board-single-source-of-truth.md |
Rename; content preserved |
adr/0035-session-traceability-convention.md |
ADR-0035: Session Traceability |
adr/security/GOV/GOV-0004-session-traceability-convention.md |
Rename; content preserved |
adr/0008-caneast-public-naming.md |
ADR-0008: CanEast Public Naming |
adr/security/GOV/GOV-0005-public-naming-convention.md |
Rename; content preserved (governance decision -- naming is a DLP-adjacent policy, not an APPSEC pattern) |
RISK -- Risk and Threat Posture
| Old path |
Old title |
New path |
Migration action |
adr/0037-secure-boot-posture.md |
ADR-0037: Secure Boot Posture |
adr/security/RISK/RISK-0001-fleet-secure-boot-posture.md |
Rename; content preserved; Tier 1 only (not published) |
IAM -- Identity and Access Management
| Old path |
Old title |
New path |
Migration action |
adr/0002-infisical-for-secrets.md |
ADR-0002: Infisical for Secrets |
adr/security/IAM/IAM-0001-infisical-secrets-management.md |
Rename; content preserved |
adr/0005-it-ot-separation-scope.md |
ADR-0005: IT/OT Separation Scope |
adr/security/IAM/IAM-0002-it-ot-zone-separation-policy.md |
Rename; content preserved |
adr/0014-ansible-service-account.md |
ADR-0014: Ansible Service Account |
adr/security/IAM/IAM-0003-it-service-accounts.md |
Rename; content preserved; IT-scoped section labeled |
adr/0046-it-ot-ansible-service-account-separation.md |
ADR-0046: IT/OT Ansible Service Account Separation |
adr/security/IAM/IAM-0004-ot-service-accounts.md |
Rename; content preserved verbatim (CISO conditions retained) |
adr/0042-external-secrets-operator.md |
ADR-0042: External Secrets Operator |
adr/security/IAM/IAM-0005-external-secrets-operator.md |
Rename; content preserved |
APPSEC -- Application and Supply-Chain Security
| Old path |
Old title |
New path |
Migration action |
adr/0003-grype-over-trivy.md |
ADR-0003: Grype over Trivy |
adr/security/APPSEC/APPSEC-0001-supply-chain-scanning.md |
Consolidated with ADR-0040 (Aikido); TeamPCP incident preserved as labeled subsection |
adr/0040-aikido-security-scanner.md |
ADR-0040: Aikido Security Scanner |
consolidated into APPSEC-0001 |
Sources section lists ADR-0003 and ADR-0040 |
adr/0017-public-docs-pipeline.md |
ADR-0017: Public Docs Pipeline |
adr/security/APPSEC/APPSEC-0002-public-docs-dlp-controls.md |
Consolidated with ADR-0018 and ADR-0033 |
adr/0018-sanitization-verification-strategy.md |
ADR-0018: Sanitization Verification Strategy |
consolidated into APPSEC-0002 |
Sources section lists ADR-0017, ADR-0018, ADR-0033 |
adr/0033-public-docs-security-controls.md |
ADR-0033: Public Docs Security Controls |
consolidated into APPSEC-0002 |
Sources section lists ADR-0017, ADR-0018, ADR-0033 |
SECOPS -- Security Operations
| Old path |
Old title |
New path |
Migration action |
adr/0027-purple-team-tooling.md |
ADR-0027: Purple Team Tooling |
adr/security/SECOPS/SECOPS-0001-purple-team-tooling.md |
Rename; content preserved |
IT Class
| Old path |
Old title |
New path |
Migration action |
adr/0004-opnsense-kvm-not-docker.md |
ADR-0004: OPNsense KVM Deployment |
adr/it/PLAT/PLAT-0001-opnsense-kvm-deployment.md |
Rename; content preserved |
adr/0016-k3s-namespace-design.md |
ADR-0016: k3s Namespace Design |
adr/it/PLAT/PLAT-0002-k3s-namespace-design.md |
Rename; content preserved |
adr/0034-k3s-cp-migration-caneast-site1-node4.md |
ADR-0034: k3s CP Migration caneast-site1-node4 |
adr/it/PLAT/PLAT-0003-k3s-control-plane-node-placement.md |
Standalone; NOT addendum to PLAT-0002 |
adr/0019-systemd-timesyncd-over-chrony.md |
ADR-0019: systemd-timesyncd |
adr/it/PLAT/PLAT-0004-fleet-conventions.md |
Consolidated with ADR-0024 and ADR-0036 |
adr/0024-region-based-node-naming.md |
ADR-0024: Region-Based Node Naming |
consolidated into PLAT-0004 |
Sources section lists ADR-0019, ADR-0024, ADR-0036 |
adr/0036-sudo-provider-pin.md |
ADR-0036: Sudo Provider Pin |
consolidated into PLAT-0004 |
Sources section lists ADR-0019, ADR-0024, ADR-0036 |
adr/0043-cert-manager-letsencrypt-dns01.md |
ADR-0043: cert-manager Let's Encrypt |
adr/it/PLAT/PLAT-0005-cert-manager-letsencrypt.md |
Rename; content preserved |
adr/0044-traefik-ingressroutes-tls.md |
ADR-0044: Traefik IngressRoutes TLS |
adr/it/PLAT/PLAT-0006-traefik-ingressroute-tls.md |
Rename; content preserved |
adr/0006-power-outage-strategy.md |
ADR-0006: Power Outage Strategy |
adr/it/PLAT/PLAT-0007-power-outage-strategy.md |
Rename; content preserved (IT infrastructure resilience; UPS/DR scope) |
adr/0007-standalone-flood-detection.md |
ADR-0007: Standalone Flood Detection |
adr/it/PLAT/PLAT-0008-flood-detection.md |
Rename; content preserved (IT infrastructure resilience decision; OT sensor implementation captured in OT-XXXX) |
adr/0013-ansible-core-fqcn-requirement.md |
ADR-0013: Ansible Core FQCN Requirement |
adr/it/PLAT/PLAT-0009-ansible-quality-enforcement.md |
Consolidated with ADR-0020; both authored 2026-04-02, same v0.4 baseline run, inseparable decisions (FQCN and lint profile are one enforcement surface) |
adr/0020-ansible-lint-production-profile.md |
ADR-0020: Ansible Lint Production Profile |
consolidated into PLAT-0009 |
Sources: ADR-0013 + ADR-0020; retained as ADR (quality bar decision affecting CI behavior, not pure tool selection) |
adr/0025-multi-cloud-terraform-strategy.md |
ADR-0025: Multi-Cloud Terraform Strategy |
adr/it/PLAT/PLAT-0010-multi-cloud-terraform-strategy.md |
Rename; content preserved |
NET -- Network Architecture
| Old path |
Old title |
New path |
Migration action |
adr/0041-dns-architecture.md |
ADR-0041: DNS Architecture |
adr/it/NET/NET-0001-dns-architecture.md |
Rename; content preserved |
OBS -- Observability
| Old path |
Old title |
New path |
Migration action |
adr/0009-telegram-over-whatsapp.md |
ADR-0009: Telegram over WhatsApp |
adr/it/OBS/OBS-0001-observability-stack.md |
Consolidated with ADR-0038 and ADR-0045 |
adr/0038-it-observability-data-plane.md |
ADR-0038: IT Observability Data Plane |
consolidated into OBS-0001 |
Headlamp included as labeled section per orchestrator |
adr/0045-headlamp-kubernetes-dashboard.md |
ADR-0045: Headlamp Kubernetes Dashboard |
consolidated into OBS-0001 |
Sources: ADR-0009, ADR-0038, ADR-0045 |
DEV -- Developer Environment
| Old path |
Old title |
New path |
Migration action |
adr/0011-claude-code-iac-authoring.md |
ADR-0011: Claude Code IaC Authoring |
adr/it/DEV/DEV-0001-developer-environment.md |
Consolidated with ADR-0012, ADR-0021, ADR-0026 |
adr/0012-wsl-ubuntu-alienware-dev-env.md |
ADR-0012: WSL Ubuntu Dev Env |
consolidated into DEV-0001 |
Sources: ADR-0011, ADR-0012, ADR-0021, ADR-0026 |
adr/0021-claude-code-developer-tooling.md |
ADR-0021: Claude Code Developer Tooling |
consolidated into DEV-0001 |
Sources: ADR-0011, ADR-0012, ADR-0021, ADR-0026 |
adr/0026-claude-code-optimization-mcp.md |
ADR-0026: Claude Code MCP Optimization |
consolidated into DEV-0001 |
Sources: ADR-0011, ADR-0012, ADR-0021, ADR-0026 |
adr/0031-alienware-workstation-as-code.md |
ADR-0031: CanEast AI Node Workstation-as-Code |
adr/it/DEV/DEV-0002-alienware-workstation-as-code.md |
Standalone; content preserved |
adr/0032-workstation-secret-zero.md |
ADR-0032: Workstation Secret Zero |
adr/it/DEV/DEV-0003-workstation-secret-zero.md |
Standalone; cross-references IAM-0001 |
LLMOPS -- LLM Operations
| Old path |
Old title |
New path |
Migration action |
adr/0029-openclaw-adoption.md |
ADR-0029: OpenClaw Adoption |
adr/it/LLMOPS/LLMOPS-0001-openclaw-gateway.md |
Rename; content preserved |
adr/0030-ask-archy-docs-chat-widget.md |
ADR-0030: Ask Archy Docs Chat Widget |
adr/it/LLMOPS/LLMOPS-0002-agent-plane.md |
Consolidated with ADR-0039 |
adr/0039-ai-operations-agent-plane.md |
ADR-0039: AI Operations Agent Plane |
consolidated into LLMOPS-0002 |
Sources: ADR-0030, ADR-0039 |
OT Class
OT ADRs are renumbered within the ot/OT- prefix, restarting at OT-0001. Note: this
is a renumber of the new canonical files under adr/ot/, not a change to the legacy
OT-XXXX numbering scheme used in old filenames.
| Old path |
Old title |
New path |
Migration action |
adr/OT-0001-sensor-naming-convention.md |
OT-0001: Sensor Naming Convention |
adr/ot/OT-0001-sensor-hardware-conventions.md |
Consolidated with OT-0003, OT-0004, OT-0008 |
adr/OT-0003-rain-sensor-pin34.md |
OT-0003: Rain Sensor Pin 34 |
consolidated into ot/OT-0001 |
Hardware-specific finding; preserved as labeled subsection |
adr/OT-0004-hcsr04-mm-not-cm.md |
OT-0004: HC-SR04 mm not cm |
consolidated into ot/OT-0001 |
Hardware convention; preserved as labeled subsection |
adr/OT-0008-snr02-basement-freezer-sensor-node.md |
OT-0008: snr02 Basement Freezer |
consolidated into ot/OT-0001 |
Hardware record; preserved as labeled subsection |
adr/OT-0002-mqtt-topic-structure.md |
OT-0002: MQTT Topic Structure |
adr/ot/OT-0002-mqtt-topic-structure.md |
Rename only; content preserved verbatim |
adr/OT-0005-influxdb-historian-retention.md |
OT-0005: InfluxDB Historian Retention |
adr/ot/OT-0003-historian-retention.md |
Rename; OT-0010 fold deferred until OT-0010 reaches Accepted |
adr/OT-0006-isa182-alarm-rationalization.md |
OT-0006: ISA 18.2 Alarm Rationalization |
adr/ot/OT-0004-alarm-rationalization-cmms.md |
Consolidated with OT-0007 |
adr/OT-0007-cmms-integration.md |
OT-0007: CMMS Integration |
consolidated into ot/OT-0004 |
Sources: OT-0006, OT-0007 |
adr/OT-0009-grafana-dashboard-taxonomy.md |
OT-0009: Grafana Dashboard Taxonomy |
adr/ot/OT-0005-dashboard-taxonomy.md |
Rename; content preserved |
adr/OT-0010-historian-retention-architecture.md |
OT-0010: Historian Retention Architecture |
stays at adr/OT-0010-... (Proposed) |
Deferred; folds into ot/OT-0003 when Accepted |
Retired to Wiki
The following legacy ADRs document tooling decisions or platform state that belongs in
Tier 2 or Tier 3 wiki pages, not the ADR record. Their content is migrated to
docs/architecture/governance/documentation-toolchain.md during Phase E.
Original files retain a deprecation banner; they are not deleted.
| Old path |
Old title |
Destination |
Notes |
adr/0010-mermaid-over-kroki-d2.md |
ADR-0010: Mermaid over Kroki/D2 |
docs/architecture/governance/documentation-toolchain.md |
Tool selection; not an architectural pattern |
adr/0015-internal-documentation-platform.md |
ADR-0015: Internal Documentation Platform |
docs/architecture/governance/documentation-toolchain.md |
Platform selection; superseded by current stack |
adr/0023-multi-repo-docs-aggregation.md |
ADR-0023: Multi-Repo Docs Aggregation |
docs/architecture/governance/documentation-toolchain.md |
Build pipeline decision; operational |
Previously Unverified -- Now Resolved
All 6 ADRs that were flagged as requiring classification verification have been
resolved by orchestrator review on 2026-05-02. Their placements are now in the
PLAT and GOV tables above. No unverified ADRs remain.
| ADR |
Resolved placement |
0006 |
it/PLAT/PLAT-0007 |
0007 |
it/PLAT/PLAT-0008 |
0008 |
security/GOV/GOV-0005 |
0013 + 0020 |
it/PLAT/PLAT-0009 (consolidated) |
0025 |
it/PLAT/PLAT-0010 |
ADR-0000 and ADR-0047
These two ADRs are anchors and remain at the root docs/adr/ path. They are not
subject to the class/prefix numbering scheme. They will remain in the mkdocs.yml nav
at the top of the Decisions section indefinitely.
Consequences
- All 56 legacy ADRs have a documented migration destination
- ADR-0047 is the single lookup table for any reader holding a legacy ADR number
- The migration is phased (A through H) to allow incremental review
- Legacy files are never deleted; deprecation banners point to new paths
- OT-0010 (Proposed) is deliberately not migrated until it reaches Accepted status;
it will fold into ot/OT-0003 at that time
References
- ADR-0000: Documentation Architecture (taxonomy spine)
- Umbrella WI: WI-389 (feat(docs): two-tier documentation architecture migration)
- Session: A.3 (orchestrator: 05-01-26-A)