From 257c29813c62ca63af82dddcdef07016f7cfd5ac Mon Sep 17 00:00:00 2001 From: Smarter Harder <33955773+NWarila@users.noreply.github.com> Date: Wed, 3 Jun 2026 15:23:22 -0400 Subject: [PATCH] docs: bring template ADRs to living-schema conformance Reformat docs/decision-records/template ADRs to the full living-ADR schema and close the PT-M1 docs-layout gap. - Reformat ADR-0001 and ADR-0002 to the 13-field living metadata table with Compliance Notes and Changelog sections; decision content preserved. - Resolve dangling references: ADR-0002 -> org ADR-0004 (Renovate, tier-qualified cross-tier link); ADR-0001 -> new template ADR-0003. - Add ADR-0003 (Python minimum version floor, 3.11) and ADR-0004 (Python package layout and app anatomy). - Relocate the docs index out of docs/ root (disallowed by the docs-layout standard) to docs/explanation/documentation-map.md; remove docs/README.md. check_adr_schema, check_docs_layout, check_ai_residue, and scripts/qa.py all pass. --- docs/README.md | 23 --- ...-scripts-are-standalone-and-stdlib-only.md | 47 ++++-- ...ull-based-manifest-driven-template-sync.md | 43 +++-- .../0003-python-minimum-version-floor.md | 130 ++++++++++++++++ ...4-python-package-layout-and-app-anatomy.md | 147 ++++++++++++++++++ docs/explanation/documentation-map.md | 22 +++ 6 files changed, 359 insertions(+), 53 deletions(-) delete mode 100644 docs/README.md create mode 100644 docs/decision-records/template/0003-python-minimum-version-floor.md create mode 100644 docs/decision-records/template/0004-python-package-layout-and-app-anatomy.md create mode 100644 docs/explanation/documentation-map.md diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index f1acf8e..0000000 --- a/docs/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# Documentation - -Documentation for this template follows the [Diataxis framework](https://diataxis.fr/). - -| Area | Path | Purpose | -| --- | --- | --- | -| Tutorials | `tutorials/` | Learning-oriented, start-to-finish walkthroughs | -| How-to | `how-to/` | Task-oriented guides for a specific goal | -| Reference | `reference/` | Lookup-oriented facts about the QA and sync contract | -| Explanation | `explanation/` | Background and rationale behind the architecture | -| Runbooks | `runbooks/` | Operator procedures for template maintenance | -| Decisions | `decision-records/` | Architecture Decision Records | -| Diagrams | `diagrams/` | Mermaid (`.mmd`) source for architecture diagrams | - -## Start here - -- New to the template? Read [tutorials/getting-started.md](tutorials/getting-started.md). -- Adding or changing a quality gate? Use [how-to/add-a-qa-check.md](how-to/add-a-qa-check.md). -- Need the exact script and CI contract? See [reference/qa-contract.md](reference/qa-contract.md). -- Want the architecture rationale? Read - [explanation/why-two-layer-pull-sync.md](explanation/why-two-layer-pull-sync.md). -- Want the flow diagram? See [diagrams/qa-template-sync-flow.mmd](diagrams/qa-template-sync-flow.mmd). -- Looking for decisions? Start with [decision-records/README.md](decision-records/README.md). diff --git a/docs/decision-records/template/0001-scripts-are-standalone-and-stdlib-only.md b/docs/decision-records/template/0001-scripts-are-standalone-and-stdlib-only.md index 9d61bc2..7a2a3be 100644 --- a/docs/decision-records/template/0001-scripts-are-standalone-and-stdlib-only.md +++ b/docs/decision-records/template/0001-scripts-are-standalone-and-stdlib-only.md @@ -1,15 +1,20 @@ # ADR-0001: QA Scripts Are Standalone and Stdlib-Only -| Field | Value | -| -------------- | --------------------------------------- | -| Status | Accepted | -| Date | 2026-04-08 | -| Authors | Nick Warila (@NWarila) | -| Decision-maker | Nick Warila (sole portfolio maintainer) | -| Consulted | Python packaging and tooling docs. | -| Informed | Downstream Python repositories. | -| Reversibility | Medium | -| Review-by | N/A (Accepted) | +| Field | Value | +| ---------------- | ---------------------------------------------------------------------------- | +| ID | ADR-0001 | +| Scope | Template | +| Status | Accepted | +| Decision-subject | QA scripts are standalone, stdlib-only, and independently syncable. | +| Date accepted | 2026-04-08 | +| Date | 2026-06-03 | +| Last reviewed | 2026-06-03 | +| Authors | Nick Warila (@NWarila) | +| Decision-makers | Nick Warila (sole portfolio maintainer) | +| Consulted | Python packaging and tooling docs. | +| Informed | Downstream Python repositories. | +| Reversibility | Medium | +| Review-by | 2026-11-30 | ## TL;DR @@ -33,7 +38,7 @@ Two design paths were considered: ## Considered Options -1. Standalone, stdlib-only scripts — no shared module, no third-party deps. +1. Standalone, stdlib-only scripts - no shared module, no third-party deps. 2. Shared helper module (`_common.py`) imported by each check script. 3. Template Python package installed as a dev dependency. @@ -41,7 +46,7 @@ Two design paths were considered: Chosen option: **Option 1, standalone stdlib-only scripts.** -Each `check_*.py` file reads `pyproject.toml` via `tomllib` (stdlib since 3.11), resolves paths, invokes the tool via `subprocess`, and reports results — all inline. The `~10-line config-reading pattern is duplicated across scripts rather than shared. +Each `check_*.py` file reads `pyproject.toml` via `tomllib` (stdlib since 3.11), resolves paths, invokes the tool via `subprocess`, and reports results - all inline. The `~10-line` config-reading pattern is duplicated across scripts rather than shared. Scripts shell out to the actual tools (`ruff`, `mypy`, `pytest`, `pip-audit`, `codespell`, `build`, `twine`) and do not import them. This means the scripts carry zero non-stdlib import dependencies of their own. @@ -69,7 +74,7 @@ Scripts shell out to the actual tools (`ruff`, `mypy`, `pytest`, `pip-audit`, `c ## Confirmation 1. No `check_*.py` or `qa.py` file contains a cross-script import. -2. The only stdlib module used for config reading is `tomllib` (Python 3.11+), consistent with the org's minimum supported version (ADR-0003). +2. The only stdlib module used for config reading is `tomllib` (Python 3.11+), consistent with this template's minimum supported Python version ([ADR-0003](0003-python-minimum-version-floor.md)). 3. `mypy` and `ruff` pass on all scripts in CI (`template-ci.yml`). ## Consequences @@ -89,7 +94,7 @@ Scripts shell out to the actual tools (`ruff`, `mypy`, `pytest`, `pip-audit`, `c ## Assumptions -1. Python 3.11 remains the minimum version for the org (see PLAN.md Resolved Decision 15). +1. Python 3.11 remains the minimum version for this template (see PLAN.md Resolved Decision 15). 2. The set of check scripts stays small enough that per-file duplication is manageable. ## Supersedes @@ -107,5 +112,15 @@ None (current). ## Related ADRs -- ADR-0002: Pull-based manifest-driven template sync -- ADR-0003: Python minimum version floor +- [ADR-0002](0002-pull-based-manifest-driven-template-sync.md): Pull-based manifest-driven template sync. +- [ADR-0003](0003-python-minimum-version-floor.md): Python minimum version floor. + +## Compliance Notes + +None. + +## Changelog + +| Date | Change | Reason | Author/Role | Body-diff? | +| ---------- | --------------------------------------- | -------------------------------------------------- | ----------------------------------- | ---------- | +| 2026-06-03 | Reformatted to the living ADR schema. | Satisfy the template ADR conformance gate. | Portfolio maintainer / template ADR | Yes | diff --git a/docs/decision-records/template/0002-pull-based-manifest-driven-template-sync.md b/docs/decision-records/template/0002-pull-based-manifest-driven-template-sync.md index faefe59..a965c8a 100644 --- a/docs/decision-records/template/0002-pull-based-manifest-driven-template-sync.md +++ b/docs/decision-records/template/0002-pull-based-manifest-driven-template-sync.md @@ -1,15 +1,20 @@ # ADR-0002: Pull-Based, Manifest-Driven Template Sync -| Field | Value | -| -------------- | --------------------------------------- | -| Status | Accepted | -| Date | 2026-04-08 | -| Authors | Nick Warila (@NWarila) | -| Decision-maker | Nick Warila (sole portfolio maintainer) | -| Consulted | GitHub Actions reusable workflow docs, git submodule docs. | -| Informed | Downstream Python repositories. | -| Reversibility | Medium | -| Review-by | N/A (Accepted) | +| Field | Value | +| ---------------- | ---------------------------------------------------------------------------- | +| ID | ADR-0002 | +| Scope | Template | +| Status | Accepted | +| Decision-subject | Template updates are synced by downstream-owned pull requests and manifests. | +| Date accepted | 2026-04-08 | +| Date | 2026-06-03 | +| Last reviewed | 2026-06-03 | +| Authors | Nick Warila (@NWarila) | +| Decision-makers | Nick Warila (sole portfolio maintainer) | +| Consulted | GitHub Actions reusable workflow docs, git submodule docs. | +| Informed | Downstream Python repositories. | +| Reversibility | Medium | +| Review-by | 2026-11-30 | ## TL;DR @@ -59,7 +64,7 @@ The template publishes a GitHub release whenever `scripts/` changes (via `auto-r - Good, because it uses native git tooling. - Bad, because submodules pin to a commit, not a release; there is no selective file mapping. -- Bad, because downstream repos get no PR with migration notes — the submodule bump is one diff line. +- Bad, because downstream repos get no PR with migration notes - the submodule bump is one diff line. - Bad, because submodule workflows are brittle across clone contexts. ### Option 3: Versioned Python package @@ -81,7 +86,7 @@ The template publishes a GitHub release whenever `scripts/` changes (via `auto-r 1. `sync-manifest.json` at the repository root defines all synced source-to-destination mappings. 2. `self-update.yml` supports `workflow_call` so downstream repos can call it as a reusable workflow. -3. The reusable workflow uses `GITHUB_TOKEN` (downstream repo's own token) for PR creation — no PAT. +3. The reusable workflow uses `GITHUB_TOKEN` (downstream repo's own token) for PR creation - no PAT. 4. `auto-release.yml` creates a new release when `scripts/` changes merge to `main`. 5. This repo dogfoods the sync mechanism via a nightly scheduled run of `self-update.yml`. @@ -121,5 +126,15 @@ None (current). ## Related ADRs -- ADR-0001: QA scripts are standalone and stdlib-only -- ADR-0004: Use Renovate for dependency updates (`.github/renovate.json5`) +- [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md): QA scripts are standalone and stdlib-only. +- [org ADR-0004 (Use Renovate for dependency updates)](../org/0004-use-renovate-for-dependency-updates.md): `.github/renovate.json5`. + +## Compliance Notes + +None. + +## Changelog + +| Date | Change | Reason | Author/Role | Body-diff? | +| ---------- | --------------------------------------- | -------------------------------------------------- | ----------------------------------- | ---------- | +| 2026-06-03 | Reformatted to the living ADR schema. | Satisfy the template ADR conformance gate. | Portfolio maintainer / template ADR | Yes | diff --git a/docs/decision-records/template/0003-python-minimum-version-floor.md b/docs/decision-records/template/0003-python-minimum-version-floor.md new file mode 100644 index 0000000..be34382 --- /dev/null +++ b/docs/decision-records/template/0003-python-minimum-version-floor.md @@ -0,0 +1,130 @@ +# ADR-0003: Python Minimum Version Floor + +| Field | Value | +| ---------------- | ---------------------------------------------------------------------------- | +| ID | ADR-0003 | +| Scope | Template | +| Status | Accepted | +| Decision-subject | The template requires Python 3.11 or newer. | +| Date accepted | 2026-06-03 | +| Date | 2026-06-03 | +| Last reviewed | 2026-06-03 | +| Authors | Nick Warila (@NWarila) | +| Decision-makers | Nick Warila (sole portfolio maintainer) | +| Consulted | Python packaging docs, CPython `tomllib` docs, Ruff configuration docs. | +| Informed | Downstream Python repositories. | +| Reversibility | Medium | +| Review-by | 2026-11-30 | + +## TL;DR + +This template requires Python 3.11 or newer. The floor is already encoded in `pyproject.toml` as `requires-python = ">=3.11"` and in Ruff as `target-version = "py311"`. It also makes the stdlib-only QA scripts in [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md) possible because they can use `tomllib` without a backport dependency. + +## Context and Problem Statement + +The template provides reusable quality-gate scripts, workflow files, and reference configuration for downstream Python repositories. Those scripts are intentionally standalone and stdlib-only per [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md), so they need a Python runtime whose standard library contains the parsing functionality they depend on. + +`tomllib` entered the Python standard library in Python 3.11. The QA scripts read `pyproject.toml`, so supporting Python versions earlier than 3.11 would either require a non-stdlib TOML dependency, duplicate parser logic, or conditional compatibility code. Each option conflicts with the standalone script decision. + +The repository already declares the same floor in `pyproject.toml`: `[project] requires-python = ">=3.11"`, `[tool.ruff] target-version = "py311"`, and `[tool.mypy] python_version = "3.11"`. The ADR records that those settings are intentional template policy, not accidental tool defaults. + +## Decision Drivers + +1. Keep the QA scripts stdlib-only and individually copyable. +2. Avoid compatibility shims or backport dependencies in template infrastructure. +3. Align package metadata, lint configuration, and type-checking configuration around one Python baseline. +4. Permit modern typing and standard-library APIs in future template code. +5. Keep downstream expectations explicit before they adopt or sync the template. + +## Considered Options + +1. Support Python 3.10 and newer with a TOML backport or compatibility path. +2. Require Python 3.11 and newer. +3. Require only the newest actively developed Python minor version. + +## Decision Outcome + +Chosen option: **Option 2, require Python 3.11 and newer.** + +The template's Python floor is 3.11. `pyproject.toml` remains the machine-readable source for packaging and tool configuration, while this ADR records the rationale. The QA scripts may use `tomllib` directly and do not need a backport dependency or runtime fallback for older Python versions. + +Future changes to the Python floor must update this ADR, `pyproject.toml`, and any affected QA-script assumptions together. + +## Pros and Cons of the Options + +### Option 1: Support Python 3.10 and newer + +- Good, because it would let older downstream environments adopt the template without upgrading Python first. +- Bad, because `tomllib` is not available in the Python 3.10 standard library. +- Bad, because adding a TOML backport would violate the stdlib-only QA-script decision. +- Bad, because conditional compatibility code would make each standalone script harder to read and maintain. + +### Option 2: Require Python 3.11 and newer + +- Good, because it matches the existing `pyproject.toml` package metadata and Ruff target version. +- Good, because it allows direct `tomllib` use with no helper package. +- Good, because it supports modern typing and standard-library features without compatibility shims. +- Neutral, because downstream repositories must provide Python 3.11 or newer before adopting the template. +- Bad, because repositories pinned to older Python runtimes must upgrade or defer adoption. + +### Option 3: Require only the newest actively developed Python minor version + +- Good, because it would maximize access to current language and tooling features. +- Bad, because it would create unnecessary churn for downstream repositories. +- Bad, because the template does not currently need features beyond Python 3.11 to meet its QA-script contract. + +## Confirmation + +1. `pyproject.toml` declares `[project] requires-python = ">=3.11"`. +2. `pyproject.toml` declares `[tool.ruff] target-version = "py311"`. +3. `pyproject.toml` declares `[tool.mypy] python_version = "3.11"`. +4. QA scripts may import `tomllib` directly and must not add a TOML backport dependency for template-owned config reading. + +## Consequences + +### Positive + +- The template has one clear Python baseline across packaging, linting, typing, and scripts. +- The stdlib-only script policy stays simple because `tomllib` is available. +- Future template code can use Python 3.11 typing and standard-library behavior without compatibility layers. + +### Negative + +- Downstream repositories on Python 3.10 or older cannot adopt the template unchanged. +- Lowering the floor later would require revisiting script imports, tool targets, and type syntax. + +### Neutral + +- The Python floor is a template-tier decision. Individual downstream repositories may choose a stricter floor, but they should not claim compatibility below the template floor while syncing these scripts unchanged. + +## Assumptions + +1. Downstream repositories that adopt this template can run CI and local QA with Python 3.11 or newer. +2. The template continues to value stdlib-only QA scripts over older runtime compatibility. +3. The template does not need to support Python interpreters outside the CPython-compatible packaging and tooling ecosystem. + +## Supersedes + +None. + +## Superseded by + +None (current). + +## Implementing PRs + +None yet. The policy is already reflected in `pyproject.toml`; future PRs that change the floor should be listed here. + +## Related ADRs + +- [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md): QA scripts are standalone and stdlib-only. + +## Compliance Notes + +None. + +## Changelog + +| Date | Change | Reason | Author/Role | Body-diff? | +| ---------- | ------------------------------------------- | -------------------------------------------------------- | ----------------------------------- | ---------- | +| 2026-06-03 | Accepted the template Python version floor. | Document the Python 3.11 policy already encoded in tools. | Portfolio maintainer / template ADR | Yes | diff --git a/docs/decision-records/template/0004-python-package-layout-and-app-anatomy.md b/docs/decision-records/template/0004-python-package-layout-and-app-anatomy.md new file mode 100644 index 0000000..d127f83 --- /dev/null +++ b/docs/decision-records/template/0004-python-package-layout-and-app-anatomy.md @@ -0,0 +1,147 @@ +# ADR-0004: Python Package Layout and App Anatomy + +| Field | Value | +| ---------------- | ---------------------------------------------------------------------------- | +| ID | ADR-0004 | +| Scope | Template | +| Status | Accepted | +| Decision-subject | The template ships a generic `src/` package anatomy. | +| Date accepted | 2026-06-03 | +| Date | 2026-06-03 | +| Last reviewed | 2026-06-03 | +| Authors | Nick Warila (@NWarila) | +| Decision-makers | Nick Warila (sole portfolio maintainer) | +| Consulted | Python packaging docs, PyPA typing marker docs, Pydantic docs. | +| Informed | Downstream Python repositories. | +| Reversibility | Medium | +| Review-by | 2026-11-30 | + +## TL;DR + +The template will ship a generic package skeleton under `src/` rather than only QA scripts. The package contains `__init__.py`, `__main__.py`, `py.typed`, `config.py`, `exceptions.py`, `_contracts.py`, `validators.py`, and `main.py`. This layout gives downstream repositories a typed, testable, app-shaped starting point without choosing a product domain or framework for them. + +## Context and Problem Statement + +The template already standardizes quality gates and sync behavior. Downstream Python repositories also benefit from a small, consistent package anatomy that demonstrates how application code should be organized once a project moves beyond scripts and configuration. + +The skeleton needs to be useful as a starting point, but it must stay generic. Template-tier code should establish packaging, typing, validation, configuration, exception, contract, and CLI boundaries. It should not encode consumer-side product architecture, deployment assumptions, service frameworks, persistence models, or domain workflows. + +The package should also be compatible with the template's Python 3.11 floor in [ADR-0003](0003-python-minimum-version-floor.md), so it can use modern standard-library and typing features while remaining approachable. + +## Decision Drivers + +1. Give new repositories a real package shape instead of leaving every consumer to invent its own first module layout. +2. Keep the skeleton generic enough for libraries, CLIs, and small applications. +3. Make the public API explicit and typed from the start. +4. Separate configuration, contracts, validation, exceptions, and CLI wiring into predictable files. +5. Keep domain-specific framework choices outside the template. +6. Align the skeleton with the Python 3.11 floor and modern typing expectations. + +## Considered Options + +1. Keep the template script-only and provide no package skeleton. +2. Ship a minimal generic `src/` package anatomy. +3. Ship a richer application framework skeleton with domain-specific layers. + +## Decision Outcome + +Chosen option: **Option 2, ship a minimal generic `src/` package anatomy.** + +The template package anatomy is: + +- `src//__init__.py` defines the curated public API and `__all__`. +- `src//__main__.py` provides a self-demo entry point for `python -m `. +- `src//py.typed` marks the package as typed and is shipped as package data. +- `src//config.py` owns the frozen `pydantic-settings` configuration API: `BaseSettings`, env-prefix handling, and `load()` / `save_defaults()`. +- `src//exceptions.py` defines typed exceptions with What, Why, and Fix fields. +- `src//_contracts.py` defines frozen Pydantic models, Result shapes, and `StrEnum`-based codes. +- `src//validators.py` contains pure validation functions called from `model_validator` methods. +- `src//main.py` owns the CLI entry point. + +The package skeleton is intentionally small. Consumer repositories may add domain packages, integrations, persistence, orchestration, or service layers in their own ADRs, but those choices are not template-tier decisions. + +## Pros and Cons of the Options + +### Option 1: Keep the template script-only + +- Good, because it avoids adding any application-code opinion to the template. +- Good, because downstream repositories have maximum freedom. +- Bad, because every new Python repository must invent its first package layout independently. +- Bad, because typing markers, public API boundaries, configuration, and validation patterns can drift immediately. + +### Option 2: Ship a minimal generic package anatomy + +- Good, because it gives consumers a concrete, typed starting point. +- Good, because the file boundaries are conventional and easy to replace. +- Good, because the skeleton demonstrates package data, CLI entry points, contracts, validation, and exceptions without choosing a domain. +- Good, because public API exports are curated from the beginning through `__init__.py` and `__all__`. +- Neutral, because consumers may delete or rename the sample package when they specialize the template. +- Bad, because the template now carries a small amount of application-code surface area to maintain. + +### Option 3: Ship a richer application framework skeleton + +- Good, because a specific framework skeleton could be immediately runnable for one style of application. +- Bad, because it would force consumer repositories toward a product architecture they may not need. +- Bad, because framework-specific choices belong in consumer repositories or more specialized templates, not in this generic Python template. +- Bad, because richer scaffolding would increase maintenance and sync churn. + +## Confirmation + +1. The package skeleton lives under `src/`. +2. `__init__.py` exposes only the curated public API and defines `__all__`. +3. `__main__.py` runs a self-demo through `python -m `. +4. `py.typed` is included as package data so type information is visible to downstream type checkers. +5. `config.py` exposes the frozen `pydantic-settings` configuration API: `BaseSettings`, env-prefix handling, and `load()` / `save_defaults()`. +6. `exceptions.py` exposes typed What, Why, and Fix exception details. +7. `_contracts.py` owns frozen Pydantic models, Result shapes, and `StrEnum`-based codes. +8. `validators.py` contains pure validation functions that are called from `model_validator` methods. +9. `main.py` owns the CLI entry point. + +## Consequences + +### Positive + +- New Python repositories start with a typed package layout instead of a blank source tree. +- Public API, runtime entry points, package typing, settings, contracts, validation, exceptions, and CLI wiring have predictable homes. +- The skeleton remains generic enough for downstream repositories to specialize without undoing framework-specific assumptions. + +### Negative + +- The template must maintain sample package files in addition to QA scripts and workflow assets. +- Consumers that want a different layout must consciously replace the skeleton rather than starting from an empty package. + +### Neutral + +- The skeleton is a template starting point, not an organization-wide application architecture. Consumer repositories can add local ADRs when they choose domain-specific layers or frameworks. + +## Assumptions + +1. Downstream repositories benefit from an example package shape that is more concrete than documentation alone. +2. The template continues to target Python 3.11 or newer. +3. Consumer repositories remain responsible for domain-specific architecture beyond this generic package anatomy. + +## Supersedes + +None. + +## Superseded by + +None (current). + +## Implementing PRs + +None yet. The follow-on package skeleton implementation should be listed here when it lands. + +## Related ADRs + +- [ADR-0003](0003-python-minimum-version-floor.md): Python minimum version floor. + +## Compliance Notes + +None. + +## Changelog + +| Date | Change | Reason | Author/Role | Body-diff? | +| ---------- | ------------------------------------------ | ------------------------------------------------- | ----------------------------------- | ---------- | +| 2026-06-03 | Accepted the template package layout ADR. | Document the package anatomy before implementation. | Portfolio maintainer / template ADR | Yes | diff --git a/docs/explanation/documentation-map.md b/docs/explanation/documentation-map.md new file mode 100644 index 0000000..5d44155 --- /dev/null +++ b/docs/explanation/documentation-map.md @@ -0,0 +1,22 @@ +# Documentation Map + +Documentation for this template follows the [Diataxis framework](https://diataxis.fr/). + +| Area | Path | Purpose | +| --- | --- | --- | +| Tutorials | [`tutorials/`](../tutorials/) | Learning-oriented, start-to-finish walkthroughs | +| How-to | [`how-to/`](../how-to/) | Task-oriented guides for a specific goal | +| Reference | [`reference/`](../reference/) | Lookup-oriented facts about the QA and sync contract | +| Explanation | [`explanation/`](./) | Background and rationale behind the architecture | +| Runbooks | [`runbooks/`](../runbooks/) | Operator procedures for template maintenance | +| Decisions | [`decision-records/`](../decision-records/) | Architecture Decision Records | +| Diagrams | [`diagrams/`](../diagrams/) | Mermaid (`.mmd`) source for architecture diagrams | + +## Start here + +- New to the template? Read [tutorials/getting-started.md](../tutorials/getting-started.md). +- Adding or changing a quality gate? Use [how-to/add-a-qa-check.md](../how-to/add-a-qa-check.md). +- Need the exact script and CI contract? See [reference/qa-contract.md](../reference/qa-contract.md). +- Want the architecture rationale? Read [explanation/why-two-layer-pull-sync.md](why-two-layer-pull-sync.md). +- Want the flow diagram? See [diagrams/qa-template-sync-flow.mmd](../diagrams/qa-template-sync-flow.mmd). +- Looking for decisions? Start with [decision-records/README.md](../decision-records/README.md).