hatch3r 1.8.0 → 2.0.0

package/dist/content/rules/hatch3r-maintainability.md

@@ -0,0 +1,157 @@
+---
+id: hatch3r-maintainability-rule
+type: rule
+description: CQ8 Maintainability Quality measurement rule — jscpd duplication index, pattern-reuse ratio, cyclomatic complexity, expand-contract migrations, API breaking-change discipline, ADR presence on architectural changes
+scope: conditional
+globs: "src/**,**/migrations/**,**/db/migrations/**,**/prisma/migrations/**,**/openapi.yaml,**/openapi.json,**/*.proto,**/schema.graphql,**/asyncapi.yaml"
+tags: [review, maintainability, code-standards, floor:content-quality]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Maintainability Quality (CQ8)
+
+**Pillars:** P4 (Comprehensive Lean Coverage), CQ8 (Maintainability Quality)
+
+## Scope
+
+This rule binds the CQ8 measurement set across end-user code that hatch3r-generated agents produce AND the framework's own source tree. It owns:
+
+- The jscpd duplication-index ceiling.
+- The pattern-reuse ratio floor.
+- The cyclomatic-complexity per-function ceiling.
+- The expand-contract migration conformance gate.
+- The API breaking-change discipline on stable endpoints.
+- ADR presence on architectural-decision-class changes.
+- Specialist routing to `agents/hatch3r-maintainability.md`.
+
+This complements (does not duplicate) `rules/hatch3r-anti-duplication.md` (the pre-implementation discovery gate). Anti-duplication is the discipline; this rule owns the measurement set + thresholds + specialist routing.
+
+## CQ8 Threshold Set
+
+Source: pillar CQ8 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| jscpd duplication index | ≤5% per cycle | `npx jscpd --min-tokens 50 --min-lines 5 src/` JSON report |
+| Pattern-reuse ratio (reused / newly-authored) | ≥70% | Diff grep against named patterns (circuit breaker, retry-with-jitter, error handler, idempotency-key handler) |
+| Cyclomatic complexity per function | ≤10 | ESLint `complexity` rule (JS/TS), radon (Python), lizard (polyglot) |
+| Documentation currency on user-facing API surfaces | ≤180 days | Last-modified timestamp on doc files; vs API surface diff |
+| Expand-contract migration conformance | 100% | Per `rules/hatch3r-migrations.md` — expand → migrate → contract phases |
+| API breaking-change events on stable endpoints | 0 per release | `oasdiff` (OpenAPI), `buf breaking` (protobuf), `graphql-inspector diff` (GraphQL SDL) |
+| ADR presence on architectural-decision-class changes | 100% | Nygard-format ADR with one of {Proposed, Accepted, Superseded, Deprecated} |
+
+## Duplication Scan
+
+Run `npx jscpd` against in-scope directories every cycle and surface the JSON report path in the finding. The duplication-index is the percentage of duplicated tokens over total tokens — not the percentage of duplicated lines. Configure the scan via `.jscpd.json` with:
+
+- `min-tokens: 50`
+- `min-lines: 5`
+- `ignore: ["**/__tests__/**", "**/node_modules/**", "**/dist/**", "**/build/**"]`
+- `reporters: ["json", "console"]`
+
+Critical-path duplication (auth, payment, settlement, ledger) is escalated regardless of the global index — even <5% global can hide a duplicated security-critical helper.
+
+## Pattern-Reuse Ratio
+
+Count reused vs newly-authored patterns per diff:
+
+- **Reused** — code references a named existing module (e.g. `import { withCircuitBreaker } from '@/lib/resilience'`).
+- **Newly-authored** — code introduces a new pattern that overlaps with an existing one.
+
+Ratio target: ≥70% reused. Per cycle, list the named patterns with their canonical file path:
+
+| Pattern | Canonical location |
+|---------|--------------------|
+| Circuit breaker | `src/lib/resilience/circuitBreaker.ts` (or project equivalent) |
+| Retry with decorrelated jitter | `src/lib/resilience/retryWithBackoff.ts` |
+| Error handler / RFC 9457 problem details | `src/lib/errors/problemDetails.ts` |
+| Idempotency-Key handler | `src/lib/middleware/idempotencyKey.ts` |
+
+Authoring a fifth circuit-breaker implementation in `src/auth/jwt.ts` is a CQ8 violation regardless of unit-test quality.
+
+## Cyclomatic Complexity
+
+Per function, complexity ≤10 (McCabe). Configure linter rules:
+
+- **JS/TS:** ESLint `complexity: ['error', 10]`.
+- **Python:** `radon cc -s -n B` (block B threshold = 6-10).
+- **JVM:** detekt `ComplexMethod: threshold=10`, ktlint, or Checkstyle `CyclomaticComplexity max=10`.
+- **Go:** `gocyclo -over 10 ./...`.
+- **Rust:** `cargo clippy -- -W clippy::cognitive_complexity`.
+
+Functions above the threshold MUST be refactored before merge unless an explicit exception is documented in an ADR (see ADR Presence below).
+
+## Expand-Contract Migrations
+
+Source: `rules/hatch3r-migrations.md`. Schema migrations on shared databases (multi-deploy environments) follow the three-phase pattern:
+
+1. **Expand** — add the new column/table/index in a backward-compatible way. Old code keeps working.
+2. **Migrate** — backfill data; deploy code that writes to both old + new locations or reads from both.
+3. **Contract** — remove the old column/table/index after the migrate phase is verified.
+
+Destructive single-deploy schema changes (drop column, rename column without alias, alter type without conversion) are CRITICAL findings. The specialist names the missing phase in the finding.
+
+## API Breaking-Change Discipline
+
+On stable endpoints (versioned `v1`, `v2`; or unversioned with public-consumer commitment), zero breaking changes per release. Run the per-spec diff tool in CI:
+
+- **OpenAPI 3.x:** `oasdiff breaking --fail-on-diff` exits non-zero on breaks.
+- **Protobuf:** `buf breaking --against '.git#branch=main'` exits non-zero.
+- **GraphQL SDL:** `graphql-inspector diff schema.graphql https://api/graphql --rule considerUsage`.
+
+A breaking change requires a major-version bump per semver 2.0.0 (semver.org). Bypass requires a documented deprecation timeline per `rules/hatch3r-api-versioning.md` — `Deprecation` (RFC 9745) + `Sunset` (RFC 8594) headers + migration guide.
+
+## ADR Presence
+
+Architectural-decision-class changes per `rules/hatch3r-code-standards.md` ADR-trigger list require a Nygard-format ADR with status one of {Proposed, Accepted, Superseded, Deprecated}. Triggers:
+
+- New external dependency (npm package, system tool, managed service).
+- Cross-module API change (public interface, exported types, plugin contract).
+- Performance trade-off requiring documentation (caching strategy, batch size, partition scheme).
+- Security trade-off requiring documentation (auth flow choice, token TTL, encryption algorithm).
+
+ADRs live under `docs/adr/NNNN-{slug}.md` (or project equivalent) and are linked from the PR description.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| Any code mutation | `agents/hatch3r-maintainability.md` (post-write duplication + complexity scan) |
+| Schema or migration file modified | `agents/hatch3r-maintainability.md` (expand-contract conformance) |
+| API spec (OpenAPI / GraphQL SDL / protobuf / AsyncAPI) modified | `agents/hatch3r-maintainability.md` (breaking-change diff) |
+| Architectural decision per ADR-trigger list | `agents/hatch3r-maintainability.md` (ADR presence audit) |
+| Pre-write duplication scan during Implementer phase | `agents/hatch3r-maintainability.md` invoked by `agents/hatch3r-implementer.md` post-write |
+| Release-prep audit | `agents/hatch3r-maintainability.md` |
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ8. The `proof_trace` excerpt is the file:line citation + jscpd/oasdiff/buf-breaking output for the threshold that produced the finding.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ8 Action per status:
+
+- `CRITICAL`: Destructive single-deploy migration; breaking change on stable endpoint without major-version bump; missing ADR on decision-class change.
+- `FINDINGS`: Duplication-index >5%; pattern-reuse ratio <70%; cyclomatic complexity >10; documentation staleness >180 days.
+- `PASS`: All thresholds met; surface in iteration summary.
+
+## When to Invoke
+
+- Every PR that mutates code, schema, or API spec.
+- `agents/hatch3r-implementer.md` invokes this rule's checks post-write to scan its own diff for duplication before declaring completion (anti-duplication procedure per `agents/shared/quality-charter.md` §12).
+- Pre-merge full CQ8 gate — duplication + complexity + pattern-reuse + migration + API-breaking + ADR-presence.
+- Schema-change audits — any migration file triggers an expand-contract conformance scan.
+- API-change audits — any diff touching `openapi.yaml`, `openapi.json`, `*.proto`, or GraphQL SDL triggers the breaking-change CI gate.
+- Release-prep audit before publishing.
+
+## References
+
+- Pillar CQ8 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The prompt-engineering and compound-system audit domains (maintainability domains).
+- `agents/hatch3r-maintainability.md` (CQ8 reviewer / gate).
+- `rules/hatch3r-anti-duplication.md` (pre-implementation discovery gate).
+- `rules/hatch3r-migrations.md` (expand-contract migration pattern).
+- `rules/hatch3r-api-versioning.md` (semver + deprecation + sunset policy).
+- `rules/hatch3r-code-standards.md` (ADR-trigger list).
+- `rules/hatch3r-resilience-patterns.md` (named patterns for the reuse ratio).

package/dist/content/rules/hatch3r-maintainability.mdc

@@ -0,0 +1,152 @@
+---
+description: CQ8 Maintainability Quality measurement rule — jscpd duplication index, pattern-reuse ratio, cyclomatic complexity, expand-contract migrations, API breaking-change discipline, ADR presence on architectural changes
+globs: ["src/**", "**/migrations/**", "**/db/migrations/**", "**/prisma/migrations/**", "**/openapi.yaml", "**/openapi.json", "**/*.proto", "**/schema.graphql", "**/asyncapi.yaml"]
+alwaysApply: false
+precedence: high
+---
+# Maintainability Quality (CQ8)
+
+**Pillars:** P4 (Comprehensive Lean Coverage), CQ8 (Maintainability Quality)
+
+## Scope
+
+This rule binds the CQ8 measurement set across end-user code that hatch3r-generated agents produce AND the framework's own source tree. It owns:
+
+- The jscpd duplication-index ceiling.
+- The pattern-reuse ratio floor.
+- The cyclomatic-complexity per-function ceiling.
+- The expand-contract migration conformance gate.
+- The API breaking-change discipline on stable endpoints.
+- ADR presence on architectural-decision-class changes.
+- Specialist routing to `agents/hatch3r-maintainability.md`.
+
+This complements (does not duplicate) `rules/hatch3r-anti-duplication.md` (the pre-implementation discovery gate). Anti-duplication is the discipline; this rule owns the measurement set + thresholds + specialist routing.
+
+## CQ8 Threshold Set
+
+Source: pillar CQ8 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| jscpd duplication index | ≤5% per cycle | `npx jscpd --min-tokens 50 --min-lines 5 src/` JSON report |
+| Pattern-reuse ratio (reused / newly-authored) | ≥70% | Diff grep against named patterns (circuit breaker, retry-with-jitter, error handler, idempotency-key handler) |
+| Cyclomatic complexity per function | ≤10 | ESLint `complexity` rule (JS/TS), radon (Python), lizard (polyglot) |
+| Documentation currency on user-facing API surfaces | ≤180 days | Last-modified timestamp on doc files; vs API surface diff |
+| Expand-contract migration conformance | 100% | Per `rules/hatch3r-migrations.md` — expand → migrate → contract phases |
+| API breaking-change events on stable endpoints | 0 per release | `oasdiff` (OpenAPI), `buf breaking` (protobuf), `graphql-inspector diff` (GraphQL SDL) |
+| ADR presence on architectural-decision-class changes | 100% | Nygard-format ADR with one of {Proposed, Accepted, Superseded, Deprecated} |
+
+## Duplication Scan
+
+Run `npx jscpd` against in-scope directories every cycle and surface the JSON report path in the finding. The duplication-index is the percentage of duplicated tokens over total tokens — not the percentage of duplicated lines. Configure the scan via `.jscpd.json` with:
+
+- `min-tokens: 50`
+- `min-lines: 5`
+- `ignore: ["**/__tests__/**", "**/node_modules/**", "**/dist/**", "**/build/**"]`
+- `reporters: ["json", "console"]`
+
+Critical-path duplication (auth, payment, settlement, ledger) is escalated regardless of the global index — even <5% global can hide a duplicated security-critical helper.
+
+## Pattern-Reuse Ratio
+
+Count reused vs newly-authored patterns per diff:
+
+- **Reused** — code references a named existing module (e.g. `import { withCircuitBreaker } from '@/lib/resilience'`).
+- **Newly-authored** — code introduces a new pattern that overlaps with an existing one.
+
+Ratio target: ≥70% reused. Per cycle, list the named patterns with their canonical file path:
+
+| Pattern | Canonical location |
+|---------|--------------------|
+| Circuit breaker | `src/lib/resilience/circuitBreaker.ts` (or project equivalent) |
+| Retry with decorrelated jitter | `src/lib/resilience/retryWithBackoff.ts` |
+| Error handler / RFC 9457 problem details | `src/lib/errors/problemDetails.ts` |
+| Idempotency-Key handler | `src/lib/middleware/idempotencyKey.ts` |
+
+Authoring a fifth circuit-breaker implementation in `src/auth/jwt.ts` is a CQ8 violation regardless of unit-test quality.
+
+## Cyclomatic Complexity
+
+Per function, complexity ≤10 (McCabe). Configure linter rules:
+
+- **JS/TS:** ESLint `complexity: ['error', 10]`.
+- **Python:** `radon cc -s -n B` (block B threshold = 6-10).
+- **JVM:** detekt `ComplexMethod: threshold=10`, ktlint, or Checkstyle `CyclomaticComplexity max=10`.
+- **Go:** `gocyclo -over 10 ./...`.
+- **Rust:** `cargo clippy -- -W clippy::cognitive_complexity`.
+
+Functions above the threshold MUST be refactored before merge unless an explicit exception is documented in an ADR (see ADR Presence below).
+
+## Expand-Contract Migrations
+
+Source: `rules/hatch3r-migrations.md`. Schema migrations on shared databases (multi-deploy environments) follow the three-phase pattern:
+
+1. **Expand** — add the new column/table/index in a backward-compatible way. Old code keeps working.
+2. **Migrate** — backfill data; deploy code that writes to both old + new locations or reads from both.
+3. **Contract** — remove the old column/table/index after the migrate phase is verified.
+
+Destructive single-deploy schema changes (drop column, rename column without alias, alter type without conversion) are CRITICAL findings. The specialist names the missing phase in the finding.
+
+## API Breaking-Change Discipline
+
+On stable endpoints (versioned `v1`, `v2`; or unversioned with public-consumer commitment), zero breaking changes per release. Run the per-spec diff tool in CI:
+
+- **OpenAPI 3.x:** `oasdiff breaking --fail-on-diff` exits non-zero on breaks.
+- **Protobuf:** `buf breaking --against '.git#branch=main'` exits non-zero.
+- **GraphQL SDL:** `graphql-inspector diff schema.graphql https://api/graphql --rule considerUsage`.
+
+A breaking change requires a major-version bump per semver 2.0.0 (semver.org). Bypass requires a documented deprecation timeline per `rules/hatch3r-api-versioning.md` — `Deprecation` (RFC 9745) + `Sunset` (RFC 8594) headers + migration guide.
+
+## ADR Presence
+
+Architectural-decision-class changes per `rules/hatch3r-code-standards.md` ADR-trigger list require a Nygard-format ADR with status one of {Proposed, Accepted, Superseded, Deprecated}. Triggers:
+
+- New external dependency (npm package, system tool, managed service).
+- Cross-module API change (public interface, exported types, plugin contract).
+- Performance trade-off requiring documentation (caching strategy, batch size, partition scheme).
+- Security trade-off requiring documentation (auth flow choice, token TTL, encryption algorithm).
+
+ADRs live under `docs/adr/NNNN-{slug}.md` (or project equivalent) and are linked from the PR description.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| Any code mutation | `agents/hatch3r-maintainability.md` (post-write duplication + complexity scan) |
+| Schema or migration file modified | `agents/hatch3r-maintainability.md` (expand-contract conformance) |
+| API spec (OpenAPI / GraphQL SDL / protobuf / AsyncAPI) modified | `agents/hatch3r-maintainability.md` (breaking-change diff) |
+| Architectural decision per ADR-trigger list | `agents/hatch3r-maintainability.md` (ADR presence audit) |
+| Pre-write duplication scan during Implementer phase | `agents/hatch3r-maintainability.md` invoked by `agents/hatch3r-implementer.md` post-write |
+| Release-prep audit | `agents/hatch3r-maintainability.md` |
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ8. The `proof_trace` excerpt is the file:line citation + jscpd/oasdiff/buf-breaking output for the threshold that produced the finding.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ8 Action per status:
+
+- `CRITICAL`: Destructive single-deploy migration; breaking change on stable endpoint without major-version bump; missing ADR on decision-class change.
+- `FINDINGS`: Duplication-index >5%; pattern-reuse ratio <70%; cyclomatic complexity >10; documentation staleness >180 days.
+- `PASS`: All thresholds met; surface in iteration summary.
+
+## When to Invoke
+
+- Every PR that mutates code, schema, or API spec.
+- `agents/hatch3r-implementer.md` invokes this rule's checks post-write to scan its own diff for duplication before declaring completion (anti-duplication procedure per `agents/shared/quality-charter.md` §12).
+- Pre-merge full CQ8 gate — duplication + complexity + pattern-reuse + migration + API-breaking + ADR-presence.
+- Schema-change audits — any migration file triggers an expand-contract conformance scan.
+- API-change audits — any diff touching `openapi.yaml`, `openapi.json`, `*.proto`, or GraphQL SDL triggers the breaking-change CI gate.
+- Release-prep audit before publishing.
+
+## References
+
+- Pillar CQ8 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The prompt-engineering and compound-system audit domains (maintainability domains).
+- `agents/hatch3r-maintainability.md` (CQ8 reviewer / gate).
+- `rules/hatch3r-anti-duplication.md` (pre-implementation discovery gate).
+- `rules/hatch3r-migrations.md` (expand-contract migration pattern).
+- `rules/hatch3r-api-versioning.md` (semver + deprecation + sunset policy).
+- `rules/hatch3r-code-standards.md` (ADR-trigger list).
+- `rules/hatch3r-resilience-patterns.md` (named patterns for the reuse ratio).

package/{rules → dist/content/rules}/hatch3r-migrations.md

@@ -2,8 +2,10 @@
 id: hatch3r-migrations
 type: rule
 description: Database migration and schema change patterns — expand-contract, online DDL, backfills, compatibility windows, reversibility, multi-region, tooling
-scope: "**/migrations/**,**/*migration*,**/migrate/**,**/seeds/**,**/seeders/**,**/prisma/migrations/**,**/drizzle/**,**/knex/**"
-tags: [implementation, brownfield]
+scope: conditional
+globs: "**/migrations/**,**/*migration*,**/migrate/**,**/seeds/**,**/seeders/**,**/prisma/migrations/**,**/drizzle/**,**/knex/**"
+tags: [implementation, ctx:brownfield-only]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-migrations.mdc

@@ -2,6 +2,7 @@
 description: Database migration and schema change patterns — expand-contract, online DDL, backfills, compatibility windows, reversibility, multi-region, tooling
 globs: ["**/migrations/**", "**/*migration*", "**/migrate/**", "**/seeds/**", "**/seeders/**", "**/prisma/migrations/**", "**/drizzle/**", "**/knex/**"]
 alwaysApply: false
+precedence: high
 ---
 # Migrations
 

package/{rules → dist/content/rules}/hatch3r-observability-logging.md

@@ -4,7 +4,8 @@ type: rule
 description: Structured logging and error reporting conventions for the project
 scope: conditional
 globs: "**/*log*,**/*logger*,**/*logging*,**/*error*,**/observability/**,**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**"
-tags: [devops]
+tags: [devops, observability]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-observability-logging.mdc

@@ -2,6 +2,7 @@
 description: Structured logging and error reporting conventions for the project
 globs: ["**/*log*", "**/*logger*", "**/*logging*", "**/*error*", "**/observability/**", "**/routes/**", "**/handlers/**", "**/services/**", "**/api/**", "**/middleware/**", "**/controllers/**", "**/lib/**"]
 alwaysApply: false
+precedence: high
 ---
 # Observability -- Logging & Error Reporting
 

package/{rules → dist/content/rules}/hatch3r-observability-metrics.md

@@ -4,7 +4,8 @@ type: rule
 description: Metrics, SLO/SLI definitions, alerting, and dashboard conventions for the project
 scope: conditional
 globs: "**/*metric*,**/*slo*,**/*sli*,**/*alert*,**/*dashboard*,**/observability/**,**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**"
-tags: [devops]
+tags: [devops, observability]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-observability-metrics.mdc

@@ -2,6 +2,7 @@
 description: Metrics, SLO/SLI definitions, alerting, and dashboard conventions for the project
 globs: ["**/*metric*", "**/*slo*", "**/*sli*", "**/*alert*", "**/*dashboard*", "**/observability/**", "**/routes/**", "**/handlers/**", "**/services/**", "**/api/**", "**/middleware/**", "**/controllers/**", "**/lib/**"]
 alwaysApply: false
+precedence: high
 ---
 # Observability -- Metrics, SLOs & Alerting
 

package/{rules → dist/content/rules}/hatch3r-observability-tracing.md

@@ -4,7 +4,8 @@ type: rule
 description: Distributed tracing, OpenTelemetry conventions, and AI agent instrumentation for the project
 scope: conditional
 globs: "**/*trac*,**/*span*,**/*telemetry*,**/*otel*,**/*agent*,**/observability/**,**/routes/**,**/handlers/**,**/services/**,**/api/**,**/middleware/**,**/controllers/**,**/lib/**"
-tags: [devops]
+tags: [devops, observability]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -34,7 +35,7 @@ Distributed tracing, OpenTelemetry semantic conventions, AI agent instrumentatio
 
 ## OpenTelemetry Semantic Conventions
 
-Follow the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) (v1.29+) for consistent attribute naming across all telemetry signals.
+Follow the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) (v1.41.1) for consistent attribute naming across all telemetry signals.
 
 ### Standard Attribute Namespaces
 
@@ -84,43 +85,46 @@ Every telemetry-producing service must declare resource attributes at startup:
 
 ## AI Agent Instrumentation
 
-Follow the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for AI/LLM agent instrumentation.
+Follow the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for AI/LLM agent instrumentation. The GenAI conventions are Development status — gate any opt-in alias emission on `OTEL_SEMCONV_STABILITY_OPT_IN` and re-check the spec each P3 currency cycle.
 
 ### GenAI Span Attributes
 
 Use these attributes on all spans representing interactions with generative AI models:
 
-| Attribute | Type | Description | Example |
-|-----------|------|-------------|---------|
-| `gen_ai.system` | string | GenAI provider system name | `openai`, `anthropic`, `azure_openai` |
-| `gen_ai.request.model` | string | Model name as specified in the request | `gpt-4o`, `claude-sonnet-4-20250514` |
-| `gen_ai.response.model` | string | Model name as returned in the response | `gpt-4o-2024-08-06` |
-| `gen_ai.request.max_tokens` | int | Maximum tokens requested for generation | `4096` |
-| `gen_ai.request.temperature` | float | Temperature parameter | `0.7` |
-| `gen_ai.response.finish_reasons` | string[] | Reasons the model stopped generating | `["stop"]`, `["length"]` |
-| `gen_ai.usage.input_tokens` | int | Tokens in the input/prompt | `1250` |
-| `gen_ai.usage.output_tokens` | int | Tokens in the generated output | `530` |
-
-- Always set `gen_ai.system` and `gen_ai.request.model` on every GenAI span.
-- Record `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from the API response for cost dashboards.
+| Attribute | Type | Requirement | Description | Example |
+|-----------|------|-------------|-------------|---------|
+| `gen_ai.operation.name` | string | Required | Operation kind: `chat`, `generate_content`, `embeddings`, `create_agent`, `invoke_agent`, `execute_tool` | `chat`, `invoke_agent` |
+| `gen_ai.provider.name` | string | Required | GenAI provider name | `openai`, `anthropic`, `azure.ai.openai` |
+| `gen_ai.request.model` | string | Required | Model name as specified in the request | `gpt-4o`, `claude-sonnet-4-20250514` |
+| `gen_ai.response.model` | string | Recommended | Model name as returned in the response | `gpt-4o-2024-08-06` |
+| `gen_ai.request.max_tokens` | int | Recommended | Maximum tokens requested for generation | `4096` |
+| `gen_ai.request.temperature` | float | Recommended | Temperature parameter | `0.7` |
+| `gen_ai.response.finish_reasons` | string[] | Recommended | Reasons the model stopped generating | `["stop"]`, `["length"]` |
+| `gen_ai.usage.input_tokens` | int | Recommended | Tokens in the input/prompt | `1250` |
+| `gen_ai.usage.output_tokens` | int | Recommended | Tokens in the generated output | `530` |
+
+- Always set `gen_ai.operation.name`, `gen_ai.provider.name`, and `gen_ai.request.model` on every GenAI span.
+- Record `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from the API response for cost dashboards. `gen_ai.operation.name` + `gen_ai.provider.name` are the required label pair on GenAI metrics (`gen_ai.client.token.usage`, `gen_ai.client.operation.duration`).
 - Use `gen_ai.response.finish_reasons` to detect truncated outputs (`length`) and trigger re-prompting.
+- **Migration (SemConv v1.37.0, 2025-07-05):** `gen_ai.system` is renamed to `gen_ai.provider.name`; emit the new key. Instrumentations bridging older collectors may dual-emit the legacy `gen_ai.system` alias only under `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`.
 
 ### Agent Invocation Spans
 
 Instrument the full lifecycle of an agent invocation with a dedicated span. This span is the parent for all LLM calls, tool executions, and sub-agent delegations.
 
-- **Span name pattern:** `agent.{agent_name}.invoke`
-- **Required attributes:** `agent.id`, `agent.name`, `agent.parent_id`, `agent.task`, `agent.framework`
+- **Span name pattern:** `invoke_agent {gen_ai.agent.name}` (OTel GenAI agent span naming).
+- **Required attributes:** `gen_ai.operation.name` = `invoke_agent`, `gen_ai.agent.id`, `gen_ai.agent.name`. Use `create_agent` for the agent-construction span.
+- **Project-namespaced extras:** `app.agent.parent_id`, `app.agent.task` carry hatch3r-specific context the GenAI namespace does not define (prefix custom attributes per the Attribute Naming Guidelines above).
 - **Span events for state transitions:** `agent.planning`, `agent.tool_selection`, `agent.awaiting_human`, `agent.delegating`, `agent.completed`, `agent.error`
 
 ```typescript
-const agentSpan = tracer.startSpan('agent.code_reviewer.invoke', {
+const agentSpan = tracer.startSpan('invoke_agent code_reviewer', {
   attributes: {
-    'agent.id': invocationId,
-    'agent.name': 'code_reviewer',
-    'agent.parent_id': parentAgentId ?? '',
-    'agent.task': `review PR #${prNumber}`,
-    'agent.framework': 'custom',
+    'gen_ai.operation.name': 'invoke_agent',
+    'gen_ai.agent.id': invocationId,
+    'gen_ai.agent.name': 'code_reviewer',
+    'app.agent.parent_id': parentAgentId ?? '',
+    'app.agent.task': `review PR #${prNumber}`,
   },
 });
 agentSpan.addEvent('agent.planning');
@@ -133,26 +137,32 @@ agentSpan.end();
 
 Every tool invocation by an agent creates a child span of the agent invocation span.
 
-- **Span name pattern:** `tool.{tool_name}.execute`
-- **Required attributes:** `tool.name`, `tool.input_hash` (SHA-256), `tool.output_status`, `tool.duration_ms`, `tool.parameters_count`
-- Tool spans must be children of the invoking agent span. Set span status to `ERROR` when `tool.output_status` is `error` or `timeout`.
+- **Span name pattern:** `execute_tool {gen_ai.tool.name}` (OTel GenAI tool span naming).
+- **Required attributes:** `gen_ai.operation.name` = `execute_tool`, `gen_ai.tool.name`.
+- **Project-namespaced extras:** `app.tool.input_hash` (SHA-256), `app.tool.output_status`, `app.tool.duration_ms`, `app.tool.parameters_count` — hatch3r audit-trail fields the GenAI namespace does not define.
+- Tool spans must be children of the invoking agent span. Set span status to `ERROR` when `app.tool.output_status` is `error` or `timeout`.
 - For tools performing I/O, create nested child spans using appropriate semantic conventions (`http.*`, `db.*`).
 
 ```typescript
 const toolSpan = tracer.startSpan(
-  'tool.git_diff.execute',
-  { attributes: { 'tool.name': 'git_diff' } },
+  'execute_tool git_diff',
+  {
+    attributes: {
+      'gen_ai.operation.name': 'execute_tool',
+      'gen_ai.tool.name': 'git_diff',
+    },
+  },
   trace.setSpan(context.active(), agentSpan),
 );
 try {
   const result = await tools.gitDiff(params);
   toolSpan.setAttributes({
-    'tool.output_status': 'success',
-    'tool.duration_ms': performance.now() - startTime,
-    'tool.input_hash': hashInput(params),
+    'app.tool.output_status': 'success',
+    'app.tool.duration_ms': performance.now() - startTime,
+    'app.tool.input_hash': hashInput(params),
   });
 } catch (err) {
-  toolSpan.setAttributes({ 'tool.output_status': 'error' });
+  toolSpan.setAttributes({ 'app.tool.output_status': 'error' });
   toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
   toolSpan.recordException(err);
   throw err;
@@ -163,8 +173,8 @@ try {
 
 ### LLM Request/Response Tracing
 
-- **Span name pattern:** `gen_ai.{operation}` (e.g., `gen_ai.chat`, `gen_ai.completion`)
-- **Token tracking:** Capture `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. Aggregate in metrics: Counter `gen_ai.tokens_total` with labels `{direction, model, agent_name}`, Histogram `gen_ai.request_duration_ms`.
+- **Span name pattern:** `{gen_ai.operation.name} {gen_ai.request.model}` (e.g., `chat gpt-4o`, `generate_content claude-sonnet-4-20250514`)
+- **Token tracking:** Capture `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. Aggregate in the registered GenAI metrics: Histogram `gen_ai.client.token.usage` (attribute `gen_ai.token.type` = `input`/`output`), Histogram `gen_ai.client.operation.duration`.
 - **Model version tracking:** Record both `gen_ai.request.model` and `gen_ai.response.model` for drift detection.
 - **Retry spans:** Each retry attempt is a separate child span. Set `gen_ai.request.retries` on the final span. Record `http.response.status_code` on failed spans (429 vs 500+).
 - Never log raw prompt content or full model responses as span attributes. Use token counts for cost tracking and correlated logs for prompt debugging in non-production environments.
@@ -172,7 +182,7 @@ try {
 
 ### Tool Call Audit Trail
 
-Maintain a structured audit log for every tool invocation in agentic workflows, separate from tracing spans.
+Maintain a structured audit log for every tool invocation in agentic workflows, separate from tracing spans. These are hatch3r log-schema field names (not OTel span attributes); on the tool span itself, emit the OTel GenAI keys (`gen_ai.tool.name`, `gen_ai.operation.name`) plus the `app.tool.*` extras from "Tool Call Spans" above.
 
 | Field | Type | Description |
 |-------|------|-------------|