[EPIC] Add reusable GitHub-backed discussions for generated documentation

[dieterbaier]

As a documentation project maintainer, I want to enable GitHub-backed discussions for generated static documents, so that readers can give public, document-specific feedback without a custom backend.

Motivation

The profile website already supports GitHub-backed article comments without a backend service. It demonstrates that static documentation can offer public feedback while GitHub remains the discussion system of record.

Generalize that implementation in the architecture-knowledge-toolkit so every generated documentation project can opt into the same capability for arc42 chapters, ADRs, articles, and other generated pages.

Goals

• Provide a reusable standalone generator, tentatively named generator-github-discussions.
• Generate document-specific discussion links for supported document types.
• Keep generated websites fully static and load existing discussions only after explicit user interaction.
• Reuse the capability across toolkit generators without duplicating project-specific implementation.
• Keep the feature optional and disabled by default.

Functional requirements

• Support arc42 chapters, ADRs, articles, and additional generated pages through an extensible document-type mapping.
• Use stable semantic document identifiers that do not depend on page titles or generated URLs.
• Derive an allowlist containing only published, discussion-enabled document identifiers.
• Synchronize the reproducibly generated allowlist to a configurable GitHub discussion repository.
• Generate links that open a configurable GitHub issue form/template with the stable document identifier and relevant document context.
• Make the GitHub repository, issue template, labels, and user-facing discussion texts configurable.
• Discover existing discussions by stable document identifier.
• Load existing discussions only after explicit user interaction; failure or GitHub rate limiting must not affect access to the documentation content.
• Keep non-website outputs free of website-only interaction markup.

Non-functional requirements

• No custom backend service or additional runtime infrastructure.
• GitHub is the single source of truth for discussion content.
• Documentation builds and generated allowlists are deterministic and reproducible from reviewed source and configuration.
• Existing discussions survive page-title and URL changes.
• The feature is reusable by all toolkit generators and remains disabled unless explicitly configured.

Deliverables

• Standalone GitHub-discussions generator.
• Configuration schema and reference documentation.
• Proposed ADR covering the architecture, trust boundary, terminology, and synchronization mechanism.
• Example integration for at least one arc42 chapter, one ADR, and one article or generic page.
• Language-agnostic Gherkin feature specification and automated tests bridged to every scenario.
• Migration guide from the profile repository's project-local implementation.

Proposed acceptance specification

Feature: GitHub-backed discussions for generated documentation
  As a documentation project maintainer
  I want to enable document-specific GitHub discussions
  So that readers can give public feedback without a custom backend

  Scenario: Discussions are disabled by default
    Given a documentation project without discussion configuration
    When its documentation is generated
    Then no discussion links, interaction assets, or allowlist are emitted

  Scenario Outline: Supported published documents receive stable discussion links
    Given discussions are enabled for a published <document type>
    When the documentation is generated
    Then the page receives a discussion link containing its stable semantic document identifier
    And changing the page title or URL does not change that identifier

    Examples:
      | document type   |
      | arc42 chapter   |
      | ADR             |
      | article         |
      | additional page|

  Scenario: Only published discussion-enabled identifiers are synchronized
    Given published, unpublished, and discussion-disabled documents
    When the discussion allowlist is generated and synchronized
    Then the configured GitHub repository receives only identifiers for published discussion-enabled documents

  Scenario: Existing discussions are loaded on explicit request
    Given a generated static page with GitHub-backed discussions
    When the reader explicitly requests existing discussions
    Then the page loads discussions matching the stable document identifier from GitHub
    And the page content remains usable if the request fails or is rate-limited

  Scenario: Non-website outputs omit discussion interaction
    Given a discussion-enabled document
    When it is rendered for a non-website target
    Then website-only discussion markup and scripts are omitted

Acceptance criteria

• A generated documentation project can enable GitHub-backed discussions through configuration.
• New supported pages automatically receive stable semantic identifiers.
• Only published, discussion-enabled identifiers are accepted by the GitHub-side workflow.
• Existing discussions survive page-title and URL changes.
• Static hosting continues to work unchanged.
• No additional runtime infrastructure is required.
• The automated test suite maps every Gherkin scenario to at least one identifiable verification.

Architecture impact and open decisions

This feature affects the shared generator boundary, artifact metadata and identifier semantics, generated site assets, publication filtering, the build/deployment workflow, and the GitHub repository trust boundary.

The ADR must decide at least:

• whether “discussion” is the toolkit domain term while GitHub Issues remain the implementation mechanism, or whether GitHub Discussions are supported as an alternative;
• whether existing artifact IDs are always the semantic discussion IDs or whether generic pages need a separate ID namespace;
• how allowlist synchronization is authenticated, versioned, validated, and made idempotent;
• which assets are generator-owned and how consuming generators integrate them without copying implementation;
• how public GitHub API limits, accessibility, privacy, and untrusted discussion content are handled.

Potentially affected architecture knowledge includes the generator building blocks, generation and interaction runtime scenarios, deployment/publishing view, cross-cutting configuration and security concepts, quality goals for reproducibility and portability, and risks around API rate limits and repository synchronization.

Reference implementation

Generalize rather than duplicate the implementation from dieterbaier/profile#44, especially:

• features/article-comments.feature
• scripts/validate-profile-metamodel.rb
• src-content/theme/article-comments.js
• test/profile_comments_test.rb
• .github/workflows/update-profile.yml

The meetup slides in talks/ai-assisted-coding-meetup-envite/slides.adoc provide additional project context but are not the source of truth for implementation behavior.

Suggested slicing

1. Specify configuration, semantic identifiers, publication eligibility, and the ADR.
2. Build the walking skeleton for one generated document type, including link, allowlist, synchronization, and interaction-on-demand.
3. Extend document-type adapters for arc42 chapters, ADRs, articles, and generic pages.
4. Add example integrations, documentation, migration guidance, and cross-generator verification.

Out of scope

• A custom comments backend.
• Mirroring discussion content into generated source files.
• Eagerly loading GitHub data during normal page load.
• Replacing GitHub as the discussion system of record.