Skip to main content

ADR-0011: Use [web:*] source tags with a central mapping file

  • Status: Accepted
  • Date: 2026-06-17
  • Deciders: Michel Gillet

Context​

A2C workflows rely heavily on external sources: tool and platform documentation, ADR and architecture guidance, language and security practices, and other web references.

Inlining raw URLs in ADRs and design docs makes documents noisy and harder to read. Using shorthand tags like [web:001] without a mapping leaves future readers and AI agents unable to audit, fetch, or refresh the underlying material reliably. It also becomes easy to lose track of which external sources influenced which decisions.

Accepted ADRs are immutable in substance (docs/adr/README.md, rules/08-adr-editing-evolution.md). When an external URL rots, maintenance should not require rewriting ADR decision text. A versioned mapping file separates stable inline tags from maintainable URLs.

This decision supports the A2C value proposition: architecture and workflow knowledge stay readable, auditable, and machine-resolvable for humans and AI-assisted processes.

Decision​

For a2c-managed documentation under docs/:

  1. Use shorthand source tags [web:NNN] (three-digit zero-padded sequential IDs) inline in ADRs and markdown docs to reference external web sources.
  2. Maintain a central mapping file at docs/web-source-mapping.md. Each ### web:NNN — Label entry maps a tag to:
    • a human-readable label
    • one or more concrete URLs (first URL is canonical for AI fetch; additional URLs are alternates or supplements)
  3. No new [web:NNN] tag is allowed without a corresponding mapping entry in the same commit.
  4. When introducing a new tag, authors (human or AI) must identify a canonical URL, allocate the next free sequential ID, and add the entry under an appropriate editorial section in the mapping file.
  5. Prefer [web:NNN] over inlined raw URLs when a mapping entry exists.
  6. Soft adoption for existing material: Accepted ADRs and older docs may keep inline URLs. New and materially updated docs must use [web:NNN] for new external references. Bulk retroactive conversion is out of scope.
  7. Enforcement: CI fails on unmapped tags and on orphan mapping entries (defined in mapping but unused in scoped docs). This prevents reference debt from accumulating silently.
  8. Machine-usable process rules live in rules/15-web-source-tags.md.

Scope​

In scopeOut of scope (initial)
docs/adr/*.mdrules/, prompts/, templates/ companion trees
docs/**/*.md (workflow, architecture, guides)CHANGELOG.md, root README.md
External http(s) referencesInternal relative doc links (../architecture/…)

Metadata files excluded from tag scanning: portal-integration.md, navigation-meta.md.

Consequences​

Positive​

  • ADRs and design docs stay readable with short, stable tags.
  • External sources are auditable in one versioned registry alongside the architecture log.
  • AI agents can resolve tags from the mapping file to fetch, cache, or refresh knowledge.
  • URL maintenance on Accepted ADRs can update the mapping without changing ADR decision text.

Negative​

  • Introducing a new external source requires a mapping update (extra step).
  • Authors must keep mapping entries and inline tags in sync; CI enforces this.
  • Sequential IDs carry no semantic prefix; the mapping label provides meaning.

Follow-up​

  • scripts/check_web_source_tags.py — lint unmapped tags and orphan mapping entries; wired into workflow-docs:contract.
  • Web source recovery (optional, human-confirmed) — when lint fails or the mapping file is incomplete:
    • scan scoped docs for [web:NNN] tags;
    • identify tags missing from the mapping file;
    • for each unmapped tag, inspect nearby text to infer the topic;
    • perform a focused web search to propose a canonical URL;
    • add proposed entries to docs/web-source-mapping.md for human review and confirmation before commit.
    • Process prompt: prompts/maintenance/web-source-recovery.md.
  • Recovery does not bulk-convert legacy inline URLs in Accepted ADRs (soft adoption unchanged). It repairs tag↔mapping consistency only.
  • Optional check-web-sources hook in a2c-pre-commit-hooks (v0.3.0+) for consumer repos with docs/web-source-mapping.md.
  • Optional CLI command (e.g. a2c web-sources recover --dry-run) — not required for ADR acceptance.
  • Optional extensions: [paper:*], [book:*] with separate mapping files (not part of this ADR).

References​

Supersedes​

  • (none)

Superseded by​

  • (none)