@afokapu/atdd-bun 0.6.2 → 0.7.1

package/README.md

@@ -54,6 +54,7 @@ registerEnforcementTest({ root: import.meta.dir + "/..", profiles: ["traceabilit
 | `traceability` | acceptance → Bun test → source closure: every acceptance tested, every binding and `Tested-By` resolving |
 | `topology` | feature decomposition and the plan, source, test and E2E locations |
 | `planner` | schemas for every plan artifact, graph integrity, the scoped planner rules |
+| `telemetry` | the telemetry tracking plan: item shape, path-mirrored identity and versioning under `telemetry/`, wagon ownership of logical artifacts, the per-acceptance telemetry decision, metric label cardinality, source `Telemetry:` references, raw-string and forbidden-property emission, the vendor-SDK boundary around the TelemetryPort, and telemetry tests that bind the acceptance and item, assert the exact identity on a captured sink, cover every required item, and exercise declared timing semantics |
 | `docs` | the documentation capability, including the generated journey view |
 | `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions |
 | `interlocking` | train/interlocking binding, infrastructure and route coverage |
@@ -76,8 +77,15 @@ profiles: [traceability, planner]
 
 `all`, the hooks and the generated CI then run only those profiles. Any profile can still be run
 by name (`bun run atdd-bun coder`) to see what remains. An unknown name or an empty list is an
-error, never a silent run of nothing. Removing a profile loosens `atdd-bun.yaml`, so the integrity
-check reports it against the base branch until a human approves the change.
+error, never a silent run of nothing.
+
+With no `profiles:` field, every profile runs, but none is governed yet. The first explicit list is
+the adoption that establishes the governed set, so a brownfield repository can declare
+`profiles: [docs]` in an ordinary pull request. From then on, the integrity check reports, against
+the base branch, removing a profile from the list and removing the list itself. The second closes
+the two-step bypass `[docs, security]` → no list → `[docs]`. `init` writes a new `atdd-bun.yaml`
+with every profile listed, so a greenfield repository is governed from its first commit; trim the
+list before that commit to adopt gradually.
 
 ## Configuration
 
@@ -90,6 +98,7 @@ topology:                                     # default layout; point it at exis
   source_root: src/wagons
   test_root: tests/wagons
   e2e_root: e2e
+  telemetry_root: telemetry                    # tracking-plan registry; inert until the tree or a decision exists
 frontend:
   viewports: [375, 768, 1280]
   breakpoints: [480, 768, 1024, 1280]
@@ -114,7 +123,8 @@ modify the toolkit itself, only the configuration it offers, and enable capabili
 - the installed package differs from its published hashes;
 - the dependency is not an npm registry version;
 - a generated file (workflow, skills, instruction block, integrity test) was edited;
-- `atdd-bun.yaml` is looser than on the base branch.
+- `atdd-bun.yaml` is looser than on the base branch (after the first explicit `profiles:` list,
+  dropping a profile or the list counts).
 
 Each finding names its restore command.
 

package/conventions/coder.bun/coder.bun.telemetry-forbidden-properties.convention.yaml

@@ -0,0 +1,51 @@
+schema_version: 1.1.0
+rule_id: coder.bun.telemetry-forbidden-properties
+kind: rule
+status: active
+name: Forbidden properties never reach an emit call
+statement: >-
+  The object literal passed to an emit-like call naming a declared tracking-plan item MUST NOT
+  carry a property the plan forbids on that item (REQUIRED).
+terms:
+- term_id: forbidden_property
+  text: >-
+    a name in the item's forbidden_properties list (raw payloads, secrets, prompts): what must
+    never leave the process on that item. The plan writes snake_case; code may write camelCase;
+    comparison is normalized.
+- term_id: properties_object
+  text: >-
+    the object literal following the first argument of the emit-like call, on the same statement.
+content:
+  summary: >-
+    The forbidden list is a privacy and cost promise. It is enforced where the data leaves: the
+    emit call itself, against the plan entry the call names.
+  normative_text: |
+    When an emit-like call's first argument is a declared concrete id, the properties object is
+    scanned and every top-level key normalized (separators stripped, case folded) against the
+    item's forbidden list. Shorthand properties carry no name of their own and are invisible to
+    this scan; nested objects are judged at their own level. Properties the plan merely does not
+    declare are not forbidden — undeclared-key drift is the generated contract's concern, not this
+    rule's.
+  fix_hint: |
+    Pass the identifier, not the thing it identifies:
+
+      telemetry.emit("telemetry:event:be:commons:response-invocation-accepted", {
+        response_id: response.id,   // the identifier: allowed, planned, high-cardinality-declared
+        // raw_payload: response.raw,  // forbidden by the plan: never attach it
+      });
+  exceptions:
+  - >-
+    Only calls naming a declared item are checked: an id the registry does not hold is the
+    raw-string rule's finding, and double-reporting it here would be noise.
+  - >-
+    Inert until adoption, like every rule in this family.
+metadata:
+  aliases:
+  - CODER-TELEMETRY-FORBIDDEN-PROPERTIES-001
+  severity: 3
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_code

package/conventions/coder.bun/coder.bun.telemetry-implementation-binding.convention.yaml

@@ -0,0 +1,45 @@
+schema_version: 1.1.0
+rule_id: coder.bun.telemetry-implementation-binding
+kind: rule
+status: active
+name: Required telemetry is bound to its implementation
+statement: >-
+  Every concrete telemetry item an acceptance requires MUST be bound to at least one non-test
+  implementation source file by a `// Telemetry:` header (REQUIRED).
+terms:
+- term_id: required_item
+  text: >-
+    a concrete telemetry URN listed by an acceptance whose telemetry disposition is required.
+- term_id: implementation_binding
+  text: >-
+    a `// Telemetry:` header naming the item in non-test source — the source-to-telemetry edge
+    coder.bun.telemetry-source-binding resolves.
+content:
+  summary: >-
+    The third leg of the traceability tripod: planned, implemented, tested. This rule closes the
+    second leg — a required item no source claims is telemetry the plan believes in and the code
+    has never heard of.
+  normative_text: |
+    Required items are collected from acceptance decisions; implementation bindings from every
+    resolved Telemetry: header in non-test source. Their difference is reported at the tracking-plan
+    item's own file, because that is where the remedy starts: either bind the emitting source, or
+    stop requiring what nothing emits. An unresolvable required URN is the acceptance-decision
+    rule's finding and is not double-reported here.
+  fix_hint: |
+    Bind the emitting source, or drop the requirement:
+
+      // src/.../accept-response.ts
+      // Telemetry: telemetry:metric:be:commons:response-invocation-accepted:duration
+  exceptions:
+  - >-
+    Inert until adoption, like every rule in this family.
+metadata:
+  aliases:
+  - CODER-TELEMETRY-IMPLEMENTATION-BINDING-001
+  severity: 2
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_code

package/conventions/coder.bun/coder.bun.telemetry-raw-string-emit.convention.yaml

@@ -0,0 +1,53 @@
+schema_version: 1.1.0
+rule_id: coder.bun.telemetry-raw-string-emit
+kind: rule
+status: active
+name: No undeclared raw-string telemetry names
+statement: >-
+  An emit-like call (emit, emitted, track, capture, record, logEvent, emitEvent, sendEvent) whose
+  first argument is a string literal naming an event MUST name an item declared in the tracking
+  plan (REQUIRED).
+terms:
+- term_id: emit_like_call
+  text: >-
+    a call to the emit vocabulary, as function or method, with a string literal first argument.
+    Calls with computed first arguments (variables, template literals, contract constants) are
+    invisible to this check by design.
+- term_id: event_shaped_string
+  text: >-
+    a string that looks like a telemetry event name: a telemetry: URN, snake_case, camelCase with
+    an internal case shift, or a Title Case analytics name. Single lowercase words (log levels,
+    keys) are not event names.
+content:
+  summary: >-
+    Undeclared event strings are how tracking plans rot: the string compiles, the dashboard never
+    fills, and nobody owns the difference. The registry is the list of names that may be emitted.
+  normative_text: |
+    When an emit-like call passes an event-shaped string, that string must be a declared concrete
+    telemetry id. A declared id passed as a raw string passes today; once generated contracts ship,
+    emitting even a declared id by string is the drift the contract exists to prevent, and this
+    rule tightens with it. This check does not attempt to prove transaction ordering or any other
+    runtime property — it is a name-resolution check.
+  fix_hint: |
+    Declare the item, then emit through the plan:
+
+      telemetry/commons/response-invocation-accepted/event.be.json   # declares the id
+      telemetry.emit("telemetry:event:be:commons:response-invocation-accepted", { ... });
+  exceptions:
+  - >-
+    Test files are excluded: assertion code legitimately names events it is proving.
+  - >-
+    Strings that are not event-shaped (log levels like "info", single-word keys) never trigger the
+    check; the emit vocabulary with a non-event string is some other concern.
+  - >-
+    Inert until adoption, like every rule in this family.
+metadata:
+  aliases:
+  - CODER-TELEMETRY-RAW-STRING-EMIT-001
+  severity: 3
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_code

package/conventions/coder.bun/coder.bun.telemetry-source-binding.convention.yaml

@@ -0,0 +1,48 @@
+schema_version: 1.1.0
+rule_id: coder.bun.telemetry-source-binding
+kind: rule
+status: active
+name: Source Telemetry references resolve into the tracking plan
+statement: >-
+  A `// Telemetry:` reference in implementation source names a concrete telemetry URN that resolves
+  to a tracking-plan item under the telemetry root (REQUIRED).
+terms:
+- term_id: telemetry_reference
+  text: >-
+    a line comment of the form `// Telemetry: telemetry:{kind}:{plane}:{theme}:{artifact}[:{measure}]`
+    in a non-test source file, binding the file to the concrete item it emits.
+- term_id: tracking_plan_item
+  text: >-
+    a JSON registry entry under telemetry/<theme>/<artifact>/ whose id is the referenced URN.
+content:
+  summary: >-
+    The Telemetry: header is the source-to-telemetry traceability edge. Like Tested-By, it is a
+    promise the package can check: the URN must be well-formed and the registry must hold it.
+  normative_text: |
+    Implementation source that emits telemetry says so, by name, in a header comment. Two failures
+    are reported: a reference that is not a concrete telemetry URN (grammar), and a reference that
+    is grammatical but names no tracking-plan item (resolution). A header inside a string literal
+    is not a header. Test files are implementation's mirror, not implementation: they are excluded,
+    because a telemetry test legitimately names items while asserting them.
+  fix_hint: |
+    Bind the file to the item it emits, and keep the binding current when the plan renames:
+
+      // Telemetry: telemetry:event:be:commons:response-invocation-accepted
+      export function acceptResponse(response, telemetry) { ... }
+  exceptions:
+  - >-
+    The capability is inert until adopted (no telemetry root and no acceptance telemetry declaration
+    anywhere): an unadopting repository emits nothing, whichever profiles it runs.
+  - >-
+    The header is a line comment in source syntax (`//`). Block comments and markup attributes are
+    not parsed in this realization.
+metadata:
+  aliases:
+  - CODER-TELEMETRY-SOURCE-BINDING-001
+  severity: 2
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_code

package/conventions/coder.bun/coder.bun.telemetry-vendor-sdk.convention.yaml

@@ -0,0 +1,51 @@
+schema_version: 1.1.0
+rule_id: coder.bun.telemetry-vendor-sdk
+kind: rule
+status: active
+name: Telemetry vendor SDKs stay in infrastructure adapters
+statement: >-
+  A layered source file outside the integration layer and infrastructure directories MUST NOT
+  import a telemetry vendor SDK (REQUIRED).
+terms:
+- term_id: vendor_sdk
+  text: >-
+    an exporter or agent package: @opentelemetry/*, @sentry/*, @datadog/*, dd-trace, newrelic,
+    segment (bare or @segment/*), mixpanel (bare or @mixpanel/*), amplitude (bare or
+    @amplitude/*), @posthog/*, @statsig/*, @braze/*, @heap/*, @rudderstack/*.
+- term_id: adapter_location
+  text: >-
+    the integration layer, or an infrastructure/ directory — the outer ring where exporters are
+    wired to the neutral TelemetryPort.
+content:
+  summary: >-
+    Core depends only on a TelemetryPort. The moment a domain module imports an exporter, every
+    wagon behind it inherits the vendor, and the plan's exporter-neutrality promise is gone.
+  normative_text: |
+    Files carrying a layer segment (domain, application, presentation, integration, assembly) may
+    import a vendor SDK only when the layer is integration or the path sits under infrastructure/.
+    Type-only imports count: the coupling is real even when erased. Unlayered entrypoints (a
+    composition root, a script) are outside this rule — they wire adapters, they do not become one.
+  fix_hint: |
+    Depend on the port; adapt at the edge:
+
+      // domain/accept-response.ts — no SDK, only the port parameter
+      export function acceptResponse(response, telemetry: TelemetryPort) { telemetry.emit(...); }
+
+      // infrastructure/otel-adapter.ts — the SDK lives here and only here
+      import { metrics } from "@opentelemetry/api";
+  exceptions:
+  - >-
+    The integration layer and infrastructure/ directories are exempt by design: that is where the
+    adapter belongs.
+  - >-
+    Inert until adoption, like every rule in this family.
+metadata:
+  aliases:
+  - CODER-TELEMETRY-VENDOR-SDK-001
+  severity: 2
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_code

package/conventions/planner.telemetry/planner.telemetry.acceptance-decision.convention.yaml

@@ -0,0 +1,58 @@
+schema_version: 1.1.0
+rule_id: planner.telemetry.acceptance-decision
+kind: rule
+status: active
+name: Every acceptance makes an explicit telemetry decision
+statement: >-
+  Every acceptance declares telemetry with disposition required (naming at least one concrete
+  telemetry URN that resolves to a tracking-plan entry) or disposition not-applicable (with a
+  rationale), and every tracking-plan item's acceptance references resolve to declared acceptances
+  (REQUIRED).
+terms:
+- term_id: decision
+  text: >-
+    the acceptance's telemetry block: disposition plus, for required, concrete item lists
+    (events, metrics, traces, logs), or, for not-applicable, a rationale of at least 20 characters.
+- term_id: required_item
+  text: >-
+    a concrete telemetry URN an acceptance demands be observed emitted. It must exist as a
+    tracking-plan item under the telemetry root.
+content:
+  summary: >-
+    The decision removes the false choice between "test every debug log" and "have no observability
+    requirement". Not-applicable is a considered answer, not the absence of one.
+  normative_text: |
+    Once the capability is adopted, silence is not a disposition. An acceptance either requires
+    telemetry — and then each URN it lists must be a well-formed concrete URN present in the
+    tracking plan, or the requirement is unplannable — or it declares not-applicable with a
+    rationale long enough to be an answer (20 characters minimum). In the other direction, a
+    tracking-plan item that names an acceptance nothing declares is a dangling traceability link.
+    Resolution is checked in both directions; the lists are not required to be mirror images,
+    because an item may serve acceptances beyond those that first required it.
+  fix_hint: |
+    Decide, on every acceptance:
+
+      telemetry:
+        disposition: required
+        events: [telemetry:event:be:commons:response-invocation-accepted]
+
+      telemetry:
+        disposition: not-applicable
+        rationale: No externally useful observable outcome beyond the tested return value.
+  exceptions:
+  - >-
+    Diagnostic logs and internal spans are not automatically telemetry obligations. The decision is
+    per acceptance; nothing here requires a dedicated test for every debug-oriented record.
+  - >-
+    Inert until adoption: with no telemetry root and no acceptance telemetry declaration, this rule
+    emits nothing (see planner.telemetry.tracking-plan-schema).
+metadata:
+  aliases:
+  - TELEMETRY-ACCEPTANCE-DECISION-001
+  severity: 2
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: planner_telemetry_plan

package/conventions/planner.telemetry/planner.telemetry.logical-ownership.convention.yaml

@@ -0,0 +1,50 @@
+schema_version: 1.1.0
+rule_id: planner.telemetry.logical-ownership
+kind: rule
+status: active
+name: Concrete telemetry resolves to exactly one wagon-owned logical artifact
+statement: >-
+  Every concrete tracking-plan item's logical artifact is produced by exactly one wagon's
+  produce[] telemetry declaration, and the item's owner names that wagon (REQUIRED).
+terms:
+- term_id: ownership_declaration
+  text: >-
+    a wagon produce[] entry whose telemetry field (string or list) names the logical artifact
+    URN telemetry:{theme}:{artifact}. Ownership lives in the plan, not in the registry.
+- term_id: owner
+  text: >-
+    the tracking-plan item field naming the wagon slug accountable for the artifact. It must equal
+    the wagon whose produce[] declares the logical artifact.
+content:
+  summary: >-
+    A logical telemetry artifact with two producers is a coincidence waiting to diverge; with none,
+    it is emitted by code no plan stands behind. Both are plan defects, caught at the item.
+  normative_text: |
+    The registry does not grant ownership; it resolves against ownership the plan already declares.
+    For each item, the logical artifact must appear in exactly one wagon's produce[] telemetry, and
+    the item's owner field must equal that wagon's slug. Zero owners means no wagon has stood behind
+    the observable outcome; more than one means the emission contract has two authors with no
+    arbiter.
+  fix_hint: |
+    Declare the logical artifact on the producing wagon, and name that wagon as owner:
+
+      # plan/commons/_commons.yaml
+      produce:
+        - name: commons:response-invocation
+          contract: null
+          telemetry: telemetry:commons:response-invocation-accepted
+  exceptions:
+  - >-
+    Duplicate producers at the wagon level are also reported by planner.wagon.telemetry-filesystem
+    under the planner profile; this rule reports the same ambiguity at the item level under the
+    telemetry profile, so an adopting repository sees it whichever profile it runs.
+metadata:
+  aliases:
+  - TELEMETRY-LOGICAL-OWNERSHIP-001
+  severity: 2
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: planner_telemetry_plan

package/conventions/planner.telemetry/planner.telemetry.metric-cardinality.convention.yaml

@@ -0,0 +1,47 @@
+schema_version: 1.1.0
+rule_id: planner.telemetry.metric-cardinality
+kind: rule
+status: active
+name: High-cardinality identifiers are forbidden as metric labels
+statement: >-
+  Metric tracking-plan items declare only low- or medium-cardinality dimensions, and no dimension
+  names a property declared cardinality high (REQUIRED).
+terms:
+- term_id: dimension
+  text: >-
+    a metric label: an entry of the metric item's dimensions list, with a name and a declared
+    cardinality (low, medium or high).
+- term_id: high_cardinality_identifier
+  text: >-
+    a property whose distinct-value volume is unbounded or near-unbounded (request ids, user ids,
+    session tokens). Legal in event, log and trace properties where the plan justifies it; never as
+    a metric label.
+content:
+  summary: >-
+    A high-cardinality metric label is a backend outage with a YAML file attached: every distinct
+    value becomes a new time series. The plan is where that mistake is cheapest to catch.
+  normative_text: |
+    Metric dimensions must declare cardinality, and high is rejected — both when the dimension
+    itself says high and when the dimension names a property the item declares cardinality high.
+    The identifier still belongs in the plan: carry it as an event, log or trace property, where
+    cardinality is the point rather than a liability.
+  fix_hint: |
+    Keep the identifier, change the signal:
+
+      # telemetry/commons/response-invocation-accepted/metric.be.duration.json
+      "dimensions": [{ "name": "outcome", "cardinality": "low" }]
+      # response_id moves to the sibling event's properties, declared cardinality high.
+  exceptions:
+  - >-
+    Event, log and trace properties may declare cardinality high where justified; this rule judges
+    metric dimensions only.
+metadata:
+  aliases:
+  - TELEMETRY-METRIC-CARDINALITY-001
+  severity: 3
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: planner_telemetry_plan

package/conventions/planner.telemetry/planner.telemetry.tracking-plan-schema.convention.yaml

@@ -0,0 +1,75 @@
+schema_version: 1.1.0
+rule_id: planner.telemetry.tracking-plan-schema
+kind: rule
+status: active
+name: Tracking-plan items are versioned, path-mirrored registry entries
+statement: >-
+  Every JSON file under the telemetry root is one concrete tracking-plan item at
+  `telemetry/<theme>/<artifact>/{event|trace|metric|log}.<plane>[.<measure>].json`, shape-valid
+  against telemetry-plan.schema.json, with its id and logical artifact mirroring its path, a SemVer
+  version, and no concrete id declared twice (REQUIRED).
+terms:
+- term_id: tracking_plan_item
+  text: >-
+    one JSON file in the telemetry tree declaring a concrete observation: id, version,
+    logical_artifact, kind, plane, owner, purpose, acceptances, properties, required, and
+    optionally forbidden_properties and (for metrics) dimensions.
+- term_id: concrete_item
+  text: >-
+    a telemetry URN with kind and plane: telemetry:{kind}:{plane}:{theme}:{artifact}[:{measure}].
+    Metric items carry a measure segment; event, trace and log items never do.
+- term_id: logical_artifact
+  text: >-
+    the stable architectural identity of an observable outcome, telemetry:{theme}:{artifact}. Not
+    an exporter event; the concrete items under it are.
+- term_id: telemetry_root
+  text: >-
+    the versioned tracking-plan source of truth, `telemetry/` by default, configurable as
+    topology.telemetry_root in atdd-bun.yaml.
+content:
+  summary: >-
+    The telemetry tree is a registry, not a suggestion. Each file is schema-validated, and the
+    file's place in the tree is the authority for its identity: a renamed file or a hand-edited id
+    cannot drift apart silently.
+  normative_text: |
+    Local shape is the JSON Schema's job (telemetry-plan.schema.json): required identity fields, URN
+    grammar, SemVer core version, property declarations with classification and cardinality, and
+    metric dimensions that declare cardinality. Everything the Schema cannot see is this rule's
+    cross-artifact half: the file name's kind, plane and measure must match the declared fields; the
+    id must equal telemetry:{kind}:{plane}:{theme}:{artifact}[:{measure}] derived from the path; the
+    logical artifact must equal telemetry:{theme}:{artifact} from the path; every name in `required`
+    must be declared in `properties`; and no two files may declare the same concrete id.
+  fix_hint: |
+    Name the file for what it is and let the identity follow the path:
+
+      telemetry/commons/response-invocation-accepted/event.be.json
+      {
+        "id": "telemetry:event:be:commons:response-invocation-accepted",
+        "version": "1.0.0",
+        "logical_artifact": "telemetry:commons:response-invocation-accepted",
+        "kind": "event", "plane": "be", "owner": "commons",
+        "purpose": "Records that a response invocation passed acceptance so ingress health can be audited.",
+        "acceptances": ["acc:commons:E001-UNIT-001"],
+        "properties": { "response_id": { "type": "string", "classification": "internal", "cardinality": "high" } },
+        "required": ["response_id"],
+        "forbidden_properties": ["raw_payload", "secret", "prompt"]
+      }
+  exceptions:
+  - >-
+    The capability is inert until adopted. With no telemetry root and no acceptance telemetry
+    declaration anywhere, this rule emits nothing: upgrading the package must not fail a repository
+    that has not opted in. Adoption is a positive act — creating the tree, or making the first
+    acceptance decision.
+  - >-
+    The tree holds only tracking-plan items. Free-form JSON (notes, indexes, generated bundles)
+    does not belong under the telemetry root; every .json file is judged as an item.
+metadata:
+  aliases:
+  - TELEMETRY-PLAN-SCHEMA-001
+  severity: 2
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: planner_telemetry_plan

package/conventions/tester.bun/tester.bun.telemetry-captured-sink.convention.yaml

@@ -0,0 +1,47 @@
+schema_version: 1.1.0
+rule_id: tester.bun.telemetry-captured-sink
+kind: rule
+status: active
+name: Telemetry tests assert on a captured sink
+statement: >-
+  A telemetry test contains an assertion on the emission itself — `toHaveBeenCalled[With|Times]`, or
+  an expectation on `.emit` / `.emitted` / `.capture` / `.track` / `.record` (REQUIRED).
+terms:
+- term_id: captured_sink
+  text: >-
+    the spy, mock or captured array the emitter writes to: the thing whose CONTENT is the emission.
+    A return value is not a sink.
+- term_id: telemetry_test
+  text: >-
+    a test file with a Telemetry: header, a TELEMETRY/EVENT/METRIC URN kind segment, or
+    *.telemetry.test.* colocation.
+content:
+  summary: >-
+    Same obligation as tester.bun.telemetry-emit, carried into the telemetry profile and joined
+    with the exact-identity requirement: the event is the point, and only the sink saw it fire.
+  normative_text: |
+    A telemetry test that checks a return value has proven the function ran. It has not proven the
+    item fired — and dashboards, alerts and downstream analytics are built on the emission. The
+    predicate is deliberately the emission-assertion vocabulary, not a data-flow analysis: it names
+    what a test must contain, not what the runtime did.
+  fix_hint: |
+    Capture the emitter, assert on it:
+
+      const emit = mock(() => {});
+      acceptResponse({ id: "r-1" }, { emit });
+      expect(emit).toHaveBeenCalledWith("telemetry:event:be:commons:response-invocation-accepted", { response_id: "r-1" });
+  exceptions:
+  - >-
+    Only telemetry-identified tests are scanned; the tester profile's own rule governs the rest.
+  - >-
+    Inert until adoption, like every rule in this family.
+metadata:
+  aliases:
+  - TESTER-TELEMETRY-CAPTURED-SINK-001
+  severity: 3
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_test

package/conventions/tester.bun/tester.bun.telemetry-identity-assertion.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.1.0
+rule_id: tester.bun.telemetry-identity-assertion
+kind: rule
+status: active
+name: Telemetry tests assert the exact item identity
+statement: >-
+  Every concrete telemetry URN a telemetry test claims in its `// Telemetry:` header appears in
+  the test's code as an assertion string; a telemetry test with no header asserts at least one
+  concrete telemetry URN (REQUIRED).
+terms:
+- term_id: exact_identity
+  text: >-
+    the concrete telemetry URN, verbatim, inside a string literal of the test. Not a prefix, not a
+    captured-anything matcher, not a comment.
+content:
+  summary: >-
+    A test that mocks an emitter and asserts "called with anything" proves emission happened, not
+    that the planned item is the one that fired. Renames and copy-paste drift hide exactly there.
+  normative_text: |
+    The claimed URNs are the test's Telemetry: headers; each must appear in the comment-masked
+    source as a quoted string, so that the assertion and the plan cannot silently diverge. A
+    telemetry test identified only by URN segment or colocation must carry at least one concrete
+    telemetry: URN in code. When generated contracts ship, the contract identifier satisfies this
+    the same way.
+  fix_hint: |
+    Name the item in the assertion itself:
+
+      expect(emit).toHaveBeenCalledWith("telemetry:event:be:commons:response-invocation-accepted", { response_id: "r-1" });
+  exceptions:
+  - >-
+    Comments do not assert: a URN that appears only in the header or a comment does not satisfy
+    this rule.
+  - >-
+    Inert until adoption, like every rule in this family.
+metadata:
+  aliases:
+  - TESTER-TELEMETRY-IDENTITY-ASSERTION-001
+  severity: 3
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_test

package/conventions/tester.bun/tester.bun.telemetry-required-item-coverage.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.1.0
+rule_id: tester.bun.telemetry-required-item-coverage
+kind: rule
+status: active
+name: Every required telemetry item has a telemetry test
+statement: >-
+  Every concrete telemetry item an acceptance requires is bound by at least one test file's
+  `// Telemetry:` header (REQUIRED).
+terms:
+- term_id: required_item
+  text: >-
+    a concrete telemetry URN listed by an acceptance whose telemetry disposition is required and
+    that exists in the tracking plan.
+content:
+  summary: >-
+    The evidence leg of the traceability tripod: planned, implemented, tested. The coder rule
+    binds the implementation; this binds the proof. A required item no test covers is a plan
+    nobody can rely on.
+  normative_text: |
+    Required items are collected from acceptance decisions; test bindings from every Telemetry:
+    header in test files. Their difference is reported at the tracking-plan item's own file.
+    Unresolvable required URNs belong to the acceptance-decision rule and are not double-reported.
+  fix_hint: |
+    Give the item its proof:
+
+      // tests/.../accept-response.telemetry.test.ts
+      // Acceptance: acc:commons:E001-UNIT-001
+      // Telemetry: telemetry:metric:be:commons:response-invocation-accepted:duration
+  exceptions:
+  - >-
+    Diagnostic logs and internal spans an acceptance does not require need no dedicated test —
+    only required items are covered by this closure.
+  - >-
+    Inert until adoption, like every rule in this family.
+metadata:
+  aliases:
+  - TESTER-TELEMETRY-REQUIRED-ITEM-COVERAGE-001
+  severity: 2
+  # strict: atdd-bun fails on every finding; it has no advisory mode and no ratchet baseline.
+  disposition: strict
+  introduced_in: 0.7.0
+implementation:
+  type: validator
+  ref: bun_telemetry_test