Appendix H: Architecture-as-Code Reference

Overview

Architecture documentation can connect approved intent, implementation, tests and operational evidence through versioned references. Generating a page or creating it before the code helps coordination; it does not make drift impossible.

This appendix distinguishes a proposed metadata/index pattern from the helpers actually shipped in the kit. Docusaurus is the rendering layer. In the future business-intent workspace, authoritative artifacts and approvals remain in the permissioned record system; rendered pages are audience-specific views.

Frontmatter Schema

The following is an illustrative adoption profile, not a schema validator or plugin supplied by this kit:

---
title: Eligibility boundary
description: Approved intent and observed implementation for one boundary
components:
  - src/eligibility/service.ts
tests:
  - tests/eligibility.contract.test.ts
depends_on:
  - architecture/identity
consumers:
  - src/application/router.ts
accountable_roles:
  - domain-owner
  - technical-owner
status: in-progress
last_verified: "2026-01-01"
verification_scope: "Illustrative source inspection only"
intent_ref: "RULE-EXAMPLE/revision-2"
implementation_ref: "illustrative-repository-revision"
---

Paths, dates and references above are synthetic. Define and validate the adopted metadata profile before using it as a machine contract; do not mistake these strings for genuine evidence or grants.

Field Definitions

Field	Proposed meaning	Limit
components	Existing source paths relative to the declared repository root	Existence is not correct behavior or deployed state
tests	Relevant tests	A mapping is not execution evidence
depends_on	Documentation/architecture relationships	Links do not verify semantics
consumers	Consuming code paths	Not human accountability
accountable_roles	Roles responsible for meaning and engineering review	Actual identities/grants need the project's authority system
status	Implemented, in-progress or planned claim	Not certification or approval
last_verified / scope	When and what was reviewed	Not a blanket freshness assertion
Intent/implementation references	Exact artifacts/revisions being described	Resolved separately from runtime evidence

Earlier examples used owners for consuming files. If an adopter already uses that field, preserve its meaning during migration; do not silently reinterpret file paths as accountable people.

Status Values

Status	How to read it
implemented	Inspect the stated implementation evidence; deployment and acceptance remain separate
in-progress	Identify completed, incomplete and unassessed parts
planned	A proposal/design, with no implied code or approval

Rules

Organize architecture pages around meaningful boundaries. Business journeys, tutorials, operational procedures and API references can have different structures. Apply traceability to frontend, backend, configuration and workflows—not only Python files.

Keep existing paths in components. Describe proposed files explicitly as proposed paths in design prose or an adopted separate field. A planned page can reference existing components it proposes to change without implying those changes exist.

Architecture Index

An optional generated index can map source paths to pages and verification references. It is a derived navigation aid, not a replacement for approved intent.

Implementation

The kit does not supply a general architecture-index build plugin. If an adopter needs one, its acceptance requirements include:

1. Declare the repository/source roots, admitted pages, metadata schema and revision.
2. Validate supported frontmatter rather than silently dropping unsupported forms.
3. Resolve component/test/doc references and report unassessed inputs.
4. Measure mapped coverage against an explicit denominator, including relevant non-backend sources.
5. Keep generated content deterministic for fixed inputs; put observation time in a separate receipt if freshness comparison uses exact bytes.
6. Stage owned output safely and test failures, removals and concurrent changes.
7. Apply the audience policy to the index as well as its pages.

Prefer an explicit generation step with a defined output contract. A build plugin that writes back into its own input tree needs careful ordering and loop/ownership checks.

CLAUDE.md / AGENTS.md Integration

An adopter can add a concise pointer to the installed procedure:

Before changing a mapped boundary, read its authoritative intent and current
documentation references. Use the adopted index if present and current.
After changing it, review affected claims against the appropriate evidence.
Record a discrepancy instead of silently changing approved intent.

Verify which instruction file the host actually loads. Do not copy large duplicated procedures into every context file. A missing index is an explicit coverage gap, not permission to assume no documentation is affected.

ADR Publishing (canonical → site)

Keep the accepted ADR register authoritative. A site mirror renders selected decisions without making a second editable master. Publication selection must respect confidentiality; a generator's ability to read the register is not permission to expose it.

Implementation

The supplied templates/scripts/generate-adr-mirror.sh takes an output directory and the ADR_SRC source directory (default ./docs/adr). It supports the documented numbered ADR filenames, emits Docusaurus metadata and preserves canonical bodies. Use a controlled source set authorized for the destination audience.

The helper records generated-file ownership, preserves authored files, rejects collisions/unsafe overlap and stages promotion with recovery for handled interruptions. These are process-level safeguards, not proof of hostile-filesystem safety, power-loss durability or publication authority.

The companion templates/scripts/check-generated-fresh.sh can compare regenerated output with the selected destination. A match establishes reproducibility within that declared scope, not the truth of an ADR or its approval.

Sidebar

An autogenerated ADR sidebar can expose generated pages without manual per-page edits. Test the production navigation and audience: “autogenerated” does not mean every source is appropriate to publish. Source admission, visibility metadata and actual rendered routes are separate checks.

Single source of truth vs. legacy curation

Review divergent hand-curated pages before adopting a generated mirror. Preserve authored material and determine its authority. Do not fold edits silently into an accepted ADR body: use an authorized erratum, superseding decision or clearly separated explanatory commentary. Link explanations to the exact canonical revision.

The generator may own only the explicitly adopted output; filename resemblance alone must not authorize overwriting someone else's page. See ADR lifecycle and corrections.

Sync Surfacing

The installed helper's actual behavior matters more than a diagram of intended enforcement.

Staleness Check (Advisory)

templates/hooks/check-doc-staleness.sh <docs-dir> [window-days] scans Markdown and MDX and reports supported verification dates against a UTC-day window (default 30). It handles supported generated STATE headers, marks invalid/duplicate dates and unavailable input unassessed, and reports untracked pages separately. It never updates files.

Its exit code remains zero because it is advisory. Plain Stop-hook output may be debug-only; verify the adopted warning delivery path. It does not inspect a component map or determine whether documentation is factually wrong.

Coverage Check (Warning)

Component-to-page coverage is a proposed architecture-index feature, not functionality of the age hook. The kit's sidebar coverage check answers a different question: whether supported documentation IDs appear in the supported sidebar configuration. Neither is semantic coverage.

The --docs-verified Flag

No such flag is shipped by the reference age hook. Re-verification requires reviewing named claims, recording outcomes and updating the appropriate scope/date through the authorized editing process. Do not automate date bumps as a substitute for that work.

Documentation-First Development

Drafting a planned page during design gives business and engineering something tangible to review. It does not approve the design or predict implementation truth.

A small bugfix, parameter change or feature flag can change documented business behavior. Review effects, not labels. If no documentation change is needed, record the scoped rationale without a cosmetic edit.

Test Mapping

A tests list suggests what to inspect/run; it is not a receipt. The shipped Stop verification hook prints a reminder, not a mapped-test executor. A future executor must prove selected and actually executed tests, candidate/environment identity, outcomes and omissions.

Unit checks, contract tests, production observations and business acceptance answer different questions. One cannot automatically stand in for another.

Rollout Guide

Start with one high-value boundary, one business validation example and one actual evidence-producing check. Decide ownership, metadata profile, storage and audience before extending coverage.

Demonstrate a normal update and an adverse case: stale approval, removed component, inaccessible source, failed build or incorrect business interpretation. Expand based on observed usefulness and maintenance cost, not a universal “80% documented” threshold or fixed day count.

Evidence

Report what was measured: source revision, selected pages/files, mapping coverage denominator, checks executed, outcomes and unassessed scope. A historical adopter example is not a current production-readiness certificate for the kit or another project.

Canonical site template

Local methodology publisher

This repository's website/scripts/build-docs.sh invokes scripts/render-docs.py. It admits the sources named in website/publication.json, checks classification, preserves unowned authored pages and replaces only explicitly owned generated output. The ownership receipt identifies files; it is not approval of their meaning or audience.

Cooperating builds use a sibling .<output-directory>.s4u-publication.lock. A second publisher is refused while the first owns that destination. The compiler fingerprints admitted sources, its admission configuration, the shipped classification implementation and the existing output before generation, then rechecks them before promotion. An observed input change or intervening contribution blocks replacement so it can be reviewed and rebuilt. If promotion and rollback cannot complete, the previous output and lock remain for reviewed recovery; a retry cannot silently replace the missing target. Do not remove a live or unexplained lock to force a build through; check for a running publisher and the reported recovery location first.

These checks protect the local controlled-build workflow. They are not an atomic transaction with arbitrary editors, a hostile-filesystem sandbox or an access-revocation service. A production publication pipeline needs immutable reviewed inputs, an authorized promotion step and withdrawal of content whose access is revoked—including copies in caches and search indexes. Keeping an old build available after failure is not always privacy-safe.

Adopter overlay

templates/docusaurus-site/ is a starting configuration for an adopter, not a complete application package or accessibility guarantee. Use a reviewed Docusaurus scaffold and compatible locked dependencies, then overlay only the chosen template files.

The reference includes Mermaid configuration, a semantic color palette, sidebar options, a TOC component and broken-link settings. Inspect which routes/anchors those settings validate. A successful build does not prove that client-side diagrams rendered correctly.

Verify actual text/background contrast, legibility, keyboard navigation and scrolling on the final diagrams in light/dark and small/large views. A palette's intended contrast is not a guarantee for every rendered node or connector label. The local methodology site and reusable template must each be checked after configuration changes.