@afokapu/atdd-bun 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/planner-schemas/acceptance.schema.json

@@ -323,6 +323,57 @@
       }
     },
 
+    "telemetry": {
+      "type": "object",
+      "description": "The acceptance's explicit telemetry decision. `required` names the concrete telemetry items whose emission this acceptance must observe; `not-applicable` records why nothing beyond the tested return value is externally useful. This block supersedes the DESCRIPTIVE half of `signal` (metrics/traces/logs/events); it does not touch the EXECUTABLE bar `signal.metric` + `signal.threshold`, which is a gate, not telemetry.",
+      "$comment": "Introduced with the telemetry tracking-plan profile. Every acceptance in an adopting repository carries exactly one of the two dispositions — the false choice between 'test every debug log' and 'have no observability requirement' is what this block removes. Items listed here must resolve to tracking-plan files under telemetry/ (planner.telemetry.acceptance-decision).",
+      "required": ["disposition"],
+      "additionalProperties": false,
+      "properties": {
+        "disposition": {
+          "type": "string",
+          "enum": ["required", "not-applicable"]
+        },
+        "rationale": {
+          "type": "string",
+          "minLength": 20,
+          "description": "Required with disposition: not-applicable — why no observable outcome beyond the tested return value is externally useful."
+        },
+        "events": {
+          "type": "array",
+          "minItems": 1,
+          "items": {"$ref": "#/definitions/telemetry_event_urn"}
+        },
+        "metrics": {
+          "type": "array",
+          "minItems": 1,
+          "items": {"$ref": "#/definitions/telemetry_metric_urn"}
+        },
+        "traces": {
+          "type": "array",
+          "minItems": 1,
+          "items": {"$ref": "#/definitions/telemetry_trace_urn"}
+        },
+        "logs": {
+          "type": "array",
+          "minItems": 1,
+          "items": {"$ref": "#/definitions/telemetry_log_urn"}
+        }
+      },
+      "allOf": [
+        {
+          "$comment": "not-applicable forbids item lists: an acceptance cannot simultaneously require nothing and require something.",
+          "if": {"properties": {"disposition": {"const": "not-applicable"}}, "required": ["disposition"]},
+          "then": {"not": {"anyOf": [{"required": ["events"]}, {"required": ["metrics"]}, {"required": ["traces"]}, {"required": ["logs"]}]}}
+        },
+        {
+          "$comment": "required declares at least one concrete item; resolution against the tracking plan is a cross-artifact validator concern.",
+          "if": {"properties": {"disposition": {"const": "required"}}, "required": ["disposition"]},
+          "then": {"anyOf": [{"required": ["events"]}, {"required": ["metrics"]}, {"required": ["traces"]}, {"required": ["logs"]}]}
+        }
+      ]
+    },
+
     "metadata": {
       "type": "object",
       "required": ["wagon"],
@@ -389,8 +440,26 @@
             "author": {"type": "string"},
             "created": {"type": "string"}
           }
-        }
+        },
+        "telemetry": {"$ref": "#/properties/telemetry"}
       }
+    },
+    "telemetry_event_urn": {
+      "$comment": "Concrete telemetry URNs accepted in an acceptance's telemetry decision. Same grammar as telemetry-plan.schema.json's id, where path and ownership coherence are additionally checked.",
+      "type": "string",
+      "pattern": "^telemetry:event:(ui|ux|be|nw|db|st|tm|sc|au|fn|if):[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"
+    },
+    "telemetry_trace_urn": {
+      "type": "string",
+      "pattern": "^telemetry:trace:(ui|ux|be|nw|db|st|tm|sc|au|fn|if):[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"
+    },
+    "telemetry_log_urn": {
+      "type": "string",
+      "pattern": "^telemetry:log:(ui|ux|be|nw|db|st|tm|sc|au|fn|if):[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"
+    },
+    "telemetry_metric_urn": {
+      "type": "string",
+      "pattern": "^telemetry:metric:(ui|ux|be|nw|db|st|tm|sc|au|fn|if):[a-z][a-z0-9-]*:[a-z][a-z0-9-]*:(latency|duration|throughput|error_rate|success_rate|count|size|age|staleness|freshness)$"
     }
   }
 }

package/planner-schemas/telemetry-plan.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Telemetry Tracking-Plan Item Schema",
+  "description": "Validates one concrete telemetry tracking-plan file under telemetry/<theme>/<artifact>/{kind}.{plane}[.{measure}].json. Local shape only: path mirroring, kind/plane/measure coherence with the file name, wagon ownership resolution and acceptance linkage are cross-artifact validator concerns (src/telemetry-plan.ts).",
+  "$comment": "Shipped by the telemetry profile (planner_telemetry_plan). The capability is deliberately inert until a repository adopts it: no telemetry/ root and no acceptance telemetry declaration means no findings. `signal` in acceptance.schema.json keeps the executable bar (signal.metric + signal.threshold); the descriptive arrays it also carries are superseded by the acceptance `telemetry` block and by this registry, and are not renamed here — that migration is a separate, documented step.",
+  "type": "object",
+  "required": ["id", "version", "logical_artifact", "kind", "plane", "owner", "purpose", "acceptances", "properties"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^telemetry:(event|trace|metric|log):(ui|ux|be|nw|db|st|tm|sc|au|fn|if):[a-z][a-z0-9-]*:[a-z][a-z0-9-]*(?::(latency|duration|throughput|error_rate|success_rate|count|size|age|staleness|freshness))?$",
+      "description": "Concrete telemetry URN: telemetry:{kind}:{plane}:{theme}:{artifact}[:{measure}]. Must mirror the file's path and name; the validator checks that coherence."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$",
+      "description": "SemVer core for this item's contract. Changing properties, required or forbidden_properties is a contract change and must bump it."
+    },
+    "logical_artifact": {
+      "type": "string",
+      "pattern": "^telemetry:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
+      "description": "The stable architectural identity of the observable outcome: telemetry:{theme}:{artifact}. Not an exporter event. Must be owned by exactly one wagon's produce[] telemetry entry."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["event", "trace", "metric", "log"]
+    },
+    "plane": {
+      "type": "string",
+      "enum": ["ui", "ux", "be", "nw", "db", "st", "tm", "sc", "au", "fn", "if"]
+    },
+    "measure": {
+      "type": "string",
+      "enum": ["latency", "duration", "throughput", "error_rate", "success_rate", "count", "size", "age", "staleness", "freshness"],
+      "description": "Required for metric items (and only metric items); must match the measure segment of the file name and of the id."
+    },
+    "instrument": {
+      "type": "string",
+      "enum": ["counter", "gauge", "histogram", "summary"],
+      "description": "Metric instrument type per the telemetry kind vocabulary."
+    },
+    "unit": {
+      "type": "string",
+      "description": "Unit of measure for metric items (ms, s, bytes, percent, count)."
+    },
+    "owner": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The wagon slug that owns the logical artifact. The validator checks it equals the wagon whose produce[] declares the logical artifact."
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 20,
+      "description": "The question this item answers. A tracking plan is read by people deciding what to alert and dashboard on; an item that cannot state its question is not planned."
+    },
+    "acceptances": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^acc:[A-Za-z0-9._:-]+$",
+        "description": "Acceptance URNs that require this item. Each must resolve to a declared acceptance in the plan."
+      }
+    },
+    "properties": {
+      "type": "object",
+      "description": "The fields this item may carry, by name. `required` names must all appear here.",
+      "additionalProperties": {
+        "$ref": "#/definitions/property"
+      }
+    },
+    "required": {
+      "type": "array",
+      "items": {"type": "string", "minLength": 1},
+      "description": "Property names that must be present on every emission."
+    },
+    "forbidden_properties": {
+      "type": "array",
+      "items": {"type": "string", "minLength": 1},
+      "description": "Property names that must never be attached to this item (raw payloads, secrets, prompts)."
+    },
+    "dimensions": {
+      "type": "array",
+      "description": "Metric labels. Every dimension declares cardinality; high cardinality is forbidden for metrics — use an event, log or trace property instead.",
+      "items": {
+        "type": "object",
+        "required": ["name", "cardinality"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {"type": "string", "minLength": 1},
+          "cardinality": {"type": "string", "enum": ["low", "medium", "high"]}
+        }
+      }
+    },
+    "timing": {
+      "type": "array",
+      "description": "Critical timing semantics a telemetry test bound to this item must exercise: post-commit (emitted only after the transaction commits), absent-after-rollback (never emitted when the transaction rolls back), correlation-across-async (correlation context continues across an async handoff). Declaring a semantic is what makes it testable; a test that cannot exercise it should not claim the item.",
+      "items": {"type": "string", "enum": ["post-commit", "absent-after-rollback", "correlation-across-async"]}
+    }
+  },
+  "definitions": {
+    "property": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["string", "integer", "number", "boolean"]
+        },
+        "classification": {
+          "type": "string",
+          "enum": ["internal", "external", "pii"],
+          "description": "Who may see the value. PII forces a justification nobody has to reconstruct later."
+        },
+        "cardinality": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "description": "Distinct-value volume. High cardinality is legal in event, log and trace properties where justified; never as a metric label."
+        },
+        "allowed_values": {
+          "type": "array",
+          "minItems": 1,
+          "items": {"type": ["string", "number", "boolean"]},
+          "description": "Closed vocabulary for this property."
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/relationships.yaml

@@ -81,6 +81,11 @@ nodes:
   - coder.bun.security-sql-injection
   - coder.bun.station-master-interlocking-routing
   - coder.bun.station-master-journey-routing
+  - coder.bun.telemetry-forbidden-properties
+  - coder.bun.telemetry-implementation-binding
+  - coder.bun.telemetry-raw-string-emit
+  - coder.bun.telemetry-source-binding
+  - coder.bun.telemetry-vendor-sdk
   - coder.bun.wagon-honours-its-contract
   - coder.htmx.fragment-escapes-interpolation
   - coder.htmx.swap-no-inline-handler
@@ -220,6 +225,10 @@ nodes:
   - planner.steps.linguistic-patterns
   - planner.steps.sequence
   - planner.subject.invariants
+  - planner.telemetry.acceptance-decision
+  - planner.telemetry.logical-ownership
+  - planner.telemetry.metric-cardinality
+  - planner.telemetry.tracking-plan-schema
   - planner.theme.definition
   - planner.theme.must-be-canonical
   - planner.theme.theme-zero-mandatory
@@ -310,7 +319,12 @@ nodes:
   - tester.bun.security-input
   - tester.bun.smoke-no-collaborator-substitution
   - tester.bun.smoke-observable-assertion
+  - tester.bun.telemetry-captured-sink
   - tester.bun.telemetry-emit
+  - tester.bun.telemetry-identity-assertion
+  - tester.bun.telemetry-required-item-coverage
+  - tester.bun.telemetry-test-binding
+  - tester.bun.telemetry-timing-semantics
   - tester.bun.test-carries-urn-identity
   - tester.bun.test-imports-bun-test
   - tester.bun.test-isolation-no-live-state
@@ -5012,3 +5026,163 @@ edges:
     target_ref: atdd-bun.planner.identity-required
     type: enables
     origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the tracking-plan tree is the versioned realization of the telemetry URN-to-filesystem mapping
+    source_ref: planner.telemetry.tracking-plan-schema
+    strength: important
+    target_ref: planner.wagon.telemetry-filesystem
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "a tracking-plan item's path mirrors its concrete telemetry identity"
+    source_ref: planner.telemetry.tracking-plan-schema
+    strength: important
+    target_ref: planner.artifact-naming.path-mirrors-identity
+    type: follows
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "wagon produce[] telemetry entries are the ownership declarations items resolve against"
+    source_ref: planner.telemetry.logical-ownership
+    strength: important
+    target_ref: planner.wagon.produce-consume-artifacts
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the disposition decision governs the telemetry URNs an acceptance may declare
+    source_ref: planner.telemetry.acceptance-decision
+    strength: important
+    target_ref: planner.acceptance.signal-telemetry-naming
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "metric measures and dimensions inherit the naming rule's cardinality discipline"
+    source_ref: planner.telemetry.metric-cardinality
+    strength: important
+    target_ref: planner.acceptance.signal-telemetry-naming
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "a source Telemetry: reference resolves against the tracking-plan registry"
+    source_ref: coder.bun.telemetry-source-binding
+    strength: important
+    target_ref: planner.telemetry.tracking-plan-schema
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: only telemetry an acceptance has decided and the plan declares may be emitted by name
+    source_ref: coder.bun.telemetry-raw-string-emit
+    strength: important
+    target_ref: planner.telemetry.acceptance-decision
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: start_to_start
+    reason: vendor SDKs stay in infrastructure adapters as framework imports stay out of domain
+    source_ref: coder.bun.telemetry-vendor-sdk
+    strength: important
+    target_ref: coder.bun.commons-domain-no-framework-import
+    type: runs_alongside
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the forbidden-property list comes from the tracking-plan item
+    source_ref: coder.bun.telemetry-forbidden-properties
+    strength: important
+    target_ref: planner.telemetry.tracking-plan-schema
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the binding obligation runs on the same header the source rule resolves
+    source_ref: coder.bun.telemetry-implementation-binding
+    strength: important
+    target_ref: coder.bun.telemetry-source-binding
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: required items come from acceptance decisions
+    source_ref: coder.bun.telemetry-implementation-binding
+    strength: important
+    target_ref: planner.telemetry.acceptance-decision
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: a bound test must point at the acceptance whose decision requires the item
+    source_ref: tester.bun.telemetry-test-binding
+    strength: important
+    target_ref: planner.telemetry.acceptance-decision
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the captured-sink obligation carries the emission assertion into the telemetry profile
+    source_ref: tester.bun.telemetry-captured-sink
+    strength: important
+    target_ref: tester.bun.telemetry-emit
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: exact identity extends the emission assertion from any-call to the named item
+    source_ref: tester.bun.telemetry-identity-assertion
+    strength: important
+    target_ref: tester.bun.telemetry-emit
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: telemetry items follow the acceptance-has-test discipline
+    source_ref: tester.bun.telemetry-required-item-coverage
+    strength: important
+    target_ref: traceability.plan.executable-acceptance-has-test
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: timing semantics are declared on the tracking-plan item
+    source_ref: tester.bun.telemetry-timing-semantics
+    strength: important
+    target_ref: planner.telemetry.tracking-plan-schema
+    type: requires
+    origin: "@afokapu/atdd-bun"

package/src/agent.ts

@@ -7,10 +7,14 @@ const version = (await Bun.file(join(root, "package.json")).json() as { version:
 const render = async (path: string) => (await readFile(join(root, "templates/agents", path), "utf8")).replace("{{VERSION}}", version);
 // .agents/skills is the vendor-neutral Agent Skills path (Codex, Copilot, Cursor, Gemini CLI, …); .claude/skills is Claude Code's.
 const skillPaths = [".agents/skills/atdd/SKILL.md", ".claude/skills/atdd/SKILL.md"];
+// AGENTS.md is read by Codex, Cursor and most agents; CLAUDE.md by Claude Code. Both carry the same block.
+export const instructionPaths = ["AGENTS.md", "CLAUDE.md"];
 const block = /<!-- atdd-bun:start[\s\S]*?<!-- atdd-bun:end -->\n?/;
+/** `current` with the managed block replaced, or appended after at least one blank line; `current` itself is kept. */
+const withBlock = (current: string, managed: string) => block.test(current) ? current.replace(block, managed) : `${current}${current ? "\n\n".slice(current.match(/\n{0,2}$/)![0].length) : ""}${managed}`;
 
-/** Write the ATDD skill for every agent and a managed pointer block in AGENTS.md. Existing files and an
- * existing block are kept unless `replace`; the rest of AGENTS.md is never touched. */
+/** Write the ATDD skill for every agent and a managed pointer block in AGENTS.md and CLAUDE.md. Existing files
+ * and an existing block are kept unless `replace`; the rest of each instruction file is never touched. */
 export async function agentInit(repo = process.cwd(), replace = false) {
   const written: string[] = [], kept: string[] = [];
   for (const path of skillPaths) {
@@ -18,14 +22,17 @@ export async function agentInit(repo = process.cwd(), replace = false) {
     if (existsSync(output) && !replace) { kept.push(output); continue; }
     await mkdir(dirname(output), { recursive: true }); await writeFile(output, await render("atdd/SKILL.md")); written.push(output);
   }
-  const agents = join(repo, "AGENTS.md"), current = existsSync(agents) ? await readFile(agents, "utf8") : "", managed = await render("AGENTS.block.md");
-  if (block.test(current) && !replace) kept.push(agents);
-  else { await writeFile(agents, block.test(current) ? current.replace(block, managed) : current + (current && !current.endsWith("\n\n") ? (current.endsWith("\n") ? "\n" : "\n\n") : "") + managed); written.push(agents); }
+  const managed = await render("AGENTS.block.md");
+  for (const path of instructionPaths) {
+    const file = join(repo, path), current = existsSync(file) ? await readFile(file, "utf8") : "";
+    if (block.test(current) && !replace) { kept.push(file); continue; }
+    await writeFile(file, withBlock(current, managed)); written.push(file);
+  }
   if (!written.length) return { ok: false, message: `${kept.join(", ")} exist; use --replace` };
   return { ok: true, message: written.join("\n") };
 }
 export async function agentStatus(repo = process.cwd()) {
-  const agents = join(repo, "AGENTS.md"), missing = skillPaths.map(path => join(repo, path)).filter(path => !existsSync(path));
-  if (!existsSync(agents) || !block.test(await readFile(agents, "utf8"))) missing.push(`${agents} (atdd-bun block)`);
-  return { ok: !missing.length, message: missing.length ? `missing: ${missing.join(", ")}` : [...skillPaths, "AGENTS.md"].map(path => join(repo, path)).join("\n") };
+  const missing = skillPaths.map(path => join(repo, path)).filter(path => !existsSync(path));
+  for (const path of instructionPaths) { const agents = join(repo, path); if (!existsSync(agents) || !block.test(await readFile(agents, "utf8"))) missing.push(`${agents} (atdd-bun block)`); }
+  return { ok: !missing.length, message: missing.length ? `missing: ${missing.join(", ")}` : [...skillPaths, ...instructionPaths].map(path => join(repo, path)).join("\n") };
 }

package/src/enforce.ts

@@ -1,9 +1,10 @@
+import { existsSync } from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { topologyFor } from "./topology";
 
-export type Profile = "traceability" | "topology" | "docs" | "planner" | "coder" | "tester" | "security" | "architecture" | "metrics" | "runtime" | "interlocking" | "htmx" | "design" | "all";
+export type Profile = "traceability" | "topology" | "docs" | "planner" | "telemetry" | "coder" | "tester" | "security" | "architecture" | "metrics" | "runtime" | "interlocking" | "htmx" | "design" | "all";
 
 export type Violation = {
   rule_id: string;
@@ -26,6 +27,7 @@ const profiles: Record<Exclude<Profile, "all">, string[]> = {
   topology: ["atdd_topology"],
   docs: ["planner_docs_capability"],
   planner: ["planner_plan_integrity", "planner_schema_validation", "planner_static_validators", "atdd_topology"],
+  telemetry: ["planner_telemetry_plan", "bun_telemetry_code", "bun_telemetry_test"],
   coder: ["bun_green_traceability_detector", "bun_clean_architecture_detector", "bun_ts_metrics_detector", "bun_fullstack_detector", "bun_design_system_detector", "bun_responsive_detector", "atdd_topology"],
   tester: ["bun_tester_discipline_detector", "htmx_e2e_detector", "atdd_topology"],
   security: ["bun_security_hygiene_detector"],
@@ -37,8 +39,27 @@ const profiles: Record<Exclude<Profile, "all">, string[]> = {
   design: ["bun_design_system_detector", "bun_responsive_detector"],
 };
 
+type ConcreteProfile = Exclude<Profile, "all">;
+/** Every profile but `all`. */
+export const concreteProfiles = Object.keys(profiles) as ConcreteProfile[];
 /** Profile names accepted by the CLI and public integrations. */
-export const profileNames = [...Object.keys(profiles), "all"] as Profile[];
+export const profileNames = [...concreteProfiles, "all"] as Profile[];
+
+/**
+ * The profiles the operator has activated: `profiles:` in atdd-bun.yaml, or every profile when absent. A legacy
+ * repository can adopt enforcement gradually by listing only what it is ready for. `all`, the hooks and the
+ * generated CI run exactly these; naming a profile explicitly still runs it. An unknown name or an empty list is
+ * a configuration error, never a silent "run nothing".
+ */
+export async function enabledProfiles(root = process.cwd()): Promise<ConcreteProfile[]> {
+  const file = join(resolve(root), "atdd-bun.yaml");
+  const listed = existsSync(file) ? (Bun.YAML.parse(await readFile(file, "utf8")) as { profiles?: unknown } | null)?.profiles : undefined;
+  if (listed === undefined) return concreteProfiles;
+  if (!Array.isArray(listed) || !listed.length) throw new Error("atdd-bun.yaml profiles must be a non-empty list of profile names");
+  const unknown = listed.filter(name => !concreteProfiles.includes(name));
+  if (unknown.length) throw new Error(`atdd-bun.yaml profiles lists unknown profile(s): ${unknown.join(", ")}; known: ${concreteProfiles.join(", ")}`);
+  return [...new Set(listed as ConcreteProfile[])];
+}
 
 const packageRoot = resolve(import.meta.dir, "..");
 const detectorRoot = join(packageRoot, "detectors");
@@ -120,8 +141,12 @@ export async function enforce(config: EnforcementConfig = {}): Promise<Violation
   const root = resolve(config.root ?? process.cwd());
   const scanRoots = (config.scanRoots?.length ? config.scanRoots : [root]).map((path) => resolve(root, path));
   const excludes = ["node_modules", ".git", ".atdd", ...(config.excludes ?? [])];
+  // `all` means every profile the operator activated; explicitly named profiles run as asked. The operator's list
+  // is validated on every run, so a misspelled atdd-bun.yaml fails whichever profile is requested.
+  const requested = config.profiles ?? ["all"], enabled = await enabledProfiles(root);
+  const selected = requested.includes("all") ? [...new Set([...requested.filter(p => p !== "all"), ...enabled])] : requested;
   const results = await Promise.all(
-    implementationsFor(config.profiles).map((implementation) => runImplementation(implementation, { scanRoots, excludes })),
+    implementationsFor(selected).map((implementation) => runImplementation(implementation, { scanRoots, excludes })),
   );
   return results.flat().sort((left, right) =>
     left.rule_id.localeCompare(right.rule_id) || left.file.localeCompare(right.file) || left.line - right.line,

package/src/hooks.ts

@@ -1,7 +1,7 @@
 import { chmod, mkdir, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { enforce } from "./enforce";
+import { enabledProfiles, enforce } from "./enforce";
 import { topologyFor } from "./topology";
 
 export type WorktreePolicy = { enabled: boolean; root: string; primary_directory: string; primary_branch: string; require_linked_worktree: boolean };
@@ -19,7 +19,7 @@ const isRegistry = (cfg: HookPolicy, path: string) => cfg.registry_paths.some(pa
 const stagedStats = async (root: string) => (await git(root, ["diff", "--cached", "--numstat", "--no-renames"])).out.split("\n").filter(Boolean).map(row => { const [added, removed, ...path] = row.split("\t"); return { added: Number(added) || 0, removed: Number(removed) || 0, path: path.join("\t") }; });
 
 export async function policy(root: string): Promise<HookPolicy> { const file = join(root, "atdd-bun.yaml"); if (!existsSync(file)) return defaultHookPolicy; const data = Bun.YAML.parse(await readFile(file, "utf8")) as Record<string, unknown>; const configuredWorktrees = data?.worktrees && typeof data.worktrees === "object" && !Array.isArray(data.worktrees) ? data.worktrees as Record<string, unknown> : {}; return { ...defaultHookPolicy, ...Object.fromEntries(Object.entries(data ?? {}).filter(([key, value]) => key in defaultHookPolicy && key !== "worktrees" && typeof value === typeof (defaultHookPolicy as any)[key])), protected_branches: strings(data?.protected_branches) ?? defaultHookPolicy.protected_branches, registry_paths: strings(data?.registry_paths) ?? defaultHookPolicy.registry_paths, worktrees: { ...defaultWorktreePolicy, ...Object.fromEntries(Object.entries(configuredWorktrees).filter(([key, value]) => key in defaultWorktreePolicy && typeof value === typeof (defaultWorktreePolicy as any)[key])) } }; }
-async function validation(root: string, changed: string[], full: boolean, registryChanged = false) { const profiles: any[] = [], topology = await topologyFor(root); if (registryChanged || changed.some(path => path.startsWith(`${topology.planRoot}/`)) || changed.includes("atdd-bun.yaml")) profiles.push("planner", "traceability"); if (changed.some(path => /\.(?:[cm]?[jt]sx?|html)$/.test(path))) profiles.push("coder", "tester"); if (changed.includes("atdd-bun.yaml") || changed.some(path => /\.ya?ml$/.test(path))) profiles.push("topology"); if (!profiles.length) return { ok: true, message: "no affected area" }; try { const findings = await enforce({ root, profiles: full ? ["all"] : [...new Set(profiles)] }); return findings.length ? bad(findings.map(f => `${f.rule_id}: ${f.file}`).join("\n")) : { ok: true, message: "validation clean" }; } catch (error) { return bad(`Bun enforcer resolution failed: ${String(error)}`); } }
+async function validation(root: string, changed: string[], full: boolean, registryChanged = false) { const profiles: any[] = [], topology = await topologyFor(root); if (registryChanged || changed.some(path => path.startsWith(`${topology.planRoot}/`)) || changed.includes("atdd-bun.yaml")) profiles.push("planner", "traceability"); if (changed.some(path => /\.(?:[cm]?[jt]sx?|html)$/.test(path))) profiles.push("coder", "tester"); if (changed.includes("atdd-bun.yaml") || changed.some(path => /\.ya?ml$/.test(path))) profiles.push("topology"); if (!profiles.length) return { ok: true, message: "no affected area" }; try { const enabled = await enabledProfiles(root), selected = full ? ["all" as const] : [...new Set(profiles)].filter(profile => enabled.includes(profile)); if (!selected.length) return { ok: true, message: "no activated profile covers the affected area" }; const findings = await enforce({ root, profiles: selected }); return findings.length ? bad(findings.map(f => `${f.rule_id}: ${f.file}`).join("\n")) : { ok: true, message: "validation clean" }; } catch (error) { return bad(`Bun enforcer resolution failed: ${String(error)}`); } }
 
 const inside = (parent: string, child: string) => { const path = relative(parent, child); return path === "" || (path !== ".." && !path.startsWith("../") && !path.startsWith("..\\")); };
 async function primaryRoot(root: string): Promise<string | null> { const result = await git(root, ["rev-parse", "--git-common-dir"]); if (result.code) return null; return dirname(resolve(root, result.out)); }

package/src/index.ts

@@ -5,6 +5,8 @@ export type { DocumentationCheck, DocumentationDeclaration, DocumentationRender,
 export { loadPlan, traceabilityPlan, validatePlan } from "./planner-kernel";
 export type { PlanArtifact, PlanFinding, PlanGraph, PlanKind } from "./planner-kernel";
 export { validateStaticPlannerConventions } from "./planner-validators";
+export { validateTelemetryPlan, loadTelemetryFiles, telemetryDecisionOf, CONCRETE_URN } from "./telemetry-plan";
+export type { TelemetryPlanItem, TelemetryFile } from "./telemetry-plan";
 export { PLANNER_SCHEMA_RULE_ID, validatePlannerSchemas } from "./planner-schema-validator";
 export { defaultHookPolicy, hookEvents, hooksStatus, installHooks, runHook, uninstallHooks } from "./hooks";
 export type { HookEvent, HookPolicy } from "./hooks";

package/src/integrity.ts

@@ -1,6 +1,8 @@
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
+import { instructionPaths } from "./agent";
+import { concreteProfiles } from "./enforce";
 import { defaultHookPolicy, type HookPolicy } from "./hooks";
 
 /**
@@ -95,15 +97,17 @@ async function checkGenerated(root: string, packageRoot: string): Promise<Integr
   await same(WORKFLOW, "templates/github/atdd-bun.yml", "bun run atdd-bun ci init --replace");
   for (const skill of SKILLS) await same(skill, "templates/agents/atdd/SKILL.md", "bun run atdd-bun agent init --replace");
   await same(relative(root, await testFilePath(root)), "templates/agents/atdd-bun.integrity.test.ts", "bun run atdd-bun integrity init --replace");
-  const agents = existsSync(join(root, "AGENTS.md")) ? await readFile(join(root, "AGENTS.md"), "utf8") : "";
-  const block = agents.match(BLOCK)?.[0], canonical = (await readFile(join(packageRoot, "templates/agents/AGENTS.block.md"), "utf8")).match(BLOCK)![0];
-  if (!block) findings.push({ file: "AGENTS.md", detail: "is missing the atdd-bun block", restore: "bun run atdd-bun agent init --replace" });
-  else if (unstamp(block) !== unstamp(canonical)) findings.push({ file: "AGENTS.md", detail: "atdd-bun block was edited", restore: "bun run atdd-bun agent init --replace" });
+  const canonical = (await readFile(join(packageRoot, "templates/agents/AGENTS.block.md"), "utf8")).match(BLOCK)![0];
+  for (const file of instructionPaths) {
+    const agents = existsSync(join(root, file)) ? await readFile(join(root, file), "utf8") : "", block = agents.match(BLOCK)?.[0];
+    if (!block) findings.push({ file, detail: "is missing the atdd-bun block", restore: "bun run atdd-bun agent init --replace" });
+    else if (unstamp(block) !== unstamp(canonical)) findings.push({ file, detail: "atdd-bun block was edited", restore: "bun run atdd-bun agent init --replace" });
+  }
   return findings;
 }
 
 /** Names of the policy fields in `current` that are looser than in `base`. */
-export function loosenedPolicy(base: Partial<HookPolicy>, current: Partial<HookPolicy>): string[] {
+export function loosenedPolicy(base: Partial<HookPolicy> & { profiles?: unknown }, current: Partial<HookPolicy> & { profiles?: unknown }): string[] {
   const b = { ...defaultHookPolicy, ...base, worktrees: { ...defaultHookPolicy.worktrees, ...base.worktrees } }, c = { ...defaultHookPolicy, ...current, worktrees: { ...defaultHookPolicy.worktrees, ...current.worktrees } };
   const out: string[] = [];
   for (const key of ["max_staged_files", "max_staged_changed_lines", "max_uncommitted_files", "max_commits_per_push", "max_registry_removed_lines"] as const) if (Number(c[key]) > Number(b[key])) out.push(`${key} ${b[key]} → ${c[key]}`);
@@ -112,6 +116,10 @@ export function loosenedPolicy(base: Partial<HookPolicy>, current: Partial<HookP
   const removed = b.protected_branches.filter(x => !c.protected_branches.includes(x)), added = c.registry_paths.filter(x => !b.registry_paths.includes(x));
   if (removed.length) out.push(`protected_branches drops ${removed.join(", ")}`);
   if (added.length) out.push(`registry_paths adds ${added.join(", ")}`);
+  // Deactivating a profile stops enforcing it; the operator may do it, as a change a human approves.
+  const active = (config: { profiles?: unknown }): string[] => Array.isArray(config.profiles) ? config.profiles.map(String) : concreteProfiles;
+  const dropped = active(base).filter(name => !active(current).includes(name));
+  if (dropped.length) out.push(`profiles drops ${dropped.join(", ")}`);
   return out;
 }