hatch3r 1.9.0 → 2.0.0

package/dist/content/rules/hatch3r-observability-tracing.md

@@ -4,7 +4,7 @@ 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
@@ -35,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
 
@@ -85,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');
@@ -134,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;
@@ -164,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.
@@ -173,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 |
 |-------|------|-------------|

package/dist/content/rules/hatch3r-observability-tracing.mdc

@@ -30,7 +30,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
 
@@ -80,43 +80,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');
@@ -129,26 +132,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;
@@ -159,8 +168,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.
@@ -168,7 +177,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 |
 |-------|------|-------------|

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

@@ -2,7 +2,8 @@
 id: hatch3r-operability
 type: rule
 description: Operability patterns in user code — liveness / readiness / startup probes, graceful shutdown, feature flags, runbook URL annotations, health endpoints
-scope: "**/services/**,**/handlers/**,**/health*,**/probes/**,**/k8s/**,**/manifests/**,**/charts/**,**/feature*,**/flags/**"
+scope: conditional
+globs: "**/services/**,**/handlers/**,**/health*,**/probes/**,**/k8s/**,**/manifests/**,**/charts/**,**/feature*,**/flags/**"
 tags: [implementation, devops]
 precedence: high
 quality_charter: agents/shared/quality-charter.md

package/dist/content/rules/hatch3r-passkey-server.md

@@ -2,7 +2,8 @@
 id: hatch3r-passkey-server
 type: rule
 description: Server-side WebAuthn / passkey ceremony — registration, authentication, attestation, counter, RP-ID, recovery, FIDO CXP/CXF awareness
-scope: "**/auth/**,**/passkey*,**/webauthn*,**/fido*,**/credentials/**,**/api/**,**/handlers/**"
+scope: conditional
+globs: "**/auth/**,**/passkey*,**/webauthn*,**/fido*,**/credentials/**,**/api/**,**/handlers/**"
 tags: [implementation, floor:security]
 precedence: high
 quality_charter: agents/shared/quality-charter.md

package/dist/content/rules/hatch3r-performance-budgets.md

@@ -10,6 +10,8 @@ cache_friendly: true
 ---
 # Performance Budgets
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ7 (Performance Quality)
+
 ## Application Budgets
 
 | Metric                            | Budget               |

package/dist/content/rules/hatch3r-performance-budgets.mdc

@@ -5,6 +5,8 @@ alwaysApply: false
 ---
 # Performance Budgets
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ7 (Performance Quality)
+
 ## Application Budgets
 
 | Metric                            | Budget               |

package/dist/content/rules/hatch3r-php-laravel-patterns.md

@@ -0,0 +1,109 @@
+---
+id: hatch3r-php-laravel-patterns
+type: rule
+description: PHP 8.3+ and Laravel 11.x conventions covering typed properties, attributes, Eloquent ORM, Service Container DI, Pest testing, queue workers, and Laravel Pint formatting
+scope: conditional
+globs: "**/*.php,**/composer.json,**/composer.lock,**/artisan,**/phpunit.xml,**/phpunit.xml.dist,**/phpstan.neon,**/phpstan.neon.dist,**/pint.json,**/.php-cs-fixer.php,**/app/**,**/bootstrap/**,**/config/**,**/database/migrations/**,**/routes/**,**/tests/**"
+tags: [implementation]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# PHP / Laravel Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a PHP application. Detection signals: `composer.json` at repo root, `artisan` script (Laravel), or any `*.php` source file. Symfony and Symfony-based projects also follow most of the language-level guidance here.
+
+## PHP Language Floor
+
+- Target PHP 8.3+ (8.4 recommended for new projects). Use typed properties, constructor property promotion, enums, readonly classes, first-class callable syntax. Avoid PHP 7.x patterns in new code.
+- Enable strict types in every file (`declare(strict_types=1);` as the first statement after `<?php`). The IDE / Pint config enforces presence.
+- Static analysis: PHPStan level 8 or Psalm level 1 in CI. Treat warnings as errors. Configure via `phpstan.neon` with project-specific baselines for legacy code.
+- Format with Laravel Pint (Laravel projects) or PHP-CS-Fixer with PER 2.0 / PSR-12 ruleset. Run in CI; reformat-on-save in editors.
+
+## Project Layout (Laravel)
+
+- Default Laravel structure:
+  - `app/Models/` — Eloquent models.
+  - `app/Http/Controllers/` — controllers (HTTP only, thin orchestration).
+  - `app/Services/<Domain>/` — domain services and business logic.
+  - `app/Actions/` — single-purpose action classes (one public `execute()` method).
+  - `app/Jobs/` — queue jobs.
+  - `app/Policies/` — authorization policies.
+- Keep controllers thin: receive request → call action / service → return response. Business logic in services or action classes, not controllers.
+- Public API of the app: HTTP routes (`routes/api.php`, `routes/web.php`), Artisan commands (`app/Console/Commands/`), broadcast channels (`routes/channels.php`).
+
+## Laravel 11.x
+
+- Laravel 11 is the floor (Feb 2024 release, supported through 2026). Migrate from earlier versions via the official upgrade guide; do not skip major versions.
+- Use the streamlined application skeleton: `bootstrap/app.php` with `withRouting`, `withMiddleware`, `withExceptions` configuration callbacks. Avoid restoring the legacy `kernel.php` files for new projects.
+- Configuration: `config/*.php` returns arrays; access via `config('key.path')`. Never call `env()` outside `config/*.php` — `php artisan config:cache` invalidates direct `env()` calls in app code.
+- Environment-specific config: `.env.local`, `.env.production`. Never commit `.env` files to VCS.
+
+## Eloquent ORM
+
+- Define models with explicit `$fillable` (allowlist) — never `$guarded = []`. Mass-assignment vulnerabilities are real.
+- Type-hint relationship return types: `public function orders(): HasMany { ... }`. The static analyzer catches relationship typos.
+- N+1 query prevention: eager-load relationships explicitly (`User::with('orders.items')->...`). Use the Laravel debug bar or `LazyEagerLoad::enforce()` in tests to catch N+1 violations in CI.
+- Avoid mass operations through Eloquent (`Model::all()`, then iterating). Use the query builder, chunked queries (`->chunk(100, function ($users) { ... })`), or lazy collections for large result sets.
+- Migrations are forward-only in production. Never `php artisan migrate:rollback` against production. For destructive schema changes, write a forward-only migration that achieves the same outcome.
+
+## Service Container & DI
+
+- Constructor injection via type-hinted parameters. The container auto-resolves bindings declared in service providers.
+- Define bindings in `app/Providers/AppServiceProvider.php` (or feature-specific providers). Use `bind` for transient services, `singleton` for app-wide singletons, `scoped` for request-scoped.
+- Contextual bindings via `$this->app->when(MyController::class)->needs(LoggerInterface::class)->give(...)`. Stops type-hint hacks.
+- Avoid `app()` and `resolve()` helpers in app code — they obscure dependencies. Reserve for service providers and one-off scripts.
+
+## HTTP Layer
+
+- Form Requests (`php artisan make:request StoreUserRequest`) for input validation. Define `rules()`, `authorize()`, and `messages()` methods. Controllers receive the validated request, never `$request->all()` blindly.
+- Resource classes (`php artisan make:resource UserResource`) for API responses. Stop returning raw Eloquent models — Resources control the shape and protect against accidental field leaks.
+- Use route model binding (`Route::get('/users/{user}', [UserController::class, 'show'])` with type-hinted `User $user`). Automatic 404s and stable URL conventions.
+- Middleware: composable via `bootstrap/app.php` `withMiddleware()`. Avoid global middleware unless it applies to all routes — prefer route groups.
+
+## Queues & Jobs
+
+- Use Laravel queues for any work over 200ms: emails, third-party API calls, image processing, report generation. Synchronous handling blocks the HTTP response.
+- Job classes implement `ShouldQueue`. Configure retry counts (`public int $tries = 3`) and backoff (`public function backoff(): array { return [60, 300, 1800]; }`). Idempotency keys for jobs touching external APIs.
+- Driver choice: Redis (`predis/predis` or `phpredis`) for high throughput, Database for low-volume / dev. Avoid Beanstalkd / SQS unless infrastructure requires it.
+- Run workers via Horizon (`laravel/horizon`) for production observability and balanced auto-scaling. Configure tags, supervisors, and memory limits in `config/horizon.php`.
+
+## Testing
+
+- Use Pest (`pestphp/pest`) for new test suites — terser syntax than PHPUnit, runs on top of PHPUnit. PHPUnit alone is acceptable for legacy projects.
+- Test types under `tests/`:
+  - `tests/Unit/` — pure logic, no Laravel bootstrap.
+  - `tests/Feature/` — full HTTP / queue / database flows with `RefreshDatabase` trait.
+  - `tests/Browser/` — Dusk for end-to-end browser tests.
+- Database tests: `RefreshDatabase` trait wraps each test in a transaction and rolls back. Never use `DatabaseMigrations` in CI — too slow.
+- Mock external services with Laravel's HTTP facade (`Http::fake([...])`). Never hit real network in tests.
+- Coverage: `php artisan test --coverage --min=80`. Floor: 80% line coverage; 90% in critical modules (auth, billing, persistence).
+
+## Security
+
+- Validate every user input via Form Requests. Never trust `$request->all()` direct to a model.
+- Authorization via Policies (`app/Policies/`) registered in `AuthServiceProvider`. Controllers call `$this->authorize('update', $post)`. Never authorize in views — too late.
+- CSRF protection: Laravel adds it by default to web routes. Do not disable globally.
+- Mass-assignment: `$fillable` allowlist on every model. Audit `$guarded = []` patterns and migrate.
+- Encryption: `Crypt::encryptString()` for sensitive at-rest data. Never reinvent symmetric encryption.
+
+## Composer & Dependency Hygiene
+
+- Pin versions in `composer.json` to caret ranges (`^11.0` for Laravel itself, `^1.2` for stable libraries). Avoid `*` and `dev-` requirements in production.
+- Lock file (`composer.lock`) committed for applications. Library packages typically omit the lock.
+- Vulnerability scanning: `composer audit` (PHP 8.2+, Composer 2.4+) in CI against the FriendsOfPHP/security-advisories database. Block merge on advisories.
+- License compliance: `composer-license-checker` with an allowlist. Block GPL contamination.
+
+## References
+
+- PHP 8.3 release notes: https://www.php.net/releases/8.3/en.php (accessed 2026-05-27, official-docs)
+- Laravel 11 upgrade guide: https://laravel.com/docs/11.x/upgrade (accessed 2026-05-27, official-docs)
+- Laravel docs: https://laravel.com/docs/11.x (accessed 2026-05-27, official-docs)
+- Pest: https://pestphp.com/docs/installation (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to Laravel API endpoints.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `php artisan test --coverage`.
+- `rules/hatch3r-secrets-management.md` — `.env` handling and secret rotation patterns.

package/dist/content/rules/hatch3r-php-laravel-patterns.mdc

@@ -0,0 +1,104 @@
+---
+description: PHP 8.3+ and Laravel 11.x conventions covering typed properties, attributes, Eloquent ORM, Service Container DI, Pest testing, queue workers, and Laravel Pint formatting
+globs: ["**/*.php", "**/composer.json", "**/composer.lock", "**/artisan", "**/phpunit.xml", "**/phpunit.xml.dist", "**/phpstan.neon", "**/phpstan.neon.dist", "**/pint.json", "**/.php-cs-fixer.php", "**/app/**", "**/bootstrap/**", "**/config/**", "**/database/migrations/**", "**/routes/**", "**/tests/**"]
+alwaysApply: false
+---
+# PHP / Laravel Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a PHP application. Detection signals: `composer.json` at repo root, `artisan` script (Laravel), or any `*.php` source file. Symfony and Symfony-based projects also follow most of the language-level guidance here.
+
+## PHP Language Floor
+
+- Target PHP 8.3+ (8.4 recommended for new projects). Use typed properties, constructor property promotion, enums, readonly classes, first-class callable syntax. Avoid PHP 7.x patterns in new code.
+- Enable strict types in every file (`declare(strict_types=1);` as the first statement after `<?php`). The IDE / Pint config enforces presence.
+- Static analysis: PHPStan level 8 or Psalm level 1 in CI. Treat warnings as errors. Configure via `phpstan.neon` with project-specific baselines for legacy code.
+- Format with Laravel Pint (Laravel projects) or PHP-CS-Fixer with PER 2.0 / PSR-12 ruleset. Run in CI; reformat-on-save in editors.
+
+## Project Layout (Laravel)
+
+- Default Laravel structure:
+  - `app/Models/` — Eloquent models.
+  - `app/Http/Controllers/` — controllers (HTTP only, thin orchestration).
+  - `app/Services/<Domain>/` — domain services and business logic.
+  - `app/Actions/` — single-purpose action classes (one public `execute()` method).
+  - `app/Jobs/` — queue jobs.
+  - `app/Policies/` — authorization policies.
+- Keep controllers thin: receive request → call action / service → return response. Business logic in services or action classes, not controllers.
+- Public API of the app: HTTP routes (`routes/api.php`, `routes/web.php`), Artisan commands (`app/Console/Commands/`), broadcast channels (`routes/channels.php`).
+
+## Laravel 11.x
+
+- Laravel 11 is the floor (Feb 2024 release, supported through 2026). Migrate from earlier versions via the official upgrade guide; do not skip major versions.
+- Use the streamlined application skeleton: `bootstrap/app.php` with `withRouting`, `withMiddleware`, `withExceptions` configuration callbacks. Avoid restoring the legacy `kernel.php` files for new projects.
+- Configuration: `config/*.php` returns arrays; access via `config('key.path')`. Never call `env()` outside `config/*.php` — `php artisan config:cache` invalidates direct `env()` calls in app code.
+- Environment-specific config: `.env.local`, `.env.production`. Never commit `.env` files to VCS.
+
+## Eloquent ORM
+
+- Define models with explicit `$fillable` (allowlist) — never `$guarded = []`. Mass-assignment vulnerabilities are real.
+- Type-hint relationship return types: `public function orders(): HasMany { ... }`. The static analyzer catches relationship typos.
+- N+1 query prevention: eager-load relationships explicitly (`User::with('orders.items')->...`). Use the Laravel debug bar or `LazyEagerLoad::enforce()` in tests to catch N+1 violations in CI.
+- Avoid mass operations through Eloquent (`Model::all()`, then iterating). Use the query builder, chunked queries (`->chunk(100, function ($users) { ... })`), or lazy collections for large result sets.
+- Migrations are forward-only in production. Never `php artisan migrate:rollback` against production. For destructive schema changes, write a forward-only migration that achieves the same outcome.
+
+## Service Container & DI
+
+- Constructor injection via type-hinted parameters. The container auto-resolves bindings declared in service providers.
+- Define bindings in `app/Providers/AppServiceProvider.php` (or feature-specific providers). Use `bind` for transient services, `singleton` for app-wide singletons, `scoped` for request-scoped.
+- Contextual bindings via `$this->app->when(MyController::class)->needs(LoggerInterface::class)->give(...)`. Stops type-hint hacks.
+- Avoid `app()` and `resolve()` helpers in app code — they obscure dependencies. Reserve for service providers and one-off scripts.
+
+## HTTP Layer
+
+- Form Requests (`php artisan make:request StoreUserRequest`) for input validation. Define `rules()`, `authorize()`, and `messages()` methods. Controllers receive the validated request, never `$request->all()` blindly.
+- Resource classes (`php artisan make:resource UserResource`) for API responses. Stop returning raw Eloquent models — Resources control the shape and protect against accidental field leaks.
+- Use route model binding (`Route::get('/users/{user}', [UserController::class, 'show'])` with type-hinted `User $user`). Automatic 404s and stable URL conventions.
+- Middleware: composable via `bootstrap/app.php` `withMiddleware()`. Avoid global middleware unless it applies to all routes — prefer route groups.
+
+## Queues & Jobs
+
+- Use Laravel queues for any work over 200ms: emails, third-party API calls, image processing, report generation. Synchronous handling blocks the HTTP response.
+- Job classes implement `ShouldQueue`. Configure retry counts (`public int $tries = 3`) and backoff (`public function backoff(): array { return [60, 300, 1800]; }`). Idempotency keys for jobs touching external APIs.
+- Driver choice: Redis (`predis/predis` or `phpredis`) for high throughput, Database for low-volume / dev. Avoid Beanstalkd / SQS unless infrastructure requires it.
+- Run workers via Horizon (`laravel/horizon`) for production observability and balanced auto-scaling. Configure tags, supervisors, and memory limits in `config/horizon.php`.
+
+## Testing
+
+- Use Pest (`pestphp/pest`) for new test suites — terser syntax than PHPUnit, runs on top of PHPUnit. PHPUnit alone is acceptable for legacy projects.
+- Test types under `tests/`:
+  - `tests/Unit/` — pure logic, no Laravel bootstrap.
+  - `tests/Feature/` — full HTTP / queue / database flows with `RefreshDatabase` trait.
+  - `tests/Browser/` — Dusk for end-to-end browser tests.
+- Database tests: `RefreshDatabase` trait wraps each test in a transaction and rolls back. Never use `DatabaseMigrations` in CI — too slow.
+- Mock external services with Laravel's HTTP facade (`Http::fake([...])`). Never hit real network in tests.
+- Coverage: `php artisan test --coverage --min=80`. Floor: 80% line coverage; 90% in critical modules (auth, billing, persistence).
+
+## Security
+
+- Validate every user input via Form Requests. Never trust `$request->all()` direct to a model.
+- Authorization via Policies (`app/Policies/`) registered in `AuthServiceProvider`. Controllers call `$this->authorize('update', $post)`. Never authorize in views — too late.
+- CSRF protection: Laravel adds it by default to web routes. Do not disable globally.
+- Mass-assignment: `$fillable` allowlist on every model. Audit `$guarded = []` patterns and migrate.
+- Encryption: `Crypt::encryptString()` for sensitive at-rest data. Never reinvent symmetric encryption.
+
+## Composer & Dependency Hygiene
+
+- Pin versions in `composer.json` to caret ranges (`^11.0` for Laravel itself, `^1.2` for stable libraries). Avoid `*` and `dev-` requirements in production.
+- Lock file (`composer.lock`) committed for applications. Library packages typically omit the lock.
+- Vulnerability scanning: `composer audit` (PHP 8.2+, Composer 2.4+) in CI against the FriendsOfPHP/security-advisories database. Block merge on advisories.
+- License compliance: `composer-license-checker` with an allowlist. Block GPL contamination.
+
+## References
+
+- PHP 8.3 release notes: https://www.php.net/releases/8.3/en.php (accessed 2026-05-27, official-docs)
+- Laravel 11 upgrade guide: https://laravel.com/docs/11.x/upgrade (accessed 2026-05-27, official-docs)
+- Laravel docs: https://laravel.com/docs/11.x (accessed 2026-05-27, official-docs)
+- Pest: https://pestphp.com/docs/installation (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to Laravel API endpoints.
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `php artisan test --coverage`.
+- `rules/hatch3r-secrets-management.md` — `.env` handling and secret rotation patterns.

package/dist/content/rules/hatch3r-progressive-delivery.md

@@ -2,13 +2,17 @@
 id: hatch3r-progressive-delivery
 type: rule
 description: Progressive delivery — canary, blue-green, feature-flag rollout with auto-rollback on SLO burn; staged rollout to prevent CrowdStrike-class incidents
-scope: "**/.github/workflows/**,**/deploy/**,**/k8s/**,**/manifests/**,**/argo/**,**/flagger/**,**/spinnaker/**,**/rollout*"
+scope: conditional
+globs: "**/.github/workflows/**,**/deploy/**,**/k8s/**,**/manifests/**,**/argo/**,**/flagger/**,**/spinnaker/**,**/rollout*"
 tags: [devops]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Progressive Delivery
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ4 (Reliability Quality)
+
 ## Three Rollout Strategies
 
 Choose one per service based on risk profile and resource budget:

package/dist/content/rules/hatch3r-progressive-delivery.mdc

@@ -2,9 +2,12 @@
 description: Progressive delivery — canary, blue-green, feature-flag rollout with auto-rollback on SLO burn; staged rollout to prevent CrowdStrike-class incidents
 globs: ["**/.github/workflows/**", "**/deploy/**", "**/k8s/**", "**/manifests/**", "**/argo/**", "**/flagger/**", "**/spinnaker/**", "**/rollout*"]
 alwaysApply: false
+precedence: high
 ---
 # Progressive Delivery
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ4 (Reliability Quality)
+
 ## Three Rollout Strategies
 
 Choose one per service based on risk profile and resource budget: