Forge Runtime Tracing section for OpenTelemetry and Agent Reliability OTEL Labels

[ericksondelacruz]

Forge Runtime Tracing section for OpenTelemetry and Agent Reliability OTEL Labels

Summary

trustabl forge now tells the coding model how to make an agent observable at
run time. The generated SKILL.md gains a "Runtime Tracing" section built
around agent-reliability-otel-labels, the library that adds process labels
(run identity, step order, tool-call fingerprints, attempt count, side-effect
class, exit reason) to the OpenTelemetry spans an agent already emits.

Forge also keeps each SDK's rule section to the languages that SDK is used in,
so a Go-only repo is no longer handed Python and TypeScript rules.

This PR changes forge only. It adds no scan rules, changes no rule packs, and
leaves schema_version unchanged. The scan-side label rules (OBS-006..012)
ship separately.

Runtime Tracing section

It comes right after the apply loop, in four steps:

1. Emit spans with OpenTelemetry.
2. Add the labels with agent-reliability-otel-labels.
3. Choose the values (attempt, side_effect, error_class, exit_reason).
4. Check before moving on.

Content:

• One block per language (Python, TypeScript, Go), plus ten framework recipes:
  Python (AutoGen, CrewAI, Google ADK, LangChain / LangGraph, MCP client
  sessions, OpenAI Agents SDK, Pydantic AI), TypeScript (OpenAI Agents SDK,
  Vercel AI SDK), Go (Google ADK).
• Each language's setup registers its tracer provider globally, because
  framework instrumentation starts its spans on the global provider.
• The Google ADK Go recipe keeps one Run per runner.Run on the context.
  ADK builds the agent, its tools and its callbacks once, so a Run they
  closed over would be shared by every run, which is the defect OBS-009
  flags.
• The text is embedded markdown under internal/forge/tracingtext/.

Selection:

• Forge detects the language each SDK is declared in from the manifest that
  declares it (pyproject.toml / requirements.txt / Pipfile /
  poetry.lock → Python, package.json → TypeScript, go.mod → Go). It keeps
  (category, language) pairs as detected, with no cross product.
• --lang python,typescript,go adds a language. An unknown value exits 1.
• The section is omitted, with a one-line stderr note, when no supported
  language is selected. It is omitted without a note when claude_skill is
  the only category: skills are SKILL.md files, not agent code.

Rule sections filtered by language

SelectRuleLanguages decides which languages each category's rules are kept
for. GenerateCombined then drops each rule whose language the SDK is not
used in, using the scanner's own language gate (RuleDef.AppliesToLanguage).
TypeScript keeps JavaScript rules, and a rule with no language is always kept.

• A listed language that no rule of the pack targets gets a one-line note
  under that SDK's heading. Today that is a Go-only Google ADK repo, which gets
  the two language-independent ADK rules and the note.
• A category keeps every rule when forge does not know every language it is
  used in: one given only through --policy, or one also declared in a
  manifest forge cannot place, such as composer.json (Detection.Unplaced).
• --lang adds its language to every listed category, so it can bring rules
  back but never remove them.

This also changes output for single-language repos of other SDKs. A
Python-only OpenAI Agents repo now gets its 33 Python rules and 2
language-independent rules, not the TypeScript rules as well.

CLI

• --lang help says it does not select a rule pack, so a repo with no
  manifest yet needs --policy too. When --lang is given and nothing is
  detected, the exit-1 message says the same.
• forge check's regenerate hint reminds you to pass the --policy and
  --lang flags used originally, since the stamp does not record them.

Supporting changes

• Recon gains a go.mod needle for Google ADK for Go. Its recon-only name
  google-adk-go is not mapped to an SDK for scan, so it never emits
  META-002.
• TemplateVersion is 3, so forge check reports older generated skills as
  outdated.
• A drift guard against the library: a vendored copy of its key manifest, a
  golden list of the 36 identifiers the text uses, tests for both, and
  scripts/check-otel-sync.sh for checking against the real repo. The script
  counts only declarations in source files, so a stale __pycache__/*.pyc, a
  comment, or another package's function with the same name (rand.Read)
  cannot hide a rename.

How to verify

• go test ./... passes.
• OTEL_REPO=../agent-reliability-otel-labels scripts/check-otel-sync.sh
  passes: 36 identifiers checked.
• RULES_REPO=<agent-reliability-rules at main> scripts/check-rules-sync.sh
  passes (128 files). This PR touches no rule files.
• Unit tests cover:
  • the ADK Go recipe: its Go block is parsed, and the Run must be created
    only in a per-run function whose result reaches runner.Run;
  • global provider registration in all three language setups;
  • the rule-language selection and filter, and the coverage note;
  • the skill-only and --lang CLI paths.
• Run by hand against the published 0.1.0 API; these harnesses are not
  committed:
  • ADK Go v1.7.0: the recipe's code, taken from a generated SKILL.md,
    ran on one agent built once, 5 runs with 3 at once. It gave 5 distinct run
    IDs, and step indexes restart at 0 in every run. The pattern this
    replaces gave 1 shared run ID.
  • OpenTelemetry JS 2.x: with the TypeScript setup from a generated
    SKILL.md, a span started through the global API is exported and
    labelled. Without the global registration it is dropped.
  • check-otel-sync.sh: each identifier was renamed in a copy of the
    library. The script catches all 36 renames and 9 declaration-only renames;
    the earlier version missed 6 and 7 of them.

Known limits

• Forge text proves nothing at run time. With no current span inside a tool,
  every label call is a silent no-op.
• Non-OpenTelemetry tracing stacks are not covered. A framework with no
  recipe gets its language block only, and is told to turn on its own
  OpenTelemetry instrumentation.
• In the ADK Go recipe, ADK skips the after-agent callback when the caller
  stops iterating a run's events, so a run that stops on its first failure
  carries no trustabl.exit_reason. The recipe text says so.
• No Go-specific Google ADK rules exist, so a Go ADK repo gets the
  language-independent ADK rules only.

Follow-ups

• Add a CI job for check-otel-sync.sh. The library repo is now public.