[docs] Add architecture decision records (#74)

docs/internals/adr/0001-wiki-preview-branches.rst

@@ -0,0 +1,39 @@
+ADR 0001: Wiki Preview Branches
+===============================
+
+Status
+------
+
+Accepted.
+
+Context
+-------
+
+Fast Forward repositories generate wiki documentation from source code. The
+GitHub Wiki repository uses its own ``master`` branch, while the source
+repository protects ``main`` and expects all source changes to pass through pull
+requests.
+
+Publishing pull request wiki output directly to ``master`` would expose
+unmerged documentation. Committing generated submodule pointers directly to
+``main`` would also conflict with protected branch rules.
+
+Decision
+--------
+
+Pull request wiki output is published to a PR-scoped wiki branch named
+``pr-<number>``. The parent pull request branch receives the matching
+``.github/wiki`` submodule pointer update.
+
+After the pull request is merged into ``main``, the accepted preview content is
+promoted to the wiki ``master`` branch.
+
+Consequences
+------------
+
+- Reviewers can inspect generated wiki output before merge.
+- Protected ``main`` remains the only path to final wiki publication.
+- Bot commits are expected on pull request branches when generated wiki pointers
+  change.
+- Maintainers may need to resolve ``.github/wiki`` pointer conflicts when a pull
+  request is rebased after a newer preview is generated.

docs/internals/adr/0002-reports-pages-previews.rst

@@ -0,0 +1,35 @@
+ADR 0002: Reports Pages Previews
+================================
+
+Status
+------
+
+Accepted.
+
+Context
+-------
+
+Reports include generated documentation, coverage, and quality artifacts. Those
+outputs are useful during review, but the canonical GitHub Pages site should
+represent the accepted ``main`` branch.
+
+Multiple pull requests can be open at the same time, so previews must not
+overwrite each other or replace the published site.
+
+Decision
+--------
+
+Pull request reports are published under PR-specific Pages paths such as
+``previews/pr-<number>/``. Main branch reports are published to the root of the
+Pages site.
+
+Pull request comments may link to the preview, and workflow artifacts remain the
+fallback when Pages links or comments are unavailable.
+
+Consequences
+------------
+
+- Multiple pull requests can have independent report previews.
+- The root Pages site remains tied to ``main``.
+- Closed pull requests need preview cleanup to avoid stale artifacts.
+- Maintainers should treat preview links as review aids, not release output.

docs/internals/adr/0003-sync-preserves-consumer-customizations.rst

@@ -0,0 +1,36 @@
+ADR 0003: Sync Preserves Consumer Customizations
+================================================
+
+Status
+------
+
+Accepted.
+
+Context
+-------
+
+``dev-tools:sync`` distributes shared defaults into consumer repositories, but
+consumer projects may already have custom workflows, Dependabot rules,
+``.editorconfig`` settings, skills, or repository-specific ignore files.
+
+Overwriting consumer-owned files by default would make adoption risky and could
+silently remove project-specific behavior.
+
+Decision
+--------
+
+Sync creates missing shared assets and repairs known managed links, while
+preserving existing consumer-owned files and non-symlink directories by default.
+
+Generated updates that must be in place, such as Composer script entries, are
+applied in place instead of replacing the whole file.
+
+Consequences
+------------
+
+- Consumer repositories can adopt DevTools incrementally.
+- Maintainers must compare existing custom files with packaged defaults when
+  they want newer shared behavior.
+- Sync output may be conservative; a repository can intentionally diverge from
+  the packaged default.
+- Future overwrite features should remain explicit and reviewable.

docs/internals/adr/0004-resource-stubs-call-reusable-workflows.rst

@@ -0,0 +1,38 @@
+ADR 0004: Resource Stubs Call Reusable Workflows
+================================================
+
+Status
+------
+
+Accepted.
+
+Context
+-------
+
+Fast Forward maintains shared GitHub Actions behavior for many consumer
+repositories. Copying full workflow implementations into every repository would
+make updates slow, noisy, and inconsistent.
+
+Consumer repositories still need local workflow files so GitHub can expose
+standard Actions entry points and repository-specific triggers.
+
+Decision
+--------
+
+Consumer repositories receive small workflow stubs from
+``resources/github-actions``. Those stubs call reusable workflows implemented in
+the DevTools repository through ``workflow_call``.
+
+The reusable workflow owns the shared behavior, while the stub keeps the
+consumer repository integration point small and predictable.
+
+Consequences
+------------
+
+- Central workflow fixes can benefit consumers without large per-repository
+  edits.
+- Consumer stubs must remain compatible with the reusable workflow interface.
+- Changes to reusable workflow inputs or secrets are architectural changes for
+  downstream repositories.
+- Documentation and sync behavior should describe both the local stub and the
+  central workflow role.

docs/internals/adr/index.rst

@@ -0,0 +1,34 @@
+Architecture Decision Records
+=============================
+
+Architecture decision records capture durable context for choices that affect
+Fast Forward DevTools users and consumer repositories. ADRs explain why a
+decision exists, not every implementation detail.
+
+Format
+------
+
+Each ADR uses the same compact structure:
+
+- status: proposed, accepted, superseded, or deprecated;
+- context: the problem and constraints at the time of the decision;
+- decision: the chosen direction;
+- consequences: trade-offs, follow-up responsibilities, and known limits.
+
+Naming Convention
+-----------------
+
+Use a four-digit sequence and a short kebab-case topic:
+``0001-example-topic.rst``. New ADRs should be appended rather than inserted so
+existing references remain stable.
+
+Records
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   0001-wiki-preview-branches
+   0002-reports-pages-previews
+   0003-sync-preserves-consumer-customizations
+   0004-resource-stubs-call-reusable-workflows

docs/internals/architecture.rst

@@ -4,6 +4,9 @@ Architecture and Command Lifecycle
 The package has two connected execution models: local command execution and
 consumer repository synchronization.
 
+For durable context behind major workflow and synchronization choices, see
+:doc:`adr/index`.
+
 Local Command Lifecycle
 -----------------------
 

docs/internals/index.rst

@@ -9,4 +9,5 @@ step.
    :maxdepth: 1
 
    architecture
+   adr/index
    release-publishing