docs(adr): accept ADR 0071 harness snapshot for agent traces

[HofniGartner]

Summary

Record ADR 0071: Level-1 harness-snapshot.json plus mirrored root-span forge pointers as the run-time join contract. Docs only — implementation remains #5449.

Replaces auto-closed #5505 / #5508 after vouch (discussion #5520). Incorporates prior review feedback: Accepted status, Options, single Decision, bullet Consequences, Planned callout, architecture.md sync, ADR 0005 in Context, and clear OTEL_SDK_DISABLED behavior for trace_id / traceparent.

Related Issue

Implementation: #5449

Changes

• Add accepted ADR 0071 (snapshot file + root-span attrs when tracing is on; omit trace fields when SDK disabled)
• Tracing guide: Level 1 = run-telemetry.jsonl; snapshot under > **Planned:** + Implement ADR 0071: harness-snapshot.json + root-span forge pointers #5449
• docs/architecture.md: Observability decided entry linking ADR 0071

Testing

• Docs-only — no code/lint/test changes required for this PR
• ADR number still free on main at merge (/renumber-adr if needed)

Checklist

• PR title follows Conventional Commits
• Commits are signed off (DCO)
• I wrote this contribution myself and can explain all changes in it

Made with Cursor

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

docs(adr): accept ADR 0071 harness snapshot + forge pointer correlation

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add accepted ADR 0071 defining a run-start join contract via harness-snapshot.json.
• Specify root-span attribute mirroring when tracing is enabled, and omission when
 OTEL_SDK_DISABLED=true.
• Update tracing guide and architecture doc to reference the ADR and planned implementation (#5449).

Diagram

graph TD
  env{{"CI env / FULLSEND_*"}} --> run["fullsend run"] --> enabled{"OTEL SDK enabled?"} --> root["Root run span"] --> jsonl["run-telemetry.jsonl"] --> otlp{{"OTLP backend"}}
  root -->|"mirror vcs.* / cicd.*"| otlp
  root -->|"write snapshot + trace_id"| snap["harness-snapshot.json"] --> offline{{"Offline consumers"}}
  enabled -- "no (OTEL_SDK_DISABLED)" -->|"write snapshot (no trace fields)"| snap

  subgraph Legend
    direction LR
    _proc["Process / artifact"] ~~~ _dec{"Decision"} ~~~ _ext{{"External"}}
  end

Loading

High-Level Assessment

The PR’s approach is appropriate: document the join contract as an accepted ADR and mark the snapshot behavior as planned in the tracing guide until implementation (#5449) lands. This keeps the runtime/API contract explicit without coupling it prematurely to telemetry format details.

Files changed (3) +107 / -8

Documentation (3) +107 / -8

0071-forge-pointer-correlation-for-agent-traces.mdAdd accepted ADR 0071 for harness snapshot + root-span join keys +93/-0

Add accepted ADR 0071 for harness snapshot + root-span join keys

• Introduces ADR 0071 (Accepted) defining the runtime join contract for correlating runs with forge/CI provenance. Specifies a dedicated 'harness-snapshot.json' plus mirrored root-span attributes when tracing is enabled, and clarifies behavior when 'OTEL_SDK_DISABLED=true' (omit trace context fields and skip mirroring).

docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md

architecture.mdRecord ADR 0071 under Observability decisions +1/-0

Record ADR 0071 under Observability decisions

• Adds a new Observability “Decided” bullet documenting the harness snapshot artifact and root-span key mirroring, linking to ADR 0071.

docs/architecture.md

distributed-tracing.mdClarify Level 1 baseline and add planned snapshot callout +13/-8

Clarify Level 1 baseline and add planned snapshot callout

• Rephrases the Level 1 section to emphasize 'run-telemetry.jsonl' as the baseline artifact and clarifies that 'OTEL_SDK_DISABLED=true' suppresses span export. Adds a planned callout referencing ADR 0071 and the implementation tracking issue (#5449), noting that only 'run-telemetry.jsonl' is guaranteed until shipped.

docs/guides/infrastructure/distributed-tracing.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (2)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Snapshot marked shipped ✓ Resolved 🐞 Bug ≡ Correctness

Description

docs/architecture.md states that every run writes harness-snapshot.json, but the distributed
tracing guide explicitly says it is planned (tracked in #5449) and that only run-telemetry.jsonl
is currently guaranteed on disk. This contradictory artifact contract can mislead operators and
downstream tooling authors into depending on a file that is not yet produced.

Code

docs/architecture.md[265]

+- Harness snapshot join keys: every run writes `harness-snapshot.json` (harness fingerprint + forge/CI pointers) and, when tracing is enabled, mirrors those keys on the root span so offline and OTLP consumers can correlate without scraping CI env ([ADR 0071](ADRs/0071-forge-pointer-correlation-for-agent-traces.md)).

Relevance

⭐⭐⭐ High

Repo frequently accepts fixes that qualify docs to avoid claiming planned behavior is shipped or
guaranteed.

PR-#2743
PR-#5454

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The architecture doc claims harness-snapshot.json is written on every run, while the tracing guide
in the same PR says it is planned and not yet guaranteed; the new ADR also states implementation is
tracked separately, reinforcing that it is not yet shipped behavior.

docs/architecture.md[254-266]
docs/guides/infrastructure/distributed-tracing.md[8-25]
docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[58-84]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`docs/architecture.md` currently presents `harness-snapshot.json` as a guaranteed, shipped artifact (“every run writes ...”), but `docs/guides/infrastructure/distributed-tracing.md` marks it as **Planned** with implementation tracked in #5449 and says it is not yet guaranteed. This creates an inconsistent contract across docs.

### Issue Context
The same PR adds a **Planned** callout in the tracing guide and an accepted ADR noting implementation is tracked separately, so the architecture bullet should not read as already implemented.

### Fix Focus Areas
- docs/architecture.md[262-266]

### Suggested change
Update the new architecture bullet to explicitly indicate it is planned/pending implementation (e.g., prefix with “Planned:” or “Decided (pending #5449):”) and/or remove the “every run writes” wording until the feature ships.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Guide not in admin/user 📜 Skill insight ⌂ Architecture

Description

The modified guide file is located under docs/guides/infrastructure/, but guides must live under
either docs/guides/admin/ or docs/guides/user/. This breaks the required guides directory
structure and audience organization.

Code

docs/guides/infrastructure/distributed-tracing.md[R10-24]

+Every `fullsend run` produces **`run-telemetry.jsonl`** in the run output
+directory with no configuration required — OTLP JSON spans covering the run
+lifecycle (sandbox creation, agent iterations, validation) with timestamps,
+durations, trace IDs, and token/cost attributes.

This file is written on every run unless `OTEL_SDK_DISABLED=true`, which
-suppresses all telemetry output including the local file. It contains
-metadata only — no prompts, completions, or source code content.
+suppresses span export (local file and OTLP). It contains metadata only — no
+prompts, completions, or source code content.
+
+> **Planned:** `harness-snapshot.json` (run-start harness fingerprint and
+> forge/CI pointers, mirrored on the root span) is decided in
+> [ADR 0071](../../ADRs/0071-forge-pointer-correlation-for-agent-traces.md).
+> Implementation is tracked in
+> [#5449](https://github.com/fullsend-ai/fullsend/issues/5449). Until that
+> ships, only `run-telemetry.jsonl` is guaranteed on disk.

Relevance

⭐ Low

Multiple prior reviews rejected moving guides into admin/user subtrees; directory-structure rule not
enforced in practice.

PR-#5454
PR-#4901
PR-#5457

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062077 requires guides under docs/guides/ to be placed in either admin/ or
user/. The PR modifies docs/guides/infrastructure/distributed-tracing.md, which is not in either
required subdirectory.

docs/guides/infrastructure/distributed-tracing.md[1-24]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/guides/infrastructure/distributed-tracing.md` is a guide placed outside the allowed `docs/guides/admin/` or `docs/guides/user/` directories.

## Issue Context
Compliance requires every guide under `docs/guides/` to be placed in either the `admin/` or `user/` subdirectory and target a single audience.

## Fix Focus Areas
- docs/guides/infrastructure/distributed-tracing.md[1-40]
- docs/guides/README.md[1-200]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. ADR adds non-template section 📜 Skill insight ⚙ Maintainability

Description

The new ADR includes a ## Related section that is not present in the required ADR template, so the
ADR does not match the template exactly. This undermines consistent ADR structure and automated
parsing/validation assumptions.

Code

docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[R86-93]

+## Related
+
+- [ADR 0050](0050-distributed-tracing-instrumentation.md)
+- [ADR 0005](0005-forge-abstraction-layer.md)
+- Shared join contract: [provenance_forge_pointers.md](https://github.com/RHEcosystemAppEng/ABEvalFlow/blob/main/Docs/provenance_forge_pointers.md)
+- Implementation: [#5449](https://github.com/fullsend-ai/fullsend/issues/5449)
+- [#2368](https://github.com/fullsend-ai/fullsend/issues/2368)
+- [#294](https://github.com/fullsend-ai/fullsend/issues/294)

Relevance

⭐ Low

Similar request to add non-template ADR section (Implementation/References) was rejected; template
adherence not enforced that strictly.

PR-#2743

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062099 requires ADRs to follow docs/ADRs/0000-adr-template.md exactly. The
template defines sections through ## Consequences and does not include ## Related, but the new
ADR adds ## Related at the end.

docs/ADRs/0000-adr-template.md[10-41]
docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[86-93]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR includes an extra `## Related` section, but the project ADR template does not include this section, and the rule requires the ADR to follow the template exactly.

## Issue Context
Either the ADR should remove/merge the extra section into template-approved sections, or the template should be updated to include `## Related` (and then ensure the ADR matches the updated template).

## Fix Focus Areas
- docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[86-93]
- docs/ADRs/0000-adr-template.md[10-41]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[HofniGartner]

Addressed the architecture.md inconsistency: the Observability bullet now reads Decided (pending #5449) / "every run will write", matching the Planned callout in the tracing guide.