docs: add compact AGENT_DECISION_COMMENTS.md convention

AGENTS.md

@@ -5,10 +5,14 @@
 This is a documentation-first repository for the Agent Decision Comments
 convention. `README.md` is the canonical specification: it defines the four
 directives, their format, scope, examples, review workflow, and current version.
-`LICENSE` contains the MIT license. There are currently no source, test,
-generated, or asset directories. Keep new documentation at the repository root
-unless a larger collection clearly warrants a focused directory such as
-`examples/`.
+`AGENT_DECISION_COMMENTS.md` is the compact operational convention that
+adopting repositories copy into their own repositories; agents read it on every
+task, so keep it short. Keep it consistent with the full specification: every
+rule and example it states must match `README.md`, and both files must carry
+the same specification version. `LICENSE` contains the MIT license. There are
+currently no source, test, generated, or asset directories. Keep new
+documentation at the repository root unless a larger collection clearly warrants
+a focused directory such as `examples/`.
 
 ## Build, Test, and Development Commands
 
@@ -18,9 +22,10 @@ check. Run these commands before submitting a change:
 - `npx --yes markdownlint-cli2@0.23.2 --config .markdownlint.jsonc "**/*.md"`
   runs the same linter version as CI.
 - `git diff --check` detects trailing whitespace and malformed patches.
-- `rg '^#{1,6} ' README.md AGENTS.md` reviews the Markdown heading hierarchy.
-- `git diff -- README.md AGENTS.md` gives a focused review of documentation
-  changes.
+- `rg '^#{1,6} ' README.md AGENTS.md AGENT_DECISION_COMMENTS.md` reviews the
+  Markdown heading hierarchy.
+- `git diff -- README.md AGENTS.md AGENT_DECISION_COMMENTS.md` gives a focused
+  review of documentation changes.
 
 Also render changed Markdown in a previewer and verify that fenced examples,
 lists, and headings display correctly.
@@ -43,8 +48,9 @@ directive-only examples.
 The workflow in `.github/workflows/markdownlint.yml` lints every Markdown file
 on pushes and pull requests. Confirm every new example matches the format and
 scope rules in `README.md`, uses valid syntax for its declared language, and
-does not contradict another section. Run the local lint command and
-`git diff --check`, then inspect the rendered output.
+does not contradict another section, including `AGENT_DECISION_COMMENTS.md`.
+Run the local lint command and `git diff --check`, then inspect the rendered
+output.
 
 ## Commit & Pull Request Guidelines
 

AGENT_DECISION_COMMENTS.md

@@ -0,0 +1,92 @@
+# Agent Decision Comments
+
+> Preserve the why in agent-written, human-reviewed code.
+
+- Specification version: **0.4.0**
+- Full specification: <https://github.com/dbrattli/adc>
+
+Agent Decision Comments (ADCs) are concise, structured annotations that keep
+durable engineering decisions beside the code they govern. They use ordinary
+comments, documentation comments, or docstrings, and they require no runtime
+dependency.
+
+## The four labels
+
+```text
+decision:    A deliberate choice and the reason for it.
+invariant:   A falsifiable property that the code must preserve.
+assumption:  An external belief that this code does not guarantee.
+tradeoff:    A cost accepted in exchange for a benefit.
+```
+
+Directives are optional. Add only those that capture non-obvious rationale.
+Start with `decision:` and `invariant:`. A caller obligation is a precondition,
+not an assumption.
+
+## Format
+
+```text
+<label>: <statement> [— <reason or consequence>]
+```
+
+- One directive per physical line, in present tense and as concise as
+  practical.
+- State only what is not already evident from code, types, or tests.
+- Prefer specific, falsifiable statements over general claims.
+- In a docstring or documentation comment, write normal prose first, leave a
+  blank line, then list the directives.
+- Use an ordinary comment when API documentation is not needed.
+- Update or remove a directive whenever its code or rationale changes.
+
+The em dash is a readability convention, not a parser delimiter.
+
+```python
+def process_events(queue):
+    """
+    Deliver queued events to their registered handlers.
+
+    decision: processes events on one consumer to preserve arrival order
+    decision: routes events through a queue to decouple producers from handler timing
+    invariant: handlers observe events in enqueue order
+    tradeoff: limits throughput to gain deterministic processing
+    """
+```
+
+## When to write one
+
+Write or update an ADC when a change:
+
+- chooses one meaningful algorithm, architecture, or data structure over
+  another;
+- introduces ordering, consistency, concurrency, or lifecycle constraints;
+- establishes a boundary that future code must not accidentally cross;
+- relies on an external condition that could prove false;
+- accepts a known limitation in return for a concrete benefit;
+- implements behavior a competent reviewer would reasonably question;
+- distills a relevant RFC or ADR decision at the point where it constrains code.
+
+Do not add one for mechanics that are clear from the implementation, facts
+enforced by the type system, trivial mechanical refactoring, generic advice,
+speculative reasoning, or every function merely for consistency.
+
+## Scope
+
+A directive governs the construct it is attached to and its nested constructs.
+Directives from enclosing scopes accumulate. A narrower directive may
+specialize a broader decision but never silently cancels an invariant. Before
+modifying code, collect the active directives from the file level down to the
+modified site. If active directives conflict, surface the conflict before
+changing the code.
+
+## Existing comments are active constraints
+
+Before modifying code, read the ADCs already governing it.
+
+- Preserve an `invariant:` or justify the change explicitly.
+- Do not silently reverse a `decision:`.
+- Validate an `assumption:` when the change depends on it.
+- Reconsider a `tradeoff:` when its cost or benefit changes.
+
+If a decision changes, update or remove the annotation in the same change and
+call it out in the review summary. An obsolete directive is worse than no
+directive: it creates false confidence for reviewers and future agents.

README.md

@@ -2,7 +2,7 @@
 
 > Preserve the why in agent-written, human-reviewed code.
 
-- Specification version: **0.3.1**
+- Specification version: **0.4.0**
 - Canonical repository: <https://github.com/dbrattli/adc>
 
 Agent Decision Comments (ADCs) are concise, structured annotations that keep durable
@@ -26,9 +26,9 @@ To adopt ADCs in another repository, ask your coding agent:
 Let's adopt https://github.com/dbrattli/adc for this repository.
 ```
 
-The agent should copy the convention from a published release into the
-repository as `AGENT_DECISION_COMMENTS.md`. It should then reference the local
-file from `AGENTS.md`, `CLAUDE.md`, or the equivalent:
+The agent should copy `AGENT_DECISION_COMMENTS.md` from a published release
+into the repository. It should then reference the local file from `AGENTS.md`,
+`CLAUDE.md`, or the equivalent:
 
 ```text
 This repository uses Agent Decision Comments.
@@ -40,6 +40,10 @@ Treat them as active constraints and justify any change explicitly.
 Add ADCs for non-obvious rationale introduced by your change.
 ```
 
+Keep the local convention file compact: agents read it on every task. The full
+specification in `README.md` is the human reference for discussion and edge
+cases.
+
 If you use another stable path, such as `docs/agent-decision-comments.md`, name
 that exact path in the instruction file. Prefer a descriptive filename over
 `ADC.md` so contributors and agents can discover the convention easily.
@@ -417,7 +421,8 @@ adoption requirements.
 Version changes apply to the convention itself, not repository-only maintenance
 such as CI or contributor documentation. Each specification version is
 published as a GitHub release and `vX.Y.Z` tag so adopting repositories can
-trace and review updates.
+trace and review updates. Releases include both the compact convention and the
+full specification.
 
 ---