hatch3r 1.8.0 → 2.0.0

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

@@ -2,6 +2,7 @@
 description: Distributed tracing, OpenTelemetry conventions, and AI agent instrumentation for the project
 globs: ["**/*trac*", "**/*span*", "**/*telemetry*", "**/*otel*", "**/*agent*", "**/observability/**", "**/routes/**", "**/handlers/**", "**/services/**", "**/api/**", "**/middleware/**", "**/controllers/**", "**/lib/**"]
 alwaysApply: false
+precedence: high
 ---
 # Observability -- Distributed Tracing & OpenTelemetry
 
@@ -29,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
 
@@ -79,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');
@@ -128,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;
@@ -158,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.
@@ -167,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/{rules → dist/content/rules}/hatch3r-operability.md

@@ -2,8 +2,10 @@
 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
 cache_friendly: true
 ---

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

@@ -2,6 +2,7 @@
 description: Operability patterns in user code — liveness / readiness / startup probes, graceful shutdown, feature flags, runbook URL annotations, health endpoints
 globs: ["**/services/**", "**/handlers/**", "**/health*", "**/probes/**", "**/k8s/**", "**/manifests/**", "**/charts/**", "**/feature*", "**/flags/**"]
 alwaysApply: false
+precedence: high
 ---
 # Operability
 

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

@@ -2,8 +2,10 @@
 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/**"
-tags: [security, implementation]
+scope: conditional
+globs: "**/auth/**,**/passkey*,**/webauthn*,**/fido*,**/credentials/**,**/api/**,**/handlers/**"
+tags: [implementation, floor:security]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

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

@@ -2,6 +2,7 @@
 description: Server-side WebAuthn / passkey ceremony — registration, authentication, attestation, counter, RP-ID, recovery, FIDO CXP/CXF awareness
 globs: ["**/auth/**", "**/passkey*", "**/webauthn*", "**/fido*", "**/credentials/**", "**/api/**", "**/handlers/**"]
 alwaysApply: false
+precedence: high
 ---
 # Passkey Server — WebAuthn Ceremony
 

package/{rules → 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               |
@@ -111,5 +113,5 @@ Targets align with Google's "Good" thresholds (measured at p75 from real user da
 | Memory / CPU       | Chrome DevTools, profiler          | Infrastructure metrics (Prometheus) |
 | Visual regression  | Playwright screenshot diffing      | RUM CLS tracking                 |
 
-- Automated regression detection: compare each PR's metrics against the default branch baseline (`board.defaultBranch` from `.agents/hatch.json`; fallback: `"main"`). Flag regressions > 5% in any budget metric.
+- Automated regression detection: compare each PR's metrics against the default branch baseline (`board.defaultBranch` from `.hatch3r/hatch.json`; fallback: `"main"`). Flag regressions > 5% in any budget metric.
 - Review performance budgets quarterly and tighten thresholds as the application matures.

package/{rules → 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               |
@@ -106,5 +108,5 @@ Targets align with Google's "Good" thresholds (measured at p75 from real user da
 | Memory / CPU       | Chrome DevTools, profiler          | Infrastructure metrics (Prometheus) |
 | Visual regression  | Playwright screenshot diffing      | RUM CLS tracking                 |
 
-- Automated regression detection: compare each PR's metrics against the default branch baseline (`board.defaultBranch` from `.agents/hatch.json`; fallback: `"main"`). Flag regressions > 5% in any budget metric.
+- Automated regression detection: compare each PR's metrics against the default branch baseline (`board.defaultBranch` from `.hatch3r/hatch.json`; fallback: `"main"`). Flag regressions > 5% in any budget metric.
 - Review performance budgets quarterly and tighten thresholds as the application matures.

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/{rules → 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/{rules → 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:

package/dist/content/rules/hatch3r-proof-model.md

@@ -0,0 +1,131 @@
+---
+id: hatch3r-proof-model
+type: rule
+description: Mandatory citation per factual claim + pre-execution verification gates + proof_trace block schema. Hallucination prevention via verifiable proof, not citation alone.
+tags: [proof, verification, citation, floor:content-quality]
+precedence: high
+scope: always
+---
+# hatch3r Proof Model
+
+**Pillars:** P2 (Scientific Quality), P5 (Governance Self-Quality)
+
+This rule operationalises Decision #19 (CONSTITUTION §6): hallucination prevention via verifiable proof, not citation alone. It defines WHEN proof is required, WHAT schema each proof emits, and WHICH gates a hatch3r-driven agent must pass before issuing a factual assertion.
+
+## When Proof Trace Is Required
+
+Emit a `proof_trace:` block under any state-dependent claim:
+- File existence or absence
+- File content matching a pattern (specific bytes, frontmatter field, exported symbol)
+- grep match presence/count (zero matches is itself a state-dependent claim)
+- Type-check pass/fail (`npx tsc --noEmit` exit code)
+- Test exit code + output (`npm test` per-suite pass/fail counts)
+- Command exit code + output (any shell invocation whose result the agent is about to cite)
+- Web fetch success + content matching (URL resolves AND target string present)
+
+State-independent claims (definitional, axiomatic, design-rationale) do NOT require proof_trace — citing the file:line where the definition lives is sufficient.
+
+## Proof Trace Schema
+
+```yaml
+proof_trace:
+  claim: <one-sentence assertion>
+  command: <bash invocation OR Read tool call OR grep pattern>
+  expected: <pattern OR quoted output>
+  actual: <verbatim ≤200 chars from command output>
+  verdict: matched | mismatched
+  accessed: YYYY-MM-DD
+```
+
+Field rules:
+- `claim` — one sentence; what the proof verifies. Never a multi-clause assertion.
+- `command` — runnable verbatim by a reviewer. No paraphrase.
+- `expected` — either a regex/pattern OR the verbatim string the command should emit.
+- `actual` — verbatim slice of the command output, truncated to 200 characters with `…` suffix if longer.
+- `verdict` — `matched` when actual satisfies expected; `mismatched` otherwise. A `mismatched` verdict still belongs in the proof trace — it documents that verification was attempted.
+- `accessed` — ISO-8601 date when the command was run.
+
+## Pre-Execution Verification Gates
+
+Before issuing any agent-generated assertion that affects a downstream decision, the agent passes these gates in order:
+
+1. **State-dependent claim?** If yes, prepare a `proof_trace` block — do not emit the claim without it.
+2. **External dependency claim** (library version, API behavior, platform feature)? Verify against current documentation per `agents/shared/quality-charter.md` §15 Currency Verification (≤180 days). Cite URL + access date + trust tier per `agents/shared/rigor-contract.md` §Web Research Mandate.
+3. **Cross-file claim** (file X imports file Y, function A calls function B)? Run grep + cite file:line. Do not infer from filename or directory.
+4. **Behavioral claim** (function does X under condition Y)? Either point to a test that exercises Y → X, or write one before asserting.
+5. **Negative claim** (X does NOT exist, Y does NOT happen)? Run the search command and emit the zero-match output in `actual:`. Absence is harder to prove than presence — make the search command explicit.
+
+A claim that fails its gate is either dropped, or downgraded to confidence `low` per `agents/shared/quality-charter.md` §1 with the gap explicitly named.
+
+## Citation Alone Is Insufficient
+
+Per CONSTITUTION §6 Decision #19: "Citation alone insufficient — verification commands close the loop." Documents become stale; commands return current state. A citation without a verification command is a Medium-minimum finding under D24 self-audit.
+
+Concrete failure modes citation-alone leaves open:
+- File path moved or renamed since the cited revision
+- Section heading rewritten such that the citation refers to absent content
+- Behavior changed in a way the prose has not yet caught up to
+- Reviewer reading the citation does not have the cited file open
+
+A proof_trace defeats all four — the command runs against current state at review time.
+
+## Acceptable Failure Modes
+
+- **Verification impossible at write time** (e.g., production database state from local dev) — explicitly state the verification gap + lower confidence to medium per quality-charter §1.
+- **Verification cost prohibitive** (e.g., 30-minute integration suite for a docs typo) — log a `verification_skipped: <reason>` field; flag for downstream check. The skip must be documented, not silent.
+- **Source 404 / withdrawn** — re-research before relying; do not cite a dead URL per rigor-contract.md §Web Research Mandate. Re-running the fetch with a `accessed:` date earlier than the 404 does not rescue the citation.
+- **Verification command itself unreliable** (flaky test, intermittent network) — note the unreliability + run the command N≥3 times + cite the majority outcome.
+
+## Examples
+
+State-dependent claim WITH proof_trace:
+
+```yaml
+proof_trace:
+  claim: rigor-contract.md defines a Proof Trace Contract section
+  command: grep -n "Proof Trace Contract" agents/shared/rigor-contract.md
+  expected: line-numbered match referencing "Proof Trace Contract"
+  actual: "84:## Proof Trace Contract (Decision 9 — added 2026-05-26)"
+  verdict: matched
+  accessed: 2026-05-26
+```
+
+Negative claim WITH proof_trace:
+
+```yaml
+proof_trace:
+  claim: no occurrences of "TODO" remain in src/content/contentRoot.ts
+  command: grep -c "TODO" src/content/contentRoot.ts
+  expected: "0"
+  actual: "0"
+  verdict: matched
+  accessed: 2026-05-26
+```
+
+External dependency claim WITH proof_trace:
+
+```yaml
+proof_trace:
+  claim: Commander.js 12.x supports async action handlers
+  command: WebFetch https://github.com/tj/commander.js/blob/master/Readme.md#action-handler
+  expected: section "Action handler" describes async support
+  actual: "Action handler functions can also be async. Use parseAsync()…"
+  verdict: matched
+  accessed: 2026-05-26
+```
+
+## Enforcement
+
+The audit prompt's Behavioral Charter directive 20 (added 2.0.0) and `agents/shared/rigor-contract.md` §Proof Trace Contract (added 2026-05-26) operationalise this rule at audit time. Findings missing proof_trace on state-dependent claims are dropped at SA output time per the charter's directive 20 + rigor-contract §Schema Enforcement.
+
+Reviewer-class artifacts (`agents/hatch3r-reviewer.md`, future Reviewer Pass 1.5 per rigor-contract §Proof Trace Contract) read proof_trace blocks to verify implementation against documented runtime state. Implementer-class artifacts (`agents/hatch3r-implementer.md`) emit proof_trace blocks before declaring task completion.
+
+## Pillar Service
+- P2 — every factual claim becomes verifiable; placeholder findings are detectable and retryable.
+- P5 — governance system applies proof to itself; the rule that mandates proof is itself bound by proof at audit time.
+
+## Cross-References
+- Decision #19 — proof-trace + mandatory citation as 2.0.0 hallucination-prevention floor
+- `agents/shared/rigor-contract.md` §Proof Trace Contract — schema canonical location + Shallow Finding Detector linkage
+- The audit prompt's Behavioral Charter directive 20 — audit-time enforcement at SA output time
+- `agents/shared/quality-charter.md` §15 Currency Verification — external-dependency claim freshness window (≤180 days)