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.

[waynesun09]

Automated verification pass on ADR 0071: numbering, cross-references, and citation accuracy. Findings below as inline comments.

[waynesun09]

[HIGH] ADR number 0071 collides with open PR #2791

PR #2791 ("docs: ADR 0071 — Auto-merge", branch adr-0062-auto-merge) is open, mergeable, and independently adds docs/ADRs/0071-auto-merge.md for an unrelated decision. Because ADR filenames embed a distinct slug, the two files don't conflict at the git level, so both PRs can merge cleanly and leave two different documents both titled "71. ..." on main. On main today, docs/ADRs/ jumps directly from 0070-portable-provider-profile-resolution.md to 0073-named-mint-privilege-levels.md — 0071 and 0072 are only free because they're reserved by in-flight PRs (#2791 claims 0071; open PR #5016 claims 0072). This PR's own checklist item "ADR number still free on main at merge (/renumber-adr if needed)" is left unchecked, and a main-only check wouldn't catch this collision, since main alone still shows 0071 as free.

Suggestion: Before merging, check open PRs touching docs/ADRs/ (not just main) for the same slot. Whichever of #5524 / #2791 merges second should renumber at merge time to the actually-free slot — re-verify immediately before merge, since 0072 (#5016) and 0074 (also contested by two other open PRs) are in the same situation.

[waynesun09]

[HIGH] Implementation-tracking issue #5449 is closed as not_planned but cited as the active tracker

Issue #5449 ("Implement ADR 0071: harness-snapshot.json + root-span forge pointers") is closed with state reason not_planned, closed the day before this PR was opened, with a comment noting it was "opened too early" (the issue was meant to be filed only after this ADR merges, per the repo's ADR-then-issue workflow — so the closure was correct at the time). However, this PR still ships four live references to #5449 as the active/pending tracker: this ADR's Consequences bullet (here), this ADR's Related section ("Implementation: #5449"), docs/architecture.md ("Decided (pending #5449): ..."), and the callout in docs/guides/infrastructure/distributed-tracing.md ("Implementation is tracked in #5449 ... Until that ships, only run-telemetry.jsonl is guaranteed on disk"). Anyone following any of these links today lands on a closed, "not planned" issue — the opposite of what "pending"/"tracked"/"Planned" are meant to convey.

Suggestion: Reopen #5449 (its closure reason no longer applies once this ADR is Accepted) or file a fresh implementation-tracking issue, and repoint all four references before or immediately upon merge. At minimum, note in the PR description that #5449 will be reopened post-merge.

[waynesun09]

[MEDIUM] "Bitbucket" listed as a partially-covered forge, but it isn't a supported forge

This bullet implies Bitbucket is one of fullsend's targeted forges. ADR 0005 (forge-abstraction-layer, cross-referenced two lines earlier in this ADR's own Context) states "Fullsend must eventually support GitHub, GitLab, and Forgejo" and never mentions Bitbucket. In the codebase, internal/harness/forge_test.go (TestResolveForge_UnknownPlatform) uses "bitbucket" as the canonical example of an invalid forge platform, asserting ResolveForge("bitbucket") errors with "not valid." internal/forge/ on main also only contains github/ and gitlab/ subpackages. This reads as a mix-up with "Forgejo," fullsend's actual third forge, stated as settled fact in an Accepted ADR.

Suggestion: Change "GitLab/Bitbucket" to "GitLab/Forgejo" to match ADR 0005's forge scope and the codebase's forge-validation logic, or reword to "non-GitHub forges" if a generic statement was intended.

[waynesun09]

[MEDIUM] "Shared join contract" this ADR defers to is not yet merged

Context and Consequences both treat the external "shared join contract" document as an existing, settled artifact this ADR can safely defer field-naming detail to. This Related-section link (https://github.com/RHEcosystemAppEng/ABEvalFlow/blob/main/Docs/provenance_forge_pointers.md) currently 404s — that repo's Docs/ directory on main has no such file. The file exists only in RHEcosystemAppEng/ABEvalFlow#57 ("docs: freeze forge pointer and harness snapshot join contract"), an open, mergeable PR that adds Docs/provenance_forge_pointers.md. So the shared contract is real and in progress, but this ADR cites it as an already-frozen reference via a link that is dead today.

Suggestion: Either hold this ADR until ABEvalFlow#57 merges, link to the PR itself (.../pull/57) instead of the non-existent main path, or inline the minimal field list this ADR actually depends on so the decision doesn't hinge on an external, unmerged document in another org's repo.