Cut unnecessary comment content across the engine and observers

[chris-colinsky]

Removes 556 comment lines across 9 files. No executable code changes.

Verifying that first, since it is the only thing that matters here

Every changed file was compared token by token against main, with comments and formatting-only tokens stripped:

files changed on this branch: 9
code tokens IDENTICAL in every one: the diff is comments only

So this cannot change behaviour, independent of the suite. The suite is green anyway (2214 passing), along with ruff and pyright.

What was cut, and the test used

The rule is whether a comment describes the code as it stands. Not how it got there, not what it used to do, not the reasoning that produced it.

The dominant pattern, in every one of the nine files, was a real invariant followed by the story of the change that introduced it. The invariant stays, in present tense; the story goes to git. The fan-out tracking key is the clearest example: the key must carry both concurrency axes or two live executions collide and one rolls forward results it never computed. That stays. The account of the branch axis having been absent, and of why nothing surfaced it, does not.

Specifically removed:

• History. What an earlier version did, what a defect used to be, what the engine no longer does.
• Decision provenance. Which coord thread settled a question, "raised for the batched review", "spec ruled".
• Meta-commentary on the comments themselves, including one comment explaining why a previous version of that same comment was wrong.
• Prose duplicating a CHANGELOG entry for the same change, in two copies that had already drifted apart.
• Over-explanation. A 26-line restatement of a keying scheme the code states, numbered walkthroughs of algorithms, proposal-by-proposal change logs on event field docs.

Deliberately kept: every spec citation, and every explanation of a constraint the code currently has to satisfy. Several blocks are still 11-19 lines because they are dense with contract and nothing in them is unnecessary.

Ratios

  cut  file                    ratio
  228  langfuse/observer.py   31.4% -> 25.1%
  127  otel/observer.py       32.0% -> 29.5%
   67  compiled.py            29.4% -> 27.5%
   57  events.py              27.9% -> 24.6%
   27  openai.py              26.0% -> 25.0%
   23  fan_out.py             30.7% -> 29.0%
   17  graph/observer.py      26.8% -> 25.6%
    6  metadata.py            23.3% -> 22.0%
    4  lineage.py             39.2% -> 37.7%

src/ overall moves 23.1% to 21.7%. The ratio barely shifts despite 556 lines going, because the files shrank too, which is the point: these files are long structurally, not merely over-annotated. Closing that gap is the file split, tracked separately and deliberately not attempted during release prep.

Also here

AGENTS.md gains a Docstrings vs # comments section. Docstrings are published through mkdocstrings into docs/reference/, so they are shipped end-user documentation, which is why spec citations and normative language belong in comments instead. That convention governed this sweep and had never been written down.

Not in scope

• A docstring pass. 80 docstrings across 31 files still carry spec refs or normative language; tracked.
• The remaining 36 source files. The mechanically-detectable categories (history, provenance) were swept repo-wide and come back clean; the judgment-based pass covered these nine, and the rest average under 50 narrative lines each.

[Copilot]

🟡 Changes recommended

A newly updated comment in otel/observer.py references a non-existent _publish_active_span symbol and should be corrected to avoid misleading future maintainers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR reduces long-form historical/provenance commentary across core engine and observability modules, keeping only comments that describe current invariants and spec-mandated constraints. It also documents the repo convention for what belongs in docstrings vs # comments in AGENTS.md.

Changes:

• Trimmed/condensed comments across engine + observer modules without changing executable logic.
• Added guidance in AGENTS.md clarifying docstrings (published API docs) vs maintainer-facing # comments.

File summaries

File	Description
src/openarmature/observability/otel/observer.py	Comment reductions/condensation around OTel observer span/lineage handling.
src/openarmature/observability/metadata.py	Comment trimming around reserved metadata key enforcement.
src/openarmature/observability/lineage.py	Comment condensation describing lineage-aware dispatch key canonicalization.
src/openarmature/observability/langfuse/observer.py	Comment reductions/condensation around Langfuse mapping and lineage behavior.
src/openarmature/llm/providers/openai.py	Comment condensation around managed wire fields, typed events, and canonicalization.
src/openarmature/graph/observer.py	Comment trimming around invocation context and checkpointing invariants.
src/openarmature/graph/fan_out.py	Comment condensation around fan-out progress keying and resume validation behavior.
src/openarmature/graph/events.py	Comment condensation clarifying event field contracts and spec references.
src/openarmature/graph/compiled.py	Comment reductions around fan-out progress projection/restore and invoke stepping.
AGENTS.md	Added “Docstrings vs # comments” guidance for contributors/agents.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.