Proposal: Introduce ADR for intentional semantics and important design decisions

[QuantumGhost]

AI disclosure: This issue was drafted with Codex using GPT-5.4.
I have reviewed the report, and I am responsible for the content.

Summary

Introduce an ADR mechanism in graphon to record intentional semantics and other important design decisions that downstream users should rely on.

The goal is not to document all historical behavior or every refactor. The goal is to make a small set of important decisions explicit, durable, and reviewable.

This should especially cover decisions like:

• HITL interface boundary
• LLM polling execution model
• other semantics that answer: “what should future users rely on?”

Problem

graphon is evolving quickly, and many important decisions currently live only in:

• PR descriptions
• issue discussions
• code diffs
• AI coding conversations
• Internal IM conversations

That creates a few problems:

• it is hard to tell which behavior is explicitly designed
• it is hard to distinguish supported semantics from behavior that is merely:
  • historical
  • evolutionary
  • code-implied
• future maintainers may re-open already-settled semantic questions
• downstream integrators may rely on behavior that was never intentionally supported

In other words, PR history is good implementation history, but it is not enough as long-term semantic memory.

Core Principle

ADR should record intentional semantics, not discovered semantics.

An ADR is needed when a change:

• establishes a semantic or contract that downstream users should rely on
• changes or intentionally retires an existing supported semantic or contract
• defines a cross-cutting boundary or ownership model
• promotes an explicitly experimental behavior into supported behavior

An ADR is usually unnecessary for:

• historical or code-implied behavior that the project is not intentionally promoting
• bug fixes within an already accepted semantic
• dependency updates, CI changes, release chores
• local refactors that preserve semantics
• docs-only or test-only changes

Proposal

Introduce an ADR workflow for graphon with the following properties:

1. ADR is lightweight memory, not a separate approval gate

ADR should be:

• short
• same-PR
• focused on semantics and decision boundaries
• independent from implementation details

It should not become a heavyweight pre-implementation design process.

2. ADR should record a small number of things

Each ADR should capture:

• context
• decision
• supported semantic / contract
• consequences
• reasonable alternatives considered and rejected, with reasons

3. Explicitly experimental behavior is the only normal exception

If an API or behavior is explicitly marked experimental, ADR capture may be deferred until the semantics stabilize.

Otherwise, if a PR introduces or changes supported semantics, ADR should land with the same PR.

AI-assisted Workflow

This repository is a strong candidate for AI-generated ADR drafts.

My preferred workflow is:

1. AI coding process produces code changes
2. AI automatically drafts the ADR from:
   • coding conversation
   • linked issue / PR discussion
   • relevant code diff
3. human supplements the missing context that does not appear in the conversation
4. human reviews and edits the ADR before merge

Ideally, ADR generation should be as automatic as possible during AI-assisted development.

The human should not need to write the first draft from scratch. The human’s main job should be:

• add context that is outside the AI conversation
• correct omissions or overclaims
• confirm that the recorded semantics are actually intentional

Initial Scope

A good initial scope is to backfill a very small number of high-signal decisions first, for example:

• HITL interface boundary
• LLM polling execution model

This keeps the process focused and helps establish what “ADR-worthy” means in practice.

Non-goals

This issue is not proposing that we:

• write ADRs for every feature or refactor
• treat every public API change as ADR-worthy by default
• document all historical behavior
• introduce a heavyweight up-front design bureaucracy

Acceptance Criteria

• An ADR mechanism exists in the repository
• The policy clearly states that ADR records intentional semantics
• The workflow is lightweight and same-PR
• Explicitly experimental behavior is the only normal deferral path
• AI-generated ADR drafts are part of the intended workflow
• At least a small number of representative, high-signal ADRs are backfilled

Suggested Follow-ups

• add ADR index + ADR policy doc
• add ADR scaffold / generator for AI-assisted use
• wire ADR consideration into PR workflow
• backfill:
  • HITL interface
  • LLM polling

[QuantumGhost]

One concern raised by @WH-2099 in a private discussion is that ADR-style documentation may not pay for itself in a fast-moving codebase.

The main objection is that:

• Documentation can easily drift from the actual code, and stale or incorrect documents may be more harmful than having no document at all. From this perspective, if a decision depends on real operational constraints, those constraints should ideally be captured in code, configuration, or infrastructure, rather than in a separate narrative artifact.
• There is also concern that maintaining decision records introduces its own complexity and historical inertia, which can discourage re-evaluating decisions from first principles as the system evolves.